On July 16, 2026, we released Workflow Engine NEO 22.0.0. Version 22 builds on the existing TenantId and multi-tenant Web API support and addresses two harder problems:
- a Workflow Engine Web API host can now add and remove tenant configurations while the application is running; and
- logical tenant scope now reaches workflow definitions, configuration, forms, processes, and process-related data more consistently.
Together, these changes complete support for physical, logical, and hybrid multitenancy in one Workflow Engine Web API host. A SaaS platform can give selected customers dedicated runtimes and databases, place others in logically isolated groups on shared infrastructure, and manage the entire topology through the same application. This flexibility is the central architectural capability in version 22.
I am Mike Lukinov, co-founder of Optimajet. This article explains how the three models fit together, then reviews the questions a SaaS team should answer before choosing its tenant architecture: where isolation lives, how tenants enter and leave the system, where authorization is enforced, what may be shared, and where product responsibilities split.
What hybrid multitenancy means
Workflow Engine Web API separates physical and logical tenancy.
A physical tenant is a runtime and provider boundary. It can use a dedicated database and can serve one or more logical tenant IDs. Logical tenants share that runtime and provider, while their workflow data is separated by TenantId.
Hybrid multitenancy means using both mappings in one Web API host:
One ASP.NET / Workflow Engine Web API host
|
|-- Physical tenant A
| |-- Runtime and provider A
| |-- Dedicated database A
| `-- Logical tenant ID: acme
|
`-- Physical tenant B
|-- Runtime and provider B
|-- Shared database B
`-- Logical tenant IDs: globex, stark
Acme has its own runtime and database boundary. Globex and Stark share a runtime and database with logical separation. That combination is hybrid tenancy.
The five architecture questions
| Question | Architecture decision |
|---|---|
| Where should the isolation boundary sit? | Shared database, dedicated database, or a combination of both. |
| Does onboarding require a deployment? | Whether the tenant catalog belongs to application startup or to a runtime control plane. |
| Where is the security boundary? | How identity, tenant authorization, routing, and persistence work together. |
| What is isolated and what may be shared? | Which data belongs exclusively to a tenant and which definitions act as common defaults. |
| Where does the engine's responsibility end? | The boundary between Workflow Engine and the surrounding SaaS control plane. |
Question 1: where should the isolation boundary sit?
Workflow Engine NEO supports three answers.
- Logical tenancy puts several tenant IDs behind one runtime, provider, and database. It minimizes the number of infrastructure units while separating workflow data by tenant ID.
- Physical tenancy gives a tenant its own runtime and provider configuration. When its provider points to a dedicated database, it also creates an independent backup and restore boundary.
- Hybrid tenancy uses physical isolation for customers that require it and logical isolation for customers that can share infrastructure.
The choice should follow operational requirements: data residency, regulatory commitments, independent backup and restore, database-provider requirements, and the acceptable impact of a database-level incident.
A physical tenant remains part of the same ASP.NET application deployment. Its boundary covers runtime and persistence, while the application version and host process stay shared. Tenant-specific definitions also work in the logical model, allowing customized workflows to use shared infrastructure.
Question 2: does onboarding require a deployment?
Version 22.0.0 lets a multi-tenant host start with a partial tenant catalog and accept tenant registrations later. Adding or removing a Workflow Engine tenant becomes a control-plane operation during the lifetime of the ASP.NET application.
The important architectural property is consistency during change. New requests use the updated tenant map, while requests already in progress continue with the view under which they started. Removing a tenant stops new requests from being routed to it without invalidating work that is already using the previous routing state.
Customer onboarding still spans the wider SaaS control plane:
- provision a database or choose a shared one;
- create and store credentials;
- configure identity, billing, quotas, and product-specific data; and
- register the resulting runtime and tenant mapping with Workflow Engine.
Offboarding has the same separation of concerns. Removing a tenant affects routing, while database lifecycle and retention remain separate. Traffic removal, runtime shutdown, archival, and data erasure should remain explicit operations.
Adding a physical tenant changes the runtime and provider topology. Adding a logical ID extends an existing shared tenant group. The control plane should model them as distinct operations.
Question 3: where is the security boundary?
Tenant routing and tenant authorization are separate decisions. The tenant identifier on a request selects context. Caller identity and permissions establish access to that context.
An effective boundary has four layers:
| Layer | Responsibility |
|---|---|
| Identity and authorization | Establish who the caller is and which tenant and operations the caller may access. |
| Tenant routing | Map the selected logical tenant to the correct runtime and provider. |
| Workflow persistence | Keep built-in process reads and writes inside the selected tenant or dedicated database. |
| Application integration | Apply the same tenant rule to custom endpoints, actions, external services, and application-owned tables. |
Version 22.0.0 strengthens the built-in Workflow Engine Web API path: Data API and RPC API process operations apply the current tenant context to process access.
Application-wide tenant safety also depends on direct provider access, custom queries, domain tables, file storage, caches, and message handlers carrying the same tenant context. Workflow Engine enforces the data it owns; the application extends that boundary across the rest of the system.
Question 4: what is isolated and what may be shared?
The answer differs for operational data and reusable configuration.
| Data group | Tenant behavior |
|---|---|
| Process instances and operational records | Tenant-scoped. This includes process status, parameters, timers, transition history, inbox entries, and approval history. |
| Workflow definitions | A standard definition can be shared, while a tenant-specific definition can replace it for one customer. |
| Forms | Shared forms can act as defaults, with tenant-specific forms taking priority where configured. |
| Global Parameters | Values can live in shared or tenant scope. If the application wants shared values to act as defaults, that fallback should be an explicit policy. |
This gives a SaaS product a useful customization model: most customers can run a standard approval flow, while selected customers use a tenant-specific version without requiring another application deployment.
The safe general rule is simple: process state belongs to one tenant; reusable definitions and configuration may be shared deliberately. Records without a tenant value follow the sharing and fallback policy of their resource type.
Question 5: where does Workflow Engine's responsibility end?
Workflow Engine NEO 22.0.0 supplies the workflow-side building blocks: tenant topology, runtime lifecycle, tenant-aware API behavior, and shared or scoped workflow resources. The surrounding SaaS architecture decides:
- which customers require dedicated storage;
- how databases, secrets, identities, and non-workflow data are provisioned;
- how users acquire membership in a tenant;
- how long offboarded tenant data is retained;
- how custom application code enforces tenant context; or
- how tenant limits, billing, and product entitlements are applied.
These are SaaS architecture and product-policy decisions. Workflow Engine participates in one part of the boundary, and the application completes it. Each responsibility should have an explicit owner.
An architecture review checklist
Use this checklist during the architecture review. For every item, record the decision, its owner, and the evidence that confirms it. The review is complete when the team has produced all five artifacts.
- [ ] A tenant placement map. Assign each customer segment to a logical, physical, or hybrid topology. Show which tenant IDs share a runtime and database, which customers receive dedicated resources, and which requirement drives each choice.
- [ ] A tenant lifecycle flow. Document the complete onboarding and offboarding sequence: infrastructure provisioning, secret creation, tenant registration, traffic activation, routing removal, archival, and deletion. Name the system or team responsible for every step.
- [ ] An authorization rule and its test. Define where the tenant ID comes from, how caller membership is verified, and which permissions are required before routing. Add a test that changes the tenant ID while keeping the same identity and confirms that access is rejected.
- [ ] A data ownership matrix. Classify processes, operational records, workflow definitions, forms, and Global Parameters as tenant-owned or shared. Record the override and fallback policy for every shared resource type.
- [ ] A responsibility map for integrations. List custom endpoints, direct provider calls, background jobs, application tables, files, caches, and messages. Assign an owner and document how each path receives and enforces tenant context.
The resulting placement map, lifecycle flow, authorization test, data matrix, and responsibility map become the implementation contract for multitenancy. They give developers, security reviewers, and operations teams the same definition of the tenant boundary.
The detailed migration steps and API changes are in the Workflow Engine 22.0.0 release notes. For Workflow Engine NEO licensing options, see Optimajet product pricing.
If you want to check our answers against your own architecture, the upgrade details are on our blog, and my team does demo walkthroughs where we build the argument on your tenancy model, not ours.
Top comments (5)
Runtime tenant registration is a meaningful improvement, especially for SaaS platforms where onboarding should never require a production restart.
I also like the hybrid model, but I’d add one architectural caution: API-level tenant isolation is only one layer. Background jobs, caches, direct persistence access, audit exports, and operational tooling all need the same tenant context and enforcement.
The real test is whether a missing or incorrect tenant context fails closed everywhere, not only through the public API.
Mustafa, thank you for this comment, I agree with your main point. А missing tenant context should fail everywhere, not only in the API.
We did push tenant context below the API in this release: timers and process records take their tenant from the process instance, and IPersistenceProvider signatures now require a tenant id, so a provider that ignores it won't compile. But you're right that the engine only covers its own surface. Raw SQL, caches, ops tooling stay the platform's responsibility, and that's where I see most real problems.
And while I have the luck of talking to someone who has clearly been around these systems, let me use it. Would Workflow Engine NEO pass your own technical bar as the main workflow solution for a .NET application? If yes, I'd like to know what would tip the scale for you. And I'm honestly even more interested in the other side: what weaknesses do you see, what's missing, what would stop you, if that's relevant to your work at all. Feel free to be blunt. That kind of feedback is worth more to me than praise.
Thanks in advance,
Mike Lukinov
Thanks, Mike. I spent some time with the live designer and documentation after your reply.
Yes, Workflow Engine NEO would pass my initial technical bar and I would put it into a serious PoC for a .NET SaaS or ERP. The embedded designer, scheme versioning, hybrid tenancy, runtime tenant registration, and explicit tenant context in the persistence contracts are all strong architectural choices.
What would decide whether it became the main workflow solution would be operational behaviour rather than additional designer features:
One design choice I would examine especially carefully is treating an empty tenant ID as shared data. Hybrid tenancy is useful, but I would want global object creation to be an explicit privileged operation, so a missing tenant context fails closed rather than accidentally creating something visible to every tenant.
So my honest answer is: yes, it is a credible candidate. What would tip the scale is proving recovery, observability, idempotency and tenant-level operations under failure—not adding more boxes to the designer. Features attract the first demo; operational behaviour decides whether the engine stays in production for ten years.
Mustafa, honestly, this comment is better than most architecture reviews. Thank you.
I tried to answer here, deleted the draft twice, and gave up )))
Questions this good can't be answered in a comment box without turning into marketing. You'd catch that instantly.
So I'll do it properly, this post becomes a series, and your list is the outline. Recovery first, then observability, then tenant operations. Your point about empty tenant ID gets a direct answer there too, it's the sharpest one.
Thanks, Mike—I really appreciate that.
I also appreciate that you didn’t try to squeeze those answers into a marketing reply. Those topics deserve the space, and I’d much rather read a deep technical article than a short comment.
Looking forward to the series. Those operational aspects are exactly what separate an impressive demo from a platform teams can confidently build on.