elsa-core/doc/wiki/workflow-management.md

Workflow Management

Workflow management owns workflow definitions and workflow instances as manageable resources. It is the layer used by Studio, import/export, validation, activity descriptors, workflow reference graphs, and many API endpoints.

Start in src/modules/Elsa.Workflows.Management.

Feature Wiring

WorkflowManagementFeature registers:

• memory stores for WorkflowDefinition and WorkflowInstance
• activity providers and descriptor providers
• workflow definition and instance managers
• serializer, importer, exporter, publisher, validator
• materializers for CLR, JSON, and typed workflows
• activity registry population
• workflow reference graph services
• host method activities
• workflow definition activities
• variable descriptors and expression descriptors
• read-only mode and default log persistence mode

It depends on workflow core, caching, mediator, string compression, system clock, workflow definitions, and workflow instances.

Key Entities

Entity	File	Meaning
WorkflowDefinition	Entities/WorkflowDefinition.cs	Persisted definition version and metadata.
WorkflowInstance	Entities/WorkflowInstance.cs	Persisted execution instance and workflow state.

Management entities are separate from core execution models. Core can run workflows; management stores definitions and instances.

Stores

Contracts:

• IWorkflowDefinitionStore
• IWorkflowInstanceStore

Defaults:

• MemoryWorkflowDefinitionStore
• MemoryWorkflowInstanceStore
• CachingWorkflowDefinitionStore

EF Core persistence replaces these stores through Elsa.Persistence.EFCore/Modules/Management.

Definition Lifecycle

flowchart LR
    Draft["Draft definition"] --> Save["Save draft"]
    Save --> Validate["Validate"]
    Validate --> Publish["Publish version"]
    Publish --> Runtime["Runtime can start or dispatch"]
    Publish --> Retract["Retract"]
    Draft --> Delete["Delete definition/version"]

Important services:

• WorkflowDefinitionManager
• WorkflowDefinitionPublisher
• WorkflowDefinitionService
• CachingWorkflowDefinitionService
• WorkflowValidator

Notifications under Notifications allow cache eviction, validation, reference updates, and cascading behavior.

Materializers

Materializers convert persisted or typed representations into executable workflows:

• ClrWorkflowMaterializer
• JsonWorkflowMaterializer
• TypedWorkflowMaterializer

The materializer registry is MaterializerRegistry, with the contract IMaterializerRegistry.

Import, Export, And Serialization

Management uses:

• WorkflowSerializer
• WorkflowDefinitionImporter
• WorkflowDefinitionExporter

These services are used by API endpoints for workflow definition import/export and by tests that load JSON workflow definitions.

Activity And Variable Descriptors

Designer and API clients need metadata about available activities, inputs, outputs, UI hints, variable types, and expressions. Management provides:

• TypedActivityProvider
• DefaultExpressionDescriptorProvider
• ActivityRegistryPopulator
• ExpressionDescriptorRegistry

Modules add activities by calling Module.UseWorkflowManagement(management => management.AddActivitiesFrom<TMarker>()) or equivalent helpers.

Host Method Activities

Host method activities expose methods from registered host classes as activities. Relevant files:

• HostMethodActivity
• HostMethodActivityProvider
• HostMethodActivitiesOptions

The reference server registers an activity host with AddActivityHost<Penguin>() in Program.cs.

Workflow Definition Activity

The workflow definition activity allows one workflow to reference another workflow definition:

• WorkflowDefinitionActivity
• WorkflowDefinitionActivityProvider
• WorkflowReferenceGraphBuilder
• WorkflowReferenceUpdater

Component tests under WorkflowReferenceGraph exercise this behavior.

Read-Only Mode

WorkflowManagementFeature.UseReadOnlyMode(bool) affects mutable workflow definition operations. API authorization uses NotReadOnlyRequirement and the NotReadOnlyPolicy in workflow API.

When To Change This Layer

Change management when the work is about workflow definitions, workflow instances as persisted records, import/export formats, activity metadata, variable metadata, validation, read-only behavior, reference graphs, or workflow store replacement. Do not put runtime dispatch or transport-specific behavior here unless management contracts need to expose it.