Proven Practice

Application Servers – Installing and

Configuring the Cognos Application
Product(s): Cognos 8, Application Servers

Area of Interest: Infrastructure

Application Servers – Installing and Configuring the Cognos Application 2

TABLE OF CONTENT
1 Introduction ...........................................................................................................................................3
1.1 Purpose..............................................................................................................................................3
1.2 Scope.................................................................................................................................................3
1.3 Definitions, Acronyms, and Abbreviations.......................................................................................3
1.4 References.........................................................................................................................................3
1.5 Assumptions......................................................................................................................................3
2 Cognos 8 Installation Wizard ...............................................................................................................4
2.1 Cognos 8 Installation Wizard............................................................................................................4
2.1.1 Launch the Cognos 8 Installation Wizard................................................................................4
2.1.2 Installation Location................................................................................................................4
2.1.3 Component Selection...............................................................................................................6
2.1.4 Finish.......................................................................................................................................7
3 Cognos 8 Updates ..................................................................................................................................7
4 General Environment Setup.................................................................................................................8
4.1 Install Database Client(s) ..................................................................................................................8
4.2 Install Security Provider Files...........................................................................................................8
5 Cognos Configuration .........................................................................................................................10
5.1 Setup the Environment....................................................................................................................10
5.2 Launch Cognos Configuration ........................................................................................................11
5.3 Cognos Configuration Settings .......................................................................................................13
5.3.1 Change URI Values...............................................................................................................13
5.3.2 Delete the Tomcat Service Configuration .............................................................................16
5.3.3 Remaining Cognos Configuration Changes ..........................................................................17
5.3.4 Save Cognos 8 Configuration Changes .................................................................................17
5.4 Build Application Files Wizard ......................................................................................................18
5.4.1 Start the Build Application Files Wizard...............................................................................18
5.4.2 Select the Application Archives to be Built...........................................................................18
5.4.3 Application File Type, Location and Context Root...............................................................19
5.4.4 Build Application Files in Progress.......................................................................................21
6 Cognos 8 Business Intelligence Modeling..........................................................................................22
7 Troubleshooting / Tips ........................................................................................................................23

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 3

1 Introduction

1.1 Purpose
The purpose of this document is to detail the steps necessary to complete the transfer and configuration
phases of a Cognos 8 install to allow for a single server or a distributed implementation in an application
server environment.
The steps in this document represent common tasks that must be completed irrespective of the application
server being used.

1.2 Scope
Cognos 8 installation and general configuration will be covered in this document.

1.3 Definitions, Acronyms, and Abbreviations

Term Definition
Application Server A J2EE compliant Java application container environment. See the
Cognos Support web site for a list of supported products.
JRE Java Runtime Environment
JVM Java Virtual Machine
Tomcat Servlet container that ships with Cognos 8

1.4 References
Ref. ID Author/Paper Location
Cognos 8 Installation and <Cognos 8>/webcontent/documentation
Configuration Guide

1.5 Assumptions
• Single server install: The application server has been installed and configured with a single server
instance into which Cognos 8 will be deployed. The servlet gateway will not be used.
• Distributed install: The application server has been installed and configured with multiple server
instances into which Cognos 8 will be deployed.
• The hostname and port for each application server / JVM instance is known to the installer.
• The installation location has sufficient storage space to handle the install, the associated
application archive files, and temporary working space.
• If a web server is being used in the environment, that it is already installed and working.
• All required database clients are installed and tested.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 4

2 Cognos 8 Installation Wizard

Throughout this document, there will be notes that apply to a single server install and a distributed install.
A single server install represents installing all the Cognos 8 components into a single location and running
within a single Java instance. This is ideal for demonstrations and low impact cases. The Cognos 8 Servlet
Gateway cannot be used in a single server install as it must run in an isolated JVM instance. In order to
access the Cognos 8 portal in a single server environment, a separate web server must be used, or the
Cognos 8 dispatcher can be accessed directly if the application is built with the static webcontent option
enabled.
A distributed install can comprise a variety of configurations. The examples in this document will outline
separating the Cognos 8 components in three distinct installs. The three components are comprised of the
Content Manager, Application Tier Components and the Gateway.
Many of these steps are similar for all Cognos 8 installs, even those that will run under Tomcat.

2.1 Cognos 8 Installation Wizard

2.1.1 Launch the Cognos 8 Installation Wizard

• Navigate to the mount point or Cognos 8 CD and run the Cognos 8 Installation Wizard
o Windows: issetup.exe
o Unix: issetup

• Select the language that you wish to use to perform the install
• Read and accept or decline the license agreement. If you decline, the installation will not continue.

2.1.2 Installation Location

Enter the path into which you wish to install Cognos 8.

NOTE: Do not copy or rename a Cognos 8 installation directory when you are using an
application server. The installation path is stored in a file that is used as part of the
deployment so that the Java components of Cognos 8 can locate the remainder of the
Cognos 8 product. If necessary, perform a fresh install into the proper location.

Example: Windows Default Installation Location

NOTE: When installing into an application server environment, it is recommended that you
install into a path that does not contain spaces (Windows) as this causes issues for some of
the application server scripts. If absolutely necessary to install into a path with spaces, use

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 5

the DOS 8.3 naming convention where necessary to reference the install path. (ie c:\program
files\cognos\c8 would become c:\progra~1\cognos\c8)

Example: Single Server – All Components Installation Location

In a distributed install where each component will run in a distinct JVM, each component must be installed
into a unique install location. There will be a direct one-to-one correlation between the application server
instance and the Cognos 8 installation. The Cognos 8 Installation Wizard must be run multiple times to
transfer the files to multiple locations.

Example: Distributed - Content Manager Installation Location

Example: Distributed - Application Tier Components Installation Location

Example: Distributed - Gateway Installation Location

The installation location does not have to exist prior to executing the Cognos 8 installation. If the path does
not exist, you will be prompted to create it during the install.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 6

2.1.3 Component Selection

Select the component(s) to install. By default, all components will be installed.

Example: Single Server – All Component Selection

Example: Distributed – Content Manager Component Selection

Example: Distributed – Application Tier Component Selection

Example: Distributed – Gateway Component Selection

Other distributed install combinations are possible and may be implemented in your environment.

• Shortcut Folder (Windows only) - For Windows, you may enter/change the shortcut folder name
to be used for Cognos 8 or accept the default value.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 7

• Installation Summary - After all the selections have been made, you will be presented with a
summary page. Be sure to check the space requirements carefully and allow for extra space for the
application files and temporary working space.

• Installation Progress - Installation will now proceed. Depending on the source media and system
speed, this step could take a few minutes to complete. On Windows, anti-virus checking often
slows this process as well due to the number of files being transferred.

2.1.4 Finish
Once the installation is complete, you will be presented with a final page that will indicate success or
failure. You may select to view the logs and readme files at this time.

Any errors during the transfer must be rectified prior to proceeding.

When installing into an application server environment, it is recommended that you do not start Cognos
Configuration at this time as there are additional steps that must be completed prior to proceeding.

Example: Installation is complete

3 Cognos 8 Updates

If you have any updates to Cognos 8 such as hotsite fixes or other patch files, now is the time to apply
them. They must be applied to each instance of Cognos 8 that you have installed. It is critical that these be
installed prior to building the web application files.

Please refer to the documentation supplied with the update to obtain the correct installation procedure.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 8

4 General Environment Setup

4.1 Install Database Client(s)

Ensure that all necessary client software is installed and available to the user account that will run the
application server for access to the database that you will use for Content Manager as well as your report
database(s). The database that will be used as the Content Manager data store must be created and a user id
/ password must be given appropriate rights to the database.

It is recommended that you verify access to the database using an appropriate tool (such as sqlplus) to
ensure the client software is installed and configured correctly.

Keep in mind that this environment must be available to the user running the application server and
Cognos 8 and should therefore be setup in such a way that it is set automatically and will be available if the
server is restarted.

Important: Ensure that any java database client files are in place prior to proceeding so
that they will be properly included in the application archive file that will be built later in
this document. (example: classes12.jar for Oracle Database) See the Cognos 8
documentation for more information on setting up database clients.

4.2 Install Security Provider Files

Cognos Configuration requires that a number of security/encryption provider files be copied into a location
that the JRE that will be used by the application server can access. This directory is location under
<java>\<jre>\lib\ext. Cognos 8 ships the required security provider files under <C8 install
path>bin\jre\1.3.1\lib\ext on all platforms.

Warning: To ensure that the application server environment is not disrupted, only copy the
files that are not already present, or do not overwrite any existing files. You may wish to
copy the original <java>/<jre>/lib/ext directory to a backup location prior to copying the
Cognos 8 files.

Example: Cognos 8 Java Directory on Windows

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 9

For a distributed environment, this step only needs to be performed once per application server/JRE
installation.

Note that each application server product will/may have a different location of the JRE and the screen shot
are provided only as examples. Some application servers do not ship with a JRE and it must be installed
separately.

Example: Oracle Application Server (Windows) JRE location after the security files have been copied.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 10

5 Cognos Configuration

5.1 Setup the Environment

Prior to launching Cognos Configuration or generating new encryption keys, you must set the environment
variable JAVA_HOME to point to the JDK that will be used by the application server.

For most simple installations, it is recommended that the value be set as global system environment
variable (windows) or in a script (Unix). Many application servers set this value in an environment script
and this script can be run to setup your environment. A reminder for Unix users, be sure to set the variables
correctly which may necessitate the “export” command as well. Different platforms and different shell
environments use slightly different syntax to accomplish this task.

Example: Windows Global System Environment Variable

On Unix, the JAVA_HOME variable can be set for the terminal session, in the user profile or whatever
means is appropriate for your environment.

Example: Unix Terminal Window

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 11

5.2 Launch Cognos Configuration

The following steps represent a single server installation.

If you are performing a distributed installation:

• Follow the steps as indicated starting with the Content Manager distributed install. Complete all
related tasks and start Cognos 8 Content Manager and leave it active and running.

• Once the Cognos 8 Content Manager is running, repeat the steps making the appropriate changes
and start the Cognos 8 Application Tier Components.

• Finally, repeat the steps making the appropriate changes and configure the Cognos 8 Gateway
component.

To start Cognos Configuration after setting the JAVA_HOME environment variable, navigate to the <C8
installation>\bin directory and run the batch file cogconfig.bat (Windows) or the script cogconfig.sh (Unix).

Example: Windows cogconfig.bat file

Example: Unix cogconfig.sh script

If the security provider files were not copied to the correct location, you may encounter an error.

Example: Security provider files could not be found (Windows)

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 12

The batch file (Windows) or script file (Unix) will also indicate which JRE was found based on the
JAVA_HOME environment variable. This should be checked to ensure the correct one is being used.

Example: Batch file output on Windows – check J_HOME value

Example: Script output on Unix

If Cognos Configuration was run previously and there are existing encryption keys, then you may
encounter a warning dialogue. This dialogue indicates that an alternative JRE vendor or version was used
previously and the keys are not compatible with the current JRE vendor or version.

Example: Existing Encryption Keys

If the correct JRE is indeed referenced, then you may select the option to automatically regenerate new
encryption keys. This is typical when switching between a Tomcat environment and an application server
environment.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 13

Example: Regenerate Encryption Keys

Ensure that all steps complete successfully during the regeneration process prior to proceeding. If the
automatic regeneration of the encryption keys fails for any reason, it may be necessary to follow the
manual key recreation steps outlined in the Cognos 8 Installation and Configuration Guide, Chapter 8.

5.3 Cognos Configuration Settings

The default values in Cognos Configuration represent the out-of-box Tomcat solution and therefore there
are a number of settings that must be changed to suit your application server environment. Obviously there
are many other options that you may have to alter that will not be covered in this document.

5.3.1 Change URI Values

A Cognos 8 URI contains the following elements:

• For a Content Manager or Dispatcher URI’s

protocol://host_name_or_IP:port/context_root/alias_path

• For a Gateway or Web content URI

protocol://host_name_or_IP:port/virtual_directory/gateway_application

or

protocol://host_name_or_IP:port/context_root/alias_path

Protocol
This element specifies whether standard (http) or secure (https) communication is used when transmitting
or receiving information.

Host Name or IP
The host name is the name of the server as it is identified on the network. You may use an IP address if
name resolution is not possible. You must change the localhost element of a URI to a server name, fully
qualified domain name, or IP address in a distributed installation. In a mixed environment of UNIX and
Windows servers, ensure that host names can be resolved to IP addresses by all servers in the environment.
Also ensure that the application server is configured to listen on the value entered.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 14

Port
This element specifies the port on which the host system has a socket open to listen for requests. The value
entered must match the value in your Web server, Tomcat, or application server configuration.

Context Root
The context root element is used by the Web server, Tomcat, or the application server to route requests to
the appropriate Java application. The context root can only be changed if you are using an application
server. In a distributed Cognos 8 environment, the context root for all application deployments must be the
same, with the exception that the Servlet Gateway application can have a unique value. The context root
must be a single entity, i.e. it may not contain slashes (“/”).

Alias Path
This portion of the URI must not be modified or Cognos 8 components will not function correctly. The
value is defined and used internally by Cognos 8.

Virtual Directory
This element must indicate the virtual directory alias exactly as it is defined in your Web server
configuration. For example, in the default Gateway URI of http://localhost:80/cognos8/cgi-bin/cognos.cgi,
the virtual directory is cognos8/cgi-bin.

Gateway Application
The Gateway URI must include a reference to the gateway application. For example, if you are accessing
Cognos 8 components using a Common Gateway Interface (CGI), then the default gateway application
would be cognos.cgi.

In the Cognos Configuration Explorer window, under environment, set the appropriate values for all URI
entries used in your environment.
Example: Single Server - Cognos Configuration Default Values (Tomcat)

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 15

Example: Distributed Content Manager - Cognos Configuration Default Values (Tomcat)

Example: Distributed Content Application Tier - Cognos Configuration Default Values (Tomcat)

Example: Distributed Gateway - Cognos Configuration Default Values (Tomcat)

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 16

Example: Single Server – shows hostname as “localhost”, “127.0.0.1” & “servername”. Port has been
changed to 9081

5.3.2 Delete the Tomcat Service Configuration

By default, a Cognos 8 service entry will be defined in Cognos Configuration. As this setting is used only
for configuring to run under Tomcat, it should be removed.

To delete the entry, right-click on it and select “delete” as the action.

Example: Delete the Cognos 8 Service

As a safety measure, you will be prompted to confirm the removal of the Cognos 8 service. Should you
wish to return to run under Tomcat, this service can be added back into Cognos Configuration at a later
time.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 17

5.3.3 Remaining Cognos Configuration Changes

• Navigate to the Content Manager Content Store field and enter the appropriate values for your
environment. Please see the Cognos 8 customer documentation for creating other Content Store
types.

• At this time you should make any other changes within Cognos Configuration that are necessary
for proper operation in your environment. Depending on your setup, no other changes may be
required.

5.3.4 Save Cognos 8 Configuration Changes

Once all the configuration changes have been made, you can save the configuration.

During the Save operation, encryption keys will be created using the JRE referenced by the JAVA_HOME
variable. Other actions such as backing up the configuration files will also take place.

Reminder: For an Application Tier distributed install, the Content Manager must be up and running in
order for the Save operation to complete successfully.

Reminder: For a Gateway distributed install, the Content Manager and the Application Tier must be up
and running in order for the Save operation to complete successfully.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 18

5.4 Build Application Files Wizard

Note: Should it be necessary to make any configuration changes in the future, it is not necessary to recreate
the application archive file. Make and save the appropriate changes, then stop and restart the application
server instance for the changes to be recognised.

5.4.1 Start the Build Application Files Wizard

The Cognos Configuration Build Application Files Wizard can be run to create and package all the files
that are necessary to deploy to the application server.

Important: The Application file does not contain any of the configuration information as entered into the
Cognos Configuration UI and therefore the application files does not have to be rebuild or redeployed
should you wish to make configuration changes. It does however contain a reference link to the actual
Cognos 8 installation directory and therefore you should not manually rename or move the Cognos 8
install. Since the Cognos 8 install path is embedded in the application file, the application file should not be
used to deploy into multiple application server installs or the one-to-one relationship will not be
maintained. The exception to this statement is deployment into a WebSphere cluster and the configuration
for that is covered in a separate document.

The Wizard can be initiated by selecting the Build Application Files option located in the Actions menu.

Example: Initiating the Build Application Wizard

5.4.2 Select the Application Archives to be Built

The first step of the wizard allows you select the type of application that you are building. The options may
vary depending on the Cognos 8 components that you have actually installed.

The main application, “Cognos 8” represents either or both the Content Manager and Application Tier
Components.

• If you are going to use the application server as a Web Server and service the Cognos 8 static
content (images, javascripts, etc) from the application server then select the option to include the
static files into the application file. If you are using a separate Web Server or the Servlet Gateway,
then it is not necessary to include this content and the resulting application file will be much
smaller and faster to deploy.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 19

The Servlet Gateway can be selected, built and deployed to your application server to replace the Web
Server and gateway combination.

You may select to build the main Cognos 8 application, the Cognos 8 Servlet Gateway application, or both
applications.

Example: Build Application Wizard Application Selection

5.4.3 Application File Type, Location and Context Root

If you have elected to build the main Cognos 8 application file, you will be presented with a number of
options.

You may select a file type. An application server may require a specific file type for proper deployment and
management in its own environment. The Cognos 8 customer documentation and the application server
vendor documentation should be consulted. In most cases, an Enterprise Application Archive (EAR) file
may be selected. Older application servers may not support EAR files and therefore a Web Archive
(WAR) file is an alternative. Some application servers such as BEA WebLogic also permit an application
to be placed directly into a folder that it will manage. In this case, the third file type, expand files into a
folder, should be selected.

The Location entry represents the path and filename of the application file that will be created by the
wizard.

Only if necessary, you may also change the context root value. Keep in mind that the context root value for
the Cognos 8 application must be consistent across your entire install if you are performing a distributed
install. In addition the value entered here must match the value entered in the URI entries on the main
Cognos Configuration page as well as be identical to the context root value that you enter when deploying
the application file into the application server. Application servers that use the Expand files into a folder
option will use the folder name as a context root value. WAR files will not store the context root value and
it must be manually entered when deploying the application into the application server.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 20

Example: Cognos 8 application file selections

Similar to the Cognos 8 application, the Cognos 8 Servlet Gateway will also allow you to specify the file
type, location and name of the application file as well as the context root. Note that the context root in this
case is not the same as the context root of the Cognos 8 application above.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 21

5.4.4 Build Application Files in Progress

After making the appropriate selections, the Build Application File Wizard will indicate its progress as it
builds the application files.

Example: Building the Cognos 8 application and the servlet gateway application

A number of files must be copied, manipulated and packaged into the application file by the wizard so this
step may take a few moments to complete based on your selections.

Example: Build of Application Files Completed

This concludes the basic portion of the transfer and setup of Cognos 8 for a single server installation.

In a distributed installation, repeat the various tasks as necessary to transfer and setup Cognos 8 in
preparation for deployment into an application server

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 22

6 Cognos 8 Business Intelligence Modeling

In order to be able to create and publish modeling information, Cognos 8 Business Intelligence Modeling
must be installed and configured for your environment. Follow the Cognos 8 Business Intelligence
Modeling installation instructions.

Launch Cognos 8 Business Intelligence Modeling Configuration and make the changes appropriate to your
environment.

Cognos Proprietary Information

Application Servers – Installing and Configuring the Cognos Application 23

7 Troubleshooting / Tips

If you encounter any encryption key issues, you can verify which JRE was actually used by Cognos
Configuration by looking at <cognos8>/configuration/cogconfig.prefs in both Windows and Unix. The
JRE path, vendor and version will be listed in the text file. This file must not be manually edited unless
directed by Cognos support.
Example: cogconfig.prefs text file

Cognos Proprietary Information