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.

KeyDefaultMeaning
WorkflowRuntime:DefaultProviderStella.EngineThe 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:EnabledProvidersempty (all)When not empty, only these providers may run
WorkflowRuntime:MaxMapConcurrency8The highest concurrency of a map (1 to 64, checked at start)
WorkflowRuntime:MaxMapItems512The most items of a map (1 to 10000, checked at start)
WORKFLOW_MAX_MAP_CONCURRENCY, WORKFLOW_MAX_MAP_ITEMSnoneOverride the two keys above
WorkflowRuntime:StateJson:MaxBytes262144The largest workflow state (16384 to 1048576, checked at start)
WORKFLOW_STATE_JSON_MAX_BYTESnoneOverrides MaxBytes
WorkflowRuntime:StateJson:MaxDepth16The deepest nesting of the state
WorkflowRuntime:StateJson:MaxArrayItems256The longest array in the state
WorkflowRuntime:StateJson:MaxStringLength4096The longest string in the state
WorkflowRuntime:StateJson:ForbiddenFragmentssecret, ciphertext, accesstoken, bearertoken, presignedurl, temporaryurl, mapitems, attempthistoryState property names that contain one of these fragments are refused. Configured values are added to the defaults; a default cannot be removed
WorkflowEngine:MaxConcurrentSignalHandlersprocessor countSignal pump workers
WorkflowEngine:ExecutionTimeoutSecondsnone (off)A timeout for one start, completion or resume
WorkflowEngine:GracefulShutdownTimeoutSeconds30The time the pump gets to finish at shutdown
WorkflowEngine:MaxInlineWaitSeconds10The longest wait in a request for work that continues at once; 0 or less does not wait

Store selection

Options classes: WorkflowBackendOptionsand WorkflowSignalDriverOptions.

KeyDefaultMeaning
WorkflowBackend:ProviderPostgresPostgres or Mongo
WorkflowSignalDriver:ProviderNativeNative 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.

KeyDefaultMeaning
STELLAOPS_POSTGRES_WORKFLOW_CONNECTIONnone (required)The connection string. The host stops at start without it
WorkflowBackend:Postgres:ApplicationNamestellaops-workflowThe application name of the connections
WorkflowBackend:Postgres:PoolingtrueConnection pooling
WorkflowBackend:Postgres:MinPoolSize1
WorkflowBackend:Postgres:MaxPoolSize100
WorkflowBackend:Postgres:ConnectionIdleLifetimeSeconds300
WorkflowBackend:Postgres:NotifyChannelworkflow_signalThe LISTEN/NOTIFY channel of signals
WorkflowBackend:Postgres:WakeOutboxNotifyChannelworkflow_signal_wake_outboxThe channel of the wake outbox
WorkflowBackend:Postgres:ClaimTimeoutSeconds60The lease of a claimed signal
WorkflowBackend:Postgres:BlockingWaitSeconds30The 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.

KeyDefaultMeaning
WorkflowBackend:Mongo:ConnectionStringNameWorkflowMongoThe name under ConnectionStrings
ConnectionStrings:WorkflowMongonone (required)The connection string
WorkflowBackend:Mongo:DatabaseNamestellaops_workflow_storeThe database
WorkflowBackend:Mongo:ClaimTimeoutSeconds60The lease of a claimed signal
WorkflowBackend:Mongo:BlockingWaitSeconds30The longest wait for a wake-up
WorkflowBackend:Mongo:<Name>CollectionNameworkflow_*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).

KeyDefaultMeaning
WorkflowSignalDriver:Redis:ChannelNamestellaops:workflow:signalsThe Redis channel
WorkflowSignalDriver:Redis:BlockingWaitSeconds30The longest wait for a wake-up

Signal pump

Options class: WorkflowAqOptions.

KeyDefaultMeaning
WorkflowAq:MaxDeliveryAttempts10Deliveries before a signal is dead-lettered (at least 1), counted by the store across all nodes and restarts (Persistence and signals)
WorkflowAq:ConsumerNameWORKFLOW_SERVICEThe 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.

KeyDefaultMeaning
WorkflowRetention:OpenStaleAfterDays30Days after which an inactive open instance is marked stale
WorkflowRetention:CompletedPurgeAfterDays180Days after completion before an instance is purged
WorkflowRetentionHostedJob:EnabledtrueRun the retention job
WorkflowRetentionHostedJob:RunOnStartupfalseRun it once at start
WorkflowRetentionHostedJob:InitialDelay00:05:00The delay before the first run, when not at start
WorkflowRetentionHostedJob:Interval1.00:00:00The interval between runs
WorkflowRetentionHostedJob:LockNameworkflow.retentionThe host lock that keeps one node at a time
WorkflowRetentionHostedJob:LockLease02:00:00The lease of that lock

Actor claims

Options class: WorkflowActorClaimOptions.

Read by AddWorkflowAuthorization.

KeyDefaultMeaning
WorkflowAuthorization:ActorIdClaimTypessub, then the name identifier claimClaim types read for the actor ID of a task action, in order
WorkflowAuthorization:RoleClaimTypesthe role claim and roleClaim types whose values are the actor’s roles

Task permissions

Options class: GenericAssignmentPermissionOptions.

KeyDefaultMeaning
GenericAssignmentPermissions:AdminRolesemptyRoles that may perform every task action
GenericAssignmentPermissions:AssigneeCanCompletefalseThe 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.

KeyDefaultMeaning
WorkflowHttpTransport:TimeoutSeconds30One attempt; the whole call gets three times this value
WorkflowHttpTransport:RetryCount3Retries, exponential from one second with jitter
WorkflowHttpTransport:Targets:<name>:UrlnoneThe base URL of an http target
WorkflowHttpTransport:Targets:<name>:Headers:<header>noneHeaders of every request to the target
WorkflowEndpointTransport:Services:<name>:UrlnoneThe base URL of an endpoint service
WorkflowEndpointTransport:Services:<name>:Headers:<header>noneHeaders 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.

KeyDefaultMeaning
WorkflowGraphqlTransport:TimeoutSeconds30One attempt; the whole call gets three times this value
WorkflowGraphqlTransport:RetryCount3Retries
WorkflowGraphqlTransport:Targets:<name>:UrlnoneThe GraphQL endpoint (target names are case-sensitive)
WorkflowGraphqlTransport:Targets:<name>:Headers:<header>noneHeaders

RabbitMQ transport

Options classes: WorkflowRabbitTransportOptionsand WorkflowRabbitTlsOptions.

Read by AddWorkflowRabbitTransport, once at registration.

KeyDefaultMeaning
WorkflowRabbitTransport:HostNamenone (required for a call)The broker
WorkflowRabbitTransport:Port5672
WorkflowRabbitTransport:VirtualHost/
WorkflowRabbitTransport:UserName, Passwordnone: the RabbitMQ client’s default user appliesCredentials; set both
WorkflowRabbitTransport:ClientProvidedNamestellaops-workflowThe connection name shown by the broker
WorkflowRabbitTransport:Tls:EnabledfalseTLS to the broker
WorkflowRabbitTransport:Tls:ServerNamethe host nameThe name the certificate must carry
WorkflowRabbitTransport:Tls:ClientCertificatePath, ClientCertificatePassphrasenoneA client certificate
WorkflowRabbitTransport:ConfirmTimeoutSeconds30The wait for the broker’s publisher confirm
WorkflowRabbitTransport:ReplyTimeoutSeconds30The wait for a command reply
WorkflowRabbitTransport:ReplyQueueModeDirectReplyToDirectReplyTo or ExclusiveQueue
WorkflowRabbitTransport:ChannelPoolSize8Channels per host
WorkflowRabbitTransport:CommandHeaderNamecommandHeader framing: the header with the command name
WorkflowRabbitTransport:EnvelopeCommandField, EnvelopeCorrelationIdField, EnvelopePayloadFieldcommand, correlationId, payloadEnvelope framing: the field names
WorkflowRabbitTransport:ReplyPayloadField, ReplyErrorField, ReplyErrorHeaderNamepayload, error, errorThe reply’s payload and error

Rendering

Options class: WorkflowRenderingOptions.

KeyDefaultMeaning
WorkflowRendering:LayoutProviderElkSharpThe layout engine of diagrams

Licence

Options class: WorkflowComponentLicenceOptions.

KeyDefaultMeaning
StellaOps:ComponentLicence:PathnoneA licence file, or a directory of licence files
StellaOps:ComponentLicence:KeynoneThe same signed record as one base64 line; set either Path or Key
StellaOps:ComponentLicence:InstallationIdnoneThe Installation identifier the licence record names
STELLAOPS_VENDOR_TRUST_ROOTS (environment)noneA 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.

KeyDefaultMeaning
WorkflowDurableStart:Definitions:<code>emptyThe audience allowed to start the definition durably
WorkflowRegisteredSignals:ServiceSubjects:<subject>emptyThe audience of an authenticated service subject
WorkflowRegisteredSignals:Signals:<code>emptyThe only audience that may wait for and raise the signal
WorkflowExternalActivityRegistry:ManifestPath or ManifestJsonnoneThe signed activity registry; without it the registry is empty
WorkflowExternalActivityRegistry:ManifestSha256noneThe SHA-256 of the canonical manifest (required with a manifest)
WorkflowExternalActivityRegistry:SignaturePath or SignatureBase64noneThe signature
WorkflowExternalActivityRegistry:PublicKeyPath or PublicKeyPemnoneThe public key; a relative path is resolved against the application directory
WorkflowMaintenance:CompactionRetentionDays30Retention of delivered outbox and inbox rows (7 to 3650)
WorkflowConsole:SafeStateKeysstatus, currentStage, progress, outcome, safeCodeState keys the execution console shows
WorkflowConsole:TechnicalRedactedFragmentssecret, token, password, prompt, documentBody, signedUrl, bearerFragments 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).

KeyDefault
Enabledtrue
Endpointnone
CommandPath/api/workflow/definitions/import
ServiceName, AuthTokennone
Timeout00:00:30
MaxRetriesPerWorkflow, RetryBaseDelay3, 00:00:02
FailOnError, DryRunfalse, 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>"