# Dynamic tenant registration in NEO 22.0.0

Source: https://workflowengine.io/blog/workflow-engine-neo-22-0-0-dynamic-tenant-registration/
Site index for agents: https://workflowengine.io/llms.txt (products, licensing, documentation hosts, package names).

Workflow Engine NEO 22.0.0 adds tenants at runtime and scopes schemes, forms, and process data per tenant. What changed, with code and upgrade steps.

[Workflow Engine by Optimajet](https://workflowengine.io/products/workflow-engine-neo/) version 22.0.0 shipped on July 16, 2026. The release brings dynamic tenant registration to Workflow Engine NEO: tenants are added and removed at runtime through the tenant registry API, and the ASP.NET host keeps serving requests the whole time. The same release extends tenant scoping to every data layer the engine stores, from workflow schemes to approval history.

If you run a multi-tenant SaaS on .NET, this is the release that turns customer onboarding from a restart into an API call. Here is what changed, what it looks like in code, and what the upgrade costs.

## What is dynamic tenant registration

Dynamic tenant registration means the set of tenants served by the Workflow Engine Web API can change while the application is running. `IWorkflowTenantRegistry.RegisterTenantsAsync` adds a tenant, `UnregisterTenantsAsync` removes one, and no host restart or redeploy is involved. Before 22.0.0, the tenant list was fixed at startup.

```csharp
var tenantRegistry = services.GetRequiredService<IWorkflowTenantRegistry>();

var tenants = await tenantRegistry.RegisterTenantsAsync(new WorkflowTenantCreationOptions
{
    TenantIds = ["TenantA"],
    PersistenceProviderId = PersistenceProviderId.Mssql,
    ConnectionString = connectionString
});

var tenant = tenants.Single();

// Removing a tenant works the same way. The host keeps running.
await tenantRegistry.UnregisterTenantsAsync(tenant);
```

Tenants registered this way start automatically and shut down gracefully when removed. If your application manages tenant lifecycle itself, mark the tenant as externally owned with the new `WorkflowTenantLifecycleOwnership` setting and the registry skips the automatic lifecycle calls.

Reads stay consistent while the list changes. The new `IWorkflowTenantSnapshot` interface gives your code an immutable, point-in-time view of the registered tenants, so a request never observes the tenant list mid-change.

## What is tenant-scoped in Workflow Engine 22.0.0

Tenant scoping in 22.0.0 covers all engine data, not just processes:

| Engine data | Behavior in 22.0.0 |
| --- | --- |
| Workflow schemes | Tenant-scoped; records with an empty tenant value stay shared |
| Global Parameters | Tenant-scoped; system types are closed to generic Data API access |
| Forms (Forms Plugin) | Tenant-specific form resolves first, shared form is the fallback |
| Process records | Statuses, timers, persistence parameters, transition history, inbox entries, and approval history follow the process's tenant |

Scheme scoping is the part SaaS teams tend to underestimate. When customers customize their approval flows, per-tenant schemes are the difference between one customer's process change and a change every customer inherits on the next publish. The full model is described in the [multi-tenancy feature overview](https://workflowengine.io/features/multi-tenancy/) and the [Web API multitenancy documentation](https://workflowengine.io/documentation/web-api/multitenancy).

## How the API enforces the tenant boundary

The tenant boundary in 22.0.0 is enforced by the API layer, not by convention in your code. A Data API request for another tenant's process returns a not-found result. RPC API endpoints check the process tenant against the current HTTP tenant and reject cross-tenant commands. Even `rpc/is-process-exists` answers `false` for a process that belongs to another tenant, so one tenant cannot probe whether another tenant's data exists. In multi-tenant mode, a request with a missing, invalid, or forbidden tenant ID gets 403 Forbidden.

The release also closes a quieter hole: system Global Parameter types (security settings, LDAP configuration, CORS settings, and similar) are no longer reachable through generic Data API operations. Those requests return 400, and management goes through the specialized APIs.

If you are deciding which HTTP surface your callers should use under this model, start with our guide on [choosing between the Data API and RPC API](https://workflowengine.io/blog/data-api-vs-rpc-api-in-workflow-engine-neo/).

## What happens to existing data after the upgrade

Nothing changes on its own. The model is hybrid on purpose: records with an empty tenant value are treated as shared and stay visible across tenants, exactly as they behaved before the upgrade. New records created in a tenant context are written with that tenant ID. You can upgrade first, keep your standard schemes shared, scope the customer-specific ones, and let historical data age out as shared records. No day-one migration project.

## How to upgrade to 22.0.0

This is a major release with breaking changes, so plan the upgrade rather than bumping package versions in passing:

- Update all Workflow Engine packages to 22.0.0.
- SQL providers: call `RunMigrations()` before starting the updated runtime. Bundled migration scripts run automatically.
- MongoDB: run the `update_22.0.0.js` script manually to add the indexes that tenant-aware queries need.
- Custom `IPersistenceProvider` and `IWorkflowTenant` implementations must be updated to the new contracts, including tenant-aware method signatures.
- The `AssignmentPlugin` has been removed.

The platform moved as well: the [Forms Plugin behind workflow forms](https://workflowengine.io/features/workflow-forms/) is now tenant-aware, its frontend packages use Form Engine Core 10.0.1 and Form Engine Designer 10.0.1, and the Angular Designer packages moved to Angular 22. The [22.0.0 release notes](https://workflowengine.io/documentation/release-notes/22.0.0) list every breaking change with a migration scenario for each.

## Frequently asked questions

### Can I add a tenant without restarting Workflow Engine?

Yes. Starting with Workflow Engine NEO 22.0.0, `IWorkflowTenantRegistry.RegisterTenantsAsync` and `UnregisterTenantsAsync` change the tenant list at runtime. The ASP.NET host keeps serving requests while tenants are added or removed.

### How do I onboard a new SaaS customer with Workflow Engine?

Register a tenant from your provisioning code with `RegisterTenantsAsync`, passing the tenant ID, persistence provider, and connection string. Creating the tenant database and storing its secrets remain your provisioning code's job; the engine picks the tenant up without a deployment.

### What happens to my existing data after the upgrade?

Nothing changes on its own. Records with an empty tenant value are treated as shared records and remain visible as before. Only new records created in a tenant context get a tenant ID.

### Is Workflow Engine 22.0.0 a breaking release?

Yes. The tenant contract, parts of the Web API authorization surface, and several persistence provider signatures changed, and the `AssignmentPlugin` was removed. Database migrations are mandatory. Review the release notes before upgrading a production system.

### Do base Workflow Engine and Community Edition include these features?

No. The Web API and full multi-tenancy are capabilities of the separate Workflow Engine NEO product, available since version 19.0.0. Workflow Engine and Workflow Engine Free embed in-process and keep process-level multi-tenancy. The [product comparison](https://workflowengine.io/products/compare/) shows what each product and edition includes.

## See it on your own architecture

The fastest way to evaluate 22.0.0 is a [one-hour demo](https://workflowengine.io/book-a-demo/) where we walk through dynamic tenant registration against your tenancy model. Prefer to try it yourself? Request a Workflow Engine NEO trial key at [trial.workflowengine.io](https://trial.workflowengine.io). Without one, the HTTP API still serves the Designer API and health endpoints; the trial key enables the Data, Search, and RPC groups for evaluation.