IBM Business Analytics Proven Practices: Pre-Populating Tenant IDs in IBM Cognos Content Manager

Nature of Document: Tip or Technique; Product(s): IBM Cognos BI version 10.2; Area of Interest: Infrastructure

An application that will pre-populate tenant IDs for use in a multi-tenant IBM Cognos BI environment.

Dan Edmunds, Software Developer, IBM

Dan Edmunds is a software developer on the Cognos Platform team and has been working with IBM Cognos for 4 and a half years. During that time Dan has worked on Content Manager and multi-tenancy.



24 September 2012

Introduction

Purpose

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.

Applicability

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.


Overview

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:

  1. Logging in as a System Administrator.
  2. Creating a temporary dummy folder object in Content Manager.
  3. 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.
  4. Deleting the dummy folder object.
  5. Logging out.

Code Sample

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.


Using The Sample Application

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.

Installation

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.

Setup

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:

ParameterDescriptionExample
urlThe URL of the dispatcher in the IBM Cognos Business Intelligence installation.http://myserver:9300/p2pd/servlet/dispatch
namespaceThe namespace to authenticate against.MyNamespace
usernameThe user name of the System Administrator to run the sample as.jsmith
passwordThe user's password.myPa$$word
tenantsFileThe file listing the tenants to populate Content Manager with.c:/ibmcognos/tenantIdPopulator/tenants.txt
dummyParentThe 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.

Troubleshooting

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.

Url '<url>' is invalid.

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.

Unable to logon.

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.


Download

DescriptionNameSize
Code sampletenantIdPopulator.zip6KB

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Big data and analytics on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Big data and analytics
ArticleID=835296
ArticleTitle=IBM Business Analytics Proven Practices: Pre-Populating Tenant IDs in IBM Cognos Content Manager
publish-date=09242012