Skip to main content

Build any workflow

A workflow (also called a pipeline) is a graph of nodes. Data enters at one end, each node does one job and passes a result to the next, and the last node produces the outcome: a record, a message, a report. This guide gives you a method that works for any workflow, then the control-flow patterns you combine to build it. Every pattern below was run on the real engine with synthetic data, and the results shown are what it returned.

How this guide fits with the others

Is a workflow the right tool?​

You needUse
A fixed sequence of steps with branches, the same every time, that you can test and repeatA workflow (this guide)
One assistant with tools that decides for itself what to callAn agent
Several model steps with roles, routing, review loops and an audit trail of every promptAn agent graph

A workflow can call agents as a step (the agent-executor node), so you can mix them: fixed plumbing around a model that does the reasoning.

The method​

The loop you repeat: define the job, wire the nodes, validate, test, save a version, deploy and monitor. A failed test returns to wiring.

1. Define the job​

Before you open the editor, write down five things. Most workflow bugs come from skipping one of them.

QuestionExample (lab-result triage)
How does it start?Someone runs it with a lab result.
What data comes in, with which fields and types?patient_id (text), test (text), value (a number).
What decisions does it make?Is value above 5.5?
What leaves, and where does it go?A high-value record or a routine record; this exercise sends no notification.
What happens when a step fails, and who sees it?The run fails and shows in Tiet · Studio → Workflows → Monitor.

2. Choose how it starts​

The first node decides how the workflow starts. Pick the one that matches the job.

StartNodeWhat it needsUse it for
Run by hand or APIinputdefaults (or data) and required_fieldsAnything you start yourself, with values from Run with inputs or the API
On a timerschedulerschedule_type (interval, once or daily), interval_seconds, execute_at, time_of_dayRecurring jobs. For a cron expression, choose Schedule in the Run menu (it offers cron presets and a custom expression and adds the trigger node), or use Tiet · Studio → Workflows → Monitor → Schedules (see Run options)
An HTTP callapi-webhookport (9090), listen_path, auth_mode (none, header_secret, hmac_sha256), webhook_secretAnother system notifies you
A FHIR subscriptionfhir-webhookfilter_resource_type, filter_eventReact to FHIR resource changes
An HL7 messagehl7-listenerlisten_port (2575), filters on message type, event, sending application and facilityHospital interfaces; see the ADT recipe
Generic eventtriggertype (manual, webhook, schedule, condition, event)When none of the above fits

The input node's output port carries the whole record, so the next node can read every field.

3. Build it in the editor​

  1. Open Tiet · Studio → Workflows and choose New Workflow. A blank editor opens in a tab.
  2. In the left panel choose Palette. Search by name, id, category, description or port type (the box reads "Search name, type, port, standard…"), or expand a category. Drag the node onto the canvas.
  3. Select a node. The Inspector on the right shows its settings (Node Settings) and its Ports. Fill in the required ones (marked with a red asterisk). Settings are split into tabs such as Basic and Advanced. How a setting is entered depends on its type: text and number boxes; drop-downs for fixed choices; on/off switches; a JSON text box for json and any settings (it turns red and keeps your text as plain text until it parses); a list with Add item for arrays such as required_fields; and, for transform Mappings, rows with Target and Source boxes (plus Transform and Default where the node offers them) added with Add field.
  4. Draw an edge from an output port (right side of a node) to an input port (left side) of the next node.
  5. Put values you reuse (a base URL, a threshold) in Resources (toolbar), on the Variables tab, and reference them as {{name}}. The same drawer has Connectors, Storage and Test Data tabs.

The lab-result triage workflow in the editor: an input node, a jsonpath node that picks the value, a condition node with true and false ports, two transform nodes and an output node.

The toolbar, left to right: zoom and layout controls, Resources, Validate, Save, the Live/Test toggle, the Run in environment selector, Run (with an arrow menu) and Deploy. The right panel's tabs are Inspector, Assistant, Diff, Docs and API, and the Routing switch (Smart or Curved) and AI Assistant sit at the top right of the canvas.

Select a node to see exactly what it accepts and produces:

4. Wire the data correctly​

Five rules cover most problems. The ports page explains each one with examples.

  1. An edge connects a port to a port, not a field. If you need one field, a node in between has to pick it out (for example jsonpath, whose value port carries the extracted field). In the editor you can only draw edges between the ports a node declares, so check the ports in the Inspector first.
  2. A transform in map mode reads upstream data under the name of the port it was wired to, so its mappings start with input. (for example input.patient_id). Without the prefix the fields come out empty.
  3. A condition node tests the value on its field port and passes on only its comparison result. The field port must carry the number itself, not a record that contains it (a record fails with values must be numeric for > comparison). To carry the record down the chosen branch, wire it to the context port and name it in pass_through.
  4. Numeric comparisons need numbers. The text "6.1" is not a number and fails with values must be numeric for > comparison.
  5. A secret variable is not substituted by {{name}}. It reaches the target as the literal text. Keep secrets in the credential store, and use variables only for values that are safe to see in the workflow.
A mistyped port name raises no error

If an edge uses a port that does not exist on the source node, the run still finishes as completed and the target node is quietly skipped. After every run, scan the nodes for skipped and check that each one is expected.

5. Test, then test again​

ToolWhat it tells you
ValidateChecks the workflow before you run it. It reports errors only. It does not flag a wrong port name, and port-type mismatches do not turn it red.
Run with inputsRuns with values you type as JSON. Numbers must be JSON numbers.
Run in selectorPicks the environment the run executes in. An environment that allows drafts runs what the editor holds; any other runs only what was deployed to it, and the server refuses the rest.
Live/Test toggleThe button reads Live (real connectors) or Test (fixtures). In Test mode fixtures and input overrides are applied so nodes use pre-defined data instead of waiting for real events. Dry run in the Run menu is labelled "Run in test mode" but saves and runs exactly like Run; it follows the toggle, so switch to Test first. Do not assume either avoids a real side effect such as a phone call.
Debug step-by-stepPauses at each node. Right-click a node and choose Inspect Data, or select it and open the Diff tab, to see what went in and came out.
EXECUTION LOG, STEP DEBUG, TRACEThe bottom panel: per-node status, data, and the span tree of the run.

Run on mesh is always listed but disabled ("Set a node's Runs-on placement to enable") until at least one node has a Runs on (placement) value; see Run on mesh.

Test the edges of your input, not only the middle: the smallest value, a missing field, a value exactly on a threshold.

6. Save a version and release it​

Save (Ctrl/Cmd+S) opens Save New Version, which suggests the next version number; every save is a new version. Save once before the first run: Run, Run with inputs, Dry run and Deploy need a workflow that has been saved once, and afterwards they save your current changes first (without a version prompt). The Deploy menu lists one entry, Deploy vN to <environment>, for every other environment, plus Export as JSON and Export as YAML; its Activate (enable schedule, enable trigger), push and deployment-history entries are shown disabled. Be aware of what Deploy does and does not do, and read Environments and promotion before relying on it for a controlled release.

After release, watch runs in Tiet · Studio → Workflows → Monitor.

Control-flow patterns​

Branch on a condition​

The condition node tests the value that arrives on its field port and activates either its true port or its false port. Only the nodes wired to the active port run; the others are skipped.

One workflow, two branches: a lab result is routed to a high-value record or a routine record, and the branch not taken is skipped.

Download the complete JSON definition or YAML definition, plus sample inputs. The full downloads use the builder export format (definition.nodes and definition.connections).

The same branching pattern in abbreviated YAML (edges is the connection alias):

nodes:
- id: result
type: input
config:
required_fields: [patient_id, test, value]
defaults: {patient_id: "test-patient-a", test: "potassium", value: 4.2}
- id: pick-value
type: jsonpath
config:
path: value
- id: above-threshold
type: condition
config:
field: value
condition_type: greater_than
compare_value: 5.5
pass_through: {record: context}
- id: high-value
type: transform
config:
transformation_type: map
mappings: {patient: input.record.patient_id, test: input.record.test, value: input.record.value}
- id: routine
type: transform
config:
transformation_type: map
mappings: {patient: input.record.patient_id, test: input.record.test, value: input.record.value}
- id: out
type: output
edges:
- {source_node: result, source_port: output, target_node: pick-value, target_port: data}
- {source_node: pick-value, source_port: value, target_node: above-threshold, target_port: field}
- {source_node: result, source_port: output, target_node: above-threshold, target_port: context}
- {source_node: above-threshold, source_port: "true", target_node: high-value, target_port: input}
- {source_node: above-threshold, source_port: "false", target_node: routine, target_port: input}
- {source_node: high-value, source_port: result, target_node: out, target_port: input}
- {source_node: routine, source_port: result, target_node: out, target_port: input}

Every edge uses a port the node declares, so you can draw the whole workflow in the editor. Two edges leave the input node: one into pick-value (so the condition gets the bare number on field) and one into the condition's context port (so the whole record can be carried down the chosen branch). Wiring the input node's output straight into field does not work: the port carries the whole record, and the comparison fails with values must be numeric for > comparison. The condition node's field setting (value) names the number being tested; the value that arrives on the field port is the one it compares.

Result of the two runs:

valueActive porthigh-valueroutineout receives
4.2falseskippedran{patient: "test-patient-a", test: "potassium", value: 4.2}
6.1trueranskipped{patient: "test-patient-a", test: "potassium", value: 6.1}

Both branches feed one out node. The run completes with one branch skipped, so a join after a branch is safe. For more than two outcomes, use the router node (rules, default_route) or chain conditions.

Filter and aggregate a list​

Use filter to keep the records that match, then aggregator to count or summarise them.

nodes:
- id: labs
type: input
config:
defaults:
data:
- {patient_id: "pt-a", test: "potassium", value: 4.1}
- {patient_id: "pt-b", test: "potassium", value: 6.2}
- {patient_id: "pt-c", test: "potassium", value: 5.9}
- {patient_id: "pt-d", test: "potassium", value: 3.8}
- id: critical
type: filter
config:
logic: AND
conditions:
- {field: value, operator: greater_than, value: 5.5}
- id: count
type: aggregator
config: {aggregation_type: count}
edges:
- {source_node: labs, source_port: data, target_node: critical, target_port: data}
- {source_node: critical, source_port: filtered_data, target_node: count, target_port: data}

The filter node returns filtered_data (the matching records) with filtered_count. Run on the four records above it keeps pt-b and pt-c, and the aggregator returns {"count": 2}.

Wire the list, not the wrapper

The aggregator wants an array. Wired from result, it receives the wrapper object and fails with data must be an array. Wire the filtered_data field into its data port.

Filter operators include equals, not_equals, greater_than, less_than, contains, starts_with, regex, in, not_in, exists, is_empty and is_null (and short forms such as gt, ==, >=). aggregation_type can be count, sum, average, min, max, group or distinct.

Combine two sources​

Two nodes with no dependency between them run in the same batch, in parallel. Join them with a merge node:

  - id: combine
type: merge
config: {merge_type: object, sources: [demographics, vitals]}
edges:
- {source_node: demographics, source_port: output, target_node: combine, target_port: demographics}
- {source_node: vitals, source_port: output, target_node: combine, target_port: vitals}

With demographics = {patient_id: "pt-a", name: "Test Patient A"} and vitals = {heart_rate: 72, spo2: 97}, merge returned merged: {heart_rate: 72, name: "Test Patient A", patient_id: "pt-a", spo2: 97}, field_count: 4 and source_count: 2. merge_type is object, array or concat.

Work through a list​

The loop node (loop_type: for_each, while or until) emits a list with an index for each item:

{"count": 2, "results": [{"index": 0, "item": {"patient_id": "pt-a"}}, {"index": 1, "item": {"patient_id": "pt-b"}}]}
The loop does not run a branch once per item

The node produces the indexed list once, and the nodes after it run once. It does not repeat the downstream branch for each item. A workflow graph can never contain a cycle (the engine rejects it at compile time). For per-record work use batch (batch_size, parallelism, continue_on_error) or do the work inside a node that accepts a list.

Handle failure on purpose​

By default a failed node fails the run (fail_fast). You can change that for one node with error_handling, and you can retry transient errors with retry.

What the error_handling strategy does to the rest of the run: fail_fast stops the run; log_and_continue ends the node degraded and the next node runs only if it accepts degraded.

  - id: write
type: fhir-crud
config: {operation: transaction, fhir_url: "{{FHIR_URL}}"}
error_handling: {strategy: log_and_continue} # fail_fast (default), log_and_continue, fallback
retry: {max_retries: 3, initial_delay_ms: 500, backoff_factor: 2, jitter: true}
- id: report
type: output
accept_outcomes: [succeeded, degraded] # needed to run after a degraded node

In the test, write failed at run time because it was handed something that was not a Bundle. What the engine did:

SettingResult
fail_fastwrite failed with transaction input must be a Bundle, got resourceType=<nil>, and the run ended failed.
log_and_continue, next node without accept_outcomeswrite completed with outcome degraded and empty outputs, and the next node failed: node after requires a successful outcome from bad (received degraded).
log_and_continue, next node with accept_outcomes: [succeeded, degraded]The next node ran, and the run finished partial.

Use log_and_continue only where the rest of the workflow can truly proceed without that step's output, and make the later node handle the missing data. A run that ends partial is not a success: monitor for it.

Other control nodes: validator (rules, strict_mode; with strict_mode off a failing record passes through with valid=false), error-handler (strategy: catch, fallback, transform, retry_info) and delay.

Before you rely on a workflow​

  • Every required field has a value, and the exact node ids come from the palette.
  • You ran it with a normal input, an edge-case input and a missing-field input.
  • No node shows skipped unless you expected it.
  • Numbers are numbers, and no secret sits in a variable.
  • Failure handling is deliberate: you know what a degraded or partial run means for the next step.
  • Anything that writes to a clinical system writes proposals or drafts, not final records, unless a person reviews them. See Agents and governance.
  • You tested with synthetic data only.

When it does not work​

SymptomLikely causeFix
A node shows skipped.Its incoming edge is on a condition port that was not active, or a port name on an edge is wrong.Check the source port name on the edge (true or false for a condition).
A mapped field is null.The mapping lacks the port-name prefix.Use input.<field>.
values must be numeric for > comparisonA text value reached a numeric comparison.Supply a number.
data must be an arrayA list node received its wrapper object.Wire the list field (for example filtered_data).
compilation failed: node release xyz@ is unavailableThe node id is not in the catalog.Copy the id from the palette.
compilation failed: ... circular dependency detectedThe graph has a cycle.Remove the edge that loops back.
node ... validation failed: <field> is requiredA required setting is empty.Fill it in the Inspector.
requires a successful outcome from <node> (received degraded)The node before ended degraded under log_and_continue.Add accept_outcomes to this node, or stop using log_and_continue on the earlier one.
The run is partial.At least one node ended degraded.Open the run in Monitor and check which one.

More errors, with the data-flow ones in detail, are in Ports, types and data flow.

Where next​

Something unclear? Send documentation feedback by email.