Setting up a flow

The Flow is defined by a JSON file. Name of the file can be anything, but flow.json is a recommended name. Format of the data inside must be either JSON or JSONC. The flow.json file will be picked up, loaded and exposed by the Forms module.

{
    "name": "demo",
    "public": false,
    "require_roles": [
        "role00"
    ],
    "enable_progressbar": false,
    "show_user_menu": true,
    "verbose_logs": [
        "flow",
        "session"
    ],
    "buttons": {
        "next_button": {
            "enabled": true,
            "text": "flow00.next_button"
        },
        "save_button": {
            "enabled": true,
            "text": "flow00.create_button"
        },
        "restart_button": {
            "enabled": true,
            "text": "flow00.restart_button"
        }
    },
    "steps": "@include:steps/*.json",
    "pre_pipe": "forms.flow00.pre_pipe",
    "pipe": "forms.flow00.finalize",
    "incomplete": "@include:incomplete.json",
    "summary": "@include:steps/summary.json"
}

Before step 1

Sometimes it is necessary to perform some kind of logic before first step is rendered. Typically used for validation and or collecting data reqired in step 1.

For case like this use pre_pipe.

In order to consume data in subsequent steps, make sure the pipe returns one item. Data in this item will be accessible using {{flow.xxx}}

How it is connected

In order for authentication to work, a SAML SP authenticator needs to be configured. Also, SAML SP need to share first part of URI in with Forms module.

Example

Forms module has "http_context" configured to "/forms". The SAML must have it's "http_context" set to "/forms/xxx" ("/forms/auth" is a good pattern).

Typically the properties regarding authentication in Forms module will look something like this:

On the SAML SP side configuration will look like this:

Once the user is authenticated data from incoming assertion vill be transfered to the session.

NameID vill be the users login identifier. Other attributes will be put in the session where multivalued attributes is merged into a comma separated list.

Filtering access to a Flow

Once authenticated all users by default can access a Flow. Restricting is based on roles attribute in the incoming assertion. By using the "requires_role" configuration parameter on the Flow restriction control is performed comparing the incoming "roles" in the assertion and data in "requires_role" for the Flow.

One value of "role" must match "requires_role" in order for user getting access.