5.4.2.3.5. History

History Pseudostate

A History pseudostate is an entry point into a composite or orthogonal state's region that restores the region's most recently active state configuration. It is a pseudostate, not a stable state: it is traversed when a transition targets it and is not left active in the resulting configuration.

stateDiagram-v2
    [*] --> Workflow
    state Workflow {
        [*] --> Draft
        Draft --> Review
        Review --> Approved
        state "H*" as H
        H --> Draft : default when no history exists
    }
    Workflow --> Outside : Leave
    Outside --> H : Return

Loading

Mermaid does not provide a native deep-history symbol. The box labeled H* approximates UML's deep-history circle; H*, rather than shallow-history H, reflects Stateflows' saved active subtree. Its position inside the region and its incoming/default transitions are significant; the box shape is not UML history notation.

H is inside the Workflow region: the transition from Outside targets that region's history pseudostate. When a configuration has already been recorded, history restores it instead of following the default route to Draft. A history vertex is not a state that remains active, and it cannot be placed at the top level outside a composite state's region.

Add a history entry point

Call AddHistory inside a composite state, or inside an orthogonal state's region:

using Stateflows.StateMachines;

public sealed record Leave;
public sealed record Return;
public sealed record Submit;
public sealed record Approve;

Fragment of a State Machine definition:

.AddInitialCompositeState("Workflow", state => state
    .AddHistory()
    .AddInitialState("Draft", draft => draft
        .AddTransition<Submit>("Review")
    )
    .AddState("Review", review => review
        .AddTransition<Approve>("Approved")
    )
    .AddState("Approved")
    .AddTransition<Leave>("Outside")
)
.AddState("Outside", outside => outside
    .AddTransition<Return, History>()
)

The AddHistory() overload uses State<History>.Name. Supply a name when the model needs a named entry point:

.AddCompositeState("Workflow", state => state
    .AddHistory("WorkflowHistory")
    // child states and transitions
)

Target the history pseudostate with the typed transition overload, such as .AddTransition<Return, History>(), or target a named history entry point by its string name. A history entry point belongs to the region in which it is declared; its outgoing transitions must remain within that region. Declare it once in the region whose configuration should be remembered.

Remembered configuration and fallback

When an active state in a region with history is exited, Stateflows records its active state subtree for that region. Later, when a transition targets that region's History pseudostate, the last recorded subtree is restored and its states are entered. The snapshot includes nested active states, so nested configurations are resumed rather than restarted at the region's initial state.

If the region has not yet recorded a configuration, the History pseudostate uses its configured outgoing transition as a default entry path. For example, a guarded history transition can select a special initial child when the State Machine is first entering the region. If no such path is taken, normal region initialization proceeds through its initial state (and any default transitions).

.AddCompositeState("Workflow", state => state
    .AddHistory(history => history
        .AddTransition("Review", transition => transition
            .AddGuard(c => c.ExecutionTrigger is Resume { InReview: true })
        )
    )
    .AddInitialState("Draft")
    .AddState("Review")
)

This fragment assumes public sealed record Resume(bool InReview); and an incoming transition triggered by Resume that targets this History entry point. ExecutionTrigger is the event that initiated the current State Machine execution. Here the fallback condition is inspected only if there is no previously recorded history. A successful history restoration resumes the saved configuration instead of following that fallback.

History in orthogonal states

History is scoped to a region. To remember the active child configuration of each region in an orthogonal state, add a History entry point separately to each region:

.AddOrthogonalState("ParallelWork", state => state
    .AddRegion(region => region
        .AddHistory("WorkHistory")
        .AddInitialState("Waiting")
        .AddState("Running")
    )
    .AddRegion(region => region
        .AddHistory("AuditHistory")
        .AddInitialState("NotAudited")
        .AddState("Audited")
    )
)

A transition into one region's history entry point restores that region; it is not a global history selector for every region. For UML's shallow-versus-deep terminology, Stateflows stores the active subtree for the region; there is no separate shallow/deep mode option on AddHistory.

See Pseudostates for the other transition-control vertices and Composite States and Orthogonal States for region structure.