![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
In a multi-tenant setup of IBM Cognos BI version 10.2 it may be desirable to pre-populate the system with tenant IDs rather than waiting for them to be discovered and created by the system itself. This document presents a sample IBM Cognos BI SDK application which will populate the system with tenant IDs read from a file. It will outline how to install and run the application.
For more information about multi-tenancy, refer to chapter titled Multiple Tenant Environments in the the IBM Cognos BI version 10.2 Security and Administration Guide.
The documented information, technique(s) and sample(s) apply to all IBM Cognos BI version 10.2 installations. Although precautions are taken to ensure that the information, technique(s) and sample(s) span newer releases, some of the content may become obsolete and/or no longer applicable.
Tenant IDs are discovered by Content Manager at run time and are saved whenever a new one is encountered. New tenant IDs are generally discovered on logon, add and update. In some cases it may be desirable to pre-populate the tenant IDs. For example, a company may want to pre-assign content to tenants prior to users from that tenant logging into the system. This sample application will pre-populate tenant IDs by:
- Logging in as a System Administrator.
- Creating a temporary dummy folder object in Content Manager.
- Updating the tenantID property of the dummy folder to the values specified by an input file. By updating the tenantID property, the process Content Manager uses to discover the new tenantIDs will be triggered.
- Deleting the dummy folder object.
- Logging out.
The approach the sample application takes to populate Content Manager with a list of tenants is to update the tenantID property on a sample object with the various tenant IDs parsed from a file.
The following is a sample Java snippet of how to use the IBM Cognos BI SDK to update the tenantID property with a hard-coded list of values.
List<String> tenantIds = new ArrayList<String>();
tenantIds.add("myFirstTenantId");
tenantIds.add("mySecondTenantId");
Folder folder = new Folder();
folder.setSearchPath(new StringProp(null, "/content/folder[@name='myTempFolder']"));
ContentManagerService_ServiceLocator locator = new ContentManagerService_ServiceLocator();
ContentManagerService_PortType connection =
locator.getcontentManagerService(new URL("http://localhost:9300/p2pd/servlet/dispatch"));
logon(connection);
UpdateOptions options = new UpdateOptions();
options.setUpdateTenantIDRecursive(true);
for(String tenantId : tenantIds) {
folder.setTenantID(new StringProp(null, tenantId));
connection.update(new BaseClass[] { folder }, options);
}
logoff(connection); |
This snippet assumes there is already a folder named myTempFolder under /content and leaves the logon and logoff operations as stubs.
By iterating over the values of the tenantIds List and updating the tenantID field of the folder with those values, the tenantIDs will be persisted in Content Manager.
This sample comes packaged as ZIP file containing a directory named tenantIdPopulator which in turn contains the sample application and .bat and .sh files to run it. The application is controlled by setting the values in the tenantIdPopulator.properties file. For the purposes of this document, it is assumed that the IBM Cognos BI install directory is c:\ibmcognos.
Download the ZIP file and extract the sample into the IBM Cognos BI install directory. The extracted sample should exist at the same level as the webapps directory.
Now that you've extracted the application you must configure the tenantIdPopulator.properties file and possibly the run script.
When you open the tenantIdPopulator.properties file you will notice that it contains a list of configuration parameters and sample values. All parameters are mandatory except for “dummyParent”. The parameters are as follows:
| Parameter | Description | Example |
|---|---|---|
| url | The URL of the dispatcher in the IBM Cognos Business Intelligence installation. | http://myserver:9300/p2pd/servlet/dispatch |
| namespace | The namespace to authenticate against. | MyNamespace |
| username | The user name of the System Administrator to run the sample as. | jsmith |
| password | The user's password. | myPa$$word |
| tenantsFile | The file listing the tenants to populate Content Manager with. | c:/ibmcognos/tenantIdPopulator/tenants.txt |
| dummyParent | The searchPath to the object to add the dummy folder to. The searchPath must point to an object which is able to contain folder objects and belongs to the public tenant. This parameter is optional and has a default value of “/content” | /content |
If you are on Windows you will be able to use the run.bat without needing to configure anything as run.bat will make use of the IBM Java run-time environment (JRE) that is installed with IBM Cognos BI. However if you are on Unix or Linux, you will need to edit the run.sh file to define either a JRE_HOME or JAVA_HOME environment variable that points to a JRE.
Running the sample application
Once you have set the values in the tenantIdPopulator.properties file, you can run the sample application by running the script packaged with it. Use run.bat for Windows and run.sh for Unix/Linux.
The output of a successful execution looks like the following,
Successfully added dummy folder. Adding tenantID: tenant1 Adding tenantID: tenant2 Sucessfully deleted dummy folder. Verifying tenantIDs successfully added to Content Manager Successfully verified tenantIDs. Exiting. |
When the application runs into an error or exception, it will print out what it was trying to do when the error occurred as well as a stack trace of the exception if there is one.
Configuration file not found: 'tenantIdPopulator.properties'.
The tenantIdPopulator.properties file is missing. Extract the sample file from the archive again.
Unable to load configuration file 'tenantIdPopulator.properties'.
An IOException occurred while trying to load the configuration file. Make sure you do not have it open in a different program. Investigate the stack trace for further information into the cause of the problem.
Missing value for <configurationParameter>
There is no value for the configuration parameter listed in the message. Review the tenantIdPopulator.properties file. You may have missed or removed a value. The parameters are listed in the section titled Using The Sample Application.
File '<fileName>' does not exist.
The path you provided as a value to the tenantsFile configuration parameter did not resolve to an existing file. Review the path and make sure the file exists.
Unable to read file: '< fileName>'.
An IOException occurred while trying to load the tenants file specified by the tenantsFile configuration parameter. Make sure you do not have it open in a different program. Investigate the stack trace for further information into the cause of the problem.
The URL you provided as a value for the url configuration parameter could not be parsed. Review the URL and make sure it's valid. Investigate the stack trace for further information into the cause of the problem.
Unable to connect to Content Manager.
The application was unable to connect to Content Manager. Make sure the URL you provided points to an IBM Cognos BI Dispatcher. You may also review the stack trace to gain insight into the problem.
The application failed to perform a logon. Review the credentials you provided and make sure they are valid. You may also review the stack trace to gain insight into the problem.
Exception occurred while adding the dummy folder.
The application failed to create the temporary dummy folder used during execution. Make sure the specified user is a System Administrator. You may also review the stack trace to gain insight into the problem.
Exception occurred while updating the tenantID.
The application failed while trying to update the tenantID property on the temporary dummy folder. Make sure the specified user is a System Administrator. You may also review the stack trace to gain insight into the problem.
Exception occurred while deleting dummy folder.
The application failed to delete the temporary dummy folder. This is likely a connection issue since the user must be a System Administrator to have gotten this far. You may also review the stack trace to gain insight into the problem.
Exception occurred while getting tenant list from Content Manager.
The application failed to retrieve the tenant list from Content Manager. This is likely a connection issue since the user must be a System Administrator to have gotten this far. You may also review the stack trace to gain insight into the problem.
tenantID '<tenantID>' is not present in Content Manager.
The tenantID listed in the message was not returned when the application queried for the list of tenantIDs.
| Name | Size | Download method |
|---|---|---|
| tenantIdPopulator.zip | 6KB | FTP |
Information about download methods
