Workflow Engine 21.0.0

March 20, 2026

Overview

Workflow Engine 21.0.0 is a major release focused on Web API authorization, performance and stability improvements, .NET 10 support, and removal of legacy runtime APIs and outdated plugins.

Why update

• Get substantially faster parameter persistence, especially in workflows that store many process parameters.
• Use the new compact Web API authorization model for operation and tenant access with smaller JWT payloads and clearer multi-tenant enforcement.
• Improve timer stability by fixing startup-time timer races and reworking timer management internals.
• Improve graceful shutdown stability by removing a potential memory leak and making runtime behavior after shutdown more predictable.
• Move to .NET 10 across Workflow Engine samples and platform support while retiring .NET 6 support.

Key features

• Redesigned parameter persistence substantially improves throughput on mixed benchmark workloads, with the largest gains on schemes that carry many parameters.
• Web API authorization now uses one compact WorkflowApiPermissions claim for both operation access and tenant access, with explicit builder APIs and hierarchical permission rules.
• Timer management internals were reworked for more stable timer registration and execution.
• Graceful shutdown handling was rewritten to eliminate a potential memory leak and make runtime API behavior after shutdown consistent.
• Workflow Engine now supports .NET 10 and all samples were updated to .NET 10.
• The major-version cleanup removes previously obsolete runtime APIs, legacy timer value mutation flows, schema-generation parameter support, and deprecated messaging plugins.

Changelog

Update instructions

• All packages: update Workflow Engine packages to version 21.0.0.
• Before moving to 21.0.0, first upgrade to 20.0.7 or later, rebuild your solution, and remove usages that already show [Obsolete] warnings. In 21.0.0, previously obsolete APIs are removed, except AssignmentPlugin, which is now marked obsolete. See Workflow Engine 20.0.7.
• If you use Workflow Engine Web API with security enabled, reissue all JWTs after upgrading. The old WorkflowApiPermissions:<operation> claim format is replaced with one compact WorkflowApiPermissions claim that stores operation and tenant rules together.
• If you store Web API permission values in your application database, migrate saved permission lists to the new serialized claim value format before issuing new tokens. For security-enabled multi-tenant deployments, include tenant rules in the stored value.
• If you use SQL persistence providers, apply the bundled Workflow Engine database migrations before starting the updated runtime. This release changes storage related to deprecated schema-generation parameters: DefiningParameters, DefiningParametersHash, and IsDeterminingParametersChanged. See Database versioning.
• If you target .NET 6, retarget to a supported version before upgrading. Workflow Engine 21.0.0 adds .NET 10 support and removes .NET 6 support.
• If you use synchronous WorkflowRuntime methods, replace them with asynchronous runtime APIs before upgrading. See Async API.
• If you use timer value mutation APIs or implicit timers with values 0 or -1 resolved through NeedTimerValue, move timer calculation to timer expressions or parameter-based expression timers before upgrading. See How to create dynamic timers and Timers.
• If you implement a custom ITimerManager, adapt it to the streamlined 21.0.0 contract before rebuilding.
• If you use custom build steps that accept schema-generation parameters, remove that parameters argument from BuildStep.ExecuteAsync. See Build steps.
• If you use TelegramPlugin, SlackPlugin, NexmoPlugin, or TwilioPlugin, remove those packages and replace the integration before upgrading.
• If you use AssignmentPlugin, you can keep it in 21.0.0, but all its APIs are now obsolete and scheduled for removal in a future release. See Assignment Plugin. Contact support@optimajet.com if you need migration guidance.
• In 21.0.0, explicitly call StartAsync() or ColdStartAsync() once before you begin using WorkflowRuntime methods. See Runtime and Async API.
• After ShutdownAsync(), explicitly call StartAsync() or ColdStartAsync() again before resuming runtime API usage. These methods are not intended to be called before every runtime API method. See Single-Server Mode and Multi-Server Mode.
• Before 21.0.0, single-server mode still allowed runtime API calls without an explicit start, including after graceful shutdown, for backward compatibility.
• If Web API security is enabled in a multi-tenant setup, make sure issued tokens include both operation rules and tenant rules. Operation access alone is no longer enough for requests that resolve tenant context through Workflow-Api-Tenant-ID.

Example migration from old per-operation claims to the new builder-based claim:

var claim = permissions.BuildClaim(builder => builder
    .DenyAllOperations()
    .Allow(
        "workflow-api.liveness",
        "workflow-api.data.schemes.get")
    .AllowAllTenants());

For stricter multi-tenant access, issue an explicit tenant allow list:

var claim = permissions.BuildClaim(builder => builder
    .DenyAllOperations()
    .Allow("workflow-api.liveness")
    .DenyAllTenantsExcept("TenantA", "TenantB"));

Features

• Web API: introduced compact authorization through a single WorkflowApiPermissions claim that controls both operation access and tenant access.
• Web API: added IWorkflowApiPermissionsBuilder with fluent APIs such as AllowAllOperations(), DenyAllOperations(), Allow(...), Deny(...), AllowAllTenants(), DenyAllTenants(), AllowAllTenantsExcept(...), DenyAllTenantsExcept(...), GetValue(), SetValue(...), and ValidateValue(...).
• Web API: added hierarchical operation permissions, so branch rules such as workflow-api.rpc and workflow-api.data.schemes apply to child operations while more specific rules still take precedence.
• Web API: added tenant authorization for requests that resolve tenant context through Workflow-Api-Tenant-ID; the selected tenant is now allowed only when the token's WorkflowApiPermissions claim includes a matching tenant rule.
• Core and samples: added .NET 10 support and updated all samples to .NET 10.

Enhancements

• Core: redesigned parameter persistence to improve throughput when saving process parameters.
• Web API: reduced JWT payload size for broad permissions because one compact claim and branch rules can replace large operation claim sets.
• Web API: centralized authorization in the security pipeline through HttpContextHasAccess(...), so controllers no longer need separate tenant checks.
• Core: reworked timer manager internals and simplified the ITimerManager surface to make timer handling more predictable and stable.
• Core: reworked graceful shutdown internals to improve runtime shutdown stability and make post-shutdown behavior more consistent.

Reference mixed-workload benchmark results for parameter persistence:

Number of parameters	MSSQL	PostgreSQL	Oracle	MySQL
8	x1.4 (+40%)	x1.2 (+20%)	x1.4 (+40%)	x1.1 (+10%)
16	x1.6 (+60%)	x1.5 (+50%)	x1.5 (+50%)	x1.2 (+20%)
32	x2.3 (+130%)	x2.0 (+100%)	x1.8 (+80%)	x1.4 (+40%)
64	x3.0 (+200%)	x2.5 (+150%)	x2.1 (+110%)	x1.7 (+70%)

The benchmark used a mixed workload where only one third of schemes had a significant number of parameters. Actual results depend on your workload profile.

Bug fixes

• Core: fixed a race condition when starting a process that creates timers during startup.
• Core: fixed a potential memory leak in graceful shutdown handling.

Breaking changes

• Web API security-enabled authorization now expects exactly one WorkflowApiPermissions claim instead of multiple WorkflowApiPermissions:<operation> claims. Existing JWTs issued with the old claim contract are not accepted and must be reissued.
• Multiple WorkflowApiPermissions claims in the same principal are invalid when Web API security is enabled.
• In security-enabled multi-tenant Web API deployments, tokens must include tenant authorization rules. Missing tenant rules, missing tenant header when no default tenant is configured, invalid tenant IDs, unknown tenant IDs, or a header changed to a tenant not allowed by the token now result in 403 Forbidden.
• IWorkflowApiPermissions no longer exposes the old per-operation claim API: AllowAll(), AllowList(...), DenyAll(), DenyList(...), GetAllPermissions(), and ValidatePermissions(...) were removed. Use CreateBuilder() and BuildClaim(...) instead.
• Removed .NET 6 support. Retarget applications and related build pipelines to a supported framework before upgrading.
• Removed synchronous WorkflowRuntime APIs. Use asynchronous runtime methods instead. See Async API.
• Simplified the ITimerManager contract. Update custom timer manager implementations to the 21.0.0 interface before rebuilding.
• Removed SetTimerValueAsync and ResetTimerValueAsync. Use timer expressions to calculate timer values instead.
• Removed support for implicit timers with values 0 and -1 resolved through NeedTimerValue. Use timer expressions instead.
• WorkflowRuntime methods now require an explicit StartAsync() or ColdStartAsync() call once before runtime API usage begins. After ShutdownAsync(), the runtime must be started again before any further API calls. These methods are not intended to be called before every runtime API method. The old single-server compatibility behavior, where runtime API calls still worked without an explicit start, was removed.
• SetSchemeIsObsoleteAsync now works only on a started runtime and obeys shutdown state.
• Removed schema-generation parameter support from runtime and builder APIs. Depending on the surface, these parameters were previously named DeterminingParameters, DefiningParameters, or Parameters.
• Custom BuildStep.ExecuteAsync implementations that accepted schema-generation parameters must drop that argument.
• Removed previously obsolete APIs introduced by earlier deprecations in 20.x, except AssignmentPlugin, which remains available but is now obsolete.
• Removed and no longer support TelegramPlugin, SlackPlugin, NexmoPlugin, and TwilioPlugin.

Resources

• Web API security documentation: Security services.
• Database migrations guide: Database versioning.
• Runtime API usage: Basic Operations.
• Async runtime API guidance: Async API.
• Single-server lifecycle and shutdown: Single-Server Mode.
• Multi-server lifecycle and shutdown: Multi-Server Mode.
• Timer migration guidance: How to create dynamic timers.