Utilities Used for Multi-Tenancy

This article contains the following topics:
casm173
This article contains the following topics:
This section describes utilities that are used to manage a multi-tenancy environment.
Note:
Required parameters are enclosed within "{ }", while optional parameters are in "[ ]".
pdm_buildtenant
-- Creating Tenants from Another Object
The
pdm_buildtenant
utility is used to create tenants from another 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 use pdm_buildtenant to map the data in the previously-used object to the new tenant object.
Before you run pdm_buildtenant, you
must
configure the service provider.
In this section, the object used to hold tenant-like information is named 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.
The pdm_buildtenant utility builds the tenant objects from pre-tenant objects. This application creates a tenant for each pre-tenant object, and sets the tenant attribute in the pre-tenant object to reference the new tenant. This utility has the following syntax:
pdm_buildtenant [-h] | [-f [configuration_file]
  • -f configuration_file
    (Optional) Specifies the location of a configuration file specifying the rules for creating tenants from the pre-tenant object. If this argument is not included, pdm_buildtenant uses the configuration file from the $NX_ROOT/site/cfg directory. This file assumes the pre-tenant object is org; if this is not the case, you
    must
    edit the configuration file before using pdm_buildtenant.
    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 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.
  • -h
    Displays usage information for pdm_buildtenant.
The following is the format of the configuration file:
<?xml version="1.0" encoding="utf-8" ?> <BuildTenant> <Object from="MajicObjectName"> <Attribute from="sourceAttribute1" to="tenantAttribute1" /> <Attribute from="sourceAttribute2" to="tenantAttribute2" /> </Object> </BuildTenant>
The
from
attribute of the Object tag identifies the pre-tenant object. Each Attribute tag identifies an attribute to be copied from the pre-tenant object to an attribute of the new tenant.
For UNIX implementations of multi-tenancy, you
must
run pdm_task to export LIBPATH before executing the pdm_settenant and pdm_buildtenant utilities. If you do not run pdm_task before executing these utilities, you receive system errors. Use ../pdm_task to run the command.
pdm_clean_attachments -- Delete Redundent Attachments After Importing Tenant Data
After importing tenant data, you should delete redundant attachments. This utility has the following syntax:
pdm_perl pdm_clean_attachments.pl [-h] | [-n repository_name] | [-S|-K]
  • -h
    Specifies to display command line help.
  • -n
    repository_name
    Specifies the name of the repository to process. If not specified, all repositories are processed.
  • -S
    Specifies that only CA SDM repositories are processed.
  • -K
    Specifies that only Knowledge Management and Embedded Images repositories are processed.
Running the pdm_clean_attachments.pl command without any arguments processes all repositories.
On UNIX, the LIBPATH must be set before running several CA SDM utilities. Use
pdm_task
to set the LIBPATH before running a utility. For example, input "pdm_task pdm_clean_attachments ...".
pdm_settenant -- Assigning Tenants to Objects
After you define tenants, you must use the
pdm_settenant
utility to set the tenant column in other objects. This utility has the following syntax:
pdm_settentant [-h] | {-f [configuration_file] | -r} [-d domsrvr]
  • -d domsrvr
    (Optional) Specifies a domsrvr to use. If this argument is not specified, pdm_settenant uses the default domsrvr.
  • -f
    configuration_file
    (Optional) Specifies the location of a configuration file specifying the data that will be updated and the rules for updating the file. If this argument is not specified, pdm_settenant uses the configuration file from the $NX_ROOT/site/cfg directory (after the configuration file is copied to the $NX_ROOT/site/cfg folder).
    Note:
    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.
The following sample XML code describes the format of this file:
<?xml version="1.0" encoding="utf-8" ?> <SetTenant> <Object name="MajicObjectName"> <TenantRule type="SREL">MajicColumName</TenantRule> <Where>tenant is null</Where> </Object> <Object name="MajicObjectName"> <TenantRule type="Name">TenantName</TenantRule> <Where>tenant is null</Where> </Object> </SetTenant>
Each Object tag specifies a CA SDM object to be tenanted. The TenantRule tag specifies how pdm_settenant should determine the tenant, and the Where tag selects the objects to be tenanted. There are two types of TenantRule tags:
  • type="Name"
    Specifies an explicit tenant by name.
  • type="SREL"
    Specifies an SREL attribute in the object. Pdm_settenant copies the tenant of the object referenced by the SREL.
  • -h
    Displays usage information for pdm_settenant.
  • -r
    Outputs a report displaying the total number of rows in each tenant-required table, and how many have a null tenant column.
If both the -f and -r arguments are specified, pdm_settenant outputs a report after completing its update. If you only specify the -r argument, pdm_settenant outputs a report, but does not update any data.
Running pdm_settenant without any arguments displays usage information. To run pdm_settenant using the default configuration file, specify the -f option without the configuration_file argument. The pdm_settenant utility reads its configuration file and processes each rule it defines in sequence. It writes output to the pdm_settenant.log file in the $NX_ROOT/log directory.
You can run pdm_settenant as many times as needed. The first pass may take a significant time (possibly several hours at a large site). Subsequent passes run faster, as they only need to process rows that have not been updated. This prepares the database prior to installing the multi-tenancy option.
On UNIX implementations of multi-tenancy, you must run pdm_task to export LIBPATH before executing the pdm_settenant and pdm_buildtenant utilities. If you do not run pdm_task before executing these utilities, you will receive system errors. Use ../pdm_task to run the command.
Assign Tenants to Objects Considerations
After you define tenants, you can use the pdm_settenant (assign tenants to objects) utility to set the tenant column in other objects. When you change the tenant for an object, you must consider whether to change the tenancy on related tenanted objects in order to maintain data integrity. Failure to keep these objects synchronized can cause data to appear missing from CIs, relationships, MDRs, versioning, and so on. The following CA CMDB objects are tenanted:
  • nr -- CI definitions
  • nr_com -- Log entries associated with a CI
  • bmhier -- Relationships associated with CIs
  • mdr_idmap -- MDR provider definitions
  • ci_mdr_idmap -- CI/MDR federated mappings
For each CI, do the following to synchronize data when you use pdm_settenant to change tenancy:
  • Specify nr for the CI object name.
  • Change the log entries associated with the CI in nr_com so that you can view the log entries for the new tenant.
Example: XML to Change the Tenant and Log
The following XML changes the tenant for a CI named CITest to T2 and also changes the corresponding log entries in nr_com:
<Object name="nr"> <TenantRule type="Name">T2</TenantRule> <Where>name = 'CITest'</Where> </Object> <Object name="nr_com"> <TenantRule type="Name">T2</TenantRule> <Where>asset_id.name = 'CITest'</Where> </Object>
pdm_tenant_delete -- Deleting Tenant Data from a Database
The
pdm_tenant_delete
utility removes all data for a specified tenant from the database.
The referential constraints on the ca_ tables must be dropped before running pdm_tenant_delete and restored afterwards.
This utility has the following syntax:
pdm_tenant_delete -h|-t tenant_name [-C|-R] [-Q]
  • -h
    Displays the usage information for pdm_tenant_delete.
  • -t
    tenant_name
    Specifies the name of the tenant of the data to be deleted.
    The tenant must be marked inactive before you can use this utility to delete the data.
  • -C
    Specifies that all contacts for a tenant will be marked inactive. Since contacts can be shared between products, default logic should not mass delete or mass inactivate contacts unless explicitly requested.
    This option is ignored if the -R option is specified.
  • -R
    Specifies that all rows in all tenanted tables marked CA_COMMON in ddict.sch will be deleted, including the tenant object itself.
    These tables are shared between multiple products, so use this option with caution.
  • -Q
    Specifies quick query processing to execute database queries as fast as possible. If this argument is not specified, the utility uses background query processing so that queries run only when the system is otherwise idle. This argument improves running time at the expense of a greater impact on an active system.
    On UNIX, the LIBPATH must be set before running several CA SDM utilities. Use
    pdm_task
    to set the LIBPATH before running a utility. For example, input "pdm_task pdm_clean_attachments ...".
pdm_tenant_extract -- Extracting Tenant Data
The
pdm_tenant_extract
utility extracts all data for a specified tenant from the database. It extracts the data in pdm_userload format so that it can easily be loaded into another database. This utility has the following syntax:
pdm_tenant_extract -h | -c control_file [-d domsrvr] [-g yes|no] [-o output_file] -p phase [[-t tenant_name]...] [-Q] [table1 [table2...]]
  • -h
    Displays the usage information for pdm_tenant_extract.
  • -c
    control_file
    Specifies the location of the control file for this tenant extract. For the Initial phase, the file is created in the specified location (and must not already exist). The file must exist for the Update and Final phases.
  • -d domsrvr
    (Optional) Specifies a domsrvr to use.
  • -g yes|no
    (Optional) Specifies whether or not public data is included in the output file. If this argument is not specified, public data from all tables is included.
  • -o
    output_file
    (Optional) Specifies the location of the output file. If this argument is not specified, output is directed to stdout.
  • -p
    phase
    Specifies the phase of the extract. Use one of the following values:
    I
    -- Initial
    U
    -- Update
    F
    -- Final
  • -t
    tenant_name
    Specifies the name of a tenant to be extracted. This argument is required for the Initial phase and can be repeated for multiple tenants. It is not valid on the Update and Final phase.
  • -Q
    Specifies quick query processing to execute database queries as fast as possible. If this argument is not specified, the utility uses background query processing so that queries run only when the system is otherwise idle
  • table1 [table2...]
    (Optional) Specifies the tables to extract. If omitted, all tables are extracted.
The output from the initial phase must be loaded into a database that has never been used for CA SDM or for any other product. Each table loaded from initial phase data is truncated prior to the load, which could cause loss of data if the database is already in use.
To avoid referential problems during the data load, run the appropriate drop constraints script ($NX_ROOT/samples/views/Oracle/OracleDropConstraints.sql or $NX_ROOT/samples/views/SQLServer/SQLDropConstraints.sql ). After the loads complete, re-apply the constraints with the appropriate xxxAddConstraints.sql script found in the same directory.
pdm_userload -- Load Tenant Data
The
pdm_userload
utility is used to load data into a CA SDM database. This utility is available even if multi-tenancy is not installed. Multi-tenancy adds support for one additional argument (-t) that specifies the name of a tenant whose id must be inserted into the tenant column of all rows inserted or updated into a tenanted table. `The specified tenant must already be in the database.
When extracting data, complete the following steps to avoid errors in stdlog:
  1. Before you start loading data, shut down CA SDM and restart the product in DBADMIN mode as follows:
    • Windows
      Run pdm_d_mgr -s DBADMIN
    • UNIX
      Run pdm_init -s DBADMIN
  2. After the data loads, shut down CA SDM using the pdm_halt command.
  3. Restart CA SDM in normal mode.