Skip to main content

Multi-tenancy

Multi-tenancy is the ability of the system to cope with multiple tenants. Such a tenant can be a company or department typically consisting of a number of users and groups. The main point of multi-tenancy is that the data of a given tenant is inaccessible by users of another tenant.

The Tenant Identifier​

Multi-tenancy in Flowable Work or Engage follows the same pattern as the open source engines: all types of data get a so-called tenant identifier added to distinguish which tenant the data belongs to.

  • When running in single tenant mode, the tenant identifier is an empty string (consistent with the default in open source).

  • When running in multi-tenant mode, a default tenant (also named default) is created, in addition to all configured regular tenants.

All users and groups in the system have such a tenant identifier to indicate the tenant they are members of.

The Default Tenant​

The default tenant is handled specially:

  • Definitions deployed to this tenant are considered shared by all tenants. This means that if you have, for example, a process definition with key abc and start a process instance by key:

    • a lookup is first done in the current tenant of the user starting the process instance. If found, that process definition is used (this means that it is always possible to override in a tenant specific way the shared definition).

    • if the previous lookup returns no results, a lookup in the default tenant is done.

This applies to all definitions: process, case, user definition, template, action, etc.

Users that are part of the default tenant and are part of the flowableAdministrator group are considered super administrators. Such users have access to data of all tenants.

Users in a tenant that are part of the flowableAdministrator group are considered tenant administrators and have only access to all data of that particular tenant.

Configuration​

To enable multi-tenancy, set the following property:

flowable.platform.multi-tenant.enabled=true

It is also needed to configure for which tenants the default apps are deployed. This is done with the following setting:

flowable.platform.multi-tenant.auto-deploy-tenants=acme,megacorp

With this setting, all definitions (apps, user deployments, process definition, case definitions, etc.) are deployed to both the 'acme' and the 'megacorp' tenant.

If you want to deploy all models to only the default tenant, use:

flowable.platform.multi-tenant.auto-deploy-tenants=default

This, therefore, makes everything on the classpath shared by all tenants. This is typically the proper use case for the classpath models.

The package for the apps is com/flowable/app/default or com/flowable/app/custom. When apps are placed in the custom package, the apps from default are ignored. This way, projects can easily override any defaults that might be present.

To create users or groups per tenant, it is required to have a tenant setup JSON file for each tenant. The tenant JSON files are put in either (similar to single tenant): com/flowable/tenant-setup/default or com/flowable/tenant-setup/custom.

For example, the tenant JSON file for the 'acme' tenant is named acme-tenant-setup.json. The file has the following format where the tenantKey is the tenant identifier.

{
  "name": "Acme ",
  "tenantKey": "acme",

  "groups": [
    { "key": "flowableUser", "name": "Flowable User" },
    { "key": "flowableAdministrator", "name": "Flowable Administrator" },
    ...
  ],

  "users": [
    {
      "firstName": "Shane",
      ...
    }
  ]
}

Note: A tenant setup file without tenantKey has all users and groups created in the default tenant.

Deploying from Flowable Design to a specific tenant​

To deploy an app from Design to a certain tenant by changing/setting the following property in Design:

flowable.modeler.app.deployment-api-tenant-id=default

where default is the tenantKey of the tenant you want to deploy to.

The tenant identifier is implicitly determined on the Work or Engage side by that user invoking that REST publish call.

Deploying from Flowable Design to different tenants​

To deploy apps from Design to a user-specific tenants the following property in Design is required:

flowable.modeler.app.multi-tenant-enabled=true

In Flowable Design different users which can deploy apps to user-specific tenants can be added. Therefore, a (non-administrator) user needs to be added in Flowable Design with a specific Tenant ID (Is administrator needs to be unticked).

The Tenant ID of the user determines in this case to which tenant the underlying app is going to be deployed.

Otherwise, for admin users it is possible to activate a Tenant-switcher in Flowable Design by adding the following properties in addition to the flowable.modeler.app.multi-tenant-enabled property set to true.

flowable.modeler.app.tenant.list-provider=fixed
flowable.modeler.app.tenant.fixed-tenant-ids=default,tenant1,tenant2

The property flowable.modeler.app.tenant.list-provider enables the tenant-switcher when is set to fixed or database:

  • For fixed the available tenants can be configured by a comma-separated list with the property flowable.modeler.app.tenant.fixed-tenant-ids.

  • For database the available tenants can be configured via the database table FLW_DE_TENANT.

Multi-tenancy Implementation Notes​

Group ids in a tenant are prefixed with their tenant identifier. The reason is that group ids need to be unique within the whole system (like user ids).

For this purpose, a group key exists that holds the original group id (for people that are used to working with the open source users and groups). When writing multi-tenant aware logic, one must take into account (e.g., for permissions) that the group keys need to be checked and not the ids.

In single tenant mode, the id and group key are equivalent.