Identity Selection

Identity Selection lets a user choose the identity or identities a Forms Flow will work with before its first Step is displayed. Configure it on the Flow when the same process should apply to different people, rather than building a separate Flow for each person.

When to use it

A help desk Flow can first ask which user to update, then show that user's details and perform the requested change. A bulk administration Flow can let an operator select several identities before applying the same action to all of them. In both cases, the Flow starts with a search and selection, so later Steps work with the intended identities.

Use selection: "single" for one identity or selection: "multi" for several. With prompt.controls, the user enters search criteria before the search runs. Without prompt controls, the search runs automatically when the Flow opens. Set max_results to a useful limit for the task and make sure the search can stay within it.

Identity Selection is part of the Flow, rather than a Control on a Step. The selection must be completed before pre_pipe or any Step runs. The selected identities remain fixed during the Flow; restarting the Flow clears the selection so the user can choose again.

Configure the Flow

Put identity_selection in the Flow configuration. For a larger Flow, keep the definition in a separate file beside flow.json, following the usual @include pattern:

flows/manage-user/flow.json:

{
  "name": "manage-user",
  "public": false,
  "identity_selection": "@include:identity_selection/identity_selection.json",
  "steps": "@include:steps/*.json"
}

flows/manage-user/identity_selection/identity_selection.json:

{
  "pipe_id": "forms.manage-user.search",
  "title": "Select identity",
  "selection": "single",
  "max_results": 20,
  "show_export_button": true,
  "display_property": "displayName",
  "columns": [
    { "key": "displayName", "label": "Display name" },
    { "key": "department", "label": "Department" }
  ],
  "prompt": {
    "title": "Search for an identity",
    "controls": [
      {
        "id": "name",
        "type": "Input",
        "data": "",
        "schema": { "type": "string", "title": "Name" }
      }
    ]
  }
}

Keep the search Pipe at flows/manage-user/identity_selection/pipe.json, beside identity_selection.json. This is the file layout used by Management Center. Give the Pipe the same ID as pipe_id and ensure the Pipes module loads it. For example, when config/modules/pipes.json and config/flows/ are sibling paths, add the Identity Selection pattern to the existing config.pipes include list:

{
  "name": "Pipes",
  "config": {
    "pipes": "@include_as_array:../flows/*/pipes/*.json,../flows/*/identity_selection/pipe.json"
  }
}

Keep other existing Pipe patterns in that list. If Flows are stored under config/modules/flows/, use flows/*/identity_selection/pipe.json instead.

For a local demonstration, flows/manage-user/identity_selection/pipe.json can use the same scaffold search Valve that Management Center creates:

{
  "id": "forms.manage-user.search",
  "config": {
    "valves": [
      {
        "name": "IdentitySelectionScaffoldSearch",
        "config": {
          "filter_property": "displayName",
          "request_field": "name",
          "candidates": [
            {
              "id": "demo-user-1",
              "properties": {
                "displayName": "Ada Lovelace",
                "department": "Engineering"
              }
            },
            {
              "id": "demo-user-2",
              "properties": {
                "displayName": "Grace Hopper",
                "department": "Engineering"
              }
            }
          ]
        }
      }
    ]
  }
}

Replace the scaffold search with a Pipe that queries the relevant identity source before using the Flow in production.

The search Pipe receives the prompt values by their control IDs, such as name above. It also receives columns as a comma-separated list, max_results as the configured limit plus one, and timeout_ms as the server-controlled execution timeout. Return selectable items with a non-empty string id and a properties object containing the configured display columns. The Pipe may also return total, the number of matches before limiting the result set. For example:

{
  "items": [
    {
      "id": "demo-user-1",
      "properties": {
        "displayName": "Ada Lovelace",
        "department": "Engineering"
      }
    }
  ],
  "total": 1
}

Only configured column values and temporary selection keys are sent to the browser. The full selected items stay on the server and are passed to pre_pipe, when configured, and Step Pipes. The selected display values can be used in later configuration as ${flow.identity.displayName} for a single selection or ${flow.identities.0.displayName} for the first item in a multiple selection. See Flow data and Step Pipes for how Flow values are used across Steps.

Set show_export_button to true when the user should be able to download the current result view as CSV. The export contains the configured result columns in their displayed order and the rows that remain after filtering and sorting. Internal selection keys and other properties are excluded. Multivalue attributes are written into one CSV cell, and the file uses UTF-8 with a byte order mark for spreadsheet compatibility.

Caution

CSV export writes the displayed identity data to the user's device. Enable it only for users and Flows where local handling of that data is permitted.

Configuration properties

Property	Description	Default	Mandatory
pipe_id	ID of the registered search Pipe	N/A	Yes
columns	At least one unique display column; use a key string or an object with key and optional label	N/A	Yes
selection	single or multi	single	No
max_results	Maximum number of results the user can select from; must be positive	200	No
timeout_ms	Search Pipe execution timeout in whole milliseconds, from 1 to 21,600,000	30000	No
title	Heading of the selection view	Empty	No
display_property	Display field; must match a configured column key	Empty	No
allow_filter	Allow filtering of the displayed results	true	No
show_total	Show the total when the search Pipe returns total	true	No
show_export_button	Allow the user to export the filtered and sorted result rows to CSV	false	No
sort_priority	Column keys used for result sorting priority	[]	No
prompt.title	Heading of the search criteria form	Empty	No
prompt.controls	Controls that collect search criteria; omit or leave empty for automatic search	[]	No

Prompt controls use ordinary Forms Control configuration and need unique, non-empty IDs. A column object can also specify presentation with one type: text, avatar, or badge.

An empty result set leaves the user at Identity Selection. When the result count exceeds max_results, the results cannot be selected. In prompt mode, the user can enter narrower criteria and search again. In automatic mode, adjust the search Pipe or the configured limit. A missing or failing search Pipe prevents the selection from completing; make sure pipe_id refers to a registered Pipe and that its result follows the item format above.