Workflow JSON
Understand the B3OS workflow definition format used by the API, editor, templates, and Caddie-assisted workflows.
A workflow definition is a directed graph. The graph always has a root node, and every child reference must point to another node in the same nodes map.
The visual editor is the fastest way to learn the shape of trigger and action payloads. Export or inspect the resulting definition when you need to automate the same pattern through the API.
Required Shape
json{ "nodes": { "root": { "type": "manual", "payload": {}, "children": ["next_node"] }, "next_node": { "type": "log", "payload": { "message": "Hello" }, "children": [] } }}
Node Fields
| Field | Required | Description |
|---|---|---|
| type | Yes | Trigger ID for root, action ID for all other nodes. |
| payload | Yes | JSON object validated against the trigger or action schema. |
| children | No | Ordered list of downstream node IDs. |
| connector | Conditional | Connector reference for actions that need external account, wallet, or bot access. |
| loopBody | Conditional | Child nodes executed per item for loop actions. |
| branch | Conditional | Branch label used under branch-capable parents. |
Expressions
Expressions pull data from the trigger, previous nodes, workflow props, and loop state.
| Expression | Meaning |
|---|---|
| {{$trigger.body.amount}} | Field from manual, webhook, or event trigger input. |
| {{$nodes.fetch_price.result.price}} | Result from a previous node. |
| {{$props.asset}} | Reusable prop supplied by a template or workflow consumer. |
| {{$item}} | Current loop item. |
| {{$index}} | Current loop index. |
Use readable IDs such as fetch_price, check_threshold, and send_alert. Stable IDs make expressions easier to
review.
If a value comes from a branch or loop, design a fallback path or only reference it inside the same branch context.
Connector Reference
Use connector references for actions that need account access. The connector record stores credentials separately from the workflow definition.
json{ "type": "send-telegram-message", "connector": { "type": "telegram-bot", "id": "conn_telegram_bot" }, "payload": { "chatId": "123456789", "text": "Workflow result: {{$nodes.format_message.result.formatted}}" }, "children": []}
Store external credentials in connectors or service-side configuration. Payloads should contain business inputs, not raw tokens, wallet signing material, or provider secrets.
Minimal Branch
json{ "nodes": { "root": { "type": "manual", "payload": {}, "children": ["check_amount"] }, "check_amount": { "type": "if", "payload": { "condition": { "$and": [{ "{{$trigger.body.amount}}": { "$gte": 100 } }] } }, "children": ["send_large_alert", "send_small_alert"] }, "send_large_alert": { "type": "log", "branch": "then", "payload": { "message": "Large amount" }, "children": [] }, "send_small_alert": { "type": "log", "branch": "else", "payload": { "message": "Small amount" }, "children": [] } }}