Workflow engine overview

Stella Ops Workflow is a set of libraries that let you run an orchestration engine inside your own services, with horizontal scaling, fine-grained control and extensions. This page explains the concepts the other pages use; read it once before you write your first workflow.

What the engine does

The engine runs long-lived business processes inside your .NET application. A process can wait for a person (a human task), call your services, branch, loop, run branches in parallel, wait for a timer or an external signal, and start other workflows. The engine keeps every instance, task and state change in your database, so a process survives restarts and can run for days or months.

The engine is a library, not a server. You add it to an ASP.NET Core or worker host, choose a store, register your workflows and, if you want the HTTP API, map the endpoints. Getting started builds a complete host.

How it differs from Temporal, Camunda, Elsa and others: Comparison.

Definitions

A workflow definition describes one process. It has:

You write a definition in one of two forms:

FormWhat it isWhen to use it
C#A class that implements IDeclarativeWorkflow<TStartRequest> and builds a WorkflowSpec<TStartRequest> with the fluent builderYour workflows ship with your application and are registered in code
Canonical JSONA document with the schema identifier stellaops.workflow.definition/v1You store, version, review, export or deploy definitions as data

The two forms are equivalent: the engine compiles every C# definition to its canonical JSON form, and the JSON form is what it validates, stores, renders and hashes. See Defining workflows and Canonical definitions.

Instances, state and the business reference

An instance is one run of a definition. Starting a workflow creates an instance with an identifier, binds the start request (start.*) and builds the workflow state (state.*), a JSON object that the steps read and change.

An instance is Open until a complete step ends it, then Completed. The retention job marks open instances that are inactive for too long as Stale and purges completed ones after a retention period (Operations).

A business reference is the key of your business object (an order number, a claim number), attached to the instance and its tasks. You search instances and tasks by it. Mark a start-request property with [WorkflowBusinessId], or set the reference in a step.

Human tasks

A human task is a step that waits for a person. A task has a name (unique in the workflow), a task type (the form your client shows), a route, roles, a payload (the data the form shows) and an optional deadline. When a person completes the task, the completion payload (payload.*) is available to the task’s OnComplete steps.

A task moves through Open, Assigned, then Completed. A task whose deadline passes ends Expired (its timeout branch runs), and a task still open in a fork branch that another branch ends with TerminateFork ends Cancelled. Retention marks the tasks of a stale instance Stale. Five actions act on a task: assign to oneself, assign to another user, assign to roles, release, complete. Who may perform each is decided by a permission evaluator from the task’s effective roles and the caller’s roles (Human tasks and the HTTP API).

Steps

KindBuilder methodCanonical $type
Change the stateSet, SetIfHasValueset-state
Set the business referenceSetBusinessReferenceassign-business-reference
Open a human taskActivateTaskactivate-task
Call a serviceCall, QueryGraphqlcall-transport
BranchWhenExpression, WhenStateFlag, WhenStateEquals, WhenPayloadEqualsdecision
LoopRepeatrepeat
Run branches in parallelFork, TerminateForkfork, terminate-fork
Wait for a durationWaittimer
Wait for an external signalWaitForSignalexternal-signal
Run another workflow and waitSubWorkflowsub-workflow
Start another workflow and continueContinueWithcontinue-with-workflow
Fan out over a collectionMapmap
Hand work to a registered external handlerExternalActivityexternal-activity
End the instanceCompletecomplete

Expressions

Steps compute values with expressions: literals, paths, objects, arrays, operators and functions. A path reads one of four roots:

RootContains
startThe start request
stateThe workflow state
payloadThe completion payload of the task being completed
resultThe results kept by a step with a result key, and result.lastFailure in a failure or timeout branch

In C# you build expressions with WorkflowExpr (WorkflowExpr.Path("state.amount")). Expressions are data, so the definition stays portable and the analyzer can check it at compile time. See Defining workflows.

Address kinds

A call-transport step names an address. There are four kinds, each implemented by a transport package:

KindCallsPackage
endpointA named service: base URL from configuration, method and path from the definitionStellaOps.Workflow.Transport.Http
httpA named HTTP targetStellaOps.Workflow.Transport.Http
graphqlA named GraphQL target, with a query and an operation nameStellaOps.Workflow.Transport.GraphQL
rabbitA RabbitMQ exchange and routing key, with an optional command and replyStellaOps.Workflow.Transport.RabbitMq

Register the package of every kind your workflows use. Without it, a host on Stella.Engine, the default, stops at start with WFIMP010; on Stella.InProcess, every call of that kind fails with an error that names the missing transport. See Calling services.

Signals and the signal pump

A step that waits (a timer, an external signal, a task deadline, a child workflow) ends the current transaction and leaves a signal for later. The signal pump, a hosted service, receives due signals and resumes their instances. A signal that keeps failing goes to the dead letters, where an operator can inspect and replay it.

On PostgreSQL the signals use the database and its LISTEN/NOTIFY; on MongoDB, the database and its change streams. Redis can replace the wake-up notification on either store. See Persistence and signals.

Runtime providers

The engine has two runtime providers:

ProviderNameRuns a builder workflow from
Canonical engine (the default)Stella.EngineIts canonical definition
In-processStella.InProcessIts C# specification

Stella.InProcess runs no fork, map, external activity, timer, external signal or task deadline; a host that selects it with a workflow that uses one stops at start with a message naming the step.

WorkflowRuntime:DefaultProvider selects the provider. A start and a task completion use the provider configured at that moment; only the resumption from a signal (a timer, an external signal, a child workflow) uses the provider that started the instance. Do not change the provider while instances are open (Hosting).

Code-registered and stored definitions

The engine runs the workflows that the host registers in code. The definition store (in the same database) keeps canonical definitions as versioned data: an import stores a version inactive, and a separate, audited activation makes it the active version. Stored definitions serve review, export, rendering, deployment to other installations and the durable start, which admits only an active stored version. See Governed activation and publishing.

Durable execution

Durable execution adds exactly-once start by message, registered signals with deadlines, external activities handed to registered handlers through a transactional outbox, bounded fan-out (maps), child-execution links and an execution history. You enable it with two more registrations and a message transport of your own. See Durable execution.

Designated Workflows

The Workflow licence counts Designated Workflows: the distinct workflow names an installation has ever registered in code or stored. The count is cumulative: a name counts from its first sighting and keeps counting; versions do not count. The engine records each name in a ledger, shows the count in its readiness report and on GET /api/workflow/designated-workflows, and never refuses or stops anything because of the count. See Licensing.

Next