Manage Multi-Tenancy

This article contains the following topics:
casm172
This article contains the following topics:
How to Initialize a New Tenant
As the service provider, you may want to build a standard set of data for a new tenant, such as categories, data partitions, ticket templates, and so on. This task can be done by using pdm_extract or pdm_tenant_extract to build a pdm_userload input file containing the data you want.
If necessary, you can edit this file with any text editor. It can then be loaded into the database using pdm_userload with the -t argument to set the tenant column to the new tenant.
The following process describes how to initialize a new tenant:
  1. Create the tenant in the ca_tenant table. Use the online Create Tenant page.
  2. Load the standard data as previously described.
    Use pdm_userload -t to set the tenant.
  3. Create contact records for the new tenant.
    Load outside data or use pdm_userload -t.
How to Convert an Existing Tenant Implementation to the Tenant Object
You may have used data partitions and another CA SDM object to achieve some of the functionality now provided by multi-tenancy. If you want to convert an implementation to multi-tenancy, the first step is to map the data in the previously-used object to the new tenant object. The previously-used object is called the
pre-tenant
object. For most sites with these requirements, the org (organization) object is the pre-tenant object, but the following approach can be used for any pre-tenant object.
  1. If the pre-tenant object is not org, verify that its Majic object definition specifies TENANT_REQUIRED.
  2. Verify the attribute mappings from the pre-tenant object to the new tenant object in the buildtenant.xml file in the following location:
    $NX_ROOT/samples/multi_tenancy
    You must copy buildtenant.xml to the $NX_ROOT/site/cfg directory. In addition, buildtenant.xsd must be in the same directory as buildtenant.xml, or you will receive an error. When you install the product, buildtenant.xsd is located in $NX_ROOT/site/cfg, so you do not have to copy this file.
    The default settings are based on org. If the pre-tenant object is not org, you must edit the file.
  3. Run pdm_buildtenant -f.
    A new tenant is created for each pre-tenant object, and sets the tenant attribute in the pre-tenant object to reference the new tenant.
  4. Log in to CA SDM, and review both the tenant object and the pre-tenant object.
    In some situations, you want to map multiple pre-tenant objects to a single tenant object. To do this, manually update the pre-tenant objects affected, and then delete or inactivate the unused tenants.
How to Populate the Tenant Attributes in Your Tables
To populate the tenant attribute in all or a subset of a table, use the
pdm_settenant
utility. This utility uses a configuration file to select the objects to be tenanted and to specify where to obtain the tenant for the objects. You can specify an explicit tenant, or specify that the tenant should be derived from an SREL reference in the object to be tenanted.
To populate the tenant attributes in your tables using pdm_settenant, complete the following steps:
  1. Create or edit a configuration file.
    The configuration file selects the rows that will have their tenant attribute set and specifies a source for the tenant attribute's value. The product provides a sample settenant.xml file in the following location:
    $NX_ROOT/samples/multi_tenancy
    You can modify the sample settenant.xml file, or create a file and copy it to the $NX_ROOT/site/cfg directory. In addition, settenant.xsd must be in the same directory as settenant.xml, or you will receive an error. When you install the product, settenant.xsd is located in $NX_ROOT/site/cfg, so you do not have to copy this file.
  2. Run pdm_settenant -f [configuration file] -r
    The pdm_settenant utility reads its configuration file and processes each rule it defines in sequence.
    We recommend that you use this utility first to populate the tenant attribute in the cnt (contact) object, and then use the cnt object as a source for populating tenant into other objects.
    After the cnt object is properly tenanted, it can be used as a base for setting tenant in other tables by completing the following steps:
    1. Specify a TenantRule with type="SREL" in the configuration file for an attribute referencing the cnt object to set tenant in other tables.
    2. (Optional) Specify a TenantRule with type="Name" < tenantname > to set tenant explicitly in some of the tables.
  3. Run pdm_settenant with a new configuration file.
  4. Rerun pdm_settenant as required.
    After you have populated the tenant column in an object, you can use SRELs to that object as the basis of an SREL TenantRule for setting tenant in other objects.
Example: SREL Type Syntax
SREL type syntaxt checks for cnt objects that do not have a tenant value specified and uses the tenant value from the linked organization object:
<Object name="cnt"> <TenantRule type="SREL">organization</TenantRule> <Where>tenant is null</Where> </Object>
Example: Name Type Syntax
Name type syntax checks for org objects that do not have a tenant value specified and sets their tenant field to the name of an actual Tenant object:
<Object name="org"> <TenantRule type="Name">Tenant A</TenantRule> <Where>tenant is null</Where> </Object>
Tenant Hierarchies
A
tenant hierarchy
is a structured tenant group that is system-created or modified when you assign a
parent tenant
to a tenant. The tenant becomes a
subtenant
of the parent and higher tenants (if any) in that hierarchy.
The service provider can create multiple unrelated hierarchies, or none. Even in a system with tenant hierarchies, you can define standalone tenants.
A subtenant typically represents a subdivision within its
supertenants
. A subtenant can have its own business rules and data, and supertenant data is "pushed" to the subtenant automatically on a read-only basis.
CA SDM supports a tenant hierarchy of unlimited depth. However, the
service provider
can specify a limit on the total number of tenants and the depth of tenant hierarchies (default is four levels). The service provider also determines whether individual tenants can have subtenants.
The service provider can participate in tenant hierarchies, but this is not required. The service provider cannot have a parent tenant.
Create a Subtenant
Subtenancy allows you to build and modify tenant hierarchies for organizational and data-sharing purposes. To place a tenant into a tenant hierarchy, you assign it a parent tenant.
Follow these steps:
  1. On the Administration tab, select Security and Role Management, Tenants.
    The Security and Role Management, Tenants option is available only when multi-tenancy is enabled.
  2. Click an existing tenant to Edit, or click Create New.
    Enter any required data or changes.
  3. Select a Parent Tenant.
    The Parent Tenant drop-down only displays tenants that are allowed to have subtenants.
  4. Click Save.
    The tenant is a subtenant of the parent tenant.
    When a tenant is a subtenant, it belongs to the Subtenant group of the parent tenant, as do the subtenants (if any) of that subtenant, and so on. The parent tenant joins the Supertenant group of the subtenant, as do the supertenants (if any) of that supertenant, and so on. Each joins the Related Tenants group of the other.
System-Maintained Tenant Groups
CA SDM generates and maintains three tenant groups automatically for each tenant in a tenant hierarchy (
tenant
is the tenant name):
  • tenant
    _subtenants (tenant, its child tenants, and their lower subtenants)
  • tenant
    _supertenants (tenant, its parent tenant and its higher supertenants)
  • tenant
    _relatedtenants (entire single hierarchy)
System-maintained tenant groups can be used like user-defined tenant groups. However, only their names and descriptions can be modified.
Tenant Data Assignments
CA SDM displays the tenant in the same format in both the View and Edit versions of a detail page for an existing object, because the tenant for an existing object cannot be changed from the web interface.
When you edit a tenanted object, drop-down lists on the edit page are automatically restricted to values that are public, owned by the same tenant as the base object or any tenants above it in the tenant hierarchy, or owned by the service provider (if the drop-down list applies to a SERVICE_PROVIDER_ELIGIBLE attribute).
There are no changes on the detail page for lookup fields associated with a tenanted object. If a user with access to multiple tenants clicks a lookup link to a tenanted table, the web engine automatically restricts the lookup to values appropriate for the attribute, and displays a banner message on the pop-up search or list page.
Tenant restrictions are not displayed in the search filter, and they cannot be changed by the user.
Tenant becomes a selector (either a lookup or a drop-down list) when you ask to create a tenant-required object.
If the tenant field is empty, you can specify a tenant value directly by filling in the field, or indirectly by specifying a value for a tenant-implying attribute (such as Affected End User). The interface displays the following suffixes:
  • (T) 
    Indicates an attribute that is tenant-implying; that is a lookup to a tenant-required table.
  • (TO)
    Indicates an attribute that is optionally tenant implying that is, a lookup to a tenant-optional table.
web.cfg properties control the text of these indicators.
Except for the tenant attribute itself, tenant-implying attributes are always shown as lookups, even if created with a dtlDropdown macro.
CA SDM automatically sets the tenant when you look up or autofill a tenanted value into any tenant-implying field (except that filling a SERVICE_PROVIDER_ELIGIBLE field with a reference to a service provider object does not set the tenant). After the tenant is set, lookups for tenant-implying fields are restricted in the same way as existing tenanted objects.
Until you save the object, the tenant field remains editable, and you can change the tenant by directly updating it. When you change the tenant, CA SDM automatically clears any tenant-implying fields containing references to objects belonging to the previous tenant.
CA SDM typically initializes the Tenant selector to empty. You can change this behavior in several ways:
  • Open the Create New page from a page such as the Quick Profile, which pre-populates a tenant-implying field
  • Set the Retain Tenant user preference
    This is a new user preference that initializes the tenant for new objects to the same tenant as the last detail page viewed or updated, or in the last list page search filter restriction.
  • Open the page with a URL that explicitly specifies a tenant
    This is not provided in any predefined URL, but is available to allow sites to create menu items or buttons that specify a tenant.
 If you create configuration items from another CA Technologies product (such as CA APM) or the command-line interface, then the object is Public.
 
Create a Tenanted Object
The service provider can add tenant-specific data to objects such as issues, requests, change orders, and so on. You can add a tenant to a ticket (such as an incident) that is created from a Scoreboard tab.
Follow these steps:
  1. Click File, New Incident.
  2. Complete any of the following steps:
    1. Select the tenant from the Tenant drop-down.
    2. Click Affected End User (or any other tenant-implying field).
      The Contact Search page appears. Search for a user; you can filter the search by tenant.
    3. Enter a name into the Affected End User field.
      The tenant data completes automatically.
  3. Continue to create the incident.
Activity Notifications
Activity Notifications control both the contents of notifications and which contacts receive notifications for various events in the history of a ticket.
In a multi-tenancy environment, the notification rule is a tenant-optional object. Public notification rules apply to all tickets; tenanted rules apply only to tickets with the same tenant as the rule, or to tenants in its subtenant hierarchy. The tenanting restriction is applied in addition to any condition specified with the rule itself.
Default Notification Rules are stored as public objects. If multi-tenancy is installed, you must create a copy of the Notification Rule for each of the tenants, otherwise the Update Contacts option is restricted.
Repositories
The repository (doc_rep) object is tenant-optional. Tenants can define their own repositories, and it is possible to define public repositories for objects such as attachments to public knowledge documents. Each tenant can have its own default repository, and you can specify a default public repository.
All attachments are either public or associated with a single tenant. If a tenant does not have its own default repository, the public repository is displayed as the default for its tenanted objects.