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

Workflow Runtime

Workflow runtime owns starting, dispatching, resuming, canceling, logging, and recovering workflow executions. It is the layer that turns definitions into running instances and responds to triggers, bookmarks, background work, and admin operations.

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

Feature Wiring

WorkflowRuntimeFeature registers and configures:

• IWorkflowRuntime
• IWorkflowDispatcher
• IStimulusDispatcher
• IWorkflowCancellationDispatcher
• bookmark, bookmark queue, trigger, workflow execution log, and activity execution stores
• workflow matcher, starter, invoker, resumer, canceler, restarter
• trigger indexer and bookmark manager
• background workflow, stimulus, task, and activity dispatch
• bookmark queue worker and queue purger
• distributed lock provider
• execution cycle registry
• graceful shutdown machinery
• runtime startup and recurring tasks

It also configures WorkflowsFeature to use the runtime commit state handler.

Runtime Stores

Important runtime entities:

• StoredTrigger
• StoredBookmark
• BookmarkQueueItem
• WorkflowExecutionLogRecord
• ActivityExecutionRecord
• WorkflowInboxMessage

The default runtime feature uses memory stores. EF Core runtime persistence is wired by EFCoreWorkflowRuntimePersistenceFeature, which replaces runtime store factories on WorkflowRuntimeFeature.

Dispatch Paths

flowchart TB
    Start["Start workflow request"] --> Starter["DefaultWorkflowStarter"]
    Trigger["Trigger/stimulus"] --> Stimulus["StimulusSender / TriggerInvoker"]
    Bookmark["Bookmark resume"] --> Resumer["BookmarkResumer / WorkflowResumer"]
    Instance["Dispatch existing instance"] --> Dispatcher["WorkflowDispatcher"]
    Starter --> Invoker["WorkflowInvoker"]
    Stimulus --> Matcher["WorkflowMatcher"]
    Matcher --> Dispatcher
    Resumer --> Dispatcher
    Dispatcher --> Runtime["LocalWorkflowRuntime"]
    Runtime --> Runner["IWorkflowRunner"]

Key files:

• LocalWorkflowRuntime
• BackgroundWorkflowDispatcher
• ValidatingWorkflowDispatcher
• WorkflowInvoker
• DefaultWorkflowStarter
• WorkflowResumer
• BookmarkResumer
• TriggerInvoker

Triggers And Bookmarks

Triggers start workflows. Bookmarks resume suspended workflow instances. Runtime indexes and queries them through:

• TriggerIndexer
• DefaultBookmarkManager
• BookmarkPersister
• BookmarkUpdater
• BookmarkBoundWorkflowService
• TriggerBoundWorkflowService

Bookmark queue processing is handled by:

• StoreBookmarkQueue
• BookmarkQueueProcessor
• BookmarkQueueWorker
• BookmarkQueueSignaler

Execution Logs

Workflow and activity execution logs flow through sinks and stores:

• StoreWorkflowExecutionLogSink
• StoreActivityExecutionLogSink
• WorkflowExecutionLogRecordExtractor
• DefaultActivityExecutionMapper

API endpoints under WorkflowInstances/Journal, ActivityExecutions, and ActivityExecutionSummaries expose this data.

Background Work

Runtime has several background paths:

• BackgroundWorkflowDispatcher for workflow dispatch.
• BackgroundStimulusDispatcher for stimulus dispatch.
• BackgroundTaskDispatcher for RunTask.
• LocalBackgroundActivityScheduler for background activity execution.
• BackgroundActivityInvoker for executing background activity work.

These paths matter for tests: a workflow may return before background activity or bookmark work has completed.

Graceful Shutdown And Recovery

Recent graceful shutdown work added node-local quiescence and drain concepts. Source landmarks:

• QuiescenceSignal
• IngressSourceRegistry
• DrainOrchestrator
• DrainOrchestratorHostedService
• InterruptedRecoveryScanner
• RecoverInterruptedWorkflowsStartupTask

The design intent is captured in specs/002-graceful-shutdown/plan.md.

Ingress source adapters are currently registered by modules such as HTTP and Scheduling so the runtime can pause external event intake during drain.

Runtime Admin

The workflow API includes runtime admin endpoints:

• GET /elsa/api/admin/workflow-runtime/status
• POST /elsa/api/admin/workflow-runtime/pause
• POST /elsa/api/admin/workflow-runtime/resume
• POST /elsa/api/admin/workflow-runtime/force-drain

Endpoint code lives under Elsa.Workflows.Api/Endpoints/RuntimeAdmin. The service behind these endpoints is WorkflowRuntimeAdminService.

Distributed Runtime

Distributed runtime support lives in Elsa.Workflows.Runtime.Distributed. It layers distributed coordination and resilience support on top of the base runtime. When making runtime changes, check whether the distributed project has a parallel worker or dispatcher that must honor the same semantics.

When To Change This Layer

Change runtime for dispatch semantics, trigger/bookmark indexing, background work, execution logs, recovery, cancellation, graceful shutdown, or runtime stores. If a change only affects how definitions are saved or described, it belongs in management. If it only changes HTTP endpoint activity behavior, start in Elsa.Http.