Workflow Engine 23.0.0

OptimaJet Team Updated 2026-10-28 14 min read 2,765 words

Release date: October 27, 2026

Workflow Engine 23.0.0 adds Forms API, real-time tracking integration, and licensed API operation callbacks to Workflow Engine Web API. It also adds localized API responses and RPC lookups, an external expression compiler, and MongoDB Driver 3.x support. Review the update instructions for framework requirements and changes to existing integration contracts.

Why update

Forms API

The Forms API seamlessly connects FormsPlugin to your Workflow Engine Web API host and provides a ready-to-use HTTP API. Load forms, save drafts, and execute workflow commands from HTTP clients using your existing runtime and tenant configuration. See Workflow Forms and the Workflow Forms sample.

Real-time tracking through the HTTP API

Show live workflow progress in the Designer using your existing HTTP API host. The new integration supplies the SignalR hub and connects each subscription to the selected tenant's runtime. You can monitor several tenants and runtimes in one application without writing that integration yourself. Optional callbacks add application checks and logging around hub calls. See the Interactive Designer overview and the HTTP API sample.

API operation callbacks

Add application rules around an existing API operation. Inspect or change the operation's input, add authorization checks, adjust a successful response, or handle an exception while keeping the built-in operation handler. The API Configurator is a separately licensed option. If your update period is still active, contact sales to request a reissued license with ApiConfigurator enabled. See the HTTP API sample and the Workflow Forms sample.

Localized HTTP API responses and RPC operations

Show translated workflow names without making a separate localization request for each displayed value. API responses now include localized values beside the original names, so a client can use translations for labels and keep technical names for commands and application logic. See Localization and the HTTP API sample's OpenAPI document.

Use names from a workflow scheme's translations in an HTTP client instead of keeping a second translation table in the frontend. The new RPC operations return localized state and command names using the request's current culture. See Localization and the HTTP API sample's OpenAPI document.

External expression compiler

Choose how your application evaluates workflow expressions. A custom compiler can accept a limited expression language, reject operations your application does not permit, or delegate selected expressions to the built-in C# compiler. See Basic Plugin parameter expressions.

MongoDB Driver 3.x

Use the MongoDB provider with applications that depend on MongoDB .NET Driver 3.x. Workflow Engine now uses Driver 3.12.0 and adapts its queries and BSON handling while preserving existing workflow GUIDs. This major upgrade also updates the MongoDB HTTP API integration. Review the MongoDB update instructions before upgrading. See the MongoDB provider implementation.

Update instructions

Use the sections that apply to your Workflow Engine installation. Steps for adopting a new optional feature are labeled separately from changes to existing integrations.

Packages and platform support

Update Workflow Engine packages to version 23.0.0.
For a tested and supported configuration, retarget to .NET Framework 4.7.2 or later, update the deployment runtime, and rebuild. If you keep 4.6.2, validate your application and its selected packages yourself; Workflow Engine no longer tests that configuration.
Check the target frameworks of every provider and integration package. The MongoDB provider now targets netstandard2.1 and net472, so its 23.0.0 package requires a compatible host regardless of the Core package's .NET Standard 2.0 target. See the MongoDB update instructions.

MongoDB provider

Update the MongoDB provider and related Workflow Engine packages together. For .NET Framework applications, retarget to 4.7.2 or later; for modern applications, use a supported .NET runtime. Update any intermediate library that still targets only .NET Standard 2.0.
Review direct MongoDB.Driver references, custom BSON mappings, and code that accesses MongoDBProvider.Store. Keep CSharpLegacy GUID handling for existing Workflow Engine IDs. Do not rewrite stored Workflow Engine UUIDs to Standard representation as part of this upgrade.
Check reads, writes, process history, timers, and custom queries against a copy of your existing database before upgrading the production application.

Web API tenant resolution

Rebuild custom tenant locators and implement GetWorkflowTenantId(HttpContext) using the supplied request or connection context. Do not substitute the ambient HTTP context for a SignalR connection.
Review clients and proxies that already send workflowApiTenantId. Send one tenant value, or matching header and query values. Tenant selection still requires the caller's existing tenant permissions.

Real-time tracking integration

To adopt API tracking, install the integration package, register it once, and let it attach the core plugin to API-created runtimes. Set the Designer's realTimeTrackingUrl to the mapped hub URL, including any custom BasePath. In multi-tenant applications, select the same tenant for Designer HTTP requests and the tracking connection.
Grant tracking callers the workflow-api.realtime-tracking operation permission and any required tenant access. For JWT browser connections, configure the host's OnMessageReceived handler to read access_token only for the tracking operation; the integration does not configure JWT handlers. See the sample host's authentication configuration.
Keep the default tracking registration without ConfigureWorkflowApi if no customization is needed. A license with ApiConfigurator is required when adding host callbacks.
Migrate the obsolete ASP.NET integration before the next release. For Workflow Engine Web API hosts, use OptimaJet.Workflow.Api.RealTimeTrackingPlugin. For standalone hosts, register a notification sender and NotifierService, then map an application-owned hub. Obsolete warnings may already require changes in builds that treat warnings as errors. No database migration is required for this integration.

Forms API and Forms Viewer

Update custom Forms Viewer save and execute handlers to return a string message for each field in formErrors. Convert structured error objects to display text before returning them.
To adopt the new Forms API, install OptimaJet.Workflow.Api.Forms, register AddFormsPlugin(...), and configure a license with the Forms capability. Configure authentication, authorization, and CORS in the host application.

API Configurator licensing

Configure a license with ApiConfigurator enabled before starting an application that calls ConfigureWorkflowApi(...). The check runs when API configuration is built, before callbacks are applied or endpoints are mapped. Without this capability, configuration fails with InvalidOperationException; even an empty registration triggers the check.
If you do not need custom callbacks, omit ConfigureWorkflowApi(...) and use the default configuration. Default Forms and Real-Time Tracking module registration does not require ApiConfigurator. Existing API and plugin license requirements still apply.
The same license requirement applies to custom HTTP operation callbacks, Forms callbacks, and Real-Time Tracking hub callbacks.

Localized API responses and models

Regenerate HTTP clients if you want to read the new localized fields. Use the original name fields when sending commands or identifying workflow entities.
Rebuild .NET projects that reference the API model assembly. Update constructor/deconstruction code affected by changed record signatures; use named properties when reading InboxEntryModel.
Supply translations in the workflow scheme and configure the request culture in the host. The release does not create or translate customer localization data.

Files Plugin and SQLite dependencies

Update the Files Plugin and SQLite provider with the other Workflow Engine packages. If your application pins SSH.NET or SQLite dependencies directly, reconcile those pins with the provider's new dependency versions and rebuild.

Breaking changes

Major changes affect platform support, provider compatibility, or custom host implementations. Minor changes affect specific client contracts and legacy integration APIs.

Major breaking changes

Platform support: Workflow Engine will no longer be tested or supported on .NET Framework 4.6.2. The supported baseline is .NET Framework 4.7.2. Most libraries still target .NET Standard 2.0, so applications on 4.6.2 may continue to work at your own risk, without compatibility guarantees.
MongoDB provider: replaced the netstandard2.0 target with netstandard2.1 and net472. Applications and libraries that depend on the provider must target a compatible framework.
MongoDB integrations: applications that reference MongoDB.Driver or BSON APIs directly must use versions compatible with Driver 3.12.0 and rebuild custom queries and serializers.
Workflow Engine Web API: custom implementations of IWorkflowTenantLocator must now implement GetWorkflowTenantId(HttpContext). The interface supplies no default implementation.

Minor breaking changes

Workflow Engine Web API: workflowApiTenantId now participates in tenant selection on all API requests. If the query parameter and Workflow-Api-Tenant-ID header are both present, their values must match exactly. Multiple values or conflicting sources are rejected; the default tenant applies only when both sources are absent. An explicit empty query value no longer falls back to that default.
Forms Viewer: SaveFormResponse.formErrors and ExecuteFormResponse.formErrors now use Record<string, string> instead of Record<string, unknown>. Custom TypeScript adapters that return non-string field errors must be updated.
.NET consumers of API model classes: several public positional records gained parameters, and InboxEntryModel changed from a positional record to an explicitly declared record. Existing compiled consumers and code that deconstructs these models may need changes. The HTTP response changes are additive.
Real-Time Tracking Plugin: the built-in ASP.NET Core integration in WorkflowEngine.NETCore-RealTimeTrackingPlugin is obsolete. The old AddRealTimeTracking and MapRealTimeTracking methods, built-in hub, and legacy integration constructors still work in 23.0.0 but will be removed in the next release. The core package will no longer provide this ASP.NET integration; use the HTTP API integration package or an application-owned hub and notification sender.

Release changelog

Workflow Engine 23.0.0 includes the following product features, improvements, and fixes.

New features

Workflow Engine Web API: bootstrap a project in two CLI commands with .NET templates: dotnet new install OptimaJet.Workflow.Api.Template, then dotnet new workflow-engine-web-api --name MyWorkflowApi.
API template: choose SQL Server, PostgreSQL, MySQL, Oracle, MongoDB, or SQLite, with a JavaScript, React, or Angular Designer frontend, or no frontend.
Workflow Engine Web API: added OptimaJet.Workflow.Api.Forms. Register it with AddFormsPlugin(...) before MapWorkflowApi() to expose Forms operations and configure the Forms Plugin in API-created runtimes.
Forms API: added /forms/get-form, /forms/get-executable-forms, /forms/save-form, and /forms/execute-form under the configured API base path.
Forms API: added ordered form-data conversion steps for mapping data between HTTP clients and the runtime.
Workflow Engine Web API: added OptimaJet.Workflow.Api.RealTimeTrackingPlugin for .NET 8 and .NET 10. Register AddRealTimeTrackingPlugin() before MapWorkflowApi() to publish the tracking hub at /workflow-api/realtime-tracking with the default API base path.
API configurator: added ConfigureOperation(api => api.RealTimeTracking.Hub) with OnBefore, OnAuthorize, OnAfterSuccess, OnAfter, and OnException callbacks. Callbacks cover hub method calls; they do not run for connections, outgoing notifications, or stream items.
Workflow Engine Web API: added the workflowApiTenantId query parameter for tenant selection on HTTP requests and tracking connections. Browser clients can select a tenant without a custom header.
Real-Time Tracking Plugin: added IRealTimeTrackingNotificationSender and IRealTimeTrackingTenantNotificationSender so applications can supply their own notification transport.
Workflow Engine Web API: added ConfigureWorkflowApi(...), licensed through the ApiConfigurator capability, with typed ConfigureOperation(...) selectors and the OnBefore, OnAuthorize, OnAfterSuccess, OnAfter, and OnException callbacks.
Operation callbacks: added access to operation input, request services, tenant context, and results so applications can supply operation-specific behavior.
Operation authorization: added a callback for application-specific checks, including when the built-in Workflow API security service is disabled.
Workflow Engine Web API: added RPC operations to retrieve a localized state name by process ID, scheme ID, or scheme code.
Workflow Engine Web API: added RPC operations to retrieve a localized command name by process ID or scheme ID.
Workflow Engine Web API: added localized fields beside existing names in applicable Data API and RPC responses, including process states, command results, history, approvals, and inbox commands.
Scheme responses: added localized names for supported scheme members, including commands, command parameters, states, actions, conditions, and comments.
Core: added IExternalExpressionsCompiler and ExpressionsCompiler.ExternalCompiler to replace expression compilation independently of Code Actions.
Expression compilation: supplies source expressions, their intended use, result type, and scheme context. The compiler returns an asynchronous function that receives the current process instance when evaluated.
Expression compilation: added ExpressionsCompiler.DefaultCompiler for explicit delegation to the built-in C# compiler.

Product enhancements

API template: included Swagger UI, database configuration, and instructions for starting and checking the generated application. Container scripts are supplied for the database choices that use a server.
Forms Plugin: added error codes to system errors so clients can distinguish form, command, data, and configuration failures.
Forms Viewer: keeps the selected form after a reload when the same form and version remain available.
Forms sample: updated to use the new Forms API.
MongoDB provider: upgraded MongoDB.Driver from 2.30.0 to 3.12.0 and updated the provider and MongoDB HTTP API integration for the new driver.
MongoDB persistence: made the existing CSharpLegacy GUID representation explicit when reading and writing workflow IDs.
MongoDB provider: updated SharpCompress from 0.48.0 to 0.48.1.
HTTP API tracking: uses the host's API authentication and permissions, checks the process's tenant before subscribing, and sends updates to groups identified by tenant and process. Each runtime has its own notifier, including when several tenants share a runtime.
HTTP API tracking: supports the existing single-server event mode and configurable multi-server polling. The Designer keeps its existing subscription and notification protocol.
API configuration: checks hub routes and their negotiation routes for conflicts with other configured API routes before publishing endpoints.
Real-Time Tracking Plugin: marked the old SignalR registration helpers, built-in hub, and service-provider constructors obsolete. Supported legacy registration continues to work in this release.
Workflow Engine Web API: made built-in operation registration order deterministic, including Forms operations.
API Configurator: checks the license capability before applying custom configuration and reports a clear error when the option is unavailable.
Localization RPC: applies the request's tenant context when resolving processes and schemes. Scheme-ID lookups reject schemes from another tenant.
HTTP API localization: uses the applicable culture and scheme translations while preserving the original technical-name fields. Localized inbox commands keep the same order as their original names.
HTTP API localization: handles records whose process or scheme is no longer available, and leaves ambiguous, timer, and automatic history trigger names untranslated.
Core: uses the external expression compiler for conditions, actor values, timers, subprocess names, inline parameters, Basic Plugin expression values, and Designer expression validation.
Core: propagates an external compiler's rejection without silently retrying with the built-in compiler or treating the expression text as a literal.
Core: invalidates cached expressions and prevents reuse of old compiled functions when the external compiler registration changes.
Angular integration: aligned the Designer wrapper and samples with Angular 22.2.2 and updated their build tooling.
Files Plugin: updated SSH.NET from 2020.0.2 to 2026.0.0 and adapted SFTP directory handling to the new dependency API.
SQLite provider for .NET 8: updated Microsoft.Data.Sqlite from 8.0.16 and Microsoft.EntityFrameworkCore.Sqlite.Core from 8.0.26 to 8.0.32.
SQLite provider for .NET 10: updated Microsoft.Data.Sqlite and Microsoft.EntityFrameworkCore.Sqlite.Core from 9.0.15 to 9.0.21.

Bug fixes

Forms Viewer: shows Save when saving is allowed, including forms with no executable commands.
Forms Viewer: clears loading indicators after failed saves or commands and clears old form errors after a successful response.
Forms Plugin: restores the process to its idle or final status when form execution stops because converted form data is invalid.
Real-Time Tracking Plugin: repeated subscriptions from the same connection no longer create duplicate entries or leave polling active after disconnect.
Real-Time Tracking Plugin: disconnect removes all subscriptions for that connection while preserving other clients' subscriptions.
HTTP API tracking: repeated disconnect and cleanup after notifier shutdown are handled safely.
Oracle provider: fixed the calendar-name index migration so it skips index creation when IDX_CALENDARNAME already exists in the current schema.

Frequently asked questions

Does the new Forms API require an API Configurator license?

Default Forms and Real-Time Tracking module registration does not require ApiConfigurator. Custom callbacks registered through ConfigureWorkflowApi(...) do require it; existing API and plugin license requirements still apply. See API Configurator licensing.

Can I continue using Workflow Engine on .NET Framework 4.6.2?

Most libraries still target .NET Standard 2.0, so applications on 4.6.2 may continue to work at your own risk, without testing or support. Individual packages can require a newer framework: the MongoDB provider now targets netstandard2.1 and net472. See packages and platform support.

Do I have to replace the old ASP.NET tracking integration immediately?

The obsolete integration still works in 23.0.0, but its methods, built-in hub, and legacy integration constructors will be removed in the next release. Migrate before that release; builds that treat obsolete warnings as errors may need changes now. See real-time tracking integration.

Next Workflow Engine 22.1.0