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

# Building a workflow

> Describe a process, let the builder turn it into steps, then refine, test and publish it.

You build a workflow by describing a process in plain language. The builder turns your description into steps, inputs and outputs. You then refine it by asking for changes or by editing the steps yourself, and publish it so others can run it.

> [!NOTE]
>
> **Who:** Admins and Members · \*\*Where:\*\***Workflows** › **Build a workflow** · **Works on:** Enterprise and SaaS (on SaaS Free, agents and workflows together are limited to 3)

## Build your first workflow

**1. Open the builder**

Go to **Workflows** and click **Build a workflow**. The page **What do you want to build?** opens with **Workflow** selected.

**2. Describe the process**

Write what the process starts from, the checks or approvals along the way, and what it should hand back. For example: "Score a card transaction for fraud, hold it above 60, ask a Fraud Analyst to approve the hold, then draft the customer SMS." The description needs at least 10 characters.

If the process follows the rules of an agent you can open, name the agent as it is called, for example "built on the Adverse Media Screening 1.2 agent". The builder reads that agent's instructions and guardrails and applies its rules to the steps, and the build report says **Read the agent**. You can also ask for an agent to do a step, such as "read the pages with an agent using the browser": the builder adds an **Agent Task** step with the tools it needs.

**3. Build**

Click **Build**. Building usually takes about a minute, and the page shows its progress.

**4. Review and refine**

The **Builder** pane on the left holds the conversation, and the workflow appears on the right. The builder lists **Inputs your workflow will ask for** and suggests changes you can click. Type more changes in the box (**Describe changes to your workflow…**), or edit the steps directly (see [Edit steps](#edit-steps)).

![The builder after building the card fraud example: the Builder pane with the request, the Inputs your workflow will ask for list and suggested changes, the steps on the right, and Save & publish at the top right.](https://mintcdn.com/neuralfactory/y-MI7aIFykaw0cY2/images/app/workflow-builder-create.png?fit=max\&auto=format\&n=y-MI7aIFykaw0cY2\&q=85\&s=7bdfc847e7ca235f9fbc2b39e91888c7)

**5. Save**

Click **Save & publish**, or open its menu and choose **Save as draft**. Saving is disabled while the workflow has issues to fix. After saving, **Run it** (published) or **Open it** (draft) takes you to the workflow page.

A saved workflow is **Private**. Only you and your organization's admins can see it until you share it under **More actions** › **Settings & sharing** (see [Share a workflow](https://docs.neuralfactory.ai/user-guide/workflows/overview.md#share-a-workflow)).

> [!TIP]
>
> You can choose **Let the builder decide** instead of **Workflow**. If your description reads like a workflow, the builder says **This reads like a workflow** and offers **Build it as a workflow** or **Build an agent anyway**.

Below the description box, **From the catalogue** shows ready-made use cases that build a workflow, and **Browse all** opens the full list. When you have no workflows yet, the empty Workflows page also offers **Start from the catalogue**. See [Catalogue](https://docs.neuralfactory.ai/user-guide/catalogue/overview.md).

## The workflow page

Open a workflow from the list to edit and run it. If you are its owner or an admin, the page has three parts.

* The header: the name, the state (**Draft r5** or **Published r3**), the revision picker, **Save** (when you have unsaved changes), **Publish**, **Run** and **More actions**.
* The **Builder** pane on the left, where you ask for changes in plain language. You can collapse it.
* The canvas, with three tabs: **Steps** (the steps as cards), **Map** (the same steps as a diagram, coloured by the selected run once there is one) and **Runs** (see [Running a workflow](https://docs.neuralfactory.ai/user-guide/workflows/running-a-workflow.md#run-from-the-workflow-page)).

Above the steps, a summary line shows the number of steps and approvals, the model the workflow **Runs on**, and when it was last edited. Choose **Default model** or a specific model in **Runs on**. Steps that do not pick their own model use this one, and a change you ask the builder for keeps your choice.

## Ask the builder for a change

Describe the change in the **Builder** pane. The builder drafts it as a proposal: the canvas highlights what would be added, changed or removed, and the header shows **· proposal pending**. Click **Accept** to apply and save it, or **Discard** to keep what you had. While a proposal is pending, you cannot edit steps or run the workflow.

**More actions** › **Undo last change** brings back the workflow as it was before the last accepted proposal. It comes back as a proposal, which you accept or discard.

## Fix issues

When the workflow has problems that would stop it from running, a banner says how many things need a quick fix and lists them. Click **Fix it for me** to let the builder fix them, or **Technical details** to see the exact messages. A workflow with issues cannot be saved or run.

## Edit steps

On the **Steps** tab:

* **Add step** opens **Add a step**. Pick the **Step type**, give it a **Name**, and choose which steps it **Runs after** (optional). Configure the details afterwards on the step card.
* The pencil on a step card opens **Edit Step**. The step's menu offers **Insert after**, **Duplicate**, **Move up**, **Move down** and **Delete step**.
* **Schemas** opens **Inputs and outputs** (see [Inputs and outputs](#inputs-and-outputs)).

Your edits are stored only when you click **Save** in the header. Leaving the page with unsaved edits asks you to confirm. If someone else saved the workflow while you were editing, your save is refused with **Someone else changed this workflow**. Choose **Keep my edits** or **Reload their version**.

Steps can use the run's inputs and the outputs of earlier steps through `{{ }}` templates, for example `{{ input.case_id }}`.

## Test and publish

Every save that changes the steps, the inputs or the outputs creates a new numbered revision (r1, r2, ...). Changing the name, description or sharing does not. One revision at a time is published. That is the one that runs from **New task**, from schedules by default, and for everyone the workflow is shared with.

**1. Test the draft**

Choose **More actions** › **Test run (draft)**. It runs your latest saved revision without publishing it.

**2. Publish**

Save your changes first, then click **Publish** in the header. The **Publish revision** dialog takes an optional **Review note** ("What was reviewed, and by whom?"), which is recorded on the audit trail.

To run or republish an older revision, pick it in the revision picker in the header. Each entry shows its date, author and number of steps. **Run** then runs that revision, and **Publish r2** makes it the published one again.

**More actions** › **Version history** lists every revision with when and by whom it was published and the review note. You can compare two revisions to see which steps were added, removed or changed, and **Restore** an earlier revision as a new draft. Restoring does not change what is published.

A run always uses the revision it started with, even if you edit or publish while it runs or waits for an approval.

## Step types

| Step type | What it does |
| - | - |
| **LLM Task** | Asks a model to produce text or structured fields from a **Prompt Template**. |
| **Tool Action** | Calls a tool or integration and maps its output. |
| **Code** | Runs Python code and returns what it prints as JSON. |
| **Agent Task** | Gives one open-ended **Task** to a bounded agent. |
| **Sub-workflow** | Runs another workflow inside this run. |
| **Condition** | Sends the run down one branch or another, based on an expression. |
| **Validation** | Checks values against rules before the workflow continues. |
| **Approval** | Pauses the run until a person approves or rejects (see [Approval steps](#approval-steps)). |
| **Parallel** | Runs several sub-steps at the same time. |
| **Loop** | Repeats a sub-step for each item of a list. |

**Approval** and **Condition** steps cannot be placed inside a **Parallel** or **Loop** step. **Parallel** and **Loop** cannot be nested.

> [accordion] LLM Task
>
> Write the **Prompt Template**. You can choose its **Model** (**Default (workflow model)** uses the model in **Runs on**) and its **Temperature**, or **Reasoning Effort** for a reasoning model. **Time limit** is how long the model has to answer, 180 seconds by default.

> [accordion] Tool Action
>
> Pick the **Tool**, give its arguments under **Tool Config (JSON)**, and map result fields with **Output Mapping**. For a knowledge-search tool you pick **Knowledge Bases** instead. Mark it **Idempotent** when calling it twice has the same effect as calling it once. **Time limit**, under **Advanced**, is how long the call may take, at most 3600 seconds. Left empty, the tool's own limit applies, or 180 seconds when it has none.

> [accordion] Code
>
> The code runs in the sandbox, a separate space set aside for running code. Code the sandbox does not allow fails with a message that starts with "Security error", for example "Security error: Import of blacklisted module '...' is not allowed". **Time limit** is how long the code may run, 180 seconds by default.

> [accordion] Agent Task
>
> Write the **Task** and choose the **Model** (**Default (workflow model)** or a named model). Then choose the **Tools the agent may use** (none means reasoning only), **Max Iterations** (1 to 25), **Time limit** (600 seconds by default, at most 1800) and, optionally, the **Output Fields** it must return.

> [accordion] Sub-workflow
>
> Pick the **Workflow**, its **Revision** (by default the one published when the run starts), the **Input Mapping** and a **Time limit** (600 seconds by default, at most 7200). The other workflow must be published, not archived, and contain no approval steps.

> [accordion] Condition
>
> Write the **Condition Expression**, then choose under **Branch Targets** the step each outcome goes to.

> [accordion] Loop
>
> Choose the list to go through (**Collection**). The loop stops at **Max Iterations**, 100 by default.

## Settings every step has

**Edit Step** also has these sections, whatever the step type.

| Section | What you set |
| - | - |
| **Dependencies** | The steps this one runs after. |
| **Governance** | **Sensitivity**: **Normal**, or the audited option that starts with **Sensitive**, which records each execution of a tool step in the security audit log. **Allowed Tools**: when set, the step may call only these tools, and any other call fails. |
| **Validation Rules** | Checks on the step's output after it runs, such as **Must not be empty**, **Must be a number** or **Must match a pattern**, each with an optional **Failure message**. |
| **Error Handling** | **On Error** (**Fail**, **Skip** or **Continue**), **Max Retries** (0 to 10), **Retry Delay (ms)**, **Retry Backoff** (**Exponential**, **Linear** or **Constant**) and a **Fallback Step** to run when the step still fails after its retries. |

## Inputs and outputs

**Schemas** opens the **Inputs and outputs** panel: what a run asks for, and what it hands back. For each field you set a name, a type, whether it is required, and a description in the words of the person filling it in. Inputs can also have a default value.

| Type | What the run form shows |
| - | - |
| **Text** | A text box (multi-line for longer text) |
| **Number**, **Whole number** | A number box |
| **Yes / no** | An on/off control |
| **Date** | A date field |
| **Date range** | A start and an end date |
| **File** | A file drop zone |
| **List** | One item per line |
| **Object** | A group of fields |

Click **Save schemas**, then **Save** in the header. The run form on **New task** and on the workflow page is built from these inputs (see [Running a workflow](https://docs.neuralfactory.ai/user-guide/workflows/running-a-workflow.md)).

## Approval steps

An **Approval** step pauses the run until someone approves or rejects it.

| Setting | What it does |
| - | - |
| **Prompt** | What the approver is asked. It can include values from the run, for example `{{ steps.draft.output.result }}`. The approver sees it above the request details, in the **Inbox** and on the run page. |
| **Approver Role** | Who may decide. A person matches when their platform role (for example Admin) or the name of one of their groups equals this text. |
| **Approver Groups** | Only members of these groups may decide. Leave it empty, with no **Approver Role**, to let anyone who can see the workflow decide. |
| **Allow self-approval (governance exception)** | Off by default: the person who started the run cannot decide its approval, admins included (four-eyes). Turning it on lets them approve their own request. |
| **Timeout (hours)** | How long the request waits. 24 by default. |
| **On Timeout** | What happens when nobody decides in time: **Auto-reject** (default) or **Auto-approve**. |
| **Notification Channels** | Email addresses to notify when the request opens, separated by commas. Other entries are ignored. Emails are sent only when your installation has email set up. |
| **On Approved → Step** | The step to go to after an approval. Empty continues to the next step. |
| **On Rejected → Step** | The step to go to after a rejection. Empty stops the workflow. |

Admins match any approver role or group, but the four-eyes rule still applies to them. Viewers cannot decide approvals. For how a request reaches approvers and how they decide, see [Decide an approval](https://docs.neuralfactory.ai/user-guide/workflows/running-a-workflow.md#decide-an-approval).

## More actions

**More actions** on the workflow page also holds:

* **Overview**: a plain-language summary of what the workflow asks for, what it does and the checks around it, with a **Print** button.
* **Schedule automatic runs**: see [Schedule a workflow](https://docs.neuralfactory.ai/user-guide/workflows/running-a-workflow.md#schedule-a-workflow).
* **Run analytics**: total runs, success rate, typical and slow durations, runs by status and by how they were started, tokens and cost, and the recent runs.
* **Settings & sharing** (**Settings** on a personal account): **Name**, **Description**, **Run retention (days)**, **Data classification** (**Unclassified**, **Internal**, **Confidential**, **Restricted**) and **Visibility**.

Only the owner and admins see **Test run (draft)**, **Undo last change**, **Schedule automatic runs**, **Version history** and the settings. Everyone who can open the workflow sees **Overview** and **Run analytics**.

## Limits and problems

> [accordion] Workflow limits (Enterprise and SaaS)
>
> * **Enterprise**: no limit on the number of workflows.
> * **SaaS**: on the Free plan, agents and workflows together are limited to 3. Creating or duplicating a workflow past the limit is refused with the reason, and **Build a workflow** is disabled. See [Plans and limits](https://docs.neuralfactory.ai/user-guide/admin/billing.md).

> [accordion] The build takes a long time
>
> Most builds finish in about a minute. A large workflow can take longer: the page waits up to 30 minutes for the build before it gives up.

> [accordion] The request did not reach Neural Factory
>
> If building, saving or changing a workflow shows "The request did not reach Neural Factory: a gateway or firewall in front of it answered instead. Please contact your administrator.", a gateway or firewall in your network answered in place of the app. Your IT administrator needs to look at it.

## Related

* [Workflows overview](https://docs.neuralfactory.ai/user-guide/workflows/overview.md)
* [Running a workflow](https://docs.neuralfactory.ai/user-guide/workflows/running-a-workflow.md)
* [Build your first workflow](https://docs.neuralfactory.ai/user-guide/guides/first-workflow.md)
* [Agents and workflows](https://docs.neuralfactory.ai/user-guide/concepts/agents-and-workflows.md)


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