Resuming suspended workflows instantiated under a prior version of Elsa

[gudatcomputers]

When upgrading Elsa... for example from 3.2 to the 3.7, how should we be handling suspended workflows created under 3.2? There are some internal changes to the way state is stored that make them not resumable by default, or without manipulating the data stored for the Bookmark and WorkflowInstance.

[sfmskywalker]

Short answer: there doesn't appear to be a built-in migration path for suspended workflow instances across Elsa versions when the persisted workflow state or bookmark shape changed.

In the current code, resume happens against the persisted workflow instance state and the stored bookmark IDs, not by rebuilding state from the latest workflow definition:

• LocalWorkflowClient.GetWorkflowGraphAsync resolves the workflow by WorkflowDefinitionHandle.ByDefinitionVersionId(workflowInstance.DefinitionVersionId), so Elsa resumes against the stored definition version ID.
• LocalWorkflowClient.RunInstanceAsync passes the persisted workflowInstance.WorkflowState back into workflowRunner.RunAsync.
• WorkflowResumer.ResumeAsync loads stored bookmarks and resumes by bookmark.Id / bookmark.WorkflowInstanceId.

Relevant source:

• elsa-core/src/modules/Elsa.Workflows.Runtime/Services/LocalWorkflowClient.cs
• elsa-core/src/modules/Elsa.Workflows.Runtime/Services/WorkflowResumer.cs
• elsa-core/src/modules/Elsa.Workflows.Core/Services/WorkflowStateExtractor.cs
• elsa-core/src/modules/Elsa.Workflows.Core/State/WorkflowState.cs
• elsa-core/src/modules/Elsa.Workflows.Runtime/Entities/StoredBookmark.cs

There are some targeted backward-compatibility hooks, but they are selective rather than a general suspended-instance upgrader:

• SerializationTypeResolver can resolve registered legacy type names.
• WorkflowsFeature registers legacy aliases for some moved types.
• WorkflowStateMapper keeps a compatibility fallback for the older workflow-instance name field.

Relevant source:

• elsa-core/src/modules/Elsa.Common/Serialization/SerializationTypeResolver.cs
• elsa-core/src/modules/Elsa.Workflows.Core/Features/WorkflowsFeature.cs
• elsa-core/src/modules/Elsa.Workflows.Management/Mappers/WorkflowStateMapper.cs

So if your 3.2 suspended instances still deserialize cleanly under 3.7, and the referenced definition versions are still available, they may resume. But if you already see breaking changes in WorkflowInstance / Bookmark storage, I couldn't find a repo-supported automatic migration command or compatibility layer that updates old suspended instances for you.

Operationally, the safest path is:

1. Drain or complete suspended 3.2 instances before upgrading when possible.
2. If they must survive the upgrade, test a copy of your persisted workflow_instances and bookmarks data in staging first.
3. For any broken records, plan a custom migration for the persisted workflow-state/bookmark payloads based on the exact fields that changed.

Related discussions:

• Breaking changes in workflow_instances documents after upgrading from Elsa 3.2.3 to 3.3.5 #7011 discusses state-shape breakage after a 3.2.3 -> 3.3.5 upgrade.
• Resuming workflow instances in V3 #6042 shows the current resume model in V3, which is bookmark/workflow-instance driven.

If you can share the exact fields that changed for your provider (e.g. MongoDB document shape, bookmark payload/type names, or deserialization errors), that would make it possible to be more specific about what needs to be migrated.

[gudatcomputers]

We saw 3 primary issues we could observe. Claude found a 4th.

• exactly what you link in Breaking changes in workflow_instances documents after upgrading from Elsa 3.2.3 to 3.3.5 #7011
• type names you mentioned being accounted for in SerializationTypeResolver.
• event case sensitivity in bookmarks
• Claude pointed the representation of Scope/FlowScope internal to the WorkflowInstance data

[sfmskywalker]

Short answer: yes, those four items all fit the current codebase and I still don't see a built-in migration path for suspended instances across versions when the persisted workflow state or bookmark payload shape changed.

A few concrete points from the current code and from 3.2-era code:

• Resume still works from persisted workflow state + stored bookmark IDs, not by rebuilding from the latest workflow definition. LocalWorkflowClient.RunInstanceAsync passes the persisted workflowInstance.WorkflowState back into workflowRunner.RunAsync, and WorkflowResumer.ResumeAsync resumes using the stored bookmark IDs.
• The type-alias / forwarded-type support is selective, not a general suspended-instance upgrader. So it can help for some renamed types, but it does not rewrite existing persisted workflow instance or bookmark documents for you.
• The event-name casing point is real. In 3.2.0, EventBookmarkPayload.EventName normalized to ToLowerInvariant(). In the current code, event stimuli are created from the event name as-is (GetEventStimulus returns new(eventName)), and bookmark matching happens through the stimulus hash path. So if your old persisted bookmark payload/hash assumed lower-cased event names and the newer runtime does not, that can definitely break matching.
• The FlowScope / scope-shape point is also real. In 3.2.0, FlowScope had a very different structure (OwnerActivityId plus an Activities dictionary of ActivityFlowState). In the current code, FlowScope is a different model with visit-count dictionaries for activities and connections, and it is still serialized into workflow state via the FlowScope type alias.

Relevant source:

• elsa-core/src/modules/Elsa.Workflows.Runtime/Services/LocalWorkflowClient.cs
• elsa-core/src/modules/Elsa.Workflows.Runtime/Services/WorkflowResumer.cs
• elsa-core/src/modules/Elsa.Common/Serialization/SerializationTypeResolver.cs
• elsa-core/src/modules/Elsa.Workflows.Runtime/Bookmarks/EventBookmarkPayload.cs
• elsa-core/src/modules/Elsa.Workflows.Runtime/Extensions/ActivityExecutionContextEventExtensions.cs
• elsa-core/src/modules/Elsa.Workflows.Core/Activities/Flowchart/Models/FlowScope.cs
• elsa-core/src/modules/Elsa.Workflows.Core/Features/FlowchartFeature.cs

Related:

• Breaking changes in workflow_instances documents after upgrading from Elsa 3.2.3 to 3.3.5 #7011 for the variable/type-name compatibility issue
• Resuming workflow instances in V3 #6042 for the current resume model in V3

So the practical conclusion is still: if you need suspended 3.2 instances to survive into 3.7, plan a custom migration for the persisted workflow_instances / bookmark payloads that are version-sensitive for your provider. I don't see a repo-supported automatic upgrader for those records.

If it helps, the next useful step would be to export one broken workflow instance document plus its related bookmarks and compare them against a freshly suspended 3.7 instance of the same workflow. That should make the exact migration delta pretty obvious.