Nocobase Workflow

Node Linking Model

• Nodes form a linked list: upstreamId → downstreamId
• Branch nodes (condition, loop) use branchIndex:
  • 1 = true branch (condition) or loop body (loop)
  • 0 = false branch (condition)
  • null = main line continuation

Variable System

Workflow Patterns

Pattern 1: Auto-numbering (on create)

Generate sequential IDs like PR-2026-001:

# Step 1: Create workflow
nb_create_workflow("Auto Purchase Number", "collection",
    '{"mode": 1, "collection": "purchase_requests", "appends": [], "condition": {"$and": []}}')

# Step 2: Add SQL node
nb_add_node(wf_id, "sql", "Generate Number",
    '{"dataSource": "main", "sql": "UPDATE purchase_requests SET request_no = \'PR-\' || TO_CHAR(NOW(), \'YYYY\') || \'-\' || LPAD((SELECT COALESCE(MAX(CAST(SUBSTRING(request_no FROM \'[0-9]+$\') AS INT)),0)+1 FROM purchase_requests WHERE request_no LIKE \'PR-\' || TO_CHAR(NOW(), \'YYYY\') || \'-%\')::TEXT, 3, \'0\') WHERE id = {{$context.data.id}}"}')

# Step 3: Enable
nb_enable_workflow(wf_id)

Pattern 2: Status Sync (on create)

Set default status when a record is created:

nb_create_workflow("Default Status", "collection",
    '{"mode": 1, "collection": "orders", "appends": [], "condition": {"$and": []}}')

nb_add_node(wf_id, "update", "Set Draft Status",
    '{"collection": "orders", "params": {"filter": {"id": "{{$context.data.id}}"}, "values": {"status": "draft"}}}')

nb_enable_workflow(wf_id)

Pattern 3: Conditional Branch (on create)

Different actions based on field value:

nb_create_workflow("Transfer Type Handler", "collection",
    '{"mode": 1, "collection": "transfers", "appends": [], "condition": {"$and": []}}')

# Condition node
cond = nb_add_node(wf_id, "condition", "Is Transfer?",
    '{"rejectOnFalse": false, "engine": "basic", "calculation": {"group": {"type": "and", "calculations": [{"calculator": "equal", "operands": ["{{$context.data.type}}", "transfer"]}]}}}')

# True branch: update status to "transferred"
nb_add_node(wf_id, "update", "Mark Transferred",
    '{"collection": "assets", "params": {"filter": {"id": "{{$context.data.asset_id}}"}, "values": {"status": "transferred"}}}',
    upstream_id=cond_id, branch_index=1)

# False branch: update status to "borrowed"
nb_add_node(wf_id, "update", "Mark Borrowed",
    '{"collection": "assets", "params": {"filter": {"id": "{{$context.data.asset_id}}"}, "values": {"status": "borrowed"}}}',
    upstream_id=cond_id, branch_index=0)

nb_enable_workflow(wf_id)

Pattern 4: Field Change Trigger (on update)

React when specific fields change:

nb_create_workflow("Disposal Complete", "collection",
    '{"mode": 2, "collection": "disposals", "changed": ["status"], "condition": {"status": {"$eq": "disposed"}}, "appends": []}')

nb_add_node(wf_id, "update", "Update Asset Status",
    '{"collection": "assets", "params": {"filter": {"id": "{{$context.data.asset_id}}"}, "values": {"status": "disposed"}}}')

nb_enable_workflow(wf_id)

Pattern 5: Date-based Schedule

Trigger N days before a date field:

# Trigger 30 days before insurance expiry
nb_create_workflow("Insurance Expiry Warning", "schedule",
    '{"mode": 1, "collection": "insurance", "startsOn": {"field": "end_date", "offset": -30, "unit": 86400000}, "repeat": null, "appends": []}')

nb_add_node(wf_id, "sql", "Mark Expiring",
    '{"dataSource": "main", "sql": "UPDATE insurance SET remark = \'expiring soon\' WHERE id = {{$context.data.id}}"}')

nb_enable_workflow(wf_id)

Pattern 6: Cron Schedule

# Run every weekday at 9 AM
nb_create_workflow("Daily Report", "schedule",
    '{"mode": 0, "startsOn": "2026-01-01T00:00:00.000Z", "repeat": "0 9 * * 1-5"}')

Pattern 7: Multi-node Chain

Chain multiple nodes on the main line:

nb_create_workflow("Complex Flow", "collection",
    '{"mode": 1, "collection": "orders", "appends": [], "condition": {"$and": []}}')

# Node 1 (first node, no upstream_id needed)
n1 = nb_add_node(wf_id, "query", "Get Customer",
    '{"collection": "customers", "multiple": false, "params": {"filter": {"id": "{{$context.data.customer_id}}"}}}')

# Node 2 (chains after node 1)
n2 = nb_add_node(wf_id, "update", "Update Order",
    '{"collection": "orders", "params": {"filter": {"id": "{{$context.data.id}}"}, "values": {"customer_name": "{{$jobsMapByNodeKey.NODE_KEY.name}}"}}}',
    upstream_id=n1_id)

nb_enable_workflow(wf_id)

Workflow

Phase 1: Plan

Before creating workflows, identify:

1. Trigger: What event starts the workflow? (record created/updated/deleted, schedule, manual)
2. Collection: Which table triggers it?
3. Logic: What conditions and actions are needed?
4. Target: What data gets modified?

Phase 2: Create

1. Create workflow with trigger config
2. Add nodes in order (first node auto-links, subsequent need upstream_id)
3. For branches: add condition node, then true/false branch nodes with branch_index

Phase 3: Enable & Verify

1. Enable the workflow
2. List workflows to confirm: nb_list_workflows()
3. Inspect with: nb_get_workflow(wf_id)

Best Practices

1. Title convention: Use prefixes for grouping, e.g. "AM-WF01 Auto Number"
2. One workflow per concern: Don't combine unrelated logic
3. Idempotent SQL: Write SQL that's safe to run multiple times
4. Test before enable: Create all nodes first, then enable
5. Batch cleanup: Use nb_delete_workflows_by_prefix("AM-") to clean up
6. Duplicate prevention: Check nb_list_workflows() before creating — duplicate titles cause confusion
7. Variable references: Always use double braces {{$context.data.field}} — single braces won't work