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

Workflow Core

Workflow core is the engine layer. It defines activities, execution contexts, scheduling primitives, inputs and outputs, variables, bookmarks, serialization, execution pipelines, flowchart behavior, and the core runner.

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

Feature Wiring

WorkflowsFeature registers the core services:

• IActivityInvoker
• IWorkflowRunner
• IActivityTestRunner
• IActivityVisitor
• IWorkflowGraphBuilder
• IWorkflowStateExtractor
• IActivitySchedulerFactory
• workflow and activity execution pipelines
• activity registry, descriptor, factory, and lookup services
• storage drivers
• serializers
• incident strategies
• UI hint handlers
• identity and hashing services

The feature also configures default workflow and activity pipelines. The umbrella ElsaFeature calls WithDefaultWorkflowExecutionPipeline() and WithDefaultActivityExecutionPipeline().

Activities

Core activity abstractions live in Abstractions:

• Activity
• Activity<T>
• CodeActivity
• WorkflowBase
• Behavior
• Trigger

Built-in activities live in Activities. Important families:

• Primitive control: Sequence, If, Switch, For, ForEach, While, Parallel, Fork, Break, End, Finish, Complete, Fault.
• Data and runtime helpers: SetVariable, SetName, Correlate, WriteLine, ReadLine.
• Dynamic and missing activity handling: DynamicActivity, NotFoundActivity.
• Flowchart: Activities/Flowchart.

Activities are described by IActivityDescriber and registered in IActivityRegistry. Workflow management adds activities to the available designer/API surface.

Execution Contexts And State

Core execution state lives under State and Models. Important concepts:

• WorkflowState: serializable workflow execution state.
• ActivityExecutionContextState: serializable activity execution context state.
• ActivityWorkItemState: queued work item state.
• WorkflowExecutionState: high-level status and state model.
• ActivityIncident: fault or incident details.
• WorkflowInput: input passed into a workflow run.
• ActivityOutputs and ActivityOutputRecord: activity output capture.

Execution context extension tests live under test/unit/Elsa.Workflows.Core.UnitTests/Extensions/ActivityExecutionContextExtensions.

Inputs, Outputs, And Expressions

Inputs and outputs are modeled through:

• Input<T> and Input
• Output<T> and Output
• InputDefinition
• OutputDefinition
• InputDescriptor
• OutputDescriptor
• Argument and ArgumentDefinition

Expression handling bridges core workflows with language providers through Expressions and the separate expression modules. DefaultActivityInputEvaluator evaluates inputs before activity execution.

Scheduling Inside A Workflow

Core scheduling is about which activity work item runs next. Key services:

• QueueBasedActivityScheduler
• StackBasedActivityScheduler
• ActivitySchedulerFactory
• WorkflowExecutionContextSchedulerStrategy
• ActivityExecutionContextSchedulerStrategy

Runtime scheduling and external dispatch are separate and live in Elsa.Workflows.Runtime.

Bookmarks And Triggers

Core models define bookmark concepts:

• Bookmark
• BookmarkInfo
• CreateBookmarkArgs
• TriggerType

The runtime persists and indexes bookmarks/triggers. Core activities create bookmarks and signals; runtime services decide how they are stored and resumed.

Flowchart Execution

Flowchart support is split between:

• FlowchartFeature
• Flowchart activities
• flowchart extension methods in Activities/Flowchart/Extensions

Relevant ADRs:

• ADR 0005: Token-Centric Flowchart Execution Model
• ADR 0007: Explicit Merge Modes For Flowchart Joins

Pipelines

Core has separate workflow and activity execution pipelines:

flowchart LR
    Runner["IWorkflowRunner"] --> WorkflowPipeline["IWorkflowExecutionPipeline"]
    WorkflowPipeline --> Scheduler["Activity scheduler"]
    Scheduler --> ActivityPipeline["IActivityExecutionPipeline"]
    ActivityPipeline --> Invoker["IActivityInvoker"]
    Invoker --> Activity["IActivity.ExecuteAsync"]

Pipeline extension methods live under Extensions and middleware under Middleware. Pipelines are configured by WorkflowsFeature.

Commit Strategies

Commit strategies determine persistence boundaries. Related files:

• CommitStrategiesFeature
• CommitStrategies
• workflow sample configuration in Elsa.Server.Web/Program.cs

Runtime replaces the default no-op commit handler with an execution-cycle-aware handler so state changes are persisted at runtime boundaries.

Serialization

Core serializers live under Serialization, including:

• JsonWorkflowStateSerializer
• JsonPayloadSerializer
• JsonActivitySerializer
• ApiSerializer
• SafeSerializer
• StandardJsonSerializer

Custom constructor and additional converter configurators are registered by WorkflowsFeature.

When To Change This Layer

Change workflow core only when you are changing engine semantics, activity contracts, execution state, serialization, core activity behavior, or flowchart behavior. If the change is about persisted definitions, API DTOs, background dispatch, or a module-specific transport, start in management, API, runtime, or the extension module instead.