Building Workflows
Workflows are the core of your automation. They connect individual steps together to move data, make decisions, and interact with external systems.
In the @culvii/kit SDK, you build workflows by creating Step instances and connecting them, then wrapping them in a Workflow.
Create your first workflow
Every workflow needs a trigger-type step as its entry point: a manualTrigger, a cronTrigger, a webhookTrigger, or a connector trigger like gmailTrigger. Without one, there's nothing for a run to start from: a manual run and an automatic trigger both reference the workflow by that step's name, and neither works if it's missing. Let's start with a simple manual trigger that passes data to an output step.
import { Step, Workflow } from '@culvii/kit';
// 1. Create the trigger
const trigger = new Step({
name: 'Manual Trigger',
type: 'manualTrigger',
});
// 2. Create an action step
const output = new Step({
name: 'Set Output Data',
type: 'core.set',
params: {
values: {
triggered: true,
source: 'sdk',
},
},
});
// 3. Connect them
trigger.connectTo(output);
// 4. Group them into a workflow
const workflow = new Workflow({
id: 'my-first-workflow',
name: 'My First Workflow',
steps: [trigger, output],
});
Step IDs and Names
By default, the SDK generates a unique ID for each step. If you want stable snapshots for testing, you can provide your own id.
The name must be unique within the workflow. Dynamic values can only be set on a node's properties, inside params (serialized as nodeParams), not on name.
const step = new Step({
id: 'enrich-lead-step',
name: 'Enrich Lead',
type: 'core.set',
params: { values: { enriched: true } },
onError: 'stopWorkflow',
});
Steps also accept credentials: { name, id } (for credentialed connector and trigger nodes), disabled: true (to skip the step at runtime), ui (to attach output or wait surfaces), and onError ('stopWorkflow', 'continueRegularOutput', or 'continueErrorOutput').
Chaining steps and passing data
When you call source.connectTo(target), you create a connection from the main output of the first step to the main input of the second. Data flows automatically along this path.
trigger.connectTo(enrichLead);
enrichLead.connectTo(notifySales);
Use an expression when a later step needs a value produced by an earlier step:
const saveReply = new Step({
name: 'Save Reply',
type: 'core.set',
params: {
values: {
reply: "={{ $('Support Agent').json.response }}",
},
},
});
See Workflow data and expressions for nested fields, arrays, items, and conditional branches.
Branching and joining (core.if, core.switch, core.merge)
Use branching nodes to route data based on conditions, and joining nodes to converge multiple paths.
- core.if: evaluates
params.conditions(combineOperation: 'all' | 'any'); output index0is true and1is false. - core.switch: evaluates
params.rules(Array<{ name?, value1, operation, value2 }>) top-to-bottom (first match wins and short-circuits). Output index0 .. rules.length - 1routes to each rule in order (switchStep.connectTo(branch, { fromOutputIndex: i })), and output indexrules.lengthis the fallback output when no rule matches. - core.merge vs. implicit OR-join:
core.mergeis an explicit AND-join that waits for every incoming predecessor branch to complete and passes all branch items through unchanged. Any other step type with multiple incoming edges is an implicit OR-join that proceeds on the first arriving predecessor and cancels still-running or paused losing branches.
const routeByTier = new Step({
id: 'route-by-tier',
name: 'Route By Tier',
type: 'core.switch',
params: {
rules: [
{ name: 'enterprise', value1: '={{ $json.tier }}', operation: 'equal', value2: 'enterprise' },
{ name: 'pro', value1: '={{ $json.tier }}', operation: 'equal', value2: 'pro' },
],
},
});
routeByTier.connectTo(enterpriseTier, { fromOutputIndex: 0 });
routeByTier.connectTo(proTier, { fromOutputIndex: 1 });
routeByTier.connectTo(starterTier, { fromOutputIndex: 2 }); // fallback at rules.length
const mergeEnrichment = new Step({
id: 'merge-enrichment',
name: 'Merge Enrichment',
type: 'core.merge',
});
enrichBilling.connectTo(mergeEnrichment);
enrichUsage.connectTo(mergeEnrichment);
mergeEnrichment.connectTo(summary);
fromOutputIndex chooses the branch. It is not part of the expression used by the target step.
Adding steps
Steps don't have to go in the Workflow constructor. Add them with addStep/addSteps as you build them out:
import { Step, Workflow } from '@culvii/kit';
const trigger = new Step({ name: 'Manual Trigger', type: 'manualTrigger' });
const output = new Step({
name: 'Set Output Data',
type: 'core.set',
params: { values: { triggered: true } },
});
trigger.connectTo(output);
const workflow = new Workflow({ id: 'my-first-workflow', name: 'My First Workflow' });
workflow.addSteps(trigger, output);
If you connect a step, it must be added to the workflow too. A step that connects to one missing from the workflow throws when validated.
Loops
Use workflow.loop() to run a body of steps once per item in a list, instead of hand-wiring a Loop step yourself. It adds the core.loop step and its body in one call, and returns the loop step so you can wire what happens after it.
const invoiceLoop = workflow.loop({
id: 'invoice-loop',
name: 'Invoice Loop',
items: "={{ $('Fetch Invoices').json.body }}",
parallel: false,
body: b => {
const extractId = b.step({
name: 'Extract ID',
type: 'core.code',
params: {
code: `export default async function main(args) {
return { json: { id: args.id } };
}`,
codeType: 'js',
codeParams: { id: '={{ $item.json.id }}' },
},
});
const recordOutcome = b.step({
name: 'Record Outcome',
type: 'core.loopOutput',
params: {
values: { id: "={{ $('Extract ID').json.id }}" },
},
});
extractId.connectTo(recordOutcome);
return recordOutcome; // required: the body's single core.loopOutput step
},
});
fetchInvoices.connectTo(invoiceLoop);
// The loop's post-loop output is output index 1 ("main"); connectTo() defaults to it, so no
// explicit fromOutputIndex is needed here. Output index 0 ("body") is wired for you, internally,
// to every step your `body` callback registers with no incoming connection from another body step.
invoiceLoop.connectTo(countInvoices);
itemsresolves to the array to iterate over — the body runs once per item.parallelis required, with no default:trueruns every iteration concurrently;falseruns them one at a time. State it explicitly every time.bodyreceives a builder whoseb.step()constructs and registers a step scoped to the loop body. It must return that body's single Loop Output step — the body's required exit point, with no outgoing connection of its own.- Inside the body,
$itemrefers to the current iteration's item, and any earlier body step can be referenced by name exactly like outside a loop. connectTo()defaultsfromOutputIndexto1forcore.loop,core.loopBreak, andcore.loopContinue(and0for all other steps). Output index0oncore.loopBreakandcore.loopContinueis a marker output and must remain unwired.- Loops cannot be nested, and workflow graphs or loop bodies cannot contain cycles.
- The maximum number of items — and so the maximum number of iterations — is 500, whether the loop runs sequentially or in parallel. A loop whose
itemsresolves to more fails. - In a sequential loop only, use Loop Break to stop the whole loop early, or Loop Continue to skip to the next item. Neither is allowed when
parallel: true, since every iteration is already spawned before any of them could run. - After the loop,
$('Invoice Loop').json.resultsis the array of every Loop Output entry — one per iteration that reached it. An iteration that exits via Break or Continue contributes no entry. - A loop body can't contain a trigger step.
See Loop, Loop Output, Loop Break, and Loop Continue for the full node reference.