> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simplified.com/mcp/workflows/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simplified.com/_mcp/server.

# Workflows

These operations require a connection that exposes `flows_` tools. [Check your inventory](/mcp/profiles-and-tool-inventory) before planning this workflow.

## Find and run a workflow

1. Use `flows_listWorkflows` and `flows_getWorkflow` to find a definition and inspect its inputs.
2. Gather the required inputs and select the teamspace.
3. Call `flows_startWorkflow` once.
4. Save the returned execution identifier.
5. Check `flows_getWorkflowRunStatus` until the execution reaches a terminal state.
6. Retrieve detailed results with `flows_getWorkflowRun`.

> Run our campaign-brief workflow for Acme using this product page. Monitor the existing run and return the final outputs or the failed step.

A workflow definition ID identifies the reusable workflow. A run ID identifies one execution. The start response may label the execution identifier `workflow_id`; preserve its value as the run ID for run-control tools. The `workflow_id` in run details refers to the definition.

## Understand run states

`COMPLETED`, `FAILED`, `TERMINATED`, and `TIMED_OUT` are terminal states. `RUNNING` and `PAUSED` are not completed results.

If your client disconnects, retrieve the existing run before starting another. Where supported, supply an `idempotency_key` on start requests to help avoid duplicate submissions.

## Control an execution

| Action    | Effect                                                  |
| --------- | ------------------------------------------------------- |
| Pause     | Requests a pause; in-flight work can finish first       |
| Resume    | Continues a paused execution                            |
| Retry     | Retries a failed execution from its failed work         |
| Restart   | Starts a terminal execution again from the beginning    |
| Terminate | Ends the execution; use only when you intend to stop it |

Restarting can repeat generation and other effects. Inspect the current status and error before choosing retry or restart.

## Handle an approval step

When a run is waiting for approval, inspect status with task expansion. Use the returned `reference_task_name` with `flows_approveWorkflowTask` and the supported approval outcome. Do not approve an arbitrary task or treat an assistant's text reply as a recorded workflow approval.

## Build or update a workflow

Discover supported actions through `flows_listWorkflowActions`. Create the definition with `flows_createWorkflow`, read it back, and use `flows_updateWorkflow` for revisions. Publish with `flows_publishWorkflow` when the definition is ready for use. Publishing validates the diagram and creates an executable version; saved edits are not used by new runs until published. If validation fails, fix the reported block before retrying. Keep definition editing, publication, and execution as separate steps so you can verify each result.

## Example: build a reusable campaign-brief workflow

Start with a small input/output contract: accept a product description and return a structured campaign brief. Add asset generation or publishing only after that first version works.

1. Discover candidate steps with `flows_listWorkflowActions`. Inspect each selected action's input schema and example output.
2. Create a draft with `flows_createWorkflow` and save the definition ID.
3. Build the diagram and save it through `flows_updateWorkflow`.
4. Read the definition back with `flows_getWorkflow` to verify the inputs, connections, and output mapping.
5. Publish with `flows_publishWorkflow`. Resolve any validation error before starting a run.
6. Start one execution with a small example input, monitor its run ID, and inspect the completed output.
7. Revise and republish the definition before testing a changed version.

## Map inputs and outputs correctly

The authoring payload uses `extra.diagram`; publication builds the executable representation. Each action block needs the action's discovered reference, its configured inputs, and connections to the next step.

Declare workflow input names in both `extra.inputs` and the start block's input schema. Declaring only the names can leave inputs unavailable at execution time. Map outputs using paths that actually exist in the selected action's example result.

When updating `extra`, preserve the complete configuration: this field is replaced as a whole. Read the current definition first so a small edit does not remove unrelated settings.

## Inspect a failed execution

Use `flows_listWorkflowRuns` to locate the execution, then read its status and details. Record the failed task, the error, and any outputs already produced. Resolve the cause before retrying; restarting from the beginning can repeat completed side effects.

For human approval, inspect the waiting task and its payload before recording an outcome. The approval tool accepts the documented completion/failure outcomes; a workflow pause and a waiting approval step are different states.

## Keep definition changes separate from run control

Editing or republishing a definition does not establish that an existing execution has changed or stopped. Inspect that execution and use the appropriate run-control tool. Delete a workflow definition only when removal is intended, not as a way to cancel one run.

## API reference

For request fields, response shapes, and direct HTTP integrations:

* [Workflow action discovery](/api-reference/workflows/authoring/list-workflow-actions)
* [Publish a definition](/api-reference/workflows/authoring/publish-workflow)
* [Run status and results](/api-reference/workflows/runs/get-workflow-run-status)

These endpoint pages describe REST requests. For MCP calls, use the current tool schema, including any additional convenience fields.

> Create automations and manage each execution deliberately.