elsa-core/doc/wiki/activities-and-authoring.md

Activities And Authoring

Elsa supports several workflow authoring paths: C# workflow classes, JSON definitions, visual designer definitions, host method activities, workflow-definition activities, and the experimental ElsaScript DSL.

C# Workflows

C# workflows usually derive from WorkflowBase and implement Build(IWorkflowBuilder builder).

The root activity can be a Sequence, Flowchart, or another composite activity. The README has a minimal example that starts with HttpEndpoint and then sends email.

Source landmarks:

• WorkflowBase
• WorkflowBuilder
• IWorkflowBuilder
• Workflow runtime feature AddWorkflow/AddWorkflowsFrom

The reference server registers workflows from its assembly with AddWorkflowsFrom<Program>() in Program.cs.

JSON Workflows

JSON definitions are materialized by JsonWorkflowMaterializer. Sample JSON workflows appear in:

• src/apps/Elsa.Server.Web/Workflows
• test/component/Elsa.Workflows.ComponentTests/Scenarios
• test/integration/Elsa.Workflows.IntegrationTests/Scenarios

JSON workflows are important for designer compatibility and import/export tests.

Designer Authored Workflows

The designer consumes metadata from workflow API descriptor endpoints and persists definitions through workflow definition endpoints. The server-side responsibilities are:

• expose activity descriptors
• expose expression descriptors
• expose variable descriptors
• save drafts and publish versions
• return workflow graphs and reference data

Relevant code:

• ActivityDescriptors endpoints
• WorkflowDefinitions endpoints
• WorkflowDefinitionManager
• ActivityRegistryPopulator

ElsaScript DSL

Elsa.Dsl.ElsaScript is an experimental JavaScript-inspired textual DSL for authoring workflows.

The module README is the best current guide: ElsaScript README.

Current shape:

• parser creates AST nodes from ElsaScript source
• compiler maps AST nodes to Elsa activities
• expression prefixes map into Elsa expression providers
• integration tests cover parser and compiler basics

Known limitations are documented in the README; do not assume full language coverage yet.

Host Method Activities

Host method activities expose methods on registered host types as activities. Register host types with workflow management:

services.AddElsa(elsa =>
{
    elsa.AddActivityHost<MyHost>();
});

Key files:

• HostMethodActivity
• HostMethodActivityProvider
• HostMethodActivitiesOptions
• sample host type Penguin

Use host method activities when host application methods need to appear as designer activities without creating a full activity package.

Workflow Definition Activities

Workflow definition activities let a workflow call another workflow definition. This is useful for composition and reuse.

Key files:

• WorkflowDefinitionActivity
• WorkflowDefinitionActivityDescriptorFactory
• WorkflowDefinitionActivityProvider
• WorkflowReferenceGraphBuilder

Tests:

• CachingAndWorkflowDefinitionActivity
• WorkflowReferenceGraph

StateMachine Activity

The StateMachine activity models named states with trigger-driven transitions. It lives in Elsa.Workflows.Core and is registered as a built-in activity.

Key concepts:

• States (StateMachineState): Named states, each with an optional Entry and Exit activity.
• Transitions (Transition): Directed From→To pairs with an optional Trigger activity, optional Condition expression, and optional Action activity.
• InitialState: The first state to enter when execution starts.

Execution cycle:

1. On start, the machine enters InitialState and runs its Entry activity if present.
2. All outbound transition triggers for the current state are scheduled concurrently.
3. When a trigger completes and its Condition evaluates to true, competing triggers are canceled, the optional Action runs, then the current state's Exit activity runs.
4. The machine moves to the To state and repeats from step 1.
5. If the current state has no valid outbound transitions, the machine completes.

When a condition evaluates to false the failed trigger is re-armed and remains waiting alongside other triggers for the state.

Spec: specs/006-state-machine-activity/spec.md.

Adding A New Activity

Typical steps:

1. Add an activity class in the owning module's Activities folder.
2. Derive from the appropriate base class, usually Activity or CodeActivity.
3. Define inputs and outputs with Elsa input/output models.
4. Register it with management, often via Module.AddActivitiesFrom<TMarker>() or management.AddActivity<T>().
5. Add a unit test with ActivityTestFixture for activity-only behavior.
6. Add integration or component tests if it creates bookmarks, uses persistence, or participates in runtime dispatch.

Good examples:

• WriteLine
• HttpEndpoint
• SendHttpRequest
• RunJavaScript

Activity Metadata And UI Hints

Designer-facing metadata is produced by descriptors and UI hint handlers. Core UI hints live under Elsa.Workflows.Core/UIHints. Module-specific handlers live with their module, such as HTTP content type options in Elsa.Http/UIHints.

If an activity property needs dynamic options, add an IPropertyUIHandler and expose it through the descriptor option endpoint.

Authoring Choice Guide

Need	Use
Compile-time workflow with strong typing	C# workflow class
Designer-created or imported workflow	JSON workflow definition
Host app method as activity	Host method activity
Reusable workflow composition	Workflow definition activity
Text DSL experiment or code-centric workflow file	ElsaScript
Module-specific trigger or IO	Custom activity in the owning module