Flow

Configuration reference for defining a Forms Flow and its runtime behavior.

A Flow defines the user journey in Forms. It controls which Steps are included, how the Flow is reached, whether authentication is required, and which supporting pages or notifications are shown when the Flow completes or fails.

Flow configuration

A Flow is defined in a JSON or JSONC file. The file can have any name, but flow.json is recommended because it makes the configuration easy to identify.

The Forms module loads the Flow configuration and exposes it through the configured Forms endpoint. The name property becomes the last part of the Flow URL and must be unique within the Forms module.

Properties
Example

Name	Description	Default	Mandatory
`name`	Last part of the Flow URL. Must be unique within the Forms module	N/A	Yes
`public`	Allow access without authentication	`false`	No
`hide_in_launchpad`	Hide the Flow from Launchpad navigation while keeping direct Flow access unchanged	`false`	No
`requires_any_role`	User must have at least one of the listed roles to access the Flow	N/A	No
`requires_all_roles`	User must have all listed roles to access the Flow	N/A	No
`enable_progressbar`	Show the progress bar	`true`	No
`show_user_menu`	Show the user menu	`true`	No
`verbose_logs`	Additional logging for selected runtime areas, such as `flow` or `session`	`[]`	No
`steps`	Steps included in the Flow. `@include` is recommended for larger Flows	`[]`	Yes
`pre_pipe`	Pipe executed before the first Step is displayed	N/A	No
`identity_selection`	Require an identity selection before the first Step; see Identity Selection	N/A	No
`summary`	Summary Step shown after the last regular Step completes successfully	N/A	No
`incomplete`	Step shown when the Flow cannot continue after a Pipe failure	N/A	No
`retry_notification`	Notification dialog shown when a Step fails and the user may retry	N/A	No
`input_jwt`	Incoming JWT configuration for Flows started by another application	N/A	No
`output_jwt`	Outgoing JWT configuration for returning control to another application	N/A	No
`buttons.next_button.enabled`	Show the Next button	`true`	No
`buttons.next_button.text`	Translation key or text for the Next button	`Next`	No
`buttons.save_button.enabled`	Show the Save button	`true`	No
`buttons.save_button.text`	Translation key or text for the Save button	`Save`	No
`buttons.restart_button.enabled`	Show the Restart button	`true`	No
`buttons.restart_button.text`	Translation key or text for the Restart button	`Restart`	No
`buttons.proceed_button.enabled`	Show the Proceed button	`false`	No
`buttons.proceed_button.text`	Translation key or text for the Proceed button	`forms.step.proceed`	No
`buttons.proceed_button.reset`	Reset Flow data after clicking the Proceed button	`false`	No
`buttons.proceed_button.url`	URL opened when the Proceed button is clicked	N/A	Yes, when `proceed_button` is enabled
`buttons.proceed_button.logout`	Log out the user when the Proceed button is clicked	`false`	No
`buttons.proceed_button.open_in_new_tab`	Open the URL in a new browser tab	`false`	No

{
  "name": "manage-my-groups",
  "public": false,
  "hide_in_launchpad": false,
  "requires_any_role": [
    "group-owner",
    "service-desk"
  ],
  "enable_progressbar": true,
  "show_user_menu": true,
  "verbose_logs": [
    "flow",
    "session"
  ],
  "buttons": {
    "next_button": {
      "enabled": true,
      "text": "forms.manage_my_groups.next"
    },
    "save_button": {
      "enabled": true,
      "text": "forms.manage_my_groups.save"
    },
    "restart_button": {
      "enabled": true,
      "text": "forms.manage_my_groups.restart"
    },
    "proceed_button": {
      "enabled": true,
      "logout": false,
      "reset": true,
      "open_in_new_tab": false,
      "url": "/launchpad",
      "text": "forms.manage_my_groups.proceed"
    }
  },
  "steps": "@include:steps/*.json",
  "pre_pipe": "forms.manage_my_groups.prepare",
  "summary": "@include:steps/summary.json",
  "incomplete": "@include:incomplete.json",
  "retry_notification": "@include:retry-notification.json"
}

Before the first Step

Use pre_pipe when the Flow needs to prepare data before the first Step is displayed. Typical examples include validating incoming data, loading user context, or collecting data needed by Controls on the first Step.

When Identity Selection is configured, the user completes the selection before pre_pipe runs. The selected item or items are then available to the Pipe.

The Pipe response must be a single, flat key/value object. Returned values are added to the accumulated Flow State and can be referenced later with expressions such as {{flow.displayName}} or ${flow.mail}.

Final actions

Each Step can have its own Step Pipe. If work needs to happen at the end of the Flow, put that logic in the Step Pipe for the final regular Step. The Summary Step should be used for user feedback after successful completion, not for business logic.

For more information about how data is accumulated and passed to Step Pipes, see Flow data and Step Pipes.

In this section