Configure Workflow Nodes
How do you turn an action into a working workflow step? Add the action, select its account, configure its fields in dependency order, and wire its inputs. Then resolve its output type. A node can be ready to run before its output type is known.
Work in the development version, where tests call providers for real. Before testing a read, choose the account and invoice record. Before a send or a write, choose a safe destination.
Find the exact action
Section titled “Find the exact action”In the app: choose Workflows → Invoice intake → Dev → flow → Add action. Search Actions, select the integration, then select the action.
With an assistant: every workflow-scoped tool call carries an explicit workflowId. List the workflows first with workflow_list:
{ "limit": 100 }Select Invoice intake’s id from data.items as <workflowId>. If several match, ask which one. If data.hasMore is true and it is absent, open it in the app and take the ID after /workflows/ in its URL.
Read its outline with workflow_outline ({ "workflowId": "<workflowId>" }), then search for the action with integration_action_list:
{ "query": "read invoice" }Take the intended data.flows[].id as <flowId>. From the action result’s data.items, select the exact nodeSlug as <slug> and key as <componentKey>. Narrow the query if data.hasMore is true.
Inspect the action with integration_action_get, then add it with node_add.
{ "integration": "<slug>", "key": "<componentKey>" }{ "workflowId": "<workflowId>", "flow": "<flowId>", "node": "<slug>", "key": "<componentKey>", "name": "Read invoice" }Note the added node’s data.nodeId as <nodeId>.
Select the account before its resources
Section titled “Select the account before its resources”In the app: choose Connection, or Connect / Add new connection to authorize an account.
With an assistant: list the connected accounts with connection_list.
{ "integration": "<slug>" }Choose the intended ACTIVE account from data.items, using its id as <connectionId>. If several active accounts match and no preference exists, ask which one. If none exists, start an authorization with connection_connect_url:
{ "nodeSlug": "<slug>" }Have the person authorize data.url. Then call connection_list again and select the new ID. Bind it with node_connection_set:
{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "connection": "<connectionId>" }Then reload it with node_prop_reload and read the props back with node_prop_list, each called with { "workflowId": "<workflowId>", "nodeId": "<nodeId>" }.
Binding checks the saved status and the integration, not the provider’s authorization. Changing the connection resets remote-option values to defaults and clears the cached field catalog. Reselect the affected values after reloading.
Configure selectors before dependent fields
Section titled “Configure selectors before dependent fields”In the app: choose the invoice spreadsheet before its sheet and columns.
With an assistant: in node_prop_list’s data.props, inspect required, reloadProps, and option metadata. Setting a concrete value on a reload selector re-resolves the later fields, which can be added, removed, or left unchanged, and selections can be cleared. Reread the props after each selector write. node_prop_list only reads. node_prop_reload re-resolves. If a selector is unset, an explicit reload preserves the dependent fields instead of removing them.
Use the field’s name as <name> and search by the resource’s label as <q> with node_prop_options:
{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "prop": "<name>", "query": "<q>" }Copy a matching data.options entry’s value as <literal> and label as <label>, then write it with node_prop_set, which takes a label array even for one selection, and reread the props with node_prop_list:
{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "prop": "<name>", "value": "<literal>", "label": ["<label>"] }In a multi-select, labels must align with values. A response carries at most 100 options. For remote options, narrow the search when data.hasMore is true, or pass the returned data.context as parsed prevContext. Static lists ignore query, report hasMore: false, and hide entries beyond 100 through this operation. Add '<prop>=<value>' entries to the for array to preview an earlier selector without saving it.
blocked_upstream means you must set blockedBy first. dynamic_upstream means an earlier expression prevents a concrete option list, so use a raw value or an expression. available means no selector blocks the lookup, and absent metadata means unknown. Configure concrete selectors and their dependent fields before switching to expressions, because an expression preserves the last concrete selection’s dependent schema instead of discovering a new one.
Enable fields and wire their values
Section titled “Enable fields and wire their values”In the app: enable Optional inputs, draw an edge from the producer, then select its value in the field’s expression editor. An edge makes a value available. It does not assign an action field.
node_prop_set enables an optional field automatically before writing to it. A write that fails can leave the field enabled. Disable a field only to delete its stored value. When the base field list is available, disabling a reload field also prunes dependents outside that base set. Disable it with node_optional_prop_set, then reread the props with node_prop_list:
{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "prop": "<name>", "enabled": false }Take the producer’s id from the outline’s selected flow’s nodes as <sourceNodeId>. Connect it with node_connect, then read the field’s bindings with expr_context:
{ "workflowId": "<workflowId>", "flow": "<flowId>", "from": "<sourceNodeId>", "to": "<nodeId>" }{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "prop": "<name>" }Use the intended data.inputs[].js binding as <src> and write it with node_prop_set using js:
{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "prop": "<name>", "js": "<src>" }Router and If / Else require branch connections.
Make downstream fields available
Section titled “Make downstream fields available”In the app: open Output → Action output format, select a supported format, or test representative data.
With an assistant: check readiness with node_status ({ "workflowId": "<workflowId>", "nodeId": "<nodeId>" }), then read the inputs a test needs with run_inputs:
{ "workflowId": "<workflowId>", "nodeIdOrFlowId": "<nodeId>" }Status reports data.readyForRun, data.readyForDownstreamExpressions, and data.blockedBy. Readiness does not prove correct wiring. For an isolated test, build <inputs> from the input readback, keyed by every referenced data.flowInputs[].id, with safe invoice values. If you leave one out, the test fails with ISOLATED_FLOW_CONTEXT_REQUIRED. Explicit null, empty text, false, and zero count as supplied. Upstream nodes do not execute, so supply wired-input fixtures using data.nodeInputs[].id, then verify upstream expressions with the complete-flow test below. Run the node with run_node, which takes parsed inputs:
{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "inputs": { "<inputId>": "<value>" } }Inspect data.resolvedConfigs, data.output, and data.outputTypeAdoption, then reread status and destination context. Adoption belongs to that exact node, and scratch discovery cannot type it. no_observed_output means no reusable type was found.
If you prefer not to run the node, declare the shape instead. An unresolved or still-declared dynamic action output accepts a documented JSON object or non-empty array, such as the contents of invoice-response.json. Static outputs, flow calls, nodes without an output, and already-observed contracts reject a declaration. Call node_output_type_declare with the parsed sample, not a filename:
{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "sample": { "invoice_id": "INV-104", "amount": 120 } }The shape stays unverified until a completed run of the unchanged node yields a reusable type. Adoption clears the declaration marker and replaces a declared type that does not match. A no_observed_output result preserves the declaration.
Use HTTP when the action does not fit
Section titled “Use HTTP when the action does not fit”A missing connection calls for authorization. Choose Send HTTP request when the catalog action cannot perform the API operation you need.
In the app: add that action and configure these fields:
| Field | Behavior |
|---|---|
Method (method) |
GET, POST, PATCH, PUT, DELETE, HEAD. |
URL (url) |
Required invoice API endpoint. |
Authentication (authType) |
None by default; Basic Auth reveals username/password; Bearer Token reveals token. Have the person enter credentials in the app, never chat. |
Body Type (body_type) |
None by default; JSON, Raw, or Form Data reveals body. Set the selector before its body. |
Timeout (in seconds) (timeout) |
Empty means no HTTP-client timeout; set a limit such as 30. |
With an assistant: find it first with integration_action_list:
{ "query": "Send HTTP request" }Select its returned nodeSlug as <slug> and key as <componentKey>. Inspect it with integration_action_get, then add it with node_add:
{ "integration": "<slug>", "key": "<componentKey>" }{ "workflowId": "<workflowId>", "flow": "<flowId>", "node": "<slug>", "key": "<componentKey>", "name": "Read invoice API" }Note data.nodeId as <httpNodeId>, then set your invoice API’s GET endpoint as <literal> with node_prop_set, once per field:
{ "workflowId": "<workflowId>", "nodeId": "<httpNodeId>", "prop": "method", "value": "GET", "label": ["GET"] }{ "workflowId": "<workflowId>", "nodeId": "<httpNodeId>", "prop": "url", "value": "<literal>" }{ "workflowId": "<workflowId>", "nodeId": "<httpNodeId>", "prop": "timeout", "value": 30 }Set authentication to match that API. A successful request returns only the body, without status or headers. A final non-2xx response fails the action. The output starts without a fixed type, so use the adoption procedure above.
Verify the complete flow
Section titled “Verify the complete flow”In the app: choose the flow in Dev → Test, then inspect Run history.
With an assistant: lay out the flow with flow_layout ({ "workflowId": "<workflowId>", "flowId": "<flowId>" }), validate it with workflow_validate ({ "workflowId": "<workflowId>" }), and read back its inputs with run_inputs:
{ "workflowId": "<workflowId>", "nodeIdOrFlowId": "<flowId>", "flow": true }Resolve validation errors first. Then build inputs from the returned data.flowInputs[].id keys, with safe values such as INV-104 and 120, and call run_flow:
{ "workflowId": "<workflowId>", "flowId": "<flowId>", "target": "dev", "inputs": { "<invoiceInputId>": "INV-104", "<amountInputId>": 120 } }Check data.nodeExecutions for resolved inputs, statuses, and outputs, and confirm the invoice read or the intended external effect. Inspect data.outputTypeAdoptions, and reread the downstream context after an adoption. These changes and adopted types now belong to development.