Configuring a new IBM Cognos BI service

When you install IBM® Business Monitor, you can optionally install a new IBM Cognos® Business Intelligence service. You can configure the new IBM Cognos BI service in the following ways: create a deployment environment, run the configuration wizard from the administrative console, use the wbmDeployCognosService command, or create an IBM Business Monitor stand-alone profile in the Profile Management Tool. You must also create an IBM Cognos BI database and user name for the content store.

IBM Business Monitor copies database drivers and application files to the IBM Cognos BI installation directories during the creation or augmentation of a IBM Business Monitor deployment manager or stand-alone profile. IBM Business Monitor also creates the IBM Cognos BI enterprise application (EAR file) to have it available for deployment of the IBM Cognos BI service.

Cluster requirements

For cluster members, at least 1 GB of extra disk space is required for IBM Cognos BI because a runtime instance must be created on each cluster member.

It is important to start only one of the cluster members at a time and wait for IBM Cognos BI to initialize fully before starting the next cluster member. IBM Cognos BI requires extra time when it is started for the first time, because the runtime instance must be created and the content store database must be initialized.

Starting another cluster member before the content store is fully initialized can cause corruption to the database. If this corruption occurs, it will be noted in the cogserver.log file for the IBM Cognos BI runtime instance. To recover, drop the content store database, re-create the database, and then restart a single cluster member. The DDL script to create the database is located in the /dbscripts/Cognos directory on the deployment manager.

Database requirements

The IBM Cognos BI service requires a separate database for its content store repository (called, by default, the COGNOSCS database). You can create this database while configuring a stand-alone or deployment manager profile, use the database design tool (dbDesignGenerator), or manually create the database using the scripts provided by IBM Business Monitor.

The IBM Cognos BI service creates tables in the IBM Cognos BI content store database the first time it is started. Because the database user provided for accessing the content store database must have privilege to create tables in the database, it is recommended that you create a new database user for the content store database only.

Systems where the IBM Cognos BI server is running must have the database client installed. The WebSphere® environment must have access to the client and the client must be configured to connect to the MONITOR database. See the "Database considerations" page and the information for your specific database.

Security requirements

When IBM Cognos BI is first deployed, the preconfigured group named Everyone belongs to several built-in groups and roles in the IBM Cognos BI namespace, including the System Administrators role. You must remove the Everyone group from all built-in groups and roles, and replace it with groups, roles, or users authorized to restrict access to IBM Cognos BI software and administration.

See "Configuring IBM Cognos BI security" for more configuration settings.

When IBM Cognos BI and Business Space are not running on the same cluster member, you must add the IBM Cognos BI host name and port number to the list of trusted servers in IBM Cognos BI. Otherwise, you will not be able to view the pages in Business Space. See step 3 in "Configuring IBM Business Monitor and Business Space to use an existing IBM Cognos BI service."

IBM Cognos BI system compatibility

When you create or augment an IBM Business Monitor deployment manager profile, the configuration files are copied and an enterprise archive (EAR) file is generated for IBM Cognos BI. The IBM Cognos BI EAR file is specific for the platform architecture (operating system and bit mode). When IBM Business Monitor deploys the IBM Cognos BI service, it uses the EAR file that was generated on the deployment manager for all nodes in the cell that are running IBM Cognos BI. To successfully run the EAR file, all nodes must be of the same type. If you have nodes that are of a different type from the deployment manager, you must generate an EAR file on one of the nodes. See "Generating an EAR file for IBM Cognos BI on a custom IBM Business Monitor node."

Bit modes

All IBM Cognos BI servers are configured to run in the same bit mode as the deployment manager. For example, if the deployment manager is running on a 32-bit platform, all IBM Cognos BI servers are configured in 32-bit mode.

If you want to change the bit mode, complete the following steps for each IBM Cognos BI server:

In the administrative console, click Servers > Server types > WebSphere application servers > server name. The Configuration panel is displayed.
Under Server Infrastructure, expand Java and Process Management and click Process Definition.
Under Additional Properties, click Environment Entries. Click PATH for each server and update the path settings for the environment variables to point to the correct directory. For 32-bit systems, point to the bin directory. For 64-bit systems, point to the bin64 directory.
Synchronize the node and restart the server.

libfreebl3.so library for Red Hat Enterprise Linux 6.0

Add LD_PRELOAD=/lib64/libfreebl3.so to the Java Virtual Machine (JVM) environment entry for the application server that is hosting IBM Cognos BI. Complete the following steps:

In the administrative console, click Servers > Server types > WebSphere application servers > server name. The Configuration panel is displayed.
Under Server Infrastructure, expand Java and Process Management and click Process Definition.
Under Additional Properties, click Environment Entries.
Add the LD_PRELOAD=/lib64/libfreebl3.so path to the JVM environment variable using a : as a delimiter.

Locating your runtime IBM Cognos BI root directory

Because IBM Cognos BI configuration settings and binaries are for a single runtime instance, IBM Business Monitor might have to create a new copy for each runtime instance during deployment of the service. IBM Business Monitor checks on startup for updates to the base installation of IBM Cognos BI and applies those to the copy made for each runtime instance. Therefore, if service is required for IBM Cognos BI, only the base installation must be updated.

The copy for each runtime instance is placed under the profile running the IBM Cognos BI service. All configuration, runtime binaries, and log files are kept in unique directories for each runtime instance. The following table shows the location of the IBM Cognos BI root directory for the IBM Cognos BI runtime instance:

Table 1. Location of the IBM Cognos BI root directory
Server type	Directory
First stand-alone server	`app_server_root/cognos`
Second stand-alone server	`profile_root/profile_name/cognos/server_name`
Cluster member server	`profile_root/profile_name/cognos/server_name`

Updating the IBM Cognos BI configuration

IBM Business Monitor saves updates to the IBM Cognos BI configuration each time the AdminTask wbmDeployCognosService command is run. For example, if the security setting changes from Federated to Stand-alone LDAP, or the Content Manager database settings change, run the wbmDeployCognosService command to reconfigure IBM Cognos BI, based on the parameters you pass to the command as well as the current WebSphere settings for the database and user registry.

The changes to the runtime instance of the IBM Cognos BI configuration are made during the server startup based on the changes from wbmDeployCognosService. IBM Business Monitor checks for changes to the IBM Cognos BI configuration each time the server is started.

Run the wbmDeployCognosService command for the following types of changes to WebSphere:

User registry changes
Database changes to either IBM Business Monitor or IBM Cognos BI
Hostname, IP address, and HTTP port address changes

Important: Updates made to the IBM Cognos BI configuration using wbmDeployCognosService will be ignored if the IBM Cognos BI Configuration application program has been used to make manual changes to the configuration. Once you have used the IBM Cognos BI Configuration application program, you must continue to use it to make changes.

Run the wbmSetCognosDatabaseUser command for the following types of changes (or edit the Cognos_JDBC_Alias WebSphere authorization alias directly):

IBM Cognos BI Content Store database user name or password

Run the wbmSetCognosAdminUser command for the following types of changes (or edit the Cognos_Admin_Alias WebSphere authorization alias directly)

IBM Cognos BI administrative user name or password

Manually updating the IBM Cognos BI configuration

When the IBM Business Monitor preconfigured configuration settings for IBM Cognos BI are not sufficient for complex configurations, you must manually configure IBM Cognos BI using the IBM Cognos BI Configuration application. Use the IBM Cognos BI Configuration application to set the host and port addresses of systems running Business Space to the valid domains or host settings of the IBM Cognos BI firewall settings.

For each unique configuration, there is a unique start script

cogconfig.bat
cogconfig.sh

The script is located in one of the following directories:

cognos_installation_root/bin for 32-bit servers
cognos_installation_root/bin64 for 64-bit servers

Use the Table 1 table to find the cognos_installation_root directory.

For each unique configuration, there is a unique start script cogconfig.bat or cogconfig.sh located in the cognos_installation_root/bin for 32-bit servers or the cognos_installation_root/bin64 for 64-bit servers. Use the Table 1 table to find the cognos_installation_root directory.

If there is a problem starting the script because Java is not found, run a command similar to the following to set the environment to locate the version of Java used with your WebSphere server:

SET JAVA_HOME=C:\WAS70\java
export JAVA_HOME=/opt/IBM/WebSphere/AppServer/java

Important: Do not run the IBM Cognos BI Configuration application until after the IBM Cognos BI server has been started at least once. The first startup copies the configuration (and the binaries unless the first stand-alone server is starting), and also creates the encryption keys and encrypts the passwords within the configuration.

Tip: After the IBM Cognos BI configuration has been saved using the IBM Cognos BI Configuration application, IBM Business Monitor no longer checks for changes to the IBM Cognos BI configuration. However, IBM Business Monitor continues to update the user names and passwords such that you only need to make changes to these in one place (for example, using the WebSphere administrative console to change the authorization alias). IBM Business Monitor updates the IBM Cognos BI configuration during server startup with the name and password from the Cognos_JDBC_Alias WebSphere security alias. If you are using the WebSphere stand-alone LDAP repository, changes to the LDAP access are updated in the IBM Cognos BI configuration.

If you need to use the IBM Cognos Administration client, it is located at http://host_name:port_number/p2pd/servlet/dispatch/ext.

Manually setting the IBM Cognos BI address that IBM Business Monitor uses

Use the wbmSetCognosDispatcher command to set the address of a remote or an existing IBM Cognos BI service, or to modify the address of a locally installed IBM Cognos BI service. To allow single sign-on for interactions between IBM Cognos BI and IBM Business Monitor, the IBM Cognos BI address should end with /ext (the full IBM Cognos BI external dispatcher address).

After changing the address, restart all IBM Business Monitor servers.