When Flowable multi-tenancy with tenant identifiers fits your platform
Flowable multi-tenancy lets one engine serve several organizations or business units by attaching a tenant identifier to deployments, process instances, tasks, jobs and history. The engine partitions data by that identifier, but it does not enforce tenant isolation. Your application must confirm that each caller belongs to the tenant it asks for, because Flowable will return or act on data for any tenant ID it receives. Treat the tenant check as part of your design, not as a default the engine provides.
Teams usually choose this model when the business units share one process platform, one operations team and similar workflows, such as a shared-services group running the same approval process for several subsidiaries. The tenant identifier can be up to 256 characters, and it is set at deployment and inherited by definitions, instances, tasks, jobs and history. That inheritance means a single deployment step carries the tenant context through the whole lifecycle, which keeps each tenant's work traceable without a separate engine per customer. Ask your team whether the tenants' process definitions truly match. If they diverge heavily, the shared model adds coordination cost.
The alternative is a separate engine and database schema per organization. The Flowable docs describe this multi-instance setup as adding complexity and maintenance, but they note it may be the right solution in some cases, such as when regulators, contracts or data residency rules require hard separation. Before you commit, confirm with your security and compliance leads whether logical separation with application-level checks satisfies those obligations. Also plan the authorization layer in writing, covering who may deploy per tenant, who may query tasks, and how administrators are scoped, before any build starts.
Tenant identifiers or a separate engine per organization
This table compares running several organizations on one Flowable engine with tenant identifiers against running a separate engine and database schema for each organization. Read each row as a decision factor, and use the last row to see which setup fits your number of organizations, their isolation requirements and the team that will operate the platform.
| Factor | Tenant identifiers on one engine | Engine and schema per organization |
|---|---|---|
| Isolation approach | Logical separation: a tenant identifier of up to 256 characters on deployments, instances, tasks, jobs and history | Physical separation: each organization has its own engine and database schema |
| Access enforcement | Your application must check tenant membership on every engine call, because Flowable does not enforce tenant rules | The engine boundary limits access, though your application still controls which engine a caller reaches |
| Operational load | One engine, one upgrade cycle and one monitoring setup, with tenant-aware queries and checks to maintain | One engine, schema and upgrade path per organization, multiplying patching, backups and monitoring |
| Per-tenant versioning | The same process definition key can be deployed for each tenant with its own version, since key, version and tenant identifier must be unique | Each engine versions its own definitions independently, with no shared version sequence |
| Noisy neighbor risk | Tenants share the async executor, thread pools and database, so heavy load from one tenant can affect others | Load is confined to each engine's own resources, subject to the shared infrastructure beneath them |
| Complexity noted by Flowable | Lower setup and maintenance overhead, with the access layer as the main added work | The Flowable docs note this adds complexity and maintenance but may be the right solution for some cases |
| When it fits | Many organizations with similar process models, a single operating team and a strong application-level authorization layer | Few organizations with strict isolation, separate data residency or independent release schedules, and a team able to run several engines |
| Questions to confirm | Which tenant checks your application needs, and how audit and history queries are scoped per tenant | Expected number of engines, the operating model for upgrades and the cost of running each one in your environment |
How to set up tenant-scoped deployments and queries
This sequence turns a shared Flowable engine into a multi-tenant setup where each organization's definitions, instances, tasks and jobs carry a tenant identifier, and where your application verifies every read and write against that identifier before the engine sees it.
Define the tenant identifier scheme
Agree with the platform owner and the application team what a tenant identifier looks like, who issues it and how it maps to each organization or business unit. Flowable accepts tenant identifiers of up to 256 characters, so record that limit in the design and reject identifiers longer than it, along with any characters your database collation or URLs handle poorly. Keep identifiers stable, because they are inherited by definitions, instances, tasks, jobs and history and are difficult to change later. The output is a short written scheme that names the source of each identifier and the validation rule applied on creation. Check: a sample of proposed identifiers passes the validation rule and none exceeds the limit.
Deploy the same process definition key per tenant
Deploy the BPMN resource once for each tenant, setting the tenant identifier on every deployment so the definitions are partitioned from the start. Use the same process definition key across tenants, since Flowable allows one key to exist for several tenants. Do this through the deployment pipeline your team controls, whether that calls the Java API or the REST API, and record which tenant each deployment belongs to. The output is one deployment per tenant that references the same key. Check: querying process definitions by key returns one definition per tenant, and each carries the expected tenant identifier.
Verify version uniqueness on key, version and tenant
Confirm that versioning behaves per tenant. Flowable makes the combination of process definition key, version and tenant identifier unique, so each tenant's version sequence increments independently of the others. Deploy a changed resource to one tenant only and check that the new version number appears for that tenant while the other tenants keep their existing versions. Also confirm that a deployment with the same key and tenant identifier produces the next version rather than a conflicting record. The output is a recorded version table per tenant. Check: the version numbers for each tenant match the deployments you made, with no gaps or cross-tenant increments.
Start instances and tasks with the tenant identifier
Update the application code path that starts processes so each call passes the tenant identifier of the authenticated user's organization, and so that tasks, jobs and any custom queries you run inherit or filter on that identifier. Derive the tenant from the server-side session or token, never from a request parameter the client can change. The output is a start path that refuses to run when no tenant can be resolved. Check: starting a process as a user from tenant A creates an instance whose tenant identifier is A, and a start request with a mismatched tenant identifier is rejected before the engine is called.
Add tenant filters to every engine query
Inventory every call your application makes to the runtime, task, history, job and management services, including REST endpoints and reporting jobs, and add a tenant filter to each one. Flowable partitions data by tenant but does not enforce that users only see their own tenant, so the filter and the check that the caller belongs to that tenant must live in your application or API layer. Put the filter in shared repository or service code where possible so new endpoints inherit it. The output is a list of queries with the filter applied to each. Check: the inventory has no engine call without a tenant condition, except administrative jobs that you have documented and restricted.
Test that cross-tenant reads and writes fail
Write tests that authenticate as a user of tenant A and attempt to read, complete, claim, suspend or delete tenant B's instances, tasks, jobs and history, using both the Java API and the REST endpoints. Include requests that pass a foreign tenant identifier, omit the identifier, or reuse a process instance or task ID from another tenant. The tests should also confirm that same-key definitions in each tenant run independently. Run them in a non-production environment that mirrors your deployment. The output is a passing test suite recorded as part of the release evidence. Check: every cross-tenant attempt returns an error or empty result, and the test suite fails when a filter is removed.
Confirm access checks in the calling layer
Review the authorization logic that sits between your users and the engine, and confirm that tenant membership is checked on each request, that roles inside a tenant are enforced, and that administrative operations across tenants are limited to a small, named group. Compare this review with your identity provider's group or organization model so that a user removed from a tenant loses access on their next request. The output is a signed-off access matrix. Check: a user whose tenant membership was removed in the identity source can no longer read or act on that tenant's data during testing.
Document the tenant model for operations and audit
Write down the tenant identifier scheme, the deployment steps for each new tenant, the versioning behavior your team relies on, the query filter pattern and the cross-tenant test cases. Note where the engine's history records carry the tenant identifier so that evidence requests can be answered per tenant. Mention in the runbook that the multitenancy model is one option among others, and that Flowable's documentation describes running a separate engine and database schema per organization as an alternative with more complexity and maintenance. The output is a runbook that your operations and compliance staff can use. Check: an engineer who did not build the setup can onboard a new tenant from the runbook alone in a test environment.
How per-tenant versioning works with one process definition key
Flowable treats a process definition as unique by the combination of process definition key, version and tenant identifier, so the same key can exist once per tenant and each tenant's copy carries its own version sequence. A deployment for tenant acme that creates version 4 of loanApproval does not change the version numbers that tenant northwind sees for the same key. The practical result is that each organization can release on its own schedule, but the engine does not coordinate those releases for you. Nothing in the engine tells you that three tenants are on different versions of the same logic, so that visibility has to come from your own deployment records.
Those separate version sequences change how you govern releases. A shared change to a key may need to be deployed to every tenant that uses it, and each deployment creates a new version under that tenant's identifier, so a single release becomes a set of tenant-scoped deployments that must be tracked together. Instance migration is also tenant-scoped: moving running instances from one version to another has to target the right tenant's definitions, and a migration validated for one tenant's version history does not prove the same mapping for another. Rollback needs the same care. Reverting a tenant means deploying or activating an earlier definition for that tenant alone, and instances already started on the newer version stay there unless you migrate them.
Confirm with your engineering and release owners how your pipeline records the tenant identifier on each deployment, who approves tenant-specific versions, and whether a release can be halted for one tenant without affecting others. Ask Flowable or your partner to show how your version list per tenant is queried and reported, and test a rollback for one tenant in a staging environment before relying on it in production. The Flowable advanced documentation describes the uniqueness rule and should be the reference for your team's deployment conventions.
Access checks your application must add
Flowable stores a tenant identifier on deployments, instances, tasks, jobs and history, but it does not decide who may act on which tenant. Every control below sits in the layer that calls the engine, so each one needs an explicit check and a test that proves a user from one tenant cannot reach another tenant's data.
Tenant membership on every API call
Resolve the caller's tenant from the authenticated identity, never from a request parameter alone, and compare it with the tenant on the process definition, instance or task before the engine call runs. Apply the same check to both the Java API and the REST API, since a check on one path does not cover the other. To verify, call each endpoint with a token for tenant A and an ID that belongs to tenant B, and confirm the request is refused.
Tenant filters on task and history queries
Task lists, inbox queries and history searches return data across tenants unless your query adds the tenant filter. Build a single query helper that always sets the tenant from the authenticated context, and avoid letting callers pass a free-form tenant value into it. To verify, log in as a user in one tenant, run every list endpoint and confirm no record from another tenant appears, including history for completed instances.
Protected deployment and admin endpoints
Deployment, migration, job management and engine administration calls can change definitions or move instances for every tenant. Restrict them to platform operators with a separate role, and keep them off the tenant-facing API surface. To verify, call each administrative endpoint with a standard tenant user token and confirm a denial, then review the deployment pipeline to confirm it sets the tenant ID explicitly.
Tenant IDs kept out of user input
If a tenant identifier can be typed into a form, URL or message payload, a user can attempt to act under another tenant's ID. Derive the tenant from the session or service identity and treat any incoming tenant value as untrusted. To verify, send requests with a substituted tenant field and confirm the application ignores it or rejects the call, and check that process variables cannot override the tenant.
Tenant-aware job and timer access
Async jobs and timers carry a tenant identifier and run without a user session, so they can act on data outside the request that created them. Confirm the job executor and any custom delegates re-check the tenant from the job's own data before they update records. To verify, create timers for two tenants, let them fire, and confirm each action touches only its own tenant's instances.
Identity mapping per tenant
Flowable identity management can be replaced with your own IdmIdentityService implementation, and that service is where group and role membership is resolved for tasks. Map each user's groups to tenant-scoped roles in that service, so candidate groups from one tenant cannot match users in another. Ask the vendor or your team to confirm how your chosen identity service applies tenant scope before go-live, and test it with users who share a group name across tenants.
Questions teams ask before adding tenants to Flowable
What does adding tenants to a Flowable engine involve?
It involves setting a tenant identifier on deployments, instances, tasks and jobs, then building the access checks your application needs, because the engine does not enforce tenant rules itself. The effort depends on how many tenant-aware touchpoints your application has: deployment pipelines, the code that starts instances, task inboxes, reporting queries, and any REST calls that expose process data. Each of these needs the tenant identifier carried through consistently. Ask any partner to list the touchpoints in writing before agreeing a fixed scope, since that list is what drives the work.
Are separate Flowable engines cheaper to run than tenant IDs?
Usually not in operational effort, though the trade-off is different. The Flowable docs contrast tenant-based multitenancy with a setup where a separate engine and database schema run per organization, noting that this adds complexity and maintenance but may be the right choice in some cases. A shared engine has fewer runtimes to patch, upgrade and back up, but places more weight on your access checks. Separate engines isolate data at the database level and can simplify per-tenant upgrade timing. Cost depends on how many tenants you have, how much they differ, and how often you need to upgrade them independently. Ask for the cost of each model over your expected upgrade cadence.
Does Flowable stop one tenant from reading another tenant's data?
No. Flowable partitions data by tenant identifier, but the Flowable advanced documentation states that it does not enforce tenant rules. Checking that a user belongs to the right tenant has to happen in the layer that calls the engine. In practice, your application must filter every query, reject task claims and variable reads across tenant boundaries, and validate the tenant on each REST request. Any API that accepts a process instance ID without checking its tenant can expose another organization's data. Treat tenant checks as part of your security design and test them with users from different tenants.
How long does tenant setup take?
The duration depends on scope rather than on the engine alone. Duration grows with the number of tenant-aware code paths, the number of existing process definitions that need tenant-specific deployment, whether you are adding tenants to a system already in production, and the depth of your testing for cross-tenant access. Adding tenants to a greenfield application is generally shorter than retrofitting a live system that already holds instances without tenant identifiers. No duration is given here because none is supplied for this topic. Ask for a timeline tied to a written list of touchpoints, deliverables and test cases.
What must our team provide before the work starts?
Your team should provide the process definitions in scope, a list of tenants and how each one is identified, the identity source that maps users to tenants, and the existing application code that starts, queries and displays process data. You also need a test environment with representative users in more than one tenant, and a decision on whether tenants share one engine or run separately. Clear ownership on the business side matters too, because someone must confirm which tenant rules are correct. Confirm these inputs in the statement of work so the fixed scope reflects what you can actually supply.
Can our own engineers add tenants to Flowable internally?
Yes, if your team has Java and Spring experience, understands the Flowable engine's tenant model, and can build and test the access layer. The work is not mainly about configuration. It requires careful review of every place the engine is called, and a habit of writing tests that prove one tenant cannot see another's data. Teams without that experience, or without time to review the whole call surface, often bring in a partner for the design review and test plan. A written scope lets you compare the internal effort against an outside quote on equal terms.
Does tenant separation help with compliance audits?
It can support evidence, but it does not satisfy an audit by itself. Auditors look for controls that are designed, implemented and operating over time. Tenant checks in your application, along with logged access decisions and tested cross-tenant restrictions, can serve as evidence for access control requirements. Whether that evidence is sufficient depends on the framework and the auditor. Independent auditors and certification bodies issue reports and certifications, and DeployOpen prepares systems and evidence for those assessments without issuing them. Confirm the expected controls with your auditor before designing the evidence trail.
Does each tenant get its own process versions?
Yes. Flowable requires the combination of process definition key, version and tenant identifier to be unique. That means the same process definition key can be deployed for several tenants, and each tenant can have its own version history. This lets one tenant move to a revised process while others remain on the earlier version. It also means your deployment pipeline must set the tenant identifier on every deployment, or definitions will not land where you expect. Plan a version and rollout policy per tenant before the first production deployment.
What tenant separation contributes to audit evidence
Tenant separation in Flowable is one input to the evidence an assessor reviews, not a finding in itself. When your organization is assessed against the security common criteria in a SOC 2 examination or against the access control requirements in ISO/IEC 27001, the question is whether you can show that users see and change only the tenant data they are entitled to, and that you can prove it over time. Tenant identifiers on deployments, instances, tasks and jobs give you a consistent key to filter on, but the evidence comes from the checks your application performs before each engine call, the logs that record those checks, and the history retained in the engine. DeployOpen prepares that evidence, but auditors and certification bodies are the ones who issue reports and certifications.
Start by listing which tenant-scoped controls your application enforces and where each one is recorded. Typical items are the mapping from user to tenant, the check that a tenant identifier on a request matches that mapping, the rule that deployments are made only by a tenant administrator role, and the history level chosen for each tenant. Confirm with your auditor which of these they test, whether they sample tenant-scoped queries, and whether they expect a Type 1 point-in-time view of the design or a Type 2 view of operating effectiveness over a period. The answer changes how much logging and retained history you need and how long it must be kept. Retention and history settings are covered elsewhere on this page, so treat them here as inputs to the evidence plan rather than as configuration steps.
Plan for the cases an assessor will probe. Ask whether an access check failure is logged with the user, tenant identifier and requested resource, and whether those logs are kept separately from the application data they describe. Test a cross-tenant request in a non-production environment and keep the result, since a passing test is easier to defend than a design statement. Also record who may change tenant mappings, because a change to that mapping alters every later access decision. If your auditor expects a separate engine per organization instead of a shared engine with tenant identifiers, raise that early, because the Flowable documentation notes that the multi-instance model may suit some cases and it changes what evidence you must produce.
How DeployOpen scopes tenant work before build
DeployOpen fixes the tenant model in the written scope before any build starts, because Flowable stores a tenant identifier on deployments, instances, tasks, jobs and history but does not decide who may see or change them. The scope names each tenant, the tenant ID value used for it and the roles that may act inside each one. It also records which layer of your application performs the membership check, since that check is yours to build. Agreeing these points in writing turns an open design question into a list of components that can be tested and signed off.
The access model is the part most likely to be underspecified. DeployOpen plans which identity source supplies tenant membership, how the calling application maps a user to a tenant ID before any engine call, and which operations (starting instances, claiming tasks, querying history, deploying definitions) each role may perform. Where a deployment needs a stronger boundary than a shared engine can give, the scope should say so early, because the Flowable advanced docs describe a multi-instance setup with a separate engine and database schema per organization as an alternative with more maintenance. Your security and architecture teams should confirm which option they accept before the fixed scope is signed.
The scope also sets the cross-tenant isolation tests that must pass before go-live. Illustrative test cases include a user from tenant A requesting a task ID that belongs to tenant B, a query that omits the tenant filter, a job executed by the async executor for the wrong tenant, and a deployment of the same process definition key under two tenant IDs with separate version numbers. DeployOpen implements these checks in your self-hosted environment, hardens the calling layer, and documents the expected results. Ask for the test list, the environments it runs in and the evidence delivered to your team as part of the quote.
How DeployOpen delivers Flowable multi-tenancy
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, including Flowable engines. For multi-tenancy with tenant identifiers, the work starts with a written scope that settles which tenant rules the engine handles and which rules your application must enforce.
How we scope
- Map each organization or business unit to a tenant identifier and document how identifiers are issued and stored.
- Define which deployments, instances, tasks, jobs and history records carry a tenant identifier in your model.
- Agree in writing which tenant access checks sit in your application layer, since the engine does not enforce them.
How we build
- Configure tenant-aware deployments so each tenant can version the same process definition key independently.
- Build the access layer that checks user tenant membership before every engine call, including REST and task queries.
- Test cross-tenant reads and writes on tasks, jobs and history, and confirm that async jobs run under the correct tenant.
How we hand over
- Deliver the written tenant model, access rules, deployment steps and query patterns your engineers will maintain.
- Document the trade-off between tenant identifiers and a separate engine and schema per organization, for your records.
- Walk your engineers through adding a new tenant, deploying its definitions and reviewing its access checks.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer for tenant access rules as your tenants grow.
- Confirm with your team which Flowable version you will run and retest tenant isolation before each upgrade.
