> For the complete documentation index, see [llms.txt](https://docs.valtimo.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.valtimo.nl/configuration-guides/building-blocks/form-flows.md).

# Form flows

Form flows are multi-step form wizards that guide users through a sequence of forms. They enable complex data collection by chaining multiple forms together, with support for conditional navigation, branching logic, and step transitions.

In the context of building blocks, form flows allow you to package reusable wizard-style interactions that can be linked to user tasks in BPMN processes.

Form flows of a building block are edited in the same form flow editor as case form flows, with a **JSON editor** tab (the default) and a visual **Editor (beta)** tab. The **Form** dropdown of a step lists the forms of the building block. See the [form flow editor documentation](/configuration-guides/cases/form-flows.md#editing-in-the-json-editor) for how to configure steps, transitions and actions.

***

## Configuring form flows

{% stepper %}
{% step %}
Navigate to **Admin** > **Building blocks** and select a building block
{% endstep %}

{% step %}
Click the **Form flows** tab

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-521c90579afb98a70dfe0aa1e89b98894bbb18fb%2F01-form-flows-tab.png?alt=media" alt=""><figcaption><p>Form flows tab showing the list of form flows</p></figcaption></figure>
{% endstep %}
{% endstepper %}

The form flows list displays all form flows defined within this building block:

| Column    | Description                                      |
| --------- | ------------------------------------------------ |
| Key       | Unique identifier for the form flow              |
| Version   | Current version number (or `-` if not versioned) |
| Read only | Whether the form flow can be edited              |

### Adding a form flow

{% stepper %}
{% step %}
Click **Create new form flow**
{% endstep %}

{% step %}
Enter a unique key for the form flow

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-d9333ba195d55aa1d0f50bb386902a8afcf1a96b%2F02-create-modal.png?alt=media" alt=""><figcaption><p>Create new form flow modal</p></figcaption></figure>
{% endstep %}

{% step %}
Click **Create** to open the JSON editor
{% endstep %}
{% endstepper %}

| Property | Description                                                                                                       |
| -------- | ----------------------------------------------------------------------------------------------------------------- |
| Key      | Unique identifier for the form flow within this building block. Use lowercase with hyphens (e.g., `my-form-flow`) |

### Editing a form flow

Click on a form flow row to open the form flow editor, which opens on the JSON editor tab. The editor provides syntax highlighting and validation against the form flow JSON schema.

<figure><img src="https://3330064618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq5dx9HWFJGshztp4binE%2Fuploads%2Fgit-blob-edc56f96c783995c28d68057068ca354c0b41ad5%2F03-form-flow-editor.png?alt=media" alt=""><figcaption><p>Form flow JSON editor</p></figcaption></figure>

Form flows are defined in JSON with the following structure:

| Property    | Description                                  |
| ----------- | -------------------------------------------- |
| `key`       | Unique identifier matching the form flow key |
| `startStep` | Key of the first step to display             |
| `steps`     | Array of step definitions                    |

Each step contains:

| Property     | Description                                              |
| ------------ | -------------------------------------------------------- |
| `key`        | Unique step identifier                                   |
| `type`       | Step type configuration (e.g., `form` to display a form) |
| `onComplete` | Array of expressions to execute when the step completes  |

### Deleting a form flow

{% stepper %}
{% step %}
Click the overflow menu (three dots) on the form flow row
{% endstep %}

{% step %}
Select **Delete**
{% endstep %}

{% step %}
Confirm the deletion in the dialog
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Form flows marked as read-only cannot be deleted.
{% endhint %}

***

## Form flow scope

Form flows in a building block can reference forms defined within the same building block.