> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an Agentic Workflow

> Build a workflow in the canvas: pick a trigger, add steps and If Blocks, pass data with variables, then save, activate and restore versions.

Build a workflow on a canvas: one trigger at the top, then the steps and conditions that run after it. This page walks through the editor from an empty canvas to an active version.

> [!NOTE]
>
> **Agentic Workflows → New workflow** in your [OpenCX dashboard](https://platform.open.cx/workflows/new). Requires the **Workflows** permission (Write).

## Create a workflow

**1. Open a new workflow**

In [Agentic Workflows](https://platform.open.cx/workflows), click **New workflow**. The workflow is named **Untitled Workflow** until you rename it: click the name at the top left, enter a new name and click **Rename**.

**2. Build it with Companion, or build it yourself**

An empty canvas shows **Build it with Companion**. Describe what should happen, for example "Escalate angry customers to a human", and Companion adds the trigger, conditions and steps for you. Click **or build it yourself** to start from a blank canvas. Once the workflow has steps, ask Companion for changes from the bar at the bottom (**Ask Companion to edit this workflow…**, or press **alt+Space**). Check every step Companion adds before you activate the workflow.

**3. Save the first version**

A new workflow exists only in your browser until you click **Save**. After the first save, every edit autosaves to your draft.

## Pick a trigger

Click **Add a trigger** on the empty canvas, or the **+** button at the top left (shortcut **A**). The picker lists **TRIGGERS**, **ACTIONS**, **BLOCKS** and **MISC**; search by name. A workflow has exactly one trigger.

Click the trigger on the canvas to configure it in the side panel. Most session triggers can be narrowed before they start a run:

| Setting | What it does |
| - | - |
| **Channels** | Only run for sessions on these channels. Empty runs on every channel. |
| **Directions** | Only run for inbound or outbound sessions. Empty runs for both. |
| **Statuses** | Only run for sessions in these statuses. Empty runs for any status. |
| **Run Synchronously** | Wait for this workflow to finish before continuing. Use it when later work depends on what this workflow does. |

Some triggers add their own settings, such as **Inactive For** and **Unit** on **Customer Inactive**, **Cron Expression** on **Cron Trigger**, or **The Goal of the Workflow** on **AI Trigger**. See [Triggers and steps](https://docs.open.cx/workflows/triggers-and-steps.md) for each one.

## Add steps

You can add a step three ways:

* Drag from the output handle of a step or trigger. A menu opens with **BLOCKS** and **ACTIONS**; pick one and it's connected for you.
* Hover a connection between two steps and click **Insert step** to put a step in between. **Remove** deletes the connection.
* Use the **+** button and connect the new step yourself.

The picker only lists steps that work with your trigger. For example, the Classical IVR steps appear only for an **IVR Incoming Call** workflow.

Click a step to fill in its inputs in the side panel. Right-click a step for **Rename**, **Configure**, **Copy step ID** and **Delete**. Renaming changes the title on the canvas, not the step ID that variables use.

Add a **Note** (under **MISC**) to leave yourself a comment on the canvas. Notes never run.

## Branch with an If Block

An **If Block** checks a condition and sends the run down its true path or its false path. Steps on the other path don't run.

**1. Add the block**

Add **If Block** from **BLOCKS** and connect it after the step whose data it checks.

**2. Write the condition**

Click **Add** and choose **Condition**, **AND Group**, **OR Group** or **NOT Group**. For a condition, pick the value to check (usually a variable), an operator and, if the operator needs one, a value to compare with.

**3. Connect both paths**

Connect steps to the true and false handles. Leave a path empty to end the run there.

The operators offered depend on the type of the value you check. They include **Equals**, **Not Equals**, **Contains**, **Starts With**, **Ends With**, **Greater Than**, **Less Than** (and their **or Equal** forms), **Is Null**, **Is Not Null**, **Is True**, **Is False**, **Is Email**, **Is URL**, **Array Contains**, **Array Is Empty** and **Array Is Not Empty**.

## Pause a run with Wait

The **Wait** step pauses the run for an **Amount** of **Seconds**, **Minutes**, **Hours** or **Days**, up to 30 days in total. While it waits, the run shows as **Waiting** in the **Runs** tab with the time it picks up again, and you can cancel it there.

## Pass data between steps with variables

Any step input that accepts a variable shows a braces button (**Insert variable**). Click it, or type `{{` in the field, to pick a value. The picker shows the type the input expects and flags values of the wrong type.

A variable is a path in double braces. The first part names where the value comes from:

| Source | Example | What it holds |
| - | - | - |
| `trigger` | `{{trigger.ticketNumber}}` | The trigger's data. The fields depend on the trigger: on **Manual Ticket Trigger** the session is under `trigger.ticket`, so the number is `{{trigger.ticket.ticketNumber}}`. |
| A step ID | `{{ask_ai.result.category}}` | The output of an earlier step. |
| `metadata` | `{{metadata.today}}` | The current date (yyyy-MM-dd), time and timezone. |
| `variables` | `{{variables.API_KEY}}` | Your workspace [global variables](https://docs.open.cx/actions/authentication.md#global-variables). |
| `secrets` | `{{secrets.MY_SECRET}}` | Your workspace secrets, by name. |
| `structuredFields` | `{{structuredFields.plan}}` | Your [structured fields](https://platform.open.cx/settings/structured-fields). |
| `routingSkills` | `{{routingSkills}}` | All your skills (name and description) as text, for skill-aware AI prompts. |

`run`, `workflow` and `organization` hold details about the current run, the workflow and your workspace.

A step can only use the trigger and the steps that run before it on the same path. A step's ID is set when you add it, from the step type: the first **Ask AI** step is `ask_ai`, the second `ask_ai_1`. Right-click a step and choose **Copy step ID** to get it.

To keep a value for later steps under a name you choose, add **Hold Variable**. To translate one value into another (for example a country code into a team), use **Map Lookup**.

## Fix validation issues

**Save** and **Activate** both check the workflow first. If something is wrong, the **Validation Issues Found** dialog lists each issue; click **Fix** to jump to the step. Steps with problems also show a warning badge on the canvas; hover it to see why.

| Message | What to do |
| - | - |
| Missing trigger - Workflow must have at least one trigger to start execution | Add a trigger. |
| Multiple triggers - Workflow should have only one trigger. Multiple triggers may cause conflicts. | Delete the extra trigger. This is a warning. |
| `<Step name>: "<Field>" is required` (for example `Tag Ticket: "Ticket Number" is required`) | Open that step or trigger and fill in the field. |

## Save, test and activate

**1. Save a version**

Click **Save** (tooltip: **Save the draft as a new version**). Your draft becomes the next version, such as v3. New versions start inactive.

**2. Test it**

With a saved version selected, click **Test** to run it once on data you choose. A test runs every step for real. See [Test and monitor workflows](https://docs.open.cx/workflows/test-and-monitor.md).

**3. Activate it**

Click **Activate** and confirm. This deactivates any other active version of the workflow. From now on the trigger starts real runs.

To stop a workflow, select its active version and click **Deactivate**.

> [!NOTE]
>
> **Test** and **Activate** need a saved version on screen. While you are looking at your draft, the editor shows **Save** instead.

## Version history and restoring a version

Every **Save** creates a version. Edits never change a saved version: they go to your draft, which is based on the version you were viewing.

* **Switch versions.** Use the version menu next to the workflow name. **Draft** appears when you have unsaved edits. The active version is marked **Active**.
* **See history.** Click the history icon (**Version history**) for every saved version, newest first, with who created it and when.
* **Restore an older version.** Select it in the version menu or history, then click **Activate**. To change it first, edit it, click **Save** to make a new version, then activate that.
* **Throw away your edits.** In the version menu, choose **Discard draft**. Your unsaved changes are deleted and the editor shows the version they were based on. This can't be undone.

When you reopen a workflow, the editor shows its active version. Pick **Draft** in the version menu to continue your edits.

## Duplicate or delete a workflow

In the [workflow list](https://platform.open.cx/workflows), hover a workflow and click **Duplicate workflow** or **Delete workflow**. A copy is marked **Cloned**. Deleting can't be undone.

***

## Related Documentation

> [card] [Test and monitor](https://docs.open.cx/workflows/test-and-monitor.md)
>
> Test runs, Runs tab, failures.

> [card] [Triggers and steps](https://docs.open.cx/workflows/triggers-and-steps.md)
>
> Every trigger and step, with requirements.

> [card] [Workflows overview](https://docs.open.cx/workflows/introduction.md)
>
> Life cycle and permissions.

> [card] [Global variables](https://docs.open.cx/actions/authentication.md)
>
> Shared credentials for steps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.