Roles

Roles define who participates in a workflow and what they can do. Instead of assigning specific people to stages, you create abstract roles — like "Submitter," "Reviewer," or "Approver" — and assign those roles to stages. When a session starts, you assign real people to the roles.

This separation makes workflows reusable. The same approval workflow works whether Alice or Bob is the approver this time. The workflow design stays the same; only the casting changes.

Creating Roles

Every workflow starts with a default "Guest" role. You can create additional roles in the Roles panel on the left side of the builder.

To create a new role:

1. Click the + button in the Roles panel
2. Give the role a name — choose something that describes the participant's function (e.g., "Reviewer," "Manager," "Client")
3. Add a description — this is shown to participants so they understand their responsibilities
4. Choose a colour — each role gets a colour that appears throughout the session interface, making it easy to see which role is responsible for each stage

Roles are workflow-level — they apply across all stages and sessions of that workflow.

Assigning Roles to Stages

Once you've created roles, you need to assign them to stages. This tells the workflow engine which roles participate at each step.

To assign a role to a stage:

1. Select a stage on the builder canvas
2. In the stage settings, add the roles that should participate at this stage

A stage can have multiple roles assigned. For example, a "Review" stage might have both a "Reviewer" role (who provides feedback) and a "Submitter" role (who can see the review but not edit).

Stage permissions

Each role assignment on a stage comes with two permission flags:

These permissions combine to support common patterns:

Session Admin

Any role can be configured as a session admin by enabling the session admin flag in the role settings. Session admins have elevated access within sessions:

• View any stage — even stages they aren't assigned to
• Stage admin actions — rewind, reopen completed stages, force-complete stages, and nudge assignees
• Session management — assign roles, archive sessions, reopen completed sessions

This is useful for facilitators, coordinators, or team leads who need to oversee and intervene in running sessions without being directly assigned to every stage.

See Managing Sessions for details on the available admin actions.

Assigning People to Roles

When a session starts, real people need to be assigned to the workflow's roles. This happens in two ways:

Manual assignment

When starting a session from the builder or via the Operator view, you assign workspace members to each role. For example, "Alice is the Submitter, Bob is the Reviewer, Carol is the Approver."

Each role can have one or more people assigned. Multiple people in the same role means they all get access to that role's stages — useful for review panels or collaborative stages.

Self-service start links

Start links let people begin sessions without workspace membership. When creating a start link, you configure role assignments:

• Self-service user — whoever clicks the link is automatically assigned to this role. Use this for the role that the external participant will fill (e.g., "Applicant," "Client").
• Specific member — pre-assign a workspace member to a role. Use this for internal roles that should always go to the same person (e.g., "HR Coordinator").

The self-service user must be assigned to a role that includes the workflow's starting stage — otherwise they won't be able to begin.

Mid-session assignment changes

Session admins can change role assignments during a running session via the Assign Roles option in the session menu. This is useful when:

• A participant is unavailable and someone else needs to take over
• A new team member needs to join a session in progress
• A role was accidentally left unassigned at session start

Adding someone to a role gives them access to any currently active stages assigned to that role.

Multi-Role Workflows

Roles become powerful when a workflow involves multiple people with different responsibilities. The workflow engine handles handovers between roles automatically.

How handovers work

When a participant completes a stage and the next stage is assigned to a different role, the workflow engine:

1. Marks the current stage as complete
2. Activates the next stage
3. Creates assignments for the people in the next role
4. Notifies them that it's their turn

The completing participant sees a handover indicator — the workflow has been passed to someone else. If they're also assigned to the next stage (because they hold multiple roles), they're navigated there directly.

Blocked handovers

If the workflow reaches a stage assigned to a role that has no people assigned, it gets stuck — the stage activates but no one can work on it. This is called a blocked handover.

When this happens:

• The stage shows a blocked state on the session graph
• Session admins can resolve it by assigning someone to the missing role via Assign Roles
• The workflow resumes as soon as the role is filled

To avoid blocked handovers, make sure every role has at least one person assigned before starting a session. The start link configuration helps enforce this by requiring assignments for all roles.

Things to Know

• Roles are reusable across sessions. The same role definitions apply every time the workflow runs. Only the people assigned to those roles change between sessions.
• One person can hold multiple roles. If Alice is both the "Submitter" and the "Reviewer," she'll be assigned to stages for both roles. The workflow still routes correctly — she'll see stages from both perspectives.
• Deleting a role archives related data. If you delete a role in the builder, its stage assignments and any session assignments derived from it are archived. This preserves the history of completed sessions while removing the role from future ones.
• Role colours appear everywhere. The colour you choose shows up on the session graph (node borders and paths), role badges, and the roles panel — helping participants quickly identify which role is responsible for what.
• Completion policies interact with roles. When a stage has an "All" completion policy, every assignee with can progress enabled must complete before the stage advances. Roles with can progress off are excluded from the count.