Skip to main content

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:

PartWhat it isWhere you set it
ConfigSettings that tell the node what to do (an operation, a URL, a threshold). Fixed for every run.Inspector, Node Settings
Input portsNamed values the node receives from upstream nodes during a run. Each port has a type.Draw an edge into the port
Output portsNamed 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 idInput ports (type)Output ports (type)
inputinput (any)output (any)
conditionfield (any), context (any)true (json), false (json), condition_met (boolean), success (boolean)
transforminput (json)result (json), errors (json), error_count (number), success (boolean)
hl7-to-fhirhl7_message (text)result (json), success (boolean)
fhir-crudresource (json), resource_json (text), resource_id (text), bundle (fhir-bundle)result (json), success (boolean)
outputinput (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).

Three nodes: a condition node&#39;s true port feeds a transform node&#39;s input port, whose result port feeds an output node&#39;s input port. Each box shows the data the port carried.

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:

  1. Generic pair. An edge from port output to port input merges the source node's whole output into the target's inputs, key by key. If the source wrapped its payload in result, the engine unwraps it first so the target sees the inner keys directly. success is passed along as well.
  2. 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].
  3. 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's result object. (This is why an edge from fhir_bundle works for a node that returns its bundle under result.)

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, the bundle.entry arrays are concatenated and numeric total and count are 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 from output to a port named foo gave foo = [{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.

A hierarchy: fhir-bundle and fhir-resource connect to json; hl7-message and ndjson connect to json and text; x12-message, csv, xml and html connect to text; dicom connects to binary.

An output of typecan connect to an input of type
anyevery type
jsonjson, fhir-bundle, fhir-resource, hl7-message, ndjson, any
texttext, hl7-message, x12-message, ndjson, csv, xml, html, any
numbernumber, any
booleanboolean, any
binarybinary, dicom, any
fhir-bundlefhir-bundle, json, any
fhir-resourcefhir-resource, json, any
hl7-messagehl7-message, json, text, any
x12-messagex12-message, text, any
dicomdicom, binary, any
ndjsonndjson, json, text, any
csv, xml, htmlthe same type, text, any

Things that surprise people:

  • fhir-bundle and fhir-resource do not connect to each other.
  • text and json do not connect to each other. There is no automatic conversion. Put a node between them that produces the type you need.
  • boolean and number ports only connect to the same type or to any.
  • A type that is not in the hierarchy (the catalog has a few ports typed string) connects only to the same type or to any.

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 connect and 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.

A condition node with active ports false. The node wired to the true port is skipped, the node wired to the false port runs, and the output node, wired to both, runs.

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.

Runcondition active portsurgentroutineoutputWhat the output node received on its input port
value = 4.2["false"]skippedcompletedcompleted{patient: "test-patient-a", test: "potassium", value: 4.2}
value = 6.1["true"]completedskippedcompleted{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 dataThe record {patient_id, test, value}
jsonpath value to condition fieldThe number alone (4.2 or 6.1)
input node output to condition contextThe 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.

A gate cannot read a field of a record

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.

note

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:

OrderSyntaxResolves 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 credentialThe 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.

warning

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.type is transaction. Every entry has request.method POST and a urn:uuid: full URL.
  • The bundle contained a Patient (identifier from PID-3, name, birth date, gender) and an Encounter (class IMP, status in-progress, location from PV1-3, subject reference). NK1 was reported in unmapped_segments.
  • Wired into the bundle port of an fhir-crud node with operation: transaction, the bundle was sent once to the base fhir_url as POST /r4 with Content-Type: application/fhir+json and the Authorization: Bearer <auth_token> header.
  • In a YAML workflow an edge with source_port: fhir_bundle worked, because of the fallback into result. The builder canvas offers only the result port 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​

SymptomCauseFix
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 > comparisonA 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_idThe 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 unavailableThe node type id is wrong.Use the exact id from the Node Catalog.
compilation failed: connection references non-existent target node: ghostAn 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-degreeThe graph has a cycle.Remove the edge that closes the loop.
node w (fhir-crud) validation failed: fhir_url is requiredA 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 inputs and outputs.

Something unclear? Send documentation feedback by email.