How to deserialize the StringData field of WorkflowDefinition to access and modify its properties?

[PlazaValentin]

Hi everyone

I'm currently migrating from Elsa Workflows v2 to v3, and I have a question regarding the WorkflowDefinition entity in the Elsa.Workflows.Management.Entities namespace.

In Elsa 2, we used to manually serialize and deserialize workflow data (activities, connections, variables, etc.) into a JSON column called Data.
In Elsa 3, I noticed that the equivalent column seems to be StringData, which contains the serialized workflow definition.

My question is:
Is there any supported way in Elsa 3 to deserialize the StringData field from a WorkflowDefinition entity (e.g., using a serializer service like IWorkflowDefinitionSerializer), modify some parts of it (for example, activities or variables), and then save it back to the database?

If yes:

Which serializer or helper class should I use to parse and re-serialize it properly?

Is the internal JSON schema for StringData stable enough to be modified directly?

Basically, I’d like to be able to:

Load a workflow definition from EF (WorkflowDefinition).

Access and modify its inner structure programmatically.

Re-serialize and save it safely.

Thanks a lot in advance for your help and for the amazing work on Elsa 3!

[sfmskywalker]

Short answer: yes, you can deserialize it, but StringData is not the full workflow-definition contract and I would avoid treating its JSON shape as a stable public API.

In the current code:

• WorkflowDefinition.StringData is only the materializer-specific textual representation. For JSON workflows, that is typically the serialized root activity tree, not the whole definition.
• WorkflowDefinitionMapper.Map deserializes OriginalSource into a full WorkflowDefinitionModel when it is available. If OriginalSource is not present, it falls back to deserializing StringData as the root activity only.
• WorkflowDefinitionImporter and WorkflowDefinitionPublisher save JSON workflows by serializing the root activity into StringData, while the rest of the definition metadata (Name, Description, Variables, Inputs, Outputs, Options, etc.) lives on the WorkflowDefinition entity itself.
• DefaultWorkflowDefinitionStorePopulator also treats StringData and OriginalSource differently depending on the materializer.

Relevant source:

• elsa-core/src/modules/Elsa.Workflows.Management/Entities/WorkflowDefinition.cs
• elsa-core/src/modules/Elsa.Workflows.Management/Mappers/WorkflowDefinitionMapper.cs
• elsa-core/src/modules/Elsa.Workflows.Management/Services/WorkflowSerializer.cs
• elsa-core/src/modules/Elsa.Workflows.Management/Services/WorkflowDefinitionImporter.cs
• elsa-core/src/modules/Elsa.Workflows.Management/Services/WorkflowDefinitionPublisher.cs
• elsa-core/src/modules/Elsa.Workflows.Runtime/Services/DefaultWorkflowDefinitionStorePopulator.cs

So the safe interpretation is:

• If you deserialize StringData, you are generally working with the workflow root/activity graph.
• If you need the full editable definition model, prefer working with WorkflowDefinitionModel / Workflow instead of editing the raw StringData JSON as a durable contract.

Practical options:

• To materialize a stored definition into an executable workflow object, use IWorkflowDefinitionService.MaterializeWorkflowAsync(definition).
• To serialize/deserialize the full workflow JSON contract, use IWorkflowSerializer (which works with Workflow) or deserialize a full JSON document into WorkflowDefinitionModel.
• If you do update a stored WorkflowDefinition directly, you need to keep the entity fields and StringData aligned. Updating only StringData is not enough for fields like variables/options/metadata that are stored separately.

So: supported for internal/application use, yes. Stable enough to treat StringData itself as a public schema contract, no.