Installing Cognos® Business Intelligence components

Install IBM® Cognos® Business Intelligence on the computer where you previously installed IBM® WebSphere® Application Server Network Deployment and the database client. The Cognos® product consists of two components (Cognos® BI Server and Cognos® Transformer); you must install both components as part of this deployment.

Before you begin

The following conditions must be satisfied to ensure that the Cognos® Business Intelligence components installs correctly:
  • The Cognos® Content Store database must have been created on the database server, and that database server must be running. Refer to Creating databases.
  • The current server must reside within the same domain as the HCL Connections servers so you can enable SSO (Single Sign-On) as required for generating reports.
  • The user running the Cognos® installation script must have permissions to use the database client.

About this task

Installing Cognos® Business Intelligence requires two Cognos® packages (BI Server and Transformer) in addition to the scripts provided in the HCL Connections kit.

Note: The installation packages for Cognos® Business Intelligence components are available in the HCL Connections kit as separate downloads.
Table 1. Package names for Cognos® components to be installed for use with HCL Connections.
Operating System Cognos® BI Server package name Cognos® Transformer package name
IBM® AIX® IBM® Cognos® Business Intelligence Server 64-bit 10.1.1 AIX® Multilingual IBM® Cognos® Business Intelligence Transformer 10.1.1 AIX® Multilingual
Linux™ IBM® Cognos® Business Intelligence Server 64-bit 10.1.1 Linux™ x86 Multilingual IBM® Cognos® Business Intelligence Transformer 10.1.1 Linux™ x86 Multilingual
Microsoft™ Windows™ IBM® Cognos® Business Intelligence Server 64-bit 10.1.1 Windows™ Multilingual IBM® Cognos® Business Intelligence Transformer 10.1.1 Windows™ Multilingual
zLinux (System z®) IBM® Cognos® Business Intelligence Server 64-bit 10.1.1 Linux™ on System z® Multilingual (CI5W5ML IBM® Cognos® Business Intelligence Transformer 10.1.1 Linux™ on System z® Multilingual (CI2QHML)

Procedure

  1. Create a shared network folder where Cognos® Transformer can publish metrics data (in the form of PowerCubes) for reports to access.

    The shared network folder is used when you cluster multiple Cognos® servers; you can use any name you want for the folder. Record this location so you can assign it to the cognos.cube.path property when you set up the cognos-setup.properties file in step 6.

    Note: The folder will be delegated to Cognos® only for storing the PowerCube so it must be either a new folder or an existing empty folder.
  2. Prepare the Cognos® BI Server package:
    1. Download the Cognos® BI Server package to a temporary location on the server.
    2. Create a directory to contain the expanded package; for example:
      • AIX® or Linux™: /opt/biserver_10.1.1
      • Windows™: C:\biserver_10.1.1
    3. Expand the package into the new directory.
  3. Prepare the Cognos® Transformer package:
    1. Download the Cognos® Transformer package to a temporary location on the server.
    2. Create a directory to contain the expanded package; for example:
      • AIX® or Linux™: /opt/transformer_10.1.1
      • Windows™: C:\transformer_10.1.1
      Important: Due to potential file name conflicts, the Transformer package cannot share a directory with the BI Server package. Extracting the packages to the same location will overwrite libraries and result in a non-functioning server.
    3. Expand the package into the new directory.
  4. Prepare the Cognos® server setup package:

    CognosConfig.zip or CognosConfig.tar can be found in the /Cognos folder within the Connections product media.

    1. Download the CognosConfig package to a temporary location on the server.
    2. Create a directory to contain the expanded package; for example:
      • AIX® or Linux™: /opt/CognosSetup
      • Windows™: C:\CognosSetup
    3. Expand the package into the new directory.
  5. Set up the JDBC driver:
    1. Locate the type 4 JDBC driver provided by your database server product.
    2. Copy the JDBC driver to the following location: /CognosSetup/BI-Customization/JDBC
    Important: In order to let Cognos® BI connects to SQL server you need to install Microsoft™ JDBC Driver 4.0 for SQL Server. This installs two versions of the JDBC jar: sqljdbc.jar and sqljdbc4.jar When both of these are present in the Lotus_Connections_Install/Cognos/BI-Customization/JDBC, the connection to the SQL server will fail as it seems to default to sqljdbc.jar but sqljdbc4.jar is required. Delete the file sqljdbc.jar in order for the cognos-setup to work.
    Note: If you are working with DB2v10, make sure to use jdbc driver v10.1 FP1 or later. You can find the driver at the DB2® JDBC Driver Versions technote.
  6. Prepare the cognos-setup.properties file by filling in a value for each property.

    The cognos-setup.properties file is located in the CognosSetup directory where you expanded the Cognos® server setup package in step 4. This file provides values that are used during installation; each property setting in the file is accompanied by a description.

    In the file, some database related properties are used to build a connection to Metrics and Cognos® databases. These settings are shared by all supported database types: DB2®, Oracle and SQL Server. So one property might present a different meaning on a different database type. Refer to the table of your preferred database type to fill-in these properties carefully.

    Table 2. DB2-related properties in the cognos-setup,properties file Property descriptions for DB2® also showing names and values.
    Property Name Value Description
    cognos.db.type db2 Indicates the DB2® database type.
    cognos.db.host [DB2_server_hostname]:[Port] Host name of the DB2® server and the port of the database instance that contains the Cognos® database.
    cognos.db.name COGNOS Created by the HCL Connections database installer.
    cognos.db.user LCUSER The dedicated DB2® database user required by the Connections database installer.
    cognos.db.password [password] The password of LCUSER.
    metrics.db.type db2 Indicates the DB2® database type.
    metrics.db.host [DB2_server_hostname]:[Port] Host name of the DB2® server and the port of the database instance that contains Metrics database.
    metrics.db.name METRICS Created by the HCL Connections database installer.
    metrics.db.local.name [Database_alias] The Metrics database alias created in the early step of Installing the DB2® database client for Cognos® Transformer.
    metrics.db.user LCUSER The dedicated DB2® database user required by the Connections database installer.
    metrics.db.password [password] The password of LCUSER.
    Table 3. Oracle-related properties in the cognos-setup,properties file Property descriptions for Oracle also showing names and values
    Property Name Value Description
    cognos.db.type oracle Indicates the Oracle database type.
    cognos.db.host [Oracle_server_hostname]:[Port] Hostname and Port of the Oracle database server. Port is port where the Oracle database server is listening, typically port 1521.
    cognos.db.name [Database_service_name] The SID of the database that contains the Cognos database.
    Note: It must be the SID if the service name and SID are different on this database; otherwise the installation script will fail on DB Connection validation.
    Run the select instance_name from v$instance command on the Oracle database to detect the SID of the database.
    cognos.db.user COGNOS Created by the Connections database installer.
    cognos.db.password [password] The password of database user COGNOS.
    metrics.db.type oracle Indicates the Oracle database type.
    metrics.db.host [Oracle_server_hostname]:[Port] Hostname and Port of the Oracle database server. Port is port where the Oracle database server is listening, typically port 1521.
    metrics.db.name [Database_service_name] The service name of the database that contains the Metrics database.
    Note: It should be the service name if the service name and SID are different on this database; otherwise the installation script will fail due to DB Connection validation.
    metrics.db.local.name [Local_tns_name] The TNS alias created in the early step of Installing the Oracle database client for Cognos® Transformer.
    metrics.db.user METRICSUSER Created by the Connections database installer.
    metrics.db.password [password] The password of database user METRICSUSER.
    Table 4. SQL Server-related properties in the cognos-setup,properties file Property descriptions for SQL Server also showing names and values.
    Property Name Value Description
    cognos.db.type sqlserver Indicates the SQL Server database type.
    cognos.db.host [SQLSERVER_hostname]:[Port] Hostname and Port of the SQL Server machine and the port of the database instance that contains Cognos® database.
    cognos.db.name COGNOS Created by the HCL Connections database installer.
    cognos.db.user COGNOSUSER Created by the Connections database installer.
    cognos.db.password [password] The password of database user COGNOSUSER.
    metrics.db.type sqlserver Indicates the SQL Server database type.
    metrics.db.host [SQLSERVER_hostname]:[Port] Host name of the SqlServer machine and the port of the database instance that contains the Metrics database.
    metrics.db.name METRICS Created by the Connections database installer.
    metrics.db.local.name [Database_instance_name] The name of the database instance that contains the Metrics database.
    Note: If the Metrics database has been created in a SQL Server default instance, set metrics.db.local.name to be empty. If the Metrics database has been created in a SQL Server named instance called, for example, DBSERVER1, set metrics.db.local.name to DBSERVER1
    metrics.db.user METRICSUSER Created by the Connections database installer.
    metrics.db.password [password] The password of database user METRICSUSER.
    Some other settings need to be noted in these files:
    • The shared network folder is represented by the cognos.cube.path property; set this property to the name you used for the shared network folder that you created in step 1.
    • The Cognos® administrator account specified for the cognos.admin.username setting must represent a valid LDAP user – this is not the WebSphere® administrator. You should have already set up a user in the LDAP for this purpose; for information see Creating the Cognos® administrator.
      Note: The Cognos® administrator's username cannot contain a space.
    • Any passwords stored in this file will be removed after the script finishes running; if you need to run the script again you will need to insert the passwords before the next run. If you prefer, you can omit the passwords from the properties file and supply them on the command line when you run the script, as shown in step 10.
  7. (RedHat Linux™ 6 64-bit systems) Run the following command to preload libraries needed for the setup scripts used in the next step:
    export LD_PRELOAD=/usr/lib64/libfreebl3.so
  8. (SuSE 11 zLinux systems) Create a symbolic link to the libXm.so.3 package:

    The openmotif22-libs-32bit-2.2.4-138.18.1 kit includes libXm.so.4, while the Cognos® installer program issetup script links with libXm.so.3 and encounters an error if it is not available. Prevent this error by creating a symbolic link to libXm.so.3 with the following command:

    ln -s /usr/lib/libXm.so.4 /usr/lib/libXm.so.3
  9. (Microsoft™ SQL Server) If you are using Microsoft™ SQL Server as your database management system, you must configure it to support remote connections before running the cognos-setup.bat|sh script, or the database validation will fail. For information on enabling remote connections in SQL Server, see the Microsoft™ site.
  10. Run the cognos-setup.sh|bat script to install the Cognos® BI Server and Transformer components.
    Any of the properties specified in the cognos-setup.properties file can be passed in as parameters when you run this script. In particular, you might want to supply passwords using this method rather than adding them into the properties file because they will be deleted from the file after it runs. For any properties you supply at run time, use the following syntax:
    cognos-setup.sh|bat -property_name1=property_value1 -property_name2=property_value2
    For example, the properties file contains settings for four passwords. You can pass all of them in at run time by including them on the command line as shown:
    cognos-setup.sh -was.local.admin.password=WASadmin_pwd -cognos.admin.password=CognosAdmin_pwd -cognos.db.password=CognosContentStore_pwd -metrics.db.password=Metrics_DB_pwd

    Output from this operation is stored in the /CognosSetup/cognos-setup.log.

    Attention: If you encounter an error when running the cognos-setup.bat|sh script, correct the error and run the script again before proceeding to the next step. For example, if you provided an incorrect password in the cognos-setup.properties file, modify the password and then run the cognos-setup.sh|bat script again. Remember that if you added passwords to the properties file, they were deleted after the previous run, and must be provided again. If you encounter other problems, see Troubleshooting Cognos® Business Intelligence components for possible solutions.
  11. Now run the cognos-configure.sh|bat script to configure the Cognos® server and set up database connections.

    Any of the properties specified in this script can be passed in as parameters when you run this script, using the syntax shown in the previous step.

    Output from this operation is stored in the /CognosSetup/cognos-configure.log.

    Attention: If you encounter an error when running the cognos-configure.sh|bat script, correct the error and run the script again before proceeding to the next step. For example, if you provided an incorrect password in the cognos-setup.properties file, modify the password and then run the cognos-setup.sh|bat script again. Remember that if you added passwords to the properties file, they were deleted after the previous run, and must be provided again. If you encounter other problems, see Troubleshooting Cognos® Business Intelligence components for possible solutions.
  12. (RedHat Linux™ 6 64-bit systems) Set the LD_PRELOAD variable to JVM environment variable list of the Cognos® server.
    The environment variable LD_PRELOAD needs to be set every time after a Linux™ system restart. To enable this, add this variable to JVM environment variable list as follows:
    1. Start server1 of the WebSphere Application Server where you deployed the Cognos BI.
    2. Log into the administrative console of the WebSphere® Application Server.
    3. Navigate to Servers > Server Types > WebSphere application servers.
    4. Click the cognos_server link.
    5. Click JAVA and then Process Management > Process definition > Environment Entries.
    6. Click New to add the following entry:
      LD_PRELOAD = /usr/lib64/libfreebl3.so
  13. Stop the Cognos® server and server1 if they are running. You will start the Cognos® server after federating it to the Deployment Manager in the next task.
    Note: In the future, whenever you want to stop the Cognos® server, you must stop the WebSphere® Application Server hosting it; wait at least one full minute to ensure that all of the Cognos® processes (AIX® or Linux™: cgsServer.sh and CAM_LPSvr processes; Windows™: cgsLauncher.exe and CAM_LPSvr processes) have completely stopped before you attempt to start the server again.

Results

The Cognos® BI Server and Transformer components are installed into the directories that you specified in the cognos-setup.properties file; for example:
  • Cognos® BI Server: cognos.biserver.install.path
    • AIX® or Linux™: /opt/IBM/CognosBI
    • Windows™: C:\IBM\CognosBI
  • Cognos® Transformer: cognos.transformer.install.path
    • AIX® or Linux™: /opt/IBM/CognosTF
    • Windows™: C:\IBM\CognosTF
Note: During the installation, you might see the following message: ERROR: The system cannot find the file specified. You can ignore this message because it will not block installation or cause any issue.
Note: During the installation, you might see the following message in the log file: ERROR: ld.so: object '/usr/lib64/libfreebl3.so' from LD_PRELOAD cannot be preloaded: ignored. You can ignore this message because it will not block installation or cause any issue.
You can verify that the components were installed successfully by reviewing the installation logs at the following locations:
  • Cognos® BI Server installation log: Cognos_BI_install_path/logs/cogserver.log
    • AIX® or Linux™: /opt/IBM/CognosBI/logs/cogserver.log
    • Windows™: C:\IBM\CognosBI\logs\cogserver.log
  • Cognos® Transformer installation log: Cognos_Transformer_install_path/logs/cogserver.log:
    • AIX® or Linux™: /opt/IBM/CognosTF/logs/cogserver.log
    • Windows™: C:\IBM\CognosTF\logs\cogserver.log

The cognos-setup.properties file contains two sign-ons: Cognos® administrator signon and Metrics database signon. These two signon will be set into the Powercube model files on the Cognos® Transformer server during the installation, which will be used for PowerCube generation. If you need to change these two signon after the installation, perform the following steps:

  1. Update the cognos-setup.properties file with the new signon information.
  2. Run transformer-logon-set.bat|sh, which is located in the CognosSetup directory. The script needs the Cognos® BI server URL as a parameter. You need to pass it in at run time by including it on the command line as shown: 
    transformer-logon-set.bat|sh -cognos.server.url=http(s)://<cognos_bi_server_doamin>:<cognos_bi_server_port>/<cognos_bi_server_contextroot>
    Output from this operation is stored in the /CognosSetup/transformer-logon-set.log. If you encounter an error when running the script, correct the error and run the script again.
  3. If you set the flag removePassword= to false instead of accepting the default value of true, then passwords will not be removed and you can just continue to run the next command.