Core Services

The Web API core services manage other services and build the API by using an internal builder based on ASP.NET Minimal API. The core services do not include database providers, so be sure to add one when configuring the Web API.

Core Options

You can configure core services options using the WorkflowApiCoreOptions record provided as ASP.NET IOptions in the service collection. Below is a table describing its properties:

Name	Type	Default	Description
BasePath	string	"workflow-api"	The root path to the Workflow Engine Web API endpoints. If an empty string is specified, the endpoints will be accessible via the root path of your application.
LicenseKey	string	""	The Workflow Engine license key with the Workflow Engine API option enabled. If the key is not provided, the API will not start. Request a key from our sales team at sales@optimajet.com.
DefaultTenantId	string?	WorkflowApiConstants.SingleTenantId	The default workflow tenant ID to use when no tenant is specified in the request. If the default tenant is null, requests without a tenant specified will be rejected.
ProtectedGlobalParameterTypes	HashSet<string>	WorkflowApiConstants.DefaultProtectedGlobalParameterTypes	Global Parameter types that cannot be accessed through generic Global Parameters Data API endpoints. Host applications can add, remove, or replace values in this set.

Protected Global Parameter Types

ProtectedGlobalParameterTypes prevents clients from reading or changing Workflow Engine system storage through the generic Global Parameters Data API endpoints. The default set protects Global Parameter types used for global code actions, runtime and server settings, plugins, security, logging, LDAP, OpenID Connect, and CORS configuration.

The protection is applied to the generic Global Parameters endpoints under workflow-api/data/global-parameters and workflow-api/search/global-parameters. Collection reads and deletes automatically exclude protected types. Single-item create, read, update, and delete requests are rejected when the current type, or the target type in an update request, is protected.

Designer and runtime global code actions continue to use the shared Workflow Engine Core Global Parameters API. They are not exposed for direct management through the generic Web API Global Parameters endpoints while their type remains in ProtectedGlobalParameterTypes.

Host applications can customize the protected type list when registering the Web API core services:

builder.Services.AddWorkflowApiCore(options =>
{
    // Add a host-specific system type to the default protected list.
    options.ProtectedGlobalParameterTypes.Add("CustomSystemType");

    // Remove a type if it must be managed through the generic Global Parameters Data API.
    options.ProtectedGlobalParameterTypes.Remove("settings");
});

To replace the default list completely, assign a new set:

builder.Services.AddWorkflowApiCore(options =>
{
    options.ProtectedGlobalParameterTypes = new HashSet<string>(StringComparer.Ordinal)
    {
        "CustomSystemType"
    };
});

Workflow Tenant Creation Options

When configuring the Workflow Engine Runtime using AddWorkflowRuntime, AddWorkflowTenants, or IWorkflowTenantRegistry.RegisterTenantsAsync(...), you can specify options for creating WorkflowRuntime instances. These options are defined in the WorkflowTenantCreationOptions class. In single-tenant mode, you can provide these options as ASP.NET IOptions in the service collection. Below is a table describing its properties:

Name	Type	Default	Description
TenantIds	string[]	[]	The unique workflow tenant identifiers handled by the tenant instance. AddWorkflowRuntime(...) sets this to WorkflowApiConstants.SingleTenantId automatically. AddWorkflowTenants(...) and dynamic registry registration require at least one explicit tenant id.
WorkflowRuntimeCreationOptions	WorkflowRuntimeCreationOptions	new()	Options for configuring the Workflow Engine WorkflowRuntime runtime of the tenant.
PersistenceProviderId	string?	null	The identifier of the data & workflow provider to use for the tenant creation. This identifier is used to select provider factory from the list of registered factories. If not specified, the first found factory will be used. Default identifiers are stored in PersistenceProviderId class. And they are the same for both data and workflow providers.
ConnectionString	string	""	Specifies the connection string used by both data and workflow providers for tenant creation.
DataProviderCreationOptions	DataProviderCreationOptions	new()	Configuration options for the tenant's data provider.
WorkflowProviderCreationOptions	WorkflowProviderCreationOptions	new()	Options for configuring the Workflow Engine Core.Persistence.IWorkflowProvider provider of the tenant.

The properties of DataProviderCreationOptions are described in the database providers documentation.

Tenant identifiers are case-sensitive, must be non-null, and can be at most 128 characters long. The empty string WorkflowApiConstants.SingleTenantId is reserved for single-tenant mode and cannot be mixed with named tenant ids.

Workflow Runtime Creation Options

The WorkflowRuntimeCreationOptions record lets you configure a tenant’s WorkflowRuntime instance. The table below describes its properties:`

Name	Type	Default	Description
RuntimeId	Guid	Guid.Empty	The unique identifier for the Workflow Engine runtime instance.
PersistenceProviderFactory	Func<IWorkflowProvider?, IPersistenceProvider>	provider => provider ?? throw new ArgumentNullException(nameof(provider))	A factory method for creating an instance of IPersistenceProvider, serving as an interface for storing process data in the Workflow Engine runtime. The parameter provided to the factory is the default IWorkflowProvider provider specified when creating the tenant or null if no provider is specified.
WorkflowBuilderFactory	Func<IWorkflowProvider?, IWorkflowBuilder>	provider => new WorkflowBuilder<XElement>(provider, new XmlWorkflowParser(), provider).WithDefaultCache()	A factory method for creating an instance of IWorkflowBuilder, serving as a workflow scheme parser for the Workflow Engine runtime. The parameter provided to the factory is the IWorkflowProvider provider specified when creating the tenant or null if no provider is specified.
ConfigureWorkflowRuntime	Action<WorkflowRuntime>	_ => { }	A delegate used to configure the Workflow Engine runtime instance. Called after the IPersistenceProvider and IWorkflowBuilder have been registered.
DisableMigrationsExecution	bool	false	If set to true, disables the execution of WorkflowRuntimeExtensions.RunMigrations(WorkflowRuntime) during the initialization of the WorkflowRuntime.
DisableRuntimeAutoStart	bool	false	If set to true, prevents the WorkflowRuntimeConfigurationExtension.StartAsync() from automatically starting after initialization.
IgnoreNotCompiledGlobalActionsOnStart	bool	false	If set to true, the Workflow Engine runtime will ignore any compilation errors that occur in global actions during its startup.

Workflow Provider Creation Options

The WorkflowProviderCreationOptions record lets you configure a tenant’s IWorkflowProvider instance. The table below describes its properties:`

Name	Type	Default	Description
DisableWritingProcessTransitionHistory	bool	false	If set to true, prevents the Workflow Engine from saving process transition history to the database.
WriteSubprocessTransitionHistoryToRootProcess	bool	false	When enabled, writes the transition history of subprocesses directly into the root process transition history.

ASP.NET Extensions

The core services provide extension methods to configure the Workflow Engine Web API in an ASP.NET application.

AddWorkflowApiCore(this IServiceCollection services, Action<WorkflowApiCoreOptions>? setupAction = null)

Adds the core Workflow Engine Web Api services, enabling you to add endpoints using MapWorkflowApi.

Parameters

Name	Type	Description
services	IServiceCollection	The IServiceCollection.
setupAction	Action<WorkflowApiCoreOptions>?	A delegate to configure the core Workflow Engine Api options.

Returns

Type	Description
IServiceCollection	A IServiceCollection that can be used to further configure services.

AddWorkflowRuntime(this IServiceCollection services, Action<WorkflowTenantCreationOptions>? setupAction = null)

Creates WorkflowRuntime and registers it with the service collection in single-tenant mode. For multi-tenant applications, use AddWorkflowTenants or IWorkflowTenantRegistry.RegisterTenantsAsync(...) instead.

Parameters

Name	Type	Description
services	IServiceCollection	The IServiceCollection.
setupAction	Action<WorkflowTenantCreationOptions>?	A delegate to configure the Workflow Runtime options. Using this method implies single-tenant mode, so the tenant ids will be set to a WorkflowApiConstants.SingleTenantId.

Returns

Type	Description
IServiceCollection	A IServiceCollection that can be used to further configure services.

AddWorkflowTenants(this IServiceCollection services, params WorkflowTenantCreationOptions[] options)

Registers static tenant creation options in multi-tenant mode. The hosted tenant registry service creates and starts the tenants during application startup. For single-tenant applications, use AddWorkflowRuntime instead.

Parameters

Name	Type	Description
services	IServiceCollection	The IServiceCollection.
options	WorkflowTenantCreationOptions[]	An array of options for creating the tenants.

Returns

Type	Description
IServiceCollection	A IServiceCollection that can be used to further configure services.

AddWorkflowTenants(this IServiceCollection services, IEnumerable<WorkflowTenantCreationOptions> options)

Registers static tenant creation options in multi-tenant mode. The hosted tenant registry service creates and starts the tenants during application startup. For single-tenant applications, use AddWorkflowRuntime instead.

Parameters

Name	Type	Description
services	IServiceCollection	The IServiceCollection.
options	IEnumerable<WorkflowTenantCreationOptions>	An enumerable of options for creating the tenants.

Returns

Type	Description
IServiceCollection	A IServiceCollection that can be used to further configure services.

MapWorkflowApi(this IEndpointRouteBuilder endpoints)

Maps all Workflow Engine Web Api endpoints to the specified IEndpointRouteBuilder. When using this method, you must first add services using AddWorkflowApiCore.

Parameters

Name	Type	Description
endpoints	IEndpointRouteBuilder	The IEndpointRouteBuilder.

Returns

Type	Description
IEndpointRouteBuilder	A IEndpointRouteBuilder that can be used to further configure endpoints.

IWorkflowTenantRegistry

Service for dynamically registering, unregistering, and snapshotting workflow tenants in a Workflow Engine Web API. The registry is mutable; request and read code should use IWorkflowTenantSnapshot or IWorkflowTenantLocator for a consistent view of tenants.

RegisterTenantsAsync(IEnumerable<WorkflowTenantCreationOptions> options) and RegisterTenantsAsync(params WorkflowTenantCreationOptions[] options)

Creates tenants from creation options, starts registry-owned tenants, registers them, and publishes a new immutable snapshot.

Parameters

Name	Type	Description
options	IEnumerable<WorkflowTenantCreationOptions> or WorkflowTenantCreationOptions[]	Tenant creation options.

Returns

Type	Description
IReadOnlyCollection<IWorkflowTenant>	The created tenant instances.

RegisterTenantsAsync(IEnumerable<IWorkflowTenant> tenants) and RegisterTenantsAsync(params IWorkflowTenant[] tenants)

Registers already created tenants and publishes a new immutable snapshot. Registry-owned tenants are started before the snapshot is published. Externally owned tenants are published without StartAsync() being called by the registry.

Parameters

Name	Type	Description
tenants	IEnumerable<IWorkflowTenant> or IWorkflowTenant[]	Tenants to register.

UnregisterTenantsAsync(IEnumerable<IWorkflowTenant> tenants) and UnregisterTenantsAsync(params IWorkflowTenant[] tenants)

Removes tenant instances from newly created snapshots. If a tenant is unknown, the call is a no-op. Registry-owned tenants are shut down only after old snapshots that still reference them are disposed.

Parameters

Name	Type	Description
tenants	IEnumerable<IWorkflowTenant> or IWorkflowTenant[]	Tenants to unregister.

GetSnapshot()

Gets an immutable point-in-time tenant snapshot. The caller must dispose it when it is no longer needed.

Returns

Type	Description
IWorkflowTenantSnapshot	A disposable immutable tenant view.

IWorkflowTenantRegistryLifecycle

Controls the host-owned lifecycle of the workflow tenant registry. The default core services register a hosted service that calls this lifecycle during ASP.NET application startup and shutdown.

StartAsync(IEnumerable<WorkflowTenantCreationOptions> options, CancellationToken cancellationToken = default)

Starts the tenant registry and registers static tenants from the provided creation options.

Parameters

Name	Type	Description
options	IEnumerable<WorkflowTenantCreationOptions>	Static tenant creation options.
cancellationToken	CancellationToken	The cancellation token for startup.

StopAsync(CancellationToken cancellationToken)

Stops the tenant registry and gracefully shuts down registry-owned tenants.

Parameters

Name	Type	Description
cancellationToken	CancellationToken	The cancellation token for shutdown.

IWorkflowTenantSnapshot

Immutable point-in-time view of registered workflow tenants. ASP.NET request scopes receive an IWorkflowTenantSnapshot automatically, so all Workflow API operations in the same request use the same tenant set.

Tenants

Returns

Type	Description
IReadOnlyCollection<IWorkflowTenant>	All tenant instances in the snapshot.

TenantIds

Returns

Type	Description
IReadOnlyCollection<string>	All tenant ids in the snapshot.

IsSingleTenant

Returns

Type	Description
bool	true when the snapshot contains the reserved single-tenant setup.

GetTenant(string id)

Gets a workflow tenant by any registered tenant id.

Parameters

Name	Type	Description
id	string	The workflow tenant id.

Returns

Type	Description
IWorkflowTenant	The workflow tenant instance.

IWorkflowTenantLocator

HTTP-specific service for resolving the current tenant from the request-scoped snapshot and WorkflowApiConstants.TenantIdHeader.

GetHttpContextWorkflowTenantSnapshot()

Gets the tenant snapshot from the current HTTP request scope.

Returns

Type	Description
IWorkflowTenantSnapshot	The current request snapshot.

GetHttpContextWorkflowTenantId()

Gets the workflow tenant id from the current HTTP context based on the provided header or default tenant id.

Returns

Type	Description
string	The workflow tenant id.

GetHttpContextWorkflowTenant()

Gets the workflow tenant instance from the current HTTP context.

Returns

Type	Description
IWorkflowTenant	The workflow tenant instance.

GetHttpContextWorkflowRuntime()

Get the workflow runtime instance for the workflow tenant identified in the current HTTP context.

Returns

Type	Description
WorkflowRuntime	The workflow runtime instance.

IWorkflowTenant

Defines a workflow tenant in a Workflow Engine Web API. In a single-tenant setup registered as a single instance with WorkflowApiConstants.SingleTenantId as its only id.

info

Has a default implementation WorkflowTenant.

Ids

Returns

Type	Description
IReadOnlyCollection<string>	All logical tenant ids that map to this tenant instance.

Runtime

Returns

Type	Description
WorkflowRuntime	The workflow runtime instance for this tenant.

DataProvider

Returns

Type	Description
IDataProvider	The data provider for this tenant.

LifecycleOwnership

Controls whether the tenant lifecycle is managed by the registry or by external code.

Returns

Type	Description
WorkflowTenantLifecycleOwnership	The lifecycle ownership mode.

StartAsync()

Starts the tenant before it is published in the registry. The default WorkflowTenant starts its WorkflowRuntime unless DisableRuntimeAutoStart is enabled or the runtime is already running.

ShutdownAsync()

Gracefully shuts down the tenant after it is removed from the registry and is no longer used by any active snapshot.

WorkflowTenantLifecycleOwnership

Value	Description
Registry	The tenant registry calls StartAsync() and ShutdownAsync() for the tenant.
External	The host application owns the tenant lifecycle. The registry only publishes and removes the tenant.

IWorkflowTenantFactory

Factory interface for creating IWorkflowTenant instances.

Create(WorkflowTenantCreationOptions options)

Creates a new IWorkflowTenant instance based on the provided creation options.

Parameters

Name	Type	Description
options	WorkflowTenantCreationOptions	The options for creating the tenant.

Returns

Type	Description
IWorkflowTenant	A new instance of IWorkflowTenant.

Create(IEnumerable<string> ids, WorkflowRuntime runtime, DataProviderCreationOptions dataProviderOptions, WorkflowTenantLifecycleOwnership lifecycleOwnership = WorkflowTenantLifecycleOwnership.Registry)

Creates a new IWorkflowTenant instance with the specified IDs, workflow runtime, data provider options, and lifecycle ownership.

Parameters

Name	Type	Description
ids	IEnumerable<string>	The logical tenant IDs that map to this tenant instance.
runtime	WorkflowRuntime	The workflow runtime instance for this tenant.
dataProviderOptions	DataProviderCreationOptions	The options for creating the data provider.
lifecycleOwnership	WorkflowTenantLifecycleOwnership	The lifecycle owner for the tenant.

Returns

Type	Description
IWorkflowTenant	A new instance of IWorkflowTenant.