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.
- Horizontal scaling. Several instances of your service share one store: due signals are claimed with a lease, each change of a workflow instance is checked against its version, and the retention job runs on one node at a time (Persistence and signals).
- Control. Immutable versions with a governed activation, durable execution, human tasks with roles, and scope-based authorization of every HTTP operation (Governed activation and publishing, Hosting).
- Extensions. Stores, signal drivers and transports are plugin libraries; expression functions, task permission rules, actor resolution and transports are public interfaces you can implement (Hosting).
How it differs from Temporal, Camunda, Elsa and others: Comparison.
Definitions
A workflow definition describes one process. It has:
- a name (
OrderApproval), which identifies the workflow; - a version (
1.0.0); a name has many versions over time; - a display name, the workflow roles that may work its tasks, a start request type, the tasks and the steps that run from the start.
You write a definition in one of two forms:
| Form | What it is | When to use it |
|---|---|---|
| C# | A class that implements IDeclarativeWorkflow<TStartRequest> and builds a WorkflowSpec<TStartRequest> with the fluent builder | Your workflows ship with your application and are registered in code |
| Canonical JSON | A document with the schema identifier stellaops.workflow.definition/v1 | You 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
| Kind | Builder method | Canonical $type |
|---|---|---|
| Change the state | Set, SetIfHasValue | set-state |
| Set the business reference | SetBusinessReference | assign-business-reference |
| Open a human task | ActivateTask | activate-task |
| Call a service | Call, QueryGraphql | call-transport |
| Branch | WhenExpression, WhenStateFlag, WhenStateEquals, WhenPayloadEquals | decision |
| Loop | Repeat | repeat |
| Run branches in parallel | Fork, TerminateFork | fork, terminate-fork |
| Wait for a duration | Wait | timer |
| Wait for an external signal | WaitForSignal | external-signal |
| Run another workflow and wait | SubWorkflow | sub-workflow |
| Start another workflow and continue | ContinueWith | continue-with-workflow |
| Fan out over a collection | Map | map |
| Hand work to a registered external handler | ExternalActivity | external-activity |
| End the instance | Complete | complete |
Expressions
Steps compute values with expressions: literals, paths, objects, arrays, operators and functions. A path reads one of four roots:
| Root | Contains |
|---|---|
start | The start request |
state | The workflow state |
payload | The completion payload of the task being completed |
result | The 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:
| Kind | Calls | Package |
|---|---|---|
endpoint | A named service: base URL from configuration, method and path from the definition | StellaOps.Workflow.Transport.Http |
http | A named HTTP target | StellaOps.Workflow.Transport.Http |
graphql | A named GraphQL target, with a query and an operation name | StellaOps.Workflow.Transport.GraphQL |
rabbit | A RabbitMQ exchange and routing key, with an optional command and reply | StellaOps.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:
| Provider | Name | Runs a builder workflow from |
|---|---|---|
| Canonical engine (the default) | Stella.Engine | Its canonical definition |
| In-process | Stella.InProcess | Its 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
- Getting started
- Hosting
- .NET API reference: one page per package, with its types and members
