Suspension Model

Execution State Machine

Correlation Token

The correlation token (also called ExecutionResId) is a GUID generated by the engine when a HIL suspension is recorded. It is:

• Globally unique — no two suspensions ever share a token.
• Single-use — once used to resume, it is marked consumed. Repeat calls are rejected.
• The primary key of the resume API URL: POST /api/executions/{executionResId}/resume
• Embedded in HIL task notifications so the actor's channel can call the API.

SuspendPayload Schema

public class SuspendPayload
{
    public string         ExecutionResId     { get; init; }  // correlation token (GUID)
    public string         SuspendedNodeId    { get; init; }
    public string         HilTaskType        { get; init; }  // "Approval" | "UserForm" | "Review"
    public string         ActorId            { get; init; }  // resolved actor
    public string         ActorType          { get; init; }  // "User" | "Group" | "Agent"
    public DateTimeOffset? ExpiresAt         { get; init; }  // null if no timeout
    public object?        TaskPayload        { get; init; }  // form schema, instruction text, etc.
}

Process_SuspendedExecutions Table

CREATE TABLE Process_SuspendedExecutions (
    ExecutionResId    UNIQUEIDENTIFIER PRIMARY KEY,
    TenantId          NVARCHAR(100)   NOT NULL,
    ExecutionId       NVARCHAR(100)   NOT NULL,
    ProcessId         NVARCHAR(100)   NOT NULL,
    SuspendedNodeId   NVARCHAR(100)   NOT NULL,
    ExecutionMemory   NVARCHAR(MAX)   NOT NULL,  -- JSON serialised
    SuspendedAt       DATETIMEOFFSET  NOT NULL,
    ExpiresAt         DATETIMEOFFSET  NULL,
    ResumedAt         DATETIMEOFFSET  NULL,       -- set on consume
    Status            TINYINT         NOT NULL    -- 0=Pending, 1=Resumed, 2=Expired
);