Defining workflows

A workflow is a class that implements IDeclarativeWorkflow<TStartRequest>. Its Spec property is built once, with the fluent builder, from expressions; the engine compiles it to a canonical definition. This page covers every construct of the builder. Each example compiles: it is part of a tutorial lesson, whose page holds the complete code, or of the order approval of Getting started.

Forks, maps, external activities, timers, external signals and task deadlines run on Stella.Engine, the default runtime provider; a host that selects Stella.InProcess with such a workflow stops at start (Hosting).

Anatomy of a workflow

/// <summary>One human task: the recipient acknowledges a document, and the workflow completes.</summary>
public sealed class AcknowledgeDocumentWorkflow : IDeclarativeWorkflow<AcknowledgeDocumentRequest>
{
    // The name and the version identify the definition. The name is the counted unit of the licence.
    public string WorkflowName => "AcknowledgeDocument";

    public string WorkflowVersion => "1.0.0";

    public string DisplayName => "Acknowledge a document";

    // The roles that may work the workflow's tasks, unless a task names its own roles.
    public IReadOnlyCollection<string> WorkflowRoles { get; } = ["staff"];

    public WorkflowSpec<AcknowledgeDocumentRequest> Spec { get; } = WorkflowSpec.For<AcknowledgeDocumentRequest>()
        // The workflow state, built from the start request ("start.*").
        .InitializeState(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("documentId", WorkflowExpr.Path("start.documentId")),
                WorkflowExpr.Prop("recipient", WorkflowExpr.Path("start.recipient"))))
        // The task: name (unique in the workflow), type (the form a client shows), route.
        .AddTask(
            WorkflowHumanTask.For<AcknowledgeDocumentRequest>(
                    "Acknowledge document",
                    "DocumentAcknowledgement",
                    "documents/acknowledge")
                .WithPayload(
                    WorkflowExpr.Obj(
                        WorkflowExpr.Prop("documentId", WorkflowExpr.Path("state.documentId"))))
                .OnComplete(flow => flow.Complete()))
        // The first steps: open the task and wait.
        .StartWith(flow => flow.ActivateTask("Acknowledge document"))
        .Build();

    public IReadOnlyCollection<WorkflowTaskDescriptor> Tasks => Spec.TaskDescriptors;
}
MemberMeaning
WorkflowNameThe identity of the workflow. Clients start it by this name; the licence counts it. Choose it once.
WorkflowVersionThe version of the definition. Change it when the steps change (Upgrading).
DisplayNameThe title in lists and diagrams.
WorkflowRolesThe roles that may work the workflow’s tasks, unless a task names its own roles.
SpecThe definition: the initial state, the tasks and the first steps.
TasksThe task descriptors, always Spec.TaskDescriptors.

The builder has three levels:

  1. WorkflowSpec.For<TStartRequest>() returns a spec builder: InitializeState, AddTask, StartWith, Build.
  2. WorkflowHumanTask.For<TStartRequest>(name, type, route, roles) builds a task: WithPayload, WithRoles, WithRoute, WithTimeout, SingleOpen, OnComplete.
  3. Inside StartWith and OnComplete, a flow builder adds steps.

The start request and the state

The start request is a plain class. The start payload of POST /api/workflow/start binds to it when you register the workflow with its type (AddWorkflowRegistration<TWorkflow, TStartRequest>()).

/// <summary>The start request: the input contract of the workflow.</summary>
public sealed class AcknowledgeDocumentRequest
{
    /// <summary>The business key. Instances and tasks can be searched by it.</summary>
    [WorkflowBusinessId]
    public string DocumentId { get; set; } = string.Empty;

    public string Recipient { get; set; } = string.Empty;
}

InitializeState builds the first workflow state from the start request. Keep in the state only what the steps need; the state is stored with every change and has a size limit (WorkflowRuntime:StateJson:MaxBytes, 256 KiB by default).

Human tasks

A task is declared with AddTask and opened with ActivateTask. Declaring and opening are separate, so the same task can be opened from several places, including its own OnComplete.

.AddTask(
    WorkflowHumanTask.For<DocumentReviewRequest>("Review document", "DocumentReview", "documents/review", ["reviewer"])
        .WithPayload(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("documentId", WorkflowExpr.Path("state.documentId")),
                WorkflowExpr.Prop("title", WorkflowExpr.Path("state.title")),
                WorkflowExpr.Prop("revision", WorkflowExpr.Path("state.revision"))))
        // Three days to act; then the escalation task opens and the review task closes.
        .WithTimeout(259200, timedOut => timedOut.ActivateTask("Escalated review"))
        .OnComplete(flow => flow
            .Set("decision", WorkflowExpr.Path("payload.decision"))
            .WhenExpression(
                "Changes requested?",
                WorkflowExpr.Eq(WorkflowExpr.Path("payload.decision"), WorkflowExpr.String("changes")),
                changes => changes
                    .Set("comments", WorkflowExpr.Path("payload.comments"))
                    .ActivateTask("Revise document"),
                final => final.Complete())))
.AddTask(
    WorkflowHumanTask.For<DocumentReviewRequest>("Revise document", "DocumentRevision", "documents/revise", ["author"])
        .WithPayload(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("documentId", WorkflowExpr.Path("state.documentId")),
                WorkflowExpr.Prop("comments", WorkflowExpr.Path("state.comments"))))
        // The revised document goes back to the reviewer: the same task opens again.
        .OnComplete(flow => flow
            .Set("revision", WorkflowExpr.Func("add", WorkflowExpr.Path("state.revision"), WorkflowExpr.Number(1)))
            .ActivateTask("Review document")))
Builder methodEffect
For<T>(name, type, route, roles)The task name (unique in the workflow), the task type your client renders, a route, and optional task roles that replace the workflow roles for this task
WithPayload(expression)The data the task shows
WithRoles(...), WithRoute(expression)Roles and route after the fact; the route can be computed
WithTimeout(seconds)A deadline: the task summary gets deadlineUtc
WithTimeout(seconds, whenTimeout)A deadline and the steps to run when it passes; the task closes as Expired
SingleOpen(slot)At most one open or assigned task per instance and slot
OnComplete(flow => ...)The steps after a completion; payload.* is the completion payload

Cases:

Decisions

WhenExpression branches on any boolean expression; the whenElse branch is optional.

// A decision on any boolean expression.
.WhenExpression(
    "Critical?",
    WorkflowExpr.Eq(WorkflowExpr.Path("state.severity"), WorkflowExpr.String("critical")),
    critical => critical
        .Call("Page on-call engineer", new EndpointAddress("paging", "/pages"),
            WorkflowExpr.Obj(WorkflowExpr.Prop("incidentId", WorkflowExpr.Path("state.incidentId"))))

WhenStateFlag is the short form for a boolean state value, WhenStateEquals for a state value and WhenPayloadEquals for a field of the completion payload:

// A nested decision on a boolean state value.
.WhenStateFlag(
    "customerFacing",
    true,
    "Customer facing?",
    customerFacing => customerFacing
        .Call("Notify support desk", new HttpAddress("support", "/notifications"),
            WorkflowExpr.Obj(WorkflowExpr.Prop("incidentId", WorkflowExpr.Path("state.incidentId"))))
        .Complete(),
    internalOnly => internalOnly.Complete()),
// A decision on a field of the completion payload ("payload.action").
.OnComplete(flow => flow
    .WhenPayloadEquals(
        "action",
        "escalate",
        "Escalate?",
        escalate => escalate
            .Set("severity", WorkflowExpr.String("critical"))
            .Call("Page on-call engineer", new EndpointAddress("paging", "/pages"),
                WorkflowExpr.Obj(WorkflowExpr.Prop("incidentId", WorkflowExpr.Path("state.incidentId"))))
            .Complete(),
        close => close.Complete())))

The decisionName is the label of the decision in diagrams. Branches nest without limit.

Calling services

Call sends a payload to an address and continues. The typed overloads (Call<TResponse>, Call<TRequest, TResponse>) keep the response under result.<resultKey>, or result.<stepName> without a key, also when the call has a failure or timeout branch; the untyped Call keeps no response. A failure or timeout branch replaces the default behaviour (the step fails: a start or a task completion answers with an error, and a step resumed by a signal retries the signal); a step timeout is the timeoutSeconds argument of the call (Calling services):

// An `endpoint` call: the service name resolves through WorkflowEndpointTransport:Services.
// The response is kept under "result.stock" for the following steps.
.Call<object>(
    "Read stock level",
    new EndpointAddress("inventory", "/items/stock-level"),
    WorkflowExpr.Obj(WorkflowExpr.Prop("sku", WorkflowExpr.Path("state.sku"))),
    resultKey: "stock")
.Set("onHand", WorkflowExpr.Path("result.stock.onHand"))
// An `http` call: the target resolves through WorkflowHttpTransport:Targets.
// A failed or unreachable call runs whenFailure, a timed-out call whenTimeout;
// "result.lastFailure" describes the failure.
.Call(
    "Place purchase order",
    new HttpAddress("purchasing", "/purchase-orders"),
    WorkflowExpr.Obj(
        WorkflowExpr.Prop("sku", WorkflowExpr.Path("state.sku")),
        WorkflowExpr.Prop("quantity", WorkflowExpr.Path("state.reorderQuantity"))),
    whenFailure: failed => failed
        .Set("orderFailure", WorkflowExpr.Path("result.lastFailure.message"))
        .ActivateTask("Place order manually"),
    whenTimeout: timedOut => timedOut
        .Set("orderFailure", WorkflowExpr.String("the purchasing service did not answer"))
        .ActivateTask("Place order manually"))

In the branch, result.lastFailure describes the failure. The address kinds, their configuration, the fields of lastFailure and the timeouts are in Calling services.

Loops

Repeat runs its body while a condition holds, up to a maximum number of iterations, and keeps the iteration number in a state key:

// Up to three attempts while the registration is not confirmed, one minute apart.
.Repeat(
    "Register supplier",
    3,
    "registrationAttempt",
    WorkflowExpr.Ne(WorkflowExpr.Path("state.registration"), WorkflowExpr.String("confirmed")),
    attempt => attempt
        .Call<object>(
            "Submit registration",
            new EndpointAddress("erp", "/suppliers"),
            WorkflowExpr.Obj(WorkflowExpr.Prop("supplierId", WorkflowExpr.Path("state.supplierId"))),
            resultKey: "registration")
        .Set("registration", WorkflowExpr.Path("result.registration.status"))
        .Wait("Pause before the next attempt", WorkflowExpr.String("00:01:00")))

The condition is evaluated before each iteration. The maximum is required: a loop always ends.

Parallel branches

Fork runs its branches concurrently and continues after the last branch has finished. A TerminateFork() step inside a branch ends the fork early: tasks still open in the other branches are cancelled and the flow continues after the fork.

// Three branches run concurrently; the flow continues when all three have finished.
.Fork(
    "Run onboarding checks",
    credit => credit.Call("Check credit", new EndpointAddress("risk", "/credit-checks"),
        WorkflowExpr.Obj(WorkflowExpr.Prop("supplierId", WorkflowExpr.Path("state.supplierId")))),
    sanctions => sanctions.Call("Screen supplier", new EndpointAddress("risk", "/screenings"),
        WorkflowExpr.Obj(WorkflowExpr.Prop("supplierId", WorkflowExpr.Path("state.supplierId")))),
    tax => tax.Call("Validate tax number", new HttpAddress("tax-registry", "/validations"),
        WorkflowExpr.Obj(WorkflowExpr.Prop("supplierId", WorkflowExpr.Path("state.supplierId")))))

Timers

Wait(stepName, delayExpression) pauses the instance. The expression evaluates to:

Any other value fails the step with an error that names the accepted forms; so does "00:01", which has no seconds. The instance resumes when the signal pump receives the due timer; the host process can restart in between.

External signals

An external-signal step pauses the instance until a caller raises the signal for it; the signal’s payload is kept under result.<resultKey>. The builder method is WaitForSignal(stepName, signalName, resultKey); it builds and runs, with the warning WF021 (the workflow is left out of the build-time bundle, see What the analyzer rejects). In canonical JSON the step is an external-signal.

// The instance waits until a client raises the signal "documents-uploaded" for it; the signal's
// payload is kept under "result.documents".
.WaitForSignal("Wait for documents", "documents-uploaded", "documents")
.Set("documentCount", WorkflowExpr.Path("result.documents.count"))

A client raises the signal with POST /api/workflow/signals/raise (Human tasks and the HTTP API).

Child workflows

SubWorkflow runs another registered workflow and waits for it; the child’s result is kept under result.<resultKey>. ContinueWith starts another workflow as an independent instance and goes on at once:

// Inline: the parent waits until PackOrder completes; its result is under "result.packing".
.SubWorkflow(
    "Pack order",
    new WorkflowReference("PackOrder"),
    WorkflowExpr.Obj(
        WorkflowExpr.Prop("orderId", WorkflowExpr.Path("state.orderId")),
        WorkflowExpr.Prop("warehouse", WorkflowExpr.Path("state.warehouse"))),
    resultKey: "packing")
.Set("parcels", WorkflowExpr.Path("result.packing.parcels"))
// Fire and forget: SendInvoice starts as a new instance and the parent completes.
.ContinueWith(
    "Send invoice",
    new WorkflowReference("SendInvoice"),
    WorkflowExpr.Obj(WorkflowExpr.Prop("orderId", WorkflowExpr.Path("state.orderId"))))
SubWorkflowContinueWith
The parentWaits for the childContinues at once
The child’s resultAvailable to the parentNot returned
A failure of the childRuns the parent’s whenFailure branch, when givenDoes not affect the parent
Typical useA reusable part of a processA follow-up process with its own lifetime

Register the child workflows in the same host.

Maps

A map step runs a body once per item of a collection, with bounded concurrency and a deterministic fan-in. Each item is in the state under the item state key while its body runs. The builder method Map(...) builds and runs with the warning WF021, like WaitForSignal; in canonical JSON the step is a map.

// One body per line, at most four at a time; each line is under "state.line" while its body runs,
// and the results are collected under "result.updates".
.Map(
    "Update prices",
    WorkflowExpr.Path("state.lines"),
    WorkflowExpr.Path("state.line.sku"),
    WorkflowExpr.Path("result.update"),
    "line",
    4,
    500,
    65536,
    body => body.Call<object>(
        "Set price",
        new EndpointAddress("pricing", "/prices"),
        WorkflowExpr.Obj(
            WorkflowExpr.Prop("sku", WorkflowExpr.Path("state.line.sku")),
            WorkflowExpr.Prop("price", WorkflowExpr.Path("state.line.price"))),
        resultKey: "update"),
    resultKey: "updates")
FieldMeaning
maxConcurrencyItems in flight at once; must not exceed maxItems or WorkflowRuntime:MaxMapConcurrency (default 8)
maxItemsItems allowed in the collection; must not exceed WorkflowRuntime:MaxMapItems (default 512)
maxAggregateStateBytesThe size limit of the collected results
fanInPolicyALL_SUCCEEDED (default), COLLECT_ALL, or MIN_SUCCEEDED with minimumSucceeded
failurePolicyFAIL_FAST (default), COLLECT_PARTIAL or ROUTE_MANUAL

A map whose bounds break these rules fails with MAP_BOUND_INVALID; the validator also refuses a maxConcurrency above maxItems (WFVAL094).

Maps need the durable stores and services (Durable execution).

The business reference in a step

A start request with [WorkflowBusinessId] sets the business reference at the start. To set or change it later, use SetBusinessReference with a WorkflowBusinessReferenceDeclaration: a key expression and named part expressions.

Expressions

All values in a definition are expressions, built with WorkflowExpr:

// Literals.
public static readonly WorkflowExpressionDefinition Text = WorkflowExpr.String("Northwind Traders");
public static readonly WorkflowExpressionDefinition Quantity = WorkflowExpr.Number(12);
public static readonly WorkflowExpressionDefinition Price = WorkflowExpr.Number(19.95m);
public static readonly WorkflowExpressionDefinition Flag = WorkflowExpr.Bool(true);
public static readonly WorkflowExpressionDefinition Nothing = WorkflowExpr.Null();

// Paths: start.* (the start request), state.* (the workflow state), payload.* (the completion
// payload of the task being completed), result.* (the results kept with a result key).
public static readonly WorkflowExpressionDefinition Customer = WorkflowExpr.Path("start.customer");
public static readonly WorkflowExpressionDefinition FirstLineSku = WorkflowExpr.Path("state.lines.0.sku");
// Comparison, logical and arithmetic operators.
public static readonly WorkflowExpressionDefinition LargeExportOrder = WorkflowExpr.And(
    WorkflowExpr.Gt(WorkflowExpr.Path("state.amount"), WorkflowExpr.Number(10000)),
    WorkflowExpr.Eq(WorkflowExpr.Path("state.region"), WorkflowExpr.String("export")));

public static readonly WorkflowExpressionDefinition NotCancelled =
    WorkflowExpr.Not(WorkflowExpr.Eq(WorkflowExpr.Path("state.status"), WorkflowExpr.String("cancelled")));

public static readonly WorkflowExpressionDefinition WithinBudget =
    WorkflowExpr.Lte(WorkflowExpr.Path("state.amount"), WorkflowExpr.Path("state.budget"));

public static readonly WorkflowExpressionDefinition LineTotal = WorkflowExpr.Binary(
    "multiply", WorkflowExpr.Path("state.quantity"), WorkflowExpr.Path("state.unitPrice"));
// Functions of the core catalogue (GET /api/workflow/functions lists the installed ones).
public static readonly WorkflowExpressionDefinition ContactName = WorkflowExpr.Func(
    "coalesce", WorkflowExpr.Path("payload.contactName"), WorkflowExpr.Path("state.contactName"), WorkflowExpr.String("unknown"));

public static readonly WorkflowExpressionDefinition Reference = WorkflowExpr.Func(
    "concat", WorkflowExpr.String("ORD-"), WorkflowExpr.Func("upper", WorkflowExpr.Path("state.region")));

public static readonly WorkflowExpressionDefinition Priority = WorkflowExpr.Func(
    "if",
    WorkflowExpr.Gte(WorkflowExpr.Path("state.amount"), WorkflowExpr.Number(5000)),
    WorkflowExpr.String("high"),
    WorkflowExpr.String("normal"));

public static readonly WorkflowExpressionDefinition HasComment = WorkflowExpr.Not(
    WorkflowExpr.Func("isNullOrWhiteSpace", WorkflowExpr.Path("payload.comment")));

// The add function sums any number of arguments.
public static readonly WorkflowExpressionDefinition Total = WorkflowExpr.Func(
    "add", WorkflowExpr.Path("state.netAmount"), WorkflowExpr.Path("state.tax"));
GroupBuilders
LiteralsString, Number, Bool, Null, FromValue
StructureObj with Prop, Array, Group
PathsPath("start.…"), Path("state.…"), Path("payload.…"), Path("result.…"), Path("businessReference.key") and businessReference.parts.…; array elements by index (state.lines.0.sku)
ComparisonEq, Ne, Gt, Gte, Lt, Lte
LogicAnd, Or, Not
ArithmeticBinary("add" / "subtract" / "multiply" / "divide", left, right), and Func("add", values…) for the sum of any number of values
FunctionsFunc(name, arguments…)

The core functions are coalesce, concat, add, first, if, isNullOrWhiteSpace, length, mergeObjects, upper, split, join, selectManyPath, wherePathEqualsOrdinal, replaceByPathOrdinal and findPath. GET /api/workflow/functions lists the functions a host has installed, with their arguments and examples. A host adds functions of its own with a provider (lesson 8).

The binary operators are eq, ne, and, or, gt, gte, lt, lte, add, subtract, multiply and divide; the only unary operator is not. The validator refuses any other operator (WFVAL102, WFVAL103); operator names are case-sensitive. Arithmetic is decimal: a whole-number result of whole-number operands is a whole number, any other result a decimal (7 divided by 2 is 3.5). Numeric strings are accepted; a missing or non-numeric operand, a division by zero or an overflow fails the step. In C#, WorkflowExpr.Binary builds with the warning WF021 (the workflow is compiled when the publisher starts), while WorkflowExpr.Func("add", ...) is bundled at build time.

Shared helpers

A helper method keeps a payload shape or a step sequence in one place. The analyzer and its generator walk into helpers of the same project, with two limits: a helper takes no parameters that end up in the definition (no string arguments for names or literals), and addresses are written in place, as new EndpointAddress("literal", "literal").

/// <summary>Expression helpers shared by several workflows.</summary>
public static class Payloads
{
    /// <summary>The customer reference that every customer-service call sends.</summary>
    public static WorkflowExpressionDefinition CustomerReference() =>
        WorkflowExpr.Obj(WorkflowExpr.Prop("customerId", WorkflowExpr.Path("state.customerId")));
}
/// <summary>A step sequence several workflows end with: notify the customer, then complete.</summary>
public static class FlowExtensions
{
    public static WorkflowFlowBuilder<TStartRequest> NotifyCustomerAndComplete<TStartRequest>(
        this WorkflowFlowBuilder<TStartRequest> flow)
        where TStartRequest : class
    {
        return flow
            .Call("Notify customer", new HttpAddress("notifications", "/messages"), Payloads.CustomerReference())
            .Complete();
    }
}

What the analyzer rejects

The analyzer checks that a Spec can be written as a canonical definition; its errors fail the build. Its source generator writes the definition into your assembly at build time and reports a warning for a workflow it cannot write:

ConstructIn C#Canonical JSON
WaitForSignal with a signal nameBuilds with WF021external-signal
MapBuilds with WF021map
ExternalActivityBuilds with WF021external-activity
QueryGraphql and QueryGraphql<TResponse>, with or without a variables expressionBuilds with WF021call-transport with a graphql address, the variables as the payload expression
QueryGraphql with a variables delegateNot publishable: a delegate has no canonical formThe variables expression
An address from a helper or a constantBuilds with WF021The address in place
A delegate (Run, a signal name, payload, delay or condition given as context => ...)Its body is checked like any code: a body that breaks a rule fails the build (WF001 to WF006), a clean body builds with WF021. The runtime compiler rejects every delegate (WFCD codes): the publisher cannot publish the workflow and a host on Stella.Engine that registers the workflow stops at startThe expression form

The rules, with examples and fixes, are in the analyzer reference; the canonical definitions page summarises them.

Registering workflows

public static class OrderApprovalRegistrations
{
    /// <summary>
    /// Registers the order approval workflow with its start request type, so that a start payload is
    /// bound to <c>OrderApprovalRequest</c> and its <c>[WorkflowBusinessId]</c> property becomes the
    /// business key.
    /// </summary>
    public static IServiceCollection AddOrderApprovalWorkflow(this IServiceCollection services)
        => services.AddWorkflowRegistration<OrderApprovalWorkflow, OrderApprovalRequest>();
}
OverloadUse
AddWorkflowRegistration<TWorkflow, TStartRequest>()The usual form: binds the start payload to the request class and reads [WorkflowBusinessId]; refuses a request type that is not the workflow’s
AddWorkflowRegistration<TWorkflow>()The same for an IDeclarativeWorkflow<T>: the request type is taken from T
AddWorkflowRegistration<TWorkflow, TStartRequest, THandler>()A workflow with its own execution handler class (the in-process provider)

A registered workflow is recorded in the Designated Workflow ledger the first time the engine sees it (Licensing).

Pitfalls