Configuration reference
Every configuration key the Workflow packages read, with its default. Keys are read from the host’s IConfiguration, so any source works: appsettings.json, environment variables, user secrets, a secret store such as Vault. In an environment variable, : becomes __ (WorkflowRuntime__DefaultProvider). Each section names the options classes its keys bind to; their pages in the .NET API reference list the properties with their types.
Engine and runtime
Options classes: WorkflowRuntimeOptions, WorkflowStateJsonPolicyOptionsand WorkflowEngineOptions.
Read by AddWorkflowEngineCoreServices.
| Key | Default | Meaning |
|---|---|---|
WorkflowRuntime:DefaultProvider | Stella.Engine | The runtime provider: Stella.Engine or Stella.InProcess. Stella.InProcess runs no fork, map, external activity, timer, external signal or task deadline; the host checks the choice at start (Hosting) |
WorkflowRuntime:EnabledProviders | empty (all) | When not empty, only these providers may run |
WorkflowRuntime:MaxMapConcurrency | 8 | The highest concurrency of a map (1 to 64, checked at start) |
WorkflowRuntime:MaxMapItems | 512 | The most items of a map (1 to 10000, checked at start) |
WORKFLOW_MAX_MAP_CONCURRENCY, WORKFLOW_MAX_MAP_ITEMS | none | Override the two keys above |
WorkflowRuntime:StateJson:MaxBytes | 262144 | The largest workflow state (16384 to 1048576, checked at start) |
WORKFLOW_STATE_JSON_MAX_BYTES | none | Overrides MaxBytes |
WorkflowRuntime:StateJson:MaxDepth | 16 | The deepest nesting of the state |
WorkflowRuntime:StateJson:MaxArrayItems | 256 | The longest array in the state |
WorkflowRuntime:StateJson:MaxStringLength | 4096 | The longest string in the state |
WorkflowRuntime:StateJson:ForbiddenFragments | secret, ciphertext, accesstoken, bearertoken, presignedurl, temporaryurl, mapitems, attempthistory | State property names that contain one of these fragments are refused. Configured values are added to the defaults; a default cannot be removed |
WorkflowEngine:MaxConcurrentSignalHandlers | processor count | Signal pump workers |
WorkflowEngine:ExecutionTimeoutSeconds | none (off) | A timeout for one start, completion or resume |
WorkflowEngine:GracefulShutdownTimeoutSeconds | 30 | The time the pump gets to finish at shutdown |
WorkflowEngine:MaxInlineWaitSeconds | 10 | The longest wait in a request for work that continues at once; 0 or less does not wait |
Store selection
Options classes: WorkflowBackendOptionsand WorkflowSignalDriverOptions.
| Key | Default | Meaning |
|---|---|---|
WorkflowBackend:Provider | Postgres | Postgres or Mongo |
WorkflowSignalDriver:Provider | Native | Native or Redis |
ValidateWorkflowProviderRegistrations fails the start when the selected store or driver was not registered.
PostgreSQL store
Options class: PostgresWorkflowBackendOptions.
Read by AddWorkflowPostgresDataStore when the provider is Postgres.
| Key | Default | Meaning |
|---|---|---|
STELLAOPS_POSTGRES_WORKFLOW_CONNECTION | none (required) | The connection string. The host stops at start without it |
WorkflowBackend:Postgres:ApplicationName | stellaops-workflow | The application name of the connections |
WorkflowBackend:Postgres:Pooling | true | Connection pooling |
WorkflowBackend:Postgres:MinPoolSize | 1 | |
WorkflowBackend:Postgres:MaxPoolSize | 100 | |
WorkflowBackend:Postgres:ConnectionIdleLifetimeSeconds | 300 | |
WorkflowBackend:Postgres:NotifyChannel | workflow_signal | The LISTEN/NOTIFY channel of signals |
WorkflowBackend:Postgres:WakeOutboxNotifyChannel | workflow_signal_wake_outbox | The channel of the wake outbox |
WorkflowBackend:Postgres:ClaimTimeoutSeconds | 60 | The lease of a claimed signal |
WorkflowBackend:Postgres:BlockingWaitSeconds | 30 | The longest wait for a wake-up |
Code options (AddWorkflowPostgresDataStore(configuration, options => ...)): ApplyMigrationsOnStartup (true), RegisterDefinitionStore (true), RegisterWakeOutbox (true).
MongoDB store
Options class: WorkflowStoreMongoOptions.
Read by AddWorkflowMongoDataStore when the provider is Mongo.
| Key | Default | Meaning |
|---|---|---|
WorkflowBackend:Mongo:ConnectionStringName | WorkflowMongo | The name under ConnectionStrings |
ConnectionStrings:WorkflowMongo | none (required) | The connection string |
WorkflowBackend:Mongo:DatabaseName | stellaops_workflow_store | The database |
WorkflowBackend:Mongo:ClaimTimeoutSeconds | 60 | The lease of a claimed signal |
WorkflowBackend:Mongo:BlockingWaitSeconds | 30 | The longest wait for a wake-up |
WorkflowBackend:Mongo:<Name>CollectionName | workflow_* | Each collection name, for example InstancesCollectionName (workflow_instances), TasksCollectionName (workflow_tasks), DefinitionsCollectionName (workflow_definitions), FirstSeenWorkflowsCollectionName (workflow_first_seen_workflows) |
Redis signal driver
Options class: RedisWorkflowSignalDriverOptions.
Read by AddWorkflowRedisSignaling when the driver is Redis. The host registers the IConnectionMultiplexer (Persistence and signals).
| Key | Default | Meaning |
|---|---|---|
WorkflowSignalDriver:Redis:ChannelName | stellaops:workflow:signals | The Redis channel |
WorkflowSignalDriver:Redis:BlockingWaitSeconds | 30 | The longest wait for a wake-up |
Signal pump
Options class: WorkflowAqOptions.
| Key | Default | Meaning |
|---|---|---|
WorkflowAq:MaxDeliveryAttempts | 10 | Deliveries before a signal is dead-lettered (at least 1), counted by the store across all nodes and restarts (Persistence and signals) |
WorkflowAq:ConsumerName | WORKFLOW_SERVICE | The consumer name in signal claims; each worker adds -<n>, the same on every node |
The pump’s wait for a signal is the BlockingWaitSeconds of the store or of the Redis driver, above.
Retention
Options classes: WorkflowRetentionOptionsand WorkflowRetentionHostedJobOptions.
| Key | Default | Meaning |
|---|---|---|
WorkflowRetention:OpenStaleAfterDays | 30 | Days after which an inactive open instance is marked stale |
WorkflowRetention:CompletedPurgeAfterDays | 180 | Days after completion before an instance is purged |
WorkflowRetentionHostedJob:Enabled | true | Run the retention job |
WorkflowRetentionHostedJob:RunOnStartup | false | Run it once at start |
WorkflowRetentionHostedJob:InitialDelay | 00:05:00 | The delay before the first run, when not at start |
WorkflowRetentionHostedJob:Interval | 1.00:00:00 | The interval between runs |
WorkflowRetentionHostedJob:LockName | workflow.retention | The host lock that keeps one node at a time |
WorkflowRetentionHostedJob:LockLease | 02:00:00 | The lease of that lock |
Actor claims
Options class: WorkflowActorClaimOptions.
Read by AddWorkflowAuthorization.
| Key | Default | Meaning |
|---|---|---|
WorkflowAuthorization:ActorIdClaimTypes | sub, then the name identifier claim | Claim types read for the actor ID of a task action, in order |
WorkflowAuthorization:RoleClaimTypes | the role claim and role | Claim types whose values are the actor’s roles |
Task permissions
Options class: GenericAssignmentPermissionOptions.
| Key | Default | Meaning |
|---|---|---|
GenericAssignmentPermissions:AdminRoles | empty | Roles that may perform every task action |
GenericAssignmentPermissions:AssigneeCanComplete | false | The current assignee may complete without one of the task’s roles |
Transports
HTTP and endpoint
Options classes: WorkflowHttpTransportOptions, WorkflowHttpTargetOptionsand WorkflowEndpointTransportOptions.
Read by AddWorkflowHttpTransport, once at registration.
| Key | Default | Meaning |
|---|---|---|
WorkflowHttpTransport:TimeoutSeconds | 30 | One attempt; the whole call gets three times this value |
WorkflowHttpTransport:RetryCount | 3 | Retries, exponential from one second with jitter |
WorkflowHttpTransport:Targets:<name>:Url | none | The base URL of an http target |
WorkflowHttpTransport:Targets:<name>:Headers:<header> | none | Headers of every request to the target |
WorkflowEndpointTransport:Services:<name>:Url | none | The base URL of an endpoint service |
WorkflowEndpointTransport:Services:<name>:Headers:<header> | none | Headers of every request to the service |
Target and service names are not case-sensitive.
GraphQL
Options classes: WorkflowGraphqlTransportOptionsand WorkflowGraphqlTargetOptions.
Read by AddWorkflowGraphqlTransport, once at registration.
| Key | Default | Meaning |
|---|---|---|
WorkflowGraphqlTransport:TimeoutSeconds | 30 | One attempt; the whole call gets three times this value |
WorkflowGraphqlTransport:RetryCount | 3 | Retries |
WorkflowGraphqlTransport:Targets:<name>:Url | none | The GraphQL endpoint (target names are case-sensitive) |
WorkflowGraphqlTransport:Targets:<name>:Headers:<header> | none | Headers |
RabbitMQ transport
Options classes: WorkflowRabbitTransportOptionsand WorkflowRabbitTlsOptions.
Read by AddWorkflowRabbitTransport, once at registration.
| Key | Default | Meaning |
|---|---|---|
WorkflowRabbitTransport:HostName | none (required for a call) | The broker |
WorkflowRabbitTransport:Port | 5672 | |
WorkflowRabbitTransport:VirtualHost | / | |
WorkflowRabbitTransport:UserName, Password | none: the RabbitMQ client’s default user applies | Credentials; set both |
WorkflowRabbitTransport:ClientProvidedName | stellaops-workflow | The connection name shown by the broker |
WorkflowRabbitTransport:Tls:Enabled | false | TLS to the broker |
WorkflowRabbitTransport:Tls:ServerName | the host name | The name the certificate must carry |
WorkflowRabbitTransport:Tls:ClientCertificatePath, ClientCertificatePassphrase | none | A client certificate |
WorkflowRabbitTransport:ConfirmTimeoutSeconds | 30 | The wait for the broker’s publisher confirm |
WorkflowRabbitTransport:ReplyTimeoutSeconds | 30 | The wait for a command reply |
WorkflowRabbitTransport:ReplyQueueMode | DirectReplyTo | DirectReplyTo or ExclusiveQueue |
WorkflowRabbitTransport:ChannelPoolSize | 8 | Channels per host |
WorkflowRabbitTransport:CommandHeaderName | command | Header framing: the header with the command name |
WorkflowRabbitTransport:EnvelopeCommandField, EnvelopeCorrelationIdField, EnvelopePayloadField | command, correlationId, payload | Envelope framing: the field names |
WorkflowRabbitTransport:ReplyPayloadField, ReplyErrorField, ReplyErrorHeaderName | payload, error, error | The reply’s payload and error |
Rendering
Options class: WorkflowRenderingOptions.
| Key | Default | Meaning |
|---|---|---|
WorkflowRendering:LayoutProvider | ElkSharp | The layout engine of diagrams |
Licence
Options class: WorkflowComponentLicenceOptions.
| Key | Default | Meaning |
|---|---|---|
StellaOps:ComponentLicence:Path | none | A licence file, or a directory of licence files |
StellaOps:ComponentLicence:Key | none | The same signed record as one base64 line; set either Path or Key |
StellaOps:ComponentLicence:InstallationId | none | The Installation identifier the licence record names |
STELLAOPS_VENDOR_TRUST_ROOTS (environment) | none | A directory with a vendor trust-root set that replaces the embedded published root, for key rotation |
An invalid value never stops the host (Licensing).
Durable execution
Options classes: WorkflowDurableStartOptions, WorkflowRegisteredSignalOptions, WorkflowExternalActivityRegistryOptions, WorkflowDurableMaintenanceOptionsand WorkflowConsoleOptions.
Read by AddWorkflowEngineDurableServices and, for the registry, AddWorkflowEngineCoreServices.
| Key | Default | Meaning |
|---|---|---|
WorkflowDurableStart:Definitions:<code> | empty | The audience allowed to start the definition durably |
WorkflowRegisteredSignals:ServiceSubjects:<subject> | empty | The audience of an authenticated service subject |
WorkflowRegisteredSignals:Signals:<code> | empty | The only audience that may wait for and raise the signal |
WorkflowExternalActivityRegistry:ManifestPath or ManifestJson | none | The signed activity registry; without it the registry is empty |
WorkflowExternalActivityRegistry:ManifestSha256 | none | The SHA-256 of the canonical manifest (required with a manifest) |
WorkflowExternalActivityRegistry:SignaturePath or SignatureBase64 | none | The signature |
WorkflowExternalActivityRegistry:PublicKeyPath or PublicKeyPem | none | The public key; a relative path is resolved against the application directory |
WorkflowMaintenance:CompactionRetentionDays | 30 | Retention of delivered outbox and inbox rows (7 to 3650) |
WorkflowConsole:SafeStateKeys | status, currentStage, progress, outcome, safeCode | State keys the execution console shows |
WorkflowConsole:TechnicalRedactedFragments | secret, token, password, prompt, documentBody, signedUrl, bearer | Fragments the console redacts |
For WorkflowConsole:SafeStateKeys and TechnicalRedactedFragments, configured values are added to the defaults; a default cannot be removed.
Publisher
Options class: WorkflowPublisherOptions.
Bound by AddWorkflowPublisher; AddWorkflowPublisher(section, assemblies) reads another section instead. The options of an enabled publisher are checked when the host starts: Endpoint an absolute http or https URL (unless DryRun), CommandPath starting with /, Timeout positive, MaxRetriesPerWorkflow and RetryBaseDelay not negative; an option outside these rules stops the host (Governed activation and publishing).
| Key | Default |
|---|---|
Enabled | true |
Endpoint | none |
CommandPath | /api/workflow/definitions/import |
ServiceName, AuthToken | none |
Timeout | 00:00:30 |
MaxRetriesPerWorkflow, RetryBaseDelay | 3, 00:00:02 |
FailOnError, DryRun | false, false |
A complete example
{
"WorkflowBackend": { "Provider": "Postgres", "Postgres": { "MaxPoolSize": 50 } },
"WorkflowSignalDriver": { "Provider": "Native" },
"WorkflowRuntime": { "DefaultProvider": "Stella.Engine" },
"WorkflowRetention": { "OpenStaleAfterDays": 60, "CompletedPurgeAfterDays": 365 },
"GenericAssignmentPermissions": { "AdminRoles": [ "workflow-admin" ] },
"WorkflowEndpointTransport": { "Services": { "fulfilment": { "Url": "<base URL of the fulfilment service>" } } },
"WorkflowHttpTransport": { "Targets": { "payments": { "Url": "<base URL of the payments API>" } } },
"StellaOps": { "ComponentLicence": { "Path": "<licence file or directory>" } }
}
STELLAOPS_POSTGRES_WORKFLOW_CONNECTION="Host=db.contoso.example;Database=workflow;Username=workflow_app;Password=<password>"
WorkflowHttpTransport__Targets__payments__Headers__Authorization="Bearer <token>"
