Skip to main content

The graph builder (tier 1)

The graph builder is code that constructs a canvas workflow. It runs when you push, never while the workflow runs, and it produces exactly the definition the canvas would save. This is also the form you get when you export a canvas workflow as code.

A first workflow​

workflows/lead-enrichment.ts
import { defineWorkflow, expr, triggers } from '@fluidgrids/workflows';
import { nodes as n } from '../.fluidgrids/nodes';

export const leadEnrichment = defineWorkflow(
{ key: 'lead-enrichment', name: 'Lead enrichment' },
(wf) => {
const inbound = wf.trigger(triggers.webhook, {
id: 'inbound',
args: { path: 'leads', validationMethod: 'HMAC_SHA256' },
});
const enrich = wf.http({
id: 'enrich',
after: inbound,
args: {
method: 'GET',
url: 'https://person.clearbit.com/v2/combined/find',
queryParams: { email: wf.json.body.email },
authType: 'connection',
responseFormat: 'json',
},
connection: 'enrichment-api',
retry: { maxRetries: 3, retryDelay: 2000, retryOnErrorTypes: ['TRANSIENT', 'DEPENDENCY'] },
});
const isEnterprise = wf.if({
id: 'is-enterprise',
after: enrich,
condition: enrich.output.body.company.metrics.employees.gte(500),
});
wf.step(n.slack.sendMessage, {
id: 'notify-sales',
after: isEnterprise.true,
connection: 'slack-ops',
args: {
channelId: 'C0SALES',
text: expr`New enterprise lead: ${enrich.output.body.person.name.fullName}`,
},
});
},
);

The same workflow in Python:

workflows/lead_enrichment.py
from fluidgrids_workflows import define_workflow, expr, triggers
from fluidgrids_workflows.project import nodes as n


@define_workflow(key="lead-enrichment", name="Lead enrichment")
def lead_enrichment(wf):
inbound = wf.trigger(triggers.webhook, id="inbound", args={"path": "leads"})
enrich = wf.http(
id="enrich",
after=inbound,
args={"method": "GET", "url": "https://person.clearbit.com/v2/combined/find",
"queryParams": {"email": wf.json.body.email}},
connection="enrichment-api",
)
is_enterprise = wf.if_(
id="is-enterprise",
after=enrich,
condition=enrich.output.body.company.metrics.employees >= 500,
)
wf.step(
n.slack.send_message,
id="notify-sales",
after=is_enterprise.true,
args={"channelId": "C0SALES",
"text": expr("New enterprise lead: ", enrich.output.body.person.name.fullName)},
connection="slack-ops",
)

Typed node clients​

fluidgrids codegen reads your workspace's node registry and writes .fluidgrids/nodes.ts (or .py). It has one property per installed node and one function per operation, typed from the node's input and output fields, so your editor completes arguments and flags mistakes before you push. Commit the file so the project type-checks in CI. Built-in nodes are also available offline from the package itself.

When the workspace's registry changes, fluidgrids validate warns that the generated file is out of date.

The builder methods​

MethodAdds
wf.trigger(trigger, options)The trigger. Exactly one per workflow: triggers.api, webhook, schedule, form, workflowCall, errorTrigger, or a store node's trigger
wf.step(operation, options)A store or built-in node operation
wf.http, wf.set, wf.code, wf.dataTable and the other built-in nodesThe matching built-in node
wf.if, wf.switch, wf.loop, wf.mergeControl flow. if returns true and false handles; loop takes a body callback
wf.wait, wf.sendAndWaitWaiting nodes
wf.subworkflowA sub-workflow
wf.note(text, options)A sticky note

wf.codeWorkflow adds a durable function as a Code workflow node, and wf.waitForSignal adds a Wait for Signal node.

Every method returns a reference to the node. after connects it: pass a node, a branch handle such as isEnterprise.true, or a list for a fan-in.

References instead of expression strings​

enrich.output.body.email is a typed reference. When the workflow is built it becomes the expression the canvas uses, {{ $node["enrich"].item.body.email }}, and wf.json.body.email becomes {{ $json.body.email }}. Comparisons such as gte, eq, contains and isEmpty, combined with and and or, become the condition tree of an IF node. Use expr`…` for text with references in it.

Rules that keep builds exact​

  • Every node needs an id. Ids keep the graph stable across builds, so the canvas keeps layout and pinned test data.
  • The same source always produces the same definition. Reading the clock or a random source while the workflow is being defined fails the build; use wf.now for the time a run starts.
  • Connections are written by name (connection: 'slack-ops'). Names are resolved to the workspace's connections when you push; a name that does not resolve stops the push before anything is written.
  • Node positions live in a sidecar file, workflows/<key>.layout.json, so the code stays readable and a round trip does not rearrange the canvas.

Next steps​