Creating a workflow¶

Status: Current | Last reviewed: 2026-10-13

Workflow settings now include Safety checks for incoming requests, final results and individual steps/tools. See safety profiles for policy selection and failure behavior.

A workflow is a graph of steps that runs in response to an event: a CRM record update, a webhook, a schedule, or an agent calling one mid-conversation. Workflows handle work that does not fit inside a single agent turn.

These appear as Background agents in the unified agent repository. Their graph, triggers, execution behavior and API IDs are unchanged.

Prefer to describe the flow and let an AI assistant build the first draft? See Generate with AI if your tenant has it enabled. The same option appears in the New background agent dialog.

When to use a workflow¶

Use a workflow when the work is:

• Asynchronous: send a confirmation email after the call ends, fetch a record that takes 10 seconds, or queue a callback.
• Multi-step with branching: fetch from CRM, decide based on the result, write back, notify a human.
• Event-driven: fire from Salesforce Pub/Sub, a webhook, a cron schedule, or an inbound broker message.

If the work is "during this turn, look up something and respond," that's a tool, not a workflow. Tools live inside an agent's pipeline; workflows live alongside.

View and preview a workflow¶

With Viewer access, both drafts and published versions show View only. Click any node to inspect its settings. Start exposes triggers and input parameters; End exposes output parameters. You can open nested workflow and For Each views, expand details, select and copy text, pan, zoom and toggle Show phases. Configuration controls are read only, and structural editing and deletion are unavailable.

Select Preview in the header or right-hand panel to run the version displayed on the canvas. Preview identifies Draft or the version number; opening a published version runs that version even when a draft exists. Values entered in Preview are temporary inputs and do not change the workflow's saved settings.

Canvas header and activity¶

The WORKFLOW CANVAS header follows the Agent Canvas layout. The version selector beside the workflow name switches between Draft and published versions. Published versions show View only; use Open draft to edit, or Create draft when none exists. Opening an unversioned workflow link defaults to its available draft.

Use Notifications in the header to review errors, warnings and save failures. Validation errors still block publishing. The canvas stays clear of warning banners. Connected collaborators appear beside the header actions when collaboration is available.

• Preview opens the tester for the selected version.
• Settings opens a centered modal for workflow configuration and metadata, matching Agent Settings.
• Activity → Change History shows edits across drafts and published versions, with a version label on each entry. Execution History lists runs across versions; select a run to open its details inside Activity.
• More → Export exports the selected version. Editors can also delete the workflow here after confirmation.

The assistant opens from the round chat button at the bottom right when enabled. It stays independent of Preview; collapsing the assistant keeps the conversation and any response in progress. Full-screen Preview temporarily hides the popup.

Workflow settings¶

Select Settings in the header to open the modal. Its content scrolls while the workflow name and Done button stay visible. Configure identity, runtime limits, LLM execution policy, provider rate limits and retries here. Triggers and inputs remain on Start; outputs remain on End.

Draft settings save automatically. Tags use Save tags, and the Active switch changes availability immediately across versions. Published settings are view only. For templates, close the modal and use Save in the canvas header.

Use Done, the close button or Escape to return to the same canvas.

Create the workflow¶

1. From the left nav, open Agents. Select Background to browse workflows.
2. Click New agent → Background agent.
3. Choose how to start:
4. Template: search and select a workflow template.
5. Scratch: start from a blank workflow.
6. Generate with AI: describe the workflow you need and let the assistant draft the first version.
7. Fill in:
8. Name: display name.
9. Description: when this fires and what it does.
10. For Generate with AI, add the workflow prompt.
11. Click Create background agent, or Start generating for Generate with AI.

You land on the workflow's graph editor. If you started from a template, its nodes, settings, triggers, and parameters are copied into the new workflow. If you started from scratch, click the + on the canvas to open the Add to flow sidebar and choose the first node; the editor keeps the path connected with new + affordances before and after the node.

Workflow templates are managed under Tools & Templates → Workflow Templates. Creating or editing a template uses the same workflow editor canvas, but templates cannot be published, tested, or run directly.

Tags and activation¶

Open Settings from the workflow canvas to edit Tags and choose Save tags. The Active switch changes workflow availability immediately. Both settings apply to the workflow identity across all versions; neither saves or publishes the graph. Activation is unavailable for workflow templates. Failed saves retain your tag edits or previous activation state so you can retry.

The graph editor¶

The inspector and Preview start collapsed, matching the agent canvas. Select a node to open its inspector, or use the edge rails to open either panel. Undo/Redo and panel controls sit on the canvas; settings, Activity and publishing stay in the page header. The inspector shows the selected node's title once.

A missing background-agent link offers Back to agents. Check the active tenant and open the agent from the repository; a deleted identity cannot be reopened by changing its version suffix.

Workflows are graphs, not linear scripts. On the graph you can add:

For behavior, configuration options, outputs, and advanced node types, see Workflow node types.

Use the + on an edge to open the Add to flow sidebar and insert a node into that path, or drag nodes from the palette onto the canvas and connect them. Use the maximize button on a For Each card to open its body, then use + between Each item and Next item. Added steps stay inside the loop and the body layout makes room automatically. Each node has its own inspector, matching the pipeline editor.

If an Action is missing a required value or receives a value the connected API cannot use, the run can pause in a waiting-for-input state. Conversation-backed runs ask the caller for the missing or corrected detail in the existing chat or speech channel, then retry the action. Runs without a conversation show the requested information on the run record so an operator or API client can provide it and resume the workflow.

Actions can use tools from the shared tool library, or define workflow-local inline tools directly from the selector. Inline Python tools run sandboxed Python; Inline API tools call one configured HTTP endpoint. Local inline tools are stored on the workflow, so every Action node in that workflow can select a tool created from any other Action node. Older Code nodes open as Action nodes that select a migrated Inline Python tool.

For Notification nodes on the SMS channel, select the messaging integration first. SMS Origination Identity then lists active SMS-capable phone numbers and active pools from that integration. You can use one of those identities, keep the integration default, or enter a custom sender identity if the live list is unavailable.

Selecting a node opens its inspector on the left. Use the toolbar Undo / Redo buttons, or the usual keyboard shortcuts, to step through recent draft edits. Use the side rails to collapse or reopen the inspector and tester when you want more canvas room, and use the expand buttons in the inspector or tester headers when you want either side to take over the workspace. Expanding or restoring the tester keeps the current test inputs and latest run details intact.

The inspector shows each node's Label, Description, and merge-template reference. Labels are display names; merge templates keep using the stable node id shown in the inspector, such as {{lookup_case.field}}.

Click Start to configure execution mode, enabled triggers, Input Parameters, and External MCP Exposure. Click End to configure output parameters returned to callers. Output parameters default to Path mode: type a source directly or choose one from the source-path browser, which lists system fields, Inputs, node outputs reachable from Start, and flow variables. Reachable leaf nodes are listed even when they end the workflow implicitly without a drawn connection to End. The browser has its own scrollbar for long lists. After choosing an object-like source such as lookup_case.data, append the exact dynamic property you need, for example lookup_case.data.records[0].Id. Switch an output row to JSONata when you need to combine, filter, reshape, or calculate values from multiple workflow fields.

AI Agent nodes have an Execution Tier advanced setting. Standard runs synchronously, Flex uses a provider flex tier when supported, and Batch submits through the provider batch API and resumes the workflow when results arrive. In the workflow Settings tab, Fallback Flex capacity errors to Standard controls whether Gemini Flex capacity or rate-limit errors retry once on Standard for that run. The setting is off by default. Provider rate limits in the same tab define shared caps such as "20 Gemini Flex calls in flight" across parallel workflow runs. Leave an AI Agent node's Rate limit ID blank to use the first matching profile, or set it to a specific profile ID.

Wait events¶

A Wait node can pause for a duration or for an event type. For an event wait, enter the event type the external system will send, such as ticket.updated. The event should be posted to workflows-api with the running workflow execution id in payload.workflow_execution_id or payload.execution_id, plus the event details that downstream nodes need. See the workflows-api for the request shape.

When the wait resumes, the event payload is exposed on the Wait node output. If the Wait node id is wait_for_ticket, reference payload fields directly, such as {{wait_for_ticket.ticket_id}} or {{wait_for_ticket.status}}. The full event body is also available under {{wait_for_ticket.payload.ticket_id}}. Use Event filter only when the wait should resume for a subset of matching events, for example a specific status or ticket id.

For Each settings¶

Use For Each when a flow needs to repeat a body step for every item in a list or dataset. Items path points at the list, such as lookup_cases.records. The body receives a fixed iterator scope: {{iterator.current_item}} is the current value, {{iterator.index}} is its zero-based position, {{iterator.total}} is the collection size, and {{iterator.parent_node}} identifies the enclosing For Each block.

Iteration mode controls the body scheduling. Sequential runs one item at a time. Parallel runs multiple list items at once.

The advanced settings have defaults that are safe for most workflows:

• Concurrency defaults to Auto, which lets the runtime choose the per-loop parallelism when parallel mode is enabled.
• Dataset execution defaults to Auto. The runtime keeps small lists inline and uses durable dataset execution when the input is large or stream-like.
• Dataset max in-flight defaults to 20. It limits how many durable dataset items can be leased at once; Concurrency limits how many loop body executions run at once.
• Max retries defaults to 3. Backoff base seconds defaults to 5; Backoff max seconds defaults to 300.
• On error defaults to Collect, which records item-level errors and lets the loop finish. Choose Fail Fast when one item failure should stop the loop.
• Max items defaults to Unlimited. Set a number only when you want a hard cap for testing or guardrails.

Select the maximize button (Open For Each body) on the For Each card to enter its focused graph. Each item replaces the ordinary Start block and shows which collection feeds iterator.current_item; select it to edit the collection, scheduling, concurrency, and item cap. Next item replaces End and shows that the current result is collected before the index advances; select it to edit fail-fast behavior and inspect the aggregate output path, node_results.<for-each-id>. Published versions expose the same explanations and inspector fields in view-only mode.

Phases¶

New workflows start without phases. Turn on Show phases only when you want visual grouping on the canvas. When phases are shown, the inspector adds a Phase field under Description. Inserting between two steps in the same phase keeps the new step in that phase. Other new nodes stay blank until you choose a phase. Choose an existing phase, leave it blank, or select Add New... to name a phase, describe it, and pick an accent color.

When Show phases is turned off, the editor lays out the workflow as a flat graph and tries to keep branch paths readable by reducing crossing or overlapping edges.

When phases are shown, each group fits its contents and follows the workflow direction with consistent space between groups. Nested For Each containers stay inside their phase, while their body nodes remain inside the loop. Older workflows that saved phase locations without a complete layout are arranged automatically when opened. Toggling Show phases preserves the workflow and its saved layout.

Joins entering the first step of a phase leave space below the phase title for the shared +. Adding a step there grows the phase and moves later groups down. Dragging a phase saves its position and contents together; Undo and Redo restore the move. Use Auto layout to replace a saved manual arrangement.

A For Each card stays compact and shows the collection and body step count. Its maximize button opens the body in a focused canvas; the parent workflow continues only after all items finish.

Inspect a subflow¶

Add For Each from the node menu to create a loop. Its body opens with the maximize button; there is no inline expand/collapse view. Older standalone Subworkflow nodes remain supported and open with Open in focused view. They call a body once, whereas For Each repeats its body for each collection item. The add menu offers For Each for new nested bodies.

Select Open in focused view to work inside the subflow. The Inspector starts collapsed. Selecting a step opens its configuration in the usual left Inspector; use the same rail to collapse, reopen or resize it. For Each bodies use this Inspector for Each item, Next item and their steps too. The full-screen configuration button opens the selected nested step.

Use the breadcrumb or Close focused view to return to the parent workflow. Nested edits save with the workflow. Published versions allow focused inspection with editing disabled.

Arrange the canvas¶

If saved boxes overlap, the canvas automatically spaces the affected steps and their branches when you open the workflow. This also works while viewing a published version. It changes the display without changing the published workflow or creating a draft. Manual layouts that already fit are preserved.

Select Auto layout in the canvas toolbox to arrange the workflow from Start to End, top to bottom. Steps align in rows, branches occupy separate columns, and joins follow their incoming paths. Rows leave room for the tallest card. Phases fit around their contents. For Each cards stay compact; body steps have their own layout in the focused loop canvas.

Connections use square corners. A path that skips steps, such as a branch straight to End, gets its own clear column alongside those steps. Start and End stay aligned in the same column and cannot be dragged independently. Use Fit view to bring the whole graph, including these connection columns, into view.

Insertion points distinguish shared work from work on one branch:

A small dot marks a join. Hover over its shared + to see Insert on all incoming paths; the add panel confirms Applies to all incoming paths. Individual branch controls sit before the join, and the shared control sits after it. Ordinary connections keep their + halfway between cards. Branch labels sit above their button and grow or wrap within the pill to fit.

Adding a step with an edge's + automatically rearranges the current graph to make room. Rows move to fit the new card, branch joins stay below their incoming steps, and phases grow around their contents. Inside a focused loop, only the body layout changes; the parent card stays compact. The canvas fits the updated graph once the new card is sized. This also works when inserting several steps in succession. You do not need to click Auto layout after each insertion. Undo removes the new step and restores the previous arrangement together; Redo restores the insertion.

Auto layout replaces saved node positions and fits containers to their contents. It autosaves as one edit; use Undo to restore the previous arrangement or Redo to apply it again. Notes stay where you placed them. Opening a saved workflow preserves manual positions that do not overlap; new blocks are placed in available space. In a draft, moving a step after an automatic overlap repair saves the repaired spacing with your move. Undo restores its previous placement.

The button also appears in focused For Each and subworkflow canvases. When phase boxes are hidden, the flat view is arranged separately and the saved phase coordinates retain their grouping. Published versions and Viewer access do not offer the Auto layout button.

Salesforce actions¶

Salesforce work is handled through Action nodes. Select a Salesforce-backed tool, MCP action, or Inline API tool, then map the inputs the action requires. For a SOQL query, the End source-path browser reads the SELECT list and offers the projected fields under that Action. A Salesforce Platform MCP query named lookup_caller with SELECT FirstName, LastName ..., for example, offers lookup_caller.records[0].FirstName and lookup_caller.records[0].LastName. The older SFDC action envelope uses lookup_caller.data.records[0].FirstName; choose the path shown by the browser for the selected action.

Action parameters support inline JSONata when an input needs normalization. To remove + from an incoming ANI inside a SOQL filter, use WHERE Phone = '{{jsonata: $replace(input.ani, "+", "")}}'. If several nodes need the normalized value, put $replace(input.ani, "+", "") in an Assignment row using JSONata mode, save it to a variable such as normalized_ani, and reference {{vars.normalized_ani}} downstream.

For large query results, route the returned dataset or list into a For Each node. Dataset-backed loops run durably by default, so a million-row query does not put a million objects into workflow state. The For Each advanced settings control per-run max_in_flight, retries, and backoff; workflow Provider rate limits control shared Gemini/Flex caps across runs.

Deleting a node reconnects the path around it, so the node above stays connected to the next node or to End. Deleting a For Each block also deletes its body steps.

Variables and the payload¶

Every workflow run starts with Inputs, the named values a caller provides. Reference them as {{input.name}}. Existing templates can still resolve event payload fields through {{trigger.field}} or {{context.field}}, but the merge-field dropdown keeps those out of the visible variable sections.

The floating Inputs & variables panel keeps Inputs separate from flow variables. Inputs use {{input.name}}; manually added local variables and Assignment/Code/Tool outputs use {{vars.name}}. Merge-field dropdowns also include system fields such as {{system.workflow_execution_id}} and {{system.workflow_id}}.

Assignment nodes write reusable flow variables. In Template mode, a row accepts literal text or merge templates. In JSONata mode, a row evaluates the value as a JSONata expression against the current workflow state. The expression document exposes upstream node IDs at the top level, plus system, vars, input, trigger, context, iterator, node_results, and state.

LLM instructions and other template fields can also use inline JSONata with {{jsonata: ...}} when a normal merge path is too broad or too shallow. For example, after a related-data lookup you can include only the fields the LLM needs:

Summarize these cases:
{{jsonata: get_related_data.records.{"case": CaseNumber, "subject": Subject, "description": Description}}}

In LLM instruction fields, autocomplete remains active inside {{jsonata: ...}}. Choosing a workflow field inserts its plain JSONata path into the expression so you can combine it with operators or functions.

Native platform tools can expose richer output shapes than generic MCP metadata provides. For Salesforce MCP related-record actions, the editor uses the selected Salesforce integration's describe metadata to identify the related object and offer record fields such as get_related_data.records.Subject or get_related_data.records[0].Description in merge-field and JSONata autocomplete.

Testing a workflow¶

Open Preview and fill in the visual input fields. Objects and lists use nested field and item controls, including when no schema is declared; JSON is optional. See Testing workflow inputs visually. The graph animates as each node executes. Each node's Input panel shows merge fields resolved to the values used for that run, followed by the node output and any errors. The configured End output parameter values appear below the node details.

Use Saved test inputs to store named payloads for repeat checks. Saved inputs belong to the workflow and are shared with other users in the tenant. Choose one from the list to load it into the tester, or enter a name and click Save to save the current visual/JSON payload.

The workflow's Execution history includes every way the workflow can run: tests, manual runs, triggers, schedules, nested workflow calls, and workflows attached to an agent's conversation start. Open a run to inspect its resolved node inputs, outputs, duration, and errors.

Test runs are isolated from production. They do not consume queue capacity and do not fire downstream notifications by default. Toggle Allow side effects in the test dialog if you want notifications or external writes during a test.

Publishing¶

Like agents, workflows have draft and published states. Drafts do not run on real triggers. Click Publish to make a workflow live.

The version menu identifies the current draft and each immutable published version. A newly created or migration-replaced draft starts from the current published graph; later edits can make it differ intentionally. Opening a published-version URL always shows that published snapshot, not the editable draft.

Opening a workflow from the repository or an unversioned link opens its draft when one exists, including when the workflow also has a published version. Without a draft, it opens the current published version. Use the version menu to inspect a specific published snapshot.

Warning: Publishing a workflow that's already triggered by an external system (webhook URL, Salesforce channel) starts running it on real events. If your draft has a bug, the bug runs in production.

See also¶

• Triggers
• Workflow node types
• Pipeline editor
• Adding an integration