Operations and Scaling
Operations and Scaling defines how Workflow Engine stores durable data, records diagnostics, coordinates multiple runtime instances, and isolates tenant data. The multitenancy terms distinguish process-level TenantId scoping, physical storage boundaries, logical separation in shared storage, and HTTP API tenant routing.
Persistence and databases
Persistence stores durable workflow data through a provider for a database or another Persistence Store. Database terms describe the adapters, supported products, and migrations used to maintain that storage.
Persistence: The capability that stores Schemes, process state, timers, Parameters, and Process Status in a database or another Persistence Store, and can also record Transition History. Persistence lets Workflow Runtime continue from confirmed checkpoints across requests and host restarts.
Persistence Provider: The technical role that stores and retrieves Process Instance data. IPersistenceProvider is the exact core interface for that role, while ISchemePersistenceProvider
Database Provider: A shipped adapter and NuGet package for a supported database product. A Database Provider implements the Workflow Engine persistence contracts for that database.
Database Versioning: Migration of Workflow Engine persistence tables and database objects between product versions. Database Versioning is not Process Versioning or Scheme Versioning.
Multi-Database Support: The feature name for Workflow Engine's set of supported Database Providers. Multi-Database Support does not by itself mean that one Workflow Runtime writes to several databases at once.
History and diagnostics
Process Logs and Transition History are records associated with workflow execution. Runtime Logs are operational diagnostic messages, while Runtime Events are in-memory notifications rather than stored records.
Process Logs: Optional diagnostic execution records represented by ProcessLogEntry and written through IProcessLogProvider. LogEnabled controls whether a Scheme or Process Instance emits Process Logs. Process Logs are not Transition History.
Transition History: Persisted process movement records represented by ProcessHistoryItem. It normally contains completed Transitions and can also contain a process initialization record whose Trigger is Initializing. Process Transition History is an accepted expanded name when the process context is unclear, and Transition History is usually the source meant by the general phrase audit trail. Recording can be disabled for the provider or suppressed for a target Activity through DisablePersistTransitionHistory; those settings do not control Process Logs.
Runtime Logs: Operational application diagnostics emitted through OptimaJet.Workflow.Core.Logging.ILogger. This is Workflow Engine's own ILogger interface, not Microsoft.Extensions.Logging.ILogger. Runtime Logs are separate from Process Logs and Transition History.
Runtime Events: In-memory notifications raised by WorkflowRuntime; they are not a durable event log. Exact event names include OnProcessActivityChanged, OnProcessStatusChanged, and OnWorkflowError. A Process Status of Error and the OnWorkflowError event are related but not identical concepts.
Runtime coordination
Runtime Status and server modes describe how Workflow Runtime hosts start, stop, recover, and coordinate execution.
Runtime Status: The operational state stored for one Workflow Runtime host so runtime instances can coordinate startup, shutdown, and recovery. The exact RuntimeStatus values include Alive, Restore, SelfRestore, Dead, Terminated, and Single. Runtime Status describes a runtime host; Process Status describes one Process Instance.
Clustering: A deployment in which multiple active Workflow Runtime instances use the same database or database schema. They are equal peers and coordinate through persisted runtime, process, and timer data rather than direct server-to-server communication. Active instances share timer processing and recovery work, and the cluster remains operational while at least one instance is active. Load balancing incoming requests is outside Workflow Engine and must be provided by the application's deployment infrastructure. Because cluster members share a persistence boundary, they work with the same tenant set.
Single-Server Mode: The mode selected with AsSingleServer() when one active Workflow Runtime instance works with a database or database schema. The runtime handles timer processing locally and, by default, runs recovery at startup for Process Instances left in Running. Use this mode when workflow execution does not require horizontal scaling or cross-host failover. It can be used with any tenancy model.
Multi-Server Mode: The mode selected with AsMultiServer() when multiple peer Workflow Runtime instances form a cluster over the same database or database schema. Each instance has its own runtime ID and uses persisted state to coordinate timer processing, runtime liveness, and recovery. If one host stops, another active instance detects the failure and runs recovery for its Process Instances left in Running. Use this mode for horizontal scaling and failover. All instances connected to the shared persistence boundary work with the same tenant set; tenant isolation is configured separately.
Tenancy models
Multitenancy separates customer or business-unit data. The core runtime and Workflow Engine Web API provide different parts of that isolation. Single-Server and Multi-Server deployments support every tenancy model.
Tenant: A customer, department, or other isolation scope recognized by the host application. TenantId is the exact string value that identifies this scope on a Process Instance or HTTP request; it is not a Process ID or workflow Actor. In Workflow Engine HTTP API, this value is a logical tenant ID. Different logical tenant IDs can share one database and schema or use dedicated databases or schemas, depending on the tenancy model. The number of Workflow Runtime instances determines whether the deployment uses Single-Server or Multi-Server Mode.
Multitenancy: The capability for one Workflow Engine deployment to serve more than one isolated Tenant. The core runtime associates process data with TenantId. Workflow Engine Web API provides tenant registration and request routing for Workflow Engine HTTP API, together with tenant-aware data access, validation, and authorization. Multi-Tenancy is an alternate spelling encountered in product material; Multitenancy is the canonical noun, and multi-tenant is the adjective.
The diagram focuses on physical storage boundaries and the logical tenant IDs inside them. Workflow Runtime instance count separately determines Single-Server or Multi-Server Mode.
Physical Tenancy: A tenancy model in which each Tenant uses a dedicated persistence boundary: either a separate database or a separate database schema. Workflow Engine Web API can route a tenant ID through an IWorkflowTenant whose provider targets that boundary. The dedicated database or schema supplies the physical isolation. Multiple runtime instances connected to the same database and schema operate in Multi-Server Mode and serve the same tenant set.
Logical Tenancy: A tenancy model in which two or more Tenants use the same database and database schema. The selected TenantId scopes tenant-aware records and operations inside that shared storage. One runtime instance or several coordinated runtime instances can serve the same logical tenant set. Workflow Runtime instance count selects Single-Server or Multi-Server Mode. Correct isolation also depends on filtering, validation, and authorization in Workflow Engine HTTP API or the host application.
Hybrid Tenancy: A tenancy model that combines dedicated and shared persistence boundaries. For example, one Tenant can use its own database or schema while two other Tenants share another database and schema with records separated by TenantId. Workflow Engine Web API can route each ID to the appropriate IWorkflowTenant. The database and schema arrangement defines the model. Hybrid Multitenancy is the accepted expanded name for this combined configuration.
Process-Level Multitenancy: The core runtime capability that associates a Process Instance with the TenantId system Parameter and carries the same ID into its Subprocesses. TenantId cannot be merged back from a Subprocess to overwrite its Parent Process. Process-Level Multitenancy does not by itself provide HTTP API filtering or operation authorization.
Workflow Engine Web API Multitenancy: The tenant registration and request-routing capability that Workflow Engine Web API provides for Workflow Engine HTTP API requests. The Workflow-Api-Tenant-ID header or configured default supplies the tenant ID. The request snapshot first uses that value to resolve the physical tenant routing registration (IWorkflowTenant) and select its Workflow Runtime and provider. The API then uses the same value as the logical TenantId: Data API operations filter by it, RPC API operations validate the Process Instance Tenant, and API permissions control access to the Tenant. A provider configured with a dedicated database or schema supplies a physical storage boundary. Web API Multitenancy is the accepted short form.
See also
These pages explain operational behavior and tenant configuration in more depth.
- Multitenancy explains logical, physical, and hybrid deployments.
- Persistence explains durable storage and Database Providers.
- Glossary overview links to the other terminology subjects.
Frequently asked questions
What is the difference between Physical and Logical Tenancy?
Physical Tenancy gives each Tenant a separate database or database schema. Logical Tenancy stores multiple Tenants in the same database and schema, then scopes tenant-aware records and operations by TenantId. Both models support Single-Server and Multi-Server Mode.
What does Hybrid Multitenancy mean in Workflow Engine?
Hybrid Multitenancy combines both storage models. Some Tenants use dedicated databases or schemas, while other Tenants share a database and schema and are separated by TenantId.
Does setting TenantId provide complete tenant isolation?
No. TenantId identifies the logical scope. Complete HTTP isolation also requires tenant-aware filtering, Process Instance validation, and authorization; physical isolation additionally requires a dedicated database or database schema.
Do Subprocesses keep the Parent Process TenantId?
Yes. A Subprocess is created with its Parent Process TenantId, and the system Parameter cannot merge back and overwrite the Parent Process value.