Loop and Reuse Flows
How do you repeat invoice processing? Put it in a flow with a typed contract. Run flow calls that flow once. Run flow on list calls a body flow for each item, one after another, and collects the results.
Continue Invoice intake with a Store invoice flow that is already implemented. It routes blank IDs and negative amounts to an invalid-input result before recording. The scaffold adds no validation.
The fixtures below assume a parent with an Invoices input of type list.custom.invoice, and a source node that passes that list through unchanged. Work in the development version. Tests perform real writes and provider actions, so choose development records or an external test destination first.
Define the per-invoice contract
Section titled “Define the per-invoice contract”The new Process invoice body takes one required Invoice. It calls Store invoice with Invoice ID, Amount, and Review needed, then returns invoice_id and status. Use the invoice shape custom.invoice. If the source contains saved records, use dataRecord.custom.invoice instead, which preserves record identity. Both are supported.
In the app: choose Workflows → Invoice intake → Dev → New flow, create Process invoice, and declare its input and outputs under Inputs and Outputs. In the parent, choose Add action → Run flow on list, then configure Flow → Data type of items → List of items and map Invoice to the current item.
With an assistant: let the scaffold create Process invoice. The scaffold always creates a new body.
Scaffold from the exact list output
Section titled “Scaffold from the exact list output”Every workflow-scoped tool call below carries an explicit workflowId. Start by listing the workflows with workflow_list:
{ "limit": 100 }Select Invoice intake from data.items, using its id as <workflowId>. If two entries share the name, ask the person which one. limit caps at 100; if data.hasMore is true and the workflow is not listed, get its ID from the app before concluding it is absent.
Read the outline with workflow_outline:
{ "workflowId": "<workflowId>" }From data.flows, note the parent and Store invoice IDs as <parentFlowId> and <storeFlowId>. Note the parent’s source node ID as <sourceNodeId>, then read that node’s outputs with node_get:
{ "workflowId": "<workflowId>", "nodeId": "<sourceNodeId>" }Use the selected data.outputs[].id as <outputId>. For a whole output containing the invoice list, call flow_for_each_scaffold:
{ "workflowId": "<workflowId>", "flow": "<parentFlowId>", "from": "<sourceNodeId>", "sourceOutput": "<outputId>", "name": "Process invoice", "itemType": "custom.invoice", "itemName": "Invoice", "maxItems": 500 }Its source is either from plus sourceOutput, or listJs alone.
For a nested list, add listField with the actual source field path; it requires the source-output form. Note data.bodyFlowId as <bodyFlowId> and data.loopNodeId as <loopNodeId>. Inspect data.itemFlowInput, data.listWiring.listExpressionJs, the warnings, and nextSteps. A type mismatch only warns, so fix it before running.
The body, list wiring, and item mapping are created before the scaffold sets an explicit cap. If that later step fails, the scaffold remains. Inspect the returned IDs and reread the outline before retrying.
Map the current item into the body
Section titled “Map the current item into the body”item exists in the parent’s per-item mapping. The body uses its own flow input binding. Data type of items reloads the list field, so after changing it, reread the props and recheck the list expression and mappings. The reload preserves existing expressions when the editor input type stays unchanged, so a saved expression can still target the old type.
In the app: use Go to flow, add Run flow, select Store invoice, and map its three inputs from Invoice.
Find the Run flow action before adding it with integration_action_list:
{ "query": "Run flow" }Use Run flow’s data.items[].nodeSlug and key as <slug> and <componentKey>, then inspect it with integration_action_get:
{ "integration": "<slug>", "key": "<componentKey>" }Add it to the body with node_add, which takes the slug as node:
{ "workflowId": "<workflowId>", "flow": "<bodyFlowId>", "node": "<slug>", "key": "<componentKey>", "name": "Store this invoice" }Note data.nodeId as <callNodeId>. Point that call at Store invoice with node_subflow_set, which takes the target as flow:
{ "workflowId": "<workflowId>", "nodeId": "<callNodeId>", "flow": "<storeFlowId>" }Then read its mapping props with node_prop_list and its bindings with expr_context, each called with:
{ "workflowId": "<workflowId>", "nodeId": "<callNodeId>" }Use the three returned mapping names as <invoiceIdProp>, <amountProp>, and <reviewNeededProp>. If context advertises flow.invoice, map each with node_prop_set and js:
{ "workflowId": "<workflowId>", "nodeId": "<callNodeId>", "prop": "<invoiceIdProp>", "js": "flow.invoice.invoice_id" }{ "workflowId": "<workflowId>", "nodeId": "<callNodeId>", "prop": "<amountProp>", "js": "flow.invoice.amount" }{ "workflowId": "<workflowId>", "nodeId": "<callNodeId>", "prop": "<reviewNeededProp>", "js": "flow.invoice.review_needed" }Editing a required child input, or an optional one that is already enabled, synchronizes ordinary callers. A new optional mapping has to be enabled. Reread the caller after contract edits. The node_subflow_set warning requiring relinking is stale.
Declare the body’s two outputs, then configure a complete Return response after the call, following Define Flow Contracts. An untouched text output writes empty text, and an untouched non-text output writes null. Later completed Returns overwrite earlier values.
Choose the cap and failure behavior
Section titled “Choose the cap and failure behavior”Max items defaults to 500 and accepts integers 1–10000. A list over the cap fails before any item runs, and it is not truncated. The whole run also shares 25,000 node executions, counting child nodes and scheduled skips. Calls beyond Max subflow depth fail, and that setting defaults to 100 with a range of 1–10000. If a child fails at either limit, iteration continuation records the failure and attempts later items.
In the app, leave Continue to next item if an iteration fails off to stop at a failed child. With an assistant, write the same setting with node_prop_set, which takes a boolean value:
{ "workflowId": "<workflowId>", "nodeId": "<loopNodeId>", "prop": "continueOnIterationError", "value": false }At scaffold creation, continuation is flow_for_each_scaffold’s continueOnError.
Stopping loses the aggregate list. Earlier effects remain, and a new run starts at item zero and repeats them. Iteration continuation retains failed-child records and moves on, but it cannot rescue list-expression or pre-child mapping errors. Node-level Continue on error lets the parent continue after a failed loop, but never resumes remaining items.
A child finishing completed_with_error keeps its outputs and has a null iteration error. It never triggers the stop switch, but it counts toward the loop’s error message, such as 1 of 2 iterations failed. The loop and parent finish completed_with_error unless a later failure ends the parent.
Inspect every iteration
Section titled “Inspect every iteration”Downstream expressions receive the iteration list from .data. Execution inspection shows {data: [...], error: null|string}. Each record has index, outputs, status, and error. A failed record has null outputs and an error. An empty list returns [] without children.
In Dev, select the body, then Test. Use one safe invoice before testing the parent. Open Run history → Flow Executions → View to inspect children.
With an assistant, lay out both flows with flow_layout (once per flow ID), validate the workflow with workflow_validate, and read both input sets with run_inputs, which takes the flow ID as nodeIdOrFlowId and flow: true:
{ "workflowId": "<workflowId>", "flowId": "<bodyFlowId>" }{ "workflowId": "<workflowId>" }{ "workflowId": "<workflowId>", "nodeIdOrFlowId": "<bodyFlowId>", "flow": true }Repeat flow_layout and run_inputs with <parentFlowId>. Then run the body once with run_flow, which takes parsed inputs:
{ "workflowId": "<workflowId>", "flowId": "<bodyFlowId>", "target": "dev", "inputs": { "Invoice": { "invoice_id": "INV-104", "amount": 120, "review_needed": false } } }Confirm the advertised input labels match these fixtures. Run each parent fixture separately with run_flow and inspect its execution before the next:
{ "workflowId": "<workflowId>", "flowId": "<parentFlowId>", "target": "dev", "inputs": { "Invoices": [] } }{ "workflowId": "<workflowId>", "flowId": "<parentFlowId>", "target": "dev", "inputs": { "Invoices": [{ "invoice_id": "INV-104", "amount": 120, "review_needed": false }] } }{ "workflowId": "<workflowId>", "flowId": "<parentFlowId>", "target": "dev", "inputs": { "Invoices": [{ "invoice_id": "INV-104", "amount": 120, "review_needed": false }, { "invoice_id": "INV-105", "amount": 1500, "review_needed": true }] } }Run the two-item fixture again with the cap set to 1. No child should start. Restore 500 afterward. Set the cap with node_prop_set, rerun the two-item fixture above with run_flow, then call node_prop_set again with "value": 500:
{ "workflowId": "<workflowId>", "nodeId": "<loopNodeId>", "prop": "maxItems", "value": 1 }To test a failed child, supply null for Store invoice’s referenced, required Amount. Its numeric mapping stays missing, and the child fails input validation.
{ "workflowId": "<workflowId>", "flowId": "<parentFlowId>", "target": "dev", "inputs": { "Invoices": [{ "invoice_id": "INV-105", "amount": null, "review_needed": true }] } }After each run, use data.workflowExecutionId as <workflowExecutionId>. A successful response can still describe a failed execution, so check data.status. A polling timeout does not cancel work, so inspect that execution with execution_tree:
{ "workflowId": "<workflowId>", "workflowExecutionId": "<workflowExecutionId>", "limit": 200 }The tree defaults to 50 rows and caps at 200, and the rows omit outputs. While data.nextCursor exists, call execution_tree again with cursor set to it to read the next page.
Use the loop row’s data.items[].id as <nodeExecutionId> and read it with execution_node_get:
{ "workflowId": "<workflowId>", "nodeExecutionId": "<nodeExecutionId>", "full": true }full: true includes the untruncated output. Recent execution lists (execution_list) default to 10 runs and cap at 100. Read the iteration statuses and resolved mappings, then read back the stored records.
Call the same flow once
Section titled “Call the same flow once”For a separate one-off parent, choose New flow, add Run flow, select Store invoice, and map its inputs. The parent waits for the child and receives its named outputs.
Create that parent with flow_create and note data.flowId as <oneOffFlowId>.
{ "workflowId": "<workflowId>", "name": "Store one invoice" }Reuse the discovered Run flow action pair with node_add:
{ "workflowId": "<workflowId>", "flow": "<oneOffFlowId>", "node": "<slug>", "key": "<componentKey>", "name": "Store one invoice" }Use data.nodeId as <oneOffNodeId>, point it at Store invoice with node_subflow_set, then read its mapping names with node_prop_list ({ "workflowId": "<workflowId>", "nodeId": "<oneOffNodeId>" }):
{ "workflowId": "<workflowId>", "nodeId": "<oneOffNodeId>", "flow": "<storeFlowId>" }Use the matching three mapping names for this call. These literal values need no item binding. Set each with node_prop_set:
{ "workflowId": "<workflowId>", "nodeId": "<oneOffNodeId>", "prop": "<invoiceIdProp>", "value": "INV-104" }{ "workflowId": "<workflowId>", "nodeId": "<oneOffNodeId>", "prop": "<amountProp>", "value": 120 }{ "workflowId": "<workflowId>", "nodeId": "<oneOffNodeId>", "prop": "<reviewNeededProp>", "value": false }Then check the wiring with flow_layout ({ "workflowId": "<workflowId>", "flowId": "<oneOffFlowId>" }) and call workflow_validate with { "workflowId": "<workflowId>" }.