Ports, types and data flow
This page explains how data moves from one node to the next in a Workflow: what a port is, how the engine fills a node's inputs, which port types can be connected, how a condition prunes a branch, and how {{NAME}} placeholders are resolved. Every example below was run on the real engine with synthetic data.
You wire nodes in the Workflows builder. To find the ports of a particular node, open it in the builder (Inspector, Ports section) or in the Node Catalog.
Anatomy of a node
A node has three kinds of things:
| Part | What it is | Where you set it |
|---|---|---|
| Config | Settings that tell the node what to do (an operation, a URL, a threshold). Fixed for every run. | Inspector, Node Settings |
| Input ports | Named values the node receives from upstream nodes during a run. Each port has a type. | Draw an edge into the port |
| Output ports | Named values the node produces. Each port has a type. | Draw an edge out of the port |
On the canvas, input port names are listed on the left of the node card and output port names on the right. Each port is a coloured dot (the colour reflects the port type). Hover a dot to see <port name> · <type>.
Most nodes have two outputs in common: result (the payload, usually type json) and success (a boolean). A few examples from the catalog:
| Node id | Input ports (type) | Output ports (type) |
|---|---|---|
input | input (any) | output (any) |
condition | field (any), context (any) | true (json), false (json), condition_met (boolean), success (boolean) |
transform | input (json) | result (json), errors (json), error_count (number), success (boolean) |
hl7-to-fhir | hl7_message (text) | result (json), success (boolean) |
fhir-crud | resource (json), resource_json (text), resource_id (text), bundle (fhir-bundle) | result (json), success (boolean) |
output | input (any) | result (json), success (boolean) |
An edge connects a port to a port
An edge is stored as four values: source node, source port, target node, target port. It does not name a field inside the data. When the workflow runs, the engine copies whatever the source port holds into the target node's inputs under the target port's name. If you need one field from inside that value, the receiving node has to pick it out (see Reading upstream data).
If you draw an edge without choosing ports, the builder stores the defaults output (source) and input (target).
How the engine fills a node's inputs
Before each node runs, the engine builds that node's inputs by looking at every edge that points at it. Three rules apply, in this order of specificity:
- Generic pair. An edge from port
outputto portinputmerges the source node's whole output into the target's inputs, key by key. If the source wrapped its payload inresult, the engine unwraps it first so the target sees the inner keys directly.successis passed along as well. - Named pair. Any other edge copies the value of the source port to the input port with the target's name:
inputs[target_port] = outputs[source_port]. - Fallback into
result. If the named source port is not at the top level of the source's output, the engine looks for it inside the source'sresultobject. (This is why an edge fromfhir_bundleworks for a node that returns its bundle underresult.)
Run inputs (for example the values you give to Run with inputs) are also copied into every node's inputs before upstream outputs are added.
Fan-in: several edges into one port
If several edges end at the same input port through a named pair (rule 2 or 3), the values are not overwritten. They are merged:
- If both values are FHIR result objects with a
bundle, thebundle.entryarrays are concatenated and numerictotalandcountare added. - Otherwise the values are collected into a list, in the order the edges were evaluated. Two input nodes with
{x: 1}and{y: 2}wired fromoutputto a port namedfoogavefoo = [{x: 1}, {y: 2}].
Edges that use the generic pair (output to input) do not collect. They merge key by key into the inputs, so when two sources carry the same key the edge evaluated last wins. The same two input nodes wired output to input gave {x: 1, y: 2, output: {y: 2}}.
Port types
Every port has a type, shown as a small chip in the palette and as a tooltip on the port. The types that appear in the real catalog (198 nodes) are json, text, boolean, number, any, fhir-bundle, binary and string. The compatibility rules also define fhir-resource, hl7-message, x12-message, dicom, ndjson, csv, xml and html.
Which types connect
The rule is a small hierarchy. A subtype connects to its parent types, and the check is symmetric (you can connect either way round). any connects to everything. Any other pair connects only if both ports have exactly the same type.
| An output of type | can connect to an input of type |
|---|---|
any | every type |
json | json, fhir-bundle, fhir-resource, hl7-message, ndjson, any |
text | text, hl7-message, x12-message, ndjson, csv, xml, html, any |
number | number, any |
boolean | boolean, any |
binary | binary, dicom, any |
fhir-bundle | fhir-bundle, json, any |
fhir-resource | fhir-resource, json, any |
hl7-message | hl7-message, json, text, any |
x12-message | x12-message, text, any |
dicom | dicom, binary, any |
ndjson | ndjson, json, text, any |
csv, xml, html | the same type, text, any |
Things that surprise people:
fhir-bundleandfhir-resourcedo not connect to each other.textandjsondo not connect to each other. There is no automatic conversion. Put a node between them that produces the type you need.booleanandnumberports only connect to the same type or toany.- A type that is not in the hierarchy (the catalog has a few ports typed
string) connects only to the same type or toany.
Where the rule is enforced
- While you draw an edge. The builder blocks a drop between two ports whose types are known and incompatible. If either port is unknown to the builder (for example a port name that does not exist), the connection is allowed.
- Validate (partly). The server's validation does compute
port type mismatch: <source>.<port> (<type>) → <target>.<port> (<type>) — these port types cannot connectand suggests target inputs that would accept the type, but for an existing workflow it is a warning, and the toolbar Validate button shows only errors (Valid or Invalid and a tooltip with the error messages). A type mismatch therefore does not make the button turn red. Validate does not flag a port name that does not exist. - At run time the engine does not check types. It copies values by port name. A type mismatch that slipped through (for example in a workflow written as YAML) is not stopped by the executor.
Branch pruning and skipped nodes
A condition node picks one branch. It evaluates its field against compare_value and emits an internal list of active ports: ["true"] or ["false"]. The executor then walks every other node and applies one rule:
A node is skipped when all of its incoming edges are inactive. An edge is inactive when its source node was itself skipped, or when its source port is not in that source's active-ports list. A node with no incoming edges is never skipped.
A skipped node does not run and has status skipped (shown in the footer of the node card as Skipped). Skipping spreads: a node whose only upstream node was skipped is skipped too. A node that has at least one active incoming edge runs, so a join node fed by both branches still runs when one branch is pruned.
The ports of a condition node carry only a small payload by default: condition_met and a result block with branch, compare_value and field_value. To pass the original record down the chosen branch, set pass_through in the condition's config as {target_name: input_key}: the value of the input named input_key is copied onto the branch under target_name. In the example below it is {record: context}, which copies whatever arrived on the context port.
Worked example: lab-result triage
This workflow has an input node (defaults: patient_id test-patient-a, test potassium, value 4.2), a jsonpath node (Pick the value, path: value), a condition node (field: value, condition_type: greater_than, compare_value: 5.5, pass_through: {record: context}), two transform nodes in map mode (urgent and routine) that build patient, test and value from input.record.*, and one output node fed by both. Every edge uses a port the node declares. It was run twice on the engine.
| Run | condition active ports | urgent | routine | output | What the output node received on its input port |
|---|---|---|---|---|---|
value = 4.2 | ["false"] | skipped | completed | completed | {patient: "test-patient-a", test: "potassium", value: 4.2} |
value = 6.1 | ["true"] | completed | skipped | completed | {patient: "test-patient-a", test: "potassium", value: 6.1} |
The edges, by port:
| Edge (source port to target port) | What it carries |
|---|---|
input node output to jsonpath data | The record {patient_id, test, value} |
jsonpath value to condition field | The number alone (4.2 or 6.1) |
input node output to condition context | The whole record again, so pass_through can carry it |
condition false (or true) to the transform's input | {condition_met, result: {branch, compare_value, field_value}, record: {patient_id, test, value}} |
transform result to output input | {patient, test, value} |
The urgent node has no inputs and no outputs in the 4.2 run: it never executed. A node fed only by urgent (an extra transform wired to urgent's result) is skipped as well, and an input node with no incoming edges still runs.
field on a condition names the key it tests, but nothing resolves a path inside the value that arrives on the field port. Wiring the record straight into field fails: the engine hands the node the whole object and it stops with values must be numeric for > comparison. Put a node that extracts the value in front of the gate (here jsonpath) and carry the record separately through context. A numeric string such as "6.1" also fails the numeric comparison. The engine does accept an edge to a port the node does not declare (a generic output to input edge spreads the record into top-level keys), but the canvas only offers declared ports, so you cannot draw it by hand.
Numeric operators need real numbers. A numeric string such as "6.1" (for example from a text field) fails with values must be numeric for > comparison. The node does not convert strings to numbers.
Reading upstream data: the input.<field> convention
A transform node in map mode receives its data under the name of the port it was wired to. In the example, the edge ends at routine's port input, so the node's inputs are { input: { ... } } and the mappings must start with input.:
config:
transformation_type: map
mappings:
patient: input.patient_id
test: input.test
value: input.value
Without the input. prefix the mapped fields come out as null. The same dotted path works for nested data, for example input.data.first_name.
{{NAME}} placeholders
Any string in a node's config can contain {{NAME}}. The engine replaces it just before the node runs. Placeholders are only resolved in config, not in edges or in data that flows between nodes. The engine tries these sources in this order, and the first one that knows the name wins:
| Order | Syntax | Resolves to |
|---|---|---|
| 1 | {{run.id}}, {{run.pipeline_id}}, {{run.pipeline_version}}, {{run.node_id}}, {{run.started_at}} | Facts about the current run (also {{run.run_id}}, same as run.id). |
| 2 | {{NAME}} for a credential | The per-tenant credential store, when the platform has one configured for your organization. |
| 3 | {{variable_name}} | A non-secret variable from the workflow's Resources drawer (Variables tab). |
| 3 | {{connectors.<name>.<field>}} | A field of a connector defined in the Resources drawer (Connectors tab). <name> is the connector's name or id. |
| 3 | {{storage.<name>.<field>}} | A field of a storage entry (for example bucket or prefix) from the Storage tab. |
| 4 | {{key}} | A top-level value in the node's own runtime inputs (from an upstream node or the run inputs). Only strings, numbers and booleans are substituted; objects, lists and null are not. |
A placeholder that nothing resolves is left in place as literal text, for example {{MISSING}}. The run does not stop; the literal text is sent to whatever uses the value.
A variable marked secret is not resolved by {{NAME}}. In the Resources drawer, a variable with the secret (eye) toggle on is refused by the placeholder resolver. A header written as Bearer {{FHIR_TOKEN}} with a secret FHIR_TOKEN reaches the target system as the literal text Bearer {{FHIR_TOKEN}}. Secrets are resolved only through the per-tenant credential store (order 2). Use a non-secret variable only for values that are safe to expose in the workflow definition (for example a base URL).
The Variables tab also lists five "SYSTEM VARIABLES" ({{pipeline_id}}, {{execution_id}}, {{user_id}}, {{organization_id}}, {{current_timestamp}}). The engine code that resolves placeholders does not read those names. Use {{run.pipeline_id}}, {{run.id}} and {{run.started_at}} instead.
Worked example: HL7 message to FHIR
A synthetic ADT^A01 message passed through hl7-to-fhir produced a result object (type json) with these keys: fhir_bundle, mapping_details, resource_count, resources, source_type, unmapped_segments and warnings. The node's only output ports are result and success.
fhir_bundle.typeistransaction. Every entry hasrequest.methodPOSTand aurn:uuid:full URL.- The bundle contained a Patient (identifier from PID-3, name, birth date, gender) and an Encounter (class
IMP, statusin-progress, location from PV1-3, subject reference). NK1 was reported inunmapped_segments. - Wired into the
bundleport of anfhir-crudnode withoperation: transaction, the bundle was sent once to the basefhir_urlasPOST /r4withContent-Type: application/fhir+jsonand theAuthorization: Bearer <auth_token>header. - In a YAML workflow an edge with
source_port: fhir_bundleworked, because of the fallback intoresult. The builder canvas offers only theresultport for this node.
The types line up: result is json and bundle is fhir-bundle, and json connects to fhir-bundle.
When something does not flow
| Symptom | Cause | Fix |
|---|---|---|
| The run finishes as completed, but a node shows Skipped and you expected it to run. | Its incoming edge is on a condition port that was not active, or its upstream node was skipped. A mistyped port name on an edge from a condition node counts as inactive: for example an edge from a port maybe raises no error, the run completes, and the target is skipped. | Open the edge in the Inspector and check the source port name. A condition node has true and false. |
| A node runs but a value you expected is missing. | The edge's source port name does not exist on the source node, so nothing is copied. The engine does not report an unknown port. | Check the port names on the source node (hover a port dot), then run Debug step-by-step and open the node in the STEP DEBUG tab to see what it received. |
values must be numeric for > comparison | A numeric operator was given a string. | Provide a real number (a JSON number, not "6.1"). |
Mapped fields in a transform are null. | The mapping does not start with the port name. | Use input.<field> when the edge ends at port input. |
node a (input) failed: required field missing: patient_id | The input node has required_fields and the run did not supply one. | Provide it in Run with inputs, or add a default. |
compilation failed: node release hl7-to-fihr@ is unavailable | The node type id is wrong. | Use the exact id from the Node Catalog. |
compilation failed: connection references non-existent target node: ghost | An edge points at a node id that is not in the workflow. | Remove the edge or fix the id. |
compilation failed: failed to determine execution order: circular dependency detected: no nodes with zero in-degree | The graph has a cycle. | Remove the edge that closes the loop. |
node w (fhir-crud) validation failed: fhir_url is required | A required config field is empty. | Fill it in the Inspector. |
A header or URL shows the text {{NAME}} at the receiving system. | The name did not resolve, or the variable is secret. | Create it as a non-secret variable, or use the per-tenant credential store for secrets. |
Limits and notes
- Values move by port name. There is no field-level wiring, no automatic conversion between types, and no run-time type check.
- Internally the engine frees a node's working copy of its output once every downstream node has read it. This does not remove anything from the run result: the per-node results still list each node's
inputsandoutputs.
Something unclear? Send documentation feedback by email.