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.
DefaultTenantId	string?	WorkflowApiConstants.SingleTenantId	The default workflow tenant ID to use when no tenant is specified in the request. If default tenant is null, requests without a tenant specified will be rejected.

Workflow Tenant Creation Options

When configuring the Workflow Engine Runtime using AddWorkflowRuntime or AddWorkflowTenants, you can specify options for creating WorkflowRuntime instances. These options are defined in the WorkflowTenantCreationOptions record. 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 to create with specific runtime options. If no tenant identifiers are specified, the single tenant id WorkflowApiConstants.SingleTenantId will be used.
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.

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 AddWorkflowTenantProvider 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.

AddWorkflowTenantProvider(this IServiceCollection services, IWorkflowTenantProvider tenantProvider)

Registers a tenant provider with the service collection in multi-tenant mode. For single-tenant applications, use AddWorkflowRuntime instead.

Parameters

Name	Type	Description
services	IServiceCollection	The IServiceCollection.
tenantProvider	IWorkflowTenantProvider	The tenant provider to register.

Returns

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

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

Creates IWorkflowTenant implementations and registers them with the service collection in multi-tenant mode. 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)

Creates IWorkflowTenant implementations and registers them with the service collection in multi-tenant mode. 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 managing workflow tenants in a Workflow Engine Web API.

Tenants

Returns

Type	Description
IReadOnlyCollection<IWorkflowTenant>	All registered workflow tenants.

Get(string id)

Get a workflow tenant by its id.

Parameters

Name	Type	Description
id	string	The workflow tenant id.

Returns

Type	Description
IWorkflowTenant	The workflow tenant instance.

GetHttpContextTenantId()

Get 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()

Get 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.

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)

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

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.

Returns

Type	Description
IWorkflowTenant	A new instance of IWorkflowTenant.

IWorkflowTenantProvider

Interface for providing workflow tenants in a multi-tenant setup.

info

Has a default implementation ListWorkflowTenantProvider that can be used to register list of tenants.

Tenants

An array of tenants to be registered in the Workflow Engine Web API.

Returns

Type	Description
IWorkflowTenant[]	An array of workflow tenants.