What is different
Most workflow engines run workflows, wait for people and call services; Standard features covers those. This page covers the design choices that set Stella Ops Workflow apart: where the engine runs, what a workflow is, how versions reach production, and how the engine behaves on several nodes. Each section says what the choice gives you, when it matters, shows a compiled example, and names its configuration, cases and pitfalls. Comparison sets these choices against other engines, with sources.
The engine runs inside your services
What. The engine, its store adapter and its HTTP endpoints are packages in your own ASP.NET Core or worker host. There is no workflow server to install, operate or upgrade: your service and its database are the whole footprint. When. You want workflows next to the code and data they serve, on infrastructure you already run.
// The engine and its PostgreSQL store. The store reads its connection string from
// STELLAOPS_POSTGRES_WORKFLOW_CONNECTION and creates the `workflow` schema at start.
builder.Services.AddWorkflowEngineCoreServices(builder.Configuration);
builder.Services.AddWorkflowPostgresDataStore(builder.Configuration);
// The signal pump, the retention job and the licence monitor, with its `licence` health entry.
builder.Services.AddWorkflowEngineHostedServices();
// Fails at start when WorkflowBackend:Provider or WorkflowSignalDriver:Provider names a backend
// or a signal driver that no registered library provides.
builder.Services.ValidateWorkflowProviderRegistrations(builder.Configuration);
Configuration. The engine’s database connection, and nothing else to start:
STELLAOPS_POSTGRES_WORKFLOW_CONNECTION="Host=db.contoso.example;Database=workflow;Username=workflow_app;Password=<password>"
Cases. An order service that owns its approval workflows; a back-office host with many workflows; a worker without HTTP endpoints that only runs signals.
Pitfalls. The engine shares your host’s resources: size the signal pump workers and the database pool together (Operations).
More: Hosting.
C# that compiles to a canonical definition
What. You write a workflow in C#, and the engine compiles it to a canonical JSON document that it validates, stores, hashes, renders and exports. A Roslyn analyzer fails the build for most C# that cannot become that document, at the line that causes it; a Run step or another C# delegate whose body breaks no rule builds with the warning WF021, and a Stella.Engine host that registers such a workflow stops when it starts. When. You want the comfort of C# and a definition that can be reviewed, diffed and stored as data.
[Test]
public void TheDefinitionCompilesToAValidCanonicalDefinition()
{
var compilation = WorkflowCanonicalDefinitionCompiler.Compile(new DocumentReviewWorkflow());
Assert.That(compilation.Succeeded, Is.True, string.Join("; ", compilation.Diagnostics.Select(d => d.Message)));
// The engine's validator: the schema, the expressions, and the modules the definition needs.
using var services = new ServiceCollection()
.AddLogging()
.AddWorkflowEngineCoreServices(new ConfigurationBuilder().Build())
.BuildServiceProvider();
using var scope = services.CreateScope();
var validation = scope.ServiceProvider.GetRequiredService<WorkflowCanonicalDefinitionService>()
.Validate(new WorkflowCanonicalValidateRequest
{
CanonicalDefinitionJson = WorkflowCanonicalJsonSerializer.Serialize(compilation.Definition!),
});
var issues = validation.SchemaIssues.Concat(validation.SemanticIssues).Concat(validation.ModuleIssues);
Assert.That(validation.IsValid, Is.True, string.Join("; ", issues.Select(issue => $"{issue.Path}: {issue.Message}")));
}
Configuration. None: the analyzer comes with StellaOps.Workflow.Abstractions. A build that treats warnings as errors keeps WF021 a warning with <WarningsNotAsErrors>$(WarningsNotAsErrors);WF021</WarningsNotAsErrors>.
Cases. Review a workflow change as a JSON diff; validate a definition in CI; write the JSON with the export helper of lesson 9.
Pitfalls. C# control flow, async, or a call into a library you do not own inside Spec (Analyzer).
More: Canonical definitions.
No replay of workflow code
What. The engine executes the canonical definition and stores each instance’s state, tasks and pending signals. It does not replay your code to rebuild an instance, so it places no determinism rule on your services, clocks or libraries; the analyzer limits what a definition may contain instead. When. Long-running processes whose code changes while instances are open.
/// <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.
Cases. Add a step for new instances while old instances finish on their version (lesson 11).
Pitfalls. An instance resumes with the definition of its own version: keep that version registered until no instance of it is open.
More: Upgrading.
Immutable versions, audited activation and rollback
What. A stored version never changes: other content under the same version is refused. An import stores a version inactive; a separate activation makes it active, fenced on the version and hash you expect to be active, and recorded in an audit table with the actor and the reason. Going back to an older version is an explicit rollback. When. Definitions reach production through a release process, or several administrators manage one installation.
/// <summary>
/// Publishes the workflows compiled into the given assemblies to a workflow host's import endpoint at
/// start. Each new version is stored inactive on the target. The options come from the host's
/// WorkflowPublisher configuration section and are checked when the host starts.
/// </summary>
public static IServiceCollection AddWorkflowDefinitionPublishing(
this IServiceCollection services,
params System.Reflection.Assembly[] workflowAssemblies)
{
services.AddWorkflowPublisher(workflowAssemblies);
return services;
}
Configuration. The publisher’s target and token:
{ "WorkflowPublisher": { "Endpoint": "<base URL of the workflow host>", "FailOnError": true } }
WorkflowPublisher__AuthToken=<token>
Cases. A pipeline imports, an administrator activates; two administrators activate at once and one gets 409 WORKFLOW_DEFINITION_ACTIVATION_FENCE_LOST; a rollback names the audit entry it reverses.
Pitfalls. Importing changed content under an existing version answers 409 WORKFLOW_DEFINITION_VERSION_HASH_CONFLICT: raise the version instead.
More: Governed activation and publishing.
Task roles, runtime roles and deadlines in the definition
What. A task carries its roles, its payload, its deadline and the steps after it, in the definition. Roles can be computed when the task opens. Who may act is decided by a permission evaluator you can replace. When. Approval processes whose rules belong with the process, not with a separate task tool.
// The approvers of the request's cost centre, for example "approver-cc-410", computed from the
// state when the task opens. They replace the task roles and the workflow roles for this task.
.StartWith(flow => flow.ActivateTask(
"Approve purchase",
WorkflowExpr.Array(
WorkflowExpr.Func("concat", WorkflowExpr.String("approver-"), WorkflowExpr.Path("state.costCentre")))))
Configuration.
{ "GenericAssignmentPermissions": { "AdminRoles": [ "workflow-admin" ], "AssigneeCanComplete": false } }
Cases. Approvers per cost centre; escalation after three days; your own rules in an IWorkflowAssignmentPermissionEvaluator.
Pitfalls. Runtime roles are computed once, when the task opens.
More: Human tasks and the HTTP API.
The HTTP API acts as the caller
What. Every route needs a token and a scope, and task actions, imports and activations act as the token’s caller: the actor ID and roles come from its claims, never from the body. When. A task list or a back office calls the engine on behalf of users.
// JWT bearer tokens (Authentication:Schemes:Bearer). The workflow scopes travel in the `scope`
// claim; MapInboundClaims = false keeps the claim names of the token.
builder.Services
.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddJwtBearer(options => options.MapInboundClaims = false);
// The three Workflow policies, and the actor of a task action taken from the token: the actor ID from
// `sub` and the roles from the `role` claims (WorkflowAuthorization:ActorIdClaimTypes, RoleClaimTypes).
builder.Services.AddWorkflowAuthorization();
Configuration.
{ "WorkflowAuthorization": { "ActorIdClaimTypes": [ "sub" ], "RoleClaimTypes": [ "role" ] } }
Cases. A user completes a task through your front end with their own token; a service account imports definitions with the admin scope.
Pitfalls. A token without an actor ID claim gets 403 WorkflowActorUnresolved on task actions.
More: Hosting, HTTP API reference.
Leased signals and version checks on several nodes
What. Every wait is a stored signal. A node claims a due signal with a lease (on PostgreSQL with for update skip locked), and every change to an instance is checked against the instance’s version; a signal that loses the check is applied again on the new version. The delivery count is kept by the store across nodes and restarts. When. Several nodes on one database, without a coordinator.
/// <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.
{ "WorkflowBackend": { "Postgres": { "ClaimTimeoutSeconds": 60 } }, "WorkflowAq": { "MaxDeliveryAttempts": 10 } }
Cases. Two nodes behind a load balancer; a node that stops while it holds a signal (the lease expires and another node takes it).
Pitfalls. Size the database and its connection pool for all nodes together (Operations).
More: Persistence and signals.
Exactly-once start and the outbox
What. Durable execution starts an instance from a message exactly once: the execution, its first history event, the receipt and the outgoing messages are written in one transaction, and a repeated start returns the recorded result. Messages leave through an outbox. When. Starts arrive from a message bus that may deliver twice, or a process spans several services.
/// <summary>
/// Durable execution: durable start, registered signals, external activities, maps, child links and
/// history (AddWorkflowEngineDurableServices), and the lane handlers with the outbox dispatcher
/// (AddWorkflowDurableMessaging), which publishes through the host's message transport.
/// </summary>
public static IServiceCollection AddWorkflowDurableExecution<TPublisher>(this IServiceCollection services, IConfiguration configuration)
where TPublisher : class, IWorkflowOutboxMessagePublisher
{
services.AddWorkflowEngineDurableServices(configuration);
services.AddWorkflowDurableMessaging();
services.AddSingleton<IWorkflowOutboxMessagePublisher, TPublisher>();
return services;
}
Configuration. The definitions that may start durably, with the audience allowed to start them:
{ "WorkflowDurableStart": { "Definitions": { "OrderApproval": "order-service" } } }
Cases. An order event starts an approval once, however often it is delivered; registered signals race a deadline; external activities hand work to other services.
Pitfalls. A durable start needs an active managed definition in the store; a definition imported without the managed fields keeps its starts waiting.
More: Durable execution.
Transports as packages
What. Each address kind is a package: endpoint and http, graphql, rabbit. A host installs the kinds its workflows use, and a definition names services and targets, never URLs. When. The same definition runs in every environment, and a host carries only the clients it needs.
/// <summary>Registers a transport for each address kind the host's workflows use.</summary>
public static IServiceCollection AddWorkflowTransports(this IServiceCollection services, IConfiguration configuration)
{
// `endpoint` (WorkflowEndpointTransport:Services) and `http` (WorkflowHttpTransport:Targets).
services.AddWorkflowHttpTransport(configuration);
// `graphql` (WorkflowGraphqlTransport:Targets).
services.AddWorkflowGraphqlTransport(configuration);
// `rabbit` (WorkflowRabbitTransport): one broker connection per host.
services.AddWorkflowRabbitTransport(configuration);
return services;
}
Configuration.
{ "WorkflowHttpTransport": { "Targets": { "purchasing": { "Url": "<base URL of the purchasing API>" } } } }
Cases. Your services by name; an external API with its own headers; RabbitMQ commands with a correlated reply; a transport of your own behind the transport interfaces.
Pitfalls. A workflow that uses a kind the host lacks stops a Stella.Engine host at start with WFIMP010.
More: Calling services.
Two runtime providers, checked at start
What. Stella.Engine, the default, runs the canonical definition with every expression-based step. Stella.InProcess runs the C# specification in the process, including inline Run code, without forks, maps, external activities, timers, external signals or task deadlines. The host checks the choice against its workflows when it starts and stops with a message naming the workflow, the step and the provider. When. Choose Stella.InProcess only for a workflow that needs inline C# code.
{ "WorkflowRuntime": { "DefaultProvider": "Stella.Engine" } }
WorkflowRuntime__DefaultProvider=Stella.Engine
Cases. The default for every host; Stella.InProcess for a short workflow with inline code and no waits.
Pitfalls. A workflow with a Run step or a C# delegate stops a Stella.Engine host at start.
More: Hosting.
Diagrams from the definition
What. The engine draws any workflow as positioned nodes and edges or as SVG, from its definition, and can highlight an instance’s progress. When. Documentation, reviews, and a view of where an instance stands.
/// <summary>Renders a registered workflow as an SVG diagram, outside any HTTP request.</summary>
public static class DiagramExport
{
public static async Task<string> RenderSvgAsync(
IServiceProvider services,
string workflowName,
CancellationToken cancellationToken = default)
{
// The canonical definition of the registered workflow, compiled into a graph of nodes and edges.
var definition = services.GetRequiredService<IWorkflowRuntimeDefinitionStore>().GetRequiredDefinition(workflowName);
var graph = services.GetRequiredService<IWorkflowRenderGraphCompiler>().Compile(definition);
// The layout engine named by WorkflowRendering:LayoutProvider (ElkSharp when unset).
var engine = services.GetRequiredService<IWorkflowRenderLayoutEngineResolver>().Resolve();
var layout = await engine.LayoutAsync(
graph,
new WorkflowRenderLayoutRequest
{
Direction = WorkflowRenderLayoutDirection.LeftToRight,
Effort = WorkflowRenderLayoutEffort.Balanced,
},
cancellationToken);
// The SVG renderer adds the licence notice when the host passes none.
return services.GetRequiredService<IWorkflowRenderSvgRenderer>()
.RenderSvg(layout, definition.Descriptor.DisplayName, licenceNotice: null);
}
}
Configuration.
{ "WorkflowRendering": { "LayoutProvider": "ElkSharp" } }
Cases. An SVG per workflow in a documentation build; an instance diagram in a support tool through GET /api/workflow/diagrams/{name}.
Pitfalls. The diagram shows the definition; a step’s runtime details are in the instance.
More: Rendering.