SemianiakaVY/elsa-core
1
0
Fork 0
Code Issues Pull requests Actions 1 Packages Projects Releases Wiki Activity
elsa-core/doc/wiki/workflow-core.md
Sipke Schoorstra c2fb027c41
Refactor: Overhauls workflow JSON type serialization (#7549) 
* Avoid null endpoint DTO metadata in tests

* Enforce console logs hub read permission

* Remove unused console logs hub import

* Support mapped endpoint metadata in auth tests

* Reduce console log capture throughput impact

* Address Copilot console logs review

* Refactor task scheduling to support tenant-level background work and enhance logging functionality.

* Introduce ConsoleStreamHook for stdout/stderr tee and enhance logging validation. Adjust test cases and startup warnings for distributed lock provider usage.

* Refactor console logging pipeline with capture optimization and new ConsoleLogsHost; update tests accordingly.

* Add Ansi SGR parser for console logs and associated unit tests

* Remove ANSI color renderings and parsers; integrate ConsoleLogScopeAccessor for improved logging context with workflow instance ID support.

* Address console logs code quality feedback

* Address PR review feedback

* Preserve console logs extension points

* Stabilize console logs host lifecycle

* Address final automated review comments

* Tighten console log capture shutdown

* Address console log review feedback

* Address follow-up review feedback

* Cover final review feedback

* Avoid recursive console provider initialization

* Guard console host lease shutdown

* Preserve console log scope and provider lifetime

* Correlate console log scope fallback

* Tighten console scope correlation

* Expose host services during provider construction

* Redact ANSI-normalized console lines

* Remove `ConsoleCaptureTee` and related services and tests

* Use pipeline contributors for console log context

* Update CShells package versions to 0.0.24-preview.132

* Filter live console logs by workflow instance

* Enhance console logging with activity execution metadata and extend test coverage.

* Address console logs stream consumption comment

* Add diagnostics OpenTelemetry backend

* Introduce dedicated workflow JSON type registry and hardening

This change addresses GitHub issue #7541 by establishing a separate type registry (`IWorkflowJsonTypeRegistry`) for workflow JSON serialization. This decouples workflow type resolution from expression type aliases, enforcing a strict trust boundary.

Key aspects:
- New workflow JSON emits preferred aliases for registered types.
- Existing persisted workflows can be loaded via registered legacy names.
- Unknown, abstract, interface, open generic, or inappropriate collection types are rejected during deserialization, enhancing security.
- Public APIs (e.g., incident strategies) now expose consistent workflow JSON type identifiers.

This ensures secure, predictable, and backward-compatible handling of types within workflow definitions and payloads.

* Remove unused project references and streamline console log endpoint

* Move serialization type aliases to Elsa.Common

* Update serialization integration fixtures for aliases

* Stabilize missing rate limiter policy test
2026-05-31 11:09:39 +02:00

8.4 KiB
Raw Blame History

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.
  • State machine: Activities/StateMachine. Named states with trigger-driven transitions. See Activities And Authoring for the execution model.

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:

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

Bookmarks And Triggers

Core models define bookmark concepts:

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:

Relevant ADRs:

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:

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.

Workflow JSON Type Identifiers

Workflow JSON type resolution uses the shared ISerializationTypeRegistry from Elsa.Common.Serialization, not expression type aliases. Register workflow-serializable payload types through SerializationTypeOptions; keep ExpressionOptions for expression/type metadata only.

New workflow JSON writes preferred aliases when a type is registered. Compatibility reads also accept explicitly registered legacy names, including selected CLR names from older persisted workflow JSON. Unknown CLR names are rejected rather than loaded dynamically. Polymorphic object reads also reject abstract, interface, open generic, and unsupported collection targets unless the resolver can map a known collection interface to a concrete collection type.

Public API payloads that expose workflow JSON type identifiers should emit values from ISerializationTypeRegistry. For example, incident strategy descriptors return the alias that workflow JSON accepts, while registered legacy CLR names remain readable during the compatibility window.

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.