Tenants and multitenancy

Tenants are business aliases that represent organizations, companies, or divisions of companies. Multitenancy allows a single SPE instance to support multiple tenants by segmenting the database to isolate the resources of each tenant.

SPE securely processes data from multiple tenants and stores it, if needed, in the SPE database. Preventing users from accessing artifacts that belong to other tenants allows a single SPE instance to support multiple customers.

Tenant access is managed by the Trading Partner UI. When you log in as a user, the system knows which tenant that you are allowed to see. Users can access objects that are controlled by their tenant (that is, the tenant under which the user is created) but not the objects of other tenants. Unless you are a system administrator, you are restricted to the artifacts or resources in the tenant to which you are assigned.

Multitenancy isolates access to resources in the following ways:
  • Assets are not visible across tenants, except to a user with the system administrator role. A system administrator can manage resources across tenants.
  • A user is assigned to a single tenant and can only view, import, and update (depending on their assigned roles) resources or artifacts for that tenant.
  • A user profile for a tenant cannot be shared between tenants or copied from one tenant to another.
  • The results of SPE functions are restricted to the tenant where the function was performed. For example, if TenantA_user1 creates an envelope from existing data, the envelope is created under the TenantA profile and is only available to TenantA users with the appropriate role assignments.

Multitenancy differs from role-based access, which controls access based on the type of artifact or resource. For example, you are a user who has access to manage envelopes, but not maps. Multitenancy restricts your envelope access to those of your assigned tenant (that is, the tenant under which you were created), but not those of another tenant.

Tenant IDs

A Tenant ID (tenant identifier) is a unique identifier or alias for the tenant and is based on the tenant name. The tenant ID is assigned to the tenant's resources (such as envelopes, maps, and outbound documents). Based on the Tenant ID, database messages are automatically filtered for further action by tenant users, as determined by their roles.

Terminology: The tenant ID might also be called the Reference ID, depending on the context in which it is used. Always use the terminology for the implementation that you’re using. A command might expect the reference ID or the tenant ID, and they are not interchangeable.
Tip: To avoid confusion, make the tenant name and tenant ID the same.

Models for implementing multitenancy

Your multitenancy implementation can follow a hierarchical or a silo model.

The hierarchical model allows the system to be managed centrally, with certain functions and artifacts controlled centrally, but others delegated to different tenants in order to be closer to the customer. For example, a services provider has two U.S. states as clients: Florida and Nevada. Both Florida and Nevada users can use artifacts from the DEFAULT tenant. If you are a user in the Florida tenant who wants to view or modify envelopes, ITXA checks artifacts that belong to your tenant (Florida) first. If the envelope that you want is not in the database segment for that client, ITXA uses the appropriate resource in the DEFAULT tenant.

The hierarchical model can also apply to an large corporation or other organization when some independence is desired for individual departments or groups within the larger entity.

In the silo model, each tenant has its own set of artifacts, and the system only looks at one tenant ID. Each tenant might have their own code lists, compliance maps, HIPAA rules, and so on. When I run as a user under the Nevada tenant, I only see the Nevada artifacts. To do this, deploy packs are separately (using the spedeploy-packs command -t= option) for each tenant.

Administering multitenancy

When SPE is installed, the DEFAULT tenant is available.

To add users to a new tenant, create the new tenant in the Trading Partner UI and create users under that tenant. Users that are created under the User Profile tab are added to the DEFAULT profile. Users cannot be moved from one tenant to another.

Command line behavior

No user ID is associated with the command line, which is treated like a system administrator. Commands executed from the command line, by default, are assumed to apply to the DEFAULT tenant. For example, the speimport command imports resources into the DEFAULT tenant unless the -refid option is used to supply the reference ID of an alternative tenant.

Run time behavior

At run time, ITXA by default only looks at artifacts that are in the DEFAULT tenant. To specify a different tenant, use the appropriate option for your host environment, noting the following:
  • Multitenancy is not supported for ITXA with Sterling B2B Integrator. When Sterling B2B Integrator and ITXA are run together, Sterling B2B Integrator manages ITXA users and roles.
  • For IBM® Integration Bus, set the tenant ID for the entire execution group in the SPE.ReferenceId property in the speiib.properties file. Use the reference ID of the tenant.
  • For the ITX SPE adapter, specify one or more tenants by tenant ID in the order that you want resources used. If multiple tenants, including the DEFAULT tenant, use semicolons to separate the list.
Important: Always use the terminology for the implementation that you’re using. Specify the tenant by tenant ID or reference ID, as required, not tenant name.
If you are using the hierarchical model with multiple tenants, specify the list with each tenant separated by a semicolon, in the order that you want them to be used. Any number of tenants can be listed, and the list is read left to right. This example is for IBM Integration Bus: 
SPE.ReferenceId=Florida;DEFAULT
means to use artifacts from the Florida tenant first, then artifacts from the DEFAULT tenant.