Session Progression Rules

This document outlines the logic governing how a user progresses through stages within a session (a workflow_run), and how a session is ultimately completed.

Core Concepts

• Stage (workflow_run_stage): Represents a single step or page in a workflow. A stage can be in one of three states:
  • Pending: The stage has not yet been reached. (active_at is null).
  • Active: The stage is currently available for a user to work on. (active_at is not null, completed_at is null).
  • Completed: The stage has been finished. (active_at and completed_at are not null).
• Transition (page_transition): A directed link between two stages (a source and a target). It represents a potential path forward in the workflow.
• Rule (transition.rule): A set of conditions attached to a Transition. These conditions are evaluated against the session's data (i.e., data in the sheet's cells) to determine if the path is valid.

1. Forward Progression: Completing a Stage

When a user completes an active stage, the following sequence is triggered:

1. Mark as Complete: The current workflow_run_stage is marked as complete by setting its completed_at and completed_by fields. The corresponding session_assignment is also marked as complete.

2. Evaluate Outgoing Transitions: The system identifies all transitions where the completed stage is the source_id.

3. Check Rules: For each outgoing transition, its rule is evaluated against the current data in the session's sheet (cells and columns).

4. Activate Next Stage(s):

   • A transition is considered valid if its rule evaluates to true.
   • The stages that are the target_id of these valid transitions are activated by setting their active_at timestamp.

5. Handling Loops: If a newly activated stage was previously completed (e.g., in a workflow loop), its completion status is reset. The completed_at and completed_by fields are set to null to allow the user to work on it again.

2. Backward Progression: Rewinding a Stage

A user can move backward from a currently active stage.

1. Pre-condition: The stage being rewound from must be active (active_at is not null).

2. Identify Previous Stage(s): The system finds the transitions that led to the current stage (i.e., where the current stage is the target_id). The source_id of these transitions points to the previous stage(s).

3. Deactivate Current Path: The current active stage, and any other stages that may have been activated concurrently, are deactivated by setting their active_at and completed_at fields to null.

4. Reactivate Previous Stage(s): The identified previous stage(s) are reactivated by setting their completed_at and completed_by fields to null and updating their active_at timestamp.

3. Manual State Changes

Beyond the standard progression flow, there are specific manual actions available.

Reactivating a Stage

• A single, previously completed stage can be manually made active again.
• This action nullifies the completed_at and completed_by fields for that specific stage and its corresponding session_assignment, setting its active_at timestamp to the current time.
• This does not automatically deactivate any subsequent stages.

4. Role Assignments and Stage Access Control

Role assignments determine which users can access and interact with each stage in a session. This system enables multi-role workflows where different users or teams work on different stages.

4.1. Core Components

Workflow Roles (workflow_roles)

• Represent abstract roles within a workflow (e.g., "Reviewer", "Approver", "Submitter").
• Defined at the workflow level and reusable across multiple stages.

Stage Role Assignments (stage_role_assignments)

• Link a workflow role to a specific stage (page).
• Define which roles are allowed to access a particular stage.
• Include two permission flags:
  • can_write: Controls whether the role can edit data on the stage (default: true).
  • can_progress: Controls whether the role can complete the stage and move forward (default: true).

Session Role Assignments (session_role_assignments)

• Created when a session starts, assigning specific users to workflow roles for that session.
• Maps a user to a role for the entire session (e.g., "Alice is the Reviewer for this session").

Session Assignments (session_assignments)

• Created dynamically as stages become active.
• Links a user to a specific active stage based on their session role assignment and the stage's role requirements.
• Inherits can_write and can_progress permissions from the stage role assignment.

4.2. How Access Control Works

Stage Access

1. When a stage becomes active, the system checks which workflow roles are assigned to that stage (via stage_role_assignments).
2. For each role assigned to the stage, the system finds users who have been assigned that role for the session (via session_role_assignments).
3. A session_assignment is created for each matching user, granting them access to the stage.

Permissions

• Can Write (can_write):

  • If true, the user can edit fields and interact with blocks on the stage.
  • If false, the user can view the stage but cannot modify any data.
  • Used in SessionRenderer to determine currentUserCanRespond.

• Can Progress (can_progress):

  • If true, the user can complete the stage and trigger progression to the next stage.
  • If false, the user can view and potentially edit the stage but cannot advance the workflow.
  • Used in progression logic to determine canUserProgress.

Visibility

• Restricted Stage Visibility (workflow.restricted_stage_visibility):
  • If enabled, users can only see stages they are assigned to.
  • If disabled, all users can view all stages (but may not be able to interact based on permissions).

4.3. Multi-Role Progression Scenarios

When multiple roles are involved in a workflow, progression can trigger different behaviors:

Handover

• Occurs when the current user completes a stage, but the next stage is assigned to a different role.
• The system marks the current stage as complete and creates session assignments for the users in the next role.
• Progression type: MARK_COMPLETE_AND_HANDOVER.

Handover with Automatic Navigation

• Similar to handover, but if the current user is also assigned to the next stage, they are automatically navigated to it.
• Progression type: MARK_COMPLETE_AND_HANDOVER_AND_GO_TO_STAGE.

Blocked Handover

• Occurs when a stage has role assignments but no users have been assigned to those roles for the session.
• The workflow cannot progress until session role assignments are created.
• Progression type: BLOCKED_HANDOVER.

4.4. Example Workflow

Scenario: A three-stage approval workflow with two roles:

• Submitter: Can submit and edit the initial request.
• Approver: Can review and approve or reject.

Setup:

1. Stage 1 ("Submit Request") has a stage role assignment for "Submitter" with can_write: true, can_progress: true.
2. Stage 2 ("Review") has a stage role assignment for "Approver" with can_write: false, can_progress: true.
3. Stage 3 ("Final Decision") has a stage role assignment for "Approver" with can_write: true, can_progress: true.

Session Flow:

1. Alice starts the session and is assigned the "Submitter" role.
2. Bob is assigned the "Approver" role.
3. Stage 1 activates, creating a session assignment for Alice.
4. Alice completes Stage 1. The system:
   • Marks Stage 1 as complete.
   • Activates Stage 2.
   • Creates a session assignment for Bob (the Approver).
   • Shows a handover notification (Alice → Bob).
5. Bob reviews Stage 2 (read-only due to can_write: false) and completes it.
6. Stage 3 activates, Bob can now edit and make the final decision.

5. Session Completion

Completing the entire session is a separate action from completing a single stage.

1. Trigger: The logic to determine when a session can be completed resides on the client-side. This is typically when a user is on a final stage that has no valid outgoing transitions, or a stage is explicitly designed to end the session.

2. Action: When triggered, the parent workflow_runs record is updated by setting its completed_at and completed_by fields. This officially closes out the entire session.