Standard features
The features on this page are the ones you expect from any workflow engine: definitions, human tasks, service calls, timers, signals, sub-workflows, parallel work, retries, failure handling, persistence, several nodes, versions and metrics. Each section says what the feature does and when to use it, shows a compiled example, lists its configuration, and gives typical cases and pitfalls. The guide named at the end of a section has the details.
For the features that set Stella Ops Workflow apart, read What is different.
Defining workflows
What. A workflow is a C# class that implements IDeclarativeWorkflow<TStartRequest>. Its Spec is built with a fluent builder from expressions, and the engine compiles it to a canonical JSON definition. When. For every process the engine runs.
/// <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;
}
Configuration. Register each workflow with its start request type:
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>();
}
Cases. A library of workflows shared by several hosts; one workflow per business process; helpers for payloads and repeated steps (lesson 7).
Pitfalls. C# control flow, async, or a call into another library inside Spec does not compile: the analyzer reports it (Analyzer). Express decisions and values with the builder and WorkflowExpr.
More: Defining workflows.
Human tasks and the task API
What. A task waits for a person. It has roles, a payload to show, an optional deadline, and the steps that run when it is completed. When. Approvals, reviews, manual corrections, anything a person decides.
.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())))
Configuration. Administrators and the assignee rule:
{ "GenericAssignmentPermissions": { "AdminRoles": [ "workflow-admin" ], "AssigneeCanComplete": false } }
GenericAssignmentPermissions__AdminRoles__0=workflow-admin
GenericAssignmentPermissions__AssigneeCanComplete=false
Cases. Send a task back for changes; escalate on a deadline; compute the approvers from the state (lesson 4); build a task list on GET /api/workflow/tasks.
Pitfalls. The actor of a task action is the token’s caller, never a field of the body. A completed, expired or cancelled task refuses further actions with 409.
More: Human tasks and the HTTP API, HTTP API reference.
Calling services
What. A Call step sends a payload to an address and keeps the answer under a result key. The address names a service or a target; configuration supplies the URL. When. Every interaction with another system.
// 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"))
Configuration.
{ "WorkflowEndpointTransport": { "Services": { "inventory": { "Url": "<base URL of the inventory service>" } } } }
WorkflowEndpointTransport__Services__inventory__Url=https://inventory.contoso.example/api/
Cases. Your own services by name (endpoint), external HTTP APIs (http), GraphQL (graphql), RabbitMQ commands and publishes (rabbit).
Pitfalls. A URL in the definition; a missing transport package (the host stops at start with WFIMP010); a retried call that is not idempotent.
More: Calling services.
Timers and deadlines
What. Wait pauses an instance until a time; WithTimeout gives a task a deadline and the steps to run when it passes. When. Pauses between attempts, reminders, escalations, service-level deadlines.
// 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")))
Configuration. Timers are signals in the store, so they survive restarts. The signal pump resumes them; WorkflowEngine:MaxConcurrentSignalHandlers sets its workers (default: the processor count).
Cases. A pause before a retry, as above; a three-day review deadline that opens an escalation task (lesson 4).
Pitfalls. A host without AddWorkflowEngineHostedServices runs no signal pump, so no timer fires. Stella.InProcess runs no timer or task deadline.
More: Defining workflows, Persistence and signals.
Signals
What. WaitForSignal waits for a named event from outside; POST /api/workflow/signals/raise delivers it with a payload. When. A document upload, a payment confirmation, a callback from a partner.
// 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"))
Configuration. The signal driver wakes the pump when a signal is stored:
{ "WorkflowSignalDriver": { "Provider": "Native" } }
WorkflowSignalDriver__Provider=Native
Cases. Wait for one event; race an event against a deadline with durable execution (Durable execution).
Pitfalls. A raised signal is queued and delivered by the pump; read the instance afterwards rather than expecting the result in the raise response.
More: Persistence and signals, HTTP API reference.
Sub-workflows
What. SubWorkflow starts another workflow and waits for its result; ContinueWith starts one and moves on. When. A step that is a process of its own, reused by several workflows.
// 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"))
Configuration. Register the child workflows in the same host.
Cases. Packing as a child of fulfilment; invoicing as a follow-up that runs on its own.
Pitfalls. Each child is a workflow of its own: its own versions and its own Designated Workflow.
More: Lesson 5.
Forks and maps
What. Fork runs fixed branches in parallel and continues when all have finished; Map runs one body for each item of a collection, with a concurrency limit. When. Independent checks; the same call for every line of an order.
// 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")))))
// 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")
Configuration.
{ "WorkflowRuntime": { "MaxMapConcurrency": 8, "MaxMapItems": 512 } }
WorkflowRuntime__MaxMapConcurrency=8
WorkflowRuntime__MaxMapItems=512
Cases. Credit, sanctions and tax checks in parallel; a price update per order line.
Pitfalls. A map needs the durable services (AddWorkflowEngineDurableServices). A map whose concurrency or item limit is above these settings fails with MAP_BOUND_INVALID, and a collection longer than the map’s own item limit fails with MAP_ITEM_LIMIT_EXCEEDED; split the collection or raise the limits.
More: Defining workflows, Durable execution.
Retries
What. Three layers: the HTTP and GraphQL transports retry a failed attempt; Repeat runs steps again while a condition holds; the signal pump retries a failed resume up to a delivery limit, then dead-letters it. When. Transient failures, polling a status, recovering from an outage.
The Repeat example under Timers and deadlines tries a registration up to three times, one minute apart.
Configuration.
{
"WorkflowHttpTransport": { "RetryCount": 3, "TimeoutSeconds": 30 },
"WorkflowAq": { "MaxDeliveryAttempts": 10 }
}
WorkflowHttpTransport__RetryCount=3
WorkflowAq__MaxDeliveryAttempts=10
Cases. A flaky partner API; a registration that is confirmed later; replaying a dead-lettered signal after the cause is fixed (Operations).
Pitfalls. Retries repeat side effects: make the called operations idempotent, for example with a request ID in the payload.
More: Calling services, Operations.
Timeouts and failure branches
What. A call can name the steps to run when it fails (whenFailure) and when it times out (whenTimeout), and set its own timeout (timeoutSeconds). The branch reads result.lastFailure. When. Every call whose failure the process can handle: a manual task, a compensation, a message.
// 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"))
Configuration. The step timeout is the timeoutSeconds argument of the call (one hour without it); the transport limits each attempt:
{ "WorkflowHttpTransport": { "TimeoutSeconds": 30 } }
WorkflowHttpTransport__TimeoutSeconds=30
Cases. Open a manual task when an order cannot be placed; continue without an optional enrichment.
Pitfalls. Without a branch, a failure in a start or a task completion answers the request with an error (502, or 500 for a timeout); in a step resumed by a signal, the signal is retried and then dead-lettered.
More: Calling services.
Persistence
What. The engine keeps instances, tasks, signals, definitions and the Designated Workflow ledger in one store: PostgreSQL or MongoDB. The PostgreSQL store creates and migrates its schema at start. When. Always: the store is what makes a workflow survive restarts.
/// <summary>
/// Both store libraries are registered; WorkflowBackend:Provider ("Postgres" or "Mongo") decides which
/// one takes effect, so one build serves either store.
/// </summary>
public static IServiceCollection AddWorkflowStores(this IServiceCollection services, IConfiguration configuration)
{
services.AddWorkflowEngineCoreServices(configuration);
services.AddWorkflowPostgresDataStore(configuration);
services.AddWorkflowMongoDataStore(configuration);
services.ValidateWorkflowProviderRegistrations(configuration);
return services;
}
Configuration.
STELLAOPS_POSTGRES_WORKFLOW_CONNECTION="Host=db.contoso.example;Database=workflow;Username=workflow_app;Password=<password>"
WorkflowBackend__Provider=Postgres
Cases. PostgreSQL for most hosts; MongoDB where your services already run on it; a schema applied by your own migration tool (Persistence and signals).
Pitfalls. Two releases of the engine on one store at the same time (Upgrading); a connection string in a committed file.
More: Persistence and signals.
Several nodes
What. Run the same host on several machines against one store. Each node claims due work with a lease, and every change to an instance is checked against its version. When. Throughput and availability.
/// <summary>
/// Redis carries the wake-up notifications between nodes (WorkflowSignalDriver:Provider = "Redis"); the
/// signals themselves stay in the store. The host provides the Redis connection; the driver announces
/// each stored signal on the Redis channel once the store's transaction commits.
/// </summary>
public static IServiceCollection AddWorkflowRedisWakeUps(this IServiceCollection services, IConfiguration configuration)
{
services.AddSingleton<IConnectionMultiplexer>(_ =>
ConnectionMultiplexer.Connect(configuration["Redis:Configuration"]
?? throw new InvalidOperationException("Set Redis:Configuration.")));
services.AddWorkflowRedisSignaling(configuration);
return services;
}
Configuration. Every node uses the same store and the same consumer name; Redis wake-ups are optional:
{ "WorkflowSignalDriver": { "Provider": "Redis" }, "WorkflowAq": { "ConsumerName": "WORKFLOW_SERVICE" } }
Cases. Two nodes behind a load balancer; more pump workers per node (WorkflowEngine:MaxConcurrentSignalHandlers) with a larger connection pool.
Pitfalls. Nodes of different releases on one store; a pool smaller than the pump workers.
More: Persistence and signals, Operations.
Versioning
What. A workflow name keeps its instances; a version is one shape of its steps. An instance keeps the version that started it, and new starts take the highest version. When. Every change to a workflow that has open instances.
/// <summary>
/// Registers both versions. New starts take 2.0.0, the highest version; an instance started on
/// 1.0.0 resumes with the 1.0.0 definition. Remove the 1.0.0 registration once no instance of it
/// is open.
/// </summary>
public static IServiceCollection AddReturnRequestWorkflows(this IServiceCollection services)
{
services.AddWorkflowRegistration<ReturnRequestWorkflowV1, ReturnRequest>();
services.AddWorkflowRegistration<ReturnRequestWorkflowV2, ReturnRequest>();
return services;
}
Configuration. None: the registrations decide. Stored definitions are imported as new versions and activated in an audited step (Governed activation and publishing).
Cases. A new approval step for new requests while old requests finish unchanged; a rollback of a stored version.
Pitfalls. Editing a version in place; removing an old registration while instances of it are open.
Metrics
What. The meter StellaOps.Workflow counts finished instances (workflow.execution.terminal, with the labels definition and outcome), and the licence meter reports the Designated Workflow count. When. Dashboards, alerts, and tests.
/// <summary>
/// Counts the finished workflow instances of this process from the engine's metrics: the counter
/// <c>workflow.execution.terminal</c> of the meter <c>StellaOps.Workflow</c>, labelled
/// <c>definition</c> and <c>outcome</c>. A test, a health probe or a dashboard of your own can read it
/// without an OpenTelemetry pipeline.
/// </summary>
public sealed class FinishedInstanceCounter : IDisposable
{
private readonly MeterListener listener = new();
private readonly ConcurrentDictionary<(string Definition, string Outcome), long> counts = new();
public FinishedInstanceCounter()
{
listener.InstrumentPublished = (instrument, meterListener) =>
{
if (instrument.Meter.Name == "StellaOps.Workflow" && instrument.Name == "workflow.execution.terminal")
{
meterListener.EnableMeasurementEvents(instrument);
}
};
listener.SetMeasurementEventCallback<long>((_, value, tags, _) =>
{
string definition = string.Empty, outcome = string.Empty;
foreach (var tag in tags)
{
if (tag.Key == "definition") definition = tag.Value?.ToString() ?? string.Empty;
if (tag.Key == "outcome") outcome = tag.Value?.ToString() ?? string.Empty;
}
counts.AddOrUpdate((definition, outcome), value, (_, total) => total + value);
});
listener.Start();
}
/// <summary>The instances of a workflow that finished with an outcome, for example <c>Completed</c>.</summary>
public long Finished(string definition, string outcome = "Completed")
=> counts.TryGetValue((definition, outcome), out var count) ? count : 0;
public void Dispose() => listener.Dispose();
}
Configuration. Export with OpenTelemetry: add the meters StellaOps.Workflow and StellaOps.Workflow.Licence and the activity source StellaOps.Workflow to your meter and tracer providers.
Cases. Finished instances per workflow and outcome; dead letters from the signal pump statistics (GET /api/workflow/signals/pump/stats); a test that asserts an instance finished.
Pitfalls. The counter counts finished instances only; open and waiting instances are read from the instance list.
More: Operations.
