IBM® Cognos® 8 Business Intelligence

PowerPlay ®

INSTALLATION AND CONFIGURATION GUIDE

Product Information
This document applies to IBM® Cognos® 8 Version 8.4 and may also apply to subsequent releases. To check for newer versions of this document,
visit the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html).

Copyright
Copyright © 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC is an IBM Company.
Portions of Cognos ULC software products are protected by one or more of the following U.S. Patents: 6,609,123 B1; 6,611,838 B1; 6,662,188
B1; 6,728,697 B2; 6,741,982 B2; 6,763,520 B1; 6,768,995 B2; 6,782,378 B2; 6,847,973 B2; 6,907,428 B2; 6,853,375 B2; 6,986,135 B2;
6,995,768 B2; 7,062,479 B2; 7,072,822 B2; 7,111,007 B2; 7,130,822 B1; 7,155,398 B2; 7,171,425 B2; 7,185,016 B1; 7,213,199 B2; 7,243,106
B2; 7,257,612 B2; 7,275,211 B2; 7,281,047 B2; 7,293,008 B2; 7,296,040 B2; 7,318,058 B2; 7,325,003 B2; 7,333,995 B2.
Cognos and the Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated) in the United States and/or other countries. IBM
and the IBM logo are trademarks of International Business Machines Corporation in the United States, or other countries or both. Java and
all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product,
or service names may be trademarks or service marks of others.
While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or
technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained
in this document.
This document shows the publication date. The information contained in this document is subject to change without notice. Any improvements
or changes to the information contained in this document will be documented in subsequent editions.
U.S. Government Restricted Rights. The software and accompanying materials are provided with Restricted Rights. Use, duplication, or dis-
closure by the Government is subject to the restrictions in subparagraph (C)(1)(ii) of the Rights in Technical Data and Computer clause at
DFARS 252.227-7013, or subparagraphs (C)(1) and (2) of the Commercial Computer Software - Restricted Rights at 48CFR52.227 as applicable.
The Contractor is Cognos Corporation, 15 Wayside Road, Burlington, MA 01803.
This document contains proprietary information of Cognos. All rights are reserved. No part of this document may be copied, photocopied,
reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior
written consent of Cognos.
Table of Contents

Introduction 11

Part 1: IBM Cognos 8 PowerPlay

Chapter 1: What’s New? 13

New Features 13
Additional Language Support 13
Support for DB2 Universal Driver for Content Store, Notification, and Logging Data-
bases 13
DB2 on z/OS as Content Store, Logging, or Notification Database 14
Support for IPv6 IP Addresses 14
Support for 64-bit Application Servers 14
Hide the Namespace from Users During Login 15
Changed Features in Version 8.4 15
Installing Supplementary Languages Documentation Required for Translated Product
Documentation 15
Default Connection to an IBM DB2 Content Store Replaces Microsoft SQL Server 15
IBM Java Runtime Environment (JRE) Replaces Sun Java Runtime Environment 15
Deprecated Features in Version 8.4 15
Support for DB2 JDBC Type 2 Driver for the Content Store, Notification, and Logging
Databases on Linux, UNIX and Windows (db2java.zip) 16
Removed Features in Version 8.4 16
Text-based User Interface for Installing and Uninstalling on UNIX and Linux 16
Language Support for IBM Cognos 8 User Interface Text and Messages Moved from Sup-
plementary Languages to IBM Cognos 8 Server Installation 16

Chapter 2: Components Used by IBM Cognos 8 PowerPlay 17

Server Components 17
Common Server Components 17
Server Components for IBM Cognos 8 PowerPlay 18
Migration Components 18
Client Component 19
Other Components 20

Part 2: Planning Your Installation

Chapter 3: Distribution Options for IBM Cognos 8 21

Distributing IBM Cognos 8 PowerPlay Server Components 21
All Components on One Computer 22
Gateways on Separate Computers 22
Application Tier Components and Content Managers on Separate Computers 23
Multiple IBM Cognos 8 Products on the Same Computer 25
IBM Cognos 8 PowerPlay with Other IBM Cognos Products 25
IBM Cognos Series 7 Products That Can Be Migrated to IBM Cognos 8 PowerPlay 25
IBM Cognos Products That Interoperate with IBM Cognos 8 PowerPlay 26

Installation and Configuration Guide 3

Table of Contents

IBM Cognos Series 7 Content That Can Be Recreated in IBM Cognos 8 29

Chapter 4: Setting Up the Environment 31

Recommendation - Review the Readme Before You Install 31
Review Supported Environments 31
Verify System Requirements 32
Review the Default Settings for IBM Cognos 8 33
Guidelines for Creating the Content Store 35
Suggested Settings for Creating the Content Store in DB2 on Linux, Windows, and UNIX 35
Suggested Settings for Creating the Content Store in DB2 on z/OS 38
Suggested Settings for Creating the Content Store in Oracle 38
Suggested Settings for Creating the Content Store in Microsoft SQL Server 39
Suggested Settings for Creating the Content Store in Sybase 40
Create Tablespaces for DB2 Content Store on z/OS 41
Configure Web Browsers 42
Configure a User Account or Network Service Account for IBM Cognos 8 44

Part 3: Installation and Configuration

Chapter 5: Upgrading to IBM Cognos 8 PowerPlay 47

Planning the Upgrade 48
Review the Documentation 50
Recommendation - Assess Applications in the Source Environment 51
Recommendation - Perform a Trial Upgrade 52
Create the Test Environment 53
Plan Your Deployment 53
Create an Export Deployment Specification 55
Copy the Deployment Specification to the Test Environment 57
Include Configuration Objects in Import of Entire Content Store 57
Import to the Test Environment 58
Test the Deployed Content 59
Recommendation - Test the Upgraded Content 60
Moving to the Production Environment 60
Upgrading from an Earlier Version of IBM Cognos 8 PowerPlay 62
Upgrade from an Earlier Version of IBM Cognos 8 PowerPlay 62

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer 67

Recommendation - Install Server Components in Interactive Mode 68
Install IBM Cognos 8 PowerPlay 69
Update the Java Environment 73
JDBC Driver Options for Using DB2 Database as a Content Store 73
Set Up Database Connectivity for the Content Store Database 74
Start IBM Cognos Configuration 76
Set Database Connection Properties for the Content Store 76
Specify a Mail Server Account 78
Configure Environment Properties 79
Configure an IBM Cognos Series 7 Namespace in IBM Cognos 8 80
Configure the Web Server 81
Start the IBM Cognos 8 Service 83
Test IBM Cognos 8 PowerPlay Server Components 84

4 PowerPlay®
 Table of Contents

Test IBM Cognos Connection 85

Test the Migration Services 85
Installing and Configuring Migration on IBM Cognos Series 7 Computers 85
Install IBM Cognos Series 7 Migration Components 86
Configure the IBM Cognos Series 7 Migration Service for Migrations from Upfront in
Distributed IBM Cognos Series 7 Installations 87
Start the IBM Cognos Series 7 Migration Service 88
Uninstalling IBM Cognos 8 88
Uninstall IBM Cognos 8 on UNIX or Linux 88
Uninstall IBM Cognos 8 on Windows 89
Uninstall Cognos Content Database 90
Uninstall the Migration Components 91

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed
Installation 93
Recommendation - Install Server Components in Interactive Mode 95
Installing and Configuring Content Manager Computers 95
Install the Content Manager Components 97
Install Cognos Content Database on a Separate Server 100
Update the Java Environment on the Content Manager Computer 100
Set Up Database Connectivity for the Content Store Database 101
Start IBM Cognos Configuration on the Content Manager Computer 102
Set Database Connection Properties for the Content Store 103
Specify a Mail Server Account 106
Configure Environment Properties for Content Manager Computers 107
Configure an IBM Cognos Series 7 Namespace in IBM Cognos 8 109
Start the IBM Cognos 8 Service on the Content Manager Computer 110
Test Content Manager 111
Installing and Configuring Application Tier Components on the PowerPlay Server 111
Install Application Tier Components on the PowerPlay Server 112
Update the Java Environment on the PowerPlay Server 115
Start IBM Cognos Configuration on the PowerPlay Server 115
Configure Environment Properties on PowerPlay Servers 116
Start IBM Cognos 8 Service on the PowerPlay Servers 117
Test IBM Cognos 8 Migration Service 117
Installing and Configuring the Gateway Component 117
Install the Gateway Component 118
Configure the Web Server 121
Update the Java Environment on the Gateway Computer 123
Start IBM Cognos Configuration on the Gateway Computer 123
Configure Environment Properties for Gateway Computers 124
Test the Gateway Computer 125
Installing and Configuring Migration on IBM Cognos Series 7 Computers 126
Install IBM Cognos Series 7 Migration Components 126
Configure the IBM Cognos Series 7 Migration Service for Migrations from Upfront in
Distributed IBM Cognos Series 7 Installations 128
Start the IBM Cognos Series 7 Migration Service 129
Uninstalling IBM Cognos 8 129
Uninstall IBM Cognos 8 on UNIX or Linux 129

Installation and Configuration Guide 5

Table of Contents

Uninstall IBM Cognos 8 on Windows 130

Uninstall Cognos Content Database 131
Uninstall the Migration Components 132

Chapter 8: Installing and Configuring Client and Modeling Components 133

Installing and Configuring IBM Cognos 8 PowerPlay Client 133
Install IBM Cognos 8 PowerPlay Client 133
Configure IBM Cognos 8 PowerPlay Client 135
Test the Installation 136
Uninstall IBM Cognos 8 PowerPlay Client 136

Chapter 9: Install and Configure Optional Components 137

PowerPlay Samples 137
IBM Cognos 8 PowerPlay Samples 137
Install the IBM Cognos 8 Samples 138
Setting Up the IBM Cognos 8 PowerPlay Samples 139
Install Translated Product Documentation 145
Install and Configure Additional Language Fonts 146
Configure Support for Japanese Yen and Korean Won Characters 147

Part 4: Customizing IBM Cognos 8 PowerPlay in Your Environment

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider 149
Disable Anonymous Access 150
Restrict User Access to the Cognos Namespace 151
Configuring IBM Cognos 8 Components to Use Active Directory Server 151
Configure an Active Directory Namespace 152
Make Custom User Properties for Active Directory Available to IBM Cognos 8 Compon-
ents 153
Enabling Secure Communication to the Active Directory Server 154
Include or Exclude Domains Using Advanced Properties 154
Enabling Single Signon Between Active Directory Server and IBM Cognos 8 Components 155
Configuring IBM Cognos 8 to Use IBM Cognos Series 7 Namespace 157
Configure an IBM Cognos Series 7 Namespace 157
Enabling Secure Communication to the Directory Server Used by the IBM Cognos Series 7
Namespace 158
Enabling Single Signon Between IBM Cognos Series 7 and IBM Cognos 8 158
IBM Cognos Series 7 Namespaces and the IBM Cognos Series 7 Trusted Signon Plug-in 159
Configuring IBM Cognos 8 to Use a Custom Authentication Provider 161
Configure a Custom Authentication Namespace 161
Hide the Namespace from Users During Login 162
Configuring IBM Cognos 8 Components to Use LDAP 163
Configure an LDAP Namespace 164
Configure an LDAP Namespace for Active Directory Server 165
Configure an LDAP Namespace for IBM Directory Server 168
Configure an LDAP Namespace for Novell Directory Server 170
Configure an LDAP Namespace for Sun Java System Directory Server 172
Make Custom User Properties for LDAP Available to IBM Cognos 8 Components 174
Enable Secure Communication to the LDAP Server 175
Enabling Single Signon Between LDAP and IBM Cognos 8 Components 176

6 PowerPlay®
 Table of Contents

Replace Operation 177

Configuring IBM Cognos 8 Components to Use eTrust SiteMinder 177
Configure a Netegrity SiteMinder Namespace 179
Enabling Secure Communication to the eTrust SiteMinder User Directory 180
Enable Single Signon Between eTrust SiteMinder and IBM Cognos 8 180
Protecting the IBM Cognos Web Alias 180
Hide the Namespace from Users During Login 181
Configuring IBM Cognos 8 Components to Use an NTLM Namespace 181
Configure an NTLM Namespace 181
Enable Single Signon Between NTLM and IBM Cognos 8 Components 182
Configuring IBM Cognos 8 to Use SAP 182
Configure an SAP Namespace 184
Enable Single Signon Between SAP and IBM Cognos 8 185
Test the Namespaces 185
Delete an Authentication Provider 185

Chapter 11: Configuration Options 187

Changing Default Configuration Settings 187
Change Default User and Password for Cognos Content Database 188
Change the Notification Database 190
Change a URI 192
Configure Cryptographic Settings 194
Configure IBM Cognos 8 Components to Use IBM Cognos Application Firewall 196
Configure Temporary File Properties 198
Configure the Gateway to Use a Namespace 199
Enable and Disable Services 199
Specify Resources for the IBM Cognos 8 Service 200
Configuring Fonts 201
Considerations to Support Simplified Chinese 203
Update the Registry Entries for Windows Font Links 203
Change the Default Font for PDF Reports 204
Configure Embedded Fonts for PDF Reports 204
Saved Report Output 205
Change Configuration Settings for the IBM Cognos Series 7 Migration Service 207
Assign a User Account to the PowerPlay and Migration Services for Migration 207
Set a User Login Account for the IBM Cognos 8 Service on Multiple PowerPlay Computers 208
Create a New Content Store Using Cognos Content Database 208
Configuring the SSL Protocol 209
Configure SSL for IBM Cognos 8 210
Set Up Shared Trust Between IBM Cognos Servers and Other Servers 212
Select and Rank Cipher Suites for SSL 213
Enable SSL on the Web Server 214
Configuring Log Messages 215
Guidelines for Creating a Logging Database 216
Create Tablespaces for DB2 Logging Database on z/OS 217
Set Up the Database Connectivity for the Logging Database 218
Log Message Destinations 220
Specify the Log Messages Destination 221
Changing Global Settings 225

Installation and Configuration Guide 7

Table of Contents

Customize Language Support to the User Interface 226

Customizing Currency Support 226
Customize Content Locale Support 227
Map Content Locales 228
Map Product Locales 230
Customize the Server Time Zone 231
Change Encoding for Email Messages 231
Customize Cookie Settings 233
Configure the Router to Test Dispatcher Availability 234
Changing the Gateway 234
Configure the Gateway for IBM Cognos Apache Web Server Module 234
Configuring the Servlet Gateway 238
Change the IP Address Version 239
Update File Location Properties on Windows Vista 240

Chapter 12: Configuring Portal Services 243

Specify the Location of the Applications.xml File 243
Configuring Security for Portal Services 244
Disable Anonymous Access to IBM Cognos 8 Components 244
Enable Single Signon Using Shared Secret 245
Enable Single Signon for SAP EP with the SAP Logon Ticket 250
Enable Single Signon for SAP EP with User Mapping 251
Enable Secure Communication Between SAP EP and IBM Cognos 8 Components 252
Enable Single Signon for WebSphere Portal Using the Application Server 252
Enable Single Signon for BEA ALUI Portal Using Basic Authentication 253
Enable Single Signon for BEA ALUI Portal Using SiteMinder 253

Chapter 13: Configuring IBM Cognos 8 for an Application Server 255

Create a Separate JVM Instance 256
Check the Setup of IBM Cognos Components 256
Back Up Existing IBM Cognos Information 257
Set Environment Variables 259
Update the Java Environment 260
Configure IBM Cognos Components to Run Within the Application Server 260
Identifying the JDK for WebLogic 9 on AIX 262
Change the Application Server Startup Script 262
Change the IBM Cognos Dispatcher Properties File for Oracle Application Server 264
Configure Application Server Properties and Deploy IBM Cognos Components 265
Enable SSL 272
Configuring the Web Server 272
Unregister Dispatchers 273
Import Content Store Data 273

Chapter 14: Advanced Configuration Options 275

Changing the Version of Java Runtime Environment Used by IBM Cognos 8 Components 275
Back Up Existing IBM Cognos Information 275
Update the Java Environment 277
Import Content Store Data 278
Configuring IBM Cognos 8 Components to Use Another Certificate Authority 278
Generate Keys and Certificate Signing Requests 278

8 PowerPlay®
 Table of Contents

Configure IBM Cognos 8 Components to Run Within Another Certificate Authority 282

Chapter 15: Setting Up an Unattended Installation and Configuration 283

Set Up an Unattended Installation 283
Set Up an Unattended Configuration 286
Set Up an Unattended Uninstallation 287

Part 5: Maintenance

Chapter 16: Performance Maintenance 289

System Performance Metrics 289
Enabling Only Services That are Required 289
Tuning a DB2 Content Store 291
Tune Apache Tomcat Settings 292
Increase the Request-handling Capacity for Cognos Content Database 292
Reduce Delivery Time for Reports in a Network 293

Part 6: Appendices

Appendix A: Manually Configuring IBM Cognos 8 295

Manually Configuring IBM Cognos 8 on UNIX and Linux 295
Manually Change Default Configuration Settings on UNIX and Linux Computers 296
Manually Change the Global Settings on UNIX and Linux Computers 299
Starting and Stopping IBM Cognos 8 in Silent Mode on UNIX and Linux Computers 300
Manually Create an IBM Cognos Application File 301

Appendix B: Troubleshooting 305

Log Files 305
Problems Starting IBM Cognos 8 307
CFG-ERR-0106 Error When Starting the IBM Cognos 8 Service in IBM Cognos Configur-
ation 308
Cryptographic Error When Starting IBM Cognos 8 309
Unable to Start the IBM Cognos 8 Service Because the Port is Used by Another Process 309
IBM Cognos 8 Service Does Not Start or Fails After Starting 310
IBM Cognos 8 Server Fails to Start and Gives No Error Message 310
IBM Cognos BI Server Not Available When Starting IBM Cognos 8 311
Cannot Log On to a Namespace When Using IBM Cognos Connection (PRS-CSE-1255
Error) 315
IBM Cognos 8 Services Fail to Restart After a Network Outage 316
Download of Resource Fails 316
DB2 Returns SQL1224N Error When Connecting from AIX 316
Content Manager Error When Starting IBM Cognos 8 316
The Page Cannot Be Found When Starting IBM Cognos 8 in Windows 2003 317
The Page Is Not Shown When Opening a Portal After Installing IBM Cognos 8 317
DPR-ERR-2058 Error Appears in Web Browser When Starting IBM Cognos 8 317
Migration Does Not Work 319
EBA-090034 Error When Starting WebLogic 8 320
DPR-ERR-2022 Error Appears in Web Browser When Starting IBM Cognos 8 320
Unable to Download the cognos.xts File 320
Application Server Startup Script Fails 321

Installation and Configuration Guide 9

Table of Contents

Deploying IBM Cognos 8 to an Oracle Application Server or IBM WebSphere Application

Server Fails 321
Microsoft Excel 2000 Multipage Report Type Does Not Work 322
Unable to Deserialize Context Attribute Error When Deploying the p2pd.war File to
WebLogic 322
Accented or Double-Byte Characters May Not Display Correctly When Installing IBM
Cognos 8 on Linux 323
Problems Configuring IBM Cognos 8 323
Run Database Cleanup Scripts 323
Error Trying to Encrypt Information When Saving Your Configuration 325
Problems Generating Cryptographic Keys in IBM Cognos Configuration 326
CAM-CRP-1315 Error When Saving Configuration 326
Configuration Data is Locked by Another Instance of IBM Cognos Configuration 327
Unable to Exit a Tab Sequence When Using Keyboard-only Navigation in IBM Cognos
Configuration 327
Unable to Save Your Configuration 327
Java Error When Starting IBM Cognos Configuration 328
Cryptographic Error When Starting IBM Cognos Configuration 328
Current Configuration Settings Are Not Applied to Your Computer 328
CM-CFG-029 Error When Trying to Save a Configuration That Specifies a SQL Server
Data Source 329
Users are Prompted for Active Directory Credentials 329
Font on UNIX Not Found When Starting IBM Cognos Configuration 329
Unable to Load DB2 OLAP Library in Framework Manager 330
Group Membership is Missing From Active Directory Namespace 330
Deploying IBM Cognos 8 to an Oracle Application Server or IBM WebSphere Application
Server 331
Errors Displayed Deploying to Oracle 10G Application Server 332
CGI Timeout Error While Connected to IBM Cognos 8 Components Through a Web
Browser 332
Servlet Class Fails to Load in WebLogic 333
Desktop Icons or IBM Cognos Configuration Window Flicker on Windows 334

Glossary 335

Index 339

10 PowerPlay®
Introduction

This document is intended for use with IBM Cognos 8 PowerPlay, a Web-based business intelligence
solution with data exploration features for IBM Cognos Series 7 PowerPlay content.
This guide contains instructions about installing, configuring, and testing IBM Cognos 8 PowerPlay,
changing application servers, and setting up samples.
For information about migration and about the differences between IBM Cognos Series 7 PowerPlay
and IBM Cognos 8 PowerPlay, see the Migration and Administration Guide.

Audience
To use this guide, you should be familiar with
● IBM Cognos Series 7 PowerPlay

● installing software on Windows and UNIX computers

● your information technology and security infrastructure

● database, directory server, and application server administration

Related Documentation
Our documentation includes user guides, getting started guides, new features guides, readmes, and
other materials to meet the needs of our varied audience. The following documents contain related
information and may be referred to in this document.

Note: For online users of this document, a Web page such as The page cannot be found may appear
when clicking individual links in the following table. Documents are made available for your par-
ticular installation and translation configuration. If a link is unavailable, you can access the document
on the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html).

Document Description

IBM Cognos 8 PowerPlay Viewing, exploring, formatting, and distributing PowerPlay reports
Studio User Guide

IBM Cognos 8 PowerPlay Migrating IBM Cognos Series 7 PowerPlay content to IBM Cognos 8
Migration and Administra- PowerPlay, and administering your IBM Cognos 8 PowerPlay envir-
tion Guide onment

IBM Cognos 8 Architec- Understanding the IBM Cognos 8 architecture, developing installation
ture and Deployment strategies, including security considerations, and optimizing perform-
Guide ance

Installation and Configuration Guide 11

Introduction

Document Description

IBM Cognos Configura- Using IBM Cognos Configuration to configure IBM Cognos 8
tion User Guide

IBM Cognos 8 Administra- Managing servers, security, reports, and portal services; and setting
tion and Security Guide up the samples, customizing the user interface and troubleshooting

IBM Cognos Connection Using IBM Cognos Connection to publish, find, manage, organize,
User Guide and view IBM Cognos content, such as scorecards, reports, analyses,
and agents

IBM Cognos Supplement- Installing and configuring supported languages other than English,
ary Languages Installation French, German, or Japanese for the IBM Cognos 8 user interface
and Configuration Guide

Finding Information
Product documentation is available in online help from the Help menu or button in IBM Cognos
products.
To find the most current product documentation, including all localized documentation and
knowledge base materials, access the IBM Cognos Resource Center (http://www.ibm.com/software/
data/support/cognos_crc.html).
You can also read PDF versions of the product readme files and installation guides directly from
IBM Cognos product CDs.

Using Quick Tours

Quick tours are short online tutorials that illustrate key features in IBM Cognos product components.
To view a quick tour, start IBM Cognos Connection and click the Quick Tour link in the lower-
right corner of the Welcome page.

Getting Help
For more information about using this product or for technical assistance, visit the IBM Cognos
Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html). This site provides
information on support, professional services, and education.

Printing Copyright Material

You can print selected pages, a section, or the whole book. You are granted a non-exclusive, non-
transferable license to use, copy, and reproduce the copyright materials, in printed or electronic
format, solely for the purpose of operating, maintaining, and providing internal training on IBM
Cognos software.

12 PowerPlay®
Chapter 1: What’s New?

This section contains a list of new, changed, deprecated, and removed features for this release. It
will help you plan your upgrade and application deployment strategies and the training requirements
for your users.
For information about upgrading, see the IBM Cognos 8 PowerPlay Installation and Configuration
Guide for your product.
To review an up-to-date list of environments supported by IBM Cognos products, such as operating
systems, patches, browsers, Web servers, directory servers, database servers, and application servers,
visit the IBM Cognos Customer Service Center (http://www.ibm.com/software/data/support/cognos_
crc.html).

New Features
Listed below are new features since the last release of IBM Cognos 8 PowerPlay. Links to directly-
related topics are included.

Additional Language Support

In addition to Japanese, German, and French, the installation documentation and the user interface
for the installation program and IBM Cognos Configuration are available in the following languages:
● Chinese (simplified)

● Chinese (traditional)

● Korean

● Italian

● Spanish

● Portuguese (Brazilian)

During the installation you can select the language to use from the first page of the installation
wizard. This determines the language of the user interfaces of the installation wizard and IBM
Cognos Configuration.
However, you must configure IBM Cognos 8 to use the additional languages. For more information,
see "Customize Language Support to the User Interface" (p. 226).

Support for DB2 Universal Driver for Content Store, Notification, and Logging
Databases
DB2 introduced a universal JDBC driver that contains both type 2 and type 4 JDBC driver support.
IBM Cognos 8 can connect to a DB2 content store, notification database, or logging database using
either type of JDBC connectivity, but you must first copy two JAR files to the IBM Cognos 8

Installation and Configuration Guide 13

Chapter 1: What’s New?

installation directory. If you are upgrading, you can continue to use type 2 JDBC connectivity
without changing the connection properties for the DB2 content store.
For more information about connection properties for the content store, see "Set Database Connec-
tion Properties for the Content Store" (p. 76).
The two JAR files that you must copy to your IBM Cognos 8 installation directory are as follows:
● a license file, for example db2jcc_license_cisuz.jar or db2jcc_license_cu.jar

● a driver file, db2jcc.jar

For information about copying these files, see "Set Up Database Connectivity for the Content Store
Database" (p. 74).

DB2 on z/OS as Content Store, Logging, or Notification Database

You can use DB2 on z/OS as your content store, logging, or notification database.
Connection settings to DB2 on z/OS are similar to those for DB2 on Linux, UNIX and Windows.
However, additional advanced settings must be configured.
For information about the configuration settings, see "Suggested Settings for Creating the Content
Store in DB2 on z/OS" (p. 38), "Suggested Settings for Creating a DB2 Notification Database on
z/OS" (p. 190), and "Suggested Settings for Creating the DB2 Logging Database on z/OS" (p. 217).
You must run scripts to create tablespaces for storing Large Objects (LOBs). For more information,
see "Create Tablespaces for DB2 Content Store on z/OS" (p. 41), "Create Tablespaces for DB2
Logging Database on z/OS " (p. 217), and "Create Tablespaces for the DB2 Notification Database
on z/OS" (p. 191).

Support for IPv6 IP Addresses

IBM Cognos 8 now supports two IP address protocols: IPv4 and IPv6. IPv4 uses 32-bit IP addresses
and IPv6 uses 128-bit IP addresses. The default is IPv4.
For IBM Cognos Configuration to accept IPv6 addresses in the local URI properties, you must start
IBM Cognos Configuration with the -ipv6 option. You can specify the option each time you open
IBM Cognos Configuration from the command line.
On Windows, you can set the option permanently by adding the option to the Start menu shortcut.
For more information, see "Change the IP Address Version" (p. 239).

Support for 64-bit Application Servers

IBM Cognos 8 Business Intelligence products are now available with support for 64-bit application
servers.
For information about supported application servers, visit the IBM Cognos Resource Center (http:
//www.ibm.com/software/data/support/cognos_crc.html).
For information about configuration, see the IBM Cognos 8 Installation and Configuration Guide.

14 PowerPlay®
 Chapter 1: What’s New?

Hide the Namespace from Users During Login

You can now hide namespaces from users during login. This lets you have trusted signon namespaces
without showing them on the namespace selection list that is presented when users log in. For more
information, see "Hide the Namespace from Users During Login" (p. 162).

Changed Features in Version 8.4

Listed below are changes to features since the last release. Links to directly-related topics are
included.

Installing Supplementary Languages Documentation Required for Translated

Product Documentation
You must install the Supplementary Languages Documentation to access product documentation
in languages other than English. For more information, see "Install Translated Product Document-
ation" (p. 145).
By default, when you install the IBM Cognos 8 gateway component, the installation documentation,
which includes the Installation and Configuration Guide, the Quick Start Installation and Config-
uration Guide and the Readme, is installed in all supported languages. The product documentation,
such as the Administration and Security Guide, is installed in English.

Default Connection to an IBM DB2 Content Store Replaces Microsoft SQL Server
When you start Cognos Configuration for the first time, the connection to IBM DB2 replaces
Microsoft SQL Server for the default content store.
If you did not install IBM Cognos Content Database, and want to use another database server for
the content store, you must delete the default content store. After you uninstall, if you install into
the same location as a previous release, your configuration is preserved and the existing content
store is used.
For more information, see "Set Database Connection Properties for the Content Store" (p. 76).

IBM Java Runtime Environment (JRE) Replaces Sun Java Runtime Environment
IBM Cognos 8 now contains the IBM version of the JRE as part of Windows installations. This
replaces the Sun JRE for 32-bit Windows platforms.
The installation location remains the same. Any content encrypted with Sun JRE can be decrypted
with the IBM JRE.

Deprecated Features in Version 8.4

A deprecated feature is one that is being replaced by a newer version or a better implementation.
The intention is to discontinue the use of the feature and provide recommendations for adapting
to this change over multiple releases.
Listed below are deprecated features, including links to related topics.

Installation and Configuration Guide 15

Chapter 1: What’s New?

Support for DB2 JDBC Type 2 Driver for the Content Store, Notification, and
Logging Databases on Linux, UNIX and Windows (db2java.zip)
DB2 introduced a universal JDBC driver that contains both type 2 and type 4 JDBC driver support.
This new universal driver replaces the deprecated type 2 driver, db2java.zip.
You can continue to use type 2 connectivity with no configuration changes required. If you choose
to use type 4 connectivity, a configuration change is required.
For more information, see "Set Database Connection Properties for the Content Store" (p. 76).

Removed Features in Version 8.4

Listed below are features that are removed since the last release. Links to directly-related topics are
included.

Text-based User Interface for Installing and Uninstalling on UNIX and Linux
In earlier versions of IBM Cognos 8 BI products, you could run a text-based, or console-mode,
installation or uninstallation program on systems that did not have XWindows. In the current
release, the text-based installation and uninstallation programs are not available. Users who install
on UNIX and Linux without XWindows must run an unattended installation or uninstallation
(p. 283).

Language Support for IBM Cognos 8 User Interface Text and Messages Moved
from Supplementary Languages to IBM Cognos 8 Server Installation
IBM Cognos 8 comes with a set of user interface text and messages in several more languages than
in the previous release. You are no longer required to install supplementary languages from a sep-
arate installation program to show the user interface in one of the supported languages. The required
files are automatically installed when you install the IBM Cognos 8 server.
However, you must use Supplementary Languages Documentation to install the Andale WT fonts
for Japan and Korea. These fonts map the U+005C value as a yen or won character. For more
information, see "Install and Configure Additional Language Fonts" (p. 146).

16 PowerPlay®
Chapter 2: Components Used by IBM Cognos 8
PowerPlay

IBM Cognos 8 PowerPlay is a Web-based business intelligence solution with integrated reporting
and data exploration features.
IBM Cognos 8 PowerPlay integrates easily into your existing infrastructure by using resources that
are in your environment. Some of these existing resources are required, such as a Java Virtual
Machine for UNIX installations. Other resources are optional, such as using an external database
for the content store or a security provider for authentication.
By default, IBM Cognos 8 PowerPlay uses Tomcat as an application server. You can configure IBM
Cognos 8 products to run on supported application servers that you currently use in your environ-
ment.

Server Components
Server components provide the user interfaces for reporting and data exploration, as well as the
server functionality for routing and processing user requests.

Common Server Components

Some server components are provided with all Cognos 8 products. Common server components
include the following tools:

IBM Cognos Connection

IBM Cognos Connection is a Web portal provided with IBM Cognos 8, providing a single access
point to the corporate data available for its products. It provides a single point of entry for querying,
analyzing, organizing, and exploring data, and for creating reports and PowerCubes. Users can run
all their Web-based IBM Cognos 8 applications through IBM Cognos Connection. Other business
intelligence applications, and URLs to other applications, can be integrated with IBM Cognos
Connection.

IBM Cognos Administration

IBM Cognos Administration is a central management interface that contains the administrative
tasks for IBM Cognos 8 PowerPlay. It provides easy access to the overall management of the IBM
Cognos environment and is accessible through IBM Cognos Connection. IBM Cognos Administration
also provides access to cube and report settings for IBM Cognos 8 PowerPlay.

Cognos Viewer
Cognos Viewer is a portlet in which you can view and interact with any type of published IBM
Cognos content. It is accessible through IBM Cognos Connection and any existing enterprise portal.

Installation and Configuration Guide 17

Chapter 2: Components Used by IBM Cognos 8 PowerPlay

IBM Cognos Configuration

IBM Cognos Configuration is a tool that you use to configure IBM Cognos 8, and to start and stop
its services.

Gateway
Web communication in IBM Cognos 8 is typically through gateways, which reside on one or more
Web servers. A gateway is an extension of a Web server program that transfers information from
the Web server to another server.
Gateways are often CGI programs, but may follow other standards, such as Internet Server
Application Program Interface (ISAPI) and Apache Modules (apache_mod).

Content Manager
Content Manager is the IBM Cognos 8 service that manages the storage of customer application
data, including security, configuration data, models, metrics, report specifications, and report output.
Content Manager is needed to publish packages, retrieve or store report specifications, manage
scheduling information, and manage the Cognos namespace.
Content Manager stores information in a content store database.
For IBM Cognos 8 PowerPlay, the Content Manager component includes the IBM Cognos 8
migration service.

Server Components for IBM Cognos 8 PowerPlay

Some server components are specific to IBM Cognos 8 PowerPlay. The server components include
the following tools:

PowerPlay Studio
PowerPlay Studio lets users view, explore, and distribute reports using a Web browser.

IBM Cognos 8 Samples

The IBM Cognos 8 samples illustrate product features and technical and business best practices
using data from a fictitious company, Great Outdoors. You can also use them for experimenting
with and sharing report design techniques, and for troubleshooting.
The IBM Cognos 8 samples include PowerCubes, models, and reports that you can use in Cognos 8
PowerPlay to view, publish, and drill through reports; and do a sample migration from IBM Cognos
Series 7 to IBM Cognos 8.

Migration Components
The IBM Cognos 8 migration components are used to migrate content from IBM Cognos Series 7
to IBM Cognos 8. They are also used to migrate PowerPlay Studio reports to Analysis Studio and
Report Studio.
For more information about the migration components, see the IBM Cognos 8 PowerPlay Migration
and Administration Guide.

18 PowerPlay®
 Chapter 2: Components Used by IBM Cognos 8 PowerPlay

The migration components include the following:

Migration Assistant
Administrators use the Migration Assistant to migrate IBM Cognos Series 7 PowerPlay content
from PowerPlay Enterprise Server, Upfront, and IBM Cognos Connection to IBM Cognos 8
PowerPlay.

Migration Services
Migration services manage the migration operations when PowerPlay content is migrated from
IBM Cognos Series 7 to IBM Cognos 8 PowerPlay. It consists of an IBM Cognos 8 service and an
IBM Cognos Series 7 service, both of which are required for successful migration. The IBM Cognos 8
migration service is part of the IBM Cognos 8 service and communicates with the IBM Cognos 8
server components. It is installed with the Content Manager component. The IBM Cognos Series 7
migration service is a Windows or UNIX service and communicates with the IBM Cognos Series 7
components. It is installed on the IBM Cognos Series 7 computer. After migration to IBM Cognos 8
PowerPlay is complete, IBM Cognos Series 7 migration components can be uninstalled. The IBM
Cognos 8 migration service remains installed, to support report migration from PowerPlay Studio
to Analysis Studio and Report Studio.

Bookmark Conversion Utility

The bookmark conversion utility converts PowerPlay Enterprise Server bookmarks into a format
that can be read by IBM Cognos 8 PowerPlay Studio.

PPR to PPX Conversion Macro

IBM Cognos 8 PowerPlay does not open reports in ppr format. IBM Cognos 8 PowerPlay provides
a macro named ppr2ppx.mac to allow you to convert ppr format reports to ppx format.

Report Upgrade Macro

If you have local .ppx files that access remote cubes, IBM Cognos 8 PowerPlay provides a macro
you can use to change the cube reference in the report to an IBM Cognos 8 package reference. Also,
the macro converts the report encoding to UTF-8.

Migration to Analysis Studio and Report Studio

Analysis Studio and Report Studio are server components that are available in IBM Cognos 8
Business Intelligence. IBM Cognos 8, users can open PowerPlay reports and migrate them to Analysis
Studio or Report Studio by using the Open with Analysis Studio or Open with Report Studio
functionality. This functionality, which the PowerPlay administrator can disable, uses the IBM
Cognos 8 migration service to migrate the reports.

Client Component
Client components provide functionality to users without the requirement of a full server installation
and may depend on the server to perform some operations. IBM Cognos 8 PowerPlay provides the
following client.

Installation and Configuration Guide 19

Chapter 2: Components Used by IBM Cognos 8 PowerPlay

IBM Cognos 8 PowerPlay Client

PowerPlay Client lets users view, explore, format, and distribute reports.

Other Components
In addition to the tools provided with IBM Cognos 8 PowerPlay, other components are required.

Content Store
The content store is a relational database that contains data that IBM Cognos 8 needs to operate,
such as report specifications, published models, and the packages that contain them; connection
information for data sources; information about the external namespace; and the Cognos namespace
itself. The relational database can be Cognos Content Database or another supported database.
Log files are not stored in the content store.
The IBM Cognos 8 service that uses the content store is named Content Manager.

Data Sources
IBM Cognos 8 PowerPlay supports PowerCube data sources. Other IBM Cognos 8 components
support other types of data sources. For more information, see the IBM Cognos 8 Administration
and Security Guide.

20 PowerPlay®
Chapter 3: Distribution Options for IBM Cognos 8

Before implementing IBM Cognos 8, decide how you will install it in your environment. You can
install all IBM Cognos 8 PowerPlay components on one computer, or distribute them across a
network. The best distribution option depends on your reporting requirements, resources, and
preferences. Configuration requirements differ depending on whether you install all components
on one computer or more than one computer.
IBM Cognos 8 PowerPlay is compatible with other IBM Cognos products. If your environment
includes other IBM Cognos products, you must consider how IBM Cognos 8 PowerPlay will fit
into that environment.

Distributing IBM Cognos 8 PowerPlay Server Components

When you install IBM Cognos 8 PowerPlay server components, you specify where to place the
gateways, Application Tier Components, and Content Manager. You can install these components
using any of these options:
● Install all components on one computer.
This option is typically used for a demonstration or in a proof of concept environment.

● Install the gateway on a separate computer.

In this option, the gateway and Web server are on one computer, and the remaining IBM Cognos
components are on other computers. You may choose this option if you have existing Web
servers available to handle IBM Cognos component requests.

● Install Application Tier Components and Content Manager on separate computers.

Choose this option to maximize performance, availability, capacity, or security based on the
processing characteristics of your organization.
If you plan to install IBM Cognos Content Database, you can install it on the same computer
as Content Manager or on another computer. If you install it on the same computer and in the
same location, IBM Cognos Content Database is automatically configured for use as your
content store. If you install it on another computer, ensure that you set the connection properties
for IBM Cognos Content Database on your Content Manager computer.

● Install IBM Cognos 8 PowerPlay server components on the same computer as other IBM
Cognos 8 products.

As you install IBM Cognos 8 server components, you must configure them so they can communicate
with each other.
In addition to installing the Content Manager, Application Tier Components, and gateway compon-
ents, you can choose to install Framework Manager, the metadata modeling application for business
intelligence. You can also choose to install Transformer, the modeling and building tool for creating
PowerCubes for use with IBM Cognos 8. No matter which IBM Cognos installation scenario you

Installation and Configuration Guide 21

Chapter 3: Distribution Options for IBM Cognos 8

follow, you can install all components in separate locations. For more information about installing
Framework Manager or Transformer, see the Installation and Configuration Guide for your mod-
eling product.

All Components on One Computer

You can install all the IBM Cognos 8 components on one computer. Choose this scenario for proof
of concept or demonstration environments where the user load is small.
Because the gateway must be located with the Web server, the single computer must also be running
a Web server. If your Web server is on UNIX or Linux, you must install the Windows-based
PowerPlay Client on a separate computer that runs on Windows.
In a single-computer installation, all server components for IBM Cognos 8 PowerPlay are installed
on one computer. The content store and data sources can be located on one or more separate
computers.

Configuration Requirements
If you install all server components for IBM Cognos 8 reporting on the same computer, you must
then
● configure your Web server to view IBM Cognos content

● specify connection information to the content store

● specify a mail server and email account for notifications (if you intend to email reports)

Gateways on Separate Computers

The gateway manages communications among IBM Cognos 8 components. It can reside on one or
more Web servers.
You can install the gateway and a Web server on one computer, and install the remaining IBM
Cognos 8 server components on other computers. If you have a Web farm, you may want to install
a gateway on each Web server. Using multiple Web servers to manage incoming requests provides
a better level of service.
If you install only the gateway component on the same computer as the Web server, your Web
server manages the core Web services and does not process IBM Cognos 8 user requests. This sep-
aration of processing may be required if you have a firewall between the Web server and your
Application Tier Components computers.
In the following diagram, two Web servers each have a gateway installed. Incoming requests are
passed to either gateway and forwarded to the Application Tier Components computer.

22 PowerPlay®
 Chapter 3: Distribution Options for IBM Cognos 8

Multiple Gateways
Web server Web server Installation
Gateway Gateway

Application Tier Components

Content Manager

Content store Data sources

Configuration Requirements
If you install one or more gateways on separate computers, you must ensure that you can view IBM
Cognos content and that the gateways can communicate with other IBM Cognos components. On
each computer where the gateway is installed you must
● configure cryptographic properties

● configure your Web server to view IBM Cognos content

● configure the Dispatcher URIs

Application Tier Components and Content Managers on Separate Computers

The components in the application tier are used to run report server processes, balance loads, access
data, perform queries, schedule jobs, and render reports. Content Manager stores all report specific-
ations, results, packages, folders, and jobs in the content store.
You can install the Application Tier Components and Content Manager on the same computer, or
on different computers. Installing on different computers can improve performance, availability,
and capacity.
To improve scalability in an environment in which there is typically a large volume of requests to
process, you can install the Application Tier Components on multiple PowerPlay servers dedicated
to processing incoming requests. By installing the Application Tier Components on multiple com-
puters, you distribute and balance loads among the computers. You also have better accessibility
and throughput than on a single computer, as well as failover support.
In an installation with multiple PowerPlay servers, incoming requests are routed to a gateway. The
gateway forwards the request to one of the PowerPlay servers. The PowerPlay server forwards the
request to Content Manager, which queries the content store for metadata to query the PowerCube.
Query results are returned to the PowerPlay server for rendering.

Installation and Configuration Guide 23

Chapter 3: Distribution Options for IBM Cognos 8

Configuration Requirements
If you install one or more Application Tier Components on a separate computer, to ensure that
they can communicate with other IBM Cognos 8 server components you must
● configure cryptographic properties

● specify all Content Manager URIs

● specify the Dispatcher URIs

● specify the Dispatcher URI for external applications

More Than One Content Manager

You can install any number of installations of Content Manager, although only one is active at any
time. The other installations each act as a standby Content Manager. One becomes active only if
the computer on which the active Content Manager is installed fails. For failover support, it is
advisable to install Content Manager on two or more computers.
Content Manager stores data that IBM Cognos 8 needs to operate, such as report specifications,
published models, and the packages that contain them; connection information for data sources;
information about the external namespace and the Cognos namespace itself; and information about
scheduling and bursting reports. The content store is a relational database management system
(RDBMS). There is only one content store for each IBM Cognos installation.
You may choose to install Content Manager separately from the Application Tier Components.
For example, you may want Content Manager in your data tier instead of the application tier.
When an active Content Manager fails, unsaved session data is lost. When the new active Content
Manager takes over, users may be prompted to logon.
In the following diagram, the gateway forwards the request to the default active Content Manager
computer. Because the computer has failed, the request is redirected to the standby Content Manager
computer, which became active when the default active Content Manager computer failed.
Multiple Content
Manager installation
Web server
Gateway
Application Tier Components

Standby Content
Manager

Default active
Content Manager

Content store Data sources

Configuration Requirements
On each computer where you install Content Manager, you must
● configure cryptographic properties

24 PowerPlay®
 Chapter 3: Distribution Options for IBM Cognos 8

● specify connection information to the content store

● specify the Dispatcher URIs

● specify all Content Manager URIs

● specify the Dispatcher URI for external applications

● set up a connection to an email account for notifications (if you want to email reports)

Multiple IBM Cognos 8 Products on the Same Computer

IBM Cognos 8 products are designed to share components, including the gateway, Content Manager,
content store, IBM Cognos Connection, and IBM Cognos Configuration. If you install more than
one IBM Cognos 8 product on the same computer, we strongly recommend that you install them
in the same installation location. The installation program checks to determine whether other IBM
Cognos 8 components exist in the installation location. If a component exists and can be shared,
it is not reinstalled.

Accessing Product Documentation in an Integrated Environment

The documentation for IBM Cognos 8 components is installed with the gateway component. If you
integrate different IBM Cognos 8 products, you can either use the same gateway or use separate
gateways. If you want to use the same gateway, all gateway components must be of the same product
version, and you should install the IBM Cognos 8 gateway component for each product into the
same location on the same computer. This ensures that all of the product documentation is available
to all users. If you want to use separate gateways for each product, you can install the IBM Cognos 8
gateway component for each product on separate computers, but the product documentation on
each gateway will be specific for the IBM Cognos 8 product you installed.
If you want users to access each IBM Cognos 8 product through separate gateways, yet still be able
to access documentation for all components, you can install each product's gateway component
into the same location as your other IBM Cognos 8 gateway components.

IBM Cognos 8 PowerPlay with Other IBM Cognos Products

You can install IBM Cognos 8 PowerPlay in an environment that includes other IBM Cognos
products. The installation wizard for IBM Cognos 8 PowerPlay can recognize compatible directories
and shows a warning when conflicts occur. After IBM Cognos 8 PowerPlay is installed, you can
access objects that are created in another IBM Cognos product in IBM Cognos 8. The requirements
for access depend on how you choose to run the two products.

IBM Cognos Series 7 Products That Can Be Migrated to IBM Cognos 8 PowerPlay
You can completely migrate IBM Cognos Series 7 PowerPlay applications to IBM Cognos 8
PowerPlay. For more information, see the IBM Cognos 8 PowerPlay Migration and Administration
Guide.

Installation and Configuration Guide 25

Chapter 3: Distribution Options for IBM Cognos 8

You can also migrate metadata and applications from other IBM Cognos Series 7 products to IBM
Cognos 8. Content that can be migrated includes Architect models from Windows, Impromptu
client reports and catalogs from Windows, and Impromptu Web reports content.

PowerPlay Enterprise Server

The data analysis and exploration capabilities of IBM Cognos Series 7 PowerPlay are now available
with IBM Cognos 8 PowerPlay. The IBM Cognos 8 service-oriented architecture makes possible
the integration of PowerPlay Web, PowerPlay Enterprise Server Administration, and the PowerPlay
Enterprise Server service.
You use the Migration Assistant to migrate IBM Cognos Series 7 PowerPlay content from
● PowerPlay Enterprise Server

● Upfront

● Cognos Connection (content published from IBM Cognos Series 7 PowerPlay Enterprise Server)

You can also migrate bookmarks and PowerPlay Client reports to Cognos 8 PowerPlay. For details
about what you can migrate from IBM Cognos Series 7 PowerPlay to IBM Cognos 8 PowerPlay,
see the IBM Cognos 8 PowerPlay Migration and Administration Guide.
To migrate content from IBM Cognos Series 7 to IBM Cognos 8 PowerPlay, you must install IBM
Cognos 8 PowerPlay Server and IBM Cognos Series 7 Migration Components.

Impromptu
You can migrate Impromptu catalogs and reports to IBM Cognos 8. You use migrated catalogs as
a metadata source for Framework Manager. After completing the catalog migration process, you
can migrate and deploy Impromptu reports.

Impromptu Web Reports

You can migrate Impromptu Web Reports content, such as schedules and events, to IBM Cognos 8.
You migrate Impromptu Web Reports content using an IBM Cognos Series 7 Deployment Manager
package as the migration source. Before you migrate Impromptu Web Reports you must migrate
the Impromptu catalog metadata used by the reports.
You cannot migrate Impromptu query definition files (.iqd), but you can continue to use existing
.iqd files to build cubes in IBM Cognos 8 Transformer. To do so, you must install the optional
component, Series 7 IQD Bridge, which is available to install with IBM Cognos 8 BI on IBM Cognos
Series 7 supported platforms.
PowerPrompts are not migrated, but you can implement similar functionality using either the built-
in administrator functionality or the Software Development Kit.

Architect
You can migrate Architect models for use as a metadata source for Framework Manager.

IBM Cognos Products That Interoperate with IBM Cognos 8 PowerPlay

Some IBM Cognos products provide functionality that is not available in IBM Cognos 8 PowerPlay.
You can use these products in the same environment as IBM Cognos 8 PowerPlay.

26 PowerPlay®
 Chapter 3: Distribution Options for IBM Cognos 8

IBM Cognos 8 Business Intelligence Server

To use modeling tools, such as Framework Manager and IBM Cognos 8 Transformer, with IBM
Cognos 8 PowerPlay, you must install IBM Cognos 8 Business Intelligence Server. If you also want
to use Report Studio, Analysis Studio, or Query Studio, you need IBM Cognos 8 Business Intelligence
Server.
We recommend that you install both IBM Cognos 8 Business Intelligence Server and IBM Cognos 8
PowerPlay before configuring your installation. If you are installing IBM Cognos 8 PowerPlay in
an existing IBM Cognos 8 environment, backup you IBM Cognos 8 configuration before installing
IBM Cognos 8 PowerPlay.
For a single-computer installation, install components for both products in the same directory, as
follows:
1. Install both IBM Cognos 8 BI Server and IBM Cognos 8 PowerPlay.

2. Configure the installed components.

3. Install IBM Cognos Series 7 Migration Components on the IBM Cognos Series 7 PowerPlay
server.

For a distributed installation, install and configure components as follows:

1. Install and configure all components for IBM Cognos 8 BI Server: Content Manager, application
tier components, and gateway.

2. Install and configure IBM Cognos 8 PowerPlay application tier components.

3. Install the PowerPlay Administration component for IBM Cognos 8 PowerPlay on the same
computers as the IBM Cognos 8 PowerPlay and IBM Cognos 8 application tier components.

4. Install the PowerPlay gateway component on the same Web server where you installed the IBM
Cognos 8 BI gateway component.

5. Install the IBM Cognos 8 PowerPlay Content Manager components on the same computer as
the IBM Cognos 8 Content Manager components.

6. Install IBM Cognos Series 7 Migration Components on the IBM Cognos Series 7 PowerPlay
Enterprise Server computer, and if required the IBM Cognos Series 7 Upfront computer.

For instructions about installing and configuring IBM Cognos 8 BI Server, see the IBM Cognos 8
Business Intelligence Installation and Configuration Guide.

IBM Cognos Planning - Analyst

You can access published plan data in IBM Cognos 8 by using the Generate Framework Manager
Model wizard, which requires IBM Cognos Planning - Analyst 7.3 MR1 or later.
For more information, see the Analyst User Guide.

IBM Cognos Planning - Contributor

You can access unpublished (real-time) Contributor cubes in IBM Cognos 8 by custom installing
the IBM Cognos 8 - Contributor Data Server component that is included with IBM Cognos Planning
- Contributor 7.3 MR1 release or later. You can access published plan data in IBM Cognos 8 by

Installation and Configuration Guide 27

Chapter 3: Distribution Options for IBM Cognos 8

using the Generate Framework Manager Model administration extension in Contributor, which
requires Cognos Planning - Contributor 7.3 MR1 or later.
For more information, see the Contributor Administration Guide.

IBM Cognos Finance

You can access IBM Cognos Finance cubes that are secured against a Series 7 namespace by using
the IBM Cognos Finance Network API Service. You can also export data and metadata from IBM
Cognos Finance for use in Framework Manager.

IBM Cognos Controller

You can access IBM Cognos 8 to create IBM Cognos Controller Standard Reports by using a pre-
defined Framework Manager model that is created when IBM Cognos Controller is installed. You
can also access published Controller data and structures in Framework Manager for custom
reporting and analysis. Both IBM Cognos Controller and IBM Cognos 8 BI must be at the same
version.

Transformer
You can use IBM Cognos PowerCubes and Transformer models that were generated by Trans-
former 7.3 or later directly in IBM Cognos 8. The cubes and models are upwards compatible and
require no migration or upgrade tools. You can run reports and analyses in IBM Cognos 8 against
the IBM Cognos PowerCubes.
If you want to use the integration features of Transformer with IBM Cognos 8, you can upgrade
IBM Cognos Series 7.x Transformer models to IBM Cognos 8 BI Transformer 8.3 or higher. This
allows you to use IBM Cognos 8 data sources (such as published packages), list reports authored
in Query Studio or Report Studio, authenticate using IBM Cognos 8 security, and publish directly
to IBM Cognos Connection.
If the model was secured in IBM Cognos Series 7 you must configure the IBM Cognos Series 7
namespace in IBM Cognos 8 (p. 157) before you load the model. The name ID that you use to con-
figure the namespace in IBM Cognos 8 must match the name used in IBM Cognos Series 7.
For more information about upgrading IBM Cognos Series 7 secured PowerCubes, see the IBM
Cognos 8 Transformer User Guide.
For IBM Cognos Series 7 PowerCubes to be used in IBM Cognos 8, we recommend that you
optimize the cubes for use in IBM Cognos 8 by using the pcoptimizer utility, which is supplied with
IBM Cognos 8. Otherwise, PowerCubes that were created with previous versions of Transformer
may take too long to open in the IBM Cognos 8 Web studios. This optimization utility is suitable
for older PowerCubes when the model no longer exists or the data used to build the PowerCube is
no longer available. It is not necessary to run this command line utility for cubes created in IBM
Cognos 8 Transformer. For more information about optimizing PowerCubes, see the Transformer
User Guide.
You can publish single PowerCube data sources and packages to IBM Cognos Connection interact-
ively in Transformer or in the command line. You can also publish silently using batch scripts after
building a PowerCube. A user who has privileges to create data sources and packages in IBM Cognos
Connection can publish PowerCubes in IBM Cognos Connection as well. The MDC file must be

28 PowerPlay®
 Chapter 3: Distribution Options for IBM Cognos 8

in a secured location that the IBM Cognos 8 dispatcher can access. Packages that use multiple
PowerCubes or PowerCubes mixed with other data sources should be published using Framework
Manager.
If you use an IBM Cognos Series 7 PowerCube as a data source, IBM Cognos 8 converts the cube
data from the encoding that was used on the system where the PowerCube was created. For a suc-
cessful conversion, IBM Cognos Series 7 PowerCubes must be created with a system locale set to
match the data in the PowerCube.

Data Manager
Data Manager is used to create data warehouses and data repositories for reporting, analysis, and
performance management. When Data Manager is installed in your IBM Cognos 8 environment,
you can use the Data Movement Service to run builds and JobStreams in IBM Cognos Connection.
You must install the Data Manager engine in the same location as your IBM Cognos 8 Application
Tier Components. Both Data Manager and IBM Cognos 8 BI must be the same version.

IBM Cognos 8 Go! Mobile

With IBM Cognos 8 Go! Mobile you can access reports authored with Analysis Studio, Report
Studio, and Query Studio on a mobile device (such as a BlackBerry®). To download, view, and
interact with reports, IBM Cognos 8 Go! Mobile requires the installation of a custom-built, rich
client on the mobile device, in addition to the IBM Cognos 8 server components. Both IBM Cognos 8
Go! Mobile and IBM Cognos 8 BI must be at the same version.

IBM Cognos 8 Go! Search

The IBM Cognos 8 Go! Search add-on provides enhanced search and navigation options in IBM
Cognos 8. In IBM Cognos Connection, you can use full-text search to locate content. In Analysis
Studio, Query Studio, and Cognos Viewer, you can use full-text search and automatic navigation,
which locates content related to the content in the current view. The IBM Cognos 8 content store
must include content that can be indexed. Both IBM Cognos 8 Go! Search and IBM Cognos 8 BI
must be at the same version.

IBM Cognos Series 7 Content That Can Be Recreated in IBM Cognos 8

Some IBM Cognos products cannot be programmatically migrated with the migration tools for
IBM Cognos 8. IBM Cognos 8 offers two options for duplicating content or functionality for the
products described below: use the Upfront portal in the IBM Cognos 8 portal; or duplicate queries,
visualizations, or objects by using IBM Cognos 8 studios.

IBM Cognos Query

You can use the migration tools to identify IBM Cognos Query objects in the IBM Cognos Series 7
migration source. You can then duplicate most IBM Cognos Query functionality in IBM Cognos 8.
Foundation queries are available in IBM Cognos 8 when you migrate an Architect model. You can
also manually replicate saved queries using SQL components in Report Studio.

Installation and Configuration Guide 29

Chapter 3: Distribution Options for IBM Cognos 8

IBM Cognos Visualizer

You can duplicate functionality by using the charting, layout, and formatting options in Report
Studio and Analysis Studio.

IBM Cognos NoticeCast

You can duplicate alert and notification functionality by using Event Studio and other IBM Cognos 8
components.

IBM Cognos Web Services

You can duplicate most IBM Cognos Web Services functionality using the IBM Cognos 8 Software
Development Kit.

IBM CognosScript
You can duplicate automation functionality using the IBM Cognos 8 Software Development Kit.

IBM Cognos Portal Services

You can duplicate most IBM Cognos Portal Services functionality using IBM Cognos Connection.

30 PowerPlay®
Chapter 4: Setting Up the Environment

When you install your IBM Cognos 8 product, you must set up resources in your environment so
that the components can operate. For example, you must create a database for the content store
and configure Web browsers. You can also create a user or service account for IBM Cognos 8.
If you want to use Cognos Content Database as your content store, you do not have to create a
database or set up a database client. When you select the Cognos Content Database in the installation
wizard, a database is created during the installation and IBM Cognos 8 is configured to use it.
You must ensure that Web browsers on user computers are set up to provide access to IBM Cognos
components.
Use the following checklist to guide you through the setup process:
❑ Review the Readme.

❑ Review the supported environments.

❑ Ensure that your computer meets the software and hardware requirements.

❑ Review the default port settings.

❑ Create the database for the content store.

❑ Configure Web browsers.

❑ Configure a user or service account for IBM Cognos 8, if required.

After you complete these tasks, you must install and configure the IBM Cognos server components
on one (p. 67) or more computers (p. 93) to work in your environment.

Recommendation - Review the Readme Before You Install

Before you install your IBM Cognos product, it is important to be aware of all issues that may
affect your installation strategy.
There may be late-breaking issues that were not known when this installation guide was created.
We recommend that you review the Readme before you install your product. The Readme contains
late-breaking information about known issues as well as documentation updates and deprecation
notices. The Readme is available from the first page of the installation wizard or from the product
CD. Readme updates are also available on the IBM Cognos Resource Center (http://www.ibm.com/
software/data/support/cognos_crc.html).

Review Supported Environments

To ensure your product works properly, apply all minimum required operating system patches and
use only the versions of software that are supported for an IBM Cognos product.

Installation and Configuration Guide 31

Chapter 4: Setting Up the Environment

To review an up-to-date list of environments supported by IBM Cognos products, such as operating
systems, patches, browsers, Web servers, directory servers, database servers, and application servers,
visit the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.
html).
It is important to note that the Linux operating system is available in a number of distributions and
supports a number of hardware platforms. Ensure that the operating system and hardware combin-
ation you are using is a supported combination.

Verify System Requirements

Use the following table to check the minimum hardware and software requirements to install and
run IBM Cognos 8 components on one computer. Additional resources may be required for distrib-
uted or production environments.

Requirement Specification

Operating system Windows

UNIX
Linux
Some IBM Cognos 8 components are not supported under Linux.

RAM Minimum: 2 GB

Operating system specifications File descriptor limit set to 2048 on UNIX and Linux (recommen-
ded)

Disk space A minimum of 2.5 GB of free space is required to install the

software and 4 GB of free space on the drive that contains the
temporary directory used by IBM Cognos components.

Web server A Web server must be installed and started.

Java Runtime Environment An IBM JRE is installed automatically with IBM Cognos 8 on
(JRE) Windows.
If you are using an application server, use the JRE that is installed
with it, if it is supported in IBM Cognos 8.

32 PowerPlay®
 Chapter 4: Setting Up the Environment

Requirement Specification

Database Cognos Content Database can be installed and configured as

the default content store database.
If you want to use another database, you must have one of the
following databases available to store IBM Cognos data:
● Oracle

● DB2

● Microsoft SQL Server

● Sybase

TCP/IP connectivity is required for all database types.

Web browser For all Web browsers, the following are enabled:
● cookies

● JavaScript

For Microsoft Internet Explorer only, the following are enabled:

● Active scripting

● Allow META REFRESH

Other On Windows, Microsoft Data Access Component (MDAC) for

use with product samples
If you want to email reports, the ability to use a mail server

Review the Default Settings for IBM Cognos 8

The following table lists the default ports and URI settings for IBM Cognos 8. After installation,
you can use the configuration tool to change the settings (p. 192).

Setting Default Description

Content Manager URI http://localhost:9300/ p2pd/servlet The URI to Content Manager

Gateway URI http://localhost:80/ cognos8/cgi- The URI to the gateway

bin/cognos.cgi

Dispatcher URI http://localhost:9300/ p2pd/servlet/ The URI to the dispatcher

dispatch
(Internal, External)

Installation and Configuration Guide 33

Chapter 4: Setting Up the Environment

Setting Default Description

Dispatcher URI for external http://localhost:9300/ p2pd/servlet/ The URI to the dispatcher
applications dispatch

Dispatcher URIs for Gate- http://localhost:9300/ p2pd/servlet/ The URI to the primary dis-
way dispatch/ext patcher used by the gateway

Log server port 9362 The port used by the local log
server

Listening port number 1527 The port used by Cognos

Content Database.

The following table lists the default settings used by IBM Cognos 8 for Tomcat. The non-SSL and
SSL connectors are automatically updated in the server.xml file when you use IBM Cognos Config-
uration to change the dispatcher port or to enable the SSL protocol. You can directly update the
shutdown port using IBM Cognos Configuration.

Setting Port Description

Non-SSL Coyote HTTP/ 1.1 9300 The port Tomcat uses to pass
Connector requests from the Web server to
IBM Cognos 8

SSL Coyote HTTP/1.1 connector 9334 The port Tomcat uses to listen for
secure connections

Shutdown port 9399 The port Tomcat uses to listen for

a shutdown command

The following table lists the default settings used in migration from IBM Cognos Series 7 to IBM
Cognos 8 PowerPlay.

Setting Port Description

Migration Service Port Number 21567 The port used for communications
between IBM Cognos Series 7
migration service and IBM Cognos 8
migration service

PPBOOKMARKTOOL_PORT 7777 The port used for bookmark migra-

tion

34 PowerPlay®
 Chapter 4: Setting Up the Environment

Guidelines for Creating the Content Store

The content store is a database that Content Manager uses to store global configuration data, global
settings (such as the language and currency formats shown in the user interface), connections to
data sources, and product-specific content.
Design models and log files are not stored in the content store.
You must create the content store before you can use IBM Cognos 8.
If you are upgrading from ReportNet or a previous version of IBM Cognos 8, you can use your
existing content store with the new version of IBM Cognos 8. After the content store is upgraded,
you cannot use it with the previous version. If you are upgrading and you want to keep running
ReportNet or the older version of IBM Cognos 8, you must create a new content store database
for use with IBM Cognos 8. You must follow the appropriate upgrade process (p. 64) when creating
the new content store database.

Database Properties
You must create the database using one of the databases listed in the following table:

Database Character Encoding Protocol

DB2 UTF-8 TCP/IP

Oracle AL32UTF8 or AL32UTF16 TCP/IP

SQL Server UTF-8 or UTF-16 TCP/IP

Sybase UTF-8 TCP/IP

Cognos Content Database pre configured pre configured

If you plan to use the Cognos Content Database as your content store, a database is created and
pre configured when the installation is complete.

Collation Sequence
Note that Cognos 8 uses a single sort order that specifies the rules used by the database to interpret,
collect, compare, and present character data. For example, a sort order defines whether the letter
A is less than, equal to, or greater than the letter B; whether the collation is case sensitive; and
whether the collation is accent sensitive. For more information about collation and collation
sequences, see the database documentation.

Suggested Settings for Creating the Content Store in DB2 on Linux, Windows,
and UNIX
The database you create for the content store must contain the recommended configuration settings.
To ensure a successful installation, use the following guidelines when creating the content store.

Installation and Configuration Guide 35

Chapter 4: Setting Up the Environment

32-bit Library Files for DB2

IBM Cognos 8 requires 32-bit library files. If you have installed DB2 version 9.5, the 64-bit library
files may be set in your environment variables. You must change the library files used or change
the order in which the library files are listed so that IBM Cognos 8 can find the 32-bit library files.
The 32-bit library files must be listed first for IBM Cognos 8.

Guidelines for Creating the Content Store in DB2 on Linux, UNIX, or Windows
If you create your own content store, use the following checklist to help you set up the content store
on DB2.
❑ If you use type 2 UDBC connectivity, set the appropriate environment variables for DB2, which
are as follows.

Environment variable Description

DB2DIR The top level directory that contains the database client
software or the entire database installation.

LD_LIBRARY_PATH The load library path.You must add the driver location.
For example, LD_LIBRARY_PATH= $DB2_location/sqllib/
lib32: $LD_LIBRARY_PATH
Examples:
For Solaris and Linux:
LD_LIBRARY_PATH= $DB2DIR/lib:
$LD_LIBRARY_PATH
For AIX:
LIBPATH=$DB2DIR/lib:$LIBPATH
For HP-UX:
SHLIB_PATH=$DB2DIR/lib:$SHLIB_PATH

DB2INSTANCE The default database server connection.

DB2CODEPAGE Setting this optional environment variable to a value of

1208 provides support for multilingual databases.
For information about whether to use this environment
variable, see the DB2 documentation.

❑ Use UTF-8 as the code set value when you create the database.
To check if your database has the correct code set, using the command line interface, type the
following at the command prompt:

db2 get database configuration for database_name

The code set value should be UTF-8 and the code page value should be 1208.

36 PowerPlay®
 Chapter 4: Setting Up the Environment

❑ Ensure that you set the following configuration parameters.

Property Setting

Application heap size 1024 KB

(applheapsz)

Lock timeout (locktimeout) 240 seconds

Do not set this to an infinite timeout value.

If the application heap size value is too small, out of memory errors may occur when there are
many users.

❑ Create a buffer pool with a page size of 32 KB, and a second one with a page size of 4 KB.

❑ Create a system temporary tablespace using the 32 KB buffer pool you created in the previous
step.

❑ Create a user temporary tablespace using the 4 KB buffer pool you created.
Global temporary tables will be created in the user temporary tablespace.

❑ Create a regular user tablespace using the 4 KB buffer pool you created.
If you are also creating a logging database, create an additional regular user tablespace with a
page size of 8 KB.

❑ Grant the following database privileges for the user account IBM Cognos 8 will use to access
the database:
● connect to database

● create tables

● create schemas implicitly

Tip: If you want to host more than one content store on your DB2 instance and you will use
both at the same time, use a different user account for each content store to ensure that each
IBM Cognos 8 instance is fully isolated from the other.

❑ Ensure that the user account has use privileges for the user temporary tablespace and other
appropriate tablespaces associated with the database.

❑ Create a schema for the user account IBM Cognos 8 will use to access the database, and ensure
the user has create, drop, and alter permissions for the schema.

❑ We recommend that you create a profile that sources the sqllib/db2profile from the DB2 user’s
home directory. For example, the content of your .profile will be similar to the following:
if
[ -f /home/db2user/sqllib/db2profile ]; then
./home/db2user/sqllib/db2profile
fi

Installation and Configuration Guide 37

Chapter 4: Setting Up the Environment

❑ Your database administrator must back up IBM Cognos 8 databases regularly because they
contain the IBM Cognos data. To ensure the security and integrity of databases, protect them
from unauthorized or inappropriate access.

Suggested Settings for Creating the Content Store in DB2 on z/OS

The database you create for the content store must contain some recommended configuration settings.
To ensure a successful installation, use the following guidelines when creating the content store.

Guidelines for Creating the Content Store in DB2 on z/OS

Use the following checklist to help you help you set up the content store in DB2 on z/OS.
❑ Create a database instance, storage group, and a user account for the content store.
A user must have permissions to create and delete tables in the database.
IBM Cognos 8 uses the credentials of the user account to communicate with the database server.

❑ Ensure you reserve a buffer pool with a page size of 32 KB, and a second one with a page size
of 4 KB for the database instance.

❑ Administrators must run a script to create tablespaces to hold Large Objects and other data
for the content store and grant user rights to the tablespaces. For information about running
the script, see "Create Tablespaces for DB2 Content Store on z/OS" (p. 41).

❑ Your database administrator must back up IBM Cognos 8 databases regularly because they
contain the IBM Cognos data. To ensure the security and integrity of databases, protect them
from unauthorized or inappropriate access.

Suggested Settings for Creating the Content Store in Oracle

The database you create for the content store must contain some recommended configuration settings.
To ensure a successful installation, use the following guidelines when creating the content store.

Guidelines for Creating the Content Store in Oracle

Use the following checklist to help you set up the content store on Oracle.
❑ Ensure that the parameter for the database instance compatibility level of the content store
database is set to 9.0.1 or higher.
For example, you can check the COMPATIBLE initialization parameter setting by issuing the
following SQL statement:

SELECT name, value, description FROM v$parameter WHERE name='compatible';

For information about changing an instance configuration parameter, see the Oracle document-
ation.

❑ Determine if the database is Unicode.

Tip: One method is to type the following select statement:

select * from NLS_DATABASE_PARAMETERS

38 PowerPlay®
 Chapter 4: Setting Up the Environment

If the result set returns an NLS_CHARACTERSET that is not Unicode, create a new database
and specify AL32UTF8 for the database character set parameters.

❑ Determine which user account will be used to access the database.

Tip: If you want to host more than one content store on your Oracle instance and you will use
both at the same time, use a different user account for each content store to ensure that each
Cognos 8 instance is fully isolated from the others.

❑ Ensure that the user account that accesses the database has permission to do the following:
● connect to the database

● create, alter, and drop tables, triggers, views, procedures, and sequences

● insert, update, and delete data in the database tables

❑ Your database administrator must back up Cognos 8 databases regularly because they contain
the Cognos data. To ensure the security and integrity of databases, protect them from unauthor-
ized or inappropriate access.

Suggested Settings for Creating the Content Store in Microsoft SQL Server
The database you create for the content store must contain some recommended configuration settings.
To ensure a successful installation, use the following guidelines when creating the content store.

Suggested settings for Microsoft SQL Server

Use the following checklist to help you set up the content store on Microsoft SQL Server.
❑ Ensure that the collation sequence is case-insensitive.
In a Custom installation, you choose a collation, which includes character sets and sort order,
during the SQL Server setup. In a Typical installation, the installation uses the locale identified
by the installation program for the collation. This setting cannot be changed later.

❑ When connecting to Microsoft SQL Server Management Studio to create the database, use SQL
server authentication.
If you connect using Windows authentication, the database that you create will also use Windows
authentication. In this situation, you must configure the database connection using a database
type of SQL Server database (Windows Authentication) in IBM Cognos Configuration.

❑ For the user account that will be used to access the database, create a new login under Security
and use the following settings:

● Select SQL Server authentication.

● Clear the Enforce password policy check box.

Tip: If you want to host more than one content store on your Microsoft SQL Server instance
and you will use both at the same time, use a different user account for each content store to
ensure that each IBM Cognos 8 instance is fully isolated from the others.

Installation and Configuration Guide 39

Chapter 4: Setting Up the Environment

❑ For Microsoft SQL Server 2008, grant EXECUTE permission to the user account that accesses
the database.

❑ For the content store database, create a new database under Databases.

❑ Under Security for the new database, create a new schema and assign a name to it.

❑ Under Security for the new database, create a new user with the following settings:

● For Login name, specify the new login that you created for the user account.

● For Default schema, specify the new schema.

● For Owned Schemas, select the new schema.

● For Role Members, select db_datareader, db_datawriter, and db_ddladmin.

Suggested Settings for Creating the Content Store in Sybase

The database you create for the content store must contain some recommended configuration settings.
To ensure a successful installation, use the following guidelines when creating the content store.

Suggested settings for Sybase

Use the following checklist to help you set up the content store on Sybase.
❑ On the Sybase server, create a server instance with an 8 KB server page size.
For instructions, see the Sybase documentation.

❑ If required, install jConnect 5.5.

This tool sets up the communication between the JDBC driver and the Sybase Adaptive Server
instance.
For instructions, see the Sybase documentation.
If your version of Sybase does not include jConnect 5.5, you must download the installer from
Sybase’s Web site.

❑ Add the UTF-8 character set to the server instance.

❑ If required, make UTF-8 the default character set on the server.

❑ Create a database device.

Tip: Set log_segment to a minimum of 10 MB.

❑ Set the new database device as the default.

Information about the new database will be stored in the new database device. Keep a backup
of the database device for recovery purposes.

❑ Create the database.

❑ Determine which user account will be used to access the database.

40 PowerPlay®
 Chapter 4: Setting Up the Environment

Tip: If you want to host more than one content store on your Sybase instance and you will use
them at the same time, use a different user account for each content store to ensure that each
IBM Cognos 8 instance is fully isolated from the others.

❑ Ensure that the user account has the following privileges for the database: create default, create
procedure, create rule, create table, and create view.

❑ Ensure that the database has the following settings and is restarted:
● create and drop table privileges for the user account

● Select into property is set to True

Create Tablespaces for DB2 Content Store on z/OS

A database administrator must run a script to create a set of tablespaces required for the content
store database. The script must be modified to replace the placeholder parameters with ones that
are appropriate for your environment.
Ensure that you use the naming conventions for DB2 on z/OS. For example, all names of parameters
must start with a letter and the length must not exceed eight characters. For more information, see
the IBM DB2 Information Center.

Steps
1. Connect to the database as a user with privileges to create and drop tablespaces and to allow
execution of SQL statements.

2. Open the tablespace_db2zOS.sql script file and use the following table to help you to replace
the generic parameters with ones appropriate for your environment.
Not all of the parameters listed are in the script, but may be added in the future.

Parameter Name Description

CMSCRIPT_CREATE_IN Specifies the base tables location

For example, databaseName.baseTablespaceName

CMSCRIPT_STOGROUP Specifies the name of the storage group.

CMSCRIPT_DATABASE Specifies the name of the content store database.

CMSCRIPT_CS_ID Specifies the instance identification for the content

store database.
The ID must not be longer than two characters.

Installation and Configuration Guide 41

Chapter 4: Setting Up the Environment

Parameter Name Description

CMSCRIPT_TABLESPACE Specifies the name of the tablespace that will contain

all of the base tables in the content store.
Auxiliary tables are not included.
The name cannot be longer than six characters.

CMSCRIPT_LARGE_BP Specifies the name of the large buffer pool allocated

for especially large objects.

CMSCRIPT_REGULAR_BP Specifies the name of the regular size buffer pool

allocated for regular and large objects.

CMSCRIPT_USERNAME Specifies the user account that accesses the content

store database.

3. Save and run the script.

4. Grant the IBM Cognos user rights to the tablespaces that were created when you ran the
tablespace_db2zOS.sql file script:
● In the remote access tool, open the rightsGrant_db2zOS.sql script file and replace the
placeholder parameters with values that are appropriate for your environment.

Tip: Ensure that you use the same values that you used when you allocated resources to
the buffer pools and user account.

● Save and run the file.

The content store database is created. You can now configure a database connection.

Configure Web Browsers

Cognos 8 PowerPlay uses the default browser configurations provided by Microsoft and Firefox.
For all browsers, you must ensure that settings are enabled for cookies and JavaScript. Additional
required settings are specific to the browser.
The following table shows the settings that must be enabled in the supported Web browsers.

Browser Setting Cognos component

Internet Explorer (settings for Allow Cookies IBM Cognos Connection

studios and portals) Active Scripting IBM Cognos Administration
Allow META REFRESH Cognos Viewer
PowerPlay Studio

42 PowerPlay®
 Chapter 4: Setting Up the Environment

Browser Setting Cognos component

Firefox Allow Cookies IBM Cognos Connection

Enable JavaScript IBM Cognos Administration
Load Images Cognos Viewer
PowerPlay Studio

Important: If Adblock Plus is installed with Firefox, disable it using the per-page option. Adblock
Plus prevents some Cognos Connection resources from working properly.
Cognos 8 PowerPlay uses the following cookies to store user information.

Cookie Type Purpose

AS_TICKET Session temporary Created if Cognos 8 PowerPlay

is configured to use a Cognos
Series 7 namespace

caf Session temporary Contains security state informa-

tion

Cam_passport Session temporary Stores a reference to a user ses-

sion stored on the Content
Manager server

cc_session Session temporary Holds session information that

is specific to Cognos Connec-
tion

cc_state Session temporary Holds information during edit

operations, such as cut, copy,
and paste

CRN Session temporary Contains the content and

product locale information, and
is set for all Cognos users

pp_session Session temporary Stores session information that

is specific to PowerPlay Studio

userCapabilities Session temporary Contains all capabilities and the

signature for the current user

Installation and Configuration Guide 43

Chapter 4: Setting Up the Environment

Cookie Type Purpose

usersessionid Session temporary Contains a unique user session

identifier, valid for the duration
of the browser session

FrameBorder Session temporary These cookies store the prefer-

ences for export to PDF.
PageOrientation
PageSize
PDFLayerDimension
PDFOPTS

DimTreeToolbarVisible Persistent Stores the setting that determ-

ines whether to show or hide
the dimension viewer toolbar.

cea-ssa Session temporary Stores the setting that determ-

ines whether the user session
information is shared with
other IBM Cognos 8 compon-
ents.

BRes Session temporary Stores information used to

determine the screen resolution
to use to render charts.

After upgrading or installing new software, restart the Web browser and advise users to clear their
browser cache.

Configure a User Account or Network Service Account for IBM

Cognos 8
You can configure either a user account or a network service account for IBM Cognos 8.
The user or network service account under which IBM Cognos 8 runs must:
● have access to all required resources, such as printers and Web servers

● have the rights to log on as a service and act as part of the operating system

In addition, the user account must be a member of the local administrator group.
For example, to print reports using a network printer, the account must have access to the network
printer, or you must assign a logon account to the IBM Cognos 8 service.

44 PowerPlay®
 Chapter 4: Setting Up the Environment

Configure a User Account

For Windows, we recommend that you assign a logon account to the IBM Cognos 8 service. You
can configure the IBM Cognos 8 service to use a special user account by selecting the IBM Cognos 8
service from the list of services shown in the Services window in Windows. You can then define the
user account properties.
For UNIX or Linux, we recommend that you create a new UNIX or Linux group named cognos8.
This group must contain the user that owns the IBM Cognos files. Change the group ownership of
the IBM Cognos files to the cognos8 group and change the file permissions for all IBM Cognos files
to GROUP READABLE/WRITABLE/EXECUTABLE.
You must configure the Web Server to use aliases. For more information, see "Configure the Web
Server" (p. 121).

Configure a Network Service Account

The network service account is the built in account NT AUTHORITY\NetworkService in the
operating system. Administrators do not need to manage a password or maintain the account.
Use an account with administrator privileges if you are installing on Windows Server 2008.
You must configure the Web server to use the application pool. For more information, see "Configure
the Web Server" (p. 121). You also need the appropriate write permissions to install to the directory.

Installation and Configuration Guide 45

Chapter 4: Setting Up the Environment

46 PowerPlay®
Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

New versions of IBM Cognos 8 PowerPlay provide enhancements that may affect many components,
such as product features and functionality, performance and scalability, and usability. Because of
these improvements, upgrading may not be simple, and should be considered a process that you
perform in stages.
If you are upgrading both IBM Cognos 8 PowerPlay and other IBM Cognos 8 components, see the
IBM Cognos 8 Installation and Configuration Guide for upgrade information for IBM Cognos 8
components such as Framework Manager.
You should treat upgrading as an IT project that requires careful planning, adequate time, and
resources.
When you upgrade, you perform two distinct activities:
1. Install the new version of the product.

2. Move applications to the new version of the product.

Install the New Version of the Product

You can install the new version of the product in the same location as the existing version after you
uninstall, or you can install into a new location.
We recommend that you first install into a new location, such as a test environment. This allows
you to test your applications in both the old and new environment to ensure that they work as
expected when you upgrade. You can compare the appearance and functionality of the reports in
both environments to ensure equivalency.

Move Content to the New Environment

As part of the upgrade process, ensure that your applications work as expected in the new version.
Sometimes, changes may introduce unexpected results. It is important to test your applications
before you move them.
In Cognos 8, when you move content from one environment to another, you do a deployment.
Different groups are commonly involved in each of these activities. As part of the project, you
should assess both your current IT environment and your existing applications separately, to ensure
that the infrastructure can support your business objectives.
If you have IBM Cognos Series 7 content, you can move some of that content to IBM Cognos 8
using migration tools that are available in a separate installation.
If you are using previous versions of ReportNet, Metrics Manager, IBM Cognos 8 Go! Office, or
Transformer, you can upgrade your content to IBM Cognos 8. You can also upgrade from previous
versions of IBM Cognos 8, including full and maintenance (MR) releases.

Installation and Configuration Guide 47

Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

Upgrade Process
The following diagram shows the approach that we recommend when you upgrade. The diagram
shows the stages in the upgrade process. Before you start, you plan the upgrade, assess the applica-
tions that you want to upgrade and create a test environment. You should iteratively deploy and
test content in both the source and target environments before you to move successfully upgraded
applications to a production environment.
Upgrade Process Workflow

Source environment New environment

1 2 3
Plan the Assess Create new
upgrade applications environment

4
Deployment process

Export existing Copy to new Import

Plan content Test
content environment

5
Test upgraded
applications

6
Move to production environment

Prepare Deploy from

Back up Uninstall Install new test
environment files version environment

In some upgrade situations, other tasks may be required. For example, if you use SDK applications
that depend on the report specifications, you must upgrade your SDK applications before upgrading
the report specifications. If you are upgrading from ReportNet 1.1 MR3 or MR4, you can use
Upgrade Manager to automate some tasks in the trial upgrade stage.
See the following topics for information about upgrading:
❑ Planning the Upgrade

❑ Upgrading from an Earlier Version of IBM Cognos 8 PowerPlay

Planning the Upgrade

We recommend that you plan your upgrade so that you know what to expect at each stage of the
process. In the planning stage, you can review the upgrade documentation for information about
expected behavior, new features, deprecated features, compatibility between versions, and require-
ments for preparing your production environment. When you finish the review, you can then conduct
a site survey to identify the BI infrastructure, applications, reports, and custom configuration settings.
Finally, you can test the upgrade on a subset of your data so that you can fine tune your reports
and data before committing to the full upgrade.
The following diagram shows a high level view of the phases in an upgrade project.

48 PowerPlay®
 Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

Source environment New environment

1 2 3 4 5
Planning the Assess Create test Deploy Test upgraded Move to
upgrade content environment content applications production

When planning your upgrade, ensure that you

● gather the necessary information, such as the required inputs and expected outputs for each
phase

● assess the applications in your reporting environment and group similar reports together

● install the new software in a test environment and deploy the content to the test environment

● test the upgraded applications to ensure reports run as expected

Deployment and testing is usually an iterative process. Assess any differences between the source
and target environments to determine actionable activities. Move to your production environment
when you are satisfied that the deployed applications meet your business requirements.
We recommend that you do not change security providers, such as changing from an IBM Cognos
Series 7 namespace to Active Directory as part of the upgrade process. You should treat that as a
separate project.
Ensure that you have the skills available, either internal or using external resources. Also consider
the hardware that you will need before you begin.
Use the following checklist to guide you through the planning process:
❑ Review the documentation.

❑ Assess applications in the source environment.

❑ Perform a trial upgrade, which includes the following tasks:

● Create the test environment.

● Plan the deployment of content from the source environment to the test environment.

● Create an export deployment specification.

● Copy the deployment specification to the test environment.

● Include configuration objects for import, if required.

● Import the deployment specification to Cognos 8 in the test environment.

● Test the upgraded content.

❑ Move to the production environment.

Installation and Configuration Guide 49

Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

Review the Documentation

Documentation is provided from a variety of sources to help you achieve a successful upgrade. All
the documentation is available online at the IBM Cognos Resource Center (http://www.ibm.com/
software/data/support/cognos_crc.html).

Steps
1. Read the "What’s New" section in this guide.
It contains a list of new, changed, deprecated, and removed features for this release.

2. Read the rest of the Upgrade information in this document.

3. Read the topic about IBM Cognos 8 with other IBM Cognos products (p. 25).
It contains information about other IBM Cognos products that you may have in your environ-
ment and that must be considered in the upgrade.

4. From the Documentation link on the IBM Cognos Resource Center (http://www.ibm.com/
software/data/support/cognos_crc.html), download and review the latest versions of the following
documentation:

Document Description

IBM Cognos 8 PowerPlay Readme Recent issues that may affect an upgrade

IBM Cognos 8 New Features New features that may affect the behavior
of existing content

Framework Manager User Guide Upgrading models

Report Studio Professional Authoring User Upgrading reports

Guide

IBM Cognos 8 Transformer User Guide Upgrading user views and upgrading IBM
Cognos Series 7 models

IBM Cognos 8 Migration and Upgrade Moving metadata, Impromptu catalogs and
Tools User Guide reports, PowerPlay reports, and Upfront
content from IBM Cognos Series 7 to IBM
Cognos 8

Upgrade Manager User Guide Using Upgrade Manager to audit trial

upgrades from ReportNet 1.1 MR3 or MR4
to Cognos 8.2 or later

IBM Cognos 8 SDK Developer Guide Upgrading SDK applications

50 PowerPlay®
 Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

Recommendation - Assess Applications in the Source Environment

Preparing to upgrade provides an opportunity to review your current BI investment, and clean up
your source environment. Inventory your BI applications to understand the strengths, weaknesses,
and areas for improvement in your environment.
For example, you may have a hundreds of reports, packages, public folders and applications in
your environment. However, it is not uncommon to find that a number of applications are not
used, or no longer meet the company’s requirements, or do not work in the source environments.
We recommend that you conduct an audit of your applications to determine which applications
should be upgraded. Assessing and reducing the number of reports is a useful exercise. Do not rely
only on user feedback to determine which content is used.
An audit of your existing applications may include the following:
❑ Do a site survey.
A survey will help you to assess the current production environment and identify areas that
require attention during an upgrade. The site survey should include information about the
infrastructure, applications, users, and configuration settings for your Cognos 8 products.

❑ Assess the software that you use in your reporting application.

List software, such as operating systems, Web servers, security, databases, and so on. Compare
the list to the supported versions for your target upgrade version, available from the Production
Information, Software Environments links at the IBM Cognos Customer Service Center (http:
//www.ibm.com/software/data/support/cognos_crc.html). Determine whether any components
require updating.

❑ List your BI applications, including the following:

● Framework Manager models

● published packages

● reports

● Transformer models

● SDK applications and their dependencies

❑ Complete a detailed assessment of your applications.

The usage, age, size, and complexity of your applications are important factors to consider
when planning the upgrade. The total size of the applications may have an impact on the time
required to complete the upgrade.

❑ List all the reports contained in your application and do the following:
● Interview the team members to see which cubes, views, or reports are needed and used,
which ones can be consolidated, and which ones can be eliminated. Use audit report data
to determine report usage.
Upgrade only the reports that work and that users need and use. This reduces the number
of applications that you must upgrade.

Installation and Configuration Guide 51

Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

For more information about audit reports, see the Administration and Security Guide.

● Look at the purpose of each report and assign a priority.

This identifies business-critical applications and the functionality that is required in the
new environment.

● Flag reports that fail to run or validate in the current environment.

They are unlikely to upgrade successfully. Repair these reports so that they upgrade.

● Consider retiring unused or little-used reports.

● Group the reports into categories, such as upgrade, eliminate, no longer used, and do not
upgrade,

❑ List the following information about your configuration:

● configuration settings that you enabled using IBM Cognos Configuration
These settings are preserved through the upgrade. They are stored in two files. For
ReportNet v1.1, the files are crnstartup.xml and crnlocale.xml. For IBM Cognos 8, the
files are cogstartup.xml and coglocale.xml.

● changes to other configuration files

Changes to other files must be made manually during the upgrade. If you changed other
configuration files, you must assess the changes that you want to preserve in the upgraded
environment. This may include .xml, .txt, and .css files in the configuration, templates,
webapps, and webcontent directories of the installation location.

Important: Changes to .ini files are not supported. If you changed .ini files, please contact
Customer Support.

❑ Back up all reports, models, and configuration data and files.

❑ Create an upgrade plan.

Recommendation - Perform a Trial Upgrade

Pilot upgrade projects are valuable and practical exercises because they ensure that the upgrade
produce the expected and required outcome. In addition, an evaluation of the pilot project ensures
that the upgrade is successful. If unexpected results occur, you can determine whether the differences
are enhancements for your situation or whether you should take action to mitigate the differences.
When you upgrade, applications usually work in the new environment, with little or no intervention.
By running an pilot upgrade you can validate selected reports to see if the expected results are
produced.
We recommend that you perform a trial upgrade several weeks before upgrading your production
system. The trial upgrade identifies components that will upgrade with minimal effort, and compon-
ents that may require additional actions before or after the upgrade.
Commonly, you upgrade a sample set of reports in an isolated environment, and you compare the
appearance and behavior of the reports before and after the upgrade.

52 PowerPlay®
 Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

Ensure skilled resources are available to perform migration work, especially for mission-critical
applications. Also, test and debug all applications prior to deployment.

Create the Test Environment

Create a test environment for the new software in preparation for your trial upgrades.
Initially, the new environment does not need to be large, or be the same as your production envir-
onment. For example, if it is acceptable, you may use hardware from existing environments, such
as development servers.
The environment can be scaled up and out in a phased way after the basic new environment is up
and running.
Alternatively, existing environments can remain untouched. If you want the test environment to
become the new production environment, configure the test system to match your production
environment.

Steps
1. Ensure the infrastructure is in place.

2. Review the supported environments.

3. Install the new software in the test environment.

Having the new version of software in a different location than the earlier version ensures that
you run both versions at the same time and confirm that your applications work properly in
both environments.
For more information about installing a basic installation, see "Installing and Configuring IBM
Cognos 8 PowerPlay on One Computer" (p. 67).

After you have installed the software, use the deployment process to upgrade the content. For more
information, see the online help in the IBM Cognos Administration console.

Plan Your Deployment

Deployment involves moving applications from one installation to another. In Cognos 8, you deploy
packages, top-level folders, or the entire content store from a source environment to a target
environment.
When you deploy, you must consider how to handle security and whether to deploy the entire
content store or to deploy selected packages, folders, and directory content. Other considerations
relate to the database you use for the content store, bursting reports, and ownership of entries.
For more information about planning the deployment of content to a new environment, see the
online help for the Administration console.
The following diagram summarizes the deployment process.

Installation and Configuration Guide 53

Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

Deployment Process Workflow

4
Deployment process

Export existing Copy to new Import

Plan Test
content environment content

5
Test upgraded
applications

Security
Before you deploy, you must consider access permissions and security of deployment archives.
To deploy IBM Cognos Connection entries, you must have the following permissions:

● Execute permissions for the Administration tasks secured feature.

● Traverse permissions for the Administration secured function.

We also recommend that you belong to the System Administrators group, and have read and write
access to the Cognos namespace, so that you can deploy the System Administrators group.
For information about deploying IBM Cognos groups and roles, see the online help in the IBM
Cognos Administration console.

References to Namespaces
Some entries, such as groups, roles, distribution lists, contacts, data source signons, and some report
properties, such as email recipients and report contacts, can refer to entities in namespaces, or
authentication providers. When you deploy public folders and directory content, you can deploy
these entries with or without the third-party references.

Deploying the Entire Content Store

Deploying the entire content store ensures that all packages, folders, and directory content are
copied to a new location. For example, if you are changing the computer where IBM Cognos 8 is
installed, you can move the entire content store from the old environment to the new environment
and keep all the reports and other entries created by administrators and users.
When you import an entire content store, configuration data is included in the export, but excluded
from the import by default. We recommend that you do not change this setting. However, if you
must import configuration settings (p. 57), you can change the default in the Advanced Settings.

Deploying Selected Public Folders and Directory Content

You can choose to do a partial deployment, deploying only selected public folders and directory
content.
You can choose the packages and folders that you want to deploy by browsing the Public Folders
hierarchy and select a package or folder. Once you select a package or folder, its contents are
deployed. You cannot select specific entries in the packages or folders. During export, the parent
packages and folders are not exported and Content Manager does not create placeholder locations
for them in the target environment. During both export and import, you can specify a new target
location in the Content Manager hierarchy for each deployed package and folder.

54 PowerPlay®
 Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

When you do a partial export of public folders and directory content, you must have the following
permissions:
● Read and traverse permissions for the entries that you export.

● Write permissions because you create a deployment specification and deployment history when
you export.

● Write and set policy permissions for the entries that you import.

Deploying Packages
A package is an entry that contains published reports and metadata. Packages are stored in the
content store and appear as entries in IBM Cognos Connection.
During a partial deployment, you can deploy one or more packages at a time. A package can reference
objects that are outside the package, such as security objects, data sources, and distribution lists.
However, referenced objects are not deployed with the package.

Create an Export Deployment Specification

After planning your deployment, the first step in moving content from the one installation to another
is to export the content store or the entries that you want to keep in your new environment. To do
this, you create an export deployment specification in your source environment.
The entries are exported to an export deployment archive in the source environment. Later, you
import the archive entries into the target environment. You can update the entries in the target
environment using the entries from the deployment archive.
We recommend that you stop the Cognos 8 service before you export and import.

Steps to Create a New Export Deployment Specification for the Content Store
1. In IBM Cognos Administration, on the Configuration tab, click Content Administration.

2. On the toolbar, click the new export button and follow the instructions in the New Export
wizard.

3. To export the entire content store, click Select the entire content store and select whether to
include user account information.

4. Click Next.

5. If you want to secure the archive, under Encryption, click Set the encryption password, type a
password, and then click OK, and then click Next.
The summary information appears.

6. Review the summary information and click Next.

Tip: If you want to change information, click Back and follow the instructions.

7. Determine how you want to run the export by selecting the action you want.

Installation and Configuration Guide 55

Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

After you run the export, you can move the deployment archive. You can also see the export run
history.

Steps to Create a New Export Deployment Specification for Partial Deployments

1. In IBM Cognos Administration, on the Configuration tab, click Content Administration.

2. On the toolbar, click the new export button and follow the instructions in the New Export
wizard.

3. To export specific folders and directory content, click Select public folders and directory content,
and then click Next.

4. In the Select the Public folders content page, click Add.

5. In the Select entries page, in the Available Entries box, select the packages or folders that you
want to export.
You can browse the Public Folders hierarchy and choose the packages and folders you want.

Click the right arrow button to move the selected items to the Selected entries box, and
click OK.

6. For each package and folder that you export, do one of the following:
● If you want to make any changes to the package or folder in the target environment, click

the edit icon make your changes, and click OK.

● To restrict access to the package or folder and its entries, select the check box in the Disable
after import column. This is useful when you want to test the reports before you make
them available in the target environment.

7. Under Options, select whether you want to include the report output versions, run history, and
schedules and what to do with entries in case of a conflict, and then click Next.

8. In the Select the directory content page, select whether you want to export IBM Cognos groups
and roles, distribution lists and contacts, and data sources and connections and what to do
with the entries in case of a conflict, and then click Next.

9. In the Specify the general options page, select whether to include access permissions and who
should own the entries after they are imported in the target environment.

10. Specify the Recording Level for the deployment history, and then click Next.

11. In the Specify a deployment archive page, under Deployment archive, select an existing
deployment archive from the list, or type a new name to create one.
If you are typing a new name for the deployment archive, we recommend that you do not use
spaces in the name. If the name of the new deployment specification matches the name of an
existing deployment archive, the existing deployment archive is overwritten.

12. If you want to secure the archive, under Encryption, click Set the encryption password, type a
password, and then click OK.

56 PowerPlay®
 Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

13. Click Next.

The summary information appears.

14. Review the summary information and click Next.

Tip: If you want to change information, click Back and follow the instructions.

15. Determine how you want to run the export by selecting the action you want.

After you run the export, you can move the deployment archive. You can also see the export run
history.

Steps to Run an Export

1. In the Actions column, click the run with options button .

2. Click Now to run the export immediately, or click Later, and enter the time that you want the
export to run.
You can also schedule a task to run on a recurring basis, and view a list of scheduled tasks
using the Schedule Management tool.

You can now move the deployment archive.

Copy the Deployment Specification to the Test Environment

Move the deployment archive that you created in the source environment to the test environment.
Later, you use the deployment archive to import entries into the target environment.
If the source and test environments use the same content store, you can import without moving the
deployment archive.
The default location is c8_location\deployment.
If you plan to move the deployment archive to a location on a LAN, ensure that there is enough
disk space. If you did not encrypt the deployment archive, we recommend that you copy it to a
secure location.

Steps to Copy the Deployment Specification

1. Copy the deployment specification from the source environment to a LAN location or to a CD.

2. Copy the deployment specification from the LAN or CD to the test environment location spe-
cified in the configuration tool.

You can now include configuration objects if you’re importing an entire content store or import to
the target environment.

Include Configuration Objects in Import of Entire Content Store

You can include configuration objects when importing an entire content store. For example, you
may want to import the configuration because you have a series of advanced settings for your services
that you want from the source environment.

Installation and Configuration Guide 57

Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

By default, configuration objects are excluded when you import an entire content store, even though
they are included in the export. Configuration objects include dispatchers and configuration folders
used to group dispatchers.

Steps
1. In IBM Cognos Administration, on the Configuration tab, click Dispatchers and Services.

2. Click the dispatcher you want.

3. Next to ContentManagerService, click the set properties button.

4. Click the Settings tab.

5. In the Value column, click Edit.

6. Select the Override the settings acquired from the parent entry check box.

7. In the Parameter column that appears, type the following in uppercase:

CM.DEPLOYMENTINCLUDECONFIGURATION

8. In the Value column, type true

9. Click OK to finish.

Import to the Test Environment

You import entries from the deployment archive into the target environment. To import the entries,
you create an import deployment specification.
When you import, you select from entries that were exported. You can either accept the default
options set during the export, or change them. You can only select options that were included in
the deployment archive during the export.
If you do a partial deployment of specific public folders and directory content, the import wizard
shows whether packages and folders already exist in the target environment and the date and time
they were last modified. You can use this information to help you decide how to resolve conflicts.
When you redeploy, the wizard also shows whether the packages and folders were in the original
deployment.

Steps to Import Deployment Specification

1. In the target environment, in IBM Cognos Administration, on the Configuration tab, click
Content Administration.

2. On the toolbar, click the new import button .

The New Import wizard appears.

3. In the Deployment archive box, click the deployment archive that you want to import.

4. If the deployment archive is encrypted, type the password, and then click OK.

5. Click Next.

58 PowerPlay®
 Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

6. Type a unique name and an optional description and screen tip for the deployment specification,
select the folder where you want to save it, and then click Next.

7. Select the content that you want to include in the import.

Tip: To ensure that the required target package or folder exists in the target content store, click

the edit button next to the package, and check the location. If you want, you can change
the target location now.

8. Select the options you want, along with your conflict resolution choice for the options that you
select.

9. In the Specify the general options page, select whether to include access permissions and who
should own the entries after they are imported in the target environment.

10. Specify the Recording Level for the deployment history.

11. Click Next.

The summary information appears.

12. Review the summary information, and click Next.

13. Determine how you want to run the import by selecting the action you want.

After you run the import, you can test the deployment.

Steps to Run an Import

1. In the Actions column, click the run with options button .

2. Click Now to run the import immediately, or click Later, and enter the time that you want the
import to run.

3. If you want to upgrade the report specifications, click Upgrade all report specifications to the
latest version.
You can also use the Schedule Management tool to schedule a task to run on a recurring basis,
and view a list of scheduled tasks.

You can now test the deployment.

Test the Deployed Content

After you import the packages from the deployment archive, you can check that all the entries were
deployed successfully in the target environment.
You can test your deployment by doing the following:
❑ Review the run history for a deployment.

❑ Ensure that the correct packages and folders were imported, along with their contents.

❑ Run imported reports and report views.

For more information, see the online help in the IBM Cognos Administration console.

Installation and Configuration Guide 59

Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

Recommendation - Test the Upgraded Content

After you import the packages from the deployment archive, you can check that all the entries were
deployed successfully in the target environment.
We recommend that you test your upgraded content by doing the following:
❑ Test your reports, as follows:
● In PowerPlay Studio, validate each report and note whether the validation was successful.

You can download Upgrade Manager from the Cognos Software Services Web site to help you
test. Upgrade Manager is a verification tool that checks that your reports run and produce the
same results in the new environment.

❑ Test models and PowerCubes in Cognos 8 Transformer, if required:

● Open models with the appropriate security options and save them.

● Test PowerCubes.

❑ Test models in Framework Manager.

You can use the same models and projects in Framework Manager for IBM Cognos 8 that you
used with the earlier version. When upgrading models, the validation process produces errors
for every model. To upgrade a project, open and save it in the new version of Framework
Manager. For more information, see the Framework Manager User Guide.

❑ Repair or exclude reports and models that do not operate correctly.

❑ Test the repaired reports and models by running them again on the test system.
Troubleshoot any issues, and contact Cognos Software Services about unresolved upgrade
issues.

❑ Revise the upgrade plan to include adaptations that you made during the trial upgrade.

For more information, see the online help in the IBM Cognos Administration console.

Moving to the Production Environment

When all issues that you discovered during the trial upgrade are resolved, you are ready to begin
the full upgrade in your production environment. Your upgrade plan will provide the details for
each step of the full upgrade.
The following diagram shows the high level steps in the process of moving upgraded applications
to a production environment. After preparing the production environment and backing up data
and configuration files, you can uninstall the older version of the software, and install the new
version in the same location. Then, you can deploy the content from your test environment.
6
Move to production environment

Prepare Back up Install new Deploy from

Uninstall test
environment files version
environment

60 PowerPlay®
 Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

If you want to leverage your existing resources and upgrade in the same directory, you must first
back up your configuration data, ensure that Framework Manager projects are backed up and
checked into a source control system (if applicable), and uninstall the older version of Cognos 8.
Use the following checklist to guide you through the process of moving to a production environment:
❑ Prepare the production environment.
● Back up files and data.
You may have modified files other than those in the configuration folder. We strongly
recommended that you back up the entire installation directory.
When you back up the configuration data, store it in a secure directory. You must protect
the directory from unauthorized or inappropriate access.

● Install your new release system in the production environment.

If you install the new software from the test environment to the same location as the
existing software, you must first uninstall the existing software.

● Configure the system.

❑ Manually configure customization.

● If you manually edited any configuration files, the changes will be overwritten during the
upgrade. You must reapply the changes. You should keep a record of any customizations
to ensure that they can be reapplied after upgrading. You should also back up these files
so that you can restore the original version if necessary.

● The IBM Cognos 8 presentation service supports automatic upgrade of some system.xml
files. If you made many customization changes to system.xml files, you can use this automatic
upgrade feature instead of reapplying the changes manually after upgrading. The system.xml
files are overwritten during the installation of IBM Cognos 8. Therefore, you must back
up the customized versions of these files and then copy them to the directory after
upgrading IBM Cognos 8. The automatic upgrade will be applied when you start the IBM
Cognos 8 service.

● The system.xml files for which automatic upgrade is supported are in the following direct-
ories:
c8_location/templates/ps
c8_location/templates/ps/portal
c8_location/templates/ps/qs

● Note: The recommended method to upgrade customized files is to manually reapply changes
after the new software is installed. Use automatic upgrade of system.xml files only when
you have made a large number of customizations to these files.

❑ Deploy the application on the production system.

When upgrading, you can export the entire content store to a deployment archive and then
import the deployment archive into IBM Cognos 8 after upgrading the software.

Installation and Configuration Guide 61

Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

❑ Deploy the reports and models from the test system to the production system.

Upgrading from an Earlier Version of IBM Cognos 8 PowerPlay

You must upgrade the software to move from an earlier version of IBM Cognos 8 PowerPlay to a
new version of IBM Cognos 8 PowerPlay. You must upgrade all components. Components from
different versions are not compatible. If you are using IBM Cognos Series 7 PowerCubes as a data
source, it is not necessary to upgrade Transformer unless you want to use the features of the new
version of Transformer. PowerCubes that are built using IBM Cognos Series 7.3 Transformer (or
later) and IBM Cognos 8.3 Transformer (or later) are both supported with IBM Cognos 8 reporting
and metrics.
You can run different versions of the software on your computer at the same time, provided that
you install them in different directories and configure each to use a different content store and a
different set of ports and URLs for each version.
Before you begin upgrading, you must plan your upgrade strategy (p. 48). The strategy depends
on the data that you want to use and any customizing that you have done with your existing con-
figuration.
After upgrading to IBM Cognos 8 using existing data, additional configuration may be required if
you want to use new features. For information about new features in IBM Cognos 8, see IBM
Cognos 8 New Features.

Upgrade from an Earlier Version of IBM Cognos 8 PowerPlay

You can upgrade IBM Cognos 8 PowerPlay in the same directory as an earlier version or in a dif-
ferent directory, depending on where you are in the process. For example, if you are setting up your
test environment, you install in a new directory. If you have finished testing your applications and
want to upgrade the software in your production environment, you install in the same directory.
If you want to upgrade IBM Cognos 8 in the same directory, you must first back up your data,
ensure that Framework Manager projects are not checked into a source control system, and uninstall
the older version of IBM Cognos 8. For complete instructions, see the steps to install in the same
directory.
If you are installing on a new computer, see the steps to install in a new directory.
When you back up the configuration data, you store it in a secure directory. The directory must be
protected from unauthorized or inappropriate access.
An alternative method of upgrading is to export the entire content store to a deployment archive
and then import the deployment archive into IBM Cognos 8 after the upgrade. For more information
about deployment, see the Administration and Security Guide. A deployment upgrade is required
if you want to change the type of database that you use for the content store. If you use the
deployment upgrade method, only the steps for exporting and restoring the configuration data are
different. All other steps are the same as documented in this section.
When you upgrade, the report administrator will no longer have access to the Content Administration
tool. The report administrator will not be able to create deployment definitions in IBM Cognos 8.

62 PowerPlay®
 Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

Customized IBM Cognos 8 Files

If you manually edited any configuration files, the changes will be overwritten during the upgrade.
You must reapply the changes. You should keep a record of any customizations to ensure that they
can be reapplied after upgrading. You should also back up these files so that the original version
can be restored if necessary.
You may have modified files other than those in the configuration folder. If so, you should also
back up the additional files before upgrading.
The IBM Cognos 8 presentation service supports automatic upgrade of some system.xml files. If
you made many customization changes to system.xml files, you can use this automatic upgrade
feature instead of reapplying the changes manually after upgrading. The system.xml files are over-
written during the installation of IBM Cognos 8. Therefore, you must back up the customized ver-
sions of these files and then copy them to the directory after upgrading IBM Cognos 8. The automatic
upgrade will be applied when you start the IBM Cognos 8 service.
The system.xml files for which automatic upgrade is supported are in the following directories:
● c8_location/templates/ps

● c8_location/templates/ps/portal

● c8_location/templates/ps/qs

Note: The recommended method to upgrade customized files is to manually reapply changes after
the new software is installed. Automatic upgrade of system.xml files is to be used only when you
have made a large number of customizations to these files.

Steps to Install in the Same Directory

1. Using your database tools, back up your existing content store database.
For information on how to do this, see the documentation for your database.

2. Back up the following files to a secure location:

● cogstartup.xml and coglocale.xml in the c8_location/configuration directory

● server.xml in the c8_location/tomcat4.1.27/conf directory

● system.xml in the appropriate directory, if required

Ensure that you note the directory path. For example,

c8_location/templates/ps

3. In IBM Cognos Configuration, export the configuration data to the same secure location.
To make the data usable for upgrading, name the file cogstartup.xml.

Important: Because the exported crnstartup.xml file contains unencrypted passwords, ensure
that the location is secure.

4. Back up any manually edited files in the c8_location/configuration and other directories to a
secure location.

5. Stop all IBM Cognos services.

Installation and Configuration Guide 63

Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

6. Uninstall IBM Cognos 8 PowerPlay from every IBM Cognos 8 PowerPlay computer.

7. Install the newer version of IBM Cognos 8 PowerPlay in the same directory that you used for
IBM Cognos 8 PowerPlay on every computer.

8. For files that you manually edited in earlier versions of IBM Cognos 8, edit the same files in
the c8_location directory and reapply the changes that you made to the original customized
files.
Do not copy the customized files from the backup location to the c8_location directories. The
earlier versions of these files may not be compatible.

9. If you use Oracle for a data source, import source, logging database, or the content store
database, delete the classes12.jar file from the c8_location\webapps\p2pd\WEB-INF\lib directory.
Older versions of IBM Cognos 8 used this file, which conflicts with the ojdbc14.jar (or, for
Oracle 11g, the ojdbc5.jar) file that is used in newer versions.

10. In IBM Cognos Configuration, review the configuration, and then save it.
When you save the configuration, an upgrade dialog box appears and asks if you want to
upgrade your report specifications. The default setting is to not upgrade report specifications.

Important: Do not upgrade your report specifications if you have SDK applications that create,
modify, or save report specifications. You must first update your SDK applications to comply
with the IBM Cognos 8 report specifications schema. Otherwise, your SDK applications may
not be able to access the upgraded report specifications. In addition, do not save your reports
until the SDK applications have been updated. For information about upgrading report specific-
ations, see the IBM Cognos 8 SDK Developer Guide.

11. Start IBM Cognos 8.

IBM Cognos 8 automatically upgrades the content store. System.xml files are upgraded, if
required, to an IBM Cognos 8 compatible version.

12. If you use pages created in earlier versions of IBM Cognos 8, you may need to reconfigure the
following properties:
● Title

● Open action links going outside a portal

For more information, see the Administration and Security Guide.

13. If you use SAP Enterprise Portal, upgrade your master iView.
Old SAP iViews will not work with the new Portal Services producer component. For informa-
tion, see the topic about deploying Cognos Portlets to SAP Enterprise Portal in the Administra-
tion and Security Guide.

Steps to Install in a New Directory

1. Using your database tools, copy your existing content store database into a new content store
database.
For information on how to do this, see the documentation for your database.

64 PowerPlay®
 Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

2. Back up the following files to a secure location:

● cogstartup.xml and coglocale.xml in the c8_location/configuration directory

● server.xml in the c8_location/tomcat4.1.27/conf directory

● system.xml in the appropriate directory, if required

Ensure that you note the directory path. For example,
c8_location/templates/ps

● In IBM Cognos Configuration, export the configuration data to the same secure location.
To make the data usable for upgrading, name the file cogstartup.xml.

Important: Because the exported cogstartup.xml file contains unencrypted passwords,

ensure that the location is secure.

● Back up any manually edited files in the c8_location/configuration and other directories
to a secure location.

3. Install IBM Cognos 8 in a new directory.

4. Copy the .xml files from the secure backup location to the following directory:
● Copy cogstartup.xml and coglocale.xml to c8_location/configuration.

● Copy server.xml to c8_location/tomcat4.1.27/conf.

● Copy system.xml to the same directory in the new location as it was in the earlier version,
if required.
For example,
c8_location/templates/ps

If you are prompted to overwrite existing files, click Yes.

5. For files that you manually edited, edit the same files in the c8_location directory and reapply
the changes that you made to the original customized files.
Do not copy the customized files from the backup location to the c8_location directories. The
earlier versions of these files may not be compatible with IBM Cognos 8.

6. Configure new Web server aliases.

7. In IBM Cognos Configuration, configure IBM Cognos 8 to point to the new content store,
configure new ports and URLs, use a different cookie path, and then save the configuration.
Ensure that the port numbers and service name for this installation are different from those
used for earlier versions so that there are no conflicts.
Ensure that security authentication settings are not changed. For example, the namespaces must
be the same for policies, users, roles, and groups to work correctly.
When you save the configuration, an upgrade dialog box appears and asks if you want to
upgrade your report specifications. The default setting is to not upgrade report specifications.

Installation and Configuration Guide 65

Chapter 5: Upgrading to IBM Cognos 8 PowerPlay

Important: Do not upgrade your report specifications if you have SDK applications that create,
modify, or save report specifications. You must first update your SDK applications to comply
with the IBM Cognos 8 report specifications schema. Otherwise, your SDK applications may
not be able to access the upgraded report specifications. In addition, do not save your reports
until the SDK applications have been updated. For information about upgrading report specific-
ations, see the IBM Cognos 8 SDK Developer Guide.

8. Start IBM Cognos 8.

IBM Cognos 8 automatically upgrades the new content store. System.xml files are upgraded,
if required, to an IBM Cognos 8 compatible version.

9. Open the Administration portal, and unregister the dispatchers that are used with earlier versions
of IBM Cognos 8.
When you open the Administration portal in IBM Cognos 8, you may see the dispatchers that
are registered for both versions.
For more information, see the Administration and Security Guide.

10. If you use pages created in ReportNet, you may need to reconfigure the following properties:
● Title

● Open action links going outside a portal

For more information, see the Administration and Security Guide.

11. If you use SAP Enterprise Portal, upgrade your master iView.
Old SAP iViews will not work with the new Portal Services producer component. For informa-
tion, see the topic about deploying Cognos Portlets to SAP Enterprise Portal in the Administra-
tion and Security Guide.

12. When you are ready to uninstall the previous version of IBM Cognos 8, do the following:
● Stop the IBM Cognos 8 service.

● Uninstall IBM Cognos 8 from all computers.

For instructions, see "Uninstalling IBM Cognos 8" (p. 88).

When you complete the upgrade tasks, IBM Cognos 8 is fully configured except for new properties
and features, and scorecarding features.
If you use Chinese, Japanese, or Korean characters, you may notice differences in some characters
after upgrading. For more information, see the Troubleshooting section of the Administration and
Security Guide.
If you use a DB2 database for the content store, you can tune the database to take advantage of
DB2 features. For more information, see the Architecture and Deployment Guide.
To ensure the security and integrity of IBM Cognos 8, it is important to protect the installation
directory from unauthorized or inappropriate access.

66 PowerPlay®
Chapter 6: Installing and Configuring IBM
Cognos 8 PowerPlay on One Computer

You can install IBM Cognos 8 PowerPlay on a single server when you are setting up a test or eval-
uation environment, or for small production environments. To use IBM Cognos 8 PowerPlay, you
must install all components that are selected by default in the installation wizard.
IBM Cognos 8 migration components are included with the IBM Cognos 8 PowerPlay installation.
These components support the migration of PowerPlay content from IBM Cognos Series 7 to IBM
Cognos 8. Also, if you install IBM Cognos 8 PowerPlay with IBM Cognos 8, the migration com-
ponents support the option to open a PowerPlay Studio report in Analysis Studio or Report Studio.
IBM Cognos Series 7 Migration Components are available with IBM Cognos 8 PowerPlay. To
migrate content from IBM Cognos Series 7 PowerPlay to IBM Cognos 8 PowerPlay, you must install
the IBM Cognos Series 7 migration components on the computer where IBM Cognos Series 7
PowerPlay Enterprise Server is installed. If you want to migrate PowerPlay content from Upfront,
you must also install the IBM Cognos Series 7 migration components on the computer where Upfront
is installed.
We recommend that you do an interactive installation (p. 68).
This section also includes information about uninstalling IBM Cognos 8. For more information,
see "Uninstalling IBM Cognos 8" (p. 88).
You can also install IBM Cognos 8 components on different computers. For more information, see
"Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Install-
ation" (p. 93).
If you want to automate the installation and configuration process, you can set up an unattended
installation and configuration (p. 283).
If you plan to install two or more IBM Cognos 8 components on the same computer, we strongly
recommend that you install them in the same installation location to avoid conflicts among ports
and other default settings.
If modelers want to create relational packages or mixed-source packages to support Analysis Studio,
Report Studio, or Query Studio, you require the IBM Cognos 8 modeling tool, Framework Manager.
If modelers want to build PowerCubes, you require IBM Cognos 8 Transformer. If modelers want
to build PowerCubes from relational sources, you require both Framework Manager and IBM
Cognos 8 Transformer. For information about installing Framework Manager and IBM Cognos 8
Transformer, see the IBM Cognos 8 Business Intelligence Installation and Configuration Guide
that is provided with your modeling components.
If you are installing IBM Cognos 8 in an application server environment, you must be aware of the
installation requirements. For more information, see "Configuring IBM Cognos 8 for an Application
Server" (p. 255).
If you want to use the samples, you must install them from the IBM Cognos 8 Business Intelligence
Samples CD. For more information, see "Install the IBM Cognos 8 Samples" (p. 138).

Installation and Configuration Guide 67

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

To follow these instructions, your Web server must be installed on the computer where you install
IBM Cognos 8 PowerPlay.
Use the following checklist to guide you through the installation tasks:
❑ If you want to use Report Studio, Analysis Studio, or Query Studio, install IBM Cognos 8
Business Intelligence Server.
For instructions, see the IBM Cognos 8 Business Intelligence Installation and Configuration
Guide.

❑ Install IBM Cognos 8 PowerPlay.

❑ Update the Java environment.

❑ Set up database connectivity for the content store database.

❑ Start IBM Cognos Configuration.

❑ Set the database connection properties for the content store.

❑ Configure a mail server account.

❑ Configure environment properties.

❑ Configure an IBM Cognos Series 7 namespace in IBM Cognos 8, if required.

❑ Configure the Web server.

❑ Start the services.

❑ Test the installation.

❑ Install and configure migration components on IBM Series 7 computers.

After you complete the initial configuration of IBM Cognos 8 PowerPlay, you can install IBM
Cognos 8 PowerPlay Client "Installing and Configuring Client and Modeling Components" (p. 133).
You can also customize the components for use in your environment by changing other settings in
IBM Cognos Configuration (p. 187).

PowerPlay Administration
To change runtime settings for IBM Cognos 8 PowerPlay, use IBM Cognos Administration, which
is accessed through the IBM Cognos 8 portal. For example, you can enable or disable dispatchers
and services, or set up permissions for users, groups, and roles. For more information, see the
Administration and Security Guide. You can also configure options for migration and for PowerPlay
reports and cubes. For more information, see the Migration and Administration Guide.

Recommendation - Install Server Components in Interactive

Mode
For a complete installation, you must install components on your server and then configure them
to work in your environment.

68 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

Typically, you run the IBM Cognos installation and configuration programs in interactive mode.
This means that in a graphical user interface (GUI) the installer prompts you to provide information,
and the configuration tool enables you to change default settings.
You can choose to install server components in silent mode.

Silent Mode
You can automate the installation of components using response files and running the installation
program in silent mode.
For information about silent mode installations, see "Setting Up an Unattended Installation and
Configuration" (p. 283).
You can automate the configuration of components by exporting the configuration settings from
one computer to another as long as the installed components are the same. We recommend that
you run IBM Cognos Configuration in interactive mode the first time.
The other option is to edit the cogstartup.xml file, using settings that apply to your environment,
and then running the configuration tool in silent mode.

Interactive Mode
Unless you intend to complete a silent-mode installation, we recommend that you install the software
from an X Window System workstation, an X terminal, or a PC or other system with X server
software installed.
To run an interactive-mode installation, the console attached to your computer must support a
Java-based graphical user interface.

Install IBM Cognos 8 PowerPlay

Use the installation wizard to select the server components that you want to install and the location
on your computer where you want to install them. Only the components that you choose to install
are copied from the CD to your computer.
If you are upgrading from a previous release of IBM Cognos PowerPlay, you must use the upgrading
steps. For information, see "Upgrading to IBM Cognos 8 PowerPlay" (p. 47).
If you want to use Cognos Content Database as your content store, you must select it in the
installation wizard. If you are installing components on several computers, you need to only install
one Cognos Content Database. If you install Cognos Content Database on the same computer as
Content Manager, and you later decide to use another database for your content store, you must
uninstall Cognos Content Database (p. 90).
On UNIX, to run graphical-mode installation, the console attached to your UNIX computer must
support a Java-based graphical user interface.
On UNIX, IBM Cognos 8 respects the file mode creation mask (umask) of the account running the
installation program. This affects only the installation directories. It does not affect the file permis-
sions within the directories. However, run-time generated files, such as logs, respect the mask. We
recommend umask 022 on the installation directory.

Installation and Configuration Guide 69

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

On Windows, ensure that you have administrator privileges for the Windows computer you are
installing on. Also ensure that your computer has a TEMP system variable that points to the directory
where you want to store temporary files. During installation, files from the CD are temporarily
copied to this directory. Ensure that the directory has sufficient space (1 GB.
If you will be using PowerCubes that are secured against an IBM Cognos Series 7 namespace, you
must install Content Manager on a computer that supports IBM Cognos Series 7.
If you are installing IBM Cognos 8 PowerPlay with IBM Cognos 8 Business Intelligence Server, we
recommend that IBM Cognos 8 Business Intelligence Server be installed and configured first. Both
products must be the same version. For more information, see "IBM Cognos Products That Inter-
operate with IBM Cognos 8 PowerPlay" (p. 26).
To ensure that reports print properly on Windows, Adobe Acrobat requires that you configure at
least one printer on the operating system where Application Tier Components are installed. All
reports, regardless of the print format that you choose, are sent as temporary PDF files to Adobe
Reader for printing.

Steps for UNIX and Linux

1. If you are installing to a directory with other IBM Cognos 8 components, stop the IBM Cognos 8
service.

2. Set the JAVA_HOME environment variable to point to the installation location of your Java
Runtime Environment (JRE).
An example of the installation location of a Java Runtime Environment is /directory/java/java_ver-
sion/jre.
IBM Cognos 8 requires a JVM, such as IBM Java, to run on Linux.

3. On HP-UX, set the _M_ARENA_OPTS environment variable as follows:

_M_ARENA_OPTS 1:4
This increases the memory allocation for HP-UX to more closely match that of other UNIX
platforms.

4. On AIX, if you are using a servlet gateway, set the AIXTHREAD_SCOPE environment variable
as follows:

AIXTHREAD_SCOPE=S
This sets the contention scope for user threads to system-wide, which supports more efficient
scheduling of user threads.

5. Mount the CD for your IBM Cognos product using Rock Ridge file extensions.

Important: To mount the IBM Cognos CD on HP-UX, do the following:

● Add the pfs_mount directory in your path.
For example,

PATH=/usr/sbin/:$PATH

export PATH

70 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

● To start the required NFS daemons and run the daemons in the background, type bg
pfs_mountd and then type bg pfsd

● To mount the drive, type

pfs_mount -t rrip <device><mount_dir> -o xlat=unix

For example,

pfs_mount /dev/dsk/c0t2d0 /cdrom -o xlat=unix

You can now install or copy files as a non-root user using an IBM Cognos CD from this
drive.

● When the installation is complete, type pfs_umount /cdrom and kill the pfsd and pfs_mountd
daemons to unmount the CD.

6. To start the installation wizard, go to the operating system directory on the CD or in the dir-
ectory where the installation files were downloaded and extracted, and then type

./issetup

Note: When you use the issetup command with XWindows, Japanese characters in messages
and log files may be corrupted. When installing in Japanese on UNIX or Linux, first set envir-
onment variables LANG=C and LC_ALL=C (where C is the language code, for example
ja_JP.PCK on Solaris), and then start the installation wizard.
If you do not use XWindows, run an unattended installation (p. 283).

7. Select the language to use for the installation.

The language that you select determines the language of the user interface. You can select the
language of the user interface for the product to any of the installed languages after installation.

8. In the Component Selection page, do not change the components that are selected by default.
If you want to use the content store database that is provided with IBM Cognos 8, also select
Cognos Content Database.
To support migration, after you complete the installation on the IBM Cognos 8 computer,
install the IBM Cognos Series 7 migration components.

9. In the Multiple Installation Locations page, specify the IBM Cognos 8 location.
If you are installing on a computer that contains other IBM Cognos 8 PowerPlay components,
install in the same directory.
Install IBM Cognos 8 PowerPlay components in a directory that contains only ASCII characters
in the path name. Some UNIX and Linux Web servers do not support non-ASCII characters in
directory names.

10. Follow the directions in the Shortcut Folder and Installation Summary pages.

11. In the Finish page, do not select any options and then click Finish.

12. Append the c8_location/bin directory to the appropriate library path environment variable:
● For AIX, LIBPATH

Installation and Configuration Guide 71

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

● For HP-UX, SHLIB_PATH

● For Solaris, LD_LIBRARY_PATH

● For Linux, LD_LIBRARY_PATH

13. On Linux, set the PRINTER environment variable to the name of your printer.

To ensure the security and integrity of IBM Cognos 8, it is important to protect the installation
directory from unauthorized or inappropriate access.
If you want users to see product documentation in a language other than English, you must install
the Supplementary Languages Documentation in the same location as the Gateway components.
For more information, see "Install Translated Product Documentation" (p. 145).

Steps for Windows

1. If you are installing to a directory with other IBM Cognos 8 components, stop the IBM Cognos 8
service.

2. Insert the CD for your IBM Cognos product.

The Welcome page of the installation wizard should appear.

If no Welcome page appears, on the CD, double-click the issetup.exe file.

3. Select the language to use for the installation.

The language that you select determines the language of the user interface. You can select the
language of the user interface for the product to any of the installed languages after installation.

4. Accept the License Agreement and click Next.

5. In the Component Selection page, do not change the components that are selected by default.
If you want to use the content store database that is provided with IBM Cognos 8, also select
Cognos Content Database.

6. In the Multiple Installation Locations page, specify the IBM Cognos 8 location.
If you are installing on a computer that contains other IBM Cognos 8 PowerPlay components,
install in the same directory.
If you do not use the default installation directory, use a directory name that contains only
ASCII characters. Some Web servers do not support non-ASCII characters in directory names.

7. Follow the directions in the Shortcut Folder and Installation Summary pages.

8. In the Finish page, click Finish.

To ensure the security and integrity of IBM Cognos 8, it is important to protect the installation
directory from unauthorized or inappropriate access.
If you want users to see product documentation in a language other than English, you must install
the Supplementary Languages Documentation in the same location as the Gateway components.
For more information, see "Install Translated Product Documentation" (p. 145).

72 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

Update the Java Environment

IBM Cognos 8 cryptographic services use a .jar (Java Archive) file, named bcprov-jdknn-nnn.jar,
that must be located in your Java Runtime Environment (JRE). This file provides additional
encryption and decryption routines that are not supplied as part of a default JVM installation. To
ensure security, the encryption file must be loaded by the JVM using the java extensions directory.
If you want to use your own JRE and have JAVA_HOME set to that location on Windows or if
you are installing on UNIX, you may have to update the Java environment for the cryptographic
services.
On Windows, you can set JAVA_HOME as a system variable or a user variable. If you set it as a
system variable, it may be necessary to restart your computer for it to take effect. If you set it as a
user variable, set it so that the environment in which Tomcat is running can access it.
If you do not have a JAVA_HOME variable already set on Windows or if JAVA_HOME points to
a Java version that is not valid for IBM Cognos 8, the JRE files provided with the installation will
be used, and you do not have to update any files in your environment.

Steps
1. Ensure that the JAVA_HOME environment variable is set to the JRE location.
For example, to set JAVA_HOME to the JRE files provided with the installation, the path is
c8_location/bin/jre/version.

2. Copy the bcprov-jdknn-nnn.jar file from the c8_location/bin/jre/version/lib/ext directory to the

Java_location/jre/lib/ext directory.

JDBC Driver Options for Using DB2 Database as a Content Store

IBM Cognos 8 uses JDBC connectivity to access the database used for the content store.
If you use DB2 on Windows, Linux or UNIX as your content store you must choose whether to
use the type 2 or type 4 JDBC driver depending on how you want to connect to the content store.
If you are using a DB2 database on z/OS for the content store, you must use type 4 JDBC
connectivity.
You specify the driver type to use in IBM Cognos Configuration.

Configuration Options for the Universal Driver

DB2 introduced a universal JDBC driver that contains both type 2 and type 4 JDBC driver support.
The universal driver, db2jcc.jar, replaces the deprecated type 2 JDBC driver, db2java.zip.
If you are upgrading, you can continue to use type 2 JDBC connectivity with no configuration
change required. If you want to use the type 4 JDBC connectivity, you must change your configur-
ation to include the host name and port number of the database server.
For information about configuration requirements, "Set Database Connection Properties for the
Content Store" (p. 76).

Installation and Configuration Guide 73

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

For both type 2 and type 4 JDBC connectivity, however, you must copy the new universal driver,
db2jcc.jar, and the accompanying license file, db2jcc_license_*.jar, to your IBM Cognos 8 installation
location.
For more information, see "Set Up Database Connectivity for the Content Store Database" (p. 74).

Using the Type 2 JDBC Driver

Type 2 JDBC drivers are comprised of a native-API component and a Java component.
The connection to the DB2 database occurs through the DB2 CLI libraries, which comprise the
native component that communicates with the database server.
Because type 2 JDBC drivers require common client code and rely on the native code of the product,
a DB2 product must be installed to use this driver. For example, a DB2 client must be installed on
the computer where you have Content Manager installed.

Using the Type 4 JDBC Driver

Type 4 JDBC drivers are pure Java drivers which provide direct access to DB2 database features
through network communication.
The type 4 driver is considered an independent product. It does not require the DB2 product to be
installed. For example, you do not need to install the DB2 client on the computer where you have
Content Manager installed.

Set Up Database Connectivity for the Content Store Database

If you are using a database other than Cognos Content Database as the content store, you may
have to install database client software, or JDBC drivers, or both, on each computer where you
install Content Manager. Doing this allows Content Manager to access the content store database.

Steps for DB2

1. If you are using type 2 JDBC connectivity, install the DB2 client software on the Content
Manager computers.
If you use type 4 JDBC connectivity for DB2, you are not required to install the DB2 client
software where Content Manager is installed. If you are using a DB2 database on z/OS for the
content store, you must use type 4 JDBC connectivity.
For more information about the differences between type 2 and type 4 drivers, see "JDBC
Driver Options for Using DB2 Database as a Content Store" (p. 73).

2. If you are using type 2 JDBC connectivity, and the content store is on a different computer than
Content Manager, configure a database alias to the content store.
On Windows, run the DB2 Client Configuration Assistant.
On UNIX or Linux, use the DB2 command line interface.
If the content store database and Content Manager are on the same computer, the content store
name automatically becomes the alias.

74 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

When you configure the Content Manager computers, ensure that they are all configured to
use the same content store.

3. On Windows, stop the DB2 services and the HTML Search Server.

4. Copy the following files from DB2_installation/sqllib/java directory to the c8_location/webapps/

p2pd/WEB-INF/lib directory.
● the universal driver file, db2jcc.jar

● the license file

for DB2 on Linux, UNIX, or Windows, db2jcc_license_cu.jar
for DB2 on z/OS, db2jcc_license_cisuz.jar

If you are connecting to DB2 on z/OS, use the driver version from Linux, UNIX, or Windows
version 9.1 fix pack 5 or version 9.5 fix pack 2.

Tip: To check the driver version, run the following command

java -cp path\db2jcc.jar com.ibm.db2.jcc.DB2Jjcc -version

5. On Windows, restart the DB2 services and the HTML Search Server.

6. On UNIX, if you are using type 2 JDBC connectivity, ensure that the 32-bit DB2 libraries are
in the library search path, which is usually the $DB2DIR/lib directory or the $DB2DIR/lib32
directory.

7. Repeat this entire procedure on the IBM Cognos 8 computers where Content Manager is
installed or where notification is sent to a DB2 database.

Steps for Oracle

1. On the computer where the Oracle client is installed, go to the ORACLE_HOME/jdbc/lib
directory.

2. Copy the appropriate JAR file to the c8_location/webapps/p2pd/WEB-INF/lib directory on

computers where Content Manager is installed and where notification is sent to an Oracle
database.
● If you use Java 1.4, copy the ojdbc14.jar file

● If you use Java 1.5, copy the ojdbc5.jar file

If the directory contains the classes12.jar file, delete it before installing the ojdbc14.jar or
ojdbc5.jar file.
The driver is available from an Oracle client or server install, and it can also be downloaded
from the Oracle technology Web site (http://www.oracle.com/technology).

Steps for Sybase

1. On the computer where Sybase is installed, go to the Sybase_location/jConnect-5_5/classes
directory.

Installation and Configuration Guide 75

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

2. Copy the jconn2.jar file to the c8_location/webapps/p2pd/WEB-INF/lib directory on every

computer where Content Manager is installed and where notification is sent to a Sybase database.

Start IBM Cognos Configuration

Use the configuration tool, IBM Cognos Configuration, to configure IBM Cognos 8, or to start and
stop IBM Cognos services.
On UNIX or Linux, do not start IBM Cognos Configuration in the last page of the installation
wizard: additional setup is required before you can configure IBM Cognos 8. For example, you
must update your Java environment. On Windows, you can start IBM Cognos Configuration in
the last page of the installation wizard only if additional setup is not required. For example, if you
use a database server other than Microsoft SQL or Cognos Content Database for the content store,
we recommend that you copy the JDBC drivers to the appropriate location before you start the
configuration tool.

Step to start IBM Cognos Configuration on a Windows computer

● From the Start menu, click Programs, IBM Cognos 8, IBM Cognos Configuration

Step to start IBM Cognos Configuration on a UNIX or Linux computer

● Go to the c8_location/bin directory and then type

./cogconfig.sh

Set Database Connection Properties for the Content Store

For all installations not using Cognos Content Database, you must specify the database server
information to ensure that Content Manager can connect to the database you use for the content
store. Content Manager uses the database logon to access the content store. After you set the
database connection properties, you can test the connection between Content Manager and the
content store.
Ensure that you used one of the supported database servers to create the content store.

Steps for DB2

1. In the location where you installed Content Manager, start IBM Cognos Configuration.

2. In the Explorer window, under Data Access, Content Manager, click Content Store.

3. In the Properties window, for the Database name property, type the name of the database or
the database alias.

4. Change the logon credentials to specify a valid user ID and password:

● Click the Value box next to the User ID and password property and then click the edit
button when it appears.

● Type the appropriate values and click OK.

76 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

5. To use type 4 JDBC connectivity, for the Database server and password property, type a value,
using host:port syntax.
If you leave this property blank, type 2 JDBC connectivity is used.
For more information about the differences between the driver types, see "JDBC Driver Options
for Using DB2 Database as a Content Store" (p. 73).

6. From the File menu, click Save.

The logon credentials are immediately encrypted.

7. Test the connection between Content Manager and the content store.

Tip: In the Explorer window, right-click the new database and click Test.
Content Manager connects to the database, checks the database permissions, and creates and
populates a table. The table is not deleted and is used each time that the test is repeated.

Steps for Microsoft SQL Server, Oracle, and Sybase

1. On the computer where you installed Content Manager, start IBM Cognos Configuration.

2. In the Explorer window, under Data Access, Content Manager, right-click Content Store and
click Delete.
This deletes the default resource. Content Manager must be configured to access only one
content store.

3. Right-click Content Manager, and then click New resource, Database.

4. In the Name box, type a name for the resource.

5. In the Type box, select the type of database and click OK.
If you are upgrading and want to use an existing content store, ensure that you select the type
of database you use for the older version.
If you installed more than one version of IBM Cognos 8, you must use a different content store
for each version. When a content store is used by a new version of IBM Cognos 8, it cannot
be used by an older version.

Tip: If you want to use Oracle Net8 keyword-value pair to manage the database connection,
select Oracle database (Advanced).

6. In the Properties window, provide values depending on your database type:

● If you use a Microsoft SQL Server database, type the appropriate values for the Database
server with port number or instance name and Database name properties.
For a Microsoft SQL Server database, you can choose to use a port number, such as 1433,
or a named instance as the value for the Database server with port number or instance
name property.
To connect to a named instance, you must specify the instance name as a JDBC URL
property or a data source property. For example, you can type localhost\instance1. If no
instance name property is specified, a connection to the default instance is created.

Installation and Configuration Guide 77

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

Note that the properties specified for the named instance, along with the user ID and
password, and database name, are used to create a JDBC URL. Here is an example:
jdbc:JSQLConnect://localhost\\instance1/user=sa/more properties as required

● If you use an Oracle database, type the appropriate values for the Database server and port
number and Service name properties.

● If you use an advanced Oracle database, for the Database specifier property, type the Oracle
Net8 keyword-value pair for the connection.
Here is an example:
(description=(address=(host=myhost)(protocol=tcp)(port=1521)(connect_data=(sid=(orcl)))))
When you select the advanced Oracle database, IBM Cognos 8 uses enterprise-oriented
Oracle features to select a listener, switch to another listener if the first listener fails, auto-
matically reconnect to the database if the connection fails, balance connection requests
among listeners, and balance connection requests among dispatchers.

● If you use a Sybase database, type the appropriate values for the Database server and port
number and Database name properties.

7. If you want to change the logon credentials, specify a user ID and password:

● Click the Value box next to the User ID and password property and then click the edit
button when it appears.

● Type the appropriate values and click OK.

8. From the File menu, click Save.

The logon credentials are immediately encrypted.

9. Test the connection between Content Manager and the content store.

Tip: From the Actions menu, click Test to test the connection between Content Manager and
the content store.
Content Manager connects to the database, checks the database permissions, and creates and
populates a table. The table is not deleted and is used each time that the test is repeated.

Content Manager can now create the required tables in the content store when you start the IBM
Cognos 8 service for the first time. If the connection properties are not specified correctly, you
cannot connect to IBM Cognos Connection.
If you are upgrading from ReportNet, Content Manager can now access the required tables in the
content store that you used for the older version.

Specify a Mail Server Account

If you want to send reports by email, you must configure a mail server account.

Steps
1. In the Explorer window, under Data Access, click Notification.

78 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

2. In the Properties window, for the SMTP mail server property, type the host name and port of
your SMTP (outgoing) mail server.

Tip: To be able to open reports that are sent by email, you must change the host name portion
of the Gateway URI from localhost to either the IP address of the computer or the computer
name. Otherwise the URL in the email will contain localhost and remote users will not be able
to open the report.

3. Click the Value box next to the Account and password property and then click the edit button
when it appears.

4. Type the appropriate values in the Value - Account and password dialog box and then click
OK.

Tip: If logon credentials are not required for the SMTP server, remove the default information
for the Account and password property. When you are prompted for confirmation to leave this
property blank, click Yes. Ensure that the default user name has been removed. Otherwise, the
default account is used and notifications will not work properly.

5. In the Properties window, type the appropriate value for the default sender account.

6. Test the mail server connections. In the Explorer window right-click Notification and click
Test.
Cognos 8 tests the mail server connection.

If you do not plan to send reports by email, or do not want to set up a mail server account immedi-
ately, you are not required. However, when you save the configuration and then you start the services
in IBM Cognos Configuration, you will see a warning message when the mail server connection is
tested. You can safely ignore the warning.

Configure Environment Properties

We recommend that you specify the server name or an IP address in the URI properties that are
used by IBM Cognos 8. By default, the URI properties specify localhost.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window, click Environment.

3. In the Properties window, change the localhost portion of all URI properties to the name or IP
address of your IBM Cognos 8 server, by doing the following:

● For Dispatcher URIs for gateway and Content Manager URIs, click the value and then
click the edit button. Change the localhost portion and then click OK.

● For all other URI properties, click the value and change the localhost portion.

4. In the Explorer window, under Security, Cryptography, click Cognos, the default cryptographic
provider.

Installation and Configuration Guide 79

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

5. Under the Certificate Authority settings property group, set the Password property.

6. From the File menu, click Save.

Configure an IBM Cognos Series 7 Namespace in IBM

Cognos 8
If you want to migrate security information or secured content from IBM Cognos Series 7 to IBM
Cognos 8, you must configure a namespace in IBM Cognos 8 that is identical to the IBM Cognos
Series 7 namespace.
You can configure multiple namespaces for authentication in IBM Cognos 8. For more information,
see "Configuring IBM Cognos 8 Components to Use an Authentication Provider" (p. 149).

Note: You cannot use an IBM Cognos Series 7 Local Authentication Export (LAE) file for authen-
tication with IBM Cognos 8 components.
We recommend that all IBM Cognos Series 7 namespaces use the same primary IBM Cognos Series 7
Ticket Server. Otherwise, you may receive errors or be prompted for authentication more than
once. To maintain performance, ensure also that the ticket server is running.
If you change the configuration information stored in the directory server used for IBM Cognos
Series 7, you must restart the IBM Cognos 8 service before the changes take effect in the IBM
Cognos installation.
A user must be in at least one Access Manager user class to be able to log on to IBM Cognos 8
components.

Steps
1. In the Explorer window, right-click Authentication and select New Resource, Namespace.

2. In the Name box, type a name for the authentication namespace.

3. In the Type list, click IBM Cognos Series 7 and then click OK.

The new authentication provider resource appears in the Explorer window, under the
Authentication component.

4. In the Resource Properties window, specify the mandatory values.

Certain values must match the values you used when you configured the IBM Cognos Series 7
namespace in Configuration Manager. Under Services, Access Manager - Runtime, Directory
Server, check the values in the Properties window.

● For Namespace ID, specify a unique identifier for the namespace.

● For Host and port, type the same value that you used for the Computer property in Con-
figuration Manager.
The format must be identical. If you use an IP address in IBM Cognos Series 7, type the
same IP address. If you use a network host name in IBM Cognos Series 7, type the same
network host name.

80 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

● For Base Distinguished Name, type the same value that you used for the Base Distinguished
Name (DN) property in Configuration Manager.

● For Namespace name, type the same value that you used for the Default Namespace
property in Configuration Manager.
This value is case sensitive and must match exactly.

5. Specify the values for all other required properties to ensure that IBM Cognos 8 components
can locate and use your existing authentication provider.

If your IBM Cognos Series 7 namespace version is 16.0, ensure that the Data encoding property
is set to UTF-8. In addition, the computers where Content Manager is installed must use the
same locale as the data in the IBM Cognos Series 7 namespace.

6. If your namespace environment includes version 15.2 of the IBM Cognos Series 7 namespace,
you must disable the Series7NamespacesAreUnicode setting.

● In the Properties window, in the Advanced Properties value, click the edit button.

● In the Value - Advanced properties window, click Add.

● In the Name box, type Series7NamespacesAreUnicode.

● In the Value box, type False, and then click OK.

7. In the Properties window, under Cookie settings, ensure that the Path, Domain, and Secure
flag enabled properties match the settings configured for IBM Cognos Series 7.

8. From the File menu, click Save.

Configure the Web Server

For all installations, before you use Web pages generated by IBM Cognos 8, you must configure
your Web server. You must create virtual directories, or aliases, so that users can connect to IBM
Cognos 8 in the portal. If you plan to run more than one IBM Cognos 8 product, or several instances
of the same product, on one computer, you must create a separate application pool for each product
or instance and then associate the aliases for that product or instance to the application pool. The
steps for creating an application pool vary depending on your operating system.
On UNIX and Linux, the account under which the Web server runs must have read access to the
cogstartup.xml file in the c8_location/configuration directory. By default the cogstartup.xml file
has read permission for others. If you run your Web server under a specific group, you can change
the cogstartup.xml file permissions to ensure that it belongs to the same group as the Web server.
You can then remove the read permission for others.
For information on creating a user account or a network service account for IBM Cognos 8, see
"Configure a User Account or Network Service Account for IBM Cognos 8" (p. 44).

Steps to Create Virtual Directories

1. Create the following virtual directories:

Installation and Configuration Guide 81

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

Alias Location Permission

cognos8 c8_location/webcontent Read

cognos8/cgi-bin c8_location/cgi-bin Execute

You can use a name other than cognos8 in the aliases. However, you must use cgi-bin as the
second part of the alias and you must change the virtual directory in the Gateway URI property
to match the new IBM Cognos alias. For more information, see "Change a URI" (p. 192).
If you are upgrading from ReportNet, you can continue to use the existing aliases. If you install
IBM Cognos 8 reporting components in a different location from ReportNet, change the
existing aliases to include the new location. If you have more than one version of ReportNet
on one computer, you must use different alias names for IBM Cognos 8.
For Apache Web Server, ensure that you define the cognos8/cgi-bin alias before the cognos8
alias in the httpd.conf file located in the Apache_installation/conf directory. The cognos8/cgi-bin
alias must be defined as a ScriptAlias.

2. If you want to use Report Studio’s image browser, enable Web Distributed Authoring and
Versioning (WebDAV) on your Web server.
If you use Apache Web Server, specify a directory in which to enable WebDAV. For information
about configuring WebDAV, see your Web server documentation.
If you use Microsoft Internet Information Services (IIS), enable the Read and Directory
Browsing properties for the URL you want to access.

3. For IBM Cognos 8 for reporting, set the content expiry on the c8_location/pat/images virtual
directory in your Web server.
Each time a user opens Report Studio, their Web browser checks with the Web server to
determine if images are current. Because there are over 600 images, this can result in excess
network traffic. You can postpone this check until a specified date by using the content expiry
feature of the Web server.
For information on setting content expiry, see the documentation for your Web server.

Note: When you upgrade, Report Studio users must clear their Web browser cache to get the
latest images.

If you use Web aliases other than cognos8, or your Web server is on another computer, or you are
using Microsoft Internet Application Interface (ISAPI), apache_mod or a servlet gateway, change
the Gateway URI (p. 192) when you configure IBM Cognos components.

Steps to Create an Application Pool

1. From the Start menu, select Control Panel, Performance and Maintenance, Administrative
Tools.

2. Launch Internet Information Services (IIS) Manager.

Web Management Tools and World Wide Web Services are enabled.

82 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

3. From the root (your system name and user), select Feature View.

4. In the IIS section, launch ISAPI and CGI Restrictions.

5. Select Edit Feature Settings and enable Allow unspecified CGI modules and then click OK.

6. Add your aliases. For example, c8_location and c8_location/cgi-bin.

7. Select your cgi-bin alias and ensure that Feature View is selected.

8. Right-click Application Pools and select Add.

9. In the dialog box, enter a web alias and the corresponding path to IBM Cognos 8 webcontent.

10. Repeat steps 8 and 9 to add the next Web alias.

11. Select Default Web Site.

12. Open Handler Mappings.

13. Select CGI-cgi mappings.

14. In the right pane, click Revert to Inherited.

15. Expand the application that points to your webcontent location.

16. Expand your cgi-bin application node.

17. Add a mapping that points to *.cgi and name it CGI-cgi.

18. Select the CGI-cgi mapping.

19. In the right pane, click Revert to Inherited.

20. Restart the IIS server.

21. Find the folder that contains cgi-bin (c8_location/cgi-bin) and right-click it.

22. Select the Security tab.

23. Add the Network Services user, granting all permissions except Full Control.

24. Right-click on Cognos8 service and select Properties.

25. Click the Log On tab.

26. Click This account and enter Network Service as the user.

27. Delete the Password and the Confirm the password values.

28. Click OK.

Start the IBM Cognos 8 Service

To register the IBM Cognos 8 service so that users can access it through IBM Cognos Connection,
you must start the services. Before you start the services, test the configuration by using the test
feature in IBM Cognos Configuration.

Installation and Configuration Guide 83

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

On Windows, the IBM Cognos 8 service is configured to start automatically by default. On UNIX
and Linux, to start the IBM Cognos 8 process automatically, you must configure the process as a
daemon. For more information, see your operating system documentation.
You must install and configure both the server components of IBM Cognos 8 and Framework
Manager before you can use IBM Cognos 8 for reporting.

Note: IBM Cognos 8 cannot access any reporting data unless the data is first packaged in and
published from Framework Manager.

Steps
1. Start IBM Cognos Configuration.

2. Ensure that you save your configuration, otherwise you cannot start the IBM Cognos 8 service.

3. From the Actions menu, click Test.

IBM Cognos Configuration checks the common symmetric keys (CSK) availability, tests the
namespace configuration, and tests the connections to the content store and logging database.

Tip: If Test is not available for selection, in the Explorer window, click Local Configuration.

4. If the test fails, reconfigure the affected properties and then test again.
If the only test that fails is the mail server test, you can start the service. If you want the mail
server test to pass, configure a valid SMTP server under Data Access, Notification.

5. From the Actions menu, click Start.

It may take a few minutes for the IBM Cognos 8 service to start.

If you receive a message that the test phase has warnings, click Yes and then click Continue in
the start dialog box.
This action starts all installed services that are not running. If you want to start a particular
service, select the service node in the Explorer window and then click Start from the Actions
menu.

Test IBM Cognos 8 PowerPlay Server Components

You test your IBM Cognos 8 PowerPlay installation by checking the migration services, checking
the Migration Assistant icon in IBM Cognos Administration, and by opening a cube in PowerPlay
Studio. If you install the samples, you can use the sample cube provided with IBM Cognos 8
PowerPlay.
You can also test Framework Manager.
Use the following checklist to test the configuration:
❑ Test migration.

❑ Test IBM Cognos Connection.

84 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

Test IBM Cognos Connection

To test the installation and configuration of server components, open IBM Cognos Connection.

Steps
1. In your Web browser, type the URL to open IBM Cognos Connection:
For example, type

http://servername/cognos8

2. In the Welcome page, click IBM Cognos Content.

After you complete the initial configuration of IBM Cognos 8 PowerPlay, you can install IBM
Cognos 8 PowerPlay Client "Installing and Configuring Client and Modeling Components" (p. 133).
You can also customize the components for use in your environment by changing other settings in
IBM Cognos Configuration (p. 187).

PowerPlay Administration
To change runtime settings for IBM Cognos 8 PowerPlay, use IBM Cognos Administration, which
is accessed through the IBM Cognos 8 portal. For example, you can enable or disable dispatchers
and services, or set up permissions for users, groups, and roles. For more information, see the
Administration and Security Guide. You can also configure options for migration and for PowerPlay
reports and cubes. For more information, see the Migration and Administration Guide.

Test the Migration Services

You can test the installation of the IBM Cognos 8 migration service by checking that the Migration
Assistant icon appears in IBM Cognos Administration.

Steps
1. In IBM Cognos Connection, from the toolbar, click Launch, IBM Cognos Administration.

2. Click the Configuration tab.

3. Click Content Administration.

The migration assistant button appears on the toolbar.

Before you can use the Migration Assistant to migrate IBM Cognos Series 7 content from PowerPlay
Enterprise Server, Upfront, and IBM Cognos Connection, you must install migration components
with IBM Cognos Series 7. For more information about migrating content from IBM Cognos Series
7, see the IBM Cognos 8 PowerPlay Migration and Administration Guide.

Installing and Configuring Migration on IBM Cognos Series 7

Computers
After installing the IBM Cognos 8 PowerPlay components, you can install IBM Cognos Series 7
migration components to support the migration of PowerPlay content from IBM Cognos Series 7

Installation and Configuration Guide 85

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

to IBM Cognos 8 PowerPlay. The IBM Cognos Series 7 migration components are available on
Windows and UNIX, on the IBM Cognos 8 PowerPlay Server CD.
Use the following checklist to guide you through the tasks to install and configure IBM Cognos 8
Migration.
❑ Install IBM Cognos Series 7 migration components.

❑ Configure the IBM Cognos Series 7 migration components, if required.

❑ Start the IBM Cognos Series 7 migration service.

Install IBM Cognos Series 7 Migration Components

Ensure that your IBM Cognos Series 7 installations are working correctly before installing the IBM
Cognos Series 7 migration components. This includes ensuring that the IBM Cognos Series 7
PowerPlay Enterprise Server service and the Upfront services, including the IBM Cognos Upfront
Administration Service, IBM Cognos Upfront Data Store and the IBM Cognos Upfront Dispatcher
services, are running.
You install IBM Cognos Series 7 migration components on the IBM Cognos Series 7 computers.
● To migrate content from a PowerPlay Enterprise Server you must install IBM Cognos Series 7
migration components on the PowerPlay Enterprise Server computer. If Upfront is located on
the same computer you can also migrate content from Upfront. Installing migration components
on the PowerPlay Enterprise Server computer also supports the migration of PowerPlay content
that was published to Cognos Connection.

● To migrate content from Upfront you must install IBM Cognos Series 7 migration components
on the Upfront computer. When Upfront and PowerPlay Enterprise Server are installed on
separate computers, you must install IBM Cognos Series 7 migration components on the both
the PowerPlay Enterprise Server computer and the Upfront computer. Also, you must set up
and configure a shared network location to support migration processing.

Steps
1. Insert the IBM Cognos 8 PowerPlay Server CD that is appropriate for your operating system.
On UNIX, you must mount the CD using Rock Ridge file extensions.

2. If the Welcome page does not appear, do one of the following:

● On Windows, in the win32 directory on the CD, double-click the issetup.exe file.

● On UNIX, in the directory that is appropriate for your operating system, type

./issetup

3. Select the language to use for the installation.

The language that you select determines the language of the installation wizard.

4. Follow the directions in the installation wizard.

5. On the Component Selection page, clear all components except IBM Cognos Series 7 Migration
Components.

86 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

6. In the Multiple Installation Locations page, specify the IBM Cognos Series 7 location to install
the components.
You must install IBM Cognos Series 7 migration components in the same directory as IBM
Cognos Series 7 version 4 (7.4).
If you are prompted for an IBM Cognos 8 installation location, you can accept the default
location or enter a new local location. This location is used to write install files. You do not
have to enter the path to an IBM Cognos 8 installation on a different computer and you do
not require IBM Cognos 8 components on the IBM Cognos Series 7 computer.

7. In the Migration Configuration Information page, for the Migration Service Port Number, type
a port number that the IBM Cognos Series 7 migration service will use. The default is 21567.

8. In the Finish page, click Finish.

Like other IBM Cognos products, the installation process creates log files that include information
such as details about transferred files and installation errors. The log files are located in the
installation_location\instlog directory.

Configure the IBM Cognos Series 7 Migration Service for Migrations from Upfront
in Distributed IBM Cognos Series 7 Installations
If you installed IBM Cognos Series 7 migration components on both a PowerPlay Enterprise Server
computer and a separate Upfront computer, you must set up and configure a shared network location.
The migration service writes temporary files to this location during migration processing.
The following limitations apply for migration from Upfront when PowerPlay Enterprise Server and
Upfront are on separate computers.

Notes
● PowerPlay Enterprise Server and Upfront must access PowerCubes using the same path, such
as \\machine_name\cubes. If the cubes are located on the same computer as PowerPlay Enterprise
Server, PowerPlay Enterprise Server will access the cubes using a local path and Upfront will
access the cubes using a path that includes the PowerPlay Enterprise computer name. Migration
from Upfront will not work in this situation.

● You can not migrate from Upfront if more than one PowerPlay Enterprise Server is used to
publish content to Upfront.

Steps
1. Create a folder in a shared network location that is accessible from both the PowerPlay Enterprise
Server computer and the Upfront computer.
Ensure that the services for PowerPlay Enterprise Server, Upfront, and IBM Cognos Series 7
migration run under named accounts that have write access to the folder.

2. Complete the following steps on each computer that includes IBM Cognos Series 7 migration
components.

Installation and Configuration Guide 87

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

● From the installation_location/mig7service, open the migs7service_configuration.xml file

in an XML or text editor.

● Edit the series7-shared-location description line to specify the network location and activate
the line (remove comment tags). For example,
<series7-shared-location description="Path to shared folder">\\bott93\shareT\s7migration</
series7-shared-location>

● Save and close the file.

3. Restart the IBM Series 7 migration service.

The configuration to support migration from separate PowerPlay Enterprise Server and Upfront
computers is complete.

Start the IBM Cognos Series 7 Migration Service

Before you can migrate content from IBM Cognos Series 7 PowerPlay to IBM Cognos 8 PowerPlay,
you must start the migration service for IBM Cognos Series 7. On Windows, the migration service
for IBM Cognos Series 7 starts automatically when it is first installed.

Step
● Start the migration service:

● On Windows, if the service is stopped, then restart the migration service using the IBM
Cognos Migration Series 7 Service entry in the Services list under Administrative Tools.

● On UNIX, go to the c8_location/migs7 directory and start the service by typing

./configure.sh --start

Uninstalling IBM Cognos 8

It is important to use IBM Cognos 8 uninstall programs to remove IBM Cognos 8 products.
If you are running IBM Cognos 8 in an application server environment, use the administration tool
provided by your application server vendor to stop the application if it is running and undeploy
the Java portion of IBM Cognos 8 components. Many application servers do not completely remove
all deployed application files or directories during an undeployment; therefore, you may have to
perform this action manually. After you have undeployed IBM Cognos 8 components, complete
the steps to uninstall on UNIX and on Windows, as required.
The IBM Cognos 8 migration components are uninstalled when you uninstall IBM Cognos 8. You
can uninstall the IBM Cognos Series 7 migration components separately from your IBM Cognos
Series 7 installation (p. 91).

Uninstall IBM Cognos 8 on UNIX or Linux

If you no longer require IBM Cognos 8 or if you are upgrading, uninstall IBM Cognos 8.

88 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

We recommend that you close all programs before you uninstall IBM Cognos 8. Otherwise, some
files may not be removed.

Steps
1. If the console attached to your computer does not support a Java-based graphical user interface,
determine the process identification (pid) of the IBM Cognos 8 process by typing the following
command:

ps -ef | grep cogbootstrapservice

2. Stop the IBM Cognos 8 process:

● If you run XWindows, start IBM Cognos Configuration, and from the Actions menu, click
Stop.

● If you do not run XWindows, type:

kill -TERM pid

3. To uninstall IBM Cognos 8, go to the c8_location/uninstall directory and type the appropriate
command:
● If you use XWindows, type

./uninst -u

● If you do not use XWindows, run an unattended uninstall (p. 283).

4. Follow the prompts to complete the uninstallation.

5. Delete all temporary Internet files.

Uninstalling does not remove any files that changed since the installation, such as configuration
and user data files. Your installation location remains on your computer, and you retain these files
until you delete them manually.

Important: Do not delete the configuration and data files if you are upgrading to a new version of
IBM Cognos 8 and you want to use the configuration data with the new version.

Uninstall IBM Cognos 8 on Windows

If you no longer require IBM Cognos 8 or if you are upgrading, uninstall all IBM Cognos 8 com-
ponents and the IBM Cognos 8 service.
If you installed more than one IBM Cognos 8 component or product in the same location, the
uninstall wizard lets you choose the packages to uninstall. All components of the package will be
uninstalled. You must repeat the uninstallation process on each computer that contains IBM
Cognos 8 components.
It is not necessary to back up the configuration and data files on Windows. These files are preserved
during the uninstallation.

Installation and Configuration Guide 89

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

We recommend that you close all programs before you uninstall IBM Cognos 8. Otherwise, some
files may not be removed.

Steps
1. From the Start menu, click Programs, IBM Cognos 8, Uninstall IBM Cognos 8.

The Uninstall wizard appears.

Tip: IBM Cognos 8 is the default name of the Program Folder that is created during the
installation. If you chose another name, go to that folder to find the program.

2. Follow the instructions to uninstall the components.

The cognos_uninst_log.txt file records the activities that the Uninstall wizard performs while
uninstalling files. This log file is created in the temp directory.

3. Delete all temporary Internet files.

For more information, see your Web browser documentation.

Uninstalling does not remove any files that changed since the installation, such as configuration
and user data files. Your installation location remains on your computer, and you retain these files
until you delete them using Windows Explorer.

Important: Do not delete the configuration and data files if you are upgrading to a new version of
IBM Cognos 8 and you want to use the configuration data with the new version.

Uninstall Cognos Content Database

If you want to uninstall only Cognos Content Database and leave other IBM Cognos 8 components
on your computer, you must use the following procedure. After you uninstall Cognos Content
Database you must configure a new content store before you can restart the IBM Cognos 8 service.
If you installed only Cognos Content Database, use another procedure. For information about this
procedure, see "Uninstall IBM Cognos 8 on UNIX or Linux" (p. 88) or "Uninstall IBM Cognos 8
on Windows" (p. 89).

Steps
1. On the computer where you installed Cognos Content Database, go to the c8_location\bin
directory, and type the following command:
● On Windows, type

derby.bat uninstall
This command removes the Cognos Content Database service.

● On UNIX, type

derby.sh stop
This command stops the Cognos Content Database service.

2. In the c8_location directory, delete the derby10.1.2.1 directory.

3. In the c8_location\bin directory, delete the following files:

90 PowerPlay®
 Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

● On Windows, derby.bat

● On UNIX, derby.sh and derbyenv.sh

4. On Windows, in the c8_location\logs directory, delete the derby.service file.

5. In the c8_location directory, open the cmplst.txt file in a text editor.

6. Remove lines containing Cognos Content Database values. The lines contain CCD and
CMDERBY. For example:
C8BISRVRCCD_version=

C8BISRVRCCD_name=

CCD_version=

CCD_name=

CMDERBY_version=

CMDERBY_name=

Tip: You can also comment the lines out by inserting # at the start of each line.

7. Save the file.

8. Start IBM Cognos Configuration.

9. Under Data Access, Content Manager, do the following:

● Delete the Cognos Content Database.

● Configure a new database resource to point to a new content store.

For more information, see "Set Database Connection Properties for the Content Store" (p. 76).

10. Restart IBM Cognos 8.

Uninstall the Migration Components

The IBM Cognos 8 migration components are uninstalled when you uninstall IBM Cognos 8. You
can not uninstall only the migration components from your IBM Cognos 8 installation.
You can uninstall the IBM Series 7 migration components separately from your IBM Cognos Series
7 installation. After you complete the migration from IBM Cognos Series 7, you can choose to
uninstall the migration components from each IBM Cognos Series 7 computer. However, the
migration components are only active during a migration and will not affect your IBM Cognos
Series 7 installation if you choose to not uninstall the migration components.

Step
● On the IBM Cognos Series 7 computers, uninstall the IBM Cognos Report Migration from
Series 7 component.
For more information about uninstalling IBM Cognos Series 7 components, see the IBM Cognos
Series 7 Solution Installation Guide.

Installation and Configuration Guide 91

Chapter 6: Installing and Configuring IBM Cognos 8 PowerPlay on One Computer

92 PowerPlay®
Chapter 7: Installing and Configuring IBM
Cognos 8 PowerPlay Server Components in a Dis-
tributed Installation

You can install server components on multiple computers. For more information, see "Distribution
Options for IBM Cognos 8" (p. 21).
IBM Cognos 8 migration components are included with the IBM Cognos 8 PowerPlay installation.
These components support the migration of PowerPlay content from IBM Cognos Series 7 to IBM
Cognos 8. Also, if you install IBM Cognos 8 PowerPlay with IBM Cognos 8, the migration com-
ponents support the option to open a PowerPlay Studio report in Analysis Studio or Report Studio.
IBM Cognos Series 7 migration components are available with IBM Cognos 8 PowerPlay. To
migrate content from IBM Cognos Series 7 PowerPlay to IBM Cognos 8 PowerPlay, you must nstall
the IBM Cognos Series 7 migration components on the computer where IBM Cognos Series 7
PowerPlay Enterprise Server is installed. If you want to migrate PowerPlay content from Upfront,
you must also install the IBM Cognos Series 7 migration components on the computer where Upfront
is installed.
Use the installation wizard to select the server components that you want to install and the location
on your computer where you want to install them. Only the components that you choose to install
are copied from the CD to your computer.
We recommend that you do an interactive installation (p. 95).
This chapter also includes information about uninstalling IBM Cognos 8. For more information,
see "Uninstalling IBM Cognos 8" (p. 129).
You can also install all IBM Cognos 8 components on one computer. For more information, see
"Installing and Configuring IBM Cognos 8 PowerPlay on One Computer" (p. 67).
If you want to install an identical configuration across several computers on your network or
automate the installation and configuration process, you can set up an unattended installation and
configuration (p. 283).
If modelers want to create relational packages or mixed-source packages to support Analysis Studio,
Report Studio, or Query Studio, you require the IBM Cognos 8 modeling tool, Framework Manager.
If modelers want to build PowerCubes, you require IBM Cognos 8 Transformer. If modelers want
to build PowerCubes from relational sources, you require both Framework Manager and IBM
Cognos 8 Transformer. For information about installing Framework Manager and IBM Cognos 8
Transformer, see the IBM Cognos 8 Business Intelligence Installation and Configuration Guide
that is provided with your modeling components.
The following constraints apply to a distributed installation:
● If you plan to install two or more IBM Cognos 8 components on the same computer, we strongly
recommend that you install them in the same installation location to avoid conflicts among
ports and other default settings.

Installation and Configuration Guide 93

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

● If you want to use the samples, you must install them from the IBM Cognos 8 Business Intelli-
gence Samples CD. For more information, see "Install the IBM Cognos 8 Samples" (p. 138).

● On UNIX, to run the graphical-mode installation the console attached to your UNIX computer
must support a Java-based graphical user interface.

● On UNIX, IBM Cognos 8 respects the file mode creation mask (umask) of the account running
the installation program. This affects only the installation directories. It does not affect the file
permissions within the directories. However, run-time generated files, such as logs, respect the
mask. We recommend umask 022 on the installation directory.

When you install IBM Cognos 8 components on more than one computer, you must configure
environment properties so that the distributed components can communicate with each other.
You must also configure cryptographic properties to ensure that each computer uses the same settings.
In a distributed environment, the sequence in which you first configure computers is important.
You must configure and then start the services on at least one computer where you installed Content
Manager before you configure other computers in your IBM Cognos environment. You must con-
figure the gateway computer last so that cryptographic keys are shared and secure communication
can take place among the three components. The server specified for the External Dispatcher URI
property on the gateway computer must be the last server that you start.
Before you begin to install, ensure that the following prerequisites are met:
● Complete the tasks in "Setting Up the Environment" (p. 31).

● If you are installing IBM Cognos 8 in an application server environment, you must be aware
of the installation requirements. For more information, see "Configuring IBM Cognos 8 for
an Application Server" (p. 255).

● If you are installing IBM Cognos 8 PowerPlay with IBM Cognos 8 Business Intelligence Server,
we recommend that IBM Cognos 8 Business Intelligence Server be installed and configured
first. Both products must be the same version. For more information, see "IBM Cognos Products
That Interoperate with IBM Cognos 8 PowerPlay" (p. 26).

Use the following checklist to guide you through the tasks to install and configure IBM Cognos 8
PowerPlay on more than one computer.
❑ Install and configure Content Manager.

❑ Install and configure Application Tier Components on the PowerPlay Server.

❑ Install and configure the gateway.

❑ Install and configure migration components on IBM Cognos Series 7 computers.

After you complete the initial configuration of IBM Cognos 8 PowerPlay, you can install IBM
Cognos 8 PowerPlay Client "Installing and Configuring Client and Modeling Components" (p. 133).
You can also customize the components for use in your environment by changing other settings in
IBM Cognos Configuration (p. 187).

94 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

PowerPlay Administration
To change runtime settings for IBM Cognos 8 PowerPlay, use IBM Cognos Administration, which
is accessed through the IBM Cognos 8 portal. For example, you can enable or disable dispatchers
and services, or set up permissions for users, groups, and roles. For more information, see the
Administration and Security Guide. You can also configure options for migration and for PowerPlay
reports and cubes. For more information, see the IBM Cognos 8 PowerPlay Migration and
Administration Guide.

Recommendation - Install Server Components in Interactive

Mode
For a complete installation, you must install components on your server and then configure them
to work in your environment.
Typically, you run the IBM Cognos installation and configuration programs in interactive mode.
This means that in a graphical user interface (GUI) the installer prompts you to provide information,
and the configuration tool enables you to change default settings.
You can choose other installation methods to install server components.

Silent Mode
You can automate the installation of components using response files and running the installation
program in silent mode.
For information about silent mode installations, see "Setting Up an Unattended Installation and
Configuration" (p. 283).
You can automate the configuration of components by exporting the configuration settings from
one computer to another as long as the installed components are the same. This means that you
must run IBM Cognos Configuration in interactive mode the first time.
The other option is to edit the cogstartup.xml file, using settings that apply to your environment,
and then running the configuration tool in silent mode.

Interactive Mode
Unless you intend to complete a silent-mode installation, we recommend that you install the software
from an X Window System workstation, an X terminal, or a PC or other system with X server
software installed.
To run an interactive-mode installation, the console attached to your computer must support a
Java-based graphical user interface.

Installing and Configuring Content Manager Computers

In a distributed installation, at least one of the computers where you install Content Manager must
be configured, running and accessible before you configure other computers in your IBM Cognos
environment. This ensures that the certificate authority service, which is installed with Content
Manager, is available to issue certificates to other IBM Cognos computers.

Installation and Configuration Guide 95

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

The Content Manager computers must know the location of the content store, other Content
Manager computers, and the notification database to use for job and schedule information.
Your installation may include more than one Content Manager, each on a different computer. One
Content Manager computer is active and one or more Content Manager computers are on standby.
The standby Content Manager computers are for failover protection. If the active Content Manager
computer is not available because of a software or hardware failure, a standby Content Manager
computer becomes active and requests are directed to it.
When the active Content Manager fails, unsaved session data is lost. When another Content Manager
becomes active, users may be prompted to log on.
The first Content Manager computer to be started becomes the default active Content Manager.
You can designate another Content Manager computer as default active, using the Administration
tool. For more information about activating a Content Manager service, see the Administration
and Security Guide.
To support failover protection, you must synchronize the system clocks on the Content Manager
computers. If you use the default CGI gateway, we recommend that you configure IBM Cognos 8
to use an ISAPI gateway instead. Otherwise, performance may be affected after failover.
Before you configure Content Manager, ensure that you created the database for the content store
on an available computer in your network.
If you want to use the Cognos Content Database as your content store, you must select it in the
installation wizard. If you are installing components on several computers, you need to only install
one Cognos Content Database. If you install Cognos Content Database on the same computer as
Content Manager, and you later decide to use another database for your content store, you must
uninstall Cognos Content Database.
Use the following checklist to guide you through the required configuration tasks for the Content
Manager computers.
❑ Install Content Manager.

❑ Update the Java environment.

❑ Set up the database connectivity for the content store database.

❑ Start IBM Cognos Configuration.

❑ Set the database connection properties for the content store.

❑ Specify a mail server account.

❑ Configure the environment properties.

❑ Configure an IBM Cognos Series 7 namespace in IBM Cognos 8, if required.

❑ Start the IBM Cognos 8 service on Content Manager.

❑ Test the Content Manager installation.

96 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Install the Content Manager Components

To install Content Manager, use the CD for your operating system. In the installation wizard, clear
all components except Content Manager. If you want to use Cognos Content Database, select that
component too unless you want to install it on a separate server.
If you are installing multiple Content Managers, you must ensure that the system clocks on the
Content Manager computers are synchronized for successful failover between Content Managers.
If you will be using PowerCubes that are secured against an IBM Cognos Series 7 namespace, you
must install Content Manager on a computer that supports IBM Cognos Series 7.

Steps for UNIX and Linux

1. If you are installing to a directory with other IBM Cognos 8 components, stop the IBM Cognos 8
service.

2. Set the JAVA_HOME environment variable to point to the installation location of your Java
Runtime Environment (JRE).
An example of the installation location of a Java Runtime Environment is /directory/java/java_ver-
sion/jre.
IBM Cognos 8 requires a JVM, such as IBM Java, to run on Linux.

3. On HP-UX, set the _M_ARENA_OPTS environment variable as follows:

_M_ARENA_OPTS 1:4
This increases the memory allocation for HP-UX to more closely match that of other UNIX
platforms.

4. On AIX, set the AIXTHREAD_SCOPE environment variable as follows:

AIXTHREAD_SCOPE=S
This sets the contention scope for user threads to system-wide, which supports more efficient
scheduling of user threads.

5. Mount the CD for your IBM Cognos product using Rock Ridge file extensions.

Important: To mount the IBM Cognos CD on HP-UX, do the following:

● Add the pfs_mount directory in your path.
For example,

PATH=/usr/sbin/:$PATH

export PATH

● To start the required NFS daemons and run the daemons in the background, type bg
pfs_mountd and then type bg pfsd

● To mount the drive, type

pfs_mount -t rrip <device><mount_dir> -o xlat=unix

For example,

Installation and Configuration Guide 97

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

pfs_mount /dev/dsk/c0t2d0 /cdrom -o xlat=unix

You can now install or copy files as a non-root user using an IBM Cognos CD from this
drive.

● When the installation is complete, type pfs_umount /cdrom and kill the pfsd and pfs_mountd
daemons to unmount the CD.

6. Go to the directory on the CD that is appropriate for your operating system.

For example, for Solaris, go to the solaris directory.

7. Start the installation wizard:

● If you use XWindows, type ./issetup

Note: When you use the issetup command with XWindows, Japanese characters in messages
and log files may be corrupted. When installing in Japanese on UNIX or Linux, first set
environment variables LANG=C and LC_ALL=C (where C is the language code, for example
ja_JP.PCK on Solaris), and then start the installation wizard.

● If you do not use XWindows, run an unattended installation (p. 283).

8. Follow the directions in the installation wizard and copy the required files to your computer.
Install Content Manager in a directory that contains only ASCII characters in the path name.
Some UNIX and Linux Web servers do not support non-ASCII characters in directory names.
If you are installing on a computer that already has ReportNet and you want to keep ReportNet,
you must install IBM Cognos 8 in a different directory.
If you are installing in a directory that contains other IBM Cognos 8 components, you are
prompted for the location of a directory in which to store backup copies of the files that will
be overwritten.

9. Choose how to proceed in the Finish page of the installation wizard:

● We recommend that you do not configure IBM Cognos 8 immediately because you must
do other tasks first to ensure that your environment is properly set up. However, if the
console attached to your computer supports a Java-based graphical user interface, you can
click Start IBM Cognos Configuration.

● If the console attached to your computer does not support a Java-based graphical user
interface, click Finish.
You can later configure IBM Cognos 8 using IBM Cognos Configuration by starting cog-
config.sh in the c8_location/bin directory, or editing cogstartup.xml in c8_loca-
tion/configuration directory.

10. Append the c8_location/bin directory to the appropriate library path environment variable.
● For Solaris and Linux, LD_LIBRARY_PATH

● For AIX, LIBPATH

● For HP-UX, SHLIB_PATH

98 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

11. On Linux, set the PRINTER environment variable to the name of your printer.

If you want to install Cognos Content Database on a separate computer, run the installation wizard
on your database server and select only the Cognos Content Database component.
If you want users to see product documentation in a language other than English, you must install
the Supplementary Languages Documentation in the same location as the Gateway components.
For more information, see "Install Translated Product Documentation" (p. 145).

Steps for Windows

1. If you are installing to a directory with other IBM Cognos 8 components, stop the IBM Cognos 8
service.

2. Insert the CD for your IBM Cognos product.

The Welcome page of the installation wizard appears.

3. If no Welcome page appears, in the win32 directory on the CD, double-click the issetup.exe
file.

4. Select the language to use for the installation.

The language that you select determines the language of the user interface. You can change the
language to any of the installed languages after installation.

5. Follow the directions in the installation wizard to copy the required files to your computer.
Install Content Manager in a directory that contains only ASCII characters in the path name.
Some Windows Web servers do not support non-ASCII characters in directory names.
If you are installing on a computer that already has ReportNet, and you want to keep ReportNet
running, you must install IBM Cognos 8 in a different directory.
If you are installing in a directory that contains other IBM Cognos 8 components, you are
prompted for the location of a directory in which to store backup copies of the files that will
be overwritten.

6. In the Finish page of the installation wizard,

● If you want to configure IBM Cognos components immediately, click Start IBM Cognos
Configuration.

● If you want to see late-breaking information about IBM Cognos components, click View
the Readme.

7. Click Finish.

Use the Windows Start menu to start IBM Cognos Configuration from the shortcut folder.

If you want to install Cognos Content Database on a separate computer, run the installation wizard
on your database server and select only the Cognos Content Database component.
If you want users to see product documentation in a language other than English, you must install
the Supplementary Languages Documentation in the same location as the Gateway components.
For more information, see "Install Translated Product Documentation" (p. 145).

Installation and Configuration Guide 99

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Install Cognos Content Database on a Separate Server

If you want to install Cognos Content Database on a separate server, you must do so before you
configure Content Manager. In the installation wizard, clear all components and select only Cognos
Content Database.

Steps
1. On your database server, insert the CD for your IBM Cognos product.
On UNIX or Linux, mount the CD using Rock Ridge file extensions.

2. If the Welcome page does not appear, start the installation wizard:

● On UNIX or Linux, from the directory for your operating system, type ./issetup

● On Windows, in the win32 directory on the CD, double-click issetup.exe.

3. Follow the directions in the installation wizard and copy the required files to your computer.
Install in a directory that contains only ASCII characters in the path name. Some UNIX and
Linux Web servers do not support non-ASCII characters in directory names.

4. In the Finish page of the installation wizard, click Finish.

Update the Java Environment on the Content Manager Computer

IBM Cognos 8 cryptographic services use a .jar (Java Archive) file, named bcprov-jdknn-nnn.jar,
that must be located in your Java Runtime Environment (JRE). This file provides additional
encryption and decryption routines that are not supplied as part of a default JVM installation. To
ensure security, the encryption file must be loaded by the JVM using the java extensions directory.
If you want to use your own JRE and have JAVA_HOME set to that location on Windows or if
you are installing on UNIX, you may have to update the Java environment for the cryptographic
services.
On Windows, you can set JAVA_HOME as a system variable or a user variable. If you set it as a
system variable, it may be necessary to restart your computer for it to take effect. If you set it as a
user variable, set it so that the environment in which Tomcat is running can access it.
If you do not have a JAVA_HOME variable already set on Windows or if JAVA_HOME points to
a Java version that is not valid for IBM Cognos 8, the JRE files provided with the installation will
be used, and you do not have to update any files in your environment.

Steps
1. Ensure that the JAVA_HOME environment variable is set to the JRE location.
For example, to set JAVA_HOME to the JRE files provided with the installation, the path is
c8_location/bin/jre/version.

2. Copy the bcprov-jdknn-nnn.jar file from the c8_location/bin/jre/version/lib/ext directory to the

Java_location/jre/lib/ext directory.

100 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Set Up Database Connectivity for the Content Store Database

If you are using a database other than Cognos Content Database as the content store, you may
have to install database client software, or JDBC drivers, or both, on each computer where you
install Content Manager. Doing this allows Content Manager to access the content store database.

Steps for DB2

1. If you are using type 2 JDBC connectivity, install the DB2 client software on the Content
Manager computers.
If you use type 4 JDBC connectivity for DB2, you are not required to install the DB2 client
software where Content Manager is installed. If you are using a DB2 database on z/OS for the
content store, you must use type 4 JDBC connectivity.
For more information about the differences between type 2 and type 4 drivers, see "JDBC
Driver Options for Using DB2 Database as a Content Store" (p. 73).

2. If you are using type 2 JDBC connectivity, and the content store is on a different computer than
Content Manager, configure a database alias to the content store.
On Windows, run the DB2 Client Configuration Assistant.
On UNIX or Linux, use the DB2 command line interface.
If the content store database and Content Manager are on the same computer, the content store
name automatically becomes the alias.
When you configure the Content Manager computers, ensure that they are all configured to
use the same content store.

3. On Windows, stop the DB2 services and the HTML Search Server.

4. Copy the following files from DB2_installation/sqllib/java directory to the c8_location/webapps/

p2pd/WEB-INF/lib directory.
● the universal driver file, db2jcc.jar

● the license file

for DB2 on Linux, UNIX, or Windows, db2jcc_license_cu.jar
for DB2 on z/OS, db2jcc_license_cisuz.jar

If you are connecting to DB2 on z/OS, use the driver version from Linux, UNIX, or Windows
version 9.1 fix pack 5 or version 9.5 fix pack 2.

Tip: To check the driver version, run the following command

java -cp path\db2jcc.jar com.ibm.db2.jcc.DB2Jjcc -version

5. On Windows, restart the DB2 services and the HTML Search Server.

6. On UNIX, if you are using type 2 JDBC connectivity, ensure that the 32-bit DB2 libraries are
in the library search path, which is usually the $DB2DIR/lib directory or the $DB2DIR/lib32
directory.

Installation and Configuration Guide 101

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

7. Repeat this entire procedure on the IBM Cognos 8 computers where Content Manager is
installed or where notification is sent to a DB2 database.

You can tune the database to take advantage of DB2 features. For more information, see the
"Tuning a DB2 Content Store" (p. 291).

Steps for Oracle

1. On the computer where the Oracle client is installed, go to the ORACLE_HOME/jdbc/lib
directory.

2. Copy the appropriate JAR file to the c8_location/webapps/p2pd/WEB-INF/lib directory on

computers where Content Manager is installed and where notification is sent to an Oracle
database.
● If you use Java 1.4, copy the ojdbc14.jar file

● If you use Java 1.5, copy the ojdbc5.jar file

If the directory contains the classes12.jar file, delete it before installing the ojdbc14.jar or
ojdbc5.jar file.
The driver is available from an Oracle client or server install, and it can also be downloaded
from the Oracle technology Web site (http://www.oracle.com/technology).

Steps for Sybase

1. On the computer where Sybase is installed, go to the Sybase_location/jConnect-5_5/classes
directory.

2. Copy the jconn2.jar file to the c8_location/webapps/p2pd/WEB-INF/lib directory on every

computer where Content Manager is installed and where notification is sent to a Sybase database.

Start IBM Cognos Configuration on the Content Manager Computer

Use the configuration tool, IBM Cognos Configuration, to configure IBM Cognos 8, or to start and
stop IBM Cognos services.
Before starting IBM Cognos Configuration, ensure that the operating environment is properly set
up. For example, ensure that all variables have been set.
If you use a database server other than Microsoft SQL for the content store, we recommend that
you copy the JDBC drivers to the appropriate location before you start the configuration tool.
Ensure that user or service account is set up. For information, see "Configure a User Account or
Network Service Account for IBM Cognos 8" (p. 44).

Step for Windows

● From the Start menu, click Programs, IBM Cognos 8, IBM Cognos Configuration.

Step for UNIX or Linux

● Go to the c8_location/bin directory and then type

102 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

./cogconfig.sh

Set Database Connection Properties for the Content Store

You must specify the database server information to ensure that Content Manager can connect to
the database you use for the content store. Content Manager uses the database logon to access the
content store. After you set the database connection properties, you can test the connection between
Content Manager and the content store.
If you installed Cognos Content Database on a different computer from where you installed Content
Manager, you must set the database connection properties for Cognos Content Database. If you
installed Cognos Content Database on the same computer as Content Manager, Content Manager
is configured to use Cognos Content Database using the default values. If you install Cognos Content
Database on the same computer as Content Manager, and you later decide to use another database
for your content store, you must uninstall Cognos Content Database.
IBM Cognos 8 components require the TCP/IP protocol to access data and the content store. Ensure
that the database server has the protocol set to TCP/IP.
Ensure that you used one of the supported database servers to create the content store.
Ensure that a user or service account is set up. For information, see "Configure a User Account or
Network Service Account for IBM Cognos 8" (p. 44).

Steps for Cognos Content Database

1. On the computer where you installed Content Manager, start IBM Cognos Configuration.

2. In the Explorer window, under Data Access, Content Manager, click Content Store.

3. In the Properties window, change the following properties:

● For Name, type cm.

● For Database server and port number, type the name of the computer where you installed
Cognos Content Database.

● For User ID and password, click the edit button and specify cognos for both the userid and
password to access Cognos Content Database.

We recommend that you change the default user ID and password after configuring the new
resource. For information about changing default values, see "Change Default User and Password
for Cognos Content Database" (p. 188).

4. From the File menu, click Save.

The logon credentials are immediately encrypted.

5. From the Actions menu, click Test to test the connection between Content Manager and the
content store.
You must start the Cognos Content Database service on the computer where it is installed
before the test will succeed.

Installation and Configuration Guide 103

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Content Manager connects to the database, checks the database permissions, and creates and
populates a table. The table is not deleted and is used each time that the test is repeated.

Steps for DB2

1. In the location where you installed Content Manager, start IBM Cognos Configuration.

2. In the Explorer window, under Data Access, Content Manager, click Content Store.

3. In the Properties window, for the Database name property, type the name of the database or
the database alias.

4. Change the logon credentials to specify a valid user ID and password:

● Click the Value box next to the User ID and password property and then click the edit
button when it appears.

● Type the appropriate values and click OK.

5. To use type 4 JDBC connectivity, for the Database server and password property, type a value,
using host:port syntax.
If you leave this property blank, type 2 JDBC connectivity is used.
For more information about the differences between the driver types, see "JDBC Driver Options
for Using DB2 Database as a Content Store" (p. 73).

6. From the File menu, click Save.

The logon credentials are immediately encrypted.

7. Test the connection between Content Manager and the content store.

Tip: In the Explorer window, right-click the new database and click Test.
Content Manager connects to the database, checks the database permissions, and creates and
populates a table. The table is not deleted and is used each time that the test is repeated.

Steps for Microsoft SQL Server, Oracle, and Sybase

1. On the computer where you installed Content Manager, start IBM Cognos Configuration.

2. In the Explorer window, under Data Access, Content Manager, right-click Content Store and
click Delete.
This deletes the connection to the default resource. Content Manager must be configured to
access only one content store.

3. Right-click Content Manager, and then click New resource, Database.

4. In the Name box, type a name for the resource.

5. In the Type box, select the type of database and click OK.
If you are upgrading and want to use an existing content store, ensure that you select the type
of database you use for the older version.

104 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

If you installed more than one version of IBM Cognos 8, you must use a different content store
for each version. When a content store is used by a new version of IBM Cognos 8, it cannot
be used by an older version.

Tip: If you want to use Oracle Net8 keyword-value pair to manage the database connection,
select Oracle database (Advanced).

6. In the Properties window, provide values depending on your database type:

● If you use a Microsoft SQL Server database, type the appropriate values for the Database
server with port number or instance name and Database name properties.
For a Microsoft SQL Server database, you can choose to use a port number, such as 1433,
or a named instance as the value for the Database server with port number or instance
name property.
To connect to a named instance, you must specify the instance name as a JDBC URL
property or a data source property. For example, you can type localhost\instance1. If no
instance name property is specified, a connection to the default instance is created.
Note that the properties specified for the named instance, along with the user ID and
password, and database name, are used to create a JDBC URL. Here is an example:
jdbc:JSQLConnect://localhost\\instance1/user=sa/more properties as required

● If you use an Oracle database, type the appropriate values for the Database server and port
number and Service name properties.

● If you use an advanced Oracle database, for the Database specifier property, type the Oracle
Net8 keyword-value pair for the connection.
Here is an example:
(description=(address=(host=myhost)(protocol=tcp)(port=1521)(connect_data=(sid=(orcl)))))
When you select the advanced Oracle database, IBM Cognos 8 uses enterprise-oriented
Oracle features to select a listener, switch to another listener if the first listener fails, auto-
matically reconnect to the database if the connection fails, balance connection requests
among listeners, and balance connection requests among dispatchers.

● If you use a Sybase database, type the appropriate values for the Database server and port
number and Database name properties.

7. If you want to change the logon credentials, specify a user ID and password:

● Click the Value box next to the User ID and password property and then click the edit
button when it appears.

● Type the appropriate values and click OK.

8. From the File menu, click Save.

The logon credentials are immediately encrypted.

9. Test the connection between Content Manager and the content store.

Installation and Configuration Guide 105

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Tip: From the Actions menu, click Test to test the connection between Content Manager and
the content store.
Content Manager connects to the database, checks the database permissions, and creates and
populates a table. The table is not deleted and is used each time that the test is repeated.

Content Manager can now create the required tables in the content store when you start the IBM
Cognos 8 service for the first time. If the connection properties are not specified correctly, the tables
are not created and you cannot connect to IBM Cognos Connection.
If you are upgrading from ReportNet, Content Manager can now access the required tables in the
content store that you used for ReportNet.

Specify a Mail Server Account

If you want to send reports by email, you must configure a mail server account.
If you send reports by email, you must change the host name portion of the Gateway URI from
localhost to either the IP address of the computer or the computer name. Otherwise the URL in the
email will contain localhost and remote users will not be able to open the report.

Steps
1. In the Explorer window, under Data Access, click Notification.

2. In the Properties window, for the SMTP mail server property, type the host name and port of
your SMTP (outgoing) mail server.

Tip: To be able to open reports that are sent by email, you must change the host name portion
of the Gateway URI from localhost to either the IP address of the computer or the computer
name. Otherwise the URL in the email will contain localhost and remote users will not be able
to open the report.

3. Click the Value box next to the Account and password property and then click the edit button
when it appears.

4. Type the appropriate values in the Value - Account and password dialog box and then click
OK.

Tip: If logon credentials are not required for the SMTP server, remove the default information
for the Account and password property. When you are prompted for confirmation to leave this
property blank, click Yes. Ensure that the default user name has been removed. Otherwise, the
default account is used and notifications will not work properly.

5. In the Properties window, type the appropriate value for the default sender account.

6. Test the mail server connections. In the Explorer window right-click Notification and click
Test.
Cognos 8 tests the mail server connection.

If you do not plan to send reports by email, or do not want to set up a mail server account immedi-
ately, you are not required. However, when you save the configuration and then you start the services

106 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

in IBM Cognos Configuration, you will see a warning message when the mail server connection is
tested. You can safely ignore the warning.

Configure Environment Properties for Content Manager Computers

After installing Content Manager on the computers you are using for failover protection, you must
configure Content Manager on those computers. If you installed more than one Content Manager,
you must list all Content Manager URIs on each Content Manager computer. In addition, we
recommend that you specify the server name or an IP address in the URI properties that are used
by IBM Cognos 8. By default, the URI properties specify localhost.
After you complete the required configuration tasks, the certificate authority service is available to
issue certificates to other IBM Cognos computers. You can then perform the required configuration
tasks on other computers, such as the Application Tier Components computer and gateway com-
puters. Otherwise you can continue to configure the Content Manager computers by changing the
default property settings (p. 187) so that they better suit your environment. For example, you can
configure IBM Cognos 8 components to use an authentication provider (p. 149), enable and disable
services (p. 199) on the Content Manager computers, or change global settings (p. 225).

Important: If you change global settings on one Content Manager computer, you must make the
same changes on the other Content Manager computers.

Steps for the First Content Manager Computer

1. On the Content Manager computer that you want to designate as the default active Content
Manager, start IBM Cognos Configuration.

Tip: We recommend that you use the computer with the highest processor speed for the default
active Content Manager.

2. In the Explorer window, click Environment.

3. In the Properties window, change the localhost portion of all URI properties to the name or IP
address of your IBM Cognos 8 servers, by doing the following:

● For Dispatcher URIs for gateway and Content Manager URIs, click the value and then
click the edit button. Change the localhost portion and then click OK.

● For all other URI properties, click the value and change the localhost portion.

4. Click the value for Content Manager URIs and then click the edit button.

5. Specify the URIs for the other Content Manager computers:

● In the Value - Content Manager URIs dialog box, click Add.

● In the blank row of the table, click and then type the full URI of the Content Manager
computer.
Do not delete the first value in the table. This value identifies the local Content Manager
computer and is required.

● Repeat the previous two bulleted steps for each URI to be added.

Important: You must include all Content Manager URIs in the list.

Installation and Configuration Guide 107

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

● Click OK.

6. In the Explorer window, under Security, click Cryptography.

7. In the Properties window, under CSK settings, set Store symmetric key locally to True.

8. From the File menu, click Save.

Steps for Standby Content Manager Computers

1. Ensure that you already configured the Environment properties on at least one Content Manager
computer and that IBM Cognos 8 components are running on that computer.

2. On the standby Content Manager computer, start IBM Cognos Configuration.

3. In the Explorer window, click Environment.

4. In the Properties window, change the localhost portion of all URI properties to the name or IP
address of your IBM Cognos 8 servers, by doing the following:

● For Dispatcher URIs for gateway and Content Manager URIs, click the value and then
click the edit button. Change the localhost portion and then click OK.

● For all other URI properties, click the value and change the localhost portion.

5. Click the value for Content Manager URIs and then click the edit button.

6. Specify the URIs for the other Content Manager computers:

● In the Value - Content Manager URIs dialog box, click Add.

● In the blank row of the table, click and then type the full URI of the Content Manager
computer.
Do not delete the first value in the table. This value identifies the local Content Manager
computer and is required.

● Repeat the previous two bulleted steps for each URI to be added.

Important: You must include all Content Manager URIs in the list.

● Click OK.

7. In the Explorer window, under Security, click Cryptography.

8. In the Explorer window, under Security, Cryptography, click Cognos, the default cryptographic
provider.

9. Under the Certificate Authority settings property group, set the Password property to match
what you configured on the default active Content Manager computer.

10. Ensure that all other cryptographic settings match what you configured on the default active
Content Manager computer.

11. In the Explorer window, under Data Access, Content Manager, click Content Store.

108 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

12. Ensure that the values for all of the properties match what you configured on the default active
Content Manager computer.

13. From the File menu, click Save.

Configure an IBM Cognos Series 7 Namespace in IBM Cognos 8

If you want to migrate security information or secured content from IBM Cognos Series 7 to IBM
Cognos 8, you must configure a namespace in IBM Cognos 8 that is identical to the IBM Cognos
Series 7 namespace.
You can configure multiple namespaces for authentication in IBM Cognos 8. For more information,
see "Configuring IBM Cognos 8 Components to Use an Authentication Provider" (p. 149).

Note: You cannot use an IBM Cognos Series 7 Local Authentication Export (LAE) file for authen-
tication with IBM Cognos 8 components.
We recommend that all IBM Cognos Series 7 namespaces use the same primary IBM Cognos Series 7
Ticket Server. Otherwise, you may receive errors or be prompted for authentication more than
once. To maintain performance, ensure also that the ticket server is running.
If you change the configuration information stored in the directory server used for IBM Cognos
Series 7, you must restart the IBM Cognos 8 service before the changes take effect in the IBM
Cognos installation.
A user must be in at least one Access Manager user class to be able to log on to IBM Cognos 8
components.

Steps
1. In the Explorer window, right-click Authentication and select New Resource, Namespace.

2. In the Name box, type a name for the authentication namespace.

3. In the Type list, click IBM Cognos Series 7 and then click OK.

The new authentication provider resource appears in the Explorer window, under the
Authentication component.

4. In the Resource Properties window, specify the mandatory values.

Certain values must match the values you used when you configured the IBM Cognos Series 7
namespace in Configuration Manager. Under Services, Access Manager - Runtime, Directory
Server, check the values in the Properties window.

● For Namespace ID, specify a unique identifier for the namespace.

● For Host and port, type the same value that you used for the Computer property in Con-
figuration Manager.
The format must be identical. If you use an IP address in IBM Cognos Series 7, type the
same IP address. If you use a network host name in IBM Cognos Series 7, type the same
network host name.

Installation and Configuration Guide 109

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

● For Base Distinguished Name, type the same value that you used for the Base Distinguished
Name (DN) property in Configuration Manager.

● For Namespace name, type the same value that you used for the Default Namespace
property in Configuration Manager.
This value is case sensitive and must match exactly.

5. Specify the values for all other required properties to ensure that IBM Cognos 8 components
can locate and use your existing authentication provider.

If your IBM Cognos Series 7 namespace version is 16.0, ensure that the Data encoding property
is set to UTF-8. In addition, the computers where Content Manager is installed must use the
same locale as the data in the IBM Cognos Series 7 namespace.

6. If your namespace environment includes version 15.2 of the IBM Cognos Series 7 namespace,
you must disable the Series7NamespacesAreUnicode setting.

● In the Properties window, in the Advanced Properties value, click the edit button.

● In the Value - Advanced properties window, click Add.

● In the Name box, type Series7NamespacesAreUnicode.

● In the Value box, type False, and then click OK.

7. In the Properties window, under Cookie settings, ensure that the Path, Domain, and Secure
flag enabled properties match the settings configured for IBM Cognos Series 7.

8. From the File menu, click Save.

Start the IBM Cognos 8 Service on the Content Manager Computer

To register the IBM Cognos 8 service so that users can access it through IBM Cognos Connection,
you must start the services. Before you start the services, test the configuration by using the test
feature in IBM Cognos Configuration.
On Windows, the IBM Cognos 8 service is configured to start automatically by default. On UNIX
and Linux, to start the IBM Cognos 8 process automatically, you must configure the process as a
daemon. For more information, see your operating system documentation.
You must install and configure both the server components of IBM Cognos 8 and Framework
Manager before you can use IBM Cognos 8 for reporting.

Note: IBM Cognos 8 cannot access any reporting data unless the data is first packaged in and
published from Framework Manager.

Steps
1. Start IBM Cognos Configuration.

2. Ensure that you save your configuration, otherwise you cannot start the IBM Cognos 8 service.

3. From the Actions menu, click Test.

110 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

IBM Cognos Configuration checks the common symmetric keys (CSK) availability, tests the
namespace configuration, and tests the connections to the content store, mail server, notification
database, and logging database.

Tip: If Test is not available for selection, in the Explorer window, click Local Configuration.

4. If the test fails, reconfigure the affected properties and then test again.

You can test individual services by right-clicking the service in the Explorer panel and selecting
Test.
Do not start the service until all tests pass.

5. From the Actions menu, click Start.

It may take a few minutes for the IBM Cognos 8 service to start.
This action starts all installed services that are not disabled.

Test Content Manager

You can test your configuration settings by running the test feature as you configure IBM Cognos 8.
You can test the installation of Content Manager by using a Web browser.

Steps
1. Open a Web browser.

2. Test the configuration by typing

http://ContentManagerComputer_name:9300/p2pd/servlet
If the response includes the string State: Running, the dispatcher and Content Manager started
successfully.

Installing and Configuring Application Tier Components on the

PowerPlay Server
You can install Application Tier Components on one or more PowerPlay servers in your environment.
Application Tier Components include PowerPlay BI Server and PowerPlay Administration. Both
components are selected by default.
The Application Tier Components computer must know the location of the Content Manager
computers and the location of the notification database to use for job and schedule information.
If you installed more than one Content Manager, you must list all Content Manager URIs on each
Application Tier Components computer.
Ensure that the computer where you installed the active Content Manager is configured and available
before you configure Application Tier Components computers.
If Content Manager and the Application Tier Components are installed on separate computers, on
the Application Tier Components computer, you must do the following:
❑ Install Application Tier Components.

Installation and Configuration Guide 111

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

❑ Update the Java environment.

❑ Start IBM Cognos Configuration.

❑ Configure environment properties.

❑ Start the IBM Cognos 8 service on the PowerPlay servers.

❑ Test the IBM Cognos 8 migration service.

Other configuration tasks are optional and may be performed later.

Install Application Tier Components on the PowerPlay Server

Use the installation wizard to select Application Tier Components and the location on your computer
where you want to install it. Application Tier Components include PowerPlay BI Server and
PowerPlay Administration.
On UNIX, to run the graphical-mode installation, the console attached to your UNIX computer
must support a Java-based graphical user interface.
On UNIX, IBM Cognos 8 respects the file mode creation mask (umask) of the account running the
installation program. This affects only the installation directories. It does not affect the file permis-
sions within the directories. However, run-time generated files, such as logs, respect the mask. We
recommend umask 022 on the installation directory.
On Windows, ensure that you have administrator privileges for the Windows computer you are
installing on. Also ensure that your computer has a TEMP system variable that points to the directory
where you want to store temporary files. During installation, files from the CD are temporarily
copied to this directory.
To ensure that reports print properly on Windows, Adobe Acrobat requires that you configure at
least one printer on the operating system where Application Tier Components are installed. All
reports, regardless of the print format that you choose, are sent as temporary PDF files to Adobe
Reader for printing.

Steps for UNIX and Linux

1. If you are installing to a directory with other IBM Cognos 8 components, stop the IBM Cognos 8
service.

2. Set the JAVA_HOME environment variable to point to the installation location of your Java
Runtime Environment (JRE).
An example of the installation location of a Java Runtime Environment is /directory/java/java_ver-
sion/jre.
IBM Cognos 8 requires a JVM, such as IBM Java, to run on Linux.

3. On HP-UX, set the _M_ARENA_OPTS environment variable as follows:

_M_ARENA_OPTS 1:4
This increases the memory allocation for HP-UX to more closely match that of other UNIX
platforms.

112 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

4. On AIX, set the AIXTHREAD_SCOPE environment variable as follows:

AIXTHREAD_SCOPE=S
This sets the contention scope for user threads to system-wide, which supports more efficient
scheduling of user threads.

5. Mount the CD for your IBM Cognos product using Rock Ridge file extensions.

6. Go to the directory on the CD that is appropriate for your operating system.

For example, for Solaris, go to the solaris directory.

7. Start the installation wizard:

● If you use XWindows, type

./issetup

Note: When you use the issetup command with XWindows, Japanese characters in messages
and log files may be corrupted. When installing in Japanese on UNIX or Linux, first set
environment variables LANG=C and LC_ALL=C (where C is the language code, for example
ja_JP.PCK on Solaris), and then start the installation wizard.

● If you do not use XWindows, run an unattended installation (p. 283).

8. Select the language to use for the installation.

The language that you select determines the language of the user interface. You can change the
language of the user interface for the product to any of the installed languages after installation.

9. On the Component Selection page, clear all components except Application Tier Components.

Important:
● PowerPlay Administration must be installed with another IBM Cognos 8 component that
includes a dispatcher, preferably PowerPlay BI Server or Application Tier Components
from IBM Cognos 8 Business Intelligence Server.

● Do not select IBM Cognos Series 7 Migration Components, even if IBM Cognos Series 7
components are on the computer. These components must be installed using the instructions
in "Installing and Configuring Migration on IBM Cognos Series 7 Computers" (p. 126).

10. In the Multiple Installation Locations page, specify the IBM Cognos 8 location.
If you are installing on a computer that contains other IBM Cognos 8 PowerPlay components,
install in the same directory. For example, if you installing with IBM Cognos 8 BI Server, install
in the same location where you installed Application Tier Components for IBM Cognos 8 BI
Server. You are prompted for the location of a directory in which to store backup copies of the
files that will be overwritten.
Install IBM Cognos 8 PowerPlay components in a directory that contains only ASCII characters
in the path name. Some UNIX and Linux Web servers do not support non-ASCII characters in
directory names.

11. Follow the directions in the Shortcut Folder and Installation Summary pages.

Installation and Configuration Guide 113

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

12. In the Finish page, click Finish.

13. Append the c8_location/bin directory to the appropriate library path environment variable.
● For Solaris and Linux, LD_LIBRARY_PATH

● For AIX, LIBPATH

● For HP-UX, SHLIB_PATH

14. On Linux, set the PRINTER environment variable to the name of your printer.

If you want users to see product documentation in a language other than English, you must install
the Supplementary Languages Documentation in the same location as the Gateway components.
For more information, see "Install Translated Product Documentation" (p. 145).
To ensure the security and integrity of IBM Cognos 8, it is important to protect the installation
directory from unauthorized or inappropriate access.

Steps for Windows

1. If you are installing to a directory with other IBM Cognos 8 components, stop the IBM Cognos 8
service.

2. Insert the CD for your IBM Cognos product.

The Welcome page of the installation wizard should appear.

If no Welcome page appears, in the win32 directory on the CD, double-click the issetup.exe
file.

3. Select the language to use for the installation.

The language that you select determines the language of the user interface. You can select the
language of the user interface for the product to any of the installed languages after installation.

4. On the Component Selection page, clear all components except Application Tier Components.

Important:
● If you are installing IBM Cognos 8 PowerPlay alone, PowerPlay Administration must
always be installed with PowerPlay BI Server. If you are installing IBM Cognos 8 PowerPlay
with another IBM Cognos 8 Business Intelligence product, PowerPlay Administration must
always be installed with Application Tier Components. PowerPlay Administration cannot
operate without one of these other IBM Cognos 8 components.

● Do not select IBM Cognos Series 7 Migration Components, even if IBM Cognos Series 7
components are on the computer. These components must be installed using the instructions
in "Installing and Configuring Migration on IBM Cognos Series 7 Computers" (p. 126).

5. In the Multiple Installation Locations page, specify the IBM Cognos 8 location.
If you are installing on a computer that contains other IBM Cognos 8 PowerPlay components,
install in the same directory. For example, if you installing with IBM Cognos 8 BI Server, install
in the same location where you installed Application Tier Components for IBM Cognos 8 BI

114 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Server. You are prompted for the location of a directory in which to store backup copies of the
files that will be overwritten.
Install IBM Cognos 8 PowerPlay components in a directory that contains only ASCII characters
in the path name. Some UNIX and Linux Web servers do not support non-ASCII characters in
directory names.

6. Follow the directions in the Shortcut Folder and Installation Summary pages.

7. In the Finish page, click Finish.

If you want users to see product documentation in a language other than English, you must install
the Supplementary Languages Documentation in the same location as the Gateway components.
For more information, see "Install Translated Product Documentation" (p. 145).

Update the Java Environment on the PowerPlay Server

Before you can start the Cognos 8 service, you must set the JAVA_HOME environment variable
and copy the Cognos .jar file to your JRE directory.
If you do not have a JAVA_HOME variable already set on Windows or if JAVA_HOME points to
a Java version that is not valid for IBM Cognos 8, the JRE files provided with the installation will
be used, and you do not have to update any files in your environment.

Steps
1. Ensure that the JAVA_HOME environment variable is set to the JRE location.
For example, to set JAVA_HOME to the JRE files provided with the installation, the path is
c8_location/bin/jre/version.

2. Copy the bcprov-jdknn-nnn.jar file from the c8_location/bin/jre/version/lib/ext directory to the

Java_location/jre/lib/ext directory.

Start IBM Cognos Configuration on the PowerPlay Server

Use IBM Cognos Configuration to configure IBM Cognos 8 components and to start and stop IBM
Cognos services.
Ensure that user or service account is set up. For information, see "Configure a User Account or
Network Service Account for IBM Cognos 8" (p. 44).

Step for Windows

● From the Start menu, click Programs, IBM Cognos 8, IBM Cognos Configuration.

Step for UNIX or Linux

● Go to the c8_location/bin directory and then type

./cogconfig.sh

Installation and Configuration Guide 115

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Configure Environment Properties on PowerPlay Servers

If you install the Application Tier Components component on a different computer than Content
Manager, you must configure the PowerPlay server so that it knows the location of Content Manager
and the notification database used for job and schedule information. The distributed components
can then communicate with each other.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window, click Environment.

3. In the Properties window, click the value for Content Manager URIs and then click the edit
button.

4. Change the localhost portion of the existing URI to the name of any Content Manager computer.

5. Specify the URIs for the remaining Content Manager computers:

● In the Value - Content Manager URIs dialog box, click Add.

● In the blank row of the table, click and then type the full URI of the Content Manager
computer.

● Repeat the previous two bulleted steps for each URI to be added.

Important: You must include all Content Manager URIs in the list.

● Click OK.

6. Change the localhost portion of the Gateway URI property to the name of the computer on
which you plan to install the gateway component.

7. Change the localhost portion of the remaining URI properties to the name or IP address of
your IBM Cognos 8 server.

8. In the Explorer window, under Security, Cryptography, click Cognos, the default cryptographic
provider.

9. Under the Certificate Authority settings property group, set the Password property to match
what you configured on the default active Content Manager computer.

10. Ensure that all other cryptographic settings match what you set on the default active Content
Manager computer.

11. From the File menu, click Save.

116 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Start IBM Cognos 8 Service on the PowerPlay Servers

After you have configured the environment properties, you can start the services on the PowerPlay
servers.

Step
● From the Actions menu, click Start.
It may take a few minutes for the IBM Cognos 8 service to start.
This action starts all installed services that are not disabled.

Test IBM Cognos 8 Migration Service

You can test the installation of the IBM Cognos 8 migration service by checking that the Migration
Assistant icon appears in IBM Cognos Administration.

Steps
1. In IBM Cognos Connection, from the toolbar, click Launch, IBM Cognos Administration.

2. Click the Configuration tab.

3. Click Content Administration.

The migration assistant button appears on the toolbar.

Before you can use the Migration Assistant to migrate IBM Cognos Series 7 content from Upfront,
PowerPlay Enterprise Server, and IBM Cognos Connection, you must install migration components
with IBM Cognos Series 7. For more information about migration content, see the IBM Cognos 8
PowerPlay Migration and Administration Guide.

Installing and Configuring the Gateway Component

You can install the Gateway component on one or more computers, depending on your environment.
The gateway computer must know the location of at least one dispatcher. We recommend using
the dispatcher that is located in Application Tier Components on the PowerPlay server.
Ensure that the computer where you installed the active Content Manager is configured and available
before you configure gateway computers.
If Content Manager and the Gateway component are installed on separate computers, on the
gateway computer, you must do the following:
❑ Install the Gateway component.

❑ Configure the Web server.

❑ Update the Java environment.

❑ Start IBM Cognos Configuration.

❑ Configure environment properties.

❑ Test the gateway computer.

Installation and Configuration Guide 117

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Install the Gateway Component

You can install the gateway on one or more Web server computers. Use the installation wizard to
select Gateway and the location on your computer where you want to install it.
On UNIX, to run the graphical-mode installation the console attached to your UNIX computer
must support a Java-based graphical user interface.
On UNIX, IBM Cognos 8 respects the file mode creation mask (umask) of the account running the
installation program. This affects only the installation directories. It does not affect the file permis-
sions within the directories. However, run-time generated files, such as logs, respect the mask. We
recommend umask 022 on the installation directory.
On Windows, ensure that you have administrator privileges for the Windows computer you are
installing on. Also ensure that your computer has a TEMP system variable that points to the directory
where you want to store temporary files. During installation, files from the CD are temporarily
copied to this directory.

Steps for UNIX and Linux

1. If you are installing to a directory with other IBM Cognos 8 components, stop the IBM Cognos 8
service.

2. Set the JAVA_HOME environment variable to point to the installation location of your Java
Runtime Environment (JRE).
An example of the installation location of a Java Runtime Environment is /directory/java/java_ver-
sion/jre.
IBM Cognos 8 requires a JVM, such as IBM Java, to run on Linux.

3. On HP-UX, set the _M_ARENA_OPTS environment variable as follows:

_M_ARENA_OPTS 1:4
This increases the memory allocation for HP-UX to more closely match that of other UNIX
platforms.

4. On AIX, set the AIXTHREAD_SCOPE environment variable as follows:

AIXTHREAD_SCOPE=S
This sets the contention scope for user threads to system-wide, which supports more efficient
scheduling of user threads.

5. Mount the CD for your IBM Cognos product using Rock Ridge file extensions.

6. Go to the directory on the CD that is appropriate for your operating system.

For example, for Solaris, go to the solaris directory.

7. Start the installation wizard:

● If you use XWindows, type

./issetup

118 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Note: When you use the issetup command with XWindows, Japanese characters in messages
and log files may be corrupted. When installing in Japanese on UNIX or Linux, first set
environment variables LANG=C and LC_ALL=C (where C is the language code, for example
ja_JP.PCK on Solaris), and then start the installation wizard.

● If you do not use XWindows, run an unattended installation (p. 283).

8. Select the language to use for the installation.

The language that you select determines the language of the user interface. You can select the
language of the user interface for the product to any of the installed languages after installation.

9. On the Component Selection page, clear all components except Gateway.

Do not select IBM Cognos Series 7 Migration Components, even if IBM Cognos Series 7
components are on the computer. These components must be installed using the instructions
in "Installing and Configuring Migration on IBM Cognos Series 7 Computers" (p. 126).

10. In the Multiple Installation Locations page, specify the IBM Cognos 8 location.
If you are installing on a computer that contains other IBM Cognos 8 PowerPlay components,
install in the same directory. For example, if you installing with IBM Cognos 8 BI Server, install
in the same location where you installed the Gateway component for IBM Cognos 8 BI Server.
You are prompted for the location of a directory in which to store backup copies of the files
that will be overwritten.
Install IBM Cognos 8 PowerPlay components in a directory that contains only ASCII characters
in the path name. Some UNIX and Linux Web servers do not support non-ASCII characters in
directory names.

11. Follow the directions in the Shortcut Folder and Installation Summary pages.

12. Choose how to proceed in the Finish page:

● If you want to see late-breaking information about IBM Cognos 8, select View the Readme.

● Click Finish.

13. Append the c8_location/bin directory to the appropriate library path environment variable.
● For Solaris and Linux, LD_LIBRARY_PATH

● For AIX, LIBPATH

● For HP-UX, SHLIB_PATH

14. On Linux, set the PRINTER environment variable to the name of your printer.

To ensure the security and integrity of IBM Cognos 8, it is important to protect the installation
directory from unauthorized or inappropriate access.

Installation and Configuration Guide 119

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

If you want users to see product documentation in a language other than English, you must install
the Supplementary Languages Documentation in the same location as the Gateway components.
For more information, see "Install Translated Product Documentation" (p. 145).

Steps for Windows

1. If you are installing to a directory with other IBM Cognos 8 components, stop the IBM Cognos 8
service.

2. Insert the CD for your IBM Cognos product.

The Welcome page of the installation wizard should appear.

If no Welcome page appears, in the win32 directory on the CD, double-click the issetup.exe
file.

3. Select the language to use for the installation.

The language that you select determines the language of the user interface. You can select the
language of the user interface for the product to any of the installed languages after installation.

4. On the Component Selection page, clear all components except Gateway.

Do not select IBM Cognos Series 7 Migration Components, even if IBM Cognos Series 7
components are on the computer. These components must be installed using the instructions
in "Installing and Configuring Migration on IBM Cognos Series 7 Computers" (p. 126).

5. In the Multiple Installation Locations page, specify the IBM Cognos 8 location.
If you are installing on a computer that contains other IBM Cognos 8 PowerPlay components,
install in the same directory. For example, if you installing with IBM Cognos 8 BI Server, install
in the same location where you installed the Gateway component for IBM Cognos 8 BI Server.
You are prompted for the location of a directory in which to store backup copies of the files
that will be overwritten.
Install IBM Cognos 8 PowerPlay components in a directory that contains only ASCII characters
in the path name. Some UNIX and Linux Web servers do not support non-ASCII characters in
directory names.

6. Follow the directions in the Shortcut Folder and Installation Summary pages.

7. In the Finish page,

● If you do not plan to install the IBM Cognos 8 samples and want to configure IBM Cognos
components immediately, click Start IBM Cognos Configuration.

● If you want to see late-breaking information about IBM Cognos components, click View
the Readme.

8. Click Finish.

Use the Windows Start menu to start IBM Cognos Configuration from the shortcut folder.

If you want users to see product documentation in a language other than English, you must install
the Supplementary Languages Documentation in the same location as the Gateway components.
For more information, see "Install Translated Product Documentation" (p. 145).

120 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Configure the Web Server

For all installations, before you use Web pages generated by IBM Cognos 8, you must configure
your Web server. You must create virtual directories, or aliases, so that users can connect to IBM
Cognos 8 in the portal. If you plan to run more than one IBM Cognos 8 product, or several instances
of the same product, on one computer, you must create a separate application pool for each product
or instance and then associate the aliases for that product or instance to the application pool. The
steps for creating an application pool vary depending on your operating system.
On UNIX and Linux, the account under which the Web server runs must have read access to the
cogstartup.xml file in the c8_location/configuration directory. By default the cogstartup.xml file
has read permission for others. If you run your Web server under a specific group, you can change
the cogstartup.xml file permissions to ensure that it belongs to the same group as the Web server.
You can then remove the read permission for others.
For information on creating a user account or a network service account for IBM Cognos 8, see
(p. 44).

Steps to Create Virtual Directories

1. Create the following virtual directories:

Alias Location Permission

cognos8 c8_location/webcontent Read

cognos8/cgi-bin c8_location/cgi-bin Execute

You can use a name other than cognos8 in the aliases. However, you must use cgi-bin as the
second part of the alias and you must change the virtual directory in the Gateway URI property
to match the new IBM Cognos alias. For more information, see "Change a URI" (p. 192).
If you are upgrading from ReportNet, you can continue to use the existing aliases. If you install
IBM Cognos 8 reporting components in a different location from ReportNet, change the
existing aliases to include the new location. If you have more than one version of ReportNet
on one computer, you must use different alias names for IBM Cognos 8.
For Apache Web Server, ensure that you define the cognos8/cgi-bin alias before the cognos8
alias in the httpd.conf file located in the Apache_installation/conf directory. The cognos8/cgi-bin
alias must be defined as a ScriptAlias.

2. If you want to use Report Studio’s image browser, enable Web Distributed Authoring and
Versioning (WebDAV) on your Web server.
If you use Apache Web Server, specify a directory in which to enable WebDAV. For information
about configuring WebDAV, see your Web server documentation.
If you use Microsoft Internet Information Services (IIS), enable the Read and Directory
Browsing properties for the URL you want to access.

3. For IBM Cognos 8 for reporting, set the content expiry on the c8_location/pat/images virtual
directory in your Web server.

Installation and Configuration Guide 121

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Each time a user opens Report Studio, their Web browser checks with the Web server to
determine if images are current. Because there are over 600 images, this can result in excess
network traffic. You can postpone this check until a specified date by using the content expiry
feature of the Web server.
For information on setting content expiry, see the documentation for your Web server.

Note: When you upgrade, Report Studio users must clear their Web browser cache to get the
latest images.

If you use Web aliases other than cognos8, or your Web server is on another computer, or you are
using Microsoft Internet Application Interface (ISAPI), apache_mod or a servlet gateway, change
the Gateway URI (p. 192) when you configure IBM Cognos components.

Steps to Create an Application Pool

1. From the Start menu, select Control Panel, Performance and Maintenance, Administrative
Tools.

2. Launch Internet Information Services (IIS) Manager.

Web Management Tools and World Wide Web Services are enabled.

3. From the root (your system name and user), select Feature View.

4. In the IIS section, launch ISAPI and CGI Restrictions.

5. Select Edit Feature Settings and enable Allow unspecified CGI modules and then click OK.

6. Add your aliases. For example, c8_location and c8_location/cgi-bin.

7. Select your cgi-bin alias and ensure that Feature View is selected.

8. Right-click Application Pools and select Add.

9. In the dialog box, enter a web alias and the corresponding path to IBM Cognos 8 webcontent.

10. Repeat steps 8 and 9 to add the next Web alias.

11. Select Default Web Site.

12. Open Handler Mappings.

13. Select CGI-cgi mappings.

14. In the right pane, click Revert to Inherited.

15. Expand the application that points to your webcontent location.

16. Expand your cgi-bin application node.

17. Add a mapping that points to *.cgi and name it CGI-cgi.

18. Select the CGI-cgi mapping.

19. In the right pane, click Revert to Inherited.

20. Restart the IIS server.

122 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

21. Find the folder that contains cgi-bin (c8_location/cgi-bin) and right-click it.

22. Select the Security tab.

23. Add the Network Services user, granting all permissions except Full Control.

24. Right-click on Cognos8 service and select Properties.

25. Click the Log On tab.

26. Click This account and enter Network Service as the user.

27. Delete the Password and the Confirm the password values.

28. Click OK.

Update the Java Environment on the Gateway Computer

Before you can start the Cognos 8 service, you must set the JAVA_HOME environment variable
and copy the Cognos .jar file to your JRE directory.
If you do not have a JAVA_HOME variable already set on Windows or if JAVA_HOME points to
a Java version that is not valid for IBM Cognos 8, the JRE files provided with the installation will
be used, and you do not have to update any files in your environment.

Steps
1. Ensure that the JAVA_HOME environment variable is set to the JRE location.
For example, to set JAVA_HOME to the JRE files provided with the installation, the path is
c8_location/bin/jre/version.

2. Copy the bcprov-jdknn-nnn.jar file from the c8_location/bin/jre/version/lib/ext directory to the

Java_location/jre/lib/ext directory.

Start IBM Cognos Configuration on the Gateway Computer

Use IBM Cognos Configuration to configure IBM Cognos 8 components and to start and stop IBM
Cognos services.
Ensure that user or service account is set up. For information, see "Configure a User Account or
Network Service Account for IBM Cognos 8" (p. 44).

Step
1. To start IBM Cognos Configuration on a Windows computer, from the Start menu, click Pro-
grams, IBM Cognos 8, IBM Cognos Configuration.

2. To start IBM Cognos Configuration on a UNIX or Linux computer, go to the c8_location/bin

directory and then type

./cogconfig.sh

Installation and Configuration Guide 123

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Configure Environment Properties for Gateway Computers

If you install the gateway component on a different computer than Content Manager or Application
Tier Components, you must configure the gateway computer so that it knows the location of a
dispatcher. A dispatcher is installed on every Content Manager and Application Tier Components
computer. We recommend that the gateway use the dispatcher on a Application Tier Components
computer.
For failover protection, you can configure more than one dispatcher for a gateway computer. When
multiple dispatchers are configured, requests are normally routed to the first dispatcher in the list.
If this dispatcher becomes unavailable, the gateway determines the next functioning dispatcher on
the list and routes requests there. The primary dispatcher status is monitored by the gateway, and
requests are routed back to this component when it returns to service.
After you do the required configuration tasks, the gateway computer can work in your environment.
Ensure that the computers where you installed Content Manager are configured and the default
active Content Manager computer is available before you configure gateway computers.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window, click Environment.

3. In the Properties window, change the localhost portion of all URI properties to the name or IP
address of your IBM Cognos 8 servers, by doing the following:

● For Dispatcher URIs for gateway and Content Manager URIs, click the value and then
click the edit button. Change the localhost portion and then click OK.

● For all other URI properties, click the value and change the localhost portion.

4. Under Gateway Settings, specify the values for Dispatcher URIs for the gateway:
● Click in the value column.

● Click the edit button.

● Change the localhost portion of the URI to the name or IP address of an Application Tier
Components computer.

Note: If you want to send requests to the dispatcher from an SDK application or an IBM
Cognos 8 modeling tool that is outside of a network firewall, we recommend that you
connect to a dedicated gateway that is configured to connect to the dispatcher using the
Internal dispatcher URI for your environment (for example, http://localhost:9300/p2pd/
servlet/dispatch). For security reasons, the default setting for the Dispatcher URI for gateway
property prevents the dispatcher from accepting requests for an SDK application or modeling
tool that is outside the firewall. Ensure that you configure appropriate security for this
dedicated gateway, such as SSL (p. 209). Do not change your main gateway to use the
Internal dispatcher URI. Doing so will reduce the security of the IBM Cognos 8 portal and
studios. For more information about the modeling tool and network firewalls, see the
Installation and Configuration Guide that is provided with your modeling tool.

124 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

● If you want to add another URI, click Add and change the localhost portion of the new
URI to the name or IP address of another Application Tier Components computer.
If you want to use the dispatcher on a standby Content Manager computer, ensure that
you add it after you add the Application Tier Components computers. If you add the dis-
patcher from the active Content Manager computer, ensure that it is last in the list.

Note: To support migration logging, you must specify the dispatcher for the active Content
Manager computer.

● After you specify all the URIs, click OK.

5. In the Explorer window, under Security, Cryptography, click Cognos, the default cryptographic
provider.

6. Under the Certificate Authority settings property group, set the Password property to match
what you configured on the default active Content Manager computer.

7. Ensure that all other cryptographic settings match what you set on the default active Content
Manager computer.

8. Test that the symmetric key can be retrieved. In the Explorer window, right-click Cryptography
and click Test.
IBM Cognos 8 components check the CSK availability.

9. From the File menu, click Save.

Test the Gateway Computer

You can test your configuration settings by running the test feature as you configure IBM Cognos 8.
After you have completed the configuration and started the services, you can test the gateway by
opening the IBM Cognos 8 portal.

Steps
1. Open a Web browser.

2. Open the IBM Cognos 8 portal by typing one of the following, where cognos8 is the virtual
directory you created when you configured the Web server.
● For the CGI gateway:

http://GatewayComputer_name:port/cognos8

● For an ISAPI gateway:

http://GatewayComputer_name:port/cognos8/isapi

● For Apache Connector on Windows:

http://GatewayComputer_name:port/cognos8/cgi-bin/mod_cognos.dll

● For Apache Connector on Solaris or AIX:

http://GatewayComputer_name:port/cognos8/cgi-bin/mod_cognos.so

Installation and Configuration Guide 125

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

● For Apache Connector on HP-UX PA-RISC:

http://GatewayComputer_name:port/cognos8/cgi-bin/mod_cognos.sl

● For Apache Connector on HP-UX IA:

http://GatewayComputer_name:port/cognos8/cgi-bin/mod2_cognos.so

● For a gateway servlet:

http://GatewayComputer_name:port/context_root/servlet/ Gateway

It may take a few minutes for the Web page to open. If you see the Welcome page of the IBM
Cognos 8 portal, your installation is working.

After you complete the initial configuration of IBM Cognos 8 PowerPlay, you can install IBM
Cognos 8 PowerPlay Client (p. 133). You can also customize the components for use in your envir-
onment by changing other settings in IBM Cognos Configuration (p. 187).

PowerPlay Administration
To change runtime settings for IBM Cognos 8 PowerPlay, use IBM Cognos Administration, which
is accessed through the IBM Cognos 8 portal. For example, you can start or stop dispatchers and
services, or set up permissions for users, groups, and roles. For more information, see the Adminis-
tration and Security Guide. You can also configure options for migration and for PowerPlay reports
and cubes. For more information, see the Migration and Administration Guide.

Installing and Configuring Migration on IBM Cognos Series 7

Computers
After installing the IBM Cognos 8 PowerPlay components, you can install IBM Cognos Series 7
migration components to support the migration of PowerPlay content from IBM Cognos Series 7
to IBM Cognos 8 PowerPlay. The IBM Cognos Series 7 migration components are available on
Windows and UNIX, on the IBM Cognos 8 PowerPlay Server CD.
Use the following checklist to guide you through the tasks to install and configure IBM Cognos 8
Migration.
❑ Install IBM Cognos Series 7 migration components.

❑ Configure the IBM Cognos Series 7 migration components, if required.

❑ Start the IBM Cognos Series 7 migration service.

Install IBM Cognos Series 7 Migration Components

Ensure that your IBM Cognos Series 7 installations are working correctly before installing the IBM
Cognos Series 7 migration components. This includes ensuring that the IBM Cognos Series 7
PowerPlay Enterprise Server service and the Upfront services, including the IBM Cognos Upfront
Administration Service, IBM Cognos Upfront Data Store and the IBM Cognos Upfront Dispatcher
services, are running.
You install IBM Cognos Series 7 migration components on the IBM Cognos Series 7 computers.

126 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

● To migrate content from a PowerPlay Enterprise Server you must install IBM Cognos Series 7
migration components on the PowerPlay Enterprise Server computer. If Upfront is located on
the same computer you can also migrate content from Upfront. Installing migration components
on the PowerPlay Enterprise Server computer also supports the migration of PowerPlay content
that was published to Cognos Connection.

● To migrate content from Upfront you must install IBM Cognos Series 7 migration components
on the Upfront computer. When Upfront and PowerPlay Enterprise Server are installed on
separate computers, you must install IBM Cognos Series 7 migration components on the both
the PowerPlay Enterprise Server computer and the Upfront computer. Also, you must set up
and configure a shared network location to support migration processing.

Steps
1. Insert the IBM Cognos 8 PowerPlay Server CD that is appropriate for your operating system.
On UNIX, you must mount the CD using Rock Ridge file extensions.

2. If the Welcome page does not appear, do one of the following:

● On Windows, in the win32 directory on the CD, double-click the issetup.exe file.

● On UNIX, in the directory that is appropriate for your operating system, type

./issetup

3. Select the language to use for the installation.

The language that you select determines the language of the installation wizard.

4. Follow the directions in the installation wizard.

5. On the Component Selection page, clear all components except IBM Cognos Series 7 Migration
Components.

6. In the Multiple Installation Locations page, specify the IBM Cognos Series 7 location to install
the components.
You must install IBM Cognos Series 7 migration components in the same directory as IBM
Cognos Series 7 version 4 (7.4).
If you are prompted for an IBM Cognos 8 installation location, you can accept the default
location or enter a new local location. This location is used to write install files. You do not
have to enter the path to an IBM Cognos 8 installation on a different computer and you do
not require IBM Cognos 8 components on the IBM Cognos Series 7 computer.

7. In the Migration Configuration Information page, for the Migration Service Port Number, type
a port number that the IBM Cognos Series 7 migration service will use. The default is 21567.

8. In the Finish page, click Finish.

Like other IBM Cognos products, the installation process creates log files that include information
such as details about transferred files and installation errors. The log files are located in the
installation_location\instlog directory.

Installation and Configuration Guide 127

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Configure the IBM Cognos Series 7 Migration Service for Migrations from Upfront
in Distributed IBM Cognos Series 7 Installations
If you installed IBM Cognos Series 7 migration components on both a PowerPlay Enterprise Server
computer and a separate Upfront computer, you must set up and configure a shared network location.
The migration service writes temporary files to this location during migration processing.
The following limitations apply for migration from Upfront when PowerPlay Enterprise Server and
Upfront are on separate computers.

Notes
● PowerPlay Enterprise Server and Upfront must access PowerCubes using the same path, such
as \\machine_name\cubes. If the cubes are located on the same computer as PowerPlay Enterprise
Server, PowerPlay Enterprise Server will access the cubes using a local path and Upfront will
access the cubes using a path that includes the PowerPlay Enterprise computer name. Migration
from Upfront will not work in this situation.

● You can not migrate from Upfront if more than one PowerPlay Enterprise Server is used to
publish content to Upfront.

Steps
1. Create a folder in a shared network location that is accessible from both the PowerPlay Enterprise
Server computer and the Upfront computer.
Ensure that the services for PowerPlay Enterprise Server, Upfront, and IBM Cognos Series 7
migration run under named accounts that have write access to the folder.

2. Complete the following steps on each computer that includes IBM Cognos Series 7 migration
components.
● From the installation_location/mig7service, open the migs7service_configuration.xml file
in an XML or text editor.

● Edit the series7-shared-location description line to specify the network location and activate
the line (remove comment tags). For example,
<series7-shared-location description="Path to shared folder">\\bott93\shareT\s7migration</
series7-shared-location>

● Save and close the file.

3. Restart the IBM Series 7 migration service.

The configuration to support migration from separate PowerPlay Enterprise Server and Upfront
computers is complete.

128 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Start the IBM Cognos Series 7 Migration Service

Before you can migrate content from IBM Cognos Series 7 PowerPlay to IBM Cognos 8 PowerPlay,
you must start the migration service for IBM Cognos Series 7. On Windows, the migration service
for IBM Cognos Series 7 starts automatically when it is first installed.

Step
● Start the migration service:

● On Windows, if the service is stopped, then restart the migration service using the IBM
Cognos Migration Series 7 Service entry in the Services list under Administrative Tools.

● On UNIX, go to the c8_location/migs7 directory and start the service by typing

./configure.sh --start

Uninstalling IBM Cognos 8

It is important to use IBM Cognos 8 uninstall programs to remove IBM Cognos 8 products.
If you are running IBM Cognos 8 in an application server environment, use the administration tool
provided by your application server vendor to stop the application if it is running and undeploy
the Java portion of IBM Cognos 8 components. Many application servers do not completely remove
all deployed application files or directories during an undeployment; therefore, you may have to
perform this action manually. After you have undeployed IBM Cognos 8 components, complete
the steps to uninstall on UNIX and on Windows, as required.

Uninstall IBM Cognos 8 on UNIX or Linux

If you no longer require IBM Cognos 8 or if you are upgrading, uninstall IBM Cognos 8.
We recommend that you close all programs before you uninstall IBM Cognos 8. Otherwise, some
files may not be removed.

Steps
1. If the console attached to your computer does not support a Java-based graphical user interface,
determine the process identification (pid) of the IBM Cognos 8 process by typing the following
command:

ps -ef | grep cogbootstrapservice

2. Stop the IBM Cognos 8 process:

● If you run XWindows, start IBM Cognos Configuration, and from the Actions menu, click
Stop.

● If you do not run XWindows, type:

kill -TERM pid

3. To uninstall IBM Cognos 8, go to the c8_location/uninstall directory and type the appropriate
command:

Installation and Configuration Guide 129

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

● If you use XWindows, type

./uninst -u

● If you do not use XWindows, run an unattended uninstall (p. 283).

4. Follow the prompts to complete the uninstallation.

5. Delete all temporary Internet files.

Uninstalling does not remove any files that changed since the installation, such as configuration
and user data files. Your installation location remains on your computer, and you retain these files
until you delete them manually.

Important: Do not delete the configuration and data files if you are upgrading to a new version of
IBM Cognos 8 and you want to use the configuration data with the new version.

Uninstall IBM Cognos 8 on Windows

If you no longer require IBM Cognos 8 or if you are upgrading, uninstall all IBM Cognos 8 com-
ponents and the IBM Cognos 8 service.
If you installed more than one IBM Cognos 8 component or product in the same location, the
uninstall wizard lets you choose the packages to uninstall. All components of the package will be
uninstalled. You must repeat the uninstallation process on each computer that contains IBM
Cognos 8 components.
It is not necessary to back up the configuration and data files on Windows. These files are preserved
during the uninstallation.
We recommend that you close all programs before you uninstall IBM Cognos 8. Otherwise, some
files may not be removed.

Steps
1. From the Start menu, click Programs, IBM Cognos 8, Uninstall IBM Cognos 8.

The Uninstall wizard appears.

Tip: IBM Cognos 8 is the default name of the Program Folder that is created during the
installation. If you chose another name, go to that folder to find the program.

2. Follow the instructions to uninstall the components.

The cognos_uninst_log.txt file records the activities that the Uninstall wizard performs while
uninstalling files. This log file is created in the temp directory.

3. Delete all temporary Internet files.

For more information, see your Web browser documentation.

Uninstalling does not remove any files that changed since the installation, such as configuration
and user data files. Your installation location remains on your computer, and you retain these files
until you delete them using Windows Explorer.

Important: Do not delete the configuration and data files if you are upgrading to a new version of
IBM Cognos 8 and you want to use the configuration data with the new version.

130 PowerPlay®
Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

Uninstall Cognos Content Database

If you want to uninstall only Cognos Content Database and leave other IBM Cognos 8 components
on your computer, you must use the following procedure. After you uninstall Cognos Content
Database you must configure a new content store before you can restart the IBM Cognos 8 service.
If you installed only Cognos Content Database, use another procedure. For information about this
procedure, see "Uninstall IBM Cognos 8 on UNIX or Linux" (p. 88) or "Uninstall IBM Cognos 8
on Windows" (p. 89).

Steps
1. On the computer where you installed Cognos Content Database, go to the c8_location\bin
directory, and type the following command:
● On Windows, type

derby.bat uninstall
This command removes the Cognos Content Database service.

● On UNIX, type

derby.sh stop
This command stops the Cognos Content Database service.

2. In the c8_location directory, delete the derby10.1.2.1 directory.

3. In the c8_location\bin directory, delete the following files:

● On Windows, derby.bat

● On UNIX, derby.sh and derbyenv.sh

4. On Windows, in the c8_location\logs directory, delete the derby.service file.

5. In the c8_location directory, open the cmplst.txt file in a text editor.

6. Remove lines containing Cognos Content Database values. The lines contain CCD and
CMDERBY. For example:
C8BISRVRCCD_version=

C8BISRVRCCD_name=

CCD_version=

CCD_name=

CMDERBY_version=

CMDERBY_name=

Tip: You can also comment the lines out by inserting # at the start of each line.

7. Save the file.

8. Start IBM Cognos Configuration.

9. Under Data Access, Content Manager, do the following:

Installation and Configuration Guide 131

Chapter 7: Installing and Configuring IBM Cognos 8 PowerPlay Server Components in a Distributed Installation

● Delete the Cognos Content Database.

● Configure a new database resource to point to a new content store.

For more information, see "Set Database Connection Properties for the Content Store" (p. 76).

10. Restart IBM Cognos 8.

Uninstall the Migration Components

The IBM Cognos 8 migration components are uninstalled when you uninstall IBM Cognos 8. You
can not uninstall only the migration components from your IBM Cognos 8 installation.
You can uninstall the IBM Series 7 migration components separately from your IBM Cognos Series
7 installation. After you complete the migration from IBM Cognos Series 7, you can choose to
uninstall the migration components from each IBM Cognos Series 7 computer. However, the
migration components are only active during a migration and will not affect your IBM Cognos
Series 7 installation if you choose to not uninstall the migration components.

Step
● On the IBM Cognos Series 7 computers, uninstall the IBM Cognos Report Migration from
Series 7 component.
For more information about uninstalling IBM Cognos Series 7 components, see the IBM Cognos
Series 7 Solution Installation Guide.

132 PowerPlay®
Chapter 8: Installing and Configuring Client and
Modeling Components

After the server components are operating in your IBM Cognos 8 environment, you can add client
and modeling components. This section contains information about installing and configuring IBM
Cognos 8 Business Intelligence PowerPlay Client. Report authors can use IBM Cognos 8 PowerPlay
Client to work disconnected from the network or to do more powerful PowerPlay authoring.
This section also includes information about uninstalling IBM Cognos 8 PowerPlay Client. For
more information, see "Uninstall IBM Cognos 8 PowerPlay Client" (p. 136).
If modelers want to create relational packages or mixed-source packages, you require the IBM
Cognos 8 modeling tool, Framework Manager. If modelers want to build PowerCubes, you require
IBM Cognos 8 Transformer. If modelers want to build PowerCubes from relational sources, you
require both Framework Manager and IBM Cognos 8 Transformer. For information about installing
Framework Manager and IBM Cognos 8 Transformer, see the IBM Cognos 8 Business Intelligence
Installation and Configuration Guide that is provided with your modeling components.
If you are installing on a Windows Vista computer, we recommend that you do not install in the
Program Files directory. Security enhancements in Windows Vista restrict applications from writing
to the Program Files directory during program operations.

Installing and Configuring IBM Cognos 8 PowerPlay Client

This section provides the information you need to install and configure IBM Cognos 8 PowerPlay
Client. IBM Cognos 8 PowerPlay Client lets you view, explore, format, and distribute PowerPlay
reports in the IBM Cognos 8 environment.
If you are upgrading from a previous release of IBM Cognos 8 PowerPlay Client, uninstall the
existing version before installing the latest version. Backup client data such as reports in the
installation location before running the uninstall.
Use the following checklist to guide you through the required tasks to install and configure IBM
Cognos 8 PowerPlay Client:
❑ Install IBM Cognos 8 PowerPlay Client.

❑ Configure IBM Cognos 8 PowerPlay Client.

❑ Test IBM Cognos 8 PowerPlay Client.

Install IBM Cognos 8 PowerPlay Client

Use the installation wizard to install IBM Cognos 8 PowerPlay Client on a Windows computer.
If you are installing on a Windows Vista computer, we recommend that you do not install in the
Program Files directory. Security enhancements in Windows Vista restrict applications from writing
to the Program Files directory during program operations.

Installation and Configuration Guide 133

Chapter 8: Installing and Configuring Client and Modeling Components

You can have IBM Cognos Series 7 PowerPlay for Windows and IBM Cognos 8 PowerPlay Client
on the same computer. This can be useful when migrating reports from IBM Cognos Series 7 to
IBM Cognos 8. When both products are installed on the same computer, file associations are set
up to launch the product that was installed most recently when a PPX or MDC file is accessed. If
you install IBM Cognos Series 7 PowerPlay for Windows after installing IBM Cognos 8 PowerPlay
Client, you can reset the file associations so that PPX and MDC files open in IBM Cognos 8
PowerPlay Client.

Steps to Install
1. Insert the product CD.

2. If the installation wizard does not open automatically, go to the win32 directory, and double-
click issetup.exe.

3. In the Welcome page of the installation wizard, select one of the available languages and then
click Next.
The language you select determines the language of the installation wizard.

4. Accept the license agreement and click Next.

5. In the Installation Location page, specify the IBM Cognos 8 location.

If other IBM Cognos 8 PowerPlay components are installed on the computer, specify the same
directory as the other PowerPlay components. You are prompted for the location of a directory
in which to store backup copies of the files that will be overwritten.
If no other IBM Cognos 8 PowerPlay components are installed on the computer, accept the
default location or specify a new location. If you are installing on Windows Vista, specify a
location outside of the Program Files directory. If you specify a new location, use a directory
name that contains only ASCII characters. Some Web servers do not support non-ASCII char-
acters in directory names.

6. In the User Information page, specify the settings and click Next.

7. In the Product Language Selection page, select the language for the product user interface and
then click Next.
Only one language can be selected per installation. We recommend using a language that
matches the system locale settings. Otherwise, use English. We also recommend setting fonts
to match the system locale. Ensure that the supporting font is installed on the client computer.
For instructions about installing supplementary languages, see the IBM Cognos 8 Supplementary
Languages Installation and Configuration Guide. The following constraints apply for the sup-
plementary languages:
● Although Russian is available in the supplementary languages, it does not apply to IBM
Cognos 8 PowerPlay Client.

● If you are installing multiple IBM Cognos 8 products in a location, you must install the
supplementary languages last.

8. In the Component Selection page, accept the default settings and click Next.

134 PowerPlay®
 Chapter 8: Installing and Configuring Client and Modeling Components

9. Follow the directions in the Shortcut Folder and Installation Summary pages.

10. In the Finish page, do the following:

● If you want to see late-breaking information about IBM Cognos 8 PowerPlay Client, select
View the Readme.

● Click Finish.

Step to Reset File Associations to IBM Cognos 8 PowerPlay Client

● If you install IBM Cognos Series 7 PowerPlay for Windows after you install IBM Cognos 8
PowerPlay Client and you want PPX and MDC files to open in IBM Cognos 8 PowerPlay Client,
run the following command in the c8_client_location\bin directory:

PwrPlay.exe /regserver.

Configure IBM Cognos 8 PowerPlay Client

After you install IBM Cognos 8 PowerPlay Client, you configure it so that it works in your envir-
onment. If you install IBM Cognos 8 PowerPlay Client to use with local PowerCubes only, no
configuration is required.
Configuration is required if you install on a separate computer from the IBM Cognos 8 PowerPlay
server and you want to use remote PowerCubes.
Some configuration tasks are optional. You perform them to change the default property values
used by IBM Cognos 8 PowerPlay Client.
Before you configure IBM Cognos 8 PowerPlay Client we recommend that you install and configure
IBM Cognos 8 server components: Content Manager, application tier components, and gateway.
This ensures that the certificate authority service on the Content Manager computer can issue a
certificate to the IBM Cognos 8 PowerPlay Client and that IBM Cognos 8 PowerPlay Client can
communicate with the gateway.

Steps To Configure Access to PowerPlay Server for Remote PowerCubes

1. On the computer where you installed IBM Cognos 8 PowerPlay Client, start IBM Cognos
Configuration.

2. In the Explorer window, click Environment.

3. In the Properties window, in the Gateway URI box, change the host name portion from localhost
to either the IP address or network host name of the gateway computer.

4. Specify the value for the Dispatcher URI for external applications.
● If your Web server is configured not to allow anonymous access, type the URI of the dis-
patcher on the Web server, ensuring that you change the host name in the URI from local-
host.

● If your Web server is inside the firewall, type the URI of the dispatcher on a Web server
outside the firewall, ensuring that you change the host name in the URI from localhost.

Installation and Configuration Guide 135

Chapter 8: Installing and Configuring Client and Modeling Components

● If you are using a dedicated gateway for IBM Cognos 8 PowerPlay Client communication,
type the URI of the dispatcher on the dedicated gateway.

5. If you changed the default password on the Content Manager computer, do the following:

● In the Explorer window, under Cryptography, click Cognos.

● Under the Certificate Authority settings property group, for the Password property, type
the same password you configured on the default active Content Manager computer.

6. From the File menu, click Save.

Test the Installation

You can test the IBM Cognos 8 PowerPlay Client installation by opening PowerPlay.

Step
● From the Start menu, under Programs, IBM Cognos 8, click PowerPlay 8.

If the Welcome page for PowerPlay appears, the installation is successful.

Uninstall IBM Cognos 8 PowerPlay Client

Uninstall IBM Cognos 8 PowerPlay Client when you want to change the language or if you no
longer require it. It is important to use IBM Cognos 8 uninstall programs to remove IBM Cognos 8
products. Do not use the Windows Add or Remove Programs tools.
Uninstalling does not remove any files that changed since the installation, such as configuration
and user data files. Your installation location remains on your computer, and you retain these files
until you delete them manually.
We recommend that you close all programs before you uninstall IBM Cognos 8 products. Otherwise,
some files may not be removed.

Steps
1. From the Start menu, click Programs, IBM Cognos 8, Uninstall IBM Cognos 8, Uninstall IBM
Cognos 8.

Uninstall Wizard appears.

Tip: IBM Cognos 8 is the default name of the folder that is created during the installation. If
you chose another name, go to that folder to find the program.

2. Follow the instructions to uninstall the components.

The cognos_uninst_log.txt file records the activities that the Uninstall wizard performs while
uninstalling files. This log file is created in the temp directory.

3. Delete all temporary Internet files.

For more information, see your Web browser documentation.

136 PowerPlay®
Chapter 9: Install and Configure Optional Compon-
ents

Optional components provide extended functionality for users.

After you install and configure IBM Cognos 8 PowerPlay, you can install the following optional
components.
● IBM Cognos 8 Samples

● Translated Product Documentation

● Additional fonts for Japanese and Korean currency symbols

PowerPlay Samples
IBM Cognos 8 provides sample databases that contain sales, marketing, and financial information
for a fictional company named the Great Outdoors Company that sells sporting equipment.
The Great Outdoors samples illustrate product features and technical and business best practices.
You can also use them for experimenting with and sharing report design techniques, and for
troubleshooting.
Before you can use the samples, your IBM Cognos 8 product must be installed, configured, and
running. You must then install the Cognos 8 samples and set up the samples so that users can access
the data.

IBM Cognos 8 PowerPlay Samples

The Great Outdoors samples include PowerCubes, models, and reports that you can use in IBM
Cognos 8 PowerPlay to try the following features:
● Migrate sample cubes and reports from IBM Cognos Series 7 to IBM Cognos 8 PowerPlay
To support migration, some samples must be copied to your IBM Cognos Series 7 PowerPlay
servers.

● View published IBM Cognos 8 PowerPlay reports in PowerPlay Studio and PowerPlay Client

● Drill through from an IBM Cognos 8 PowerPlay report to other reports and cubes

Where to Find the Samples

The samples are available on a separate CD and are described in the related user guides and online
help. To use the samples, you must install and configure them, or contact your administrator to
find out where they are installed.

What Samples Exist

The IBM Cognos 8 PowerPlay samples consist of the following:

Installation and Configuration Guide 137

Chapter 9: Install and Configure Optional Components

● PowerCubes
There is a cube for IBM Cognos Series 7 sample data, a target cube for the IBM Cognos Series 7
cube to drill through, and an IBM Cognos 8 cube created in IBM Cognos 8 Transformer.
The IBM Cognos 8 cube uses updated sample data that ranges from 2004 to 2007. The IBM
Cognos Series 7 cubes use the same samples data that was provided with IBM Cognos Series 7.

● models
There is an IBM Cognos 8 Transformer model for IBM Cognos 8 Great Outdoors. Data sources
for the model are included. If you want to open the model, IBM Cognos 8 Transformer must
be installed.

● reports
There are three sets of identical reports. One set connects to an IBM Cognos Series 7 remote
cube, one set connects to a local IBM Cognos 8 Transformer cube, and one set connects to an
IBM Cognos 8 Transformer cube package.

Install the IBM Cognos 8 Samples

The IBM Cognos 8 samples use data from the Great Outdoors company to illustrate product features
for several studios. To use the samples, install them from the IBM Cognos 8 Business Intelligence
Samples CD. Samples for all supported studios are included.

Steps for UNIX and Linux

1. Mount the CD using Rock Ridge file extensions.

Important: To mount the IBM Cognos CD on HP-UX, do the following:

● Add the pfs_mount directory in your path.
For example,

PATH=/usr/sbin/:$PATH

export PATH

● To start the required NFS daemons and run the daemons in the background, type bg
pfs_mountd and then type bg pfsd

● To mount the drive, type

pfs_mount -t rrip <device><mount_dir> -o xlat=unix

For example,

pfs_mount /dev/dsk/c0t2d0 /cdrom -o xlat=unix

You can now install or copy files as a non-root user using an IBM Cognos CD from this
drive.

● When the installation is complete, type pfs_umount /cdrom and kill the pfsd and pfs_mountd
daemons to unmount the CD.

2. Go to the directory on the CD that is appropriate for your operating system.

138 PowerPlay®
 Chapter 9: Install and Configure Optional Components

3. Start the installation wizard:

● If you use XWindows, type

./issetup

Note: When you use the issetup command with XWindows, Japanese characters in messages
and log files may be corrupted. When installing in Japanese on UNIX or Linux, first set
environment variables LANG=C and LC_ALL=C (where C is the language code, for example
ja_JP.PCK on Solaris), and then start the installation wizard.

● If you do not use XWindows, run an unattended installation.

4. Follow the directions in the installation wizard and copy the required files to your computer.
Install the samples in the same location as the other PowerPlay components. In a distributed
installation, install them on the gateway computer.

5. In the Finish page of the installation wizard, click Finish.

Steps for Windows

1. Insert the CD.

2. Start the installation wizard by clicking issetup.exe.

The Welcome page of the installation wizard appears.

3. Select the language to use for the installation.

The language that you select determines the language of the user interface. You can change the
language to any of the installed languages after installation.

4. Follow the directions in the installation wizard to copy the required files to your computer.
Install the samples in the same location as the other PowerPlay components. In a distributed
installation, install them on the gateway computer.

5. In the Finish page of the installation wizard, click Finish.

6. In IBM Cognos Configuration, save and then start IBM Cognos 8.

Setting Up the IBM Cognos 8 PowerPlay Samples

Before you can use the PowerPlay samples, you must make the data available to the users.
To prepare the IBM Cognos Series 7 data for drill-through examples and migration, you must copy
the IBM Cognos Series 7 PowerCubes and reports to the IBM Cognos Series 7 PowerPlay Enterprise
Server.
Use the following checklist to guide you through the tasks of setting up the samples.
❑ Set up the PowerCube.

❑ Set up reports for use in Cognos Viewer and PowerPlay Studio.

❑ Set up reports for use in PowerPlay Client.

Installation and Configuration Guide 139

Chapter 9: Install and Configure Optional Components

❑ Set up PowerCubes and reports for drill-through examples and migration.

Setting Up the Sample PowerCube

To make the data in the PowerCube available, create a data source connection to the PowerCube
and then create a package that accesses the PowerCube. Test the setup by opening the PowerCube.
Use the following check list to guide you through the tasks.
❑ Connect to the sample PowerCube and publish a package.

❑ Open the sample PowerCube in PowerPlay Studio.

Connect to the Sample IBM Cognos 8 PowerCube and Publish a Package

Before you can open the sample PowerCube in PowerPlay Studio or PowerPlay Client, you must
create a data source connection to the sample PowerCube and then publish a package.
Before you create the data source connection, ensure that
● the IBM Cognos 8 service is running

● you have execute permissions for the Directory secured feature and traverse permissions for
the Administration secured function

● you configured an alias for IBM Cognos 8 on the Web server

Steps
1. Connect to the IBM Cognos 8 portal by typing the following command, where cognos8 is the
virtual directory you created when you configured the Web server.

http://computer_name/cognos8

2. Start IBM Cognos Administration:

● In the Welcome page, click Administer IBM Cognos Content.

● In IBM Cognos Connection, from the toolbar, click Launch, IBM Cognos Administration.

3. In IBM Cognos Administration, click the Configuration tab.

4. Click the new data source button .

5. In the Name box, type great_outdoors_8 and then click Next.

The name must be all lowercase and include the underscore characters.

6. In the Type box, select IBM Cognos PowerCube and then click Next.

7. In the Windows location box, type the path to the great_outdoors_8 PowerCube:

c8_location\webcontent\samples\datasources\cubes\PowerCubes\language\great_outdoors_
8.mdc

8. Click Finish.

9. Select Create a Package, and click OK.

140 PowerPlay®
 Chapter 9: Install and Configure Optional Components

10. In the Package Name box, accept the default name for the package and click Next.

11. Click Finish.

Test the PowerCube in PowerPlay Studio

To test the connection to the sample PowerCube, open the cube in IBM Cognos 8 PowerPlay Studio.

Steps
1. In your Web browser, type the URL to open the IBM Cognos 8 portal:
For example, type

http://servername/cognos8

2. Open PowerPlay Studio:

● In the Welcome page, click Explore my data.

● In IBM Cognos Administration, from the toolbar, click Launch, PowerPlay Studio.

3. Click great_outdoors_8.
The cube that is associated with the great_outdoors_8 package opens in PowerPlay Studio.

If your IBM Cognos environment includes Report Studio, Analysis Studio, Metric Studio, or IBM
Cognos 8 Transformer, you can set up other IBM Cognos samples to use with them. For information
about setting up the other IBM Cognos 8 samples, see the Samples topic in the Installation and
Configuration Guide for your other IBM Cognos 8 products.

Setting Up the Sample Reports for Use in Cognos Viewer and PowerPlay Studio
To make the sample reports available for use in Cognos Viewer and PowerPlay Studio, you can
import the content or publish the reports.
Before you import the content, ensure that you set up the sample PowerCube (p. 140).
Use the following check list to guide you through the tasks.
❑ Import the PowerPlay content.

❑ Open a report in Cognos Viewer or PowerPlay Studio.

Import the PowerPlay Content

You can make the sample reports available for use in Cognos Viewer or PowerPlay Studio by
importing them using a deployment archive. The sample PowerPlay data is packaged in a deployment
archive for PowerPlay and migration and a deployment archive for drill-through examples. You
import the deployment archives in IBM Cognos Administration before users can access the reports.
Another method to make reports available in Cognos Viewer or PowerPlay Studio is to publish
them using PowerPlay Client. For more information, see "Setting Up the Sample Reports for Use
in PowerPlay Client" (p. 144).

Steps for PowerPlay and Migration Samples

1. Go to the c8_location\webcontent\samples\content directory.

Installation and Configuration Guide 141

Chapter 9: Install and Configure Optional Components

2. Copy Cognos_PowerPlay.zip to the c8_location\deployment directory.

3. Open the IBM Cognos 8 portal by typing the following command, where cognos8 is the virtual
directory you created when you configured the Web server.

http://computer_name/cognos8

4. Start IBM Cognos Administration:

● In the Welcome page, click Administer IBM Cognos Content.

● In IBM Cognos Connection, from the toolbar, click Launch, IBM Cognos Administration.

5. Click the Configuration tab.

6. Click Content Administration.

7. Click the new import button .

8. Select Cognos_PowerPlay and click Next.

9. Keep the default name and location and then click Next.

10. Select both folders and click Next.

11. Keep the default options and click Next.

12. Review the summary and then click Next.

13. Keep the default setting, Save and run once, and click Finish.

14. Click Run.

15. Click OK.

Cognos_PowerPlay appears in Administration. Two folders are added to the Public Folders:
Migrated Content and PowerPlay 8 Report samples.

Steps for Drill-through Samples

1. Go to the c8_location\webcontent\samples\content directory.

2. Copy Cognos_DrillThroughSamples.zip to the c8_location\deployment directory.

3. Open the IBM Cognos 8 portal by typing the following command, where cognos8 is the virtual
directory you created when you configured the Web server.

http://computer_name/cognos8

4. Start IBM Cognos Administration:

● In the Welcome page, click Administer IBM Cognos Content.

● In IBM Cognos Connection, from the toolbar, click Launch, IBM Cognos Administration.

5. Click Configuration.

6. Click Content Administration.

142 PowerPlay®
 Chapter 9: Install and Configure Optional Components

7. Click the new import button .

8. Select Cognos_DrillThroughSamples and click Next.

9. Keep the default name and location and then click Next.

10. In the public folders content page, select the Samples folder and click Next.

11. Click Next.

12. Review the summary and then click Next.

13. Keep the default setting, Save and run once, and click Finish.

14. Click Run.

15. Click OK.

Cognos_DrillThroughSamples appears in Administration. Three folders are added to the Public
Folders: Go Data Warehouse (analysis), Go Data Warehouse (query), and Sales and Marketing
(conformed). You must have Analysis Studio or Query Studio installed to view these drill-
through samples.

Test a Sample Report in Cognos Viewer or PowerPlay Studio

You can test the import by opening a sample report in Cognos Viewer or PowerPlay Studio. Cognos
Viewer is the default viewer when you open a report in IBM Cognos Connection.

Steps for Cognos Viewer

1. Open the IBM Cognos 8 portal by typing the following command, where cognos8 is the virtual
directory you created when you configured the Web server.

http://computer_name/cognos8

2. Start IBM Cognos Connection:

● In the Welcome page, click IBM Cognos Content.

● In IBM Cognos Administration, from the toolbar, click Launch, IBM Cognos Connection.

3. In the Public Folders list, select PowerPlay 8 Report samples.

4. Click great_outdoors_8.

5. Click any report in the list.

The report opens in Cognos Viewer.

Steps for PowerPlay Studio

1. Open the IBM Cognos 8 portal by typing the following command, where cognos8 is the virtual
directory you created when you configured the Web server.

http://computer_name/cognos8

2. Start PowerPlay Studio:

Installation and Configuration Guide 143

Chapter 9: Install and Configure Optional Components

● In the Welcome page, click Explore my data.

● In IBM Cognos Administration, from the toolbar, click Launch, PowerPlay Studio.

3. In the Public Folders list, select PowerPlay 8 Report samples.

4. Click More beside the great_outdoors_8 entry.

5. Click View package contents.

6. Click the Open with PowerPlay Studio button for any report in the list.
The report opens in PowerPlay Studio.

Setting Up the Sample Reports for Use in PowerPlay Client

To make the sample reports available in PowerPlay Client, you must copy the reports to the
PowerPlay Client computer or to an accessible location in the network.
Use the following check list to guide you through the tasks.
❑ Copy the sample reports to the PowerPlay Client computers.

❑ Open a report in PowerPlay Client.

Copy the Sample Reports to PowerPlay Client Computers

After you install the IBM Cognos 8 samples, the sample reports are ready for use in PowerPlay
Client. If PowerPlay Client is installed on separate computers, you must copy the sample reports
to the PowerPlay Client computers.
PowerPlay Client users can open the sample reports that are connected to local cubes and try the
features of IBM Cognos 8 PowerPlay. Users can also publish the reports for cube packages in
PowerPlay Client, for use in Cognos Viewer or PowerPlay Studio. For more information, see the
IBM Cognos 8 PowerPlay Client User Guide.

Steps
1. Copy the contents of the following directories to a location on the PowerPlay Client computer:
● c8_location\webcontent\samples\powerplay_reports\powerplay_8\reports_for_local_cubes\
language

● c8_location\webcontent\samples\powerplay_reports\powerplay_8\reports_for_cube_
packages\language

2. Repeat on every PowerPlay Client Computer.

Test a Report in PowerPlay Client

You can test a sample report by opening it in PowerPlay Client.

Steps
1. From the Start menu, click Programs, IBM Cognos 8, IBM PowerPlay 8.

2. In the Welcome page, click Open an existing report.

144 PowerPlay®
 Chapter 9: Install and Configure Optional Components

3. In the Choose a Report dialog box, click the arrow in the Look in box, find the directory, click
the report, and then click Open.
The report opens and the name of the report appears in the title bar of the PowerPlay window.

Set Up the Sample PowerCubes and Reports for Migration

Before you can do a sample migration from IBM Cognos Series 7 to IBM Cognos 8 PowerPlay, you
must copy the IBM Cognos Series 7 PowerCube and sample reports to the PowerPlay Enterprise
Server computer.
After you set up the sample PowerCube and reports, you can migrate the reports. After the migration,
users can then view the reports in Cognos Viewer or PowerPlay Studio. By default, the migrated
reports are in PDF format.
For information about running a migration, see the Migration and Administration Guide.

Steps
1. Go to the c8_location\webcontent\samples\powerplay_reports\powerplay_7\reports_for_remote_
cubes\language directory and copy the entire contents to a location on the IBM Cognos Series 7
computer where PowerPlay Enterprise Server is installed.

2. Go to the c8_location\webcontent\samples\datasources\cubes\PowerCubes\language directory

and copy great_outdoors_7.mdc to a location on the PowerPlay Enterprise Server computer.

3. Add the cube and reports to PowerPlay Enterprise Server.

For more information, see the IBM Cognos Series 7 PowerPlay Enterprise Server Guide.

4. To update the cube mapping, in IBM Cognos Series 7 PowerPlay Client, open each report using
a remote connection to great_outdoors_7.mdc, and then save the report.

The cube and reports are now ready for use in IBM Cognos Series 7.

Install Translated Product Documentation

To access translated user documentation, you must install it from IBM Cognos 8 Supplementary
Languages Documentation.
English product documentation is installed when you install the IBM Cognos 8 gateway component.
The Installation and Configuration Guide, the Quick Start Installation and Configuration Guide,
and the Readme are the exceptions, and are available in all supported languages.
Before installing the Supplementary Languages Documentation, ensure that
● IBM Cognos 8 is installed and configured correctly

● adequate disk space is available to install supplementary languages documentation

You need at least 220 MB of disk space.

Installation and Configuration Guide 145

Chapter 9: Install and Configure Optional Components

● your software environment is supported

Steps
1. In the location where the Gateway component is installed, insert the IBM Supplementary Lan-
guages Documentation CD or go to the directory where the installation files were downloaded
and extracted.
On UNIX or Linux, mount the CD using Rock Ridge file extensions.
On Windows, the installation wizard starts automatically from the product disk.

2. To manually start the installation wizard, go to the operating system directory and do the fol-
lowing:
● On Windows, if no Welcome page appears, double-click the issetup.exe file.

● On UNIX or Linux, type

./issetup

Note: When you use the issetup command with XWindows, Japanese characters may be
corrupted.

3. Follow the instructions in the installation wizard to copy the required files to the same location
where you installed gateway components for IBM Cognos 8.
Install in a directory that contains only ASCII characters in the path name. Some Web servers
do not support non-ASCII characters in directory names.
The supplementary languages documentation components is selected by default.

4. Choose the option you want in the Finish page of the installation wizard.

Install and Configure Additional Language Fonts

To add support for the Japanese Yen or Korean Won character, you must install additional fonts
from IBM Cognos 8 Supplementary Languages Documentation.
The Unicode code point “U+005C” is officially assigned to the backslash. However, in Japan and
Korea, that code point is historically assigned to their currency symbols and many people still prefer
to see a yen or won sign in certain parts of software, for example in file paths. To accommodate
this, you can install the “Andale WT J” and “Andale WT K” fonts.
Before installing the additional fonts, ensure that
● IBM Cognos 8 is installed and configured correctly

● adequate disk space is available to install additional fonts

You need at least 220 MB of disk space.

146 PowerPlay®
 Chapter 9: Install and Configure Optional Components

● your software environment is supported

Steps
1. In the location where Application Tier Components are installed, insert the IBM Cognos 8
Supplementary Languages Documentation CD.
On UNIX or Linux, mount the CD using Rock Ridge file extensions.

2. Go to the directory on the CD that is appropriate for your operating system.

3. Start the installation wizard by typing the following command:

● On Windows,

issetup

● On UNIX or Linux,

./issetup

Note: When you use the issetup command with XWindows, Japanese characters may be
corrupted.

4. Follow the instructions in the installation wizard to copy the required files to the same location
where you installed Application Tier Components.
Install in a directory that contains only ASCII characters in the path name. Some Web servers
do not support non-ASCII characters in directory names.

When you are prompted to select components, clear IBM Cognos 8 Business Intelligence Sup-
plementary Languages Documentation. expand Additional Language Fonts, and then select the
font.
These fonts are copied to the c8_location/bin/fonts directory. This font location is defined in
the Physical fonts location property value in IBM Cognos Configuration under Environment.
If you move the fonts to another location, ensure that the new location is added to the Physical
fonts location property value.
Fonts used to display data in a report are selected using a matching process between the fonts
requested when the report is designed and the fonts that are available when the report is
rendered. For PDF output and charts, this process occurs on the server where all fonts on the
server that generates the report can be used.

5. Choose the option you want in the Finish page of the installation wizard.

After you install the additional fonts, you must configure support for them. For more information,
see "Configure Support for Japanese Yen and Korean Won Characters" (p. 147).

Configure Support for Japanese Yen and Korean Won Characters

For Japanese and Korean currency characters to display correctly, you must define the additional
fonts in the global style sheet.

Installation and Configuration Guide 147

Chapter 9: Install and Configure Optional Components

Before you configure these fonts, you must install them from the IBM Cognos 8 Supplementary
Languages Documentation CD.

Steps to Configure the Fonts for Yen and Won Characters

1. Open the GlobalReportStyles.css style sheet in a text editor.
The GlobalReportStyles.css style sheet is located in the c8_location\bin directory.

2. Enable one of the following sections and modify it as shown below:

● /* For Japanese: */

.pg,

.pp

font-family: 'MS UI Gothic', 'Andale WT J' , Tahoma, arial, geneva,

helvetica, sans-serif;

● /* For Korean: */

.pg,

.pp

font-family: Gulim, 'Andale WT K' , Tahoma, arial, geneva, helvetica,

sans-serif;

The PDF generator uses the first available font on the server and includes all the characters in
the string to be displayed. If you prefer to use other fonts on your server, you can insert them
into the list.

3. Save the GlobalReportStyles.css file.

4. Restart the IBM Cognos 8 server.

Any changes that you make to the style sheet are overwritten if you upgrade IBM Cognos 8. You
must repeat this procedure following an upgrade.

148 PowerPlay®
Chapter 10: Configuring IBM Cognos 8 Compon-
ents to Use an Authentication Provider

IBM Cognos 8 components run with two levels of logon: anonymous and authenticated. By default,
anonymous access is enabled.
You can use both types of logon with your installation. If you choose to use only authenticated
logon, you can disable anonymous access.
For authenticated logon, you must configure IBM Cognos 8 components with an appropriate
namespace for the type of authentication provider in your environment. You can configure multiple
namespaces for authentication and then choose at run time which namespace you want to use. For
more information, see the Administration and Security Guide.
If you upgraded from ReportNet and IBM Cognos 8 detects a previously configured namespace
that is no longer configured, the unconfigured namespace appears in the list of authentication pro-
viders in the Administration portal. You can configure the namespace if you still require the user
account information. Otherwise, you can delete the namespace. For information about deleting the
namespace, see the Administration and Security Guide.
Also, when upgrading from one version to another, you must use the same authentication namespace
for both versions. Otherwise, the new version may not contain the same policies, users, roles, and
groups.
IBM Cognos 8 components support the following types of servers as authentication sources:
● Active Directory Server

● IBM Cognos Series 7

● Custom Authentication Provider

● LDAP

● eTrust SiteMinder

● NTLM

● SAP

If you use more than one Content Manager computer, you must configure identical authentication
providers on each Content Manager computer. This means that the type of authentication provider
you select and the way you configure it must be identical on all computers for all platforms. The
configuration must contain information that is accessible by all Content Manager computers.
When IBM Cognos 8 is installed on a single Linux computer, or when Content Manager is installed
on a Linux computer, IBM Cognos 8 can be configured to use only LDAP V3-compliant directory
servers and custom providers as authentication sources.

Installation and Configuration Guide 149

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Some authentication providers require libraries external to the IBM Cognos 8 environment to be
available. If these libraries are not available on Linux, the authentication provider cannot be initial-
ized.
If you want to configure one of the following as your authentication source, you must install Content
Manager on a non-Linux computer:
● IBM Cognos Series 7 namespace

● Active Directory Server

● NTLM

● eTrust SiteMinder

● SAP BW

If you enable security, you must configure security settings immediately after you complete the
installation and configuration process. For more information, see the Administration and Security
Guide.

Important: We recommend that you do not disable security after you enable it. If you delete a
namespace, the user preferences, My Folders, and My Pages entries are permanently lost. Existing
permission settings will refer to users, groups, or roles that no longer exist. While this does not
affect how the permissions work, a user administering the permission settings may see "unknown"
entries. Because these entries refer to users, groups, and roles which no longer exist, you can safely
delete them.
After you configure an authentication provider for IBM Cognos 8 components, you can enable
single signon between your authentication provider environment and IBM Cognos 8 components.
This means that a user logs on once and can then switch to another application without being asked
to log on again.
Users can select namespaces when they log in to the IBM Cognos 8 portal. You can hide Custom
Java namespaces (p. 162) and eTrust SiteMinder namespaces (p. 181) from users.
To use an authentication provider and to require users to authenticate
❑ Disable anonymous access, if required.

❑ Configure IBM Cognos 8 components to use an authentication provider.

Disable Anonymous Access

By default, IBM Cognos 8 components do not require user authentication. Users can log on
anonymously.
If you want to use authenticated logon only, you can use IBM Cognos Configuration to disable
anonymous access.

Steps
1. In each location where Content Manager is installed, start Cognos Configuration.

2. In the Explorer window, under Security, Authentication, click Cognos.

150 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

The IBM Cognos resource represents the Cognos namespace. The Cognos namespace stores
information about IBM Cognos groups, such as the Anonymous User, contacts, and distribution
lists, and refers to objects in other security namespaces. For more information, see the Admin-
istration and Security Guide.

3. In the Properties window, click the box next to the Allow anonymous access property and then
click False.

4. From the File menu, click Save.

Now, users are required to provide logon credentials when they access IBM Cognos resources.

Restrict User Access to the Cognos Namespace

You can restrict access to users belonging to any group or role defined in the IBM Cognos built-in
namespace. By default, all users belong to several built-in groups or roles. To restrict access, you
must
● enable the property to restrict access

● remove the Everyone group from the IBM Cognos built-in roles and groups

● ensure that authorized users belong to at least one IBM Cognos role or group

Steps
1. On each Content Manager computer, start IBM Cognos Configuration.

2. In the Explorer window, under Security, click Authentication.

3. In the Properties window, change the value of Restrict access to members of the built-in
namespace to True.

4. From the File menu, click Save.

You must now use the portal to remove the Everyone group from the IBM Cognos built-in roles
and groups, and then ensure that authorized users belong to at least one IBM Cognos built-in role
or group.
For information about adding or removing members of an IBM Cognos group or role, see the
Administration and Security Guide.

Configuring IBM Cognos 8 Components to Use Active Directory

Server
If you install Content Manager on a Windows computer, you can configure Active Directory as
your authentication source using an Active Directory namespace.
If you install Content Manager on a UNIX computer, you must instead use an LDAP namespace
to configure Active Directory as your authentication source. If you install Content Manager on
Windows and UNIX computers, you must use an LDAP namespace to configure Active Directory
on all Content Manager computers. When you use an LDAP namespace to authenticate against

Installation and Configuration Guide 151

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Active Directory Server, you are limited to LDAP features only. You do not have access to Active
Directory features such as advanced properties for domains (p. 154) and single signon using Kerberos
delegation (p. 156).
If you install Content Manager on a Linux computer, the same restrictions apply as for UNIX. You
must use an LDAP namespace to configure Active Directory as your authentication source.
For more information, see "Configure an LDAP Namespace for Active Directory Server" (p. 165).
If you want to use Microsoft SQL Server or Microsoft Analysis Server as a data source and use
single signon for authentication, you must use Active Directory as your authentication source.
You cannot connect to the Active Directory Global Catalog, which is a caching server for Active
Directory Server. If the connection uses port 3268, you must change it. By default, Active Directory
Server uses port 389.
To use an Active Directory Server namespace and to set up single signon, do the following:
❑ Configure IBM Cognos 8 components to use an Active Directory Server namespace

❑ Enable secure communication to the Active Directory Server, if required

❑ Enable single signon between Active Directory Server and IBM Cognos 8 components

Configure an Active Directory Namespace

You can use Active Directory Server as your authentication provider.
You also have the option of making custom user properties from the Active Directory Server
available to IBM Cognos 8 components.
For IBM Cognos 8 to work properly with Active Directory Server, ensure that the Authenticated
users group has Read privileges for the Active Directory folder where users are stored.
If you are configuring an Active Directory namespace to support single signon with a Microsoft
SQL Server or Microsoft Analysis Server data source, ensure the following configuration:
● The IBM Cognos 8 gateway is installed on an IIS Web server that is configured for Windows
Integrated Authentication.

● The gateway is assigned to the local intranet Web site in your Web browser.

● Content Manager is installed on a Windows 2000 or Windows 2003 server.

● Content Manager, Application Tier Components, IIS Web server, and the data source server
(Microsoft SQL Server or Microsoft Analysis Server) belong to the Active Directory domain.

● The data source connection for Microsoft SQL Server or Microsoft Analysis Server is configured
for External Namespace and that namespace must be the Active Directory namespace.

For more information about data sources, see the Administration and Security Guide.

Steps
1. On every computer where you installed Content Manager, open IBM Cognos Configuration.

152 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

2. In the Explorer window, under Security, right-click Authentication, and then click New resource,
Namespace.

3. In the Name box, type a name for your authentication namespace.

4. In the Type list, click the appropriate namespace and then click OK.

The new authentication provider resource appears in the Explorer window, under the
Authentication component.

5. In the Properties window, for the Namespace ID property, specify a unique identifier for the
namespace.

6. Specify the values for all other required properties to ensure that IBM Cognos 8 components
can locate and use your existing authentication provider.

7. Specify the values for the Host and port property.

To support Active Directory Server failover, you can specify the domain name instead of a
specific domain controller. For example, use mydomain.com:389 instead of dc1.mydo-
main.com:389.

8. If you want to search for details when authentication fails, specify the user ID and password
for the Binding credentials property.
Use the credentials of an Active Directory Server user who has search and read privileges for
that server.

9. From the File menu, click Save.

10. Test the connection to a new namespace. In the Explorer window, under Authentication, right-
click the new authentication resource and click Test.

IBM Cognos 8 loads, initializes, and configures the provider libraries for the namespace.

Make Custom User Properties for Active Directory Available to IBM Cognos 8
Components
You can use arbitrary user attributes from your Active Directory Server in IBM Cognos 8 compon-
ents. To configure this, you must add these attributes as custom properties for the Active Directory
namespace.
The custom properties are available as session parameters through Framework Manager. For more
information about session parameters, see the Framework Manager User Guide
You can also use the custom properties inside command blocks to configure Oracle sessions and
connections. You can use the command blocks can be used with Oracle light-weight connections
and virtual private databases. For more information, see the Administration and Security Guide.

Steps
1. On every computer where you installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, Authentication, click the Active Directory namespace.

Installation and Configuration Guide 153

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

3. In the Properties window, click in the Value column for Custom properties and click the edit
button.

4. In the Value - Custom properties window, click Add.

5. Click the Name column and type the name you want IBM Cognos 8 components to use for the
session parameter.

6. Click the Value column and type the name of the account parameter in your Active Directory
Server.

7. Repeat steps 4 to 6 for each custom parameter.

8. Click OK.

9. From the File menu, click Save.

Enabling Secure Communication to the Active Directory Server

If you are using an SSL connection to the Active Directory Server, you must copy the certificate
from the Active Directory Server to the Content Manager computer.

Steps
1. On every Content Manager computer, use your Web browser to connect to the Active Directory
Server and copy the CA root certificate to a location on the Content Manager computer.

2. Add the CA root certificate to the certificate store of the account that you are using for the
current IBM Cognos session:
● If you are running the IBM Cognos session under a user account, use the same Web browser
as in step 1 to import the CA root certificate to the certificate store for your user account.
For information, see the documentation for your Web browser.

● If you are running the IBM Cognos session under the local computer account, use Microsoft
Management Console (MMC) to import the CA root certificate to the certificate store for
the local computer.
For information, see the documentation for MMC.

3. In IBM Cognos Configuration, restart the service:

● In the Explorer window, click IBM Cognos 8 service, IBM Cognos 8.

● From the Actions menu, click Restart.

Include or Exclude Domains Using Advanced Properties

When you configure an authentication namespace for IBM Cognos 8, users from only one domain
can log in. By using the Advanced properties for Active Directory Server, users from related (parent-
child) domains and unrelated domain trees within the same forest can also log in.

154 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Authentication in One Domain Tree

If you set a parameter named chaseReferrals to true, users in the original authenticated domain and
all child domains of the domain tree can log in to IBM Cognos 8. Users above the original authen-
ticated domain or in a different domain tree cannot log in.

Authentication in All Domain Trees in the Forest

If you set a parameter named MultiDomainTrees to true, users in all domain trees in the forest can
log in to IBM Cognos 8.

Steps
1. On every computer where you installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, Authentication, click the Active Directory namespace.

3. In the Properties window, specify the Host and port property:

● For users in one domain, specify the host and port of a domain controller for the single
domain.

● For users in one domain tree, specify the host and port of the top-level controller for the
domain tree.

● For users in all domain trees in the forest, specify the host and port of any domain controller
in the forest.

4. Click in the Value column for Advanced properties and click the edit button.

5. In the Value - Advanced properties window, click Add.

6. Specify two new properties, chaseReferrals and MultiDomainTrees, with the following values:

Authentication for chaseReferrals MultiDomainTrees

One domain False False

One domain tree True False

All domain trees in the forest True True

7. Click OK.

8. From the File menu, click Save.

Enabling Single Signon Between Active Directory Server and IBM Cognos 8
Components
By default, the Active Directory provider uses Kerberos delegation and integrates with the IIS Web
server for single signon if Windows integrated authentication (formerly named NT Challenge
Response) is enabled on the IIS Web server.

Installation and Configuration Guide 155

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

If Windows integrated authentication is enabled, you are not prompted to reenter authentication
information when accessing IBM Cognos content that is secured by the Active Directory namespace.
If you do not want Kerberos delegation, you can configure the provider to access the environment
variable REMOTE_USER to achieve single signon. You must set the advanced property
singleSignOnOption to the value IdentityMapping. You must also specify bind credentials for the
Active Directory namespace. Microsoft sets REMOTE_USER by default when you enable Windows
integrated authentication. If Kerberos authentication is bypassed, single signon to Microsoft OLAP
(MSAS) data sources will not be possible.

Steps for Single Signon Using Kerberos Delegation

1. Set up Windows integrated authentication on the IIS Web server.

2. Install Content Manager on a computer that is part of the domain, for the active and standby
Content Manager computers.

3. Set up the computers, or the user account under which Content Manager runs, to be trusted
for delegation.

When setting up the computers using the Active Directory user tool, do not select the Account
attribute, which is sensitive and cannot be delegated.

Steps for Single Signon Using REMOTE_USER

1. On every computer where you installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, Authentication, click the Active Directory namespace.

3. Click in the Value column for Advanced properties and then click the edit button.

4. In the Value - Advanced properties dialog box, click Add.

5. In the Name column, type singleSignOnOption

6. In the Value column, type IdentityMapping.

7. Click OK.

8. Click in the Value column for Binding credentials, and then click the edit button.

9. In the Value - Binding credentials dialog box, specify a user ID and password and then click
OK.

The Active Directory provider now uses REMOTE_USER for single signon.

Tip: To switch back to Kerberos delegation, edit Advanced properties and, in the Value column,
type KerberosAuthentication.

156 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Configuring IBM Cognos 8 to Use IBM Cognos Series 7

Namespace
You can configure IBM Cognos 8 components to use an IBM Cognos Series 7 namespace as the
authentication provider. Users will be authenticated based on the authentication and signon config-
uration of the IBM Cognos Series 7 namespace.
A IBM Cognos Series 7 namespace is required if you want to use IBM Cognos Series 7 PowerCubes
and Transformer models in IBM Cognos 8. You must configure the namespace before you load the
Transformer models.
If you plan to run IBM Cognos 8 products within a 64-bit application server, you cannot configure
an IBM Cognos Series 7 namespace as your authentication source.
If you want to configure an IBM Cognos Series 7 namespace as your authentication source, you
must install Content Manager on a computer that supports IBM Cognos Series 7.

Note: You cannot use an IBM Cognos Series 7 Local Authentication Export (LAE) file for authen-
tication with IBM Cognos 8 components.
You can configure IBM Cognos 8 components to use multiple IBM Cognos Series 7 authentication
providers. We recommend that all IBM Cognos Series 7 namespaces use the same primary IBM
Cognos Series 7 Ticket Server. Otherwise, you may receive errors or be prompted for authentication
more than once. To maintain performance, also ensure that the ticket server is running.
If you change the configuration information stored in the directory server used for IBM Cognos
Series 7, you must restart the IBM Cognos 8 service before the changes take effect in the IBM
Cognos installation.
A user must be in at least one Access Manager user class to log on to IBM Cognos 8 components.
To use an IBM Cognos Series 7 namespace and to set up single signon, do the following:
❑ Configure IBM Cognos 8 to use an IBM Cognos Series 7 namespace

❑ Enable secure communication to the directory server used by the IBM Cognos Series 7
namespace, if required

❑ Enable single signon between IBM Cognos Series 7 and IBM Cognos 8

Configure an IBM Cognos Series 7 Namespace

You can configure IBM Cognos 8 to use one or more IBM Cognos Series 7 namespaces for
authentication.

Steps
1. On every computer where you installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, right-click Authentication, and then click New resource,
Namespace.

3. In the Name box, type a name for your authentication namespace.

4. In the Type list, click the appropriate namespace and then click OK.

Installation and Configuration Guide 157

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

The new authentication provider resource appears in the Explorer window, under the
Authentication component.

5. In the Properties window, for the Namespace ID property, specify a unique identifier for the
namespace.

6. Specify the values for all other required properties to ensure that IBM Cognos 8 components
can locate and use your existing authentication provider.

If your IBM Cognos Series 7 namespace version is 16.0, ensure that the Data encoding property
is set to UTF-8. In addition, the computers where Content Manager is installed must use the
same locale as the data in the IBM Cognos Series 7 namespace.
The host value can be a computer name or an IP address. If you are publishing from PowerPlay
Enterprise Server to IBM Cognos 8, you must use the same value format used in IBM Cognos
Series 7 Configuration Manager for the location of the directory server. For example, if the
computer name is used in IBM Cognos Series 7 Configuration Manager, you must also use the
computer name in IBM Cognos Configuration for IBM Cognos 8.

7. If your namespace environment includes version 15.2 of the IBM Cognos Series 7 namespace,
you must disable the Series7NamespacesAreUnicode setting.

● In the Properties window, in the Advanced Properties value, click the edit button.

● In the Value - Advanced properties window, click Add.

● In the Name box, type Series7NamespacesAreUnicode.

● In the Value box, type False, and then click OK.

8. In the Properties window, under Cookie settings, ensure that the Path, Domain, and Secure
flag enabled properties match the settings configured for IBM Cognos Series 7.

9. From the File menu, click Save.

10. Test the connection to a new namespace. In the Explorer window, under Authentication, right-
click the new authentication resource and click Test.

Enabling Secure Communication to the Directory Server Used by the IBM Cognos
Series 7 Namespace
If you are using an SSL connection to the Directory Server used by the IBM Cognos Series 7
namespace, you must copy the certificate from the Directory Server to each Content Manager
computer.
For more information, see the IBM Cognos Access Manager Administrator Guide and the docu-
mentation for your Directory Server.

Enabling Single Signon Between IBM Cognos Series 7 and IBM Cognos 8
If your IBM Cognos Series 7 namespace has been configured for integration with your external
authentication mechanisms for single signon, the IBM Cognos Series 7 provider will automatically
use this configuration.

158 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

By configuring single signon, you are not prompted to reenter authentication information when
accessing IBM Cognos content that is secured by the IBM Cognos Series 7 namespace.

Steps
1. Ensure that you configured IBM Cognos 8 components to use an IBM Cognos Series 7 namespace
as an authentication provider (p. 157).

2. For IBM Cognos Series 7, start Configuration Manager.

3. Click Open the current configuration.

4. On the Components tab, in the Explorer window, expand Services, Access Manager - Runtime
and click Cookie Settings.

5. In the Properties window, ensure that the Path, Domain, and Secure Flag Enabled properties
match the settings configured for IBM Cognos 8.

6. Save and close Configuration Manager.

7. If the IBM Cognos Series 7 namespace uses the Trusted Signon plug-in for single signon, you
must now define the SaferAPIGetTrustedSignonWithEnv function.

You can now add IBM Cognos Upfront Series 7 NewsBoxes to your IBM Cognos Connection portal
pages.

IBM Cognos Series 7 Namespaces and the IBM Cognos Series 7 Trusted Signon
Plug-in
If the IBM Cognos Series 7 namespace uses the Trusted Signon plug-in for single signon, you must
define the SaferAPIGetTrustedSignonWithEnv function in your plug-in. Then you must recompile
and redeploy the library for single signon to be achieved between IBM Cognos 8 components and
your authentication mechanism.
The SaferAPIGetTrustedSignonWithEnv function is an updated version of the SaferAPIGetTrusted-
Signon function. This update is required because IBM Cognos 8 logon is not performed at the Web
server as is the case for IBM Cognos Series 7 applications. Therefore, it is not possible for the plug-
in to perform a getenv() API call to retrieve Web server environment variables. The plug-in can
request that specific environment variables be removed from the Web server using the SaferAPI-
GetTrustedSignonWithEnv function.
If you are running both IBM Cognos Series 7 and IBM Cognos 8 products using the same plug-in,
both the SaferAPIGetTrustedSignonWithEnv and SaferAPIGetTrustedSignon functions are required.
For information about the SaferAPIGetTrustedSignon function, see the IBM Cognos Series 7 docu-
mentation.

SaferAPIGetTrustedSignonWithEnv Function
For users to be successfully authenticated by Access Manager, OS signons must exist and be enabled
in the current namespace.

Installation and Configuration Guide 159

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

The memory for the returned trustedSignonName and trustedDomainName is allocated internally
in this API. If the function returns SAFER_SUCCESS, Access Manager calls SaferAPIFreeTrusted-
Signon to free the memory allocated.
The memory for the returned reqEnvVarList is allocated internally in this API. If the function returns
SAFER_INFO_REQUIRED, Access Manager calls SaferAPIFreeBuffer() to free the memory allocated.
You must implement both the SaferAPIGetTrustedSignon and SaferAPIFreeBuffer functions to
successfully register the library when SaferAPIGetTrustedSignonWithEnv is implemented. The
function SaferAPIGetError is required only if you want specific error messages returned from your
plug-in.

Syntax
SaferAPIGetTrustedSignonWithEnv(
EnvVar envVar[], /*[IN]*/
char **reqEnvVarList, /*[OUT]*/
void **trustedSignonName, /*[OUT]*/
unsigned long *trustedSignonNameLength, /*[OUT]*/
void **trustedDomainName, /*[OUT]*/
unsigned long *trustedDomainNameLength, /*[OUT]*/
SAFER_USER_TYPE *userType, /*[OUT]*/
void **implementerData); /*[IN/OUT]*/

Parameter Description

[in] envVar An array of environment variable names and values that

were retrieved from the Web server. The end of the array
is represented by an entry with a null envVarName and a
null envVarValue. Note that the first time this API is called,
the envVar array contains only the end of array marker.

[in] reqEnvVarList A string that contains a comma separated list of environ-

ment variable names that are requested by the Safer imple-
mentation. The end of the list must be null-terminated.

[out] trustedSignonName A sequence of bytes that identifies the currently authentic-

ated user. This value does not need to be null-terminated.
This value is mandatory.

[out] trustedSignonNameLength An integer value that indicates the length of the trusted-
SignonName. This length should exclude the null termin-
ator, if there is one. This value is mandatory.

[out] trustedDomainName A sequence of bytes that identifies the domain of the cur-
rently authenticated user. You do not need to null-terminate
this value. If there is no trustedDomainName, the return is
null. This value is optional.

160 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Parameter Description

[out] trustedDomainNameLength An integer value that indicates the length of the trustedDo-
mainName. This length should exclude the null terminator,
if there is one. This value is mandatory and must be set to
zero if there is no trustedDomainName.

[out] userType A value that indicates the type of user that Access Manager
will authenticate. This value is mandatory.
The following return values are required for Access Man-
ager to successfully authenticate users:
SAFER_NORMAL_USER
A named user. OS signons must exist and be enabled in the
current namespace.
SAFER_GUEST_USER
A guest user. A guest user account must exist and be enabled
in the current namespace.
SAFER_ANONYMOUS_USER
An anonymous user. An anonymous user account must
exist and be enabled in the current namespace.

[in/out] implementerData A pointer used to preserve implementation-specific data

between invocations. An invocation occurs every time
Access Manager calls the trusted signon plug-in. This value
is valid only if the trusted signon plug-in was invoked and
you set a value for it.

Configuring IBM Cognos 8 to Use a Custom Authentication

Provider
If you implemented a custom Java authentication provider with your existing security infrastructure,
you can configure IBM Cognos 8 components to use it.
You can use a custom authentication provider to access and authenticate users to an alternate
authentication source. You can also use it as a single signon mechanism to integrate IBM Cognos 8
components with your security infrastructure. You can hide the namespace from users during logon.
For more information, see the Custom Authentication Provider Developer Guide.

Configure a Custom Authentication Namespace

You can configure IBM Cognos 8 components to use a custom authentication namespace. Any
additional configuration for authentication source access, single signon, or custom attributes are
dependent on the custom authentication provider implementation.

Installation and Configuration Guide 161

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Ensure that the versions of Java Runtime Environment and Java SDK that you use are compatible
with each other. If you use supported versions of the JRE and Java SDK that are not compatible
with each other, then the custom Java authentication provider that you configure will not appear
in the list of namespaces in IBM Cognos Configuration.

Steps
1. On every computer where installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, right-click Authentication, and click New resource,
Namespace.

3. In the Name box, type a name for your authentication namespace.

4. In the Type list, click Custom Java Provider and then click OK.

The new authentication provider resource appears in the Explorer window, under the
Authentication component.

5. In the Properties window, for the NamespaceID property, specify a unique identifier for the
namespace.

Tip: Do not use colons (:) in the Namespace ID property.

6. Specify the values for all other required properties to ensure that IBM Cognos 8 can locate and
use your existing authentication provider.

7. From the File menu, click Save.

8. Test the connection to a new namespace. In the Explorer window, under Authentication, right-
click the new authentication resource and click Test.

IBM Cognos 8 loads, initializes, and configures the provider libraries for the namespace.

Hide the Namespace from Users During Login

You can hide namespaces from users during login. You can have trusted signon namespaces without
showing them on the namespace selection list that is presented when users log in.
For example, you may want to integrate single signon across systems but maintain the ability for
customers to authenticate directly to IBM Cognos 8 without being prompted to choose a namespace.

Steps
1. On each computer where you configured a custom Java authentication provider, open IBM
Cognos Configuration.

2. In the Explorer window, under Security, Authentication, click the custom Java authentication
provider.

3. In the Properties window, click the box next to Selectable for authentication and then click
False.

4. From the File menu, click Save.

162 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

The namespace is not shown on the selection list that is presented at login.

Configuring IBM Cognos 8 Components to Use LDAP

You can configure IBM Cognos 8 components to use an LDAP namespace as the authentication
provider. You can use an LDAP namespace for users that are stored in an LDAP user directory,
Active Directory Server, IBM Directory Server, Novell Directory Server, or Sun Java System Directory
Server.
You can also use LDAP authentication with DB2 and Essbase OLAP data sources by specifying the
LDAP namespace when you set up the data source connection. For more information, see the
Administration and Security Guide.
You also have the option of making custom user properties from the LDAP namespace available
to IBM Cognos 8 components.
To bind a user to the LDAP server, the LDAP authentication provider must construct the distin-
guished name (DN). If the Use external identity property is set to True, it uses the External identity
mapping property to try to resolve the user's DN. If it cannot find the environment variable or the
DN in the LDAP server, it attempts to use the User lookup property to construct the DN.
If users are stored hierarchically within the directory server, you can configure the User lookup and
External identity mapping properties to use search filters. When the LDAP authentication provider
performs these searches, it uses the filters you specify for the User lookup and External identity
mapping properties. It also binds to the directory server using the value you specify for the Bind
user DN and password property or using anonymous if no value is specified.
When an LDAP namespace has been configured to use the External identity mapping property for
authentication, the LDAP provider binds to the directory server using the Bind user DN and password
or using anonymous if no value is specified. All users who log on to IBM Cognos 8 using external
identity mapping see the same users, groups, and folders as the Bind user.
If you do not use external identity mapping, you can specify whether to use bind credentials to
search the LDAP directory server by configuring the Use bind credentials for search property. When
the property is enabled, searches are performed using the bind user credentials or using anonymous
if no value is specified. When the property is disabled, which is the default setting, searches are
performed using the credentials of the logged-on user. The benefit of using bind credentials is that
instead of changing administrative rights for multiple users, you can change the administrative
rights for the bind user only.

Important: If you use a DN syntax, such as uid=${userID}, ou=mycompany.com, for the properties
User lookup, External identity mapping, or Bind user DN and password, you must escape all special
characters that are used in the DN. If you use a search syntax, such as (uid=${userID}), for the
properties User lookup or External identity mapping, you must not escape special characters that
are used in the DN.
To use an LDAP namespace and set up single signon, do the following:
❑ Configure IBM Cognos 8 components to use an LDAP namespace

❑ Make custom user properties available to IBM Cognos 8 components, if required

Installation and Configuration Guide 163

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

❑ Enable secure communication to the LDAP server, if required

❑ Enable single signon between LDAP and IBM Cognos 8 components, if required

Configure an LDAP Namespace

You can configure IBM Cognos 8 components to use an LDAP namespace when the users are stored
in an LDAP user directory. The LDAP user directory may be accessed from within another server
environment, such as Active Directory Server or eTrust SiteMinder.
If you are configuring an LDAP namespace for a directory server other than LDAP, see the appro-
priate section:
● For Active Directory Server, see Configure an LDAP Namespace for Active Directory Server.

● For IBM Directory Server, see Configure an LDAP Namespace for IBM Directory Server.

● For Novell Directory Server, see Configure an LDAP Namespace for Novell Directory Server.

● For Sun Java System Directory Server, see Configure an LDAP Namespace for Sun Java System
Directory Server

You can also use LDAP authentication with DB2 and Essbase OLAP data sources by specifying the
LDAP namespace when you set up the data source connection. For more information, see the
Administration and Security Guide.

Steps
1. On every computer where you installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, right-click Authentication, and then click New resource,
Namespace.

3. In the Name box, type a name for your authentication namespace.

4. In the Type list, click the appropriate namespace and then click OK.

The new authentication provider resource appears in the Explorer window, under the
Authentication component.

5. In the Properties window, for the Namespace ID property, specify a unique identifier for the
namespace.

6. Specify the values for all other required properties to ensure that IBM Cognos 8 components
can locate and use your existing authentication provider.

7. If you want the LDAP authentication provider to bind to the directory server using a specific
Bind user DN and password when performing searches, then specify these values.
If no values are specified, the LDAP authentication provider binds as anonymous.

If external identity mapping is enabled, Bind user DN and password are used for all LDAP
access. If external identity mapping is not enabled, Bind user DN and password are used only
when a search filter is specified for the User lookup property. In that case, when the user DN

164 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

is established, subsequent requests to the LDAP server are executed under the authentication
context of the end user.

8. If you do not use external identity mapping, use bind credentials for searching the LDAP dir-
ectory server by doing the following:

● Ensure that Use external identity is set to False.

● Set Use bind credentials for search to True.

● Specify the user ID and password for Bind user DN and password.

If you do not specify a user ID and password, and anonymous access is enabled, the search is
done using anonymous.

9. Check the mapping settings for required objects and attributes.

Depending on the LDAP configuration, you may have to change some default values to ensure
successful communication between IBM Cognos 8 components and the LDAP server.

LDAP attributes that are mapped to the Name property in Folder mappings, Group mappings,
and Account mappings must be accessible to all authenticated users. In addition, the Name
property must not be blank.

10. From the File menu, click Save.

11. Test the connection to a new namespace. In the Explorer window, under Authentication, right-
click the new authentication resource and click Test.

IBM Cognos 8 loads, initializes, and configures the provider libraries for the namespace.

Configure an LDAP Namespace for Active Directory Server

If you configure a new LDAP namespace for use with an Active Directory Server, you must modify
the necessary settings and change the values for all properties of the Active Directory objects.

Steps
1. On every computer where you installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, right-click Authentication, and then click New resource,
Namespace.

3. In the Name box, type a name for your authentication namespace.

4. In the Type list, click the appropriate namespace and then click OK.

The new authentication provider resource appears in the Explorer window, under the
Authentication component.

5. In the Properties window, for the NamespaceID property, specify a unique identifier for the
namespace.

Tip: Do not use colons (:) in the Namespace ID property.

Installation and Configuration Guide 165

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

6. Specify the values for all other required properties to ensure that IBM Cognos 8 components
can locate and use your existing authentication provider.
The following settings are examples:

● For User lookup, specify (sAMAccountName=${userID})

● If you use single signon, for Use external identity, set the value to True.

● If you use single signon, for External identity mapping, specify (sAMAccountName=$
{environment("REMOTE_USER")})
If you want to remove the domain name from the REMOTE_USER variable, specify
(sAMAccountName=${replace(${environment("REMOTE_USER")}, "domain\\","")}).

● For Bind user DN and password, specify user@domain

● For Unique identifier, specify objectGUID

7. If you want the LDAP authentication provider to bind to the directory server using a specific
Bind user DN and password when performing searches, then specify these values.
If no values are specified, the LDAP authentication provider binds as anonymous.

8. If you do not use external identity mapping, use bind credentials for searching the LDAP dir-
ectory server by doing the following:

● Ensure that Use external identity is set to False.

● Set Use bind credentials for search to True.

● Specify the user ID and password for Bind user DN and password.

9. To configure the LDAP advanced mapping properties for use with the Active Directory Server
objects, use the values specified in the following table.

LDAP attributes that are mapped to the Name property in Folder mappings, Group mappings,
and Account mappings must be accessible to all authenticated users. In addition, the Name
property must not be blank.

Mappings LDAP property LDAP value

Folder Object class organizationalUnit,organization,container

Description description

Name ou,o,cn

Group Object class group

Description description

Member member

166 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Mappings LDAP property LDAP value

Name cn

Account Object class user

Business phone telephonenumber

Content locale (leave blank)

Description description

Email mail

Fax/Phone facsimiletelephonenumber

Given name givenname

Home phone homephone

Mobile phone mobile

Name displayName

Pager phone pager

Password unicodePwd

Postal address postaladdress

Product locale (leave blank)

Surname sn

Username sAMAccountName

These mapping properties represent changes based on a default Active Directory Server
installation. If you have modified the schema, you may have to make additional mapping
changes.

10. From the File menu, click Save.

11. Test the connection to a new namespace. In the Explorer window, under Authentication, right-
click the new authentication resource and click Test.

IBM Cognos 8 loads, initializes, and configures the provider libraries for the namespace.

Installation and Configuration Guide 167

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Configure an LDAP Namespace for IBM Directory Server

If you configure a new LDAP namespace for use with an IBM Directory Server, you must modify
the necessary settings and change the values for all properties of the IBM Directory objects.

Steps
1. In each location where you installed Content Manager, open Cognos Configuration.

2. In the Explorer window, under Security, right-click Authentication, and then click New resource,
Namespace.

3. In the Name box, type a name for your authentication namespace.

4. In the Type list, click LDAP, and then click OK.

The new authentication namespace resource appears in the Explorer window, under the
Authentication component.

5. In the Properties window, for the NamespaceID property, specify a unique identifier for the
namespace.

Tip: Do not use colons (:) in the Namespace ID property.

6. Specify the values for all other required properties to ensure that IBM Cognos 8 can locate and
use your existing authentication namespace.

● For User lookup, specify (cn=${userID})

● For Bind user DN and password, specify cn=root

7. If you want the LDAP authentication provider to bind to the directory server using a specific
Bind user DN and password when performing searches, then specify these values.
If no values are specified, the LDAP authentication namespace binds as anonymous.

8. If you do not use external identity mapping, use bind credentials for searching the LDAP dir-
ectory server by doing the following:

● Ensure that Use external identity is set to False.

● Set Use bind credentials for search to True.

● Specify the user ID and password for Bind user DN and password.

9. To configure the LDAP advanced mapping properties for use with IBM Directory Server objects,
use the values specified in the following table.

LDAP attributes that are mapped to the Name property in Folder mappings, Group mappings,
and Account mappings must be accessible to all authenticated users. In addition, the Name
property must not be blank.

Mappings LDAP property LDAP value

Folder Object class organizationalunit,organization,container

168 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Mappings LDAP property LDAP value

Description description

Name ou,o,cn

Group Object class groupofnames

Description description

Member member

Name cn

Account Object class inetorgperson

Business phone telephonenumber

Content locale (leave blank)

Description description

Email mail

Fax/Phone facsimiletelephonenumber

Given name givenname

Home phone homephone

Mobile phone mobile

Name cn

Pager phone pager

Password userPassword

Postal address postaladdress

Product locale (leave blank)

Surname sn

Username uid

Installation and Configuration Guide 169

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

These mapping properties represent changes based on a default IBM Directory Server installation.
If you have modified the schema, you may have to make additional mapping changes.

10. From the File menu, click Save.

Configure an LDAP Namespace for Novell Directory Server

If you configure a new LDAP namespace for use with a Novell Directory Server, you must modify
the necessary settings and change the values for all properties of the Novell Directory objects.

Steps
1. On every computer where you installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, right-click Authentication, and then click New resource,
Namespace.

3. In the Name box, type a name for your authentication namespace.

4. In the Type list, click LDAP and then click OK.

The new authentication namespace resource appears in the Explorer window, under the
Authentication component.

5. In the Properties window, for the NamespaceID property, specify a unique identifier for the
namespace.

Tip: Do not use colons (:) in the Namespace ID property.

6. Specify the values for all other required properties to ensure that IBM Cognos 8 can locate and
use your existing authentication namespace.

● For User lookup, specify (cn=${userID})

● For Bind user DN and password, specify the base DN for an administration user, such as
cn=Admin,0=COGNOS

7. If you want the LDAP authentication provider to bind to the directory server using a specific
Bind user DN and password when performing searches, then specify these values.
If no values are specified, the LDAP authentication namespace binds as anonymous.

8. If you do not use external identity mapping, use bind credentials for searching the LDAP dir-
ectory server by doing the following:

● Ensure that Use external identity is set to False.

● Set Use bind credentials for search to True.

● Specify the user ID and password for Bind user DN and password.

9. To configure the LDAP advanced mapping properties for use with Novell Directory Server
objects, use the values specified in the following table.

170 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

LDAP attributes that are mapped to the Name property in Folder mappings, Group mappings,
and Account mappings must be accessible to all authenticated users. In addition, the Name
property must not be blank.
For users to successfully log in to IBM Cognos Connection, they must have permission to read
the ou and o attributes.

Mappings LDAP property LDAP value

Folder Object class organizationalunit,organization,container

Description description

Name ou,o,cn

Group Object class groupofnames

Description description

Member member

Name cn

Account Object class inetOrgPerson

Business phone telephonenumber

Content locale Language

Description description

Email mail

Fax/Phone facsimiletelephonenumber

Given name givenname

Home phone homephone

Mobile phone mobile

Name cn

Pager phone pager

Password (leave blank)

Installation and Configuration Guide 171

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Mappings LDAP property LDAP value

Postal address postaladdress

Product locale Language

Surname sn

Username uid

These mapping properties represent changes based on a default Novell Directory Server
installation. If you have modified the schema, you may have to make additional mapping
changes.

10. From the File menu, click Save.

Configure an LDAP Namespace for Sun Java System Directory Server

If you configure a new LDAP namespace for use with Sun Java System Directory Server, you must
modify the necessary settings and change the values for all properties of the Sun Java System Dir-
ectory objects.

Steps
1. On every computer where you installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, right-click Authentication, and then click New resource,
Namespace.

3. In the Name box, type a name for your authentication namespace.

4. In the Type list, click LDAP and then click OK.

The new authentication namespace resource appears in the Explorer window, under the
Authentication component.

5. In the Properties window, for the NamespaceID property, specify a unique identifier for the
namespace.

Tip: Do not use colons (:) in the Namespace ID property.

6. Specify the values for all other required properties to ensure that IBM Cognos 8 can locate and
use your existing authentication namespace.
The following settings are examples:

● For User lookup, type (uid=${userID})

● If you use single signon, for Use external identity, set the value to True.

● If you use single signon, for External identity mapping, specify any attribute, such as the
NT user domain ID or the user ID:

172 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

(ntuserdomainid=$environment("REMOTE_USER")})

(uid=${environment("REMOTE_USER")})

● For Unique identifier, type nsuniqueid

7. If you want the LDAP authentication provider to bind to the directory server using a specific
Bind user DN and password when performing searches, then specify these values.
If no values are specified, the LDAP authentication namespace binds as anonymous.

8. If you do not use external identity mapping, use bind credentials for searching the LDAP dir-
ectory server by doing the following:

● Ensure that Use external identity is set to False.

● Set Use bind credentials for search to True.

● Specify the user ID and password for Bind user DN and password.

9. To configure the LDAP advanced mapping properties for use with Sun Java System Directory
Server objects, use the values specified in the following table.

LDAP attributes that are mapped to the Name property in Folder mappings, Group mappings,
and Account mappings must be accessible to all authenticated users. In addition, the Name
property must not be blank.

Mappings LDAP property LDAP value

Folder Object class organizationalUnit,organization

Description description

Name ou,o

Group Object class groupofuniquenames

Description description

Member uniquemember

Name cn

Account Object class inetorgperson

Business phone telephonenumber

Content locale preferredlanguage

Description description

Installation and Configuration Guide 173

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Mappings LDAP property LDAP value

Email mail

Fax/Phone facsimiletelephonenumber

Given name givenname

Home phone homephone

Mobile phone mobile

Name cn

Pager phone pager

Password userPassword

Postal address postaladdress

Product locale preferredlanguage

Surname sn

Username uid

These mapping properties represent changes based on a default Sun Java System Directory
Server installation. If you have modified the schema, you may have to make additional mapping
changes.

10. From the File menu, click Save.

Make Custom User Properties for LDAP Available to IBM Cognos 8 Components
You can use arbitrary user attributes from your LDAP authentication provider in IBM Cognos 8
components. To configure this, you must add these attributes as custom properties for the LDAP
namespace. The custom properties are available as session parameters through Framework Manager.
For more information about session parameters, see the Framework Manager User Guide.
You can also use the custom properties inside command blocks to configure Oracle sessions and
connections. You can use the command blocks with Oracle lightweight connections and virtual
private databases. For more information, see the Administration and Security Guide.

Steps
1. In each location where you installed Content Manager, open Cognos Configuration.

2. In the Explorer window, under Security, Authentication, click the LDAP namespace.

174 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

3. In the Properties window, click in the Value column for Custom properties, and click the edit
button.

4. In the Value - Custom properties window, click Add.

5. Click the Name column, and type the name you want IBM Cognos 8 components to use for
the session parameter.

6. Click the Value column, and type the name of the account parameter in your LDAP authentic-
ation provider.

7. Repeat the preceding two bulleted steps for each custom parameter.

8. Click OK.

9. From the File menu, click Save.

Enable Secure Communication to the LDAP Server

Secure LDAP protocol (LDAPS) encrypts the communication between the Access Manager component
of Content Manager and the directory server. LDAPS prevents sensitive information in the directory
server and the LDAP credentials from being sent as clear text.
To enable LDAPS, install a server certificate that is signed by a certificate authority in the directory
server. Next, create a certificate database to contain the certificates. Finally, configure the directory
server and the IBM Cognos 8 LDAP namespace to use LDAPS.
The server certificate must be a copy of either
● the trusted root certificate and all other certificates that make up the chain of trust for the dir-
ectory server certificate.
The trusted root certificate is the certificate of the root certificate authority that signed the
directory server certificate.

● the directory server certificate only

The certificates must be Base64 encoded in ASCII (PEM) format. All certificates except the trusted
root certificate must not be self-signed.
IBM Cognos 8 works with both the cert8.db and cert7.db versions of the client certificate database.
You must use the certutil tool from Netscape OpenSource toolkit NSS_3_11_4_RTM to create the
certificate database. IBM Cognos 8 does not accept other versions of cert8.db files, including those
from the certutil tool that is provided with Microsoft Active Directory. The appropriate certutil
tool is available from ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_11_4_RTM.
You must also use the NSPR library, which is available from ftp://ftp.mozilla.org/pub/mozilla.org/
nspr/releases/v4.6.7.

Steps
1. Create a directory for the certificate database.

2. Create the certificate database by typing

certutil -N -d certificate_directory

Installation and Configuration Guide 175

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

where certificate_directory is the directory that you created in step 1.

This command creates a cert8.db file and a key3.db file in the new directory.

3. Add the certificate authority (CA) certificate or the directory server certificate to the certificate
database by typing the appropriate command for the type of certificate:
● For a CA certificate, type

certutil -A -n certificate_name -d certificate_directory -i CA.cert -t C,C,C

● For a directory server certificate, type

certutil -A -n certificate_name -d certificate_directory -i server_certificate.cert -t P

where certificate_name is an alias that you assign, such as the CA name or host name; and
server_certificate is the prefix of the directory server certificate file.

4. Copy the certificate database directory to the c8_location/configuration directory on every

computer where Content Manager is installed.

5. Configure the directory server to use LDAPS and restart the directory server.
For more information, see the documentation for the directory server.

6. In each Content Manager location where you configured the LDAP namespace to use the dir-
ectory server, start Cognos Configuration.

7. In the Explorer window, under Security, Authentication, click the LDAP namespace.

8. In the Properties window, for the Host and port property, change the port to the secure LDAPS
port.

For the SSL certificate database property, specify the path to the cert7.db file.

9. In the Explorer window, right-click the LDAP namespace and click Test.
If the test fails, revise the properties, ensuring that the correct certificate is used.

10. From the File menu, click Save.

11. From the Actions menu, click Restart.

12. Repeat steps 6 to 11 on every other computer where Content Manager is installed.

Enabling Single Signon Between LDAP and IBM Cognos 8 Components

You achieve single signon to IBM Cognos 8 components by configuring the External Identity
mapping property.
The External Identity mapping can refer to a CGI environment variable or an HTTP header variable.
In the case of an application server gateway or dispatcher entry pointing to IBM Cognos 8 compon-
ents, the External Identity mapping can refer to the userPrincipalName session variable. The resolved
value of the External Identity mapping property at runtime must be a valid user DN.
When an LDAP namespace is configured to use the External Identity mapping property for
authentication, the LDAP provider binds to the directory server using the Bind user DN and password

176 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

or using anonymous if no value is specified. All users who log on to IBM Cognos 8 using external
identity mapping see the same users, groups, and folders as the Bind user.
If you want IBM Cognos 8 components to work with applications that use Java or application
server security, you can configure the External identity mapping property to obtain the user ID
from the Java user principal. Include the token ${environment("USER_PRINCIPAL")} in the value
for the property. For more information, see the online help for IBM Cognos Configuration.
You can apply limited expression editing to the External Identity mapping property using the replace
operation.

Replace Operation
The replace operation returns a copy of the string with all occurrences of the old substring replaced
by the new substring.
The following rules apply:
● The character \ escapes the characters in the function parameters. Characters such as \ and "
need escaping.

● Nested function calls are not supported.

● Special characters are not supported.

Syntax
${replace(str , old , new)}

Parameter Description

str The string to search.

old The substring to be replaced by the new substring.

new The substring that replaces the old substring.

Examples
${replace(${environment("REMOTE_USER")},"NAMERICA\\",)}
${replace(${environment("REMOTE_USER")},"NAMERICA\\","")}

Configuring IBM Cognos 8 Components to Use eTrust Site-

Minder
You can configure IBM Cognos 8 components to use a Netegrity SiteMinder namespace as the
authentication source, provided that you installed Content Manager on a non-Linux computer.
To configure an authentication provider in an eTrust SiteMinder environment, you configure an
LDAP, NTLM, or Netegrity SiteMinder namespace depending on your eTrust SiteMinder configur-

Installation and Configuration Guide 177

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

ation. Supported eTrust SiteMinder configurations are LDAP, Active Directory Server, and NTLM
user directories.

Note: The authentication provider uses an eTrust SiteMinder SDK to implement a custom agent.
The custom agent deployment requires that you set the Agent Properties in the eTrust SiteMinder
Policy server administration console to support 4.x agents.
If you plan to run IBM Cognos 8 products within a 64-bit application server, you cannot configure
a Netegrity SiteMinder namespace as your authentication source.

If eTrust SiteMinder is Configured For More Than One User Directory

If you configured eTrust SiteMinder for more than one user directory, you must use the Netegrity
SiteMinder namespace. After configuring the Netegrity SiteMinder namespace in IBM Cognos 8,
you must also add a corresponding LDAP, Active Directory Server, or NTLM namespace to the
IBM Cognos configuration for each user directory defined in eTrust SiteMinder.
When configuring a corresponding LDAP namespace, ensure that the External identity mapping
property is enabled and that you include the token REMOTE_USER in the value for the property.
This does not mean that you must configure eTrust SiteMinder to set REMOTE_USER. The IBM
Cognos Netegrity SiteMinder namespace passes user information internally to the corresponding
LDAP namespace when it receives successful user identification from the eTrust SiteMinder envir-
onment.
When configuring a corresponding Active Directory namespace, ensure that the singleSignOnOption
property is set to IdentityMapping. The IBM Cognos Netegrity SiteMinder namespace passes user
information internally to the corresponding LDAP namespace using the REMOTE_USER environ-
ment variable when it receives successful user identification from the eTrust SiteMinder environment.
For more information, see "Enabling Single Signon Between Active Directory Server and IBM
Cognos 8 Components" (p. 155).

If eTrust SiteMinder is Configured With Only One User Directory

If eTrust SiteMinder is configured with only one user directory, the Netegrity SiteMinder namespace
is not required. You can use the user directory as your authentication source by configuring the
appropriate namespace, or you can configure the eTrust SiteMinder provider with one user directory.
For example, if the eTrust SiteMinder user directory is NTML, you can configure IBM Cognos 8
components with an NTLM namespace or configure IBM Cognos 8 components with one Netegrity
SiteMinder namespace, referring to one user directory that is an NTLM namespace.
If the eTrust SiteMinder user directory is Active Directory, you can use an Active Directory namespace
or an LDAP namespace that is configured for use with Active Directory.
If you want to use the user directory as your authentication source directly instead of configuring
a Netegrity SiteMinder namespace, configure the appropriate LDAP (p. 164), Active Directory
(p. 165), or NTLM (p. 181) namespace. In this case, verify the Agent Configuration Object properties
in eTrust SiteMinder Policy Server. Ensure that SetRemoteUser is activated.
When configuring the LDAP namespace, in this case, ensure that the External identity mapping
property is enabled and that you include the token REMOTE_USER in the value for the property.

178 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

When configuring the Active Directory namespace, in this case, ensure that the singleSignOnOption
property is set to IdentityMapping. For more information, see "Enabling Single Signon Between
Active Directory Server and IBM Cognos 8 Components" (p. 155).
To use an eTrust SiteMinder namespace and to set up single signon, do the following:
❑ Configure IBM Cognos 8 components to use a Netegrity SiteMinder namespace

❑ Enable secure communication to the eTrust SiteMinder user directory, if required

❑ Enable single signon between eTrust SiteMinder and IBM Cognos 8

❑ Protect the IBM Cognos Web alias

You can hide the namespace from users during login (p. 162).

Configure a Netegrity SiteMinder Namespace

If you configured eTrust SiteMinder for more than one user directory, you must use the Netegrity
SiteMinder namespace. After adding the Netegrity SiteMinder namespace, you must also add a
corresponding LDAP or NTLM namespace for each user directory.
You can also configure an Netegrity SiteMinder namespace if users are stored in
● an LDAP server

● an NTLM server

● an Active Directory server

Steps
1. On the computer where you installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, right-click Authentication, and click New resource,
Namespace.

3. In the Name box, type a name for your authentication namespace.

4. In the Type list, click the Netegrity SiteMinder namespace and then click OK.

The new authentication provider resource appears in the Explorer window, under the
Authentication component.

5. In the Properties window, for the NamespaceID property, specify a unique identifier for the
namespace.

Tip: Do not use colons (:) in the Namespace ID property.

6. Specify the values for all other required properties to ensure that IBM Cognos 8 components
can locate and use your existing authentication provider.

7. In the Explorer window, under Security, Authentication, right-click the namespace and click
New resource, SiteMinder Policy Server.

8. In the Name box, type a name for the policy server and click OK.

Installation and Configuration Guide 179

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

9. In the Properties window, specify the Host property and any other property values you want
to change.

10. In the Explorer window, right-click the new SiteMinder Policy Server and click New resource,
User directory.

Tip: Configure a user directory for each user directory in the SiteMinder policy server.

11. In the Name box, type a name for the user directory and click OK.

Important: The name of the user directory must match the name that appears on the policy
server.

12. In the Properties window, type a value for the Namespace ID reference property.

13. From the File menu, click Save.

14. Test the connection to a new namespace. In the Explorer window, under Authentication, right-
click the new authentication resource and click Test.

15. Configure a corresponding LDAP, Active Directory, or NTLM namespace for each LDAP,
Active Directory, or NTLM user directory.

Important: Ensure that you use the same value for the Namespace ID property that you use for
the Namespace ID property for the Netegrity SiteMinder namespace.

Enabling Secure Communication to the eTrust SiteMinder User Directory

If you use an SSL connection to the directory server, you must appropriately configure the Cognos
namespace for the user directory.
For more information, see "Configure an LDAP Namespace" (p. 164).

Enable Single Signon Between eTrust SiteMinder and IBM Cognos 8

By configuring single signon, you are not prompted to reenter authentication information.
IBM Cognos 8 components automatically refer to the eTrust SiteMinder session cookie for user
session data.
If the eTrust SiteMinder user directory is LDAP or Active Directory, you must configure the eTrust
SiteMinder user directory to use external identity mapping to the REMOTE_USER environment
variable.
If the eTrust SiteMinder user directory is NTLM, Integrated Windows Authentication is used for
single signon and no additional configuration is required.

Protecting the IBM Cognos Web Alias

Ensure that eTrust SiteMinder is configured correctly to protect the IBM Cognos Web alias.
Use the test tool provided with eTrust SiteMinder to verify that the resource is protected, authentic-
ated, and authorized. For more information, see your eTrust SiteMinder documentation.

180 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Hide the Namespace from Users During Login

You can hide namespaces from users during login. You can have trusted signon namespaces without
showing them on the namespace selection list that is presented when users login.
For example, you may want to integrate single signon across systems but maintain the ability for
customers to authenticate directly to IBM Cognos 8 without being prompted to choose a namespace.

Steps
1. On each computer where you configured an eTrust SiteMinder authentication provider, open
IBM Cognos Configuration.

2. In the Explorer window, under Security,, Authentication, click the Netegrity Siteminder
authentication provider.

3. In the Properties window, click the box next to Selectable for authentication and then click
False.

4. From the File menu, click Save.

The namespace is not shown on the selection list that is presented at login.

Configuring IBM Cognos 8 Components to Use an NTLM

Namespace
You can configure IBM Cognos 8 components to use the Windows native security, NT LAN
Manager (NTLM), as the authentication source.
If you are not using NTLM in your IS environment, you cannot use an NTLM namespace.
If you want to use an NTLM user directory as your authentication source with eTrust SiteMinder,
you must verify the Agent Configuration Object properties in the eTrust SiteMinder Policy Server.
Ensure that SetRemoteUser is activated.
To use NTLM and to set up single signon, do the following:
❑ configure an NTLM namespace

❑ enable single signon between NTLM and IBM Cognos 8 components

Configure an NTLM Namespace

You can configure IBM Cognos 8 components to use an NTLM namespace when users are stored
in an NTLM user directory. The NTLM user directory may also be accessed using an eTrust Site-
Minder authentication provider.

Steps
1. On the computer where you installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, right-click Authentication, and click New resource,
Namespace.

Installation and Configuration Guide 181

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

3. In the Name box, type a name for your authentication namespace.

4. In the Type list, click NTLM and click OK.

The new authentication provider resource appears in the Explorer window, under the
Authentication component.

5. In the Properties window, for the NamespaceID property, specify a unique identifier for the
namespace.

Tip: Do not use colons (:) in the NamespaceID property.

6. Specify the values for all other required properties to ensure that IBM Cognos 8 components
can locate and use your existing authentication provider.

7. From the File menu, click Save.

8. Test the connection to a new namespace. In the Explorer window, under Authentication, right-
click the new authentication resource and click Test.

IBM Cognos 8 loads, initializes, and configures the provider libraries for the namespace.

Enable Single Signon Between NTLM and IBM Cognos 8 Components

By default, the IBM Cognos NTLM provider integrates with the IIS Web server for single signon
if Windows integrated authentication (formerly named NT Challenge Response) is enabled on the
IIS Web server.
If Windows integrated authentication is enabled, you are not prompted to reenter authentication
information when accessing IBM Cognos content that is secured by the NTLM namespace.

Steps
1. Set up Windows integrated authentication on the IIS Web server.

2. Install Content Manager on a computer that is part of the domain, for the active and standby
Content Manager computers.

3. Set up the computers, or the user account under which Content Manager runs, to be trusted
for delegation.

4. Test the connection to a new namespace. In the Explorer window, under Authentication, right-
click the new authentication resource and click Test.

IBM Cognos 8 loads, initializes, and configures the provider libraries for the namespace.

Configuring IBM Cognos 8 to Use SAP

To use an SAP server as your authentication provider, you must use a supported version of SAP BW.
To review an up-to-date list of environments supported by IBM Cognos products, such as operating
systems, patches, browsers, Web servers, directory servers, database servers, and application servers,
visit the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.
html). In addition, Content Manager must be installed on a non-Linux computer.

182 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

In SAP BW, you can assign users to user groups or roles or both. The SAP authentication provider
uses only the roles.
The authorization rights required by the SAP user depend on who uses IBM Cognos 8 components,
users or administrators.

SAP Authorization Settings for IBM Cognos 8 Users

The following authorization objects are required for any IBM Cognos user. Some of the values
shown, such as *, are default values that you may want to modify for your environment.

Authorization object Field Value

S_RFC Activity
Authorization check for RFC
access

Name of RFC to be protected RFC1 RS_UNIFICATION,

SDTX, SH3A, SU_USER,
SYST, SUSO

Type of RFC to be protected FUGR

S_USER_GRP Activity 03
User Master Maintenance: User
Groups

Name of user group *

SAP Authorization Settings for IBM Cognos Administrators

If users will perform administrative tasks and searches for users and roles, the following values
must be added to the S_RFC authorization object in addition to the values listed above for IBM
Cognos 8 users. Some of the values shown, such as *, are default values that you may want to
modify for your environment.

Authorization object Field Value

S_RFC Activity 16
Authorization check for RFC
access

RFC_NAME PRGN_J2EE, SHSS, SOA3

Type of RFC object to be pro- FUGR

tected

Installation and Configuration Guide 183

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

Connectivity Between SAP BW and IBM Cognos 8 on UNIX

To configure connectivity between SAP BW and IBM Cognos 8 components on a UNIX operating
system, ensure that you install the SAP shared library file (provided by SAP) and add it to the library
path environment variable as follows:
● Solaris

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<librfccm.so_directory>

● HP-UX

SHLIB_PATH=$SHLIB_PATH:<librfccm.sl_directory>

● AIX

LIBPATH=$LIBPATH:<librfc.a_directory>

To use SAP and to set up single signon, do the following:

❑ Configure IBM Cognos 8 components to use an SAP namespace

❑ Enable single signon between SAP and IBM Cognos 8 components

Configure an SAP Namespace

You can configure IBM Cognos 8 components to use an SAP server as the authentication source.

Steps
1. On the computer where you installed Content Manager, open IBM Cognos Configuration.

2. In the Explorer window, under Security, right-click Authentication, and click New resource,
Namespace.

3. In the Name box, type a name for your authentication namespace.

4. In the Type list, click SAP and then click OK.

The new authentication provider resource appears in the Explorer window, under the
Authentication component.

5. In the Properties window, for the Namespace ID property, specify a unique identifier for the
namespace.

Tip: Do not use colons (:) in the Namespace ID property.

6. Specify the values for all required properties to ensure that IBM Cognos 8 components can
locate and use your existing authentication provider.

Depending on your environment, for the Host property, you may have to add the SAP router
string to the SAP host name.

7. If the SAP system encodes the contents of cookies, enable the decode tickets feature:

● In the Properties window, for Advanced properties, click the Value and then click the edit
button.

● Click Add.

184 PowerPlay®
 Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

● Enter the name URLDecodeTickets and enter the value true

● Click OK.

All SAP logon tickets will be decoded by the SAP namespace before establishing a connection.

8. From the File menu, click Save.

9. Test the connection to a new namespace. In the Explorer window, under Authentication, right-
click the new authentication resource and click Test.

Enable Single Signon Between SAP and IBM Cognos 8

You can enable single signon between SAP Enterprise Portal and IBM Cognos 8 components as
well as when using the external namespace function of the SAP BW data source connections. To
do so, ensure that you set the following system parameters on the SAP BW server:
● login/accept_sso2_ticket = 1

● login/create_sso2_ticket = 1

● login/ticket_expiration_time = 200

Test the Namespaces

After you configure one or more new namespaces for IBM Cognos 8 components, you can test the
namespaces. The test can occur before or after you start the IBM Cognos 8 service. You can test
all namespaces at the same time or test them individually.

Step to Test All Namespaces

● In the Explorer window, right-click Authentication and click Test.
IBM Cognos 8 components load, initialize, and configure the provider libraries for one
namespace before testing the next namespace.

Tip: To cancel a namespace test, click Cancel. The test stops when the current namespace test
is complete.

Step to Test a Single Namespace

● In the Explorer window, under Authentication, right-click the new authentication resource and
click Test.
IBM Cognos 8 components load, initialize, and configure the provider libraries for the
namespace.

Delete an Authentication Provider

If they are no longer required, you can delete namespaces that you added, or unconfigure namespaces
that IBM Cognos 8 components detected.

Installation and Configuration Guide 185

Chapter 10: Configuring IBM Cognos 8 Components to Use an Authentication Provider

You must not delete the Cognos namespace. It contains authentication data that pertains to all
users and is required to save the configuration.
When you delete a namespace, you can no longer log on to the namespace. Security data for the
namespace remains in Content Manager until you permanently delete it in the portal. For more
information, see the Administration and Security Guide.

Steps
1. In each location where you installed Content Manager, open Cognos Configuration.

2. In the Explorer window, under Security, Authentication, right-click the namespace and click
Delete.

3. Click Yes to confirm.

The namespace disappears from the Explorer window and you can no longer log on to the
namespace on that computer.

4. From the File menu, click Save.

5. Repeat steps 1 to 4 for each computer where you installed Content Manager.
You must now log on to the portal and permanently delete the data for the namespace. For
more information, see the Administration and Security Guide.

After you delete a namespace, it appears as Inactive in the portal.

186 PowerPlay®
Chapter 11: Configuration Options

After configuring IBM Cognos 8 PowerPlay to use one or more authentication providers, you can
further customize it in your environment.
To change runtime settings for IBM Cognos 8 PowerPlay, use IBM Cognos Administration, which
is accessed through the IBM Cognos 8 portal. For example, you can enable or disable dispatchers
and services, or set up permissions for users, groups, and roles. For more information, see the
Administration and Security Guide. You can also configure options for migration and for PowerPlay
reports and cubes. For more information, see the Migration and Administration Guide.
Use the following check list to guide you through the tasks to customize IBM Cognos 8 PowerPlay.
❑ Change default settings

❑ change configuration for the IBM Cognos Series 7 migration service

❑ Assign a user account to the PowerPlay and migration services for migration

❑ Set a user login account for the IBM Cognos 8 service on multiple computers

❑ Create a new content store using Cognos Content Database.

❑ Add security to your communications using the Secure Sockets Layer (SSL) protocol

❑ Add destinations for log messages

❑ Make changes globally for language, fonts, currency, time zones, email encoding, and cookie
domain

❑ Configure the router to test whether a dispatcher is available, if required

❑ Change to an ISAPI, Apache, or servlet gateway for your Web server

❑ Change the IP address protocol

Changing Default Configuration Settings

When you install IBM Cognos 8 components, the installation uses default configuration settings.
If you have any reason not to use these default values, such as a port is being used by another process,
use IBM Cognos Configuration to change the value.
If you change the value of a property, you must save the configuration and then restart the IBM
Cognos 8 service to apply the new settings to your computer.
For distributed installations, ensure that you configured all computers where you installed Content
Manager before you change default configuration settings on other IBM Cognos computers. For
example you can
● change the default user and password for Cognos Content Database

● change the notification database

Installation and Configuration Guide 187

Chapter 11: Configuration Options

● change a URI

● configure cryptographic settings

● configure IBM Cognos 8 components to use IBM Cognos Application Firewall

● configure temporary file properties

● configure the gateway to use a namespace

● enable and disable services

● specify the amount of resources the IBM Cognos 8 service uses

● configure fonts

● configure support for Simplified Chinese

● change the default font for reports

● configure embedded fonts for PDF reports

● save report output to a file system

Change Default User and Password for Cognos Content Database

If you install Cognos Content Database, the default database that is created is given a user ID and
password. We recommend that you change this user ID and password.
Administration tasks for Cognos Content Database are performed using a utility named ij. For
information about this utility, see the Apache Derby documentation. The documentation is available
in the c8_location\derby10.1.2.1\docs directory where you installed Cognos Content Database.

Steps to Change the Default User Password

1. On the computer where you installed Cognos Content Database, go to the c8_loca-
tion\derby10.1.2.1\bin directory.

2. Start the ij utility using the ij.bat or ij.ksh script file.

The ij utility is a command line utility for creating and managing Cognos Content Database.

3. Connect to the default database by typing the following ij utility command:

connect 'jdbc:derby://localhost:1527/cm;user=cognos;password=cognos';
If you changed the port number from the default 1527, use the correct port number for your
Cognos Content Database.
The default database is named cm. The database name is case sensitive.

4. Change the default password for the cognos user by typing the following ij utility command:

CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.user.cognos', 'NewPass-

word');
The new password must be used for the next connection to the database.

188 PowerPlay®
 Chapter 11: Configuration Options

5. Close the ij utility by typing the following command:

disconnect;

Steps to Create a New User and Password

1. On the computer where you installed Cognos Content Database, go to the c8_loca-
tion\derby10.1.2.1\bin directory.

2. Start the ij utility using the ij.bat or ij.ksh script file.

3. Connect to the default database by typing the following ij utility command:

connect 'jdbc:derby://localhost:1527/cm;user=cognos;password=cognos';
If you changed the port number from the default 1527, use the correct port number for your
Cognos Content Database.
The default database is named cm. The database name is case sensitive.

4. Create a new user by typing the following ij utility command:

CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.user.NewUser',
'NewUserPassword');

5. Give the new user full access to the database by typing the following ij utility command:

CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY ('derby.database.fullAcces-

sUsers','cognos, NewUser');
The property that you are changing, the list of users, is a comma-delimited field. In this step,
you are including the new user in the list of users with full access. The default user, cognos, is
still part of the list of users with full access. You can remove the cognos user.

6. Close the ij utility by typing the following command:

disconnect;

Steps to Remove a User

1. On the computer where you installed Cognos Content Database, go to the c8_loca-
tion\derby10.1.2.1\bin directory.

2. Start the ij utility using the ij.bat or ij.ksh script file.

3. Connect to the default database by typing the following ij utility command:

connect 'jdbc:derby://localhost:1527/cm;user=NewUser; password=NewUserPassword';

4. Choose the kind of user that you want to remove:

● To remove a user from the list of users with full access, type the following ij utility command:

CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY ('derby.database.fullAcces-

sUsers', 'NewUser');
You omit the user name from the list of users with full access. For example, the above
command removes the default cognos user and keeps the new user that you just created.

Installation and Configuration Guide 189

Chapter 11: Configuration Options

● To remove a user from the database, type the following ij utility command and omit the
user password:

CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.user.cognos', '');

This command removes the password for the default cognos user, which also removes the
user from the database.

5. Close the ij utility by typing the following command:

disconnect;

Change the Notification Database

By default, the notification server uses the same database that Content Manager uses for the content
store. You can use a separate database for notification in situations where you run large volumes
of batch reports and email.
Using a separate database for notification involves the following tasks:
❑ Create a notification database.
For DB2, Oracle, Microsoft SQL Server, or Sybase, use the same procedure that was used to
create the content store database, "Guidelines for Creating the Content Store" (p. 35).
For DB2 on z/OS, use the instructions in "Suggested Settings for Creating a DB2 Notification
Database on z/OS" (p. 190).

❑ Set up the database connectivity. You can use the same procedure as to set the connectivity for
the content store database, "Set Up Database Connectivity for the Content Store Data-
base" (p. 74).

❑ Change the connection properties for the notification database.

Suggested Settings for Creating a DB2 Notification Database on z/OS

The database you create for the notification database must contain some recommended configuration
settings.
To ensure a successful installation, use the following guidelines when creating the notification
database.
Use the following checklist to help you help you set up the notifications database in DB2 on z/OS.
❑ Create a database instance, storage group, and a user account for the notification database.
A user must have permissions to create and delete tables in the database.
IBM Cognos 8 uses the credentials of the user account to communicate with database server.

❑ Ensure you reserve a buffer pool with a page size of 32 k, and a second one with a page size
of 4 k for the database instance.

❑ Administrators must run a script to create tablespaces to hold Large Objects and other data
for the notification database to use the tablespaces. For information about running the script,
see "Create Tablespaces for the DB2 Notification Database on z/OS" (p. 191).

190 PowerPlay®
 Chapter 11: Configuration Options

❑ Your database administrator must back up IBM Cognos 8 databases regularly because they
contain the IBM Cognos data. To ensure the security and integrity of databases, protect them
from unauthorized or inappropriate access.

Create Tablespaces for the DB2 Notification Database on z/OS

A database administrator must run a script to create a set of tablespaces required for the notification
database. The script must be modified to replace the placeholder parameters with ones that are
appropriate for your environment.
Ensure that you use the naming conventions for DB2 on z/OS. For example, all names of parameters
must start with a letter and the length must not exceed eight characters. For more information, see
the IBM DB2 Information Center.

Steps
1. Using a remote access tool, connect to the database as a user with privileges to create and drop
tablespaces and to allow execution of SQL statements.

2. Open the NC_TABLESPACES.sql script file and use the following table to help you to replace
the placeholder parameters with ones appropriate for your environment.
Not all of the parameters listed are in the script, but may be added in the future.

Parameter Name Description

NCCOG Specifies the name of the notification database.

DSN8G810 Specifies the name of the storage group.

BP32K Specifies the name of the buffer pool.

3. Save and run the script in the remote access tool.

The notification database is created. You can now change the notification database in IBM Cognos
Configuration (p. 191).

Change the Connection Properties for the Notification Database

After you create a separate database for notification, you must configure IBM Cognos 8 to use the
new database.
You must configure all Content Managers and Application Tier Components to use the same
notification database.

Steps
1. In each location where Content Manager or Application Tier Components is installed, start
IBM Cognos Configuration.

2. In the Explorer window, under Data Access, click Notification.

3. Identify the database that is used for notification:

Installation and Configuration Guide 191

Chapter 11: Configuration Options

● In the Explorer window, right-click Notification and select New resource, Database.

● Type a name for the database resource.

● Select the type of database from the pull-down menu.

● Click OK.

4. In the Properties window, enter the values for the notification database resource.

5. From the File menu, click Save.

6. Test the notification. In the Explorer window right-click Notification and click Test.
Cognos 8 tests the database connection and tests the mail server connection.
If you have been using the content store database for notification, the schedules will be replicated
in the tables of the new notification database.

Important: Ensure that the values used to identify the notification database resource are the same
on all Content Manager and Application Tier Components computers. To use the default notification
database, you do not have to edit the values in the Properties window.

Change a URI
You can change certain elements in a URI depending on your environment. An IBM Cognos URI
contains the following elements:
● For a Content Manager URI, Dispatcher URI for external applications, or dispatcher URI
protocol://host_name_or_IP:port/context_root/alias_path

● For a Gateway URI or a Web content URI

protocol://host_name_or_IP:port/virtual_directory/gateway_application
OR
protocol://host_name_or_IP:port/context_root/alias_path

Element Examples Description

protocol http or https Specifies the protocol used to

request and transmit information,
either Hyper Text Transfer Pro-
tocol or Hyper Text Transfer Pro-
tocol (Secure).

192 PowerPlay®
 Chapter 11: Configuration Options

Element Examples Description

host name or IP localhost or 192.168.0.1 Specifies the identity of the host on

the network. You can use an IP
address, a computer name, or a
fully qualified domain name.
In a distributed installation, you
must change the localhost element
of a URI.
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.

port 9300 or 80 Specifies the port on which the host

system listens for requests.
The default port for Tomcat is
9300. The default port for a Web
server is 80.

context root p2pd Used by Tomcat or an application

server to determine the context of
the application so that the request
can be routed to the correct Web
application for processing.

alias path servlet/dispatch Used by the application server to

route a request to the correct com-
ponent within a Web application.
The alias path must not be modi-
fied or IBM Cognos 8 components
will not function properly.

virtual directory cognos8/ Used by the Web server to map a

virtual directory or alias to a phys-
ical location.
For example, in the default
Gateway URI of http://localhost:
80/cognos8/cgi-bin/cognos.cgi, the
virtual directory is cognos8/cgi-bin.

Installation and Configuration Guide 193

Chapter 11: Configuration Options

Element Examples Description

gateway application cognos.cgi Specifies the name of the IBM

Cognos gateway application that
is used.
For example, if you are accessing
IBM Cognos 8 components using
a Common Gateway Interface
(CGI), then the default gateway
application would be cognos.cgi.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window click the appropriate group or component:

● To change an element for the dispatcher, click Environment.

● To change an element for the local log server, under Environment, click Logging.

3. In the Properties window, click the Value box next to the URI property that you want to change.

4. Select the element and type the new information.

Tip: To change the port used by the local dispatcher, change the value of the Internal dispatcher
URI property. Because the change affects all the URIs that are based on the local dispatcher,
you must change the URIs of all local components.

Tip: If you change the dispatcher port in the dispatcher URI, ensure that you specify the new
port number when you configure remote computers that use the dispatcher, Content Manager,
or SDK services on this system.

5. From the File menu, click Save.

Configure Cryptographic Settings

IBM Cognos 8 components require a cryptographic provider; otherwise they will not run. If you
delete the default cryptographic provider, you must configure another provider to replace it.
You can configure cryptographic provider settings, including the following:
● advanced algorithms
These include signing and digest algorithms.

● common symmetric key store (CSK) properties

The CSK is used by IBM Cognos 8 to encrypt and decrypt data.

● signing key store properties

The signing key pair includes the private key used to generate the digital signature and the
public key used to verify authenticity.

194 PowerPlay®
 Chapter 11: Configuration Options

● encryption key store properties

The encryption key pair includes the private key used to encrypt data and the public key used
to decrypt data.

The default cryptographic provider uses keys up to 56 bits in length for data encryption and secure
sockets layer (SSL) protocol. You can configure other cryptographic providers which use key sizes
greater than 56 bits, such as the Enhanced Encryption Module for OpenSSL, available on request.
For more information, see the Enhanced Encryption Module for OpenSSL Installation and Config-
uration Guide.

Important: In a distributed installation, IBM Cognos computers communicate with Content Manager
to establish trust and obtain some cryptographic keys from Content Manager. If you change the
cryptographic keys in Content Manager, such as by changing application servers or reinstalling
Content Manager, you must delete the cryptographic keys on the other IBM Cognos computers.
You must then save the configuration on each computer so that they obtain the new cryptographic
keys from Content Manager. In addition, all IBM Cognos 8 components in a distributed installation
must be configured with the same cryptographic provider settings.
Also, in a distributed environment, the symmetric key should only be stored on computers where
Content Manager has been installed.

Steps for Cryptographic Settings

1. Start IBM Cognos Configuration.

2. In the Explorer window, under Security, click Cryptography.

3. In the Properties window, change the default values by clicking the Value box and then selecting
the appropriate value:
● On computers that do not contain Content Manager, if you do not want to store the CSKs
locally, under CSK settings, change Store symmetric key locally to False.

When Store symmetric key locally is False, the key is retrieved from Content Manager when
required. The Common symmetric key store location property is ignored.

● If you want the computers at both ends of a transmission to prove their identity, under
SSL Settings, change Use mutual authentication to True.

We recommend that you do not change the Use confidentiality setting.

● If you want to change the digest algorithm, for the Digest algorithm property, select another
value.

4. From the File menu, click Save.

5. Test the cryptographic provider on a gateway computer only. In the Explorer window, right-
click Cryptography and click Test.
IBM Cognos 8 components check the availability of the symmetric key.

Installation and Configuration Guide 195

Chapter 11: Configuration Options

After you configure the cryptographic provider, passwords in your configuration and any data you
create are encrypted.

Steps for Cryptographic Provider

1. Start IBM Cognos Configuration.

2. In the Explorer window, under Security, Cryptography, click Cognos.

● If you want to change the location of the signing keys, under Signing key settings, change
the Signing key store location property to the new location.

● If you want to change the location of the encryption keys, under Encryption key settings,
change Encryption key store location to the new location.

● If you want to use a third-party certificate authority, under Certificate Authority settings,
change Use third party CA to True.
You must also ensure that you use the same values for the -k parameter as you used for
the Signing key store location and Encryption key store location properties.
For more information, see "Configuring IBM Cognos 8 Components to Use Another Cer-
tificate Authority" (p. 278).

Important: The Confidentiality algorithm value determines how data is encrypted by IBM
Cognos 8 components. For example, database passwords entered in IBM Cognos Configuration
are encrypted when you save the configuration. The algorithm selected when the data is
encrypted must also be available for the data to be decrypted at a later date.
The availability of confidentiality algorithms can change if there are changes to your environ-
ment. For example, if your Java Runtime Environment (JRE) has changed or if you have installed
cryptographic software on the computer. If you have made changes to a computer, such as
upgraded the JRE or installed software that has upgraded the JRE, this may affect the availab-
ility of confidentiality algorithms. You must ensure that the Confidentiality algorithm that was
selected when the data was encrypted is also available when you want to access the data.

3. From the File menu, click Save.

If you use a third-party Certificate Authority (CA) server, you must now configure IBM Cognos 8
components to use the CA.

Configure IBM Cognos 8 Components to Use IBM Cognos Application Firewall

IBM Cognos Application Firewall analyzes and validates HTTP and XML requests before they are
processed by IBM Cognos servers. IBM Cognos Application Firewall may modify these HTTP and
XML requests.
IBM Cognos Application Firewall protects IBM Cognos Web products from malicious data. The
most common forms of malicious data are buffer overflows and cross-site scripting (XSS) attacks,
either through script injection in valid pages or redirection to another Web site.
Using IBM Cognos Configuration, you can change settings for third-party XSS tool support, and
you can add host and domain names to the IBM Cognos list of valid names.

196 PowerPlay®
 Chapter 11: Configuration Options

You can track firewall activity by checking the log file, which contains rejected requests. By default,
log messages are stored in the c8_location\logs\cogserver.log file.

Important: All CAF settings must be the same for all computers where IBM Cognos 8 Application
Tier Components are installed within a distributed environment. For example, if CAF is disabled
on some computers and enabled on others, unexpected behavior and product errors may result.
The following types of URLs are accepted by CAF validation:
● fully qualified (absolute) URLs
in the format protocol://host:port/path, where protocol is http or https and host is validated
against the valid domain list

● URLs relative to the Web installation directory

in the format /Web_installation_root/.* where Web_installation_root is the gateway Web dir-
ectory, based on the cognos8 alias that you configured on your Web server.
For example,
/cognos8/ps/portal/images/action_delete.gif

● specific allowed URLs, including the following (all case insensitive)

about:blank
JavaScript:window.close( )
JavaScript:parent.close( )
JavaScript:history.back( )
parent.cancelErrorPage( )
doCancel( )

Steps
1. On each computer where IBM Cognos 8 Application Tier Components have been installed,
start IBM Cognos Configuration.

2. In the Explorer window, under Security, click IBM Cognos Application Firewall.

3. In the Properties window, for the Enable CAF validation property, set the appropriate values.
By default, IBM Cognos Application Firewall is enabled.

Important: The IBM Cognos Application Firewall is an essential component of IBM Cognos
security, helping to provide protection against penetration vulnerabilities. Disabling the IBM
Cognos Application Firewall will remove this protection. Under normal circumstances we
recommend that you not disable the IBM Cognos Application Firewall.

4. If you are using a third-party XSS tool that checks for specific characters in GET request
parameters, in the Properties window, do the following:

● For the Is third party XSS checking enabled property, change the value to True.

● For the Third party XSS characters property, add any additional characters that are pro-
hibited by the third-party XSS tool. The default characters are >, <, and ’.

Installation and Configuration Guide 197

Chapter 11: Configuration Options

5. Add host and domain names to the IBM Cognos list of valid names:

● For the Valid domains and hosts property, click the value and then click the edit button.

● In the Value - Valid domains or hosts dialog box, click Add.

You must include the domains from all hyperlinks that are added in IBM Cognos Connec-
tion. For more information, see the topic about creating a URL in the Administration and
Security Guide.

Tips
If you are using drill-through from IBM Cognos Series 7 to reports in IBM Cognos 8, add
the host names of the IBM Cognos Series 7 gateway servers to the list.
Add the host names of all computers in a distributed installation.
If you use a fully qualified domain name, such as www.mycompany.us.com, requests that
go to the parent domain, such as www.mycompany.com, are rejected by IBM Cognos
Application Firewall unless the parent domain is specified.

● In the blank row of the table, click and then type the host or domain name.

● Repeat the previous two bulleted steps for each name to be added.

● Click OK.

IBM Cognos Application Firewall validates domain and host names to protect URLs that are
created. By default, IBM Cognos Application Firewall considers domain names derived from
the environment configuration properties to be safe domain names. Adding names to the list
of valid names and hosts is useful when you need to redirect requests to non-IBM Cognos
computers using the Back or Cancel functions or when using drill-through to different IBM
Cognos product installations.

6. Save the configuration.

7. Restart the services.

Configure Temporary File Properties

You can change the location where IBM Cognos 8 components store recently viewed reports, and
you can choose to encrypt their content. By default, IBM Cognos 8 components store temporary
files in the c8_location\temp directory and the files are not encrypted.
We recommend that all access be denied to the temp directory, except for the service account used
to start the IBM Cognos 8 service. Read and write permissions are required for the service account.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window, click Environment.

3. In the Properties window, for the Temporary files location property, specify the new location.

198 PowerPlay®
 Chapter 11: Configuration Options

4. If you require the content of temporary files to be encrypted, set the Encrypt temporary files
property to True.

5. Ensure that the user account under which IBM Cognos 8 components run have the appropriate
privileges to the temporary files location. For example:
● on Windows, full control privileges

● on UNIX or Linux, read-write privileges

Configure the Gateway to Use a Namespace

If IBM Cognos 8 components use multiple namespaces or if anonymous access is enabled and IBM
Cognos 8 components use one namespace, you can configure the gateway to connect to one
namespace. Users logged onto the Web server where the gateway is located are not prompted to
choose an authentication source.
For example, if you have two Web servers, you can configure each Web server to use a different
namespace.

Steps
1. On the computer where the gateway is located, start IBM Cognos Configuration.

2. In the Explorer window, click Environment.

3. In the Properties window, in the Value box next to the Gateway namespace property, type the
Namespace ID of the namespace you want to use.

4. From the File menu, click Save.

5. Restart your Web server.

Enable and Disable Services

In a distributed installation, you can send certain types of requests to specific computers by enabling
or disabling the installed services.
For example, to dedicate a computer to running and distributing reports, you can disable the services
on a PowerPlay server computer.

Note: The default values for dispatcher service and presentation service are false on computers that
have the Content Manager only installed. On all other types of installations, the default values are
true.
If you installed all components on several computers, you can disable appropriate services on each
computer to get the distributed configuration you require. Requests are sent only to dispatchers
where a given service is enabled.
Disabling a service prevents the service from loading into memory. When disabled, services do not
start and therefore do not consume resources. The service does not run until you enable it and
restart the IBM Cognos 8 service.

Installation and Configuration Guide 199

Chapter 11: Configuration Options

If you disable the dispatcher service, the dispatcher-related services are disabled. Only dispatcher
services that are enabled can process requests.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window, under Environment, click IBM Cognos 8 service.

3. In the Properties window, click the Value next to the service that you want to disable or enable.
By default, all services are enabled.

4. Click the appropriate state for the services:

● To disable the service, click False.

● To enable the service, click True.

5. From the File menu, click Save.

6. From the Actions menu, click Restart.

Specify Resources for the IBM Cognos 8 Service

To improve performance in a distributed environment, you can change the amount of resources
that the IBM Cognos 8 service uses by choosing a configuration template.
By default, the IBM Cognos 8 service is configured to use minimal memory resources to optimize
startup time.
The configuration template settings apply only to Tomcat, the application server that IBM Cognos 8
uses by default. If you want to configure IBM Cognos 8 to run on another application server, do
not use IBM Cognos Configuration to configure the resources. Instead, configure the resources
within that application server environment. For more information, see "Configuring IBM Cognos 8
for an Application Server" (p. 255).
The IBM Cognos 8 service is available only on the computers where you installed Content Manager
or the Application Tier Components.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window, under Environment, IBM Cognos 8 service, right-click IBM Cognos 8,
and click Delete.
This deletes the default configuration template for the service.

3. Right-click IBM Cognos 8 service, and click New resource, Configuration.

4. Type a name for the service.

In Windows, the name you choose is used to register the service. You will see this name in the
list of services running on your computer.

5. In the Type box, click the configuration template to use:

200 PowerPlay®
 Chapter 11: Configuration Options

● If you previously changed the default setting and now want to reduce the startup time,
memory footprint, and resources used, click Small configuration.

● If you want a balance between fast startup time and quick operating speeds, click Medium
configuration.

● If you want to maximize operating speeds and if performance is more important than fast
startup time, and if your computer has a lot of resources, click Large configuration.

6. In the Properties window, edit the properties so that they are appropriate for your environment.

7. From the File menu, click Save.

Configuring Fonts
IBM Cognos 8 components use fonts to render PDF reports on the IBM Cognos server. IBM Cognos 8
components also use fonts to render charts used in PDF and HTML reports.
To show output correctly, fonts must be available where the report or chart is rendered. In the case
of charts and PDF reports, the fonts must be installed on the IBM Cognos server. If a requested
font is not available, IBM Cognos 8 components substitute a different font.
Because HTML reports are rendered on a browser, the required fonts must be installed on the
computer of each IBM Cognos user who will read the HTML report. If a requested font is not
available, the browser substitutes a different font.
If you want to use a new font in your reports, you must
❑ add the font to the list of supported fonts

❑ specify the file location of the new font

❑ map the new font to the physical font name, if required

Add Fonts to the IBM Cognos Environment

You can add fonts to the list of supported fonts in your IBM Cognos environment if you want to
generate reports that use fonts that are currently not available. You can also remove fonts.
By default, IBM Cognos 8 components use a set of global fonts, which are available on all IBM
Cognos server computers.

Steps
1. On each Content Manager computer, start IBM Cognos Configuration.

2. From the Actions menu, click Edit Global Configuration.

3. Click the Fonts tab.

4. Click Add.

Tip: To remove a font from the list of supported fonts, click the box next to the font name and
then click Remove.

5. In the Supported Font Name box, type the font name and then click OK.

Installation and Configuration Guide 201

Chapter 11: Configuration Options

6. From the File menu, click Save.

All global fonts, including new fonts that you add, must be installed on all IBM Cognos com-
puters in your environment.

If a global font is not installed on all IBM Cognos computers, you must map the global font to an
installed, physical font.

Specify the Location of Available Fonts

You must specify the installation location of all fonts, including fonts that you add to the list of
supported fonts.
By default, the list of fonts consists of fonts installed in the c8_location\bin\fonts directory of the
IBM Cognos computer. If IBM Cognos 8 components are installed on a Windows computer, they
also use the fonts installed in the Windows font directory.
You specify the font location on all computers where Application Tier Components are installed.

Steps
1. On each Application Tier Components computer, start IBM Cognos Configuration.

2. In the Explorer window, click Environment.

3. In the Properties window, for the Physical fonts locations property, specify the location of the
fonts.
If there are multiple font paths, separate each path by a semicolon (;).
If you are using an application server other than Tomcat, type the fully qualified path to the
font location. For example: c8_location/bin/fonts.

4. From the File menu, click Save.

Map Supported Fonts to Installed Fonts

You can substitute global fonts, which are not installed on the computer, for physical fonts.
You map fonts on each computer where the report server is installed.
For example, you add a font to the list of supported fonts that is not installed on the IBM Cognos
computer. You can specify which font to use as a substitute.
If you want to print reports faster by using the built-in PDF fonts, you can map a global font such
as Arial to one of the built-in PDF fonts, such as Helvetica-PDF, by following the steps below. You
can also select one of the built-in PDF fonts for a text object in Report Studio or Query Studio. For
more information, see the Query Studio User Guide or the Report Studio Professional Authoring
User Guide.
No mapping is required if you add a font to the supported font list that is installed on IBM Cognos
computers. However, you must specify the location of the font.

Steps
1. On each Application Tier Components computer, start IBM Cognos Configuration.

202 PowerPlay®
 Chapter 11: Configuration Options

2. In the Explorer window, click Environment.

3. In the Properties window, click the Value box next to the Physical fonts map property, and
then click the edit button.

The Value - Physical fonts map dialog box appears.

4. Click Add.

Tip: To remove a font, select the check box next to the font and click Remove.

5. In the Global Font Name box, type the name of the font you added to the supported font list.

6. Click the Physical Font Name box.

7. If you know the physical font name, type it. Otherwise, click the edit button. In the Physical
Font Name dialog box, click Search Now and then click a font name from the results.

8. Repeat steps 4 to 7 for each global font that requires mapping.

9. Click OK.

10. From the File menu, click Save.

Now, if required, you must specify the installation location of the fonts.

Considerations to Support Simplified Chinese

IBM Cognos 8 products support the GB18030-2000 character set, which is used in the encoding
of Simplified Chinese locales. If you install on Windows, support is provided for the GB18030-
2000 character set in the NSimSun-18030 font that is provided by Microsoft. If you install on other
operating systems, or if you use Internet Explorer 6 on Windows, additional installation tasks are
required:
❑ On operating systems other than Windows, you must install a font that supports GB18030-
2000.

❑ If you use Internet Explorer 6 on Windows, you must update the registry entries for fonts that
reference SimSun.

Update the Registry Entries for Windows Font Links

The GB18030-2000 character set includes CJK Unified Ideographs Extension A characters. When
these characters are encoded as UTF-8 in Internet Explorer 6, they may not appear correctly in Web
pages. To ensure that these characters appear correctly, you must add SimSun-18030 to all font
link registry entries that specify SimSun.

Steps
1. From the Start menu, select Run.

2. In the Run dialog box, type regedit.

3. Open the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\

FontLink\SystemLink directory.

Installation and Configuration Guide 203

Chapter 11: Configuration Options

4. In Registry Editor, right-click a font that contains SimSun in the Data field and select Modify.

5. In the Edit Multi-String dialog box, under Value data, click under the selected strings and type
the following string:

SimSun18030.ttc,SimSun-18030

6. Click OK.

7. Repeat steps 4 to 6 for every font that contains SimSun.

8. When complete, close Registry Editor.

Change the Default Font for PDF Reports

You can change the default font that IBM Cognos 8 components use for PDF reports. You see this
default font when you open a report.
You change the default font on the computer where Content Manager is installed. After you make
the change, the font becomes the default for all computers in your installation. You change the font
used for PDF reports using IBM Cognos Configuration.
Ensure that the default font is installed on all computers in your IBM Cognos installation.

Steps
1. On each Content Manager computer, start IBM Cognos Configuration.

2. From the Actions menu, click Edit Global Configuration.

3. Click the General tab.

4. In the Value box, for Default font, type the font you want to use as the default for reports.

5. Click OK.

6. From the File menu, click Save.

7. On all Application Tier Components computers, ensure that the installation location of the
default font is specified in the Physical fonts locations property (under Environment in the
Explorer window) or that the font is in the Windows font directory.

Configure Embedded Fonts for PDF Reports

When a PDF report opens in Adobe Reader, all the fonts used in that report must be available.
Fonts must be either embedded in the report or installed on the user’s computer. If a font is not
available in either of these locations, Adobe Reader tries to substitute an appropriate font. This
substitution may cause changes in the presentation of the report or some characters may not be
displayed.
To ensure that PDF reports appear correctly in Adobe Reader, IBM Cognos 8 embeds required
fonts in reports by default. To minimize the file size, IBM Cognos 8 embeds only the characters
(also called glyphs) used in the report rather than all characters in the font set. IBM Cognos 8

204 PowerPlay®
 Chapter 11: Configuration Options

embeds fonts only if they are licensed for embedding. The license information is stored in the font
itself and is read by IBM Cognos 8.
If you are confident that the fonts used in reports are available on users’ computers, you can limit
or eliminate embedded fonts to reduce the size of PDF reports. When limiting fonts, you specify
whether a font is always or never embedded, using an embedded fonts list in IBM Cognos Config-
uration.

Steps
1. On the Content Manager computer, start IBM Cognos Configuration.

2. In the Explorer window, click Environment.

3. In the Properties window, under Font Settings, click the value for Fonts to embed (Batch report
service) or Fonts to embed (Report service), and then click the edit button.

4. If you are not using the default fonts directory or if you want to add a path to an additional
directory, in the Fonts to Embed in PDF Reports dialog box, specify the new path in the font
paths box.

Tip: Click Search Now to get a list of the available fonts in the specified path or paths.

5. For a font that will always be available on users’ computers, scroll to the font name, and click
the Never check box.
IBM Cognos 8 does not embed the font with any reports. Adobe Reader picks up the font from
the user’s computer when the report is opened.

6. For a font that may not always be available on the users’ computers, scroll to the font name
and click the Always check box.
IBM Cognos 8 embeds the font with all reports that use it. Adobe Reader uses the embedded
font when the report is opened.

7. Click OK.

Saved Report Output

By default, report output files are saved in the content store. You have the option of saving a copy
of the report output in another file location that is outside or inside IBM Cognos 8. If you use this
option, a descriptor file with an _descr extension is also saved. Saved files are not managed by IBM
Cognos 8.

Save Report Output Outside IBM Cognos 8

If you configure a file system location that is outside of IBM Cognos 8, you can then share the
report output with external applications or people who don’t have IBM Cognos 8. This is how
most report output files are saved.
To use this feature, you must first configure a root directory in IBM Cognos Configuration. An
administrator must then set the file location in IBM Cognos Administration. For more information,

Installation and Configuration Guide 205

Chapter 11: Configuration Options

see the topic about setting a file location for report output saved outside of IBM Cognos 8, in the
Administration and Security Guide.

Steps
1. Create a directory for your file system.

Tip: Ensure that the directory is accessible to users and separate from the installation directory.
For example, in a distributed installation, an archive folder such as \\servername\directory could
be used.

2. On the Content Manager computer, start IBM Cognos Configuration.

3. From the Actions menu, click Edit Global Configuration.

4. In the Global Configuration window, click the General tab.

5. For Archive Location File System Root, type a URI using the format

file://directory
where directory is the directory that you created in step 1.
The file:// portion of the URI is required. Windows UNC names, such as \\servername\directory,
can be used. If so, the URI must be formatted as follows:

file://\\servername\directory

6. To confirm that the correct location will be used, click Test.

7. Click OK.

8. From the File menu, click Save.

The administrator must now configure the file location. For information, see the topic about setting
a file location for report output saved outside of IBM Cognos 8, in the Administration and Security
Guide.

Save Report Output Inside IBM Cognos 8

If you configure a file system location that is inside IBM Cognos 8, you can then use the report
output again. This may also be useful for archive purposes, because files that are saved in the
Content Store may be deleted regularly due to retention rules.

To use this feature, you must first enable the Save report outputs to a file system property in IBM
Cognos Configuration. An administrator must then configure the file location using the CM.Out-
PutLocation parameter in IBM Cognos Administration. For more information, see the topic about
setting a file location for report output saved inside IBM Cognos 8, in the Administration and
Security Guide.

Steps
1. Create a directory for your file system.

Tip: Ensure that the directory is accessible to authorized users only.

2. On the Content Manager computer, start IBM Cognos Configuration.

206 PowerPlay®
 Chapter 11: Configuration Options

3. In the Explorer window, click Data Access, Content Manager.

4. For the Save report outputs to a file system property, click True.

5. To test the connection to the report output directory, from the Actions menu, click Test.

6. From the File menu, click Save.

The administrator must now configure the file location using the CM.OutPutLocation parameter.
For information, see the topic about setting a file location for report output saved inside IBM
Cognos 8, in the Administration and Security Guide.

Change Configuration Settings for the IBM Cognos Series 7

Migration Service
If necessary, you can change service port number used by the IBM Cognos Series 7 migration service.

Steps
1. Go to the s7_location\migs7 directory.

2. Locate the migs7service_configuration.xml file and remove the read-only attribute from the
file properties.

3. Open the file in an XML editor or a plain-text editor such as Notepad.

4. Change the settings in the file to match your environment.

5. Save the file.

6. Restart the migration service:

● On Windows, restart the migration service using the IBM Cognos Migration Series 7 Service
entry in the Services list under Administrative Tools.

● On UNIX, stop and then start the migration service by typing the following commands in
the migs7service directory:

./configure.sh --stop

./configure.sh --start

Assign a User Account to the PowerPlay and Migration Services

for Migration
By default, the IBM Cognos PowerPlay Enterprise Server service and the migration service use a
system account. If multiple PowerPlay servers will share data locations during migration, you must
first assign a user account to the services.
A user account must be set up on every Windows computer where Series 7 Migration Components
or the PowerPlay component are installed.

Installation and Configuration Guide 207

Chapter 11: Configuration Options

Before you assign the user account to the services, ensure that a user account is set up with a pass-
word that never expires.

Steps
1. In the Windows Control Panel, under Administrative Tools, click Services.

2. Click the IBM Cognos PowerPlay Enterprise Server service and click Startup.

3. In the Log On As panel, click This Account.

4. From the list, select the user account that you set up for the service.

5. Type the password for the account in the Password text box and the Confirm Password text
box.

6. Click OK.

7. Repeat steps 2 to 5 for the Series 7 migration service.

Set a User Login Account for the IBM Cognos 8 Service on

Multiple PowerPlay Computers
By default, the IBM Cognos 8 service is installed as a system account login. For multiple PowerPlay
computers to share data locations on a network, you must assign a user login account to the IBM
Cognos 8 service on each Windows computer.
You must first create a special user account that has the password defined to never expire.

Steps
1. In the Windows Control Panel, under Administrative Tools, click Services.

2. Right-click the IBM Cognos 8 service and click Properties.

3. In the Log On tab, select This Account and then click Browse.

4. In the Select User dialog box, click the special user account that you created. In the Password
box, type the password for this account.

5. In the Confirm Password box, type the password again.

6. Click OK.

Create a New Content Store Using Cognos Content Database

Follow the steps below if you want to create another content store database using Cognos Content
Database. This may be required if you install more than one instance of your IBM Cognos 8 product
in one location and you want to run the instances separately.
Before you create the new content store, do the following:

208 PowerPlay®
 Chapter 11: Configuration Options

● Install the additional instance of your IBM Cognos 8 product in a separate directory on the
same computer.

Ensure that you select Cognos Content Database on the Component Selection page of the
installation wizard.

● Create a new user and password for the new content store database.

Steps
1. In the location where you installed the new instance of Cognos Content Database, in the
c8_location\derby10.1.2.1\bin directory, use the ij.bat or ij.ksh script to create a new database.
Use the following syntax:

connect 'jdbc:derby://host:port/db_name;create=true;user=username; password=password';

Ensure that you use a different name, user, and password for the new content store.
For example, to create a database named contentstore2 on the localhost computer on port
number 1527 as a user named cognos2 with a password of cognos2, you would type

connect 'jdbc:derby://localhost:1527/contentstore2;create=true;user=cognos2;
password=cognos2';
The database name is case-sensitive.
The database files are located in the c8_location\contentstore directory.

2. When you are finished with the ij utility, disconnect by using the following command:

disconnect;

Configuring the SSL Protocol

The Secure Sockets Layer (SSL) protocol is used to secure communication between IBM Cognos
components installed on the same computer or on different computers.
In addition, you may want to set up SSL connections between IBM Cognos components and other
servers. You must ensure that SSL is set up for the other servers and then you must set up a shared
trust between IBM Cognos components and the other servers.
Use the following checklist to configure SSL protocol.
❑ Configure SSL for IBM Cognos components (p. 210).

❑ Set up shared trust between IBM Cognos components and other servers, if required (p. 212).

❑ Select and rank Cipher Suites to be used in an SSL connection, if required (p. 213).

❑ Enable SSL on your Web server (p. 214).

After configuring the SSL protocol, you can select and rank cipher suites, which control the quality
of protection used in the SSL connection.

Installation and Configuration Guide 209

Chapter 11: Configuration Options

Configure SSL for IBM Cognos 8

You can configure IBM Cognos components to use the SSL protocol for
● internal connections only

● external connections only

● internal and external connections

● connections to local and remote log servers

If you configure SSL only for internal connections, IBM Cognos components on the local computer
communicate using this protocol. The dispatcher listens for secure connections on a different port
than for remote, http requests. Therefore, you must configure two dispatcher URIs.
If you configure SSL only for external connections, communications from remote IBM Cognos
components to the local computer use the SSL protocol. You must configure the dispatcher to listen
for secure, remote requests on a different port than local, HTTP requests. You must also configure
the Content Manager URIs and the dispatcher URI for external applications to use the same protocol
and port as the external dispatcher.
If you configure SSL for all connections, the dispatcher can use the same port for internal and
external connections. Similarly, if you do not use SSL for local or remote communication, the dis-
patcher can use the same port for all communications.
You must also update the Content Manager URIs, Dispatcher URI for external applications, and
Gateway URI to use SSL, if required.

Tomcat Connectors
If the internal dispatcher URI is prefixed with http but the external dispatcher URI is prefixed with
https, or vice versa, both the non-SSL Coyote HTTP/1.1 and SSL Coyote HTTP/1.1 connectors are
enabled in the server.xml file.
If the internal and external dispatcher URIs use different protocol or ports, the internal dispatcher
port is accessible only to the components on the local computer. The internal dispatcher URI must
also specify localhost.

Single Computer Installations

In single computer installations, if you are running IBM Cognos 8 without SSL, you must stop the
service before adding SSL to your configuration. After you save the configuration with SSL settings,
you can restart the service.

Distributed Installations
In distributed installations, if you are using the IBM Cognos certificate authority service, you must
first configure all IBM Cognos computers to use the non-secure (http) protocol before you configure
IBM Cognos components to use the SSL protocol. You must do this because you cannot set up the
SSL protocol before trust has been established.
Also, ensure that you follow the required order of configuring computers in a distributed environ-
ment. That means that you must first configure the computer where the default active Content
Manager is installed and then start the services on this computer before you configure other com-

210 PowerPlay®
 Chapter 11: Configuration Options

puters or start services on other computers. By first configuring the default active Content Manager
computer and starting the services, you ensure that the certificate authority service on the default
active Content Manager computer can issue certificates to other computers in the IBM Cognos
environment.
After you configure all computers in the distributed installation to use the default, non-secure pro-
tocol, we recommend that you test your installation to ensure that IBM Cognos components are
working properly. After you test your installation, you can configure the SSL protocol.
When you configure IBM Cognos 8 to use the SSL protocol, ensure that you first configure the
default active Content Manager computer to use the protocol and start the services on the default
active Content Manager computer. After you do this, you can configure the SSL protocol on other
IBM Cognos computers in your environment.

Add a Computer to an Installation

If you add a computer to an SSL-enabled environment, you will be prompted to temporarily accept
trust for a certificate when you save the configuration. Accepting the temporary certificate will
allow permanent trust to be established with the Content Manager computer.

Add a Component to a Computer

You can later add a component to the same location as other IBM Cognos components. If you add
the component to a different location on the same computer as other IBM Cognos components,
you will be prompted to temporarily accept trust for a certificate when you save the configuration.
Accepting the temporary certificate will allow permanent trust to be established between the new
component and the Content Manager computer.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window, click Environment.

3. In the Properties window, type the appropriate values for the Internal dispatcher URI and
External dispatcher URI values:

● To configure SSL for internal connections only, for the Internal dispatcher URI property,
type https and a port for SSL communication. For the External dispatcher URI property,
type http and use the default or another available port.

If you use Tomcat, the Internal dispatcher URI property must also specify localhost.
The ports in the two dispatcher URIs must be different.

● To configure SSL for external connections only, for the External dispatcher URI property,
type https and a secure port. For the Internal dispatcher URI property, type http and use
the default or another available port.

If you use Tomcat, the Internal dispatcher URI property must also specify localhost.
The ports in the two dispatcher URIs must be different.

● To configure SSL for all connections, type the same URI for both the Internal dispatcher
URI and External dispatcher URI properties. Type https and a secure port, such as 9343.

Installation and Configuration Guide 211

Chapter 11: Configuration Options

Note: You do not have to use port 9343, the default SSL port. You can choose any available
port.

4. Configure the SSL protocol for the other environment URIs, including the Content Manager
URIs, the Dispatcher URI for external applications, and Gateway URI.

● For internal connections only, type https in the URIs that contain localhost.

● For external connections only, type https in the URIs that do not contain localhost.

● For all connections, type https in all the URIs.

5. In the Explorer window, click Security, Cryptography.

6. To use SSL protocol, you must specify passwords for the IBM Cognos 8 encryption key stores.
There are more settings under Security, Cryptography, Cognos.

7. From the File menu, click Save.

Set Up Shared Trust Between IBM Cognos Servers and Other Servers
If you want to use the default IBM Cognos certificate authority and you want to use SSL for con-
nections from other servers to IBM Cognos servers, you must add the IBM Cognos certificate to
the trust store on the other servers.

Note: If you use browsers to connect to IBM Cognos components, the browsers automatically
prompt users to update their trust stores.
If you want the connection between IBM Cognos servers and the other server to be mutually
authenticated, you must also copy the certificate from your certificate authority to the trust store
for IBM Cognos servers.
If you have configured IBM Cognos components to use another certificate authority (CA), you do
not have to set up shared trust between IBM Cognos server and other servers.

Steps to Copy the IBM Cognos Certificate to Another Server

1. Go to the c8_location\bin directory.

2. Extract the IBM Cognos certificate by typing the following command:

● On UNIX or Linux, type

ThirdPartyCertificateTool.sh -E -T -r destination_file -k c8_location/configuration/

signkeypair/jCAKeystore -p password

● On Windows, type

ThirdPartyCertificateTool.bat -E -T -r destination_file -k c8_location\configuration\

signkeypair\jCAKeystore -p password

3. Import the certificate to the trust store on your server.

212 PowerPlay®
 Chapter 11: Configuration Options

For information on updating the server trust store, see the documentation for your server.

Steps to Copy the CA Certificate to IBM Cognos Servers

1. Copy the certificate from your certificate authority to a secure location on the IBM Cognos
server.
Ensure that the CA certificate is in Base-64 encoded X.509 format.

2. Import the CA certificate by typing the following command:

● On UNIX or Linux, type

ThirdPartyCertificateTool.sh -T -i -r CA_certificate_file -k c8_location/configuration/

signkeypair/jCAKeystore -p password

● On Windows, type

ThirdPartyCertificateTool.bat -T -i -r CA_certificate_file -k c8_location\configuration\

signkeypair\jCAKeystore -p password

Select and Rank Cipher Suites for SSL

An SSL connection begins with a negotiation in which the client and server present a list of supported
cipher suites in a priority sequence. A cipher suite provides the quality of protection for the connec-
tion. It contains cryptographic, authentication, hash, and key exchange algorithms. The SSL protocol
selects the highest priority suite that the client and the server both support.
A list of supported cipher suites for SSL is provided. You can eliminate cipher suites that do not
meet your requirements and then assign a priority, or preference, to the remaining cipher suites.
The selected cipher suites are presented in priority sequence for the client and server sides of the
negotiation. At least one of the selected cipher suites between the client and server platforms must
match.
The list of supported cipher suites is dynamically generated on each computer, and depends on the
Java Runtime Environment (JRE) or whether you have other cryptographic software installed on
the computer. If you have made changes to a computer, such as upgraded the JRE or installed
software that has upgraded the JRE, this may affect the supported cipher suites available on that
computer. If you no longer have a supported cipher suite that matches the other computers in your
environment, you may have to change the JRE on the computer to match the other computers in
your environment.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window, click Cryptography, Cognos.

3. In the Properties window, click the Value column for the Supported ciphersuites property.

4. Click the edit button.

● To move a cipher suite to the Current values list, click the check box in the Available values
list and then click Add.

Installation and Configuration Guide 213

Chapter 11: Configuration Options

● To move a cipher suite up or down in the Current values list, click the check box and then
click the up or down arrows.

● To remove a cipher suite from the Current values list, click the check box and then click
Remove.

5. Click OK.

6. From the File menu, click Save.

Enable SSL on the Web Server

Enable secure sockets layer (SSL) to encrypt a user’s communication with the Web server.
To enable SSL on your Web server, you must obtain a Web server certificate signed by a Certificate
Authority and install it into your Web server. The certificate must not be self-signed, because self-
signed certificates will not be trusted by IBM Cognos components.
To enable IBM Cognos components to use an SSL-enabled Web server, you must have copies of
the trusted root certificate (the certificate of the root Certificate Authority which signed the Web
server certificate) and all other certificates which make up the chain of trust for the Web server’s
certificate. These certificates must be in Base64 encoded in ASCII (PEM) or DER format, and must
not be self-signed. The certificates must be installed on every computer where you have installed
Application Tier Components.
For more information about installing certificates into your Web server, see your Web server docu-
mentation.

Steps
1. Configure the Web server for SSL and start the Web server.
For more information, see your Web server documentation

2. On each Application Tier Components computer that points to the gateway on the Web server,
in IBM Cognos Configuration, change the gateway URI from HTTP to HTTPS, and save the
configuration.

Important: Do not start the IBM Cognos 8 service yet.

3. On each Planning Server computer that points to the gateway, in IBM Cognos Configuration,
change the gateway URI from HTTP to HTTPS, and save the configuration.

Important: Do not start the IBM Cognos 8 service yet.

4. On each Application Tier Components computer, go to the c8_location/bin directory and import
all the certificates that make up the chain of trust, in order starting with the root CA certificate,
into the IBM Cognos trust store.
Import the certificates by typing the following command:
On UNIX or LINUX, type

ThirdPartyCertificateTool.sh -T -i -r certificate_fileName -D ../configuration/signkeypair -p

password

214 PowerPlay®
 Chapter 11: Configuration Options

On Windows, type

ThirdPartyCertificateTool.bat -T -i -r certificate_fileName -D ../configuration/signkeypair -p

password

Note: The password should have already been set. If not, the default password is NoPassWord-
Set.

5. On each Planning Server computer, go to the c8_location/bin directory and import all the
certificates that make up the chain of trust, in order starting with the root CA certificate, into
the IBM Cognos trust store.
Import the certificates by typing the following command:

ThirdPartyCertificateTool.bat -T -i -r certificate_fileName -D ../configuration/signkeypair -p

password

Note: The password should have already been set. If not, the default password is NoPassWord-
Set.

6. On each Application Tier Components computer, in IBM Cognos Configuration, start the IBM
Cognos 8 service.

7. On each Planning Server computer, in IBM Cognos Configuration, start the IBM Cognos 8
service.

You can verify trust, by creating and running a PDF report that contains pictures that are not stored
locally but which the gateway gets from a remote computer. If the pictures appear, trust is established.
To avoid being prompted by a security alert for each new session, install the certificate into one of
your Web browser’s certificate stores.
In addition, you may want to set up SSL connections between IBM Cognos components and other
servers. You must ensure that SSL is set up for the other servers and then you must set up a shared
trust between IBM Cognos components and the other servers. For more information, see "Config-
uring the SSL Protocol" (p. 209).

Configuring Log Messages

Log messages are an important diagnostic tool for investigating the behavior of IBM Cognos 8. In
addition to error messages, log messages provide information about the status of components and
a high-level view of important events. For example, log messages can provide information about
attempts to start and stop services, completion of processing requests, and indicators for fatal errors.
Audit logs, which are available from a logging database, provide information about user and report
activity.
The IBM Cognos 8 services on each computer send information about errors and events to a local
log server. A local log server is installed in the c8_location/logs folder on every IBM Cognos 8
computer that contains Content Manager or Application Tier Components. Because the log server
uses a different port from the other IBM Cognos 8 components, it continues to process events even
if other services on the local computer, such as the dispatcher, are disabled.
The following workflow shows the tasks that are required to prepare for logging.

Installation and Configuration Guide 215

Chapter 11: Configuration Options

Plan log message processing

Configure logging Set up logging

Configure logging
Plan log message processing Set up logging

Set up logging
Plan log message processing Configure logging

❑ During planning, determine the logging configuration that is suitable for your environment.
For example, evaluate various log message destinations, such as remote log servers and log
files, such as the UNIX or Linux syslog or the Windows NT Event log, in addition to the local
log file. You can also send only audit logging information to a database. Consider security,
such as methods available for protecting log files from system failures and user tampering. For
information about planning, see the Architecture and Deployment Guide.

❑ During configuration, define the startup properties for logging, such as connection settings for
databases. You must also create a logging database if you plan to collect audit logs. If commu-
nication between a local log server and a remote log server must be secured, make the appro-
priate configuration changes on both IBM Cognos 8 computers. For information about config-
uring logging, see the Installation and Configuration Guide.

❑ When setting up logging, specify the level of detail to log to focus messages on the information
that is relevant in your organization. Audit reports may also be set up to track user and report
activity. For information about setting up logging, see the Administration and Security Guide.

For information about using log messages to solve problems and resolving logging-related issues,
see the Troubleshooting section of the Administration and Security Guide.

Guidelines for Creating a Logging Database

You can create a database to store log messages. Creating a logging database involves the following
tasks:
❑ Create a logging database.
For DB2, Oracle, Microsoft SQL Server, or Sybase, use the same procedure that was used to
create the content store database (p. 35).
For DB2 on z/OS, use the instructions in "Suggested Settings for Creating the DB2 Logging
Database on z/OS" (p. 217).

❑ Set up the database connectivity.

216 PowerPlay®
 Chapter 11: Configuration Options

❑ Specify the log messages destination.

Suggested Settings for Creating the DB2 Logging Database on z/OS

The database you create must contain some recommended configuration settings.
Use the following checklist to help you set up the logging database on DB2.
❑ Log on to the z/OS system as a user with administrator privileges in DB2 on z/OS.

❑ Create a database instance, storage group, and a user account for the content store. IBM Cognos
8 uses the credentials of the user account to communicate with the database server.

❑ Ensure that you allocate a buffer pool with a page size of 8 KB for the database instance.

❑ For a logging database in DB2 on z/OS, administrators must run a tablespace script to create
tablespaces to hold large objects and other data for the logging database, and then grant user
rights to the table. For information about running the tablespace script, see "Create Tablespaces
for DB2 Logging Database on z/OS " (p. 217).

Create Tablespaces for DB2 Logging Database on z/OS

A database administrator must run a script to create a set of tablespaces required for the logging
database. The script must be modified to replace the placeholder parameters with ones that are
appropriate for your environment.
Ensure that you use the name convention for DB2 on z/OS. For example, all names of parameters
must start with a letter and the length must not exceed eight characters. For more information, see
the IBM DB2 Information Center.

Steps
1. Using a remote access tool, connect to the database as a user with privileges to create and drop
tablespaces and to allow execution of SQL statements.

2. Open the LS_tablespace_db2zOS.sql script file and use the following table to help you to replace
the generic parameters with ones appropriate for your environment.
Not all of the parameters listed are in the script, but may be added in the future.

Parameter Name Description

IPFSCRIPT_DATABASE Specifies the name of the logging database.

IPFSCRIPT_STOGROUP Specifies the name of the storage group.

IPFSCRIPT_TABLESPACE Specifies the name of the tablespace that contains

the base tables in the logging database.
This tablespace is not for Auxiliary tables.

IPFSCRIPT_LOB_TABLESPACE Specifies the name of the tablespace that is allocated

for auxiliary tables.

Installation and Configuration Guide 217

Chapter 11: Configuration Options

Parameter Name Description

IPFSCRIPT_BP Specifies the name of the 8 k buffer pool that is

allocated for regular objects.

IPFSCRIPT_USERNAME Specifies the user account that accesses the logging

database.

3. Save and run the script in the remote access tool.

4. Grant the IBM Cognos user rights to the tablespaces that were created when you ran the LS_
tablespace_db2zOS.sql script file:
● In the remote access tool, open the LS_rightsGrant_db2zOS.sql script file, which is located
in the c8_location\configuration\schemas\logging\db2zOS directory.

● Replace the parameter values with those that are appropriate for your environment.

Tip: Ensure you use the same values that you used when you created the buffer pools and
user account.

● Save and run the LS_rightsGrant_db2zOS.sql script in the remote access tool.

The logging database is created.

Set Up the Database Connectivity for the Logging Database

After you create a database for audit logs, additional steps are required to set up the database client
if you use Oracle, DB2, or Sybase as the database server.
You cannot use Cognos Content Database as a logging database.

Note: In a distributed environment, the local log server on an Application Tier Component computer
may send log messages to a remote log server, which then sends messages to the logging database.
For Oracle, Sybase, and DB2, the appropriate JDBC driver and database client software (DB2 only)
is required only on the Application Tier Components computer with the remote log server that
connects to the logging database.

Microsoft SQL Server Database

If you use a Microsoft SQL Server database, the JSQLConnect.jar file is installed to the appropriate
location by default. The only additional step is to ensure that the Microsoft SQL Server uses TCP/IP
connectivity.

Oracle or Sybase Database

If you use an Oracle or Sybase database, you must set up the JDBC driver on all Application Tier
Components computers with a connection to the logging database. You must also set up the JDBC
driver on the Content Manager computer, unless you are using the same type of database for the
log messages as you use for the content store.

218 PowerPlay®
 Chapter 11: Configuration Options

DB2 Database
IBM Cognos 8 uses JDBC connectivity to access the database used for the logging database.
For a DB2 database, you must set up the database client software and the JDBC driver on all
Application Tier Components computers with a connection to the logging database. You must also
set up the database client software and the JDBC driver on the Content Manager computer, unless
you are using the same type of database for the log messages as you use for the content store.
If you use DB2 on Windows, Linux or UNIX as your logging database you must choose whether
to use the type 2 or type 4 JDBC driver depending on how you want to connect to the logging
database.
If you are using a DB2 database on z/OS for the logging database, you must use type 4 JDBC
connectivity.
For more information about JDBC driver options for a DB2 database, see "JDBC Driver Options
for Using DB2 Database as a Content Store" (p. 73).

Steps for Oracle

1. On the computer where Oracle is installed, go to the ORACLE_HOME/jdbc/lib directory.

2. Copy the ojdbc14.jar file to the c8_location/webapps/p2pd/WEB-INF/lib directory on the

appropriate Content Manager or Application Tier Components computers. For Oracle 11g,
copy the ojdbc5.jar file to the c8_location/webapps/p2pd/WEB-INF/lib directory on the
appropriate Content Manager or Application Tier Components computers.
If the directory contains the classes12.jar file, delete it before installing the ojdbc14.jar or
ojdbc5.jar file.

Steps for DB2 on Linux, UNIX, and Windows

1. If you are using type 2 JDBC connectivity, install the DB2 client software on the Content
Manager computers.
If you use type 4 JDBC connectivity for DB2, you are not required to install the DB2 client
software where Content Manager is installed.
For more information about the differences between type 2 and type 4 drivers, see "JDBC
Driver Options for Using DB2 Database as a Content Store" (p. 73).

2. If you are using type 2 JDBC connectivity, and the logging database is on a different computer
than log server, configure a database alias to the logging database.
● On Windows, run the DB2 Client Configuration Assistant.

● On UNIX or Linux, use the DB2 command line interface.

Note: If the logging database and log server are on the same computer, the logging database
name automatically becomes the alias.

3. On Windows, stop the DB2 services and the HTML Search Server.

4. Copy the following files from the DB2_installation/sqllib/java directory to the c8_location/
webapps/p2pd/WEB-INF/lib directory.

Installation and Configuration Guide 219

Chapter 11: Configuration Options

● the universal driver file, db2jcc.jar

● the license file

for DB2 on Linux, UNIX, or Windows, db2jcc_license_cu.jar
for DB2 on z/OS, db2jcc_license_cisuz.jar

Tip: To check the driver version, run the command java -cp path\db2jcc.jar com.ibm.db2.jcc.
DB2Jjcc -version.

5. On Windows, restart the DB2 services and the HTML Search Server.

6. Repeat this entire procedure on the IBM Cognos 8 computers where the software must be
installed.

Steps for DB2 on z/OS

1. Go to the DB2_installation/sqllib/java directory.

2. Copy the following files to the c8_location/webapps/p2pd/WEB-INF/lib directory and c8_loca-

tion/bin directories.
● the universal driver file, db2jcc.jar

● the license file, for example, db2jcc_license_cisuz.jar

If you are using a DB2 database on z/OS for the logging database, you must use type 4 JDBC
connectivity.
The driver version must be at least JCC 3.7 from Linux, UNIX, or Windows version 9.1 fix pack
or JCC 3.42 from Linux, UNIX, or Windows version 9.5 fix pack 2.

Steps for Sybase

1. On the computer where Sybase is installed, enable the JDBC driver using the following script:
Sybase_location/jConnect-5_5/sp/sql_server12.5.sql

2. Go to the Sybase_location/jConnect-5_5/classes directory.

3. Copy the jconn2.jar file to the c8_location/webapps/p2pd/WEB-INF/lib directory on the

appropriate Content Manager or Application Tier Components computers.

Log Message Destinations

A local log server is automatically installed when you install Content Manager or the Application
Tier Components. You can specify one or more destinations where the local log server sends log
messages:
● remote log server

● file

● database

● UNIX or Linux syslog or the Windows NT Event log

220 PowerPlay®
 Chapter 11: Configuration Options

For information about log messages, see the Architecture and Deployment Guide.

Remote Log Server

In a distributed installation, you can configure the log server on each IBM Cognos 8 computer to
send log messages to a single remote log server, which acts as a common log server. You can then
configure the common log server to send the log messages to a local file or database on the same
or different computer.
If the remote log server becomes unavailable, log messages are redirected to recovery files on the
local computer in the c8_location\logs\recovery\remote directory. These recovery files have timestamp
information in their file names, and are not readable like regular log files. When the remote log
server becomes available, an automatic recovery process moves all log information to the remote
log server and deletes the local log files.

File
The log server is configured by default to send log messages to the c8_location/logs/cogserver.log
file. If the default log file does not exist when the IBM Cognos 8 service starts, it is created
automatically.
You can configure the log server to send log messages to a different file. If you configure a different
log file, IBM Cognos 8 attempts to automatically create this file on startup, in addition to the default
log file. If the location for the configured log file is different from the c8_location/logs directory,
you must ensure the path to the log file exists before starting the IBM Cognos 8 service. For example,
if you configure the log server to send messages to the c:/log_files/cognos.log file, IBM Cognos 8
attempts to automatically create the cognos.log file in the c:/log_files folder. If this folder does not
exist, IBM Cognos 8 does not create the cognos.log file and no log messages can be recorded in it.
Note that these log messages are not recorded in the default log file. Although IBM Cognos 8
automatically creates the default log file even when another log file is configured, the default log
file is not used as a backup.

Database
The log server can also send audit logs to a database on the same or another computer. Audit logs
provide information about user and report activity.
The logging database has the same configuration and user account requirements as the content
store database. After you configure IBM Cognos 8 components to send messages to a logging
database, and restart the IBM Cognos 8 service, IBM Cognos 8 components create the required
tables and table fields. You can test the connection to the logging database before you restart the
IBM Cognos 8 service.

Specify the Log Messages Destination

You can configure a type of destination for the log messages, and then configure properties for the
specific destination. You can also configure more than one destination for log messages.
Before you specify a database as a destination, ensure that you
❑ created the logging database

Installation and Configuration Guide 221

Chapter 11: Configuration Options

❑ set up the database client

Steps for DB2, Linux, and Windows

1. On the computer where you installed Content Manager or the Application Tier Components,
start IBM Cognos Configuration.

2. In the Explorer window, under Environment, click Logging.

3. In the Properties window, use the following table to help set the log server properties.

Task Action

Use TCP between IBM Cognos 8 Set the Enable TCP property to True.
components on a computer and
UDP provides faster communication with a lower
its local log server
risk of lost connections than TCP. However, the risk
of losing a local TCP connection is low. TCP is
always used for communication between a local log
server and a remote log server.

Change the number of threads Type the value in the Local log server worker threads
available to the local log server property.
Set a value between 1 and 20. The default value of
10 is recommended.
However, if you have a high number of log messages,
you can allocate more threads to improve perform-
ance.

Apply UTF-8 encoding for log Set the Use UTF8 encoding property to True.
messages written to a file
If the IBM Cognos 8 component is using multibyte
encoding, you must set this property to True and use
a UTF-8 editor to view the log file. Otherwise, the
log file may contain unreadable characters.

4. In the Explorer window, under Environment, right-click Logging, and click New resource,
Destination.

5. In the Name box, type the name of the destination.

6. In the Type list, click the type of destination and then click OK.

7. If the destination is a file, in the Properties window, type the appropriate values for the man-
datory and optional properties.

8. If the destination is a remote log server, in the Properties window, type the appropriate values
for the mandatory and optional properties.

222 PowerPlay®
 Chapter 11: Configuration Options

If the Internal dispatcher URI of the destination IBM Cognos 8 computer is configured to use
SSL, in the Properties window, set the Enable SSL property to True.
You must later specify the log messages destination when you configure the remote log server.

9. If the destination is a database, in the Explorer window, under Logging, specify the type of
database and its properties, as follows:

● Right-click the database name, and click New resource, Database.

● In the Name box, type the name of the destination.

● In the Type list, click the type of database and then click OK.

● In the Properties window, type the appropriate values for the mandatory and optional
properties.
For a Microsoft SQL Server database, you can choose to use a port number, such as 1433,
or a named instance as the value for the Database server with port number or instance
name property.
To connect to a named instance, you must specify the instance name as a JDBC URL
property or a data source property. For example, you can type localhost\instance1. If no
instance name property is specified, a connection to the default instance is created.
Note that the properties specified for the named instance, along with the user ID and
password, and database name, are used to create a JDBC URL. Here is an example:
jdbc:JSQLConnect://localhost\\instance1/user=sa/more properties as required

● Test the connection to the new database. In the Explorer window, under Environment,
right-click Logging and click Test.
IBM Cognos 8 components connect to the database. If you configured more than one
database for logging messages, IBM Cognos 8 components test all the databases.

10. Repeat steps 4 to 9 for each destination to which you want the log server to send messages.

11. From the File menu, click Save.

12. In the Explorer window, click IBM Cognos 8 service, IBM Cognos 8.

13. From the File menu, click Restart.

If you selected a database as the destination, IBM Cognos 8 components create the required
tables and fields in the database that you created.

If the destination was a remote log server, configure and start the remote log server. Then restart
the IBM Cognos 8 service on the local computer.
If the destination was a database, you can use IBM Cognos 8 components to run log reports from
the database.

Installation and Configuration Guide 223

Chapter 11: Configuration Options

You can also set the logging level, which controls the amount of detail and type of messages that
are sent to a log file or database. For instructions, see the Administration and Security Guide.

Steps for DB2 for z/OS

1. On the computer where you installed Content Manager or the Application Tier Components,
start IBM Cognos Configuration.

2. In the Explorer window, under Environment, click Logging.

3. In the Properties window, use the following table to help set the log server properties.

Task Action

Use TCP between IBM Cognos 8 Set the Enable TCP property to True.
components on a computer and
UDP provides faster communication with a lower risk
its local log server
of lost connections than TCP.
TCP is used for communication between a local log
server and a remote log server.

Change the number of threads Type the value in the Local log server worker threads
available to the local log server property.
Set a value between 1 and 20. The default value of 10
is recommended. However, if you have a high number
of log messages, you can allocate more threads to
improve performance.

Apply UTF-8 encoding for log Set the Use UTF8 encoding property to True.
messages written to a file
If the IBM Cognos 8 component is using multibyte
encoding, you must set this property to True and use
a UTF-8 editor to view the log file. Otherwise, the log
file may contain unreadable characters.

4. In the Explorer window, under Environment, right-click Logging, and click New resource,
Destination.

5. In the Name box, type the name of the destination.

6. In the Type list, click Database and then click OK.

7. In the Explorer window, under Logging, right-click the database name, and click New resource,
Database.

8. In the Name box, type the name of the destination.

9. In the Type list, click DB2 database and then click OK.

224 PowerPlay®
 Chapter 11: Configuration Options

10. In the Properties window, type the Database server and port number, User ID and password,
and the z/OS Database name.
Ensure that the User ID is the same as the value you specified for the IPFSCRIPT_USERNAME
parameter in the LS_tablespace_db2zOS.sql script file, (p. 217).

11. In the Explorer window, click Local Configuration.

12. In the Properties window, next to Advanced properties, click inside the Value box, and then
click the edit button.

13. Click Add, and then add the following configuration parameter names and values:

Parameter Name Value

IPFSCRIPT_CREATE_IN The base tables location.

For example, databaseName.baseTablespaceName

IPFSCRIPT_STOGROUP The name of the storage group.

IPFSCRIPT_DATABASE The name of logging database.

IPFSCRIPT_LOB_TABLESPACE The name of the tablespace that is reserved for

auxiliary tables in the logging database.

14. From the File menu, click Save.

15. Test the connection to the new database. In the Explorer window, under Environment, right-
click Logging and click Test.
IBM Cognos 8 components connect to the database. If you configured more than one database
for logging messages, IBM Cognos 8 components test all the databases.

Changing Global Settings

You change global settings
● to customize language support for the user interface

● to customize currency support

● to customize content locale support

● to map content locales

● to map the language used in the product user interface

● to add fonts to your IBM Cognos environment

● to customize the default time zone

● to change the encoding for email messages

Installation and Configuration Guide 225

Chapter 11: Configuration Options

● to customize cookie settings

By default, IBM Cognos 8 components ensure that all locales, which may come from different
sources and in various formats, use a normalized form. That means that all expanded locales conform
to a language and regional code setting.
Each computer has a default system locale and one user locale per user. The user locales may be
different from the default system locale.

Important: If you change global settings on one Content Manager computer, you must make the
same changes on the other Content Manager computers.

Customize Language Support to the User Interface

Use the Product Locales table to add or remove the user interface language support. For example,
if you do not require a German user interface, you can remove the language from the list.
If you change the user interface language of the product, data is not affected.
Language files are installed with your IBM Cognos 8 product for all supported languages of user
interface. If you want users to see product documentation in a language other than English, you
must install the Supplementary Languages Documentation. For more information, see "Install
Translated Product Documentation" (p. 145).
Ensure that you install the appropriate fonts to support the character sets and currency symbols
you use. For Japanese and Korean currency symbols to appear correctly, you must install the
additional fonts from the Supplementary Languages Documentation CD. For more information,
see "Install and Configure Additional Language Fonts" (p. 146).

Steps
1. On each Content Manager computer, start IBM Cognos Configuration.

2. From the Actions menu, click Edit Global Configuration.

3. Click the Product Locales tab.

4. Click Add.

Tip: To remove support, select the check box next to the Supported Locale and then click
Remove.

5. In the second column, type the language portion of a locale.

6. Repeat steps 4 to 5 for other language support that you want to add.

7. Click OK.

8. From the File menu, click Save.

Customizing Currency Support

If you require additional currencies or want to remove some from the user interface, you can update
the list of supported currencies in the Currencies table. If you use Japanese or Korean currencies,
you must configure support so that Japanese Yan and Korean Won characters display correctly.

226 PowerPlay®
 Chapter 11: Configuration Options

Add Currencies to IBM Cognos 8

You can add supported or unsupported currencies to the user interface. You add supported currencies
in IBM Cognos Configuration. You add unsupported currencies to the i18n_res.xml file that is
provided in IBM Cognos 8.
By default IBM Cognos 8 components show only a subset of supported currencies in the user
interface. Currencies are identified by their ISO 4217 currency code. The complete list of supported
currencies that can be added are listed in the i18n_res.xml file in the c8_location\bin directory.
If you add a currency code that is not supported, you must manually add it to the i18n_res.xml file
in the c8_location\bin directory. Copy this file to each IBM Cognos computer in your installation.
Adding currencies to the IBM Cognos environment does not guarantee that your computer has a
font with the required characters to display the currency. Ensure that you install the appropriate
fonts to support the currency symbols you use. For example, to display the Indian currency symbol
(rupee) correctly, you must run a Japanese operating system or install a Japanese language. In
addition, for Japanese and Korean currency symbols to appear correctly, you must install the
additional fonts from the Supplementary Languages Documentation CD. For more information,
see "Install and Configure Additional Language Fonts" (p. 146).

Steps
1. On each Content Manager computer, start IBM Cognos Configuration.

2. From the Actions menu, click Edit Global Configuration.

3. Click the Currencies tab.

4. Click Add.

Tip: To remove support, select the check box next to the supported item and then click Remove.

5. In the second column, type an appropriate value.

The value you add must comply with ISO 4217 codes for the representation of currencies and
formats. Usually the value you add is a three-letter alphabetic code. The first two characters
are letters representing the ISO 3166 country code for the country the currency is from. The
additional letter represents the first letter of the currency.

6. Repeat steps 4 to 5 for other types of support that you want to add.

7. From the File menu, click Save.

Customize Content Locale Support

To ensure users see reports, data or metadata in their preferred language, or specific to their region,
you can add partial locales (language) or complete locales (language-region) to the Content Locales
table. This way, if content is available in different languages, or in different locales, it is rendered
to users based on their user locale. By default, content locale overrides product locale in the portal
for some content.
If you view reports in Thai language, digits are not supported.

Installation and Configuration Guide 227

Chapter 11: Configuration Options

If a locale is not required, you can remove it from the list. You must leave at least one content locale
in the list for the report server to operate.
Adding incomplete locales (languages) to the IBM Cognos environment does not guarantee that
your computer has a font that can display Web pages in your preferred languages. Ensure that you
install the appropriate fonts to support the character sets and currency symbols you use. For
Japanese and Korean currency symbols to appear correctly, you must install the additional fonts
from the Supplementary Languages Documentation CD. For more information, see "Install and
Configure Additional Language Fonts" (p. 146).

Steps
1. On each Content Manager computer, start IBM Cognos Configuration.

2. From the Actions menu, click Edit Global Configuration.

3. Click the Content Locales tab.

4. Click Add.

Tip: To remove support, select the check box next to the supported item and then click Remove.

5. In the second column, type an appropriate value.

● To add language support for report data and metadata, type a partial local (language) set-
ting.

● To add support specific to a region, type a complete locale (language-region) setting.

6. Repeat steps 3 to 5 for each additional locale that you want to support.

7. From the File menu, click Save.

Map Content Locales

Use the Content Locale Mappings table to map user locales to a complete (language-region) or
partial (language) locale. You can also map a user’s preferred language to another language if
content is not available in the user’s preferred language.
For example, if a report or scorecard is not available in a preferred language, for example Vietnamese,
but is available in French and German, you can use the Content Mappings table to map the preferred
language (Vietnamese) to another language (French or German). This way, you see the report or
scorecard in the mapped language.
By default, the Content Locale Mappings table includes locales that do not contain the region. This
allows you to use only the language portion of the locale when you specify locale settings and
ensures that you always see the correct information. For example, in a multilingual database, data
is usually available in different languages, such as French (fr), Spanish (es) and English (en), rather
than being available in different locales, such as English Canada (en-ca), English United States (en-
us), or French France (fr-fr).
The following examples show the method that IBM Cognos 8 components use to determine which
report or scorecard the user sees if the multiple language versions are available.

228 PowerPlay®
 Chapter 11: Configuration Options

Example 1
A report is available in Content Manager in two locales, such as en-us (English-United States) and
fr-fr (French-France), but the user locale is set to fr-ca (French-Canadian). IBM Cognos 8 uses the
locale mapping to determine which report the user sees.
First, IBM Cognos 8 checks to see if the report is available in Content Manager in the user’s locale.
If it is not available in the user’s locale, IBM Cognos 8 maps the user’s locale to a normalized locale
configured on the Content Locale Mapping tab. Because the user’s locale is fr-ca, it is mapped to
fr. IBM Cognos 8 uses the mapped value to see if the report is available in fr. In this case, the report
is available in en-us and fr-fr, not fr.
Next, IBM Cognos 8 maps each of the available reports to a normalized locale. Therefore, en-us
becomes en and fr-fr becomes fr.
Because both report and the user locale maps to fr, the user having the user locale fr-ca will see the
report saved with the locale fr-fr.

Example 2
The user’s locale and the report locales all map to the same language. IBM Cognos 8 chooses which
locale to use. For example, if a user’s locale is en-ca (English-Canada) and the reports are available
in en-us (English-United States) and en-gb (English-United Kingdom), each locale is mapped to en.
The user will see the report in the locale setting chosen by the your IBM Cognos 8 product.

Example 3
The report and the user locales do not map to a common language. Your IBM Cognos 8 product
chooses the language. In this case, you may want to configure a mapping. For example, if a report
is available in en-us (English-United States) and fr-fr (French-France), but the user locale is es-es
(Spanish-Spain), your IBM Cognos 8 product chooses the language.

Steps
1. On each Content Manager computer, start IBM Cognos Configuration.

2. From the Actions menu, click Edit Global Configuration.

3. Click the Content Locale Mapping tab.

4. Click Add.

5. In the Key box, type the user locale:

● To ensure all regions for a user locale see content in a specific language, type the language
portion of the locale, followed by a dash (-) and an asterisk (*).

For example, type fr-*

● To ensure a user locale (language-region) sees content in a specific language, type the
complete locale.

For example, type fr-ch

● To map a preferred language to another language, type the preferred language portion of
the locale.

Installation and Configuration Guide 229

Chapter 11: Configuration Options

For example, type zh

Tip: To specify the locale to use for a range of keys, use the wildcard character (*) with the
Key value and then, in the Locale Mapping box, type the locale. For example, if you want all
the German keys to use the German locale, type de* in the Key box and type de in the Locale
Mapping box.

6. In the Locale Mapping box, type the language portion of the locale.

User locales specified in the Key box will see content in this language.

7. Repeat steps 3 to 5 for other mappings you want to do.

8. Click OK.

9. From the File menu, click Save.

Map Product Locales

Use the Product Locale Mappings table to specify the language used in the user interface when the
language specified in the user’s locale is not available.
You can ensure that all regions for a locale use the same language, or that a specific, complete locale
(language-region) uses a particular language.
By default, the user sees the product interface in the language that matches the language setting of
the user locale.

Steps
1. On each Content Manager computer, start IBM Cognos Configuration.

2. From the Actions menu, click Edit Global Configuration.

3. Click the Product Locale Mappings tab.

4. Click Add.

5. In the Key box, type the user locale:

● To ensure all regions for a locale see the user interface in a specific language, type the lan-
guage portion of the locale, followed by a dash (-) and an asterisk (*).

For example, type es-*

● To ensure a complete locale (language-region) see the user interface in a specific language,
type the complete locale.

For example, type es-es

● To map a preferred language to another language, type the preferred language portion of
the locale.

For example, type zh

Tip: To specify which locale to use as the default, use the wildcard character (*) for the Key
value and then, in the Locale Mapping box type the locale.

230 PowerPlay®
 Chapter 11: Configuration Options

6. In the Locale Mapping box, type the language portion of the locale.

User locales specified in the Key box will see content in this language.

7. Repeat steps 3 to 5 for other mappings you want to do.

8. Click OK.

9. From the File menu, click Save.

Customize the Server Time Zone

You can customize the time zone used by Content Manager by selecting a different server time zone
in IBM Cognos Configuration.
For UNIX installations that do not support a Java-based graphical user interface, you can view the
list of acceptable time zones by opening IBM Cognos Configuration on the Windows computer
where Framework Manager is installed.
Content Manager is configured to use the time zone of your operating system by default. All
scheduled activities in IBM Cognos 8 are set using this time zone. In addition, users in IBM Cognos
Connection use this time zone if they set their preferences for the default time zone. For more
information about setting user preferences in IBM Cognos Connection, see the Administration and
Security Guide.

Steps
1. Start IBM Cognos Configuration.

2. From the Actions menu, click Edit Global Configuration.

3. In the Global Configuration window, click the General tab.

4. Click the Value column for Server time zone and select another time zone from the list.

5. From the File menu, click Save.

Change Encoding for Email Messages

By default, IBM Cognos 8 components use UTF-8 encoding in emails. This value sets the default
encoding used by the delivery service in this instance for all email messages. You may have older
email clients or send email from IBM Cognos 8 to cell phones and PDAs that do not recognize UTF-
8. If so, you can change the email encoding to a value that works on all your email clients (for
example, ISO-8859-1, Shift-JIS). Each instance of IBM Cognos 8 that has an available delivery
service must be changed.
The specified encoding affects the entire message, including the subject, attachments, attachment
names, and plain or HTML body text.

Character set Supported encoding value

UTF-8 utf-8

Installation and Configuration Guide 231

Chapter 11: Configuration Options

Character set Supported encoding value

Western European (ISO 8859-1) iso-8859-1

Western European (ISO 8859-15) iso-8859-15

Western European (Windows-1252) windows-1252

Central and Eastern European(ISO 8859-2) iso-8859-2

Central and Eastern European (Windows-1250) windows-1250

Cyrillic (ISO 8859-5) iso-8859-5

Cyrillic (Windows-1251) windows-1251

Turkish (ISO 8859-9) iso-8859-9

Turkish (Windows-1254) windows-1254

Greek (ISO 8859-7) iso-8859-7

Greek (Windows-1253) windows-1253

Japanese (EUC-JP) euc-jp

Japanese (ISO-2022-JP) iso-2202-jp

Japanese (Shift-JIS) shift_jis

Traditional Chinese (Big5) big5

Simplified Chinese (GB-2312) gb2312

Korean (EUC-KR) euc-kr

Korean (ISO 2022-KR) ISO 2022-KR

Korean (KSC-5601) ksc_5601

Thai (Windows-874) windows-874

Thai (TIS-620) tis-620

Steps
1. Start IBM Cognos Configuration.

232 PowerPlay®
 Chapter 11: Configuration Options

2. From the Actions menu, click Edit Global Configuration.

3. In the Global Configuration window, click the General tab.

4. Click the Value column for the Email Encoding property.

5. Scroll to the desired setting and click it.

6. From the File menu, click Save.

Customize Cookie Settings

Based on the requirements of your IBM Cognos environment, you may need to modify the settings
that IBM Cognos 8 components use to create cookies. You can use IBM Cognos Configuration to
customize the cookie domain, path, and secure flag.
IBM Cognos 8 components determine the cookie domain from the HTTP request submitted by the
client, which is typically a Web browser. In most network configurations, HTTP requests pass
through intermediaries such as proxy servers and firewalls as they travel from the browser to IBM
Cognos 8 components. Some intermediaries modify the information that IBM Cognos 8 components
use to calculate the cookie domain, and IBM Cognos 8 components then cannot set cookies. The
usual symptom of this problem is that users are repeatedly prompted to log on. To avoid this
problem, configure the cookie domain.
To set the correct value for the cookie domain, use the format and value that represents the widest
coverage for the host.

Host Format for domain Example

computer or server computer or server name (no mycompany

dots)

suffix is .com, .edu, .gov, .int, .name.suffix .mycompany.com

.mil, .net, or .org (two dots)

other .name1.name2.suffix .travelinfo.co.nz

(three dots)

Steps
1. On each Content Manager computer, start IBM Cognos Configuration.

2. From the Actions menu, click Edit Global Configuration.

3. Click the General tab.

4. Click in the Value column under Cookie Settings for each property that you want to change
and specify the new value.

If you leave the Domain property blank, the dispatcher derives the domain from the host name
of the request.

Installation and Configuration Guide 233

Chapter 11: Configuration Options

5. Click OK.

Configure the Router to Test Dispatcher Availability

If you use a router to distribute requests to IBM Cognos 8 dispatchers, and the router can test the
availability of a server using a test URL, you can configure the router to test the availability of an
IBM Cognos 8 dispatcher.

Step
● Configure the router to use a URL with the path /p2pd/servlet/ping
If the dispatcher is not ready, the following response is returned:
503 Service Unavailable
If the dispatcher is ready, the following response is returned:
200 OK

Changing the Gateway

To improve Web server performance, you can configure IBM Cognos 8 to use alternate gateways
that replace the default CGI program. You can use one of the following gateways:
● Microsoft Internet Application Programming Interface (ISAPI) for Microsoft Internet Information
Services on Windows

● Apache Web Server module

● Servlet Gateway Java application for application servers

There is no additional Web server configuration required to use ISAPI. To access IBM Cognos 8
components using ISAPI, in IBM Cognos Configuration, change the cognos.cgi portion of the
Gateway URI property to cognosisapi.dll.
Before you change the gateway, we recommend that you first ensure that the default CGI gateway
and your configuration work in your environment.

Configure the Gateway for IBM Cognos Apache Web Server Module
IBM Cognos 8 provides three Apache modules. The IBM Cognos Apache module requires Apache
Server 1.3.x and the IBM Cognos Apache 2 module requires Apache Server 2.0.x. The IBM Cognos
Apache 2.2 module requires Apache Server 2.2.x.

Steps
1. Stop Apache Web Server.

2. Append the c8_location/cgi-bin directory to the appropriate environment variable:

● On Solaris or Linux, LD_LIBRARY_PATH

● On HP-UX,

234 PowerPlay®
 Chapter 11: Configuration Options

For Apache 1.3, SHLIB_PATH

For Apache 2.0 and Apache 2.2.x, SHLIB_PATH and LD_LIBRARY_PATH

● On AIX, LIBPATH

3. On HP-UX PA-RISC, do the following:

● Ensure that the LD_PRELOAD environment variable contains /usr/lib/libcl.2.

● For Apache 1.3, set the COG_CGIBIN_DIR environment variable to c8_location/cgi-bin.

4. Go to the Apache_installation/conf directory.

5. Open the httpd.conf file in an editor.

6. Add the following to the end of the load module list:

LoadModule cognos_module "c8_location/cgi-bin/module.suffix"

where module is as follows:

Version Module

Apache 1.3 mod_cognos

Apache 2.0 mod2_cognos

Apache 2.2 mod2_2_cognos

and suffix is as follows:

Operating system Suffix

Windows dll

Solaris, AIX so

HP-UX PA-RISC sl

HP-UX IA, Linux so

7. For Apache 1.3, add the following to the end of the add module list:

AddModule mod_cognos.cpp

8. Add the following to the aliases section:

ScriptAlias /cognos8/cgi-bin "c8_location/cgi-bin"

Alias /cognos8 "c8_location/webcontent"

<Directory "c8_location/webcontent">

Installation and Configuration Guide 235

Chapter 11: Configuration Options

Options Indexes MultiViews

</Directory>

The <Directory> directive is optional.

Tip: Ensure that you define the cognos8/cgi-bin alias before the cognos8 alias.

9. For Apache 2.2, add the following security rules:

ScriptAlias /cognos8/cgi-bin " c8_location/cgi-bin"

Alias /cognos8 "c8_location/webcontent"

<Directory "c8location/webcontent">

Options Indexes MultiViews

AllowOverride None

Options None

Order allow,deny

Allow from all

</Directory>

<Directory "c8location/cgi-bin">

AllowOverride None

Options None

Order allow,deny

Allow from all

</Directory>

10. For Apache 1.3 and Apache 2.0, add the following to the server status reports section:
<Location /cognos8/cgi-bin/cognos_module>
SetHandler cognos-handler
</Location>

For Apache 2.2.x, add the following to the server status reports section:
<Location /cognos8/cgi-bin/cognos_module>
SetHandler cognos-handler
Order allow,deny
Allow from all
</Location>

Enter the code exactly as specified. The "cognos_module" string refers to the module that you
loaded in step 6.

11. For Apache 1.3 and Apache 2.0, to enable the gateway diagnostic page, add the following to
the server status reports section:
<Location /cognos8/cgi-bin/diag_cognos_module>
SetHandler cognos-handler
</Location>

236 PowerPlay®
 Chapter 11: Configuration Options

For Apache 2.2.x, add the following to the server status reports section:
<Location /cognos8/cgi-bin/cognos_module>
SetHandler cognos-handler
Order allow,deny
Allow from all
</Location>

Enter the code exactly as specified. The diag_ string is required and the "cognos_module"
string refers to the module that you loaded in step 6.

12. For Apache 1.3, on Windows, Solaris, and AIX, add the following to the user directory section:
<IfModule mod_cognos.cpp>

CGIBinDir "c8_location/cgi-bin"
</IfModule>

13. For Apache 2.0, add the following to the user directory section:
<IfModule mod_cognos.c>

CGIBinDir "c8_location/cgi-bin"
</IfModule>

For Apache 2.2.x, add the following to the user directory section:
<IfModule mod2_2_cognos.c.c>

CGIBinDir "c8_location/cgi-bin"
</IfModule>

14. Save and close the file.

15. For Apache 2.0, on HP-UX, enable searching for LD_LIBRARY_PATH by running the following
command in the Apache_installation/bin directory:

chatr +s enable +b enable httpd

16. Start Apache Web Server.

17. In IBM Cognos Configuration, configure the Gateway URI property to use the apache_mod
gateway:

http://host_name:port/cognos8/cgi-bin/module.suffix
where module and suffix match the values shown previously.

18. Users must then specify the Apache module URI in their browser, as follows

http://host_name/cognos8/module.suffix
where module and suffix match the values that you configured for the Gateway URI in IBM
Cognos Configuration.

Installation and Configuration Guide 237

Chapter 11: Configuration Options

Configuring the Servlet Gateway

If you configure the IBM Cognos Servlet Gateway to run on a supported application server, your
environment does not require a Web server. The application server and the IBM Cognos Servlet
Gateway replace the functions provided by a Web server and other IBM Cognos gateways.
Before you build and deploy the IBM Cognos Servlet Gateway, ensure the following:
● The application server is installed and running on each computer where the servlet gateway is
to be installed.

● IBM Cognos 8 Gateway components are installed (p. 118) on the same system as the application
server.

● The IBM Cognos 8 dispatcher and Content Manager components are installed and running in
the environment.

● The application server user account has full access permissions for the IBM Cognos installation.
We recommend that you create a new UNIX or Linux group named cognos8. This group must
contain the user that starts the application server and the user that owns the IBM Cognos files.
Change the group ownership of the IBM Cognos files to the cognos8 group, and change the
file permissions for all IBM Cognos files to GROUP READABLE/WRITABLE/EXECUTABLE.
For simplicity, you can also use the application server user account to install and run IBM
Cognos components.

To set up the IBM Cognos Servlet Gateway to run on your application server, do the following:
❑ Create a separate JVM instance, if necessary.
If you plan to run IBM Cognos 8 and the IBM Cognos Servlet Gateway on the same application
server, the servlet gateway must be deployed to a separate JVM instance.

❑ Check that IBM Cognos components are properly set up.

❑ Set environment variables.

❑ Update the Java environment.

❑ Configure IBM Cognos Servlet Gateway to run on the application server.

❑ Change the application server startup script, if necessary.

❑ Change the IBM Cognos dispatcher properties file, if using Oracle Application Server.

❑ Configure application server properties and deploy IBM Cognos Servlet Gateway.

❑ Enable SSL, if required.

❑ Configure the Web server.

You can then access IBM Cognos 8 components using the IBM Cognos Servlet Gateway, by entering
the gateway URI. For example,

http[s]:host_name:port/ServletGateway
The IBM Cognos Servlet Gateway URI is case-sensitive.

238 PowerPlay®
 Chapter 11: Configuration Options

Change the IP Address Version

IBM Cognos 8 supports two IP address versions: IPv4 and IPv6. IPv4 uses 32-bit IP addresses and
IPv6 uses 128-bit IP addresses. For example:
● IPv4: 192.168.0.1:80

● IPv6: [2001:0db8:0000:0000:0000:148:57ab]:80

In IBM Cognos Configuration, you can select IPv4 or IPv6 for IBM Cognos 8 communication using
the IP Version for Host Name Resolution property. By default IPv4 is employed.

The setting applies only to the computer where it is set. If you selectPrefer IPv4 stack, all outgoing
IBM Cognos 8 connections on that computer are established using IPv4 and the dispatcher accepts
only incoming IPv4 connections. If you select Prefer IPv6 addresses, all outgoing IBM Cognos 8
connections on that computer are established using IPv6 and the dispatcher accepts both incoming
IPv4 and IPv6 connections.
IPv4 client computers can communicate with dispatcher computers that are configured for IPv6.

Hostnames specified within a URI are resolved based on the value of the Network Configuration
property. However, if a URI has been specified with a numeric address, it has precedence over this
setting and communication takes place using IPv4.

The setting applies only to the computer where it is set. If you selectUse IPv4 addresses, all outgoing
IBM Cognos 8 connections on that computer are established using IPv4 and the dispatcher accepts
only incoming IPv4 connections. If you select Use IPv6 addresses, all outgoing IBM Cognos 8 con-
nections on that computer are established using IPv6 and the dispatcher accepts both incoming
IPv4 and IPv6 connections.
IPv4 client computers can communicate with dispatcher computers that are configured for IPv6.

Hostnames specified within a URI are resolved based on the value of the IP Version for Host Name
Resolution property. However, if a URI has been specified with a numeric address, it has precedence
over this setting and communication takes place using IPv4.
For IBM Cognos Configuration to accept IPv6 addresses in the local URI properties, you must start
IBM Cognos Configuration with the -ipv6 option. You can specify the option each time you open
IBM Cognos Configuration from the command line.
On Windows, you can set the option permanently by adding the option to the Start menu shortcut.

Steps to Set the IP Version

1. Start IBM Cognos Configuration.

2. In the Explorer window, click Environment.

3. Click the Value box for IP Version for Host Name Resolution and click Use IPv4 addresses or
Use IPv6 addresses.

4. From the File menu, click Save.

Installation and Configuration Guide 239

Chapter 11: Configuration Options

5. Close IBM Cognos Configuration.

Steps to to Manually Enable the IPv6 Option When Opening IBM Cognos Configuration
1. Go to the c8_location\bin directory.

2. Start IBM Cognos Configuration by including the IPv6 option in the command, as follows:
● On Windows, type

cogconfig.bat -ipv6

● On UNIX or Linux, type

./cogconfig.sh -ipv6

3. Edit the URI properties that use IPv6 format, specify the values, and then from the File menu,
click Save.

Steps to Always Open IBM Cognos Configuration With the IPv6 Option on Windows
1. From the Start menu, select Programs, IBM Cognos 8, and then right-click IBM Cognos Con-
figuration, Properties.

2. On the Shortcut tab, in the Target box, type

"c8_location\bin\cogconfigw.exe -ipv6"

3. Click OK.

Update File Location Properties on Windows Vista

If you install IBM Cognos 8 client components in an environment that includes Windows Vista,
you must change file locations properties in IBM Cognos Configuration so that IBM Cognos 8 can
use a single data location for all users. The changes must be made on all computers where IBM
Cognos 8 client components are installed.
Windows Vista has a security enhancement that restricts multiple users from sharing data locations.
You can define environment variables and use them in IBM Cognos Configuration when specifying
file locations. This allows you to direct applicable files to an area that will be accessible by IBM
Cognos 8 users. On Windows, two environment variables are preset for users: one for all users and
one for the specific user.
Because the environment variables represent system root locations, we recommend that you also
include the root directory name of the installation location when you specify file locations in IBM
Cognos Configuration. The default root directory for IBM Cognos 8 is c8.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window, click Environment.

3. In the Properties window, click Deployment files location.

240 PowerPlay®
 Chapter 11: Configuration Options

4. Replace the relative path element, "..", with the appropriate environment variable and root
directory:
● For a single file location per user, %LOCALAPPDATA%

● For a single file location for all users on the computer, %PUBLIC%

For example,
To set a single file location per user, specify the path %LOCALAPPDATA%/c8/deployment.

5. Repeat step 4 for the following properties:

● Under Environment,

- Data files location

- Map files location

- Temporary files location

● Under Environment, Logging, File,

- Log file location

● Under Cryptography,

- Common symmetric key store location

● Under Cryptography, Cognos,

- Certificate location

- Signing key store location

- Encryption key store location

6. From the File menu, click Save.

The environment variables are resolved when the file locations are accessed during system activities.

Installation and Configuration Guide 241

Chapter 11: Configuration Options

242 PowerPlay®
Chapter 12: Configuring Portal Services

Portal Services provides a set of Cognos portlets that you can use in IBM Cognos Connection and
in other portals. You can use the portlets to navigate, search, and view IBM Cognos reports in your
working environment. Other users can view IBM Cognos information without needing to know
how to use IBM Cognos products.
For more information, see the Administration and Security Guide.
Portal Services is installed automatically with IBM Cognos 8 components. In a distributed environ-
ment, it is included with the Application Tier Components. The installation includes the deployment
files for
● SAP Enterprise Portal (SAP EP)

● IBM WebSphere Portal

● BEA Aqualogic User Interaction (BEA ALUI) Portal

● SharePoint Portal

For some deployments of Portal Services, you must modify some Portal Services property settings
and prepare the IBM Cognos environment to support the portal.
When used in a third-party portal, Portal Services can authenticate users in only one namespace. If
IBM Cognos 8 components are configured with more than one namespace, you must install a sep-
arate gateway for each namespace that will be used to authenticate portal users. You must configure
each gateway to use the appropriate namespace (p. 199) and then configure the deployed portlets
to use that gateway.
After you configure the required properties, you must deploy the Cognos portlets to the third-party
portal. For more information, see the Administration and Security Guide.
To use Portal Services with IBM Cognos 8 components, do the following:
❑ Specify the location of the applications.xml file, if required.

❑ Install and test the portlets on the third-party portal.

For more information, see the Administration and Security Guide.

❑ Configure security for the third-party portal environment.

Specify the Location of the Applications.xml File

If you use the applications.xml file as part of a custom application portlet, all Application Tier
Components computers in a distributed environment must reference the same applications.xml file.
If you have multiple instances of the applications.xml file, they must be identical.

Installation and Configuration Guide 243

Chapter 12: Configuring Portal Services

Note: The steps are required only if you want to use the Extended Applications portlet, which is
included with the IBM Cognos 8 software development kit.

Steps
1. On the computer where you installed the report server, start IBM Cognos Configuration.

2. In the Explorer window, under Environment, click Portal Services.

3. In the Properties window, click the Value next to Location of ’applications.xml’.

4. Replace localhost with a valid host name or IP address and, if necessary, replace the default
port number.

5. From the File menu, click Save.

You can now deploy the Cognos portlets to your portal server. For instructions, see the Adminis-
tration and Security Guide.

Configuring Security for Portal Services

When using Portal Services in a portal other than IBM Cognos Connection, you must enable single
signon to provide seamless integration between that portal and IBM Cognos 8 components.
Portal Services uses single signon to authenticate users. This means that users do not have to log
on to other applications separately through the portal.
You must configure a URI into IBM Cognos 8 components for each portlet in Portal Services.
To enable security between IBM Cognos 8 components and a portal other than IBM Cognos Con-
nection, do the following:
❑ Disable anonymous access to IBM Cognos 8 components.
If your security infrastructure requires you to use another method for single signon, use one of
the following methods:

❑ Enable single signon for the portal using shared secret.

If your security infrastructure requires you to use another method for single signon, use one of
the following methods:
● "Enable Single Signon for WebSphere Portal Using the Application Server" (p. 252)

● "Enable Single Signon for BEA ALUI Portal Using Basic Authentication" (p. 253)

● "Enable Single Signon for BEA ALUI Portal Using SiteMinder" (p. 253)

❑ Configure IBM Cognos 8 components for SSL access, if required.

Disable Anonymous Access to IBM Cognos 8 Components

Portal Services uses single signon for authentication. If anonymous logon is enabled in IBM Cognos 8
components, Portal Services logs all portal users as anonymous. You must ensure that anonymous
access is disabled in IBM Cognos 8 components for single signon in Portal Services to be successful.

244 PowerPlay®
 Chapter 12: Configuring Portal Services

However, you can test the Portal Services connections using anonymous logon to ensure that the
portlets are working in the third-party portal.
If Portal Services fails to authenticate a user, the user receives an error message at the third-party
portal.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window, under Security, Authentication, click IBM Cognos.

3. In the Properties window, ensure that Allow anonymous access is set to False.

4. From the File menu, click Save.

5. Repeat steps 1 to 4 on all servers where you installed IBM Cognos 8 components.

Enable Single Signon Using Shared Secret

You can use shared secret for single signon between Cognos portlets and IBM Cognos 8 components.
The Cognos portlets send a message that contains an encrypted version of the portal user ID. The
encryption key is determined by the value of a secret character string shared between the portlets
and the custom Java security provider on the IBM Cognos server.
You can use shared secret for a portal other than IBM Cognos Connection only if portal user IDs
can be looked up in an NTLM, LDAP, or IBM Cognos Series 7 authentication namespace that is
shared by IBM Cognos 8 components.
IBM Cognos 8 components must have access to a directory server that contains user IDs for all
your portal users. Using IBM Cognos Configuration, you must configure an authentication namespace
so that the portal and IBM Cognos 8 components share the same authentication source.
You must also create a Custom Java Provider namespace to register the shared secret Java provider
that is provided with IBM Cognos 8 components. Within the portlets or iViews, you must link the
portlets or iViews to the Custom Java Provider namespace within your respective portal:
● Cognos iViews (SAP EP)

● Cognos Portlet Application (WebSphere Portal)

● remote server (BEA ALUI Portal)

● Cognos WebPart (SharePoint Portal)

You are not required to configure access to the Portal Services Web content. However, if you deploy
the portlets to a portal other than IBM Cognos Connection, you can configure access to an alternate
URI for Portal Services images and Web content.

Steps to Configure the Required Namespaces

1. In IBM Cognos Configuration, configure a namespace to authenticate portal users.

Installation and Configuration Guide 245

Chapter 12: Configuring Portal Services

For instructions about configuring LDAP, NTLM, or IBM Cognos Series 7 authentication
providers, see "Configuring IBM Cognos 8 Components to Use an Authentication Pro-
vider" (p. 149).

2. For an LDAP namespace, configure the following properties:

● For the Use external identity property, change the setting to True.

● For the External identity mapping property, set it to

(uid=${environment("REMOTE_USER")})

3. For an IBM Cognos Series 7 namespace, map the portal user IDs to IBM Cognos Series 7 user
IDs using OS signons.
For more information, see the IBM Cognos Series 7 documentation.

4. In IBM Cognos Configuration, create and configure a Custom Java Provider namespace.

● For the Namespace ID property, specify any new ID.

For example, cpstrusted

This new ID must be used in the portlet configuration settings.

● For the Java class name property, type

com.cognos.cps.auth.CPSTrustedSignon
Java class names are case-sensitive.

5. In IBM Cognos Configuration, under Environment, Portal Services, configure the following
properties:

● For Trusted Signon Namespace ID, type the namespace ID of the LDAP, NTLM, or IBM
Cognos Series 7 namespace that you configured in step 1.

Tip: The trusted signon namespace acts as an intermediary and must be attached to a real
directory-based namespace of type LDAP, NTLM, or IBM Cognos Series 7.

● For Shared Secret, type the key to be used for single signon.
This parameter represents the authorization secret that must be shared between the Cognos
portlets and the IBM Cognos server. Consider this as a secret password. You must use the
same character string when you configure the portlet application. You must use a single
word as the key.
For security reasons, we recommend you specify a non-null value.

6. Under Environment, for Gateway Settings, set the Allow Namespace Override property to true.

7. From the File menu, click Save.

246 PowerPlay®
 Chapter 12: Configuring Portal Services

8. Restart the IBM Cognos 8 service.

Steps to Configure Access to the Portal Services Web Content

1. On the computer where you installed the Application Tier Components, start IBM Cognos
Configuration.

2. In the Explorer window, under Environment, click Portal Services.

3. In the Properties window, click the Value box next to Web Content URI.

4. Specify the host name or IP address of the gateway and a port number using the format
host_or_IP_address:port

5. From the File menu, click Save.

Steps to Configure the Cognos iViews for SAP EP

1. Open the iView editor for each Cognos iView.

2. In the Property Category box, select Show All.

3. For the cpsauthsecret: CPS Authorization Secret property, enter the secret character string that
you used for the Shared Secret property when you configured the Custom Java Provider
namespace.

4. For the cps: authentication namespace ID property, enter the Custom Java Provider namespace
ID.

5. For the cpsserver: CPS Connection Server property, enter the URL path to access Portal Services
components through the gateway.
The format of the URL is as follows:
● For Cognos content portlets

Gateway_URI/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl
Example for a CGI gateway:

http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_action=cps.
wsdl
Example for a servlet gateway:

http://172.0.16.1:9500/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl

● For Cognos Extended Applications

Gateway_URI/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl
Example for a CGI gateway:

http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.
wsdl
Example for a servlet gateway:

http://172.0.16.1:9500/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl

Installation and Configuration Guide 247

Chapter 12: Configuring Portal Services

● For IBM Cognos Metrics Manager Watchlist portlets

Gateway_URI/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl
Example for a CGI gateway:

http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.
wsdl
Example for a servlet gateway:

http://172.0.16.1:9500/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl

Steps to Configure the Cognos Portlets for WebSphere Portal

1. For each Cognos portlet application, click Modify Parameters.

2. For the cps_auth_secret property, enter the secret character string that you used for the Shared
Secret property when you configured the Custom Java Provider namespace.

3. For the cps_auth_namespace property, enter the Custom Java Provider namespace ID.

4. For the CPS Endpoint property, enter the URL path to access Portal Services components
through the gateway.
The format of the URL is as follows:
● For Cognos content portlets

Gateway_URI/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl
Example for a CGI gateway:

http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_action=cps.
wsdl
Example for a servlet gateway:

http://172.0.16.1:9500/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl

● For Cognos Extended Applications

Gateway_URI/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl
Example for a CGI gateway:

http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.
wsdl
Example for a servlet gateway:

http://172.0.16.1:9500/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl

● For Metrics Manager Watchlist portlets

Gateway_URI/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl
Example for a CGI gateway:

http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.
wsdl

248 PowerPlay®
 Chapter 12: Configuring Portal Services

Example for a servlet gateway:

http://172.0.16.1:9500/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl

Steps to Configure the Remote Server for BEA Aqualogic User Interaction (BEA ALUI)
Portal
1. Using a plain ASCII editor, such as Notepad, edit the cpspt.properties file in the c8_location/
cps/bea_aqualogic/webapps/gadgets/WEB-INF/classes directory.

2. Configure the following settings.

Parameter Value

cps_endpoint The URL to connect to the report server and extract the WSDL
information.
Specify the URI to the gateway.
For a servlet or ISAPI gateway, replace the localhost/cognos8/
cgi-bin/cognos.cgi portion with the values to target the gateway.
For example,

http://host_name/cognos8/cgi-bin/cognos.isapi/wsrp/cps4/
portlets/[package]?wsdl&b_action=cps.wsdl

forward_cookies= The names of the cookie that should be sent to the report server
for single signon.
Leave blank.

cps_auth_secret The shared secret code IBM Cognos 8 uses to encrypt an HTTP
header variable that carries the user identity.
This parameter represents the authorization secret that must be
shared between the Cognos portlets and the IBM Cognos 8
server. Consider this as a secret password. Use the same value
that you used for Shared Secret in IBM Cognos Configuration.
For security reasons, we recommend you specify a non-null value.

cps_auth_namespace The namespace ID for the Custom Java Provider.

3. Go to the c8_location/cps/bea_aqualogic directory and run the following build file:

● On UNIX or Linux, build.sh

● On Windows, build.bat

This creates a cps-alui.war file in the c8_location/cps/bea_aqualogic/gadgets directory.

4. If IBM Cognos 8 components are running using Tomcat,

Installation and Configuration Guide 249

Chapter 12: Configuring Portal Services

● Stop IBM Cognos 8.

● Copy the cps-alui.war file to the c8_location/webapps directory.

Tomcat automatically expands the WAR file and starts the remote server.

● Start IBM Cognos 8.

5. If IBM Cognos 8 components are running under another type of application server, copy the
cps-alui.war file to the application server.
For instructions, see the administration guide for your application server.

Single signon is configured.

Steps to Configure Properties for the Cognos WebPart for SharePoint Portal
1. Using a plain ASCII editor, such as Notepad, edit the web.config file in the drive\Program
Files\Common Files\Microsoft Shared\web server extensions\12\CONFIG directory.

2. Find the following string:

<SSO cps_auth_namespace="" cps_auth_secret="" />

3. Set cps_auth_namespace to the namespace ID for the Custom Java Provider namespace.

4. Set cps_auth_secret to the value that you used for Shared Secret in IBM Cognos Configuration.

Enable Single Signon for SAP EP with the SAP Logon Ticket
If you enable single signon with the SAP Logon Ticket, you must configure IBM Cognos 8 compon-
ents with an SAP namespace that links to an SAP BW server.
Then you must copy the certificate that was generated during SAP EP installation to the SAP BW
personal security environment.
Users must have the same user ID in all SAP systems that are accessed through single signon.
Before you start, ensure that you have
● configured IBM Cognos 8 components to use an SAP authentication source

● enabled single signon between IBM Cognos 8 components and SAP BW

● installed the latest service packs on the SAP BW server

Service packs can be downloaded from SAPNET.

● installed the latest hot patches for the SAP portal

● installed the Enterprise Portal plug-in that corresponds to the SAP EP release or SAP BW server
For SAP releases earlier than 6.2, on SAPNET, download EP50_PLUG-IN for Basis 620 (SAP-
KINE32A). Using transaction SAINT, install SAPKINE32A.

● installed the SAP Security Library on the SAP BW servers

From sapservX, under /general/misc/security/SAPSECU/platform, download sapsecin and
sepsecu.dll and place both files in the /run directory of the SAP BW server.

250 PowerPlay®
 Chapter 12: Configuring Portal Services

To enable SSO for SAP EP, complete the procedures for single signon with SAP logon tickets in the
SAP Enterprise Portal Security Guide.
You can now use the Cognos iViews in the SAP Enterprise Portal. For more information, see the
Administration and Security Guide.

Enable Single Signon for SAP EP with User Mapping

If you enable single signon with user mapping, you define an IBM Cognos data source in SAP EP.
Individual users or an administrator can enter the user IDs and passwords for IBM Cognos 8
components in the data source. You must map the users logon credentials in the data source to an
LDAP or IBM Cognos Series 7 or NTLM namespace. Portal Services iViews transmit the logon
credentials to IBM Cognos 8 components using HTTP Basic Authentication.

Steps to Prepare the Environment

1. Configure the gateway URI that will be used by Portal Services to require authentication using
HTTP Basic Authentication.
For information about configuring a URL to use HTTP Basic Authentication, see the document-
ation for the gateway or for your Web server.

2. Adjust the iView configuration to access the secure URL.

For information, see the documentation for your Web server.

3. In IBM Cognos Configuration, configure a namespace to authenticate portal users.

4. If you use an LDAP namespace, configure the following properties:

● For the Use external identity property, change the setting to True.

● For the External identity mapping property, set it to

(uid=${environment("REMOTE_USER")})

Steps to Create the Data Source and Map the Users

1. In the SAP portal, ensure that the following properties are configured for the data source in
the /PortalContent/other_vendors/every_user/com.cognos.pct.c8/systems/Cognos 8 directory:

● Logon Method = UIDPW

● server name = the name of the IBM Cognos server

● port number = port number of the gateway

● Protocol of Target system = HTTP

● User Mapping Type = admin,user

● system alias (Create a system alias)

For more information, see the SAP Enterprise Portal Administration Guide.

Installation and Configuration Guide 251

Chapter 12: Configuring Portal Services

2. For each Cognos iView, enable user mapping for the data source by entering the name of the
system alias at the iView level, in an attribute called CPS: User Mapping Datasource.
For more information, see the SAP Enterprise Portal Administration Guide.

3. For each Cognos iView, set the CPS: Authentication Namespace ID property to the namespace
that you want to use for authentication.

4. Register the IBM Cognos credentials for the portal users.

Users can enter their own user IDs and passwords.
For more information, see the SAP Enterprise Portal Administration Guide.

We recommend that you enable secure communication between SAP EP and IBM Cognos 8.
You can now use the Cognos iViews in the SAP Enterprise Portal. For more information, see the
Administration and Security Guide.

Enable Secure Communication Between SAP EP and IBM Cognos 8 Components

A secure connection, using SSL, is not required between SAP EP and IBM Cognos 8 components.
It is more important if you enabled single signon with user mapping.
The SSL security supported by SAP uses encryption above 56 bits. By default, IBM Cognos 8 com-
ponents use an encryption algorithm up to 56 bits. IBM Cognos provides an enhanced encryption
module as a complementary product. To enable SSL, you must purchase and install the Enhanced
Encryption Module for OpenSSL on top of IBM Cognos 8 components. For more information, see
the IBM Cognos Enhanced Encryption Module for OpenSSL Installation and Configuration Guide.
To enable SSL between SAP EP and IBM Cognos 8 components, see your SAP EP security docu-
mentation.

After SSL is enabled, edit properties for the all iViews so that the cpsserver: CPS Connection Server
property uses https instead of http.
You can now use the Cognos portlets in the SAP Enterprise Portal. For more information, see the
Administration and Security Guide.

Enable Single Signon for WebSphere Portal Using the Application Server
The Portal Services portlets can use the Active Credentials objects provided by WebSphere Portal
to connect to IBM Cognos 8 components. Portal Services supports the following Active Credentials
objects: HttpBasicAuth, LtpaToken, SiteMinderToken, and WebSealToken.
Credentials for the portal user are passed to the gateway using this object. For more information
about Active Credential objects, see the documentation for IBM WebSphere Portal.
To use application server single signon, see the documentation for IBM WebSphere Application
Server.
For information about SSL for IBM Cognos 8 components on a WebSphere Application Server, see
"Configure SSL for IBM Cognos 8" (p. 210).
After single signon is set up, you can use the Cognos portlets in the WebSphere Portal. For more
information, see the Administration and Security Guide.

252 PowerPlay®
 Chapter 12: Configuring Portal Services

Enable Single Signon for BEA ALUI Portal Using Basic Authentication
You can configure a portlet in BEA ALUI Portal to send the username and password as an HTTP
Basic authentication header. The header can be used with an NTLM, LDAP, or IBM Cognos Series 7
authentication namespace to provide single signon.

Steps
1. In IBM Cognos Configuration, configure a namespace to authenticate portal users.

2. Install an alternate CGI or ISAPI or servlet gateway in IBM Cognos 8.

3. Configure the new gateway.

For instructions, see "Configure Environment Properties for Gateway Computers" (p. 124)

4. In the administration console of the Web server, configure the virtual directories to access the
gateway.
For more information, see "Configure the Web Server" (p. 121).

5. Configure the BEA ALUI remote server to access IBM Cognos 8:

● Edit the cpspt.properties file in the c8_location/cps/bea_aqualogic/webapps/gadgets/WEB-
INF/classes directory.

● Change the cps_endpoint property to indicate the URL of the gateway.

For a CGI gateway, you can use the default setting if the gateway and the remote server
are on the same computer. Otherwise, replace the localhost portion with host_name:port
For a servlet or ISAPI gateway, replace the localhost/cognos8/cgi-bin/cognos.cgi portion
with the values to target the gateway.
For example,

http://host_name:port/cognos8/cgi-bin/cognos.isapi/wsrp/cps4/portlets/[package]?wsdl&b_
action=cps.wsdl

● Set the cps_auth_namespace property to the namespace that you want to use for authentic-
ation.

Enable Single Signon for BEA ALUI Portal Using SiteMinder

If you use eTrust SiteMinder to provide single signon in your security infrastructure, you can also
use it for single signon with BEA ALUI Portal.
You must configure a SiteMinder authentication namespace in IBM Cognos 8. BEA ALUI Portal
sends the SiteMinder active authentication token to the remote server, which sends the token to the
IBM Cognos 8 gateway.

Steps
1. In IBM Cognos Configuration, configure a SiteMinder authentication namespace.
For instructions, see "Configuring IBM Cognos 8 Components to Use eTrust SiteMinder" (p. 177).

Installation and Configuration Guide 253

Chapter 12: Configuring Portal Services

2. Configure the remote server to forward the authentication token:

● Edit the cpspt.properties file in the c8_location/cps/bea_aqualogic/webapps/gadgets/WEB-
INF/classes directory.

● Change the forward_cookies property to include the name of the active authentication
token that SiteMinder provides.

● Change the cps_endpoint property to indicate the URL of the gateway.

For a CGI gateway, you can use the default setting if the gateway and the remote server
are on the same computer. Otherwise, replace the localhost portion with host_name:port.
For a servlet or ISAPI gateway, replace the localhost/cognos8/cgi-bin/cognos.cgi portion
with the values to target the gateway.
For example,

http://host_name:port/cognos8/cgi-bin/cognos.isapi/wsrp/cps4/portlets/[package]?wsdl&b_
action=cps.wsdl

● Change the cps_auth_namespace property to the namespace that you want to use for
authentication.

254 PowerPlay®
Chapter 13: Configuring IBM Cognos 8 for an
Application Server

IBM Cognos 8 installs and uses Tomcat as the application server by default. You can choose to run
IBM Cognos 8 within one of the following supported application servers instead:
● BEA WebLogic Server

● IBM WebSphere Application Server

● Oracle Application Server

● Red Hat JBoss

● SAP NetWeaver

● Sun Java Systems Application Server (for Windows, Linux, and Solaris operating systems only)

To ensure your product works properly, apply all minimum required operating system patches and
use only the versions of software that are supported for an IBM Cognos product.
To review an up-to-date list of environments supported by IBM Cognos products, such as operating
systems, patches, browsers, Web servers, directory servers, database servers, and application servers,
visit the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.
html).
You can choose to run the IBM Cognos Servlet Gateway on a supported application server instead
of using a Web server (p. 238). When using the servlet gateway, your environment does not require
a Web server. The application server and the servlet gateway replace the functions provided by the
Web server and other IBM Cognos gateways. IBM Cognos 8 must be installed and running prior
to configuring and deploying the IBM Cognos Servlet Gateway.
For information about configuring a multi-server distributed installation of IBM Cognos 8 in an
application server environment, visit the IBM Cognos Resource Center (http://www.ibm.com/
software/data/support/cognos_crc.html).
To set up IBM Cognos 8 to run on your application server, do the following:
❑ Create a separate JVM instance, if necessary.

❑ Check that IBM Cognos components are properly set up.

❑ Back up any existing IBM Cognos data and encryption keys, if required.

❑ Set environment variables.

❑ Update the Java environment.

❑ Configure IBM Cognos components to run within the application server.

❑ Identifying the JDK for WebLogic 9 on AIX, if necessary.

Installation and Configuration Guide 255

Chapter 13: Configuring IBM Cognos 8 for an Application Server

❑ Change the application server startup script, if necessary.

❑ Change the IBM Cognos dispatcher properties file, if using Oracle Application Server.

❑ Configure application server properties and deploy IBM Cognos 8.

❑ Enable SSL, if required.

❑ Configure the web server.

❑ Unregister dispatchers that are no longer used.

❑ Import any backed up content store data.

After setting up IBM Cognos 8 to run on your application server, you can perform some additional
configuration tasks to customize the behavior of IBM Cognos components to better suit your
reporting environment (p. 187).

Tip: Do not use install paths that contain spaces for the application server or IBM Cognos 8. Spaces
interfere with the internal scripts and command parameters. If you must use an install path that
includes spaces, use the 8.3 DOS naming convention when referring to these locations.

Create a Separate JVM Instance

To eliminate potential java class or system resource conflicts, IBM Cognos 8 must be run in a Java
Virtual Machine (JVM) instance isolated from other existing applications. This ensures that IBM
Cognos 8 does not affect any existing customer applications. When possible, IBM Cognos 8 must
be installed in a JVM instance that is separate from the application server admin processes to isolate
both IBM Cognos 8 and the administrative functions of the application server.
An isolated JVM instance can be established by creating one of the following:
● a separate managed server in BEA WebLogic

● a separate server instance in IBM WebSphere

● a separate OC4J instance in Oracle 10g Application Server

● a separate server instance for Red Hat JBoss

● a separate Java instance for SAP NetWeaver

● a separate server instance for Sun Java System Application Server

If you are using the IBM Cognos Servlet Gateway, it must be run in an instance that is separate
from IBM Cognos 8.

Check the Setup of IBM Cognos Components

Ensure that the following is done before you set up IBM Cognos components to run on the applic-
ation server:
❑ IBM Cognos components are installed (p. 93).

256 PowerPlay®
 Chapter 13: Configuring IBM Cognos 8 for an Application Server

❑ Before you start IBM Cognos 8, the database for the content store must be set up. Install and
configure the database clients, if required, and then test the database connectivity.

❑ The application server is installed and operational on each computer where IBM Cognos
components are installed.
For more information about installation, see your application server documentation.

❑ The fully qualified installation location of all fonts is specified on all Application Tier Component
computers. You specify this location in IBM Cognos Configuration (p. 202). By default, the
installation location does not use a fully qualified path.

❑ The application server user account has full access permissions for the IBM Cognos installation.

Tip: We recommend that you create a new UNIX or Linux group named cognos8. This group
must contain the user that starts the application server and the user that owns the IBM Cognos
files. Change the group ownership of the IBM Cognos files to the cognos8 group and change
the file permissions for all IBM Cognos files to GROUP READABLE/WRITABLE/
EXECUTABLE. For simplicity, you can also use the application server user account to install
and run IBM Cognos components.

Back Up Existing IBM Cognos Information

You must back up existing IBM Cognos information if IBM Cognos 8 components are running
● on an application server (including Tomcat) and you are changing to an application server that
ships with its own JVM.

● with a JVM from one vendor and you are changing to another JVM vendor.

Note: You must back up existing IBM Cognos information within the working environment prior
to upgrade.
Before configuring IBM Cognos 8 components to run on the new application server or JVM, you
must back up
● content store data by creating a deployment export.

● configuration information by exporting it. Any encrypted data is decrypted during the export.

● cryptographic keys by saving them to an alternate location. New cryptographic keys must be
created using the same JVM that the application server uses. Because these keys can be created
only if the previous keys are deleted, it is important to back up the previous keys.

To ensure the security and integrity of your IBM Cognos data, back up the content store, configur-
ation information, and cryptographic keys to a directory that is protected from unauthorized or
inappropriate access.

Installation and Configuration Guide 257

Chapter 13: Configuring IBM Cognos 8 for an Application Server

Tip: To check if any cryptographic keys exist, look in the c8_location/configuration directory.
Cryptographic keys exist if this directory includes the following subdirectories: csk, encryptkeypair
or signkeypair.

Steps
1. If data exists in the content store, start the IBM Cognos 8 service and export the entire content
store using the Deployment tool.
For more information, see the topic about creating an export deployment specification in the
Administration and Security Guide.

2. In IBM Cognos Configuration, from the File menu, click Export As and save the configuration
information in a decrypted format. When naming the file, use a name such as "decrypted.xml".
Export the data to a directory that is protected from unauthorized or inappropriate access
because passwords are stored in plain text. You are prompted to acknowledge that the export
is an unsecure operation.

3. Stop the IBM Cognos 8 service:

● If you use Tomcat, stop the IBM Cognos 8 service and close IBM Cognos Configuration.

● If you use an application server other than Tomcat, shut down IBM Cognos 8 in your
environment.

4. Back up any existing cryptographic keys by saving the appropriate files and directories to an
alternate location that is secure.
The files are
● c8_location/configuration/cogstartup.xml

● c8_location/configuration/caSerial

● c8_location/configuration/cogconfig.prefs

● c8_location/configuration/coglocale.xml

The directories are

● c8_location/configuration/csk

● c8_location/configuration/encryptkeypair

● c8_location/configuration/signkeypair

5. Delete the caSerial and cogconfig.prefs files and the three directories: csk, encryptkeypair, and
signkeypair.

6. Replace the c8_location/configuration/cogstartup.xml file with the file that contains the data
exported from IBM Cognos Configuration (for example, "decrypted.xml").

Important: In the c8_location/configuration directory, the file must use the name
"cogstartup.xml".

258 PowerPlay®
 Chapter 13: Configuring IBM Cognos 8 for an Application Server

The information in this file will be automatically re-encrypted using new cryptographic keys
when you save the configuration in IBM Cognos Configuration.

Set Environment Variables

You must set environment variables to identify the location of the JVM environment and the library
path. You can set environment variables using any of the following methods:
● On Windows, set a system or user variable, or edit the application server’s startup script.
If you set a user variable, ensure that you set it for the user account that will run the application
server, or administration console.

● On UNIX and Linux, set an environment variable in the user profile, or edit the application
server’s startup script.

For information about editing an application server’s startup script, see "Change the Application
Server Startup Script" (p. 262).

Tip: Most application server versions ship with a script specifically intended for setting environment
variables. For example, some WebSphere versions ship with setupCmdLine.bat or setupCmdLine.sh,
WebLogic ships with setEnv.cmd or setEnv.sh, and Oracle ships with iasenv.bat or iasenv.sh. These
scripts can be modified to set appropriate values for use with IBM Cognos components. Most of
these scripts set the JAVA_HOME environment variable by default.

Steps
1. Set the JAVA_HOME environment variable to point to the JVM used by the application server.

Tip: If the application server ships with a JVM, then the JAVA_HOME environment variable
must be set to reference it.
IBM Cognos Configuration uses this variable to create encryption keys for IBM Cognos com-
ponents that are compatible with the JVM used by the application server.
For example, for WebLogic under Windows, the JVM used by the application server is specified
as:
drive:/WebLogic_location/jdk142_04

2. Append c8_location/bin to the appropriate environment variable.

This variable is used to locate the IBM Cognos library files.

Operating system Environment variable

Windows PATH

AIX LIBPATH

Solaris and Linux LD_LIBRARY_PATH

HP-UX SHLIB_PATH

Installation and Configuration Guide 259

Chapter 13: Configuring IBM Cognos 8 for an Application Server

Tip: To install multiple instances of IBM Cognos 8 on a single server, set the PATH, LIBPATH,
LD_LIBRARY_PATH, or SHLIB_PATH variable within the application server instance scope
and not as a global variable to ensure that each instance has a unique value.

Note: The CRN_ROOT and COG_ROOT variables are no longer required in a non-clustered
environment and should be removed if they were used in a previous installation.

Update the Java Environment

IBM Cognos 8 cryptographic services use a specific .jar (Java Archive) file, named bcprov-jdknn-nnn,
that must be located in the JVM environment used by your application server. This file provides
additional encryption and decryption routines that are not supplied with a default JVM installation.
To ensure security, the encryption file must be loaded by the JVM using the Java extensions directory.

Steps
1. Ensure that the JAVA_HOME environment variable is set to the JRE location.
For example, to set JAVA_HOME to the JRE files provided with the installation, the path is
c8_location/bin/jre/version.

2. Copy the bcprov-jdknn-nnn.jar file from the c8_location/bin/jre/version/lib/ext directory to the

Java_location/jre/lib/ext directory.

Configure IBM Cognos Components to Run Within the Applic-

ation Server
IBM Cognos 8 must be configured with the application server configuration information, and the
configuration must be saved to create new cryptographic keys. IBM Cognos Configuration uses the
JVM that is defined by the JAVA_HOME environment variable.

Important: You must set the JAVA_HOME environment variable to the JVM supplied or used by
the application server and then copy the security provider files before you run IBM Cognos Config-
uration to ensure valid encryption keys are generated.

Steps
1. From the c8_location/bin directory, start IBM Cognos Configuration:

● On Windows, type cogconfig.bat in a command window or select IBM Cognos Configur-

ation from the Start menu.

● On UNIX or Linux, type cogconfig.sh

If you have existing incompatible encryption keys, you will be prompted to automatically
generate new ones at this time.

Tip: Ensure that the existing keys are backed up to a secure location before proceeding. There
is no undo action available after you generate new keys.

260 PowerPlay®
 Chapter 13: Configuring IBM Cognos 8 for an Application Server

2. Use the Build Application Wizard to create the application file that will be deployed to the
application server. To launch the Build Application Wizard from IBM Cognos Configuration
under Actions, click Build Application Files. The wizard allows you to select the type of
application to build and the context root used to access the application.
You must build the application file on the same computer on which you will be deploying the
file.
The context root value entered in the wizard must be the same as is entered in the Environment
tab, and used to deploy to the application server. For IBM Cognos 8, the default context root
and application directory name is p2pd, which can be used in most cases. For the IBM Cognos
Servlet Gateway, the default context root and application directory name is ServletGateway.
Other default application deployment values, such as the application name, may be changed
to better suit your environment.

Tip: It is not necessary to rebuild or redeploy the archive file when you make configuration
changes because configuration information is stored externally to the application.
For WebLogic and JBoss, you can use the Build Application wizard in IBM Cognos Configuration
to build the application to an expanded directory.
For example, for WebLogic, you put the application in C:\bea\user_projects\domains\apps\
p2pd, where p2pd is the name of the application. When deploying the application from the
WebLogic Administration Console, you would select the p2pd directory.

Important: For JBoss, if you use the Expand files into a folder option, you must include the
.war extension in the name of the folder where the wizard will create the p2pd application.
When the wizard prompts for the folder location, go to JBoss_loca-
tion/server/instance_name/deploy and create a folder named p2pd.war.
For information about which type of application file, WAR, EAR or expanded directory, is
supported in your environment, see your application server documentation.

3. In the Explorer window of IBM Cognos Configuration, expand Environment and then change
the following properties to use the port number and host name or IP address of the server where
the IBM Cognos 8 component and application server are installed.
● All URIs for the dispatcher, including

Dispatcher URIs for Gateway

External dispatcher URI

Internal dispatcher URI

Dispatcher URI for external applications

● Gateway URI

● Content Manager URIs

The application server must be configured to listen on the host name or IP address entered in
the URI. For more information, see your application server documentation.
If you change the context root from the default value of p2pd, you must change the context
root portion of the URI as well.

Installation and Configuration Guide 261

Chapter 13: Configuring IBM Cognos 8 for an Application Server

4. Under Environment, IBM Cognos 8 service, right-click IBM Cognos 8, and then click Delete.
The entry for the IBM Cognos 8 service is used to configure environment settings for running
under Tomcat. The entry is not required when using a different application server.

5. Complete other required configuration changes such as

● specifying properties for the Content Manager database

● entering user IDs and passwords

If you used the default settings for the IBM Cognos installation, you may only have to make
minor changes to the default configuration settings (p. 187). You can review the configuration
for single computer installations (p. 67) or for distributed installations (p. 93) to determine if
there are any additional changes required.

6. Save the configuration.

New cryptographic keys are created using the JVM that is defined by the JAVA_HOME variable.

7. Close IBM Cognos Configuration.

Identifying the JDK for WebLogic 9 on AIX

WebLogic 9 requires JDK 1.5. If you use WebLogic Server 9 on AIX, you must update the Java
options in the commEnv.sh file to specify the appropriate serial version unique identifier (UID). If
you do not make this update, a serial version UID mismatch occurs when using WebLogic Server
9 with IBM Java 5.

Steps
1. Open the WebLogic9_location/common/bin/commEnv.sh file.

2. Modify the file to include the following command:

JAVA_OPTIONS="${JAVA_OPTIONS}
-Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0"
export JAVA_OPTIONS

3. Save and close the commEnv.sh file.

Change the Application Server Startup Script

Some application servers have specific requirements that you must meet before you can run IBM
Cognos 8. Depending on the application server, you may have to define environment variables,
copy files, and add or change code in files.
If you are using BEA WebLogic Server 8.1 or Red Hat JBoss, you must make changes to the
application server startup script. The startup script must be modified to specify JVM settings. For
JBoss, you must also specify a log4j argument. For WebLogic 9, we recommend that you use the
Administration Console to modify the WebLogic environment.

262 PowerPlay®
 Chapter 13: Configuring IBM Cognos 8 for an Application Server

If you are using IBM WebSphere Application Server, SAP NetWeaver 6.40, or Oracle Application
Server, no changes to its startup script are required unless you want to add the environment variable
changes. If you do make changes, the Administrative Console can be used.
For Red Hat JBoss, we recommend that you create a copy of the default server instance so that you
can use the original default server instance as a backup. Give the copy a name that does not use
spaces, such as cognos.
If your environment contains a JRE that you are using for other products, the JRE folder may
contain .jar files that are not compatible with the .jar files that are provided with IBM Cognos 8.
This may result in a failure to start IBM Cognos 8 on your application server. In this situation, we
recommend that you direct IBM Cognos 8 to use the endorsed .jar files by including the following
parameter in the Java command line:
-Djava.endorsed.dirs=${cognos8_home}/tomcat[version]/common/endorsed

Steps for WebLogic

1. Create a WebLogic Server (WLS) domain for IBM Cognos 8.
If you are configuring the IBM Cognos Servlet Gateway, create a second domain for this
application.
For information about creating domains, see the WebLogic documentation.

2. Go to the appropriate directory and open the application server startup script in an editor. The
following are possible directories:
● WebLogic8.1_location/user_projects/domains/domain_name

● WebLogic9_location/user_projects/domains/domain_name/bin

The name of the startup script may vary depending on the type of WebLogic installation per-
formed. For example, in a managed server installation, the name of the startup script is start-
ManagedWebLogic.sh (UNIX) or startManagedWebLogic.cmd (Windows).

3. For non-IBM JRE versions, select the JVM run mode, and change the default setting from
JAVA_VM= to JAVA_VM=-server

4. Modify the JAVA_OPTIONS to set the appropriate XML parser for IBM Cognos 8. Add the
third line, as shown in this example:
JAVA_OPTIONS=
-Dweblogic.security.SSL.trustedCAKeyStore=%WL_HOME%\server\lib\cacerts-Dorg.
xml.sax.driver=org.apache.xerces.parsers.SAXParser

5. Set the minimum and maximum memory used by the JVM.

Typically, the memory is set using two JVM parameters: -Xms and -Xmx. A minimum of 256
MB and a maximum of 768 MB are suggested starting values. You can change these values to
suit your environment.
For WebLogic 9, the MaxPermSize parameter must also be set. Here is an example:
-XX:MaxPermSize=128m

For information about JVM parameters, see the JVM or application server documentation.

Installation and Configuration Guide 263

Chapter 13: Configuring IBM Cognos 8 for an Application Server

6. Ensure that the production mode is enabled.

For WebLogic 8 & 9, change PRODUCTION_MODE= to PRODUCTION_MODE=true

7. Save and close the file.

Steps for JBoss

1. Go to the JBoss_location/bin directory and open the application server startup script in an
editor. Do one of the following:
● For Windows, open run.bat

● For UNIX or Linux, open run.sh

2. Go to the JAVA_OPTS variable and increase the memory used by the JVM.
Typically, the memory is set using two JVM parameters: -Xms and -Xmx. A minimum of 256
MB and a maximum of 768 MB are suggested starting values. You can change these values to
suit your environment.
Here is an example:
rem Sun JVM memory allocation pool parameters. Modify
as appropriate.
set JAVA_OPTS=%JAVA_OPTS% -Xms192m -Xmx
768m -
Dsun.rmi.dgc.client.gcInterval=3600000 -
Dsun.rmi.dgc.client.gcInterval=3600000 -

For information about these parameters, see the JVM or application server documentation.

3. Add a log4j argument, as shown in the following example:

rem Sun JVM memory allocation pool parameters. Modify
as appropriate.
set JAVA_OPTS=%JAVA_OPTS% -Xms256m -Xmx512m -
Dsun.rmi.dgc.client.gcInterval=3600000 -
Dsun.rmi.dgc.client.gcInterval=3600000 -
DLog4j.defaultInitOverride=true

For information about these parameters, see the JVM or application server documentation.

4. Save and close the file.

Change the IBM Cognos Dispatcher Properties File for Oracle

Application Server
If you are using Oracle Application Server, you must uncomment one entry in the IBM Cognos
dispatcher properties file. You must make this change before deploying IBM Cognos components
or problems will occur when running IBM Cognos applications.

Steps
1. In a text editor, open the c8_location/webapps/WEB-INF/p2pd_deploy_defaults.properties file.

2. Locate the following entries:

264 PowerPlay®
 Chapter 13: Configuring IBM Cognos 8 for an Application Server

#set this to true to wrap the input stream so

that Oracle Application Server will parse the XML properly
#wrap_input_stream=true

3. Uncomment the second entry by deleting the pound symbol (#), as shown here:
wrap_input_stream=true

4. Save and close the file.

Configure Application Server Properties and Deploy IBM Cognos

Components
You must configure application server properties and deploy the IBM Cognos components.

Steps for WebSphere

1. Start the WebSphere Application Server, and then access the WebSphere Administrative Console.

2. Create a new server instance into which the IBM Cognos 8 application will be deployed, if this
option is available in the version you are running.
If you are deploying the IBM Cognos Servlet Gateway, create a second separate server instance.

3. Install a new Enterprise Application using the application file that was built by IBM Cognos
Configuration.
For IBM Cognos 8, the default context root is p2pd, which can be used in most cases. For the
IBM Cognos Servlet Gateway, the default context root is ServletGateway. Other default
application deployment values, such as the application name, may be changed to better suit
your environment. The context root value used to deploy the application must be the same as
the context root value entered in IBM Cognos Configuration when running the Build Application
wizard.

4. Set the memory used by the JVM.

Usually, the memory is set by adding or changing the initial and maximum Java heap size. For
information about these parameters, see the JVM or application server documentation.

Tip: A minimum of 256 MB and a maximum of 768 MB are suggested starting values. You
can change these values to suit your environment.

5. In the server properties, add an environment variable, as listed in the following table, that ref-
erences the installation_location/bin directory.

Operating system Environment variable

Windows PATH

AIX LIBPATH

Solaris LD_LIBRARY_PATH

Installation and Configuration Guide 265

Chapter 13: Configuring IBM Cognos 8 for an Application Server

Operating system Environment variable

HP-UX SHLIB_PATH

6. Stop and then restart the WebSphere application server instance used for IBM Cognos compon-
ents.

7. Verify that IBM Cognos components are running by looking for the following message in the
application server admin console or in the application server log file:
The dispatcher is ready to process requests.

Steps for WebLogic

1. If you used the expanded directory option when building the application in IBM Cognos Con-
figuration, go to step 2. If you created a WAR file, expand the application manually:
● Create a directory in a location that is accessible to the application server, giving the direct-
ory the same name as the context root.
For IBM Cognos 8, the default context root and application directory name is p2pd, which
can be used in most cases. For the IBM Cognos Servlet Gateway, the default context root
is ServletGateway. Other default application deployment values, such as the application
name, may be changed to better suit your environment. The context root value used to
deploy the application must be the same as the context root value entered in IBM Cognos
Configuration.

● From the directory you just created, extract the application WAR file to the WebLogic
installation using the following command from a command prompt:

WebLogic_location/jdk_version/bin/jar xvfm "installation_location/application.war" .

Important: A space and then a period are required at the end of the command. In this
command, the period does not refer to the current directory.

2. Start the WebLogic Administration Server and the WebLogic Managed Server associated with
the IBM Cognos domain.
Node Manager must be started before you can start and stop Managed Server instances using
the Administration Console.

3. For WebLogic 9, you must modify the environment in the WebLogic Administration Console
before deploying IBM Cognos 8. Logon to the Administration Console and navigate to the
Managed Server instance that will host the IBM Cognos 8 application. Select the Server Start
tab for the Managed Server instance and enable edit mode.

4. In the Java Home box, enter the path for the JVM. This value must be the same as is used for
IBM Cognos 8. You must use the JVM that is included with the WebLogic installation.

5. Set the Java arguments.

266 PowerPlay®
 Chapter 13: Configuring IBM Cognos 8 for an Application Server

The Java arguments include all JVM settings, such as memory settings specified using two JVM
parameters: -Xms and -Xmx. For WebLogic 9, the MaxPermSize must also be set. You must
also set the appropriate XML parser for IBM Cognos 8.

For example, in the Arguments box, type

-Xms768m -Xmx768m -XX:MaxPermSize=128m -Dorg.xml.sax.driver=org.apache.xerces.

parsers.SAXParser
If you use WebLogic Server 9 on AIX, you must also specify the appropriate serial version UID
in the Java arguments. If you do not make this update, a serial version UID mismatch occurs
when using WebLogic Server 9 with IBM Java 5 because WebLogic 9 requires JDK 1.5.

For example, in the Arguments box, type

-Xms768m -Xmx768m -XX:MaxPermSize=128m -Dorg.xml.sax.driver=org.apache.xerces.

parsers.SAXParser -Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0
For information about JVM parameters, see the JVM or application server documentation.

6. Save and apply the changes.

You can now start and stop the Managed Server instance from the Control tab.

7. Start the server instance. The server instance must be started before deploying IBM Cognos 8
or IBM Cognos Servlet Gateway.

8. Deploy the IBM Cognos 8 or IBM Cognos Servlet Gateway application in the WebLogic console
using a new Web application as follows:
● Set the application name.
For example, cognos8

● Set the path to the directory where the expanded application files are located.

Note: IBM Cognos 8 uses a custom loader. You must use the expanded directory option
when deploying.

● Select the target server instance.

It is recommended that the Administration Server be used only for WebLogic administration
tasks and that the IBM Cognos 8 application be deployed to its own Managed Server
instance.

9. After the deployment has completed successfully, set the reload period for the Web application
to -1 to improve performance. This will prevent WebLogic from checking for updated application
files that are used only in a development environment.

10. Stop and then restart the WebLogic Managed Server associated with the IBM Cognos domain
to activate the changes.

11. Verify that IBM Cognos components are running by looking for the following message in the
application server console window or in the application server log file:

Installation and Configuration Guide 267

Chapter 13: Configuring IBM Cognos 8 for an Application Server

The dispatcher is ready to process requests.

Steps for SAP NetWeaver 6.40 on Windows

1. Open the configuration tool by typing

drive:\usr\sap\sapid\JCxx\j2ee\configtool\configtool.bat
For example, if the SAP ID is J2E and the installation is on drive D, you would type

D:\usr\sap\J2E\JC00\j2ee\configtool\configtool.bat

2. When prompted to use the default DB settings, click Yes.

3. Under cluster-data, instance_IDxxxxxxx, Dispatcher_IDxxxxxxx, services, where xxxxxxx is

the ID number for your installation, highlight http.

4. Under Global Properties, highlight KeepAliveTimeout and type a higher number and then click
Set.

Tip: We suggest an initial KeepAliveTimeout number of at least 60.

5. Under cluster-data, instance_IDxxxxxxx, highlight Server_IDxxxxxxx.

6. Set the memory used by the JVM.

Follow the recommendations from SAP. For more information, see SAP Note 723909 in the
SAP Support Portal.
If your computer has less than 1.5 GB of memory, you may have issues when you run SAP
NetWeaver. We suggest a minimum value of 768 MB.

7. In the Java parameters box, set the XML parser as follows:

-Dorg.xml.sax.driver=org.apache.xerces.parsers.SAXParser

8. For IBM Cognos 8 environments that use Report Studio, under cluster-data,
instance_IDxxxxxxx, highlight Server_IDxxxxxxx, services, and highlight http.

9. Under Global Properties, highlight CompressedOthers, type false, and then click Set.

10. Save the changes.

You are prompted to restart the server.

11. Restart the server by using the SAP Management Console or by restarting the services in Services.

12. Use the Deploy tool to create a new project.

13. Load the IBM Cognos application file you created using IBM Cognos Configuration. By default,
the file is named p2pd.ear for IBM Cognos 8 and ServletGateway.ear for IBM Cognos Servlet
Gateway.

14. Using the Deploy tool, connect to the Administration tool and deploy the application file.

15. When you are prompted to start the application, click Yes.

268 PowerPlay®
 Chapter 13: Configuring IBM Cognos 8 for an Application Server

16. Save the project.

Steps for Oracle Application Server Release 2

1. Create an OC4J instance for IBM Cognos components to run within.

2. Set the memory used by the JVM.

Typically, the memory is set by adding or changing two JVM parameters: -Xms and -Xmx. A
minimum of 256 MB and a maximum of 768 MB are suggested starting values. You can change
these values to suit your environment. For information about these parameters, see the JVM
or application server documentation.

3. In the server properties, add "-userThreads" to the OC4J Options.

4. In the server properties, add an environment variable, as listed in the following table, that ref-
erences the installation_location/bin directory.

Operating system Environment variable

Windows PATH

AIX LIBPATH

Solaris LD_LIBRARY_PATH

HP-UX SHLIB_PATH

5. Deploy the IBM Cognos application file (named p2pd.ear for IBM Cognos 8 or ServletGate-
way.ear for IBM Cognos Servlet Gateway, by default) created by IBM Cognos Configuration.
The value of the Map to URL parameter must be the same as the context root value entered in
IBM Cognos Configuration.

6. Start the OC4J instance that you created for IBM Cognos components.

7. Verify that IBM Cognos components are running by looking for the following message in the
application server console window or in the application server log file:
The dispatcher is ready to process requests.

Steps for Oracle Application Server Release 3

1. Create an OC4J instance for IBM Cognos components to run within.

2. On Windows only, comment out the following entries in the Oracle_location\j2ee\Cognos_

OC4J_instance\config\global-web-application.xml file:
<welcome-file-list>
<welcome-file>index.html</welcome-file>
<welcome-file>default.jsp</welcome-file>
<welcome-file>index.htm</welcome-file>
<welcome-file>index.jsp</welcome-file>
</welcome-file-list>

Installation and Configuration Guide 269

Chapter 13: Configuring IBM Cognos 8 for an Application Server

3. Open the Oracle_location/opmn/conf/opmn.xml file.

4. Add an environment variable that references the installation_location/bin directory and set
variables for data sources.
Here is an example for Windows and DB2:
<environment>
<variable id="PATH" value="c8_location/bin"
append="true"/>
<variable id="DB2DIR" value="
location"/>
<variable id="DB2INSTANCE value="
instance_name"/>
<variable id="INSTHOME value="
location"/>
</environment>

This table lists the environment variables for each operating system that must reference the
c8_location/bin directory.

Operating system Environment variable

Windows PATH

AIX LIBPATH

Solaris LD_LIBRARY_PATH

HP-UX SHLIB_PATH

5. Set the memory used by the JVM.

A minimum of 256 MB and a maximum of 768 MB are suggested starting values. You can
change these values to suit your environment. For information about these parameters, see the
JVM or application server documentation.
Here is an example:
<data id="java-options" value="-server -Xmx768m
-XX:MaxNewSize=384m -XX:NewSize=192m -XX:MaxPermSize=128m -classpath
c8_location\bin;c8_location\webapps\p2pd\WEB-INF\lib
-

6. Define the OC4J userThreads setting.

Here is an example:
<data id="oc4j-options" value="-properties
-userThreads"/>

7. Save and close the Oracle_location/opmn/conf/opmn.xml file.

8. Deploy the IBM Cognos application file (named p2pd.ear for IBM Cognos 8 or ServletGate-
way.ear for IBM Cognos Servlet Gateway, by default) created by IBM Cognos Configuration.
The value of the Map to URL parameter must be the same as the context root value entered in
IBM Cognos Configuration.

270 PowerPlay®
 Chapter 13: Configuring IBM Cognos 8 for an Application Server

9. Start the OC4J instance that you created for IBM Cognos components.

10. Verify that IBM Cognos components are running by looking for the following message in the
application server console window or in the application server log file:
The dispatcher is ready to process requests.

Steps for JBoss

1. If you do not want to use the default port of 8080, open the JBoss_location/server/instance_name/
deploy/jbossweb-tomcat55.sar/server.xml file.

2. In the server.xml file, change the default port number of 8080 used by the server instance to
the port specified in IBM Cognos Configuration. For example,
<Service name="jboss.web"
className="org.jboss.web.tomcat.tc5.StandardService">
<!-- A HTTP/1.1 Connector on port 8080 -->
<Connector port="8080" address="${jboss.bind.address}"
maxThreads="250" strategy="ms" maxHttpHeaderSize="8192"
emptySessionPath="true"
enableLookups="false" redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"/>

3. Save and close the server.xml file.

4. Put the p2pd application in the JBoss_location/server/instance_name/deploy folder, if it is not

already in this location.

5. Start the application server.

The p2pd application is automatically detected and started by the application server.

6. Verify that IBM Cognos components are running by looking for the following message in the
application server console window or in the application server log file:
The dispatcher is ready to process requests.

Steps for Sun Java System Application Server

1. Use the Sun Java System Application Server Admin Console to add a new JVM Option to set
the XML Parser that will be used by the IBM Cognos Application. For example:
"-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.
DocumentBuilderFactoryImpl"

2. Add a JVM Option to set the Maximum Java Heap Size to limit the maximum amount of
memory that can be used by the Java process.
Usually, the memory is set by adding or changing the initial and maximum Java heap size. For
information about these parameters, see the JVM or application server documentation.
For example, add "-Xmx768M" to set 768M of memory as a maximum value for the Java process.

Tip: A minimum of 256 MB and a maximum of 768 MB are suggested starting values. You
can change these values to suit your environment.

3. Increase the "Maximum number of request processing threads" from the default of 5 to a value
appropriate for your environment.

Installation and Configuration Guide 271

Chapter 13: Configuring IBM Cognos 8 for an Application Server

Tip: Start with a value of 250. If the value is too low, system instability and failed processes
occur. If the value is too high, system resources are reserved unnecessarily.

4. Copy the c8_location \webapps\p2pd\WEB-INF\lib\xercesImpl.jar file to SJSAS_loca-

tion\domains\<domain name>\lib\ext.

Enable SSL
If you use the Secure Socket Layer (SSL) for IBM Cognos components, you must also enable SSL
in the application server environment. You then identify the SSL server certificate to IBM Cognos
components.

Steps
1. Configure the application server to use SSL.
An SSL server certificate is generated by a third-party Certificate Authority (CA). The certificate
of the CA that generated the SSL server certificate is also provided.
For more information about configuring the application server to use SSL, refer to the application
server documentation. For information about using CA certificates with your application server,
see the CA documentation.

2. Copy the CA certificate to the installation_location/bin directory and rename the file to ca.cer.
This file must be Base-64 encoded X.509 format.

3. From the installation_location/bin directory:

● On Windows, type:

ThirdPartyCertificateTool.bat -T -i -r ca.cer -k ../configuration/signkeypair/jCAKeystore

-p password

● On UNIX or Linux, type:

ThirdPartyCertificateTool.sh -T -i -r ca.cer -k ../configuration/signkeypair/jCAKeystore

-p password

Important: You must type jCAKeystore as the name of the CA key store.

Configuring the Web Server

If you are using a Web server in your environment, configure it now. For information, see "Configure
the Web Server" (p. 121).
For information about configuring the WebSphere Web server plugin, visit the IBM Cognos Resource
Center (http://www.ibm.com/software/data/support/cognos_crc.html).

272 PowerPlay®
 Chapter 13: Configuring IBM Cognos 8 for an Application Server

Unregister Dispatchers
After you start the application server and the IBM Cognos application, unregister any IBM Cognos
dispatchers that were previously registered and that are no longer used. For example, unregister
any Tomcat dispatchers that are now running under the application server.
You remove dispatchers using IBM Cognos Administration. To access this tool, you must have
execute permissions for the Administration secured function.

Steps
1. Open IBM Cognos Connection by connecting to the IBM Cognos 8 portal and clicking IBM
Cognos Content on the Welcome page.

2. In the upper-right corner, click Launch, IBM Cognos Administration.

3. On the Configuration tab, click Dispatchers and Services.

4. For the dispatcher you want to unregister, from the Actions column, click More.

5. Click Unregister.

6. In the confirmation dialog, click OK.

The dispatcher information is removed from Content Manager.

Import Content Store Data

If you exported the content store before setting up IBM Cognos components to run in your
application server (p. 257), import the deployment to restore and encrypt the data using the new
encryption keys.

Step
1. Start IBM Cognos 8.

2. Import the entire content store using the Deployment tool.

For more information, see the topic about importing to a target environment in the Adminis-
tration and Security Guide.

Installation and Configuration Guide 273

Chapter 13: Configuring IBM Cognos 8 for an Application Server

274 PowerPlay®
Chapter 14: Advanced Configuration Options

Advanced configuration options are changes that you make after installation to the configuration
properties of the resources that IBM Cognos 8 components use. You cannot use IBM Cognos
Configuration to make these changes. Advanced configuration options enhance security, improve
performance, or change the default behavior of IBM Cognos 8 components.

Changing the Version of Java Runtime Environment Used by

IBM Cognos 8 Components
IBM Cognos 8 components require Java Runtime Environment (JRE) to operate. The current version
provided with IBM Cognos 8 is JRE 1.5.0. For more information about the supported JRE versions,
see the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html).
IBM Cognos Configuration and other IBM Cognos 8 components use the JRE referenced by the
JAVA_HOME environment variable. On Windows, if JAVA_HOME is not set, the JRE that is
packaged with IBM Cognos 8 components is used by default.
If you want to change your current JRE, some configuration changes are required. Changing may
be appropriate in the following situations:
● You want to use IBM Cognos 8 components with an application server that requires a specific
JRE version.

● You already use a JRE version with other applications.

If you are using IBM Cognos 8 components in an application server environment, follow the process
in "Configuring IBM Cognos 8 for an Application Server" (p. 255). The process includes steps for
updating the Java environment.
Before you begin, ensure that IBM Cognos 8 components are installed and that JRE you want to
use is installed.
To change JRE versions, do the following:
❑ Back up existing IBM Cognos data and encryption keys, if required.

❑ Updated the Java environment.

❑ Import data to the content store, if required.

The tasks in this section are for an IBM Cognos installation that uses Tomcat.

Back Up Existing IBM Cognos Information

You must back up existing IBM Cognos information if IBM Cognos 8 components are running
● on an application server (including Tomcat) and you are changing to an application server that
ships with its own JVM.

Installation and Configuration Guide 275

Chapter 14: Advanced Configuration Options

● with a JVM from one vendor and you are changing to another JVM vendor.

Note: You must back up existing IBM Cognos information within the working environment prior
to upgrade.
Before configuring IBM Cognos 8 components to run on the new application server or JVM, you
must back up
● content store data by creating a deployment export.

● configuration information by exporting it. Any encrypted data is decrypted during the export.

● cryptographic keys by saving them to an alternate location. New cryptographic keys must be
created using the same JVM that the application server uses. Because these keys can be created
only if the previous keys are deleted, it is important to back up the previous keys.

To ensure the security and integrity of your IBM Cognos data, back up the content store, configur-
ation information, and cryptographic keys to a directory that is protected from unauthorized or
inappropriate access.

Tip: To check if any cryptographic keys exist, look in the c8_location/configuration directory.
Cryptographic keys exist if this directory includes the following subdirectories: csk, encryptkeypair
or signkeypair.

Steps
1. If data exists in the content store, start the IBM Cognos 8 service and export the entire content
store using the Deployment tool.
For more information, see the topic about creating an export deployment specification in the
Administration and Security Guide.

2. In IBM Cognos Configuration, from the File menu, click Export As and save the configuration
information in a decrypted format. When naming the file, use a name such as "decrypted.xml".
Export the data to a directory that is protected from unauthorized or inappropriate access
because passwords are stored in plain text. You are prompted to acknowledge that the export
is an unsecure operation.

3. Stop the IBM Cognos 8 service:

● If you use Tomcat, stop the IBM Cognos 8 service and close IBM Cognos Configuration.

● If you use an application server other than Tomcat, shut down IBM Cognos 8 in your
environment.

4. Back up any existing cryptographic keys by saving the appropriate files and directories to an
alternate location that is secure.
The files are
● c8_location/configuration/cogstartup.xml

● c8_location/configuration/caSerial

● c8_location/configuration/cogconfig.prefs

276 PowerPlay®
 Chapter 14: Advanced Configuration Options

● c8_location/configuration/coglocale.xml

The directories are

● c8_location/configuration/csk

● c8_location/configuration/encryptkeypair

● c8_location/configuration/signkeypair

5. Delete the caSerial and cogconfig.prefs files and the three directories: csk, encryptkeypair, and
signkeypair.

6. Replace the c8_location/configuration/cogstartup.xml file with the file that contains the data
exported from IBM Cognos Configuration (for example, "decrypted.xml").

Important: In the c8_location/configuration directory, the file must use the name
"cogstartup.xml".
The information in this file will be automatically re-encrypted using new cryptographic keys
when you save the configuration in IBM Cognos Configuration.

Update the Java Environment

The IBM Cognos security provider files must be located in the JVM environment for the new version
of Java.
IBM Cognos 8 cryptographic services use a .jar (Java Archive) file, named bcprov-jdknn-nnn.jar,
that must be located in your Java Runtime Environment (JRE). This file provides additional
encryption and decryption routines that are not supplied as part of a default JVM installation. To
ensure security, the encryption file must be loaded by the JVM using the java extensions directory.
If you want to use your own JRE and have JAVA_HOME set to that location on Windows or if
you are installing on UNIX, you may have to update the Java environment for the cryptographic
services.
On Windows, you can set JAVA_HOME as a system variable or a user variable. If you set it as a
system variable, it may be necessary to restart your computer for it to take effect. If you set it as a
user variable, set it so that the environment in which Tomcat is running can access it.
If you do not have a JAVA_HOME variable already set on Windows or if JAVA_HOME points to
a Java version that is not valid for IBM Cognos 8, the JRE files provided with the installation will
be used, and you do not have to update any files in your environment.

Steps
1. Ensure that the JAVA_HOME environment variable is set to the JRE location.
For example, to set JAVA_HOME to the JRE files provided with the installation, the path is
c8_location/bin/jre/version.

2. Copy the bcprov-jdknn-nnn.jar file from the c8_location/bin/jre/version/lib/ext directory to the

Java_location/lib/ext directory.

3. Start IBM Cognos Configuration.

Installation and Configuration Guide 277

Chapter 14: Advanced Configuration Options

4. Save the configuration.

IBM Cognos Configuration generates new keys and encrypts the data.

Import Content Store Data

If you exported the content store before changing the JVM, import the deployment to restore and
encrypt the data using the new encryption keys.

Step
● To import the content store data, start the IBM Cognos 8 service and import the entire content
store using the Deployment tool. For more information, see the topic about importing to a
target environment in the Administration and Security Guide.

Configuring IBM Cognos 8 Components to Use Another Certi-

ficate Authority
By default, IBM Cognos 8 components use their own certificate authority (CA) service to establish
the root of trust in the IBM Cognos security infrastructure. You can configure IBM Cognos 8
components to use another certificate authority, if you already have an existing certificate authority,
such as iPlanet or Microsoft, in your reporting environment.
When you configure IBM Cognos 8 components to use another certificate authority, ensure that
you specify the same information in both the command line utility tool and in IBM Cognos Config-
uration.
To configure IBM Cognos 8 components to use another certificate authority, you must
❑ generate IBM Cognos security keys and certificate signing requests to use with your certificate
authority

❑ submit the IBM Cognos security keys and certificates to your certificate authority

❑ configure IBM Cognos 8 components to use your certificate authority

Generate Keys and Certificate Signing Requests

Use the command line utility to generate all the keys for the IBM Cognos key stores and to generate
the certificate signing requests (CSR).
The following table lists the options for the command-line tool used to generate keys and signing
requests.

Command Description

Main operation mode

-c Create a new CSR

278 PowerPlay®
 Chapter 14: Advanced Configuration Options

Command Description

-i Import a certificate

Operation modifiers

-s Work with the signing identity

-e Work with the encryption identity

-T Work with the trust store (only with -i)

Information Flags

-d DN to use for certificate

-r CSR or certificate file location (depends on mode)

-t certificate authority certificate file (only with -i)

-p Key Store password (must be provided)

-a Key pair algorithm. RSA or DSA.

Default: RSA

-D Directory location

The following sample values are used:

Property Value

Signing certificate DN CN=SignCert,O=MyCompany,C=CA

Encryption certificate DN CN=EncryptCert,O=MyCompany,C=CA

Key store password password

Steps
1. In the c8_location\configuration directory, back up the cogstartup.xml file to a secure location.

2. Back up the contents of the following directories to a secure location:

● c8_location\configuration\signkeypair

● c8_location\configuration\encryptkeypair

3. Using IBM Cognos Configuration, export the configuration in clear text by doing the following:

Installation and Configuration Guide 279

Chapter 14: Advanced Configuration Options

● Open IBM Cognos Configuration.

● From the File menu, click Export As.

● When prompted about exporting decrypted content, click Yes.

● In the Export As dialog box, select cogstartup.xml and then click Save.

● When prompted about replacing the existing file, click Yes.

● When the tasks are complete, close the IBM Cognos Configuration dialog box.

● Save the configuration.

● Close IBM Cognos Configuration.

4. Go to the c8_location\bin directory.

5. Create the certificate signing request for the signing keys by typing the following command:
On UNIX or Linux, type

ThirdPartyCertificateTool.sh -c -s -d "CN=SignCert,O=MyCompany,C=CA" -r signRequest.csr

-D ../configuration/signkeypair -p password
On Windows, type

ThirdPartyCertificateTool.bat c -s -d "CN=SignCert,O=MyCompany,C=CA" -r signRequest.csr

-D ../configuration/signkeypair -p password

Tip: UNIX or Linux filenames are case-sensitive and must be entered exactly as shown.
You can safely ignore any warnings about logging.
The command creates the jSignKeystore file in the signkeypair directory, sets the specified
password, creates a new keypair and stores it in the keystore, and exports the signRequest.csr
file to the c8_location\bin directory.

6. Create the certificate signing request for the encryption keys by typing the following command:
On UNIX or Linux, type

ThirdPartyCertificateTool.sh -c -e -d "CN=EncryptCert,O=MyCompany,C=CA" -r
encryptRequest.csr -D ../configuration/encryptkeypair -p password
On Windows, type

ThirdPartyCertificateTool.bat -c -e -d "CN=EncryptCert,O=MyCompany,C=CA" -r
encryptRequest.csr -D ../configuration/encryptkeypair -p password
You can safely ignore any warnings about logging.
The command creates the jEncKeystore file in the encryptkeypair directory, sets the specified
password, creates a new keypair and stores it in the keystore, and exports the encryptRequest.csr
file to the c8_location\bin directory.

7. Copy the signRequest.csr and encryptRequest.csr files that were generated in steps 5 and 6 to
a directory that is accessible by your third-party certificate authority.

280 PowerPlay®
 Chapter 14: Advanced Configuration Options

8. Input the signRequest.csr and encryptRequest.csr files into your certificate authority.
The certificate authority produces a signing certificate and an encryption certificate.
For more information, see the documentation for your certificate authority.

9. Copy the contents of the signing certificate into a file named signCertificate.cer.

10. Copy the contents of the encryption certificate into a file named encryptCertificate.cer

11. Find the root CA certificate for the certificate authority and copy the contents into a file named
ca.cer.

12. Copy ca.cer, signCertificate.cer, and encryptCertificate.cer to c8_location/bin.

These files must be PEM (Base-64 encoded ASCII) format.

13. Import the signing certificate from step 10 into the IBM Cognos signing key store by typing
the following command:
On UNIX or Linux, type

ThirdPartyCertificateTool.sh -i -s -r signCertificate.cer -D ../configuration/signkeypair -p

password -t ca.cer
On Windows, type

ThirdPartyCertificateTool.bat-i -s -r signCertificate.cer -D ../configuration/signkeypair -p

password -t ca.cer
You can safely ignore any warnings about logging.
The command reads the signCertificate.cer and ca.cer files in the c8_location\bin directory and
imports the certificates from both files into the jSignKeystore file in the signkeypair directory
using the specified password.

14. Import the encryption certificate from step 11 into the IBM Cognos encryption key store by
typing the following command:
On UNIX or Linux, type

ThirdPartyCertificateTool.sh -i -e -r encryptCertificate.cer -D ../configuration/encryptkeypair

-p password -t ca.cer
On Windows, type

ThirdPartyCertificateTool.bat -i -e -r encryptCertificate.cer -D ../configuration/encryptkeypair

-p password -t cacert.cer
You can safely ignore any warnings about logging.
The command reads the encryptCertificate.cer and ca.cer files in the c8_location\bin directory
and imports the certificates from both files into the jEncKeystore file in the encryptkeypair
directory using the specified password.

15. Import the CA certificate from step 12 into the IBM Cognos trust store by typing the following
command:
On UNIX or Linux, type

Installation and Configuration Guide 281

Chapter 14: Advanced Configuration Options

ThirdPartyCertificateTool.sh -i -T -r ca.cer -D ../configuration/signkeypair -p password

On Windows, type

ThirdPartyCertificateTool.bat -i -T -r ca.cer -D ../configuration/signkeypair -p password

The command reads the ca.cer file and imports the contents into the jCAKeystore file in the
signkeypair directory using the specified password.

The certificates are now ready to be configured for IBM Cognos 8.

Configure IBM Cognos 8 Components to Run Within Another Certificate

Authority
You must configure each IBM Cognos computer to use an external certificate authority by setting
the appropriate property in IBM Cognos Configuration.
By setting this property, IBM Cognos 8 components assume that all required keys have been gener-
ated and vetted by the external certificate authority.
Ensure that the key store locations and password in IBM Cognos Configuration match the ones
you typed in the command-line tool.

Steps
1. Start IBM Cognos Configuration.

2. In the Explorer window, under Security, Cryptography, click Cognos.

3. In the Properties window, under Certificate Authority settings property group, click the Value
box next to the Use third party CA property and then click True.

Note: When you set this property to true, all properties for the certificate authority and identity
name are ignored.

4. Configure the following properties to match the ones you typed in the command line utility:

● Signing key store location

● Signing key store password

● Encryption key store location

● Encryption key store password

● Certificate Authority key store password

5. From the File menu, click Save.

6. If you want to start the IBM Cognos 8 service, from the Actions menu, click Start.
This action starts all installed services that are not running. If you want to start a particular
service, select the service node in the Explorer window and then click Start from the Actions
menu.

282 PowerPlay®
Chapter 15: Setting Up an Unattended Installation
and Configuration

Set up an unattended installation and configuration to

● install an identical configuration across several computers on your network

● automate the installation and configuration process by specifying options and settings for users

Before you set up an unattended installation and configuration, ensure that all the system require-
ments and prerequisites are met and that all required products are installed and configured.
To set up an unattended installation and configuration:
❑ configure a transfer specification file (.ats) to specify installation options

❑ run the installation tool in silent mode

❑ use a pre configured configuration file from another computer

❑ run the configuration tool in silent mode

After you complete these tasks, ensure that the IBM Cognos 8 installation directory on all computers
is protected from unauthorized or inappropriate access. Then you will be ready to use IBM Cognos 8.

Set Up an Unattended Installation

Use a transfer specification file (.ats) to copy IBM Cognos 8 components, including Framework
Manager or Metric Designer, to your computer without being prompted for information.
By default, each time you install IBM Cognos 8 components using the installation wizard, the
options you select are recorded in a transfer specification file. Therefore, if you already installed
IBM Cognos 8 components on a sample computer, you can use the generated transfer specification
file as a template for unattended installations on different computers.
If you do not use the installation wizard to install components, you can use the default transfer
specification file named response.ats that is available on the CD. You must modify the response.ats
file for your environment before you can use it for an unattended installation.
You can check if the unattended installation was successful by checking the return status. A value
of zero (0) indicates success and all other values indicate that an error occurred.

Steps Using a File Generated by an Installation on Another Computer

1. Use the installation wizard to install IBM Cognos 8 components on your computer.

2. Go to c8_location/instlog.

3. Locate the transfer specification file (.ats) that was generated:

Installation and Configuration Guide 283

Chapter 15: Setting Up an Unattended Installation and Configuration

● If you installed PowerPlay BI server, the file name is ts-C8PPES-version-yyyym-

mdd_hhmm.ats.

● If you installed PowerPlay Client, the file name is ts-C8PPCLIENT-version-yyyym-

mdd_hhmm.ats.

● If you installed the IBM Cognos 8 samples, the file name is ts-C8BISAMPLES-version-yyyym-
mdd_hhmm.ats.

4. Copy the transfer specification file to the computer where you plan to install IBM Cognos 8
PowerPlay.

5. On the computer where you plan to install the software, insert the appropriate CD and copy
the contents of the CD to your computer.

6. Open the transfer specification file that you copied in a text editor.

7. In the section named License Agreement, change the ACCEPTED= property to y.

8. Save the transfer specification file in the directory where you copied the contents of the
installation CD.

9. Install IBM Cognos 8:

● On Windows, open a Command Prompt window, and change to the win32 directory where
you copied the contents of the CD, and then type the following command, where location
is the directory where you copied filename, the transfer specification file:

issetup -s location/filename.ats

● On UNIX or Linux, change to the directory where you copied the contents of the CD, and
in the directory for your operating system, type the following command, where location is
where you copied filename, the transfer specification file:

issetup -s location/filename.ats

If a return status other than zero (0) is returned, check the log files for error messages. Errors are
recorded in the installation directory in the following log file:
● For PowerPlay BI server, the file name is tl-C8PPES-version-yyyymmdd_hhmm_summary-
error.txt.

● For PowerPlay Client, the file name is tl-C8PPCLIENT-version-yyyymmdd_hhmm_summary-

error.txt.

● For the IBM Cognos 8 samples, the file name is tl-C8BISAMPLES-version-yyyym-

mdd_hhmm_summary-error.txt.

If errors occur before sufficient initialization occurs, log messages are sent to one of the following
log files in the Temp directory:
● For PowerPlay BI Server, the file name is tl-C8PPES-version-yyyymmdd-hhmm.txt.

● For PowerPlay Client, the file name is tl-C8PPCLIENT-version-yyyymmdd-hhmm.txt.

284 PowerPlay®
 Chapter 15: Setting Up an Unattended Installation and Configuration

● For the IBM Cognos 8 samples, the file name is tl-C8BISAMPLES-version-yyyymmdd-hhmm.txt.

Also ensure that the installation directory is protected from unauthorized or inappropriate access.
After all errors are resolved, you can set up an unattended configuration.

Steps Using the Response.ats File

1. On the target computer, insert the CD and copy the contents to your computer.

2. Go to the win32 directory and open the response.ats file in a text editor.
Each section in the response.ats file corresponds to a dialog box in the installation wizard.

3. In the section named License Agreement, change the ACCEPTED= property to y.

4. Type the installation location of the program files for IBM Cognos 8 in APPDIR=location.
There should be no space on either side of the equal sign, (=).

5. For the server components of IBM Cognos 8 PowerPlay, in the section named [Component
List], next to each component:

● To install the component, type 1

● To not install the component, type 0

6. For a Windows installation, for the APPFOLDER= property, type the name of the Start menu
folder that contains your program shortcuts.

To ensure that the shortcut folder is visible to all users, type 1 for the ALLUSERS_FLAG=
property.

7. For the install information in the [Install Conditions] section:

● To specify the condition is true, type 1

● To specify the condition is false, type 0

8. Save the response.ats file to a local directory after you make the necessary changes.

9. Go to the win32 directory.

10. At the command prompt, type the following command, where location is the directory where
you copied response.ats:
● On Windows,

issetup -s location/response.ats

● On UNIX or Linux,

./issetup -s location/response.ats

If a return status other than zero (0) is returned, check the log files for error messages. Errors are
recorded in the installation directory in the following log file:
● For PowerPlay BI server, the file name is tl-C8PPES-version-yyyymmdd_hhmm_summary-
error.txt.

Installation and Configuration Guide 285

Chapter 15: Setting Up an Unattended Installation and Configuration

● For PowerPlay Client, the file name is tl-C8PPCLIENT-version-yyyymmdd_hhmm_summary-

error.txt.

● For the IBM Cognos 8 samples, the file name is tl-C8BISAMPLES-version-yyyym-

mdd_hhmm_summary-error.txt.

If errors occur before sufficient initialization occurs, log messages are sent to one of the following
log files in the Temp directory:
● For PowerPlay BI Server, the file name is tl-C8PPES-version-yyyymmdd-hhmm.txt.

● For PowerPlay Client, the file name is tl-C8PPCLIENT-version-yyyymmdd-hhmm.txt.

● For the IBM Cognos 8 samples, the file name is tl-C8BISAMPLES-version-yyyymmdd-hhmm.txt.

Also ensure that the installation directory is protected from unauthorized or inappropriate access.
After all errors are resolved, you can set up an unattended configuration.

Set Up an Unattended Configuration

Before you set up an unattended configuration, you must export a configuration from another
computer that has the same IBM Cognos 8 components installed. You can then run IBM Cognos
Configuration in silent mode.
The exported configuration contains the properties of the IBM Cognos 8 components that you
installed on the source computer. If you made changes to the global configuration, you must also
copy the global configuration file from the source computer to the computer where you plan to run
an unattended configuration. Global configuration includes such settings as content locale, product
locale, currencies, fonts, and cookie settings. For more information, see "Changing Global Set-
tings" (p. 225).
Ensure that the configuration settings on the local computer are appropriate to use to configure
another IBM Cognos 8 computer with the same installed components. For example, if you changed
the host name portion of the Gateway URI property from local host to an IP address or computer
name, ensure this setting is appropriate for the new computer’s configuration.
You can check if the unattended configuration was successful by checking the return status. A value
of zero (0) indicates success and all other values indicate that an error occurred.

Steps
1. In IBM Cognos Configuration, from the File menu, click Export as.

2. If you want to export the current configuration to a different folder, in the Look in box, locate
and open the folder.
Ensure that the folder is protected from unauthorized or inappropriate access.

3. In the File name box, type a name for the configuration file.

4. Click Save.

286 PowerPlay®
 Chapter 15: Setting Up an Unattended Installation and Configuration

5. Copy the exported configuration file from the source computer or network location to the
c8_location/configuration directory on the computer where you plan to do an unattended
configuration.

6. Rename the file to cogstartup.xml.

7. If you changed the global configuration on the source computer, copy the coglocale.xml file
from the source computer to the c8_location/configuration directory on the computer where
you plan to do an unattended configuration.

8. Go to c8_location/bin.

9. Type the configuration command:

● On UNIX or Linux, type

./cogconfig.sh -s

● On Windows, type

cogconfig.bat -s

Tip: To view log messages that were generated during an unattended configuration, see the
cogconfig_response.csv file in the c8_location/logs directory.

IBM Cognos Configuration applies the configuration settings specified in the local copy of cogstar-
tup.xml, encrypts credentials, generates digital certificates, and if applicable, starts IBM Cognos 8
service or process.

Set Up an Unattended Uninstallation

Set up an unattended installation and configuration to
● automate the removal of components on several computers that have the same components

● remove components in a UNIX or Linux environment that does not have XWindows

Steps
1. Go to c8_location/instlog.

2. Open the transfer specification .ats file for the product in a text editor:
The filename format of the transfer specification .ats file is ts-product_code-version-yyyym-
mdd_hhmm.ats
where product_code is as follows:

Product_code Product

C8BISRVR IBM Cognos 8 BI Server

C8BIMODEL Framework Manager

Installation and Configuration Guide 287

Chapter 15: Setting Up an Unattended Installation and Configuration

Product_code Product

CMMSRVR IBM Cognos Metrics Manager

C8BIMEMOD Metric Designer

C8BISAMPLES Samples

LP Supplementary Languages Documentation

If you have more than one .ats file for a product, you only need to edit one of the .ats files.

3. In the section named [Component List], specify the components to remove.

● To remove the component, type 1

● To leave the component installed, type 0

4. Save and close the file.

5. Go to the operating system directory.

6. At the command prompt, type the following command, where filename is the name of the
transfer specification .ats file that you edited:
● On Windows,

uninst -u -s c8_location/instlog/filename.ats

● On UNIX or Linux,

./uninst -u -s c8_location/instlog/filename.ats

7. Repeat the entire procedure for each product that you want to uninstall.

288 PowerPlay®
Chapter 16: Performance Maintenance

This section includes topics about using IBM Cognos products with tools and metrics that help to
maintain the performance of your IBM Cognos 8 environment.

System Performance Metrics

IBM Cognos 8 provides system metrics that you can use to monitor the health of the entire system
and of each server, dispatcher, and service. You can also set the thresholds for the metric scores.
Some examples of system performance metrics are the number of sessions in your system, how long
a report is in a queue, how long a Java Virtual Machine (JVM) has been running, and the number
of requests and processes in the system.
System performance metrics are available in IBM Cognos Administration, which you can access
from IBM Cognos Connection. For more information about using system performance metrics, see
the Administration and Security Guide.
An added feature is that you can take a snapshot of the current system metrics so that you can track
trends over time or review details about the state of the system at a particular time. For more
information, see the topic about the metric dump file in the troubleshooting chapter of the
Administration and Security Guide.

Enabling Only Services That are Required

If some IBM Cognos 8 services are not required in your environment, you can disable them to
improve the performance of other services.
For example, to dedicate a computer to running and distributing reports, you can disable the
presentation service on a report server computer. When you disable the presentation service, the
performance of the report server will improve.

Notes
● The Presentation service must remain enabled on at least one computer in your IBM Cognos 8
environment.

● If you want to use Query Studio, you must enable the Presentation service.

● If you want to use Analysis Studio, you must enable the Report service.

● If some IBM Cognos 8 components are not installed on a computer, you should disable the
services associated with the missing components. Otherwise the IBM Cognos 8 components
will randomly fail.

IBM Cognos 8 Services

After you install and configure IBM Cognos 8, one dispatcher is available on each computer by
default. Each dispatcher has a set of associated services, listed in the following table.

Installation and Configuration Guide 289

Chapter 16: Performance Maintenance

Service Purpose

Agent service Runs agents. If the conditions for an agent are met when
the agent runs, the agent service asks the monitor service
to run the tasks.

Batch report service Manages background requests to run reports and

provides output on behalf of the monitor service.

Content Manager service ● Performs object manipulation functions in the

content store, such as add, query, update, delete,
move, and copy

● Performs content store management functions, such

as import and export

Data movement service Manages the execution of data movement tasks in IBM
Cognos 8. Data movement tasks, such as Builds and
JobStreams, are created in Data Manager Designer and
published to IBM Cognos 8.

Delivery service Sends emails to an external SMTP server on behalf of

other services, such as the report service, job service,
agent service, or data integration service

Event management service Creates, schedules, and manages event objects that
represent reports, jobs, agents, content store mainten-
ance, deployment imports and exports, and metrics

Job service Runs jobs by signaling the monitor service to run job
steps in the background. Steps include reports, other
jobs, import, exports, and so on.

Log service Records log messages generated by the dispatcher and

other services. The log service can be configured to
record log information in a file, a database, a remote
log server, Windows Event Viewer, or a UNIX system
log. The log information can then be analyzed by cus-
tomers or by Cognos Software Services, including:
● security events

● system and application error information

● selected diagnostic information

290 PowerPlay®
 Chapter 16: Performance Maintenance

Service Purpose

Metric Studio service Provides the Metric Studio user interface for monitoring
and entering performance information

Migration service Manages the migration from IBM Cognos Series 7 to

IBM Cognos 8.

Monitor service ● Manages the monitoring and execution of tasks

that are scheduled, submitted for execution at a
later time, or run as a background task

● Assigns a target service to handle a scheduled task.

For example, the monitor service may ask the batch
report service to run a report, the job service to run
a job, or the agent service to run an agent.

● Creates history objects within the content manager

and manages failover and recovery for executing
entries

Presentation service ● Transforms generic XML responses from another

service into output format, such as HTML or PDF

● Provides display, navigation, and administration

capabilities in IBM Cognos Connection

Report data service Manages the transfer of report data between IBM
Cognos 8 and applications that consume the data, such
as IBM Cognos 8 Go! Office and IBM Cognos 8 Go!
Mobile.

Report service Manages interactive requests to run reports and

provides output for a user in IBM Cognos Connection
or a studio

System service Defines the Business Intelligence Bus API-compliant

service used to obtain application-wide IBM Cognos 8
configuration parameters. It also provides methods that
normalize and validate locale strings and map locale
strings to locales supported by your application.

Tuning a DB2 Content Store

If you use a DB2 database for the content store (p. 35), you can take steps to improve the speed
with which requests are processed.

Installation and Configuration Guide 291

Chapter 16: Performance Maintenance

By default, DB2 assigns tables that contain large objects (LOBS) to a database-managed tablespace.
As a result, the LOBS are not managed by the DB2 buffer pools. This results in direct I/O requests
on the LOBS, which affects performance. By reassigning the tables that contain LOBS to a
system-managed tablespace, you reduce the number of direct I/O requests.
Before changing a DB2 content store, allocate sufficient log space to restructure the database.
To reconfigure the DB2 content store, do the following:
❑ Export the data from the tables that contain at least one large object (LOB).

❑ Create the tables in a system-managed table space.

❑ Import the data into the tables.

Tune Apache Tomcat Settings

If you use Apache Tomcat, you can edit settings to improve performance.
You can edit the maxProcessor and acceptCount settings in the server.xml file.

Steps
1. Open the server.xml file.

2. Edit the settings that appear after the following comment:

<!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 8080 -->

Find the following line:

maxProcessors="75"

and change it to the following:

maxProcessors="1000"

3. Find the following line:

acceptCount="100"

and change it to the following:

acceptCount="500"

4. Save the updated server.xml file.

Increase the Request-handling Capacity for Cognos Content

Database
Cognos Content Database is configured for use with a small system. If you use Cognos Content
Database in a large system, where the number of simultaneous requests is greater than ten, you
must adjust the default JVM memory settings and increase the page cache size for Derby.

Steps
1. In the c8_location\bin directory, open the derby.sh file.

292 PowerPlay®
 Chapter 16: Performance Maintenance

2. Find the following line:

MEM_SETTINGS=-Xmx256m

and change it to the following:

MEM_SETTINGS="-Xmx1152m -XX:MaxPermSize=128M -XX:MaxNewSize=576m
-XX:NewSize=288m"

3. In the c8_location\configuration directory, rename derby.properties.sample to derby.properties.

4. In the same directory, open the derby.properties file.

5. Comment out the following line:

derby.storage.pageCacheSize=15000

Reduce Delivery Time for Reports in a Network

Reports that are distributed globally take longer to open in remote locations than to open locally.
In addition, HTML reports take longer than PDF reports to open because more requests are processed
for HTML reports.
You can reduce the amount of time for reports to open in remote locations in two ways. You can
reduce the number of requests between the browser and the server by running the report in PDF
format. If HTML reports are required, you can speed up the delivery of the report by configuring
additional gateways in some of the remote locations. Static content, such as graphics and style
sheets, will be delivered faster.

Installation and Configuration Guide 293

Chapter 16: Performance Maintenance

294 PowerPlay®
Appendix A: Manually Configuring IBM Cognos 8

The console attached to the UNIX or Linux computer on which you are installing IBM Cognos 8
may not support a Java-based graphical user interface. You must perform the following tasks
manually.
❑ Manually change default configuration settings by editing the cogstartup.xml file, located in
the c8_location/configuration directory.

❑ Manually change language or currency support, or locale mapping by editing the coglocale.xml
file, located in the c8_location/configuration directory.

❑ Apply the configuration and the locale settings to your computer by starting the IBM Cognos 8
services in silent mode.

❑ Deploy IBM Cognos 8 into an application server environment by manually creating a IBM
Cognos application file.

For all installations, some configuration tasks are required so that IBM Cognos 8 works in your
environment. If you distribute IBM Cognos 8 components across several computers, the order in
which you configure and start the computers is important.
Other configuration tasks are optional and depend on your reporting environment. You can change
the default behavior of IBM Cognos 8 by editing the cogstartup.xml file to change property values.
You can also use sample files that enable IBM Cognos 8 to use resources that already exist in your
environment.

Manually Configuring IBM Cognos 8 on UNIX and Linux

The console attached to the UNIX or Linux computer on which you are installing IBM Cognos 8
may not support a Java-based graphical user interface. You must
❑ manually change default configuration settings by editing the cogstartup.xml file, located in
the c8_location/configuration directory

❑ manually change language or currency support, or locale mapping by editing the coglocale.xml
file, located in the c8_location/configuration directory

❑ apply the configuration and the locale settings to your computer by running IBM Cognos
Configuration in silent mode

For all installations, some configuration tasks are required so that IBM Cognos 8 works in your
environment. If you distribute IBM Cognos 8 components across several computers, the order in
which you configure and start the computers is important.
Other configuration tasks are optional and depend on your reporting environment. You can change
the default behavior of IBM Cognos 8 by editing the cogstartup.xml file to change property values.
You can also use sample files that enable IBM Cognos 8 to use resources that already exist in your
environment.

Installation and Configuration Guide 295

Appendix A: Manually Configuring IBM Cognos 8

Manually Change Default Configuration Settings on UNIX and Linux Computers

If the console attached to your UNIX or Linux computer does not support a Java-based graphical
user interface, you must edit the cogstartup.xml to configure IBM Cognos 8 to work in your
environment.

Note: Some configuration settings are not saved in the cogstartup.xml file unless you use the
graphical user interface. For example, the server time zone is not set for your IBM Cognos compon-
ents when you modify the cogstartup.xml file directly and then run IBM Cognos Configuration in
silent mode. In this case, other user settings that rely on the server time zone may not operate as
expected.
If you want IBM Cognos 8 to use a resource, such as an authentication provider that already exists
in your environment, you can add a component to your configuration. You do this by copying the
required XML code from the sample files into the cogstartup.xml file and then edit the values to
suit your environment.

Important: By default, the cogstartup.xml file is encoded using UTF-8. When you save the cogstar-
tup.xml file, ensure that you change the encoding of your user locale to match the encoding used.
The encoding of your user locale is set by your environment variables.
When you edit the cogstartup.xml file, remember that XML is case-sensitive. Case is important in
all uses of text, including element and attribute labels, elements and values.
Before you edit the cogstartup.xml file, ensure that you
● make a backup copy

● create the content store on an available computer in your network

● review the configuration requirements for your installation type

Steps
1. Go to the c8_location/configuration directory.

2. Open the cogstartup.xml file in an editor.

3. Find the configuration setting you want to change by looking at the help and description
comments that appear before the start tag of the <crn:parameter> elements.

4. Change the value of the <crn:value> element to suit your environment.

Tip: Use the type attribute to help you determine the data type for the configuration property.

5. Repeat steps 3 to 4 until the configuration values are appropriate your environment.

6. Save and close the file.

You should now use a validating XML editor to validate your changes against the rules in the
cogstartup.xsd file, located in the c8_location/configuration.

Add a Component to Your Configuration

The cogstartup.xml file contains configuration settings used by IBM Cognos 8 and by default third-
party components.You can change the components that IBM Cognos 8 uses by copying XML ele-

296 PowerPlay®
 Appendix A: Manually Configuring IBM Cognos 8

ments from sample files into the cogstartup.xml file. You can then edit the configuration values to
suit your environment.
For example, to use an Oracle database for the content store, you can use the ContentManager_lan-
guage code.xml sample file to replace the default database connection information.
IBM Cognos 8 can use only one instance at a time of the following elements:
● the database for the content store

● a cryptographic provider

● a configuration template for the IBM Cognos 8 service

You should be familiar with the structure of XML files before you start editing them.

Steps
1. Go to the c8_location/configuration/samples directory.

2. Choose a sample file to open in an editor:

● To use Oracle, DB2, or Sybase for the content store, open the ContentManager_lan-
guage_code.xml file.

● To use an authentication provider, open the Authentication_language_code.xml file.

● To use a third-party cryptographic provider, open the Cryptography_language_code.xml

file.

● To send log messages somewhere other than a file, open the Logging_language_code.xml
file.

● To use a medium or large template for the amount of resources the IBM Cognos 8 process
uses, open the CognosService_language_code.xml file.

3. Copy the elements that you need.

Tip: Ensure that you copy the code including the start and end tags for the <crn:instance>
element.
For example, look for the (Begin of) and (End of) comments:
<!--
===============================================
(Begin of) DB2 template
-->
<crn:instance ...>
...
</crn:instance>
<!--
End of) DB2 template
===============================================
-->

4. Go to the c8_location/configuration directory.

5. Open the cogstartup.xml file in an editor.

Installation and Configuration Guide 297

Appendix A: Manually Configuring IBM Cognos 8

6. Paste the code from the sample file to the cogstartup.xml file and replace the appropriate
<crn:instance> element.

7. Change the values of these new elements to suit your environment.

For the <crn:instance> element, don’t change the class attribute. You can change the name
attribute to suit your environment.
For example, if you use an Oracle database for the content store, change only the name
attribute to suit your environment.
<crn:instance class="Oracle" name="MyContentStore">

8. Save and close the file.

9. Run IBM Cognos Configuration in silent mode by typing the following command:

./cogconfig.sh -s
This ensures that the file is valid and that passwords are encrypted.

Manually Change Encrypted Settings

You can manually change encrypted settings, such as passwords and user credentials, in the cogstar-
tup.xml file.
To prompt IBM Cognos Configuration to save an encrypted setting, you change the value and then
set the encryption flag to false.

Steps
1. Go to the c8_location/configuration directory.

2. Open the cogstartup.xml file in an editor.

3. Find the encrypted setting you want to change by looking at the help and description comments
that appear before the start tag of the <crn:parameter> elements.

4. Change the value of the <crn:value> element to suit your environment.

Tip: Use the type attribute to help you determine the data type for the configuration property.

5. Change the encryption value to false.

For example,
<crn:value encrypted="false">

6. Repeat steps 3 to 5 until the configuration values are appropriate for your environment.

7. Save and close the file.

8. Type the following configuration command:

./cogconfig.sh -s

The new settings are saved and encrypted.

298 PowerPlay®
 Appendix A: Manually Configuring IBM Cognos 8

Manually Change the Global Settings on UNIX and Linux Computers

If the console attached to your UNIX or Linux computer does not support a Java-based graphical
user interface, you must manually edit the coglocale.xml file located in the c8_location/configuration
directory.
You can change global settings
● to specify the language used in the user interface when the language in the user’s locale is not
available

● to specify the locale used in reports when the user’s locale is not available

● to add currency or locale support to report data and metadata

● to add language support to the user interface

By default, IBM Cognos 8 components ensure that all locales, which may come from different
sources and in various formats, use a normalized form. That means that all expanded locales conform
to a language and regional code setting.
Before you can add language support to the user interface, you must install the language files on
all computers in your distributed installation. For more information, contact Cognos Software
Services.

Example 1
A report is available in Content Manager in two locales, such as en-us (English-United States) and
fr-fr (French-France), but the user locale is set to fr-ca (French-Canadian). IBM Cognos 8 uses the
locale mapping to determine which report the user sees.
First, IBM Cognos 8 checks to see if the report is available in Content Manager in the user’s locale.
If it is not available in the user’s locale, IBM Cognos 8 maps the user’s locale to a normalized locale
configured on the Content Locale Mapping tab. Because the user’s locale is fr-ca, it is mapped to
fr. IBM Cognos 8 uses the mapped value to see if the report is available in fr. In this case, the report
is available in en-us and fr-fr, not fr.
Next, IBM Cognos 8 maps each of the available reports to a normalized locale. Therefore, en-us
becomes en and fr-fr becomes fr.
Because both report and the user locale maps to fr, the user having the user locale fr-ca will see the
report saved with the locale fr-fr.

Example 2
The user’s locale and the report locales all map to the same language. IBM Cognos 8 chooses which
locale to use. For example, if a user’s locale is en-ca (English-Canada) and the reports are available
in en-us (English-United States) and en-gb (English-United Kingdom), each locale is mapped to en.
The user will see the report in the locale setting chosen by the your IBM Cognos 8 product.

Example 3
The report and the user locales do not map to a common language. Your IBM Cognos 8 product
chooses the language. In this case, you may want to configure a mapping. For example, if a report

Installation and Configuration Guide 299

Appendix A: Manually Configuring IBM Cognos 8

is available in en-us (English-United States) and fr-fr (French-France), but the user locale is es-es
(Spanish-Spain), your IBM Cognos 8 product chooses the language.

Steps
1. On every computer where you installed Content Manager, go to the c8_location/configuration
directory.

2. Open the coglocale.xml file in an editor.

3. Add or modify the required element and attribute between the appropriate start and end tags.

Type of element Start tag End tag

Language <supportedProductLocales> </supportedProductLocales>

Content Locales <supportedContentLocales> </supportedContentLocales>

Currency <supportedCurrencies> </supportedCurrencies>

Product Locale Mapping <productLocaleMap> </productLocaleMap>

Content Locale Mapping <contentLocaleMap> </contentLocaleMap>

Fonts <supportedFonts> </supportedFonts>

Cookie settings, archive <parameter name="setting"> </parameter>

location for reports

Tip: To remove support, delete the element.

4. Save and close the file.

Tip: We recommend that you use a validating XML editor to validate your changes against the
rules in the cogstartup.xsd file, located in the c8_location/configuration.
If you add a currency code that is not supported by IBM Cognos, you must manually add it to the
i18n_res.xml file in the c8_location/bin/ directory. Copy this file to each IBM Cognos computer in
your installation.

Starting and Stopping IBM Cognos 8 in Silent Mode on UNIX and Linux Com-
puters
You run IBM Cognos Configuration in silent mode to apply the configuration settings and start
the services on UNIX or Linux computers that do not support a Java-based graphical user interface.

300 PowerPlay®
 Appendix A: Manually Configuring IBM Cognos 8

Before you run the configuration tool in silent mode, you should ensure the cogstartup.xml file is
valid according to the rules defined in the cogstartup.xsd file. The cogstartup.xsd file is located in
the c8_location/configuration directory.

Steps to Start IBM Cognos 8

1. Ensure that the cogstartup.xml file, located in the c8_location/configuration directory, has been
modified for your environment.
For more information, see "Manually Change Default Configuration Settings on UNIX and
Linux Computers" (p. 296).

2. Go to the c8_location/bin directory.

3. Type the following command

./cogconfig.sh -s

Tip: To view log messages that were generated during an unattended configuration, see the
cogconfig_response.csv file in the c8_location/logs directory.

IBM Cognos Configuration applies the configuration settings specified in the cogstartup.xml file,
encrypts credentials, generates digital certificates, and if applicable, starts the IBM Cognos 8 service
or process.

Steps to Stop IBM Cognos 8

1. Go to the c8_location/bin directory.

2. Type the following command

./cogconfig.sh -stop

Manually Create an IBM Cognos Application File

IBM Cognos 8 and the servlet gateway must be packaged into an application file for deployment
to supported application servers (p. 262), (p. 238). IBM Cognos 8 provides a Build Application wizard
that you can use to create the application file.
You can create a Web archive (.war) file, an Enterprise archive (.ear) file, or an expanded directory
that includes all the files necessary for the application. For information about WAR and EAR files
or expanded directories and to determine what is supported by your application server, see the
documentation provided with the application server.
If you choose not to use the Build Application wizard, you must complete the following steps to
create the application file.
If the application server is not being used as a Web server, you do not need to include the IBM
Cognos static content (html pages, images, and so on) in the application file. Excluding the static
content when creating the application file reduces the size of the file.

Steps to Create an IBM Cognos 8 Application File

1. Go to the c8_location/war/p2pd directory.

Installation and Configuration Guide 301

Appendix A: Manually Configuring IBM Cognos 8

2. Run the build script by using the following command syntax:

● For Windows,

build.bat file_type option

● For UNIX or Linux,

build.sh file_type option

where file_type can be one of the following:

Value Description

war WAR file with static content

war_without_webcontent WAR file with no static content

war_without_docsamples WAR file with static content and with no

documentation and sample files

ear EAR file with static content

ear_without_webcontent EAR file with no static content

ear_without_docsamples EAR file with static content and with no

documentation and sample files

expand directory containing the application with

static content

expand_without_webcontent directory containing the application with

no static content

expand_without_docsamples directory containing the application with

static content and with no documentation
and sample files

and where option can be one or more of the following:

Option Value Description

-Dappserver_type=value jboss Perform actions for a JBoss

application server
other (default)
Perform actions for a non-
JBoss application server

302 PowerPlay®
 Appendix A: Manually Configuring IBM Cognos 8

Option Value Description

-Dcontext_root=value p2pd (default) Preset a context root value for

the application

-Dwar_name=value path/filename Path and name of the WAR

file to be created
Default is ../../p2pd.war

-Dear_name=value path/filename Path and name of the EAR file

to be created
Default is ../../p2pd.ear

-Dexpand_location=value path/directory Path to directory where the

(For expand file types) Default is ../../temp/expand application files are to be
expanded

Steps to Create a Servlet Gateway Application File

1. Go to the c8_location/war/gateway directory.

2. Run the build script by using the following command syntax:

● For Windows,

build.bat file_type option

● For UNIX or Linux,

build.sh file_type option

where file_type can be one of the following:

Value Description

gateway_war WAR file with static content

gateway_war_without_docsamples WAR file with static content and with no

documentation and sample files

gateway_ear EAR file with static content

gateway_ear_without_docsamples EAR file with static content and with no

documentation and sample files

expand directory containing the application with

static content

Installation and Configuration Guide 303

Appendix A: Manually Configuring IBM Cognos 8

Value Description

expand_without_docsamples directory containing the application with

static content and with no documentation
and sample files

and where option can be one or more of the following:

Option Value Description

-Dappserver_type=value jboss Perform actions for a JBoss

application server
other (default)
Perform actions for a non-
JBoss application server

-Dcontext_root=value ServletGateway (default) Preset a context root value for

the application

-Dwar_name=value path/filename Path and name of the WAR

file to be created
Default is ../../
ServletGateway.war

-Dear_name=value path/filename Path and name of the EAR file

to be created
Default is ../../
ServletGateway.ear

-Dexpand_location=value path/directory Path to directory where the

application files are to be
Default is ../../temp/expand
expanded

304 PowerPlay®
Appendix B: Troubleshooting

Use this troubleshooting reference information and solutions as a resource to help you solve specific
problems you may encounter during or after the installation of IBM Cognos 8 PowerPlay compon-
ents.
Problems are characterized by their symptoms. Each symptom can be traced to one or more causes
by using specific troubleshooting tools and techniques. After being identified, each problem can be
fixed by implementing a series of actions.
When you are troubleshooting, log files can help you. Another valuable troubleshooting tool is the
Knowledge Base, which is available on the IBM Cognos Resource Center (http://www.ibm.com/
software/data/support/cognos_crc.html). The Knowledge Base is a database of problems and solutions
for all IBM Cognos products.
When you cannot resolve a problem, the final resource is your IBM Cognos technical support rep-
resentative. To analyze a problem, your technical support representative requires information about
the situation and the symptoms that you are experiencing. To help isolate the problem, collect the
necessary data before you contact your representative.

Log Files
Log files can help you troubleshoot problems by recording the activities that take place when you
work with a product. Operations performed in IBM Cognos 8 are recorded in various log files for
tracking purposes. For example, if you experienced problems installing IBM Cognos 8, consult the
transfer log file to learn what activities the installation wizard performed while transferring files.
Before you begin viewing log files, ensure that they contain the information that you need. The
number of log files and the information they contain are set by parameters in IBM Cognos Connec-
tion and in IBM Cognos Configuration.
Use IBM Cognos Administration to learn about logging categories and how to set the level of detail
to log for each category.
For more information, see the IBM Cognos 8 Administration and Security Guide.
Use IBM Cognos Configuration to specify the size, number, and location of log files, and to configure
the properties of the log server. For more information, see the IBM Cognos Configuration User
Guide.
When troubleshooting, the following files can assist you:

The Transfer Log File

This file records the activities that the installation wizard performed while transferring files. The
transfer log file is located in the c8_location\instlog directory. The file name identifies the product
name, version, and build number, and includes a time stamp. The following is an example of the
file name format:
tl-C8BISRVR-8.1-0.0-20080901_1122.txt

Installation and Configuration Guide 305

Appendix B: Troubleshooting

The Transfer Summary-Error Log File

This file records the components you installed, disk space information, the selections you made in
the transfer dialogs, and any errors the installation wizard encountered while transferring compon-
ents. The transfer summary-error log file is located in the c8_location/instlog directory. The file
name identifies the product name, version, and build number, and includes a time stamp. The
following is an example of the file name format:
tl-C8BISRVR-8.1-0.0-20080901_1122_summary_error.txt

The Startup Configuration File

This file records your configuration choices each time you save your property settings. The file
name is cogstartup.xml. If you are unable to save your configuration, or are having problems you
can revert to a previously saved configuration file. The backup configuration files are located in
the c8_location/configuration directory. The following is an example of the file name format for
backup configuration files:
cogstartup_200811231540.xml

The Startup Configuration Lock File

This file is created each time you open IBM Cognos Configuration. It prevents you from opening
more than one IBM Cognos Configuration window. If you experience problems opening IBM
Cognos Configuration, you can check the c8_location/configuration directory for the cogstartup.lock
file. If the file exists and IBM Cognos Configuration is not open, it means that IBM Cognos
Configuration did not shut down properly the last time you used it. You can delete the lock file
and then open IBM Cognos Configuration.

The Locale Configuration File

This file records the configuration choices you make in IBM Cognos Configuration for product
and content locales, locale mapping, and currency support. If you experience problems with language
support in the user interface or in reports, use these files to track your changes. The backup config-
uration files are located in the c8_location/configuration directory. The following is an example of
the file name format:
coglocale_200811231540.xml

The Run-Time Log File

The default IBM Cognos log file named cogserver.log file, or other log files that you configure to
receive log messages from the log server, record information after you start the IBM Cognos 8 service.
They are located in the c8_location/logs directory. If you configured another destination for log
messages, check the appropriate file or database.
Some log messages indicate problems. Most messages provide information only, but others can
help you to diagnose problems in your run-time environment.

The Gateway Log File

The gateways record errors in the gateway log file, which is located in the c8_location/logs directory.
You can use the gateway log file to troubleshoot problems that prevent the gateway from processing
requests or from using encryption. Symptoms of these problems are user IDs and passwords do not

306 PowerPlay®
 Appendix B: Troubleshooting

work, single signon does not work, and the dispatcher is running but users receive the following
error message: The IBM Cognos BI server is not available. The gateway log file uses the
following naming format, where gateway_interface is cgi, mod (Apache 1.3 module), mod2 (Apache
2.0 module), or isapi.
gwgateway_interface.log (for example, gwcgi.log)

The Uninstallation Log File

This file records the activities that the Uninstall wizard performed while uninstalling files. The log
file is named cognos_uninst_log.htm and is located in the Temp directory. You can use the log file
to troubleshoot problems related to uninstalling IBM Cognos 8 components.

The Silent Mode Log File

This file records the activities that IBM Cognos Configuration performed while running in silent
mode. This log file is named cogconfig_response.csv and is located in the c8_location/logs directory.

The ReportNet® to IBM Cognos 8 Upgrade File

This file contains a summary of the results of an upgrade from ReportNet to IBM Cognos 8. The
log file is named upgradeLog.xml and is located in the c8_location/logs directory. The file is in xml
format and references an xslt style sheet. You can double-click the file to have it appear in your
browser.

Problems Starting IBM Cognos 8

You may encounter problems when you try
● to start the IBM Cognos 8 service

● to open the Welcome page in the IBM Cognos 8 portal for the first time

● to start an application server, such as WebLogic or WebSphere

Symptoms Solution

You do not see the splash screen for the IBM Check your Web server configuration.
Cognos portal when you start IBM Cognos 8.

The service starts but no tables are created in Check your content store configuration.
the content store database.

The service does not start. Ensure that you wait a few moments before
submitting a request.

The application server does not start. Check the file permissions and directory names
of the application server installation location.

Installation and Configuration Guide 307

Appendix B: Troubleshooting

Ensure that you use software that is supported by IBM Cognos components. You can view an up-
to-date list of environments, such as operating systems, patches, browsers, Web servers, directory
servers, and database servers on the the IBM Cognos Resource Center (http://www.ibm.com/software/
data/support/cognos_crc.html).

CFG-ERR-0106 Error When Starting the IBM Cognos 8 Service in IBM Cognos
Configuration
When you start the IBM Cognos 8 service, you may receive the following error message:
CFG-ERR-0106 IBM Cognos Configuration received no response from the IBM Cognos 8 service
in the allotted time. Check that IBM Cognos 8 service is available and properly configured.
There are two possible causes for this problem:
● The IBM Cognos 8 service needs more time to start.

● A standby Content Manager computer may be configured incorrectly.

The IBM Cognos 8 Service Needs More Time

By default, IBM Cognos Configuration checks the progress of the start request every half second
for three minutes. If IBM Cognos Configuration does not receive a response within this time, the
error message appears.
To avoid this error, you can change the amount of time that IBM Cognos Configuration waits to
receive a response from the IBM Cognos 8 service. You do this by configuring the ServiceWaitInt-
erval and ServiceMaxTries properties in the c8_location/configuration/cogconfig.prefs file.
The ServiceWaitInterval property represents the time interval, in milliseconds, at which IBM Cognos
Configuration checks the progress of the start request. By default, its value is 500, which is equivalent
to half a second.
The ServiceMaxTries property represents the number of times that IBM Cognos Configuration
checks the progress of the start request. By default, its value is 360.

Content Manager Is Configured Incorrectly

If the error message appears on a standby Content Manager computer, the setting for storing the
symmetric keys may be incorrect.
To avoid this problem, configure the standby Content Manager computer to store the symmetric
keys locally.

Steps to Change the Wait Time

1. Using IBM Cognos Configuration, stop the IBM Cognos 8 service.

2. Open the c8_location/configuration/cogconfig.prefs file in an editor.

This file is created automatically the first time you open IBM Cognos Configuration.

3. Add the following code to the file:

ServiceWaitInterval=number of milliseconds

ServiceMaxTries=number of times

308 PowerPlay®
 Appendix B: Troubleshooting

Tip: Add the numeric values that correspond to your configuration needs.

4. Save the file.

5. Using IBM Cognos Configuration, start the IBM Cognos 8 service.

Steps to Store Symmetric Keys Locally

1. On the standby Content Manager computer, start IBM Cognos Configuration.

2. In the Explorer window, under Security, click Cryptography.

3. In the Properties window, under CSK settings, set Store symmetric key locally to True.

4. From the File menu, click Save.

5. From the Actions menu, click Start.

This action starts all installed services that are not running. If you want to start a particular
service, select the service node in the Explorer window and then click Start from the Actions
menu.

Cryptographic Error When Starting IBM Cognos 8

You received the following error when you tried to start the IBM Cognos 8 service after installing
server or client components:
[Cryptography]
1. [ ERROR ] java.lang.NoClassDefFoundError:
javax/net/ServerSocketFactory:
Your Java Runtime Environment (JRE) is missing the encryption and decryption routines that are
required by IBM Cognos 8. You must copy the Java Archive (.jar) file that IBM Cognos provides
to your JRE directory.

Step
● Copy the bcprov-jdknn-nnn.jar file from the c8_location/bin/jre/version/lib/ext directory to the
Java_location/jre/lib/ext directory.

Unable to Start the IBM Cognos 8 Service Because the Port is Used by Another
Process
You may not be able to start the IBM Cognos 8 service or process if one of the default ports is used
by another process.

Tip: To view the current network TCP/IP network connections, use the netstat command.
Use IBM Cognos Configuration to change the default port that IBM Cognos 8 uses.
When you change the port used by the local dispatcher, you must change the value of the Dispatcher
URI properties. Because the change affects all the URIs that are based on the local dispatcher, you
must change the URIs of all local components. By default, local components contain localhost in
the URI.

Installation and Configuration Guide 309

Appendix B: Troubleshooting

For example, if you install all components on one computer and you want to change the dispatcher
port, replace 9300 in all dispatcher and Content Manager URIs with the new port number.

Steps to Change the Default Port

1. Start IBM Cognos Configuration.

2. In the Explorer window, click the appropriate group or component:

● To access the port number in the dispatcher and Content Manager URIs, click Environment.

● To access the port number for the local log server, under Environment, click Logging.

● To access the shutdown port number, under Environment, click IBM Cognos 8 service,
IBM Cognos 8.

● To access the port number for the location of the applications.xml file used by Portal Ser-
vices, under Environment, click Portal Services.

3. In the Properties window, click the Value box next to the property that you want to change.

4. Change the value from 9300 to the new value.

Ensure that you change the ports in all URIs that contain localhost:9300.

5. From the File menu, click Save.

6. From the Action menu, click Start.

IBM Cognos 8 Service Does Not Start or Fails After Starting

You start the IBM Cognos 8 service but services either do not start correctly or are very slow to
start. After services start, the system fails a short time afterwards. While services are starting, Java
uses 100 percent of the CPU time. You may also receive multiple occurrences of error messages
such as the following:
● DPR-DPR-1035 Dispatcher detected an error.

● CAM-CRP-1157 Unable to synchronize the local common symmetric key store with Content
Manager.

If you use a DB2 database for the content store, ensure that the database version and Java version
are compatible. For DB2 version 8.2, Java 1.5 is not supported. For DB2 version 9, Java 1.5 is
supported on all operating systems except HPUX and Solaris.
To review an up-to-date list of environments supported by IBM Cognos products, such as operating
systems, patches, browsers, Web servers, directory servers, database servers, and application servers,
visit the the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.
html).

IBM Cognos 8 Server Fails to Start and Gives No Error Message

An IBM Cognos 8 server may fail to start, but no error message appears. This may occur when an
IBM Cognos 8 server is configured to use a large amount of memory.

310 PowerPlay®
 Appendix B: Troubleshooting

If the server on which IBM Cognos 8 is installed contains version 1.0 of Microsoft security update
921883, there may be an issue when a lot of contiguous memory is requested by an application.
This is a known issue with version 1.0 of Microsoft security patch 921883. Microsoft distributed
a second version of the patch to fix the problem. As a workaround, uninstall the first security patch,
or install version 2.0 of the patch. Alternatively, you can configure the IBM Cognos 8 server to use
less memory.
For more information, see the Microsoft knowledge base article about programs using a lot of
contiguous memory failing, at http://support.microsoft.com.

IBM Cognos BI Server Not Available When Starting IBM Cognos 8

After you configure IBM Cognos components and start the IBM Cognos 8 services, when you
connect to the IBM Cognos 8 portal, the following error message may appear:
The IBM Cognos Gateway is unable to connect to the IBM Cognos BI server.
The server may be unavailable, or the gateway may not be correctly configured.
Check the IBM Cognos server log file for more information. By default, the cogserver.log file is
located in the c8_location/logs directory. If you configured another destination for log messages,
check the appropriate file or database.
Content Manager may not be able to connect to the content store if the content store is not con-
figured properly. This may occur if
● the content store uses an unsupported character encoding

● the content store uses a database collation sequence that is case sensitive

● the configuration settings you specified in IBM Cognos Configuration are not valid

Unsupported Character Encoding

If the following messages appear in the log file, the database you created for the content store does
not use a supported character encoding:
● For Oracle:
CM-CFG-5063 A Content Manager configuration error was detected while connecting to the
content store.
CM-SYS-5121 Content Manager cannot start because the database character set for the content
store is not supported.
CM-SYS-5126 The content store database server uses the character set US7ASCII.
CM-SYS-5125 The content store database client uses the character set US7ASCII.

● For DB2 UDB:

CM-CFG-5063 A Content Manager configuration error was detected while connecting to the
content store.
CM-SYS-5121 Content Manager cannot start because the database character set for the content
store is not supported.

Installation and Configuration Guide 311

Appendix B: Troubleshooting

CM-SYS-5124 The content store database server uses the code page 1252.

● For Sybase:
CM-CFG-5063 A Content Manager configuration error was detected while connecting to the
content store.
CM-SYS-5121 Content Manager cannot start because the database character set for the content
store is not supported.

For Content Manager to connect to the content store, the content store must use the appropriate
character encoding.

Database Character encoding

Oracle 9i AL32UTF8
AL32UTF16

DB2 UDB Codeset UTF-8

Sybase ASE UTF-8

Microsoft SQL Server UTF8

UTF16

To resolve this problem, you must recreate the content store database using the correct character
encoding, or convert the character encoding. For more information, see the database vendor docu-
mentation.

Case Sensitive Collation Sequence

If the following messages appear in the log file, the database you created for the content store uses
a database collation sequence that is case sensitive:
CM-CFG-5063 A Content Manager configuration error was detected while connecting to the content
store.
CM-SYS-5122 The content store database has a default collation that is case-sensitive. Content
Manager requires a content store that has a case-insensitive collation.
CM-SYS-5123 The content store database server uses the collation <parameter>.
CM-SYS-5007 Content Manager build @cm_build_version@ failed to start! Review the Content
Manager log files and then contact your system administrator or customer support.
To resolve this problem, you must recreate the content store database using a database collation
sequence that is not case sensitive. For more information, see the database vendor documentation.

Invalid Configuration Settings

If the following or similar messages appear in the log file, you did not configure the content store
correctly in IBM Cognos Configuration.

312 PowerPlay®
 Appendix B: Troubleshooting

● For Microsoft SQL Server:

CM-CFG-5063 A Content Manager configuration error was detected while connecting to the
content store.
CM-CFG-5036 Content Manager failed to connect to the content store. The connection string
is "jdbc:JSQLConnect://localhost:1433/cm".
Failed Logon:com.jnetdirect.jsql.x: Cannot open database requested in login 'cm'. Login fails.
url:jdbc:JSQLConnect://localhost:1433/cm.

● For DB2:
CM-CFG-5063 A Content Manager configuration error was detected while connecting to the
content store.
CM-SYS-5003 Content Manager is unable to access the content store. Verify your database
connection parameters and then contact your database administrator.
[IBM][CLI Driver] SQL1013N The database alias name or database name "CM123" could
not be found.

● For Oracle:
CM-CFG-5063 A Content Manager configuration error was detected while connecting to the
content store.
CM-CFG-5036 Content Manager failed to connect to the content store. The connection string
is "jdbc:oracle:thin:@localhost:1521:pb1".
ORA-01017: invalid username/password; logon denied.

● For Sybase:
CM-CFG-5063 A Content Manager configuration error was detected while connecting to the
content store.
CM-CFG-5036 Content Manager failed to connect to the content store. The connection string
is "jdbc:sybase:Tds:localhost:5000/cm".
JZ006: Caught IOException: java.net.ConnectException: Connection refused: connect.

If you are using an Oracle database, do not use illegal characters such as an underscore in IBM
Cognos Configuration for the Service Name property. If the Service Name includes illegal characters,
tables are not created in the content store database when the IBM Cognos 8 service is started.

Steps for Microsoft SQL Server

1. In the Explorer window, under Data Access, Content Manager, click Content Store.

2. If you created the database using Windows authentication, you must delete the existing content
and create a new one by doing the following:

● Right-click Content Store and click Delete.

● Right-click Content Manager, and then click New resource, Database.

● In the Name box, type a name for the resource.

Installation and Configuration Guide 313

Appendix B: Troubleshooting

● In the Type box, select SQL Server database (Windows Authentication) and click OK.

3. In the Properties window, type the appropriate values for the Database server with port number
or instance name and Database name properties.
For a Microsoft SQL Server database, you can choose to use a port number, such as 1433, or
a named instance as the value for the Database server with port number or instance name
property.
To connect to a named instance, you must specify the instance name as a JDBC URL property
or a data source property. For example, you can type localhost\instance1. If no instance name
property is specified, a connection to the default instance is created.
Note that the properties specified for the named instance, along with the user ID and password,
and database name, are used to create a JDBC URL. Here is an example:
jdbc:JSQLConnect://localhost\\instance1/user=sa/more properties as required

4. If you want to change the logon credentials, specify a user ID and password:

● Click the Value box next to the User ID and password property and then click the edit
button when it appears.

● Type the appropriate values and click OK.

5. From the File menu, click Save.

The logon credentials are immediately encrypted.

6. Test the connection between Content Manager and the content store.

Tip: In the Explorer window, right-click the new database and click Test.
Content Manager connects to the database, checks the database permissions, and creates and
populates a table. The table is not deleted and is used each time that the test is repeated.

Steps for Oracle, DB2, and Sybase

1. In the Explorer window, under Data Access, Content Manager, right-click Content Store and
click Delete.
This deletes the default resource. Content Manager must be configured to access only one
content store.

2. Right-click Content Manager, and then click New resource, Database.

3. In the Name box, type a name for the resource.

4. In the Type box, select the type of database and click OK.
If you installed more than one version of IBM Cognos 8, you must use a different content store
for each version. When a content store is used by a new version of IBM Cognos 8, it cannot
be used by an older version.

Tip: If you want to use Oracle Net8 keyword-value pair to manage the database connection,
select Oracle database (Advanced).

314 PowerPlay®
 Appendix B: Troubleshooting

5. In the Properties window, provide values depending on your database type:

● If you use a DB2 database, for the Database name property, type the database alias.

● If you use an Oracle database, type the appropriate values for the Database server and port
number and Service name properties.

● If you use an advanced Oracle database, for the Database specifier property, type the Oracle
Net8 keyword-value pair for the connection.
Here is an example:
(description=(address=(host=myhost)(protocol=tcp)(port=1521)(connect_data=(sid=(orcl)))))

● If you use a Sybase database, type the appropriate values for the Database server and port
number and Database name properties.

6. If you want to change the logon credentials, specify a user ID and password:

● Click the Value box next to the User ID and password property and then click the edit
button when it appears.

● Type the appropriate values and click OK.

7. From the File menu, click Save.

The logon credentials are immediately encrypted.

8. Test the connection between Content Manager and the content store.

Tip: In the Explorer window, right-click the new database and click Test.
Content Manager connects to the database, checks the database permissions, and creates and
populates a table. The table is not deleted and is used each time that the test is repeated.

Cannot Log On to a Namespace When Using IBM Cognos Connection (PRS-CSE-

1255 Error)
You open IBM Cognos 8 through IBM Cognos Connection. However, when you attempt to create
a data source and log on to a namespace, the following error messages appear:
● PRS-CSE-1255 Exception error encountered in data decryption.

● CAM-CRP-1064 Unable to process the PKCS #7 data because of an internal error. Reason:
java.lang.IndexOutOfBoundsException.

This issue may occur if you do not have the necessary permissions for the following directories:
● c8\configuration

● c8\configuration\csk

● c8\configuration\encryptkeypair

● c8\configuration\signkeypair

Installation and Configuration Guide 315

Appendix B: Troubleshooting

The solution is to enable the read and execute permissions on the directories listed above for anyone
who must start the IBM Cognos 8 service.

IBM Cognos 8 Services Fail to Restart After a Network Outage

The IBM Cognos Bootstrap Service restarts IBM Cognos 8 services after a network outage for
Tomcat installations where a network IP address is specified in the internal dispatcher URI. During
the restart, the IBM Cognos 8 services may not initialize successfully, requiring a manual restart
after the network is restored.

To resolve the problem, configure the Internal dispatcher URI property in IBM Cognos Configuration
to use localhost or the network host name.

Download of Resource Fails

You start Report Studio in Internet Explorer and the following error message appears:
The download of the specified resource has failed.
This problem may be caused by recent Microsoft XMLHTTP upgrades if you do not have a language
preference set in Internet Explorer.
To resolve the problem, specify a language preference in Internet Explorer.

DB2 Returns SQL1224N Error When Connecting from AIX

If your content store is a DB2 database and you receive an SQL1224N error on AIX, check the
db2diag.log file for additional information about the error.
If the error includes reason code 18, you may need to change the DB2 configuration to accept more
connections. For more information, see the IBM DB2 support pages for the error SQL1224N.

Content Manager Error When Starting IBM Cognos 8

After starting IBM Cognos 8, no PPESBusServer process is started. There are errors listed in the
pogo******.log and cogserver.log files. Users receive errors in the browser when connecting to the
IBM Cognos 8 portal.
In the pogo******.log file, an error related to Content Manager appears.
In the cogserver.log file, the following error appears:
An attempt to register the dispatcher in Content Manager was unsuccessful. Will retry periodically.
When connecting to http://computer name/cognos8, the following error messages appear in the
browser:
● DPR-ERR-2058 The dispatcher cannot service the request at this time. The dispatcher is still
initializing

● SoapSocketException: Connection Refused

IBM Cognos Configuration uses a user ID to bind to the LDAP database. If this user ID is moved
to another group, IBM Cognos Configuration can no longer locate it.
To correct the problem, move the user ID back to the original group.

316 PowerPlay®
 Appendix B: Troubleshooting

The Page Cannot Be Found When Starting IBM Cognos 8 in Windows 2003
After installing IBM Cognos 8 on Windows 2003, the following message may appear when you try
to start IBM Cognos 8:
The page cannot be found. The page you are looking for might have been removed, had its name
changed, or is temporarily unavailable. HTTP Error 404 - File or Directory not found.
This error is caused by a security feature in Windows 2003 Internet Information Services (IIS). This
security feature does not allow unknown cgi file extensions.
To resolve this problem, add a new file extension in IIS for the cognos.cgi file. For more information,
see the IIS documentation.

The Page Is Not Shown When Opening a Portal After Installing IBM Cognos 8
After you install and configure IBM Cognos 8, you are unable to connect to the IBM Cognos 8
portal.
This may be because the Web server is not properly configured. For example, the virtual directories
required for IBM Cognos 8 may not exist or they may point to the wrong physical folders.
For information about configuring the Web server, see the Installation and Configuration Guide.

DPR-ERR-2058 Error Appears in Web Browser When Starting IBM Cognos 8

After you start the services in IBM Cognos Configuration and then try to open the portal, a message
similar to one of the following may appear:
DPR-ERR-2058 The dispatcher encountered an error while servicing a request. XTS handler must
be initialized before being invoked.
DPR-ERR-2058 The dispatcher cannot service the request at this time. The dispatcher is still ini-
tializing. Please try again or contact your administrator.
These error messages usually occur when the dispatcher cannot communicate with Content Manager.
To help you determine the specific cause, look in the cogserver.log file in the c8_location/logs
directory. The most common causes are listed below, with solutions.

IBM Cognos Services are Not Done Initializing

After you start the services in IBM Cognos Configuration and the configuration tool shows that
the services are running, wait a few minutes for all services to start before you open the portal.

Content Manager is Not Available

In a distributed installation, ensure that Content Manager is installed, configured, and running.
Ensure also that the other IBM Cognos computers are configured with the correct Content Manager
URI.

The Content Store is Not Available or is Not Configured Properly

Ensure that the content store database was created and that you configured it correctly in IBM
Cognos Configuration.

Installation and Configuration Guide 317

Appendix B: Troubleshooting

Tables are Not Created in the Content Store

Ensure that you are using a version of DB2, Microsoft SQL Server, Oracle, or Sybase that is sup-
ported by IBM Cognos components.

The Logon Credentials for the Content Store Are Incorrect

Check whether the information changed. For example, DB2 reads information from the NT user
management. If the password for the NT account changed, you must also change the logon credentials
for the content store in IBM Cognos Configuration.
Check for special characters in the logon password. Occasionally, the JDBC driver does not accept
characters that are reserved for xml, such as %, !, <, and >.

The User Does not Have Appropriate Permissions

Ensure that the user has the appropriate permissions.

Out of Memory on HP-UX

If you are using Tomcat, you can determine the issue is related to HP-UX server configuration. You
may be exceeding the expected maximum number of simultaneously active threads per process.

Steps to Check for an HP-UX Configuration Problem

1. In the /bin/startup.sh file, find
../tomcat4.1.27/bin/catalina.sh start "$@"

2. Change it to the following:

../tomcat4.1.27/bin/catalina.sh run "$@"
The run command causes the Tomcat output to appear in the console window for IBM Cognos 8.

3. Stop and restart IBM Cognos 8 using the ./shutdown.sh and ./startup.sh commands.
If the following error message appears in the console window for any of the application servers,
the issue is an HP-UX configuration problem:
OutofMemoryException error: Unable to create new native thread on HP-UX.
The problem is that the default values for HP-UX 11.0 and 11i are set too low for most Java
applications.

Tip: You can check the number of threads in your process by using the -eprof option available
in JDK 1.1.8 and by analyzing the Java.eprof file using HPjmeter by selecting the threads metric.

Steps to Increase the maximum Number of Threads Per Process

1. Have your system administrator change the Kernel parameter as follows:
● max_thread_proc = 512

● nkthread = 1024

2. Ensure that the ulimit settings are unlimited.

318 PowerPlay®
 Appendix B: Troubleshooting

Content Manager Cannot Connect to the Content Store on Oracle

If you are using an Oracle database as a content store, the DPR-ERR-2058 error may be generated
when logging onto the portal http://host_name/cognos8. All tables are created on the database.
You may also receive the following error messages:
● CM-CFG-5036 Content Manager failed to connect to the content store.

● ORA-01017: invalid username/password; logon denied

Steps to Set the Oracle Database Server Name

1. In the Explorer window, click Data Access, Content Manager, Content Store.

2. Change the Oracle database server name to a fully qualified name such as host_name.company-
name:1534 to match the name in the tnsnames.ora file.

Migration Does Not Work

After installing and configuring IBM Cognos 8 PowerPlay, you either cannot find the Migration
Assistant or you run a migration and nothing happens.
To resolve the problem, check the following:
● The components PowerPlay BI Server and PowerPlay Administration are installed on the IBM
Cognos 8 PowerPlay server (p. 112).

● If you install IBM Cognos 8 PowerPlay with IBM Cognos 8, install the IBM Cognos 8 PowerPlay
Content Manager component on the same computer as the IBM Cognos 8 Content Manager
component.

● On the computer where Content Manager is installed, in IBM Cognos Configuration , under
Environment, IBM Cognos 8 service, ensure the Migration service enabled property is set to
True.

● IBM Cognos Series 7 Migration Components are installed on your IBM Cognos Series 7
PowerPlay Server computer.

● The IBM Cognos Series 7 migration service is started on the IBM Cognos Series 7 PowerPlay
Server computer.

● Users are enabled to run a migration task. For more information, see the IBM Cognos 8
PowerPlay Migration and Administration Guide.
Additionally, ensure that the users who will be running migration tasks have the appropriate
permissions to create a migration task. In IBM Cognos Administration,

● click Configuration, Content Administration

● click the Set Properties - Administration button

● click the Permissions tab

● ensure that the users who will run migration tasks have Read, Write, Execute, and Traverse
permissions.

Installation and Configuration Guide 319

Appendix B: Troubleshooting

EBA-090034 Error When Starting WebLogic 8

After configuring WebLogic 8 to use SSL, you used the command startManagedWebLogic.cmd to
start the application server. The application server did not start and you received the following
error message:
EBA-0990034 Not listening for SSL
The problem occurred because WebLogic 8 has a feature that is incompatible with the IBM Cognos 8
bcprov-jdk14.134.jar file.
To resolve the problem, you must add a new version of the BouncyCastle bcprov .jar file to the
WebLogic Java extension directory.

Steps
1. From the BouncyCastle Web site, http://www.bouncycastle.org/download/, download a com-
patible BouncyCastle bcprov .jar file, such as bcprov-jdk14-137.jar.

2. Copy the downloaded .jar file to the WebLogic Java extension directory, WebLogic_loca-
tion\jdk142_nn\jre\lib\ext.

3. In the WebLogic_location\jdk142_nn\jre\lib\security directory, edit the java.security file and

add the following line to the provider list:
security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider

DPR-ERR-2022 Error Appears in Web Browser When Starting IBM Cognos 8

After you start the services in IBM Cognos Configuration and then try to open the portal, a message
similar to the following may appear:
DPR-ERR-2022 No response generated. This may be due to an incorrect configuration, a damaged
installation, or the dispatcher not having finished initializing.

Opening the Portal Too Soon

This problem can occur if you try to open the portal before IBM Cognos services are initialized.
To avoid this problem, after you start the services in IBM Cognos Configuration and the configur-
ation tool shows that the services are running, wait a few minutes for all services to start before
you open the portal.

The system.xml File Contains Errors

The system.xml file may have been edited.
Replace the system.xml file in the c8_location\templates\ps\portal directory with a copy from backup
or use an XML editor to edit it.

Unable to Download the cognos.xts File

After installing IBM Cognos 8, you are prompted to download the cognos.xts file when connecting
to the IBM Cognos 8 portal. The following error message may appear:
You have chosen to download a file from this location. cognos.xts from servername

320 PowerPlay®
 Appendix B: Troubleshooting

This problem occurs when the permissions on the virtual directories are not set properly. You must
provide the cgi-bin virtual directory in the Microsoft Internet Information Service (IIS) with execute
permissions.
To resolve this problem, recreate the virtual directories in IIS with the following permissions.

Alias Path Permissions

cognos8 c8_location\Program Files\ Read

Cognos\c8\webcontent

cognos8\ cgi-bin c8_location\Program Files\ Read Execute

Cognos\c8\cgi-bin

cognos8\help c8_location\Program Files\ Read

Cognos\c8\webcontent\
documentation

Application Server Startup Script Fails

You may have problems running the startup scripts for an application server to deploy the IBM
Cognos application if IBM Cognos 8 components are installed in a directory with a name that
includes spaces.
To resolve this problem, rename the directory and do not include spaces in the new name. If this
solution is not easily handled by the startup scripts, try adding quotation marks around the directory
name that includes spaces or use the 8.3 DOS naming convention.

Deploying IBM Cognos 8 to an Oracle Application Server or IBM WebSphere

Application Server Fails
Deploying IBM Cognos 8 to an Oracle application server or an IBM WebSphere application server
may fail with any of the following errors:
● Browser timeout in administration console

● Error Message: HTTP 500 Internal Error

● Error Message: Deployment failed: Base Exception: java.rmi.RemoteException (Oracle)

● Return to application file selection page (IBM WebSphere)

These errors can occur because the application file that you are trying to deploy is too large.
To solve this problem, do the following:

● If you are using the Build Application Wizard, clear the Include static files from the Webcontent
folder check box when you select the application to build.
This will reduce the size of the application file. If static content is required, you can manually
copy it to the deployed application location after you have successfully deployed IBM Cognos 8
into the application server.

Installation and Configuration Guide 321

Appendix B: Troubleshooting

● If you are deploying the application file manually for an Oracle application server, type the
following command:

dcmctl deployapplication -f path_and_name_of_ear_file -a application_name -co

OC4J_instance_name
This command is not supported for Oracle Release 3.

For more information about deploying IBM Cognos 8 to an application server, see the Installation
and Configuration Guide.

Microsoft Excel 2000 Multipage Report Type Does Not Work

To ensure that report URLs cannot be changed when passed from a client browser to the report
server, IBM Cognos 8 applies signatures to the URLs it generates. However, Excel 2000 multipage
(XLS) does not support signed URLs. To use the Excel 2000 multipage report type, you must disable
digital signing of the URLs by doing the following:

Steps to Disable Signed URLs

1. Stop the dispatcher.

2. In the c8_location/configuration directory, rename the cafconfig.xml.sample file to cafconfig.xml.

3. Open the cafconfig.xml and find the following section:

<!--Should we reject unsigned requests for /gd/ urls.
(e.g. multipage excel reports)
Default: true-->
<crn:parameter name="caf_signedReportUrls">
<crn:value xsi:type="xsd:boolean">true</crn:value>
</crn:parameter>

4. Change ="xsd:boolean">true</crn:value> to ="xsd:boolean">false</crn:value>.

5. Restart your dispatcher.

6. Repeat the above steps for every dispatcher in your environment, or copy the cafconfig.xml to
each c8_location/configuration directory and restart the dispatchers.

Unable to Deserialize Context Attribute Error When Deploying the p2pd.war File
to WebLogic
When you deploy the p2pd.war file to WebLogic, you may see the following error:
Error [context]Could not deserialize context attribute
java.io.NotSerializableException: com.cognos.logserver.LogService
This error does not affect the deployment of the p2pd.war file.
To avoid this problem, add at least one language preference in Internet Explorer.

322 PowerPlay®
 Appendix B: Troubleshooting

Accented or Double-Byte Characters May Not Display Correctly When Installing

IBM Cognos 8 on Linux
If you are using issetup under a UTF-8 locale, accented or double-byte characters may not display
correctly.
To resolve this problem when installing in German or French, use a non-UTF-8 locale and then
launch issetup to install IBM Cognos 8.
To resolve this problem when installing in Japanese, change the encoding setting of X Terminal to
Shift-JIS, and then install IBM Cognos 8 using an unattended installation (p. 283).

Problems Configuring IBM Cognos 8

After you install IBM Cognos 8 components, you may encounter problems when you save changes
in IBM Cognos Configuration.
Ensure that you
● configure and start the services on the computer where Content Manager is located before you
configure other components

● restart the IBM Cognos 8 service after you make any configuration changes

Run Database Cleanup Scripts

In some troubleshooting situations, you may be advised to start with new configuration data.
You can run an SQL script to delete all the tables in any of the following databases that IBM
Cognos 8 components use:
● content store for data that IBM Cognos 8 needs to operate

● delivery database for report notifications

● log database for log messages

● metric store for metric package content and Metric Studio user preferences

When you delete a table, its structural definition and data are deleted permanently from the database.
For the metric store, database objects may also be deleted.
When you restart the IBM Cognos 8 service, a new set of required database tables are created
automatically in the location specified by your configuration settings.

Steps
1. On each computer where Content Manager is located, stop the IBM Cognos 8 service.

2. Go to the appropriate directory:

● To delete tables from the log database, go to c8_location\configuration\schemas\logging.

● To delete tables from the content store, go to c8_location\configuration\schemas\content.

Installation and Configuration Guide 323

Appendix B: Troubleshooting

● To delete tables from the notification database, go to c8_location\configuration\schemas\

delivery.

● To delete tables from the metric store, go to c8_location\configuration\schemas\cmm.

3. Go to the appropriate database directory.

4. Depending on the database and database type, run one of the following scripts in the appropriate
database tool to delete the tables.

Database Database Type Script Name

Content store DB2 dbClean_db2.sql

Derby dbClean_derby.sql

Microsoft SQL Server dbClean_mssqlserver.sql

Oracle dbClean_oracle.sql

Sybase dbClean_sybase.sql

Notification DB2 NC_DROP_DB2.sql

Derby NC_DROP_Derby.sql

Microsoft SQL Server NC_DROP_MS.sql

Oracle NC_DROP_ORA.sql

Sybase NC_DROP_SYBASE.sql

Log DB2 LS_dbClean_db2.sql

Derby LS_dbClean_derby.sql

Microsoft SQL Server LS_dbClean_mssql.sql

Oracle LS_dbClean_oracle.sql

Sybase LS_dbClean_sybase.sql

Metric store DB2 cmm_purge_deleted_data

dbalias username password
Specify the dbalias only if a
database with the same
name is already cataloged.

324 PowerPlay®
 Appendix B: Troubleshooting

Database Database Type Script Name

Microsoft SQL cmm_purge_deleted_data

metric_store_name data-
base_name
Admin_user_name password

Oracle cmm_purge_deleted_data
database_name data-
base_user_name password
Replace database_name
with the name in the tns-
names.ora file that refers to
the database SID for Metric
Studio

5. Start the IBM Cognos 8 service.

Error Trying to Encrypt Information When Saving Your Configuration

When you save your configuration using the configuration tool, you may see an error message that
the cryptographic information cannot be encrypted. An error occurred when requesting a certificate
from the Certificate Authority.
The cryptographic information cannot be encrypted. Do you want to save the configuration in
plain text?
Before you can encrypt your configuration settings, the computer where Content Manager is installed
must be configured and running. On UNIX, ensure that you copied the appropriate .jar files to the
installation location of your Java Runtime Environment. In addition, ensure that your Java envir-
onment is configured correctly, the URIs are correct, and the same certificate authority password
is configured for all Content Manager computers.
On Linux, ensure that you copied the appropriate .jar files to the installation location of your Java
Runtime Environment.
Also, an error message similar to the following may appear:
java.lang.NoClassDefFoundError: javax/net/ServerSocketFactory.
The cryptographic error usually means the Java environment is not configured correctly. Ensure
that the JAVA_HOME environment variable is set correctly and the appropriate security providers
are installed, such as JSSE for JRE 1.31.

Steps to Check the Configuration

1. On the Content Manager computer, start IBM Cognos Configuration.

2. In the Explorer window, click Environment.

3. In the Properties window, verify these properties:

Installation and Configuration Guide 325

Appendix B: Troubleshooting

● Under Gateway Settings, Gateway URI

● Under Dispatcher Settings, External dispatcher URI and Internal dispatcher URI

● Under Other URI Settings, Dispatcher URI for external applications and Content Manager
URIs

4. In the Explorer window, click Security, Cryptography, Cognos.

5. In the Properties window, under Certificate Authority settings, click the value for Password.
Ensure that the same password is used on all Content Manager computers.

6. Save the configuration and restart IBM Cognos 8.

Problems Generating Cryptographic Keys in IBM Cognos Configuration

When you uninstall IBM Cognos 8, some temporary folders are left behind. Reinstalling the product
to the same location without first removing the temporary folders may cause problems while
attempting to generate the cryptographic keys in IBM Cognos Configuration.
To resolve this problem, uninstall IBM Cognos 8, remove the c8_location/temp/cam folder, and
install IBM Cognos 8 again.

CAM-CRP-1315 Error When Saving Configuration

When you save your configuration, you may receive the following error message:
CAM-CRP-1315 Current configuration points to a different Trust Domain than originally configured.
This error occurs when there has been a change to your environment’s trust domain. The trust
domain is managed by the Certificate Authority associated with the content store. This error can
occur if the content store you originally used has been removed or if you modified your configuration
to use a Content Manager associated with a different content store after you have saved your original
configuration.
To resolve the problem, change your configuration to use the original content store or regenerate
the cryptographic keys.

Steps to Regenerate Cryptographic Keys

1. On the Content Manager computer, back up the existing cryptographic keys by saving the
following directories to an alternate location that is secure:
● c8_location/configuration/csk

● c8_location/configuration/encryptkeypair

● c8_location/configuration/signkeypair

2. Delete the csk, encryptkeypair, and signkeypair directories.

3. In IBM Cognos Configuration, save the configuration and restart the services.

4. Repeat steps 1 to 3 on all computers that have IBM Cognos 8 components installed.

326 PowerPlay®
 Appendix B: Troubleshooting

Configuration Data is Locked by Another Instance of IBM Cognos Configuration

You may get an error message that the configuration data is locked by another instance of IBM
Cognos Configuration.
When you start IBM Cognos Configuration, it checks to see if the cogstartup.lock file exists in
c8_location/configuration. The file may exist if a previous instance did not shut down properly or
if another instance of IBM Cognos Configuration is running.
If another instance of IBM Cognos Configuration is running, you should exit that instance. Other-
wise, any changes you make to the local configuration may result in errors.
If no other instance of IBM Cognos Configuration is running, delete the cogstartup.lock file in
c8_location/configuration.

If the IBM Cognos 8 service is stopped, click Start.

Unable to Exit a Tab Sequence When Using Keyboard-only Navigation in IBM

Cognos Configuration
If you use the Tab key to navigate in IBM Cognos Configuration, you may experience problems
exiting a tab sequence. For example, in the Properties window, you can press the Tab key to move
from one property to another.
However, because IBM Cognos Configuration is a Java application, when you want to close the
Properties window, you must press Ctrl+Tab.

Unable to Save Your Configuration

You may be unable to save your configuration because you are missing a resource. For example,
you delete a resource such as the IBM Cognos namespace, a cryptographic provider, or the content
store. You can replace the default database type for the content store with Oracle, DB2, or Sybase.
You cannot replace the IBM Cognos namespace. You can recreate it, but you must then recreate
your IBM Cognos groups and roles.
For more information about creating groups and roles in IBM Cognos Connection, see the
Administration and Security Guide.

Steps to Recreate the IBM Cognos Namespace

1. Start IBM Cognos Configuration.

2. In the Explorer window, under Security, right-click Authentication and then click New resource,
Namespace.

3. In the Name box, type a name for the resource.

4. In the Type box, click IBM Cognos, and then click OK.

The IBM Cognos namespace appears in the Explorer window.

5. From the File menu, click Save.

Installation and Configuration Guide 327

Appendix B: Troubleshooting

Java Error When Starting IBM Cognos Configuration

When you start IBM Cognos Configuration, you may receive an error message that the Java Runtime
Environment (JRE) has changed and that the current cryptographic information is not compatible
with the new JRE. You may then be prompted to regenerate the cryptographic information for the
new JRE or exit to switch back to the previous JRE.
This error may occur for one of these reasons:
● Your configuration data was encrypted using a different JRE than the one IBM Cognos 8
components are currently using.

● The cryptographic information may have been corrupted.

If you click Regenerate in the error dialog, the IBM Cognos 8 service is stopped and the cryptographic
information is regenerated.

If you click Exit in the error dialog, you must set the JAVA_HOME environment variable to point
to the JRE that you used to save your configuration.
On Windows, if you want IBM Cognos 8 components to use the JRE that is installed by default,
unset JAVA_HOME or set JAVA_HOME to c8_location/bin/jre.

Note: If you want to change from one JRE to another, see the topic on changing the version of JVM
that IBM Cognos 8 components use. For more information, see the Installation and Configuration
Guide.

Cryptographic Error When Starting IBM Cognos Configuration

When you start IBM Cognos Configuration, the following error message may appear:
The cryptographic information may have been corrupted or the cogstartup.xml file is invalid. You
may have to fix this file or remove it from disk. For more information, see the Installation and
Configuration Guide.
This error occurs when IBM Cognos 8 components detect an error in the cogstartup.xml file. This
can occur when the cogstartup.xml file is manually edited and there is an error in the changed text.
To resolve the problem, replace the cogstartup.xml file with a copy from your backup location.

Current Configuration Settings Are Not Applied to Your Computer

You change default property values or add a resource to your installation in IBM Cognos Config-
uration. After saving the current configuration, you may not see the changes or be able to use the
resource in the run-time environment.
To apply the new settings to your computer, you must restart the IBM Cognos 8 service.

Steps to Restart the IBM Cognos 8 Service

1. Start IBM Cognos Configuration.

2. From the Actions menu, click the appropriate command:

● If the IBM Cognos 8 service is currently running, click Restart.

328 PowerPlay®
 Appendix B: Troubleshooting

This action starts all installed services that are not running and restarts services that are
running. If you want to restart a particular service, select the service node in the Explorer
window and then click Restart from the Actions menu.

● If the IBM Cognos 8 service is stopped, click Start.

This action starts all installed services that are not running. If you want to start a particular
service, select the service node in the Explorer window and then click Start from the Actions
menu.

CM-CFG-029 Error When Trying to Save a Configuration That Specifies a SQL

Server Data Source
In IBM Cognos Configuration, you try to save a configuration and the following error message
appears in the cogserver.log file:
CM-CFG-029 Content Manager is unable to determine whether the content store is initialized.
EXECUTE permission is denied on object "sp_tables", database "master", owner "dbo'.
This indicates that you do not have the correct permissions to initialize a content store or create a
table in the database.
The solution is to ensure that the content store user has permissions to use the sp_tables stored
procedure in the master database.

Users are Prompted for Active Directory Credentials

The single signon mechanism does not work when IBM Cognos 8 is configured as follows:
● Microsoft Internet Explorer runs on a Windows NT computer.

● The authentication namespace is configured with the Active Directory provider.

● Microsoft Internet Explorer on a Windows 2000 or Windows 2003 server is configured for
Integrated Windows Authentication.

As a result, users are prompted for their Active Directory credentials.

This problem occurs because the IBM Cognos 8 Active Directory provider uses ADSI protocol and
Kerberos delegation for authentication in a single signon environment. When Microsoft Internet
Explorer runs on Windows NT, it cannot authenticate to the IIS server using Kerberos delegation.
When your system is configured for Windows Integrated Authentication, for the single signon to
work with IIS, you must
● configure IBM Cognos 8 to communicate with the Active Directory server using the LDAP
provider.

● configure the external identity mapping property to read the REMOTE_USER environment
variable.

Font on UNIX Not Found When Starting IBM Cognos Configuration

When you start IBM Cognos Configuration, the following error message may appear:

Installation and Configuration Guide 329

Appendix B: Troubleshooting

Font specified in font.properties not found...

This is a common problem on UNIX. It means that the Java Virtual Machine (JVM) is trying to
use one or more fonts that are not installed on your computer. However, the JVM should use the
system default, and IBM Cognos Configuration should start and run normally.
To avoid these errors, add the missing fonts to your Java Runtime Environment by editing the
font.properties files. Several font.properties files, which contain standard font environment
information, are installed with your Java SDK. You can find these files in the JRE_location/lib
directory.
For more information, see the Java documentation.

Unable to Load DB2 OLAP Library in Framework Manager

You installed the DB2 OLAP 8.1 client and cannot load the DB2 OLAP library into Framework
Manager. You receive the following message:
DB2-ERR-0028 Unable to load the following DB2 OLAP library: "C:\ibm\db2olap\bin\essapin.dll"
IBM Cognos 8 is configured to use the DB2 OLAP library for Version 8.2. To resolve this problem,
you must edit the qfs_config.xml file and rename the library for Version 8.1.

Steps
1. In the c8_location\configuration directory, edit the qfs_config.xml file.

2. Find the following code:

<provider name="DB2OlapODP" libraryName="doodp82" connectionCode="DO"/>

3. Change the library name from doodp82 to doodp81 and save the changes.

Group Membership is Missing From Active Directory Namespace

If an Active Directory namespace is configured for the same forest and a user is authenticated using
a credential, the group membership will be missing.
The process identity of IBM Cognos 8, when running as a local system account or a domain user,
must have one of these privileges:
● impersonate a client after authentication

● act as part of the operating system

If the privilege is missing, there is no group membership for the authenticated user.
To solve this problem, perform the following steps.

Steps
1. From the Start menu, click Settings, Control Panel.

2. Click Administrative Tools, and then double-click Local Security Policy.

3. In the console tree, click Security Settings, Local Policies.

4. Click User Rights Assignment.

330 PowerPlay®
 Appendix B: Troubleshooting

5. Add the process identity of IBM Cognos 8 to one of the following policies:
● Impersonate a client after authentication
The default is Administrators, Service.
For more information, see http://technet2.microsoft.com/WindowsServer/en/Library/
fe1fb475-4bc8-484b-9828-a096262b54ca1033.mspx

● Act as part of the operating system

The default is Local system.
For more information, see http://technet2.microsoft.com/WindowsServer/en/Library/
ec4fd2bf-8f91-4122-8968-2213f96a95dc1033.mspx

Both of these privileges give an account the ability to act as another user.
The privilege Impersonate a client after authentication is similar to the Act as part of the
operating system privilege except that it will only allow a process to impersonate after
authentication, whereas the privilege Act as part of the operating system allows a process to
impersonate before authentication.
For more information, see http://www.microsoft.com/technet/prodtechnol/windowsserver2003/
technologies/security/tkerbdel.mspx

Deploying IBM Cognos 8 to an Oracle Application Server or IBM WebSphere

Application Server
You are deploying IBM Cognos 8 to an Oracle application server or an IBM WebSphere application
server and you receive the following errors:
● Browser timeout in administration console

● Error Message: HTTP 500 Internal Error

● Error Message: Deployment failed: Base Exception: java.rmi.RemoteException (Oracle)

● Return to application file selection page (IBM WebSphere)

This error can occur because the application file that you are trying to deploy is too large.
To solve this problem, on an Oracle application server, you can deploy the application file manually
using the following command:

dcmctl deployapplication -f <path and name of ear file> -a <application name> -co <OC4J instance
name>

For either IBM WebSphere or Oracle application servers, clear the Include static files from the
Webcontent folder option when you use the Build Application Wizard. Not including the static
content will reduce the size of the application file. If static content is required, you can manually
copy it to the deployed application location after you have successfully deployed IBM Cognos 8
into the application server.For more information about deploying IBM Cognos 8 to an application
server, see the Installation and Configuration Guide.

Installation and Configuration Guide 331

Appendix B: Troubleshooting

Errors Displayed Deploying to Oracle 10G Application Server

You are deploying IBM Cognos 8 to an Oracle 10G Application Server, and get the following error
messages:
CMM-APP-3254 The initialization of the metrics store failed. DIS-ERR-3115 Task execution failed.
MDS-RUN-3213 Unable to locate database bulk load utility. Please install the appropriate database
tool for this platform ('bcp' for SQL Server, 'sqlldr' for Oracle)
This occurs because the bulk loading utilities (SQL Loader on Oracle) are not included in the
deployment file created by IBM Cognos Configuration.
To resolve this error, you must use the Oracle client software on the computer where you installed
the Oracle 10G Application Server to install the missing components. Ensure that you install SQL
Loader.

CGI Timeout Error While Connected to IBM Cognos 8 Components Through a

Web Browser
When performing operations through your Web browser, you receive the following error message:
CGI Timeout, process will be deleted from server.
The error occurs when you use Windows Internet Information Services (IIS) as your Web server
and the gateway is configured to use CGI. IIS has a default timeout for CGI applications.
To resolve this problem, you can configure the gateway to use ISAPI. IIS does not have a default
timeout for ISAPI applications. Or, if you want to keep using a CGI gateway, you can increase the
CGI timeout in IIS.

Steps to Change the Gateway to ISAPI

1. On the gateway computer, start IBM Cognos Configuration.

2. Under Environment, for the Gateway URI property, change the cognos.cgi portion of the URI
to

cognosisapi.dll

3. In your Web browser, specify the ISAPI URI:

http://computer_name/cognos8/isapi

Steps to Increase the CGI Timeout

1. In the Windows administrative tools, open Internet Information Services.

2. Under the local computer node, right-click Websites and select Properties.

3. In the Home Directory tab, click Configuration.

4. In the Process Options tab, increase the CGI script timeout.

332 PowerPlay®
 Appendix B: Troubleshooting

Servlet Class Fails to Load in WebLogic

You may have problems when configuring a distributed server installation and using WebLogic as
the application server for IBM Cognos 8.
When deploying the p2pd.war for the Application Tier Components computer, you may receive
servlet exceptions and the dispatcher does not start. The cogserver.log is also not created.
The following error messages appear in the WebLogic Server console:
<Jul 9, 2004 3:47:37 PM EDT> <Error> <HTTP><BEA-101249> <[ServletContext
(id=19023494,name=p2pd,context-path=/p2pd)]:Servlet class com.cognos.pogo.isola-
tion.ServletWrapper for servletcfgss could not be loaded because the requested class was not found
in the classpath /host2/bea812/user_projects/domains/c8/applications/p2pd/WEB-INF/classes.
java.lang.ClassNotFoundException: com.cognos.pogo.isolation.ServletWrapper.>
<Jul 9, 2004 3:47:37 PM EDT> <Error> <HTTP> <BEA-101216> <Servlet: "cfgss" failed to preload
on startup in Web application: "p2pd".
javax.servlet.ServletException: [HTTP:101249][ServletContext(id=19023494,name=p2pd,context-
path=/p2pd)]: Servlet class com.cognos.pogo.isolation.ServletWrapperfor servlet cfgss could not be
loaded because the requested class was not found in the classpath /host2/bea812/user_projects/
domains/c8/applications/p2pd/WEB-INF/classes.java.lang.ClassNotFoundException:
com.cognos.pogo.isolation.ServletWrapper. at weblogic.servlet.internal.ServletStubImpl.prepareSer-
vlet (ServletStubImpl.java:799)
at weblogic.servlet.internal.WebAppServletContext.preload Servlet(WebAppServletCon-
text.java:3252)
To avoid this problem, do not deploy the p2pd application from the WebLogic applications directory.
Create the p2pd directory in another location and deploy p2pd from there.

Steps
1. Open IBM Cognos Configuration and configure the Application Tier Components computer.

2. Restart the Content Manager computer.

3. Create a p2pd directory in a location that is accessible by the WebLogic server but is not in the
WebLogic applications directory.
For example, create a directory named p2pd in the following location:
WebLogic_location/user_projects/domain_name

4. Create the p2pd.war file.

5. In the p2pd directory, extract the p2pd.war file to the WebLogic installation using the following
command:
%JAVA_HOME%/bin/jar xvfm "c8_location/p2pd.war" .

6. Start WebLogic.

7. In the WebLogic Server Console, deploy the p2pd application.

Installation and Configuration Guide 333

Appendix B: Troubleshooting

Desktop Icons or IBM Cognos Configuration Window Flicker on Windows

When you run IBM Cognos Configuration on Windows, you may notice that the desktop icons or
the IBM Cognos Configuration window flickers.
To resolve this issue, start IBM Cognos Configuration using the -noddraw command line option.

334 PowerPlay®
Glossary

access permissions
Rules defining the access rights to resources. Access permissions can be granted to any combination
of namespaces, groups, or users. Examples of resources are reports and folders.

alias
In modeling and database terminology, a secondary name for a database table. Aliases are used to
create a distinct reference to the table in the model, so that self-joins can be created or ambiguous
query paths can be resolved.
In map information technology, a secondary name for a map feature. Aliases are used to create a
reference between custom map feature names and feature names in databases.

anonymous access
A method of accessing resources in which users are not authenticated, and all users gain the same
access permissions.

application tier components

For installation, the processors that access the query databases to gather information and then
render the results as PDF and HTML reports and metrics. Application tier components also pass
requests to Content Manager and render the results that Content Manager retrieves from the content
store.

authentication
The process of verifying the identity of users when they log on. Users must be authenticated before
they can be authorized to use any secured resources.

authentication provider
The communication mechanism to an external authentication source. Functionality such as user
authentication, group membership, and namespace searches are made available through authentic-
ation providers.

certificate
A document that identifies someone or something by name. Certificates are issued by certification
authorities. Each IBM Cognos computer in a distributed installation uses a different certificate.
Certificates are used to positively identify an entity. They are used for digital signatures and secure
communications, and can be used for encryption or decryption.

cipher suite
In SSL, a set of authentication, encryption, and data integrity algorithms used for exchanging mes-
sages between network nodes. During an SSL handshake, the two nodes negotiate to see which
cipher suite to use when transmitting messages back and forth.

Installation and Configuration Guide 335

Glossary

common gateway interface

(CGI) A standard that describes how Web servers should access other programs to create a document
that will appear in a Web browser. For example, Web servers often use CGI programs to process
forms.

connection
The named information that defines the type of the data source, its physical location, and any signon
requirements. A data source can have more than one connection.

content locale
A code that is used to set the language or dialect used for browsers, report text, and so on; and the
regional preferences, such as formats for time, date, money, money expressions, and time of day.
For IBM Cognos products, you can specify a locale for the product interface (product locale) and
for the data in the report (content locale).

Content Manager
The IBM Cognos 8 service that manages the storage of customer applications, including application-
specific security, configuration data, models, metrics, reports, and report output. Content Manager
is needed to publish models, retrieve or store report specifications, manage scheduling information,
and manage the Cognos namespace.

content store
The database that contains data that IBM Cognos 8 needs to operate, such as report specifications,
published models, and the packages that contain them; connection information for data sources;
information about the external namespace, and the Cognos namespace itself; and information about
scheduling and bursting reports.
Design models and log files are not stored in the content store.
The IBM Cognos 8 service that uses the content store is named Content Manager.

credentials
Information stored about the identity of an IBM Cognos user, usually a user name and password.
You can assign your credentials to someone else so that they can use resources that you are
authorized to use.
Credentials are created for IBM Cognos components. If a user schedules or programs an action,
credentials must be stored in the content store.

data source
A relational database, dimensional cube, file, or other physical data store that can be accessed
through IBM Cognos 8.

deployment archive
A file used for deployment. A deployment archive contains the data from the content store that is
being moved.

336 PowerPlay®
 Glossary

gateway
An extension of a Web server program that transfers information from the Web server to another
server. Gateways are often CGI programs, but may follow other standards such as ISAPI and Apache
Modules.

glyph
An image of a character in a font.
Letters are glyphs, but in most cases, the term is used in discussions of non-alphabetic writing systems.

group
In security, a list of users or other groups that can be used to assign access permissions and capab-
ilities.
Groups can be referenced from other authentication sources or can be local to IBM Cognos 8. Local
groups are managed from the administration portal. The list of groups that an authentication user
is a member of is part of the user's passport for an IBM Cognos 8 session.
In reporting, grouping is the action of organizing common values of query item together and only
displaying the value once. Headers and footers often appear after each instance of a common value
in a grouped column

HTTPS
A secure version of HTTP Hypertext Transfer Protocol that incorporates secure sockets layer (SSL).
IBM Cognos products use HTTPS and SSL to encrypt and transmit passwords securely over the
Internet.

job
A group of runnable objects, such as reports, agents, and other jobs that you run and schedule as
a batch.

job step
The smallest part of a job that can be run separately. Usually, a job step is a report. A job step can
also be another job.

locale
A code that is used to set the language or dialect used for browsers, report text, and so on; and the
regional preferences, such as formats for time, date, money, and money expressions.
For IBM Cognos products, you can specify a locale for the product interface (product locale) and
for the data in the report (content locale).

metric store
A database that contains content for metric packages. A metric store also contains Metric Studio
settings, such as user preferences.

Installation and Configuration Guide 337

Glossary

namespace
For authentication and access control, a configured instance of an authentication provider. Allows
access to user and group information.
In XML, a collection of names, identified by a URI reference, which are used in XML documents
as element types and attribute names.
In Framework Manager, namespaces uniquely identify query items, query subjects, and so on. You
import different databases into separate namespaces to avoid duplicate names.

passport
Session-based information regarding authenticated users. A passport is created the first time a user
accesses IBM Cognos 8. It is retained until a session ends, either when the user logs off, or after a
specified period of inactivity.
Passport information is stored in Content Manager memory. Credentials are stored encrypted.
A passport is stored in a memory-only browser cookie for the duration of the session.

portlet
A mechanism for displaying Web content as part of a portal page.

product locale
The code or setting that specifies what language, regional settings, or both to use for parts of the
product interface, such as menu commands.

prompt
A report element that asks for parameter values before the report is run.

response file
An ASCII file that contains the setup data that is needed to automate an installation. For IBM
Cognos installations, the response file automates only the process of copying files with the default
configuration.

security provider
See authentication provider.

user
A person accessing an IBM Cognos 8 application. User information, such as the location of personal
folders or preferred formats for viewing reports, is stored in IBM Cognos 8.
Authenticated user definitions and information, such as passwords and IDs, are maintained in other
authentication sources.

338 PowerPlay®
Index

Apache Tomcat
A tuning, 292
accented characters Apache Web servers
not displayed properly, 323 configuring aliases, 81, 121
acceptCount configuring as gateways, 234
increasing for Apache Tomcat, 292 application pools, 81, 121
access application servers
configuring secure access to the portal, 80, 109 changing from the default, 255
access permissions configuring, 265
definition, 335 servlet class fails to load in WebLogic, 333
Active Directory Server servlet gateways, 238
advanced properties, 154 single signon for WebSphere Portal, 252
authenticating in multiple domains, 154 startup script fails, 321
enabling single signon, 155 startup scripts, 262
enabling SSL, 154 startup scripts for Oracle application server, 269
missing group membership, 330 Application servers
using for authentication, 151 startup scripts for Sun Java System application
with an LDAP namespace, 165 server, 271
active scripting application tier components
enabling in Web browsers, 42 configuration requirements, 24
additional fonts configuring, 111
installing, 146 definition, 335
administration installing on separate computer, 23
runtime settings, 68, 85, 95, 126 Application Tier Components
agent service, 290 log server, 215
AIX Architect models
environment variables to install IBM Cognos 8, 70, migration to IBM Cognos 8, 26
97, 112, 118 archiving
error connecting to DB2 database, 316 report output, 206
aliases audience of document, 11
configuring on Apache Web Server, 234 audit
configuring on Web servers, 81, 121 logs, 215
definition, 335 audit logs
anonymous access log destinations, 215
definition, 335 See Also log messages
disabling, 80, 109, 244 See Also troubleshooting
anonymous logon authentication
disabling, 150 Active Directory Server, 151
disabling for Portal Services, 244 configuring IBM Cognos Series 7 namespace, 157
Apache gateways custom authentication providers, 161
configuring, 234 custom properties for Active Directory Server, 153

Installation and Configuration Guide 339

Index

custom user properties for LDAP, 174 bookmark conversion utility, 19

definition, 335 builds
deleting namespaces, 185 running in IBM Cognos Connection by using Data
disabling anonymous logon, 150 Movement service, 29
domain trees for Active Directory Server, 154
eTrust Siteminder, 177, 179, 180 C
LDAP, 163, 164 CA, See certification authority
LDAP using Active Directory Server, 165 CAM-CRP-1157 error, 310
LDAP using IBM Directory Server, 168 certificates
LDAP using Novell Directory Server, 170 definition, 335
LDAP using Sun Java System Directory Server, 172 certificate signing requests
NTLM, 181 generating, 278
Portal Services, 244 certification authority
requirements for single signon with Microsoft Ana- configuring the service, 278
lysis Server or Microsoft SQL Server, 152 CGI gateway
SaferAPIGetTrustedSignon function, 159 limitations with multiple Content Manager com-
SAP, 182 puters, 95
single signon for NTLM, 182 CGI timeout error, 332
single signon for Plumtree Portal using HTTP Basic changing
authentication, 253 configuration template, 200
single signon using Active Directory Server, 155 default configuration settings, 187
single signon using eTrust SiteMinder, 180 email encoding, 231
single signon using IBM Cognos Series 7 IBM Cognos 8 gateway, 234
namespace, 158 Java versions, 275
single signon using LDAP, 176 URIs, 192
single signon using SAP, 185 characters
SSL for eTrust Siteminder, 180 encoding not supported, 311
SSL using LDAP, 175 characters improperly displayed, 323
testing namespaces, 185 chase_referral files, 154
trusted signon plug-ins for IBM Cognos Series 7, 159 chunking patches
using namespaces, 149 application servers, 256
authentication providers cipher suites
definition, 335 definition, 335
setting a priority for SSL connections, 213
B client component, 19
backing up Cognos Content Database
IBM Cognos 8 information, 257, 275 changing users and passwords, 188
backslashes appear instead of currency, 147 improving performance, 292
batch report service, 290 installing on a separate server, 100
Batch report service uninstalling, 90, 131
list of embedded fonts for PDF reports, 204 Cognos Viewer
BEA WebLogic, 255 component description, 17
Bind user DN and password property cogstartup.lock file, 306
special characters for LDAP namespace, 163 cogstartup.xml file, 296, 300
BMTScriptPlayer changing properties manually, 298
availability on Linux, 31 invalid file, 328

340 PowerPlay®
 Index

collation sequence, 35 running from command line, 300

collation sequences settings for IBM Cognos 8, 33, 187
case-sensitive, 311 settings not applied, 328
common gateway interface Tomcat settings, 33
replacing, 234 unable to open IBM Cognos Configuration, 306
common gateway interface (CGI) unable to save, 327
definition, 335 unattended, 283, 286
common symmetric key, 194 upgrade considerations, 62
components, 17 configuration files
application tier components, 23, 24 applications.xml for Portal Services, 243
bookmark conversion utility, 19 coglocale.xml, 299
Cognos Viewer, 17 cogstartup.xml, 296
Content Manager, 18, 24, 69 exporting, 286
content store, 20 configuration issues, 323
data sources, 20 configuring
gateways, 18, 22, 69 Active Directory namespace, 152
IBM Cognos 8 samples, 18 application server properties, 265
IBM Cognos Administration, 17 application tier components, 111
IBM Cognos Configuration, 18 certificate authority service, 278
IBM Cognos Connection, 17 Content Manager computers, 95
installing, 69 custom authentication providers, 161
installing on one computer, 22 default time zone, 231
Migration Assistant, 19 destination for log messages, 215
Migration Service, 19 distributed installations, 93
Open with Analysis Studio, 19 environment properties for application tier compon-
Open with Report Studio, 19 ents, 116
PowerPlay Studio, 18 eTrust SiteMinder namespace, 179
third-party, 17 fonts, 201
Confidentiality algorithm, 196 gateways, 124
configuration IBM Cognos 8, 44
adding resources, 296 IBM Cognos 8 for application servers, 260
advanced options, 275 IBM Cognos 8 service, 200
automating, 283 LDAP namespace, 164
backing up, 257, 275 LDAP namespace for Active Directory Server, 165
changing defaults settings, 187 LDAP namespace for IBM Directory Server, 168
changing the template, 200 login for IBM Cognos 8 service on multiple Power-
Content Manager, 24 Play computers, 208
cryptographic information cannot be encrypted, 325 mail server, 78, 106
data locked, 327 notification databases, 191
default settings, 187 NTLM namespace, 181
error when encrypting information, 325 Portal Services, 243
global settings, 225 properties in an unattended configuration, 298
lock file, 306 required tasks, 93
manual, 295 routers, 234
requirements for single signon with Microsoft Ana- SAP namespace, 184
lysis Server or Microsoft SQL Server, 152 shared trust with other servers, 212

Installation and Configuration Guide 341

Index

SSL protocol, 209 creating on Oracle, 38

standby Content Manager, 107 DB2 JDBC drivers, 13, 73
temporary file location, 198 definition, 336
transfer specification files (.ats), 283 deleting tables from the database, 323
unattended, 286 deploying, 54
Web browsers, 42 importing data, 273, 278
Web server, 81, 121 invalid settings, 311
connections new default in version 8.4, 15
definition, 336 requirements for changing application server, 256
console mode support for DB2 on z/OS for version 8.4, 14
for installing on UNIX and Linux, 16 context attribute cannot be deserialized, 322
content expiry context error, 322
images directory, 81, 121 conversion
content locale of bookmarks from IBM Cognos Series 7 to IBM
definition, 336 Cognos 8 PowerPlay, 19
content locales of ppr reports to ppx reports, 19
customizing, 227 cookies
mapping to user locale, 228 customizing, 233
Content Manager enabling in Web browsers, 42
an attempt to register the dispatcher, 316 settings, 233
changing time zones, 231 copyright material
component, 24 printing, 12
component description, 18 creating
configuration, 24 content store, 67
configuring, 95 credentials
configuring on multiple computers, 107 definition, 336
default active, 95 cross-script checking
definition, 336 configuring in IBM Cognos Application Fire-
failover protection, 24 wall, 196
installation options, 24 cryptographic error, 328
installing, 69 cogstartup.xml file invalid, 328
log server, 215 JRE error, 328
requirements for changing application server, 256 problems after upgrading, 326
requirements if using IBM Cognos 8 Transformer cryptographic information cannot be encrypted, 325
with Series 7 namespace, 69, 157 cryptographic keys
setting up a content store, 35, 208 backing up and deleting, 257, 275
standby, 24 generating for third-party certificate authorities, 278
Content Manager service, 290 regenerating, 326
Content Manager URIs, 107, 116 cubes, See PowerCubes
content store cube settings, 68, 85, 95, 126
and other locations to store report output, 205 currency
backing up, 257, 275 customizing support, 226
compatible versions of DB2 and Java, 310 fonts required for Yen or Won character, 146
component description, 20 won, 147
connection management, 76, 103 yen, 147
creating, 35, 67, 208 custom authentication providers, 161

342 PowerPlay®
 Index

custom user properties DB2 OLAP

Active Directory Server, 153 unable to load library, 330
LDAP, 174 delivery
decreasing the time to open reports, 293
D delivery service, 290
data deploying
importing, 58 configuration objects, 57
locked by IBM Cognos Configuration, 327 content store, 54
sharing data locations in a network, 207 directory content, 54
database client exporting, 55
setting up for a logging database, 218 failure on Oracle or WebSphere Application
database connections, See data source connections Server, 321
database connection strings IBM Cognos 8, 331
IBM DB2, 76, 103 importing, 58
Microsoft SQL Server, 76, 103 moving archives, 57
Oracle, 76, 103 packages, 54
Sybase, 76 partial deployment, 54
database connectivity Public Folders, 54
content store, 74 testing, 59, 60
databases deploying IBM Cognos 8, 265
bulk load utility missing, 332 deployment
content store, 35, 208 permissions, 54
deleting tables, 323 planning, 53
logging, 221 deployment archives
logging database client, 218 definition, 336
notification, 78, 106 moving, 57
Data files location Deployment files location
configuring for Windows Vista, 240 configuring for Windows Vista, 240
data integration service, 290 deployments
Data Manager creating an export specification, 55
using in IBM Cognos 8 BI, 29 Derby
Data Movement service page cache size, 292
using in IBM Cognos Connection, 29 description of product, 11
data source connections diagnostics, See troubleshooting
setting, 76, 103 differences
data sources between IBM Cognos Series 7 PowerPlay and IBM
component description, 20 Cognos 8 PowerPlay, 11
definition, 336 directories
DB2 deploying content, 54
JDBC drivers, 13, 73 directory not found error, 317
supported Java versions, 310 disabling
DB2 content store, 291 anonymous access, 80, 109, 244
DB2-ERR-0028, 330 dispatcher
db2java.zip changing properties file, 264
deprecated in version 8.4, 16 does not start on Application Tier Components
computer, 333

Installation and Configuration Guide 343

Index

unregistering, 273 error messages

dispatchers CAM-CRP-1064, 315
importing, 57 CAM-CRP-1315 Current configuration points to a
system metrics, 289 different trust domain, 326
distributed installation CFG-ERR-0106 IBM Cognos Configuration received
configuring user login for IBM Cognos 8 service on no response, 308
multiple computers, 208 CGI timeout, 332
distributed installations CM-CFG-029 Content Manager is unable to
configuring, 93 determine, 329
scenarios, 21 CMM-APP-3254 The initialization of the metrics
documentation store failed, 332
translated files, 15 corrupt cryptographic information, 328
domains could not deserialize context attribute, 322
Active Directory Server domain trees, 154 cryptographic information cannot be encrypted, 325
setting for cookies, 233 DIS-ERR-3115 Task execution failed, 332
double-byte characters download of specified resource fails, 316
improperly displayed, 323 DPR-ERR-2022 No response generated, 320
download of resource fails, 316 DPR-ERR-2058, 316, 317
DPR-DPR-1035 error, 310 HTTP Error 404, 317
Java Runtime Environment, 328
E MDS-RUN-3213 Unable to locate database bulk
EAR files, See Enterprise archive files load utility, 332
EBA-090034 Error page not found, 317
on WebLogic 8, 320 PRS-CSE-1255, 315
email messages servlet class fails to load on WebLogic, 333
changing the encoding, 231 SoapSocketException, 316
embedded fonts, 204 SQL1224N, 316
enabling you have chosen to download a file, 320
IBM Cognos Application Firewall, 196 errors
services, 199 DB2-ERR-0028, 330
SSL for an application server, 272 eTrust SiteMinder
encryption configuring namespaces, 179
changing settings in unattended configuration, 298 cross-script checking in IBM Cognos Application
configuration errors, 325 Firewall, 196
Enterprise archive files enabling single signon, 180
deploying IBM Cognos 8, 301 protecting the IBM Cognos 8 Web alias, 180
environments SSL, 180
supported, 31 using for authentication, 177
environment variables event logs, 221
configuring for application tier components, 116 event management service, 290
content store, 35 Excel
requirements on Windows Vista, 240 multipage report type does not work, 322
setting for application servers, 259 exporting
to install IBM Cognos 8 on UNIX or Linux, 70, 97, configuration files, 286
112, 118 creating a specification, 55

344 PowerPlay®
 Index

external identity mapping property configuring for IBM Cognos 8, 234

editing for an LDAP namespace, 177 configuring to use a namespace, 199
External identity mapping property definition, 336
special characters for LDAP namespace, 163 installing, 69
installing on separate computer, 22
F glyphs
failover protection, 24 definition, 337
ISAPI gateway required for multiple Content Man- Great Outdoors samples, 18, 137
ager installation, 95 installing, 138
file locations groups
requirements on Windows Vista, 240 definition, 337
files missing membership in Active Directory Server, 330
not found, 317
file system H
to save copies of report output, 205 help
finding getting, 12
information, 12 histories
Firefox deployment, 59, 60
browser settings, 42 HP-UX
flicker, 334 environment variables to install IBM Cognos 8, 70,
folders 97, 112, 118
deploying public, 54 HTML cookies, See cookies
font embedding lists, 204 HTTP Basic authentication
fonts for single signon with Plumtree Portal, 253
changing for PDF reports, 204 HTTP Error 404, 317
changing the default, 204 HTTPS
configuring, 201 definition, 337
list of embedded fonts for PDF reports, 204
not found when starting IBM Cognos Configuration I
on UNIX, 329 IBM Cognos 8
requirements for support, 203 changing application servers, 255
Framework Manager components, 17
cryptographic error, 309 configuring, 44
unable to load DB2 OLAP library, 330 default settings, 67
uninstalling, 89, 130 deploying, 265
dispatchers, 291
G installation options, 21
gateway installing migration tool on Windows, 86, 127
log file, 306 service does not start, 310
recommended settings for Microsoft IIS, 332 services, 291
when to use ISAPI, 332 sharing components on same computer, 25
gateways system requirements, 32
adding in a network to decrease delivery times, 293 uninstalling, 88, 129, 136
component description, 18 IBM Cognos 8 Go! Search
configuration requirements, 23 using to search IBM Cognos 8 BI content, 29
configuring, 124

Installation and Configuration Guide 345

Index

IBM Cognos 8 PowerPlay IBM Cognos Planning - Contributor

installing, 69 data access in IBM Cognos 8, 27
troubleshooting installations, 305 IBM Cognos Portal Services
IBM Cognos 8 samples, 18 migration overview, 30
IBM Cognos 8 server IBM Cognos Query
fails to start, 310 duplication of functionality in IBM Cognos 8, 29
IBM Cognos 8 service IBM Cognos Resource Center, 12
configuring, 200 IBM CognosScript
server not available, 311 migration overview, 30
starting, 76, 102, 115, 123, 328 IBM Cognos Series 7
starting from IBM Cognos Configuration, 83 enabling single signon, 158
starting from the command line, 300 enabling SSL, 158
stopping from the command line, 300 migration to IBM Cognos 8, 25
IBM Cognos Administration trusted signon plug-ins, 159
component description, 17 using for authentication, 157
IBM Cognos Application Firewall IBM Cognos Series 7 PowerCubes
configuring, 196 requirements for successful language conversion, 28
IBM Cognos Configuration IBM Cognos Visualizer
component description, 18 duplication of functionality in IBM Cognos 8, 30
font not found error on UNIX, 329 IBM Cognos Web Services
invalid settings, 311 migration overview, 30
problems opening, 306 IBM DB2
problems saving a configuration, 323 creating connection strings, 76, 103
problems with keyboard navigation, 327 IBM Directory Server
starting, 76, 102, 115, 123 with an LDAP namespace, 168
trouble generating cryptographic keys after IBM WebSphere, 255
install, 326 IIS Web servers
unable to start, 327 single signon using Active Directory, 155
unattended mode, 286 images
IBM Cognos Connection content expiry, 81, 121
component description, 17 loading in Report Studio, 81, 121
unable to open, 317 importing
IBM Cognos Controller configurations, 57
data access in IBM Cognos 8, 28 data into target environment, 58
IBM Cognos Finance Impromptu catalogs and reports
data access in IBM Cognos 8, 28 migration to IBM Cognos 8, 26
IBM Cognos Go! Mobile Impromptu Web Reports
mobile reports, 29 migration to IBM Cognos 8, 26
IBM Cognos Metrics Manager information
upgrading to IBM Cognos 8, 62 finding, 12
IBM Cognos namespace installation
recreating, 327 checklist, 67
IBM Cognos NoticeCast modes, 68, 95
duplication of functionality in IBM Cognos 8, 30 options for Content Manager, 24
IBM Cognos Planning - Analyst unattended, 283
data access in IBM Cognos 8, 27

346 PowerPlay®
 Index

installation and configuration issues supported versions for DB2 content store, 310
cannot load DB2 OLAP library, 330 updating runtime environments, 73, 100, 115, 123,
installation directory 260, 277
requirements, 93 uses all of CPU, 310
installing JAVA_HOME
additional fonts, 146 setting, 328
Cognos Content Database separately, 100 java.lang.NoClassDefFoundError, 309
Great Outdoors samples, 138 Java Archive files, See jar file
IBM Cognos 8, 67, 283 Java error when starting configuration, 328
IBM Cognos 8 on Linux, 323 Java Runtime Environment
IBM Cognos 8 PowerPlay, 69 IBM JRE replaces Sun Java Runtime Environ-
Supplementary Languages Documentation, 145 ment, 15
unattended install, 283 Java scripts
using transfer specification file (.ats), 283 enabling in Web browsers, 42
using transfer specification files (.ats), 283 Java System Web Server
Integrated Windows Authentication configuring aliases, 81, 121
issues, 329 JDBC
interface database connectivity for content store, 74
customizing language support, 226 JDBC drivers, 13, 73
Internet Explorer db2java.zip deprecated in version 8.4, 16
browser settings, 42 setting up Oracle databases, 219
requirements to support Simplified Chinese, 203 jobs
invalid cogstartup.xml file, 328 definition, 337
invalid settings job service, 290
content store, 311 job steps
IBM Cognos Configuration, 311 definition, 337
IP address version, 239 JobStreams
IPv4, 239 running in IBM Cognos Connection by using Data
IPv6, 239 Movement service, 29
ISAPI JREs
accessing IBM Cognos 8, 234 updating, 73, 100, 115, 123, 260, 277
when to use for a gateway, 332 JVM
ISAPI gateway changing, 257, 275
required with multiple Content Manager com- copying security provider files, 73, 100, 115, 123,
puters, 95 260, 277
memory settings for Cognos Content Database, 292
J
Japanese currency, 147 K
Japanese Yen keyboard
font requirements, 146 navigation problems, 327
jar file, 73, 100, 115, 123 Korean currency, 147
error when starting configuration, 328 Korean Won
Java font requirements, 146
changing versions, 275
configuring servlet gateway for Java-compatible Web
servers, 238

Installation and Configuration Guide 347

Index

L transfer, 305
language transfer summary, 306
customizing for user interface, 226 uninstallation, 307
customizing locale content support, 227 logging
languages configuring, 221
new support in version 8.4, 13 database, 221
user interface and message files, 16 database client, 218
language support, 15 remote log servers, 221
latency using files, 221
improving, 293 logging database
LDAP support for DB2 on z/OS for version 8.4, 14
Active Direcetory Server, 165 logging databases
configuring a namespace, 164 creating, 35
custom properties, 174 logging in
editing the External identity mapping property, 177 hiding namespaces during, 162, 181
enabling single signon, 176 log messages
enabling SSL, 175 enabling for IBM Cognos Application Firewall, 196
IBM Directory Server, 168 log destinations, 215
Novell Directory Server, 170 remote log server, 215
Sun Java System Directory Server, 172 See Also audit logs
using for authentication, 163 See Also troubleshooting
Linux logs
characters not displayed properly, 323 message processing, 215
console-mode installation is deprecated, 16 service, 290
environment variables for IBM Cognos 8, 70, 97,
112, 118 M
log messages, 221 macro
starting and stopping the IBM Cognos 8 service, 300 converting ppr reports to ppx reports, 19
system requirements, 67 mail server
unsupported features and components, 31 configuring, 78, 106
load balancing, 44 maintenance
configuring mail server settings, 78, 106 improving system performance, 289
enabling and disabling services, 199 Map files location
setting, 23 configuring for Windows Vista, 240
locales maxProcessor
definition, 337 increasing for Apache Tomcat, 292
log database Metric Designer
deleting tables, 323 uninstalling, 89, 130
log destinations metrics
types of, 215 for servers, dispatchers, and services, 289
log files, 305 Metrics Manager service, 291
for gateway errors, 306 metric store
locale configuration, 306 failure, 332
run-time, 306 metric stores
silent mode, 307 definition, 337
startup configuration, 306

348 PowerPlay®
 Index

Microsoft definition, 337

security update affects memory, 310 deleting, 185
Microsoft Analysis Server hiding during login, 162, 181
namespace requirement, 152 IBM Cognos Series 7, 80
Microsoft Analysis Services requirements for Content Manager if using Trans-
single signon to MSAS data sources, 155 former with Series 7 namespace, 69, 157
Microsoft IIS Web servers testing, 185
recommended gateway settings, 332 Netegrity SiteMinder, See eTrust SiteMinder
Microsoft Office Netscape
report data service, 291 browser settings, 42
Microsoft Office Excel network access
multipage report type does not work, 322 sharing data locations, 207
Microsoft SQL Server network outage
creating connection strings, 76, 103 services fail to start, 316
namespace requirement, 152 no response generated, 320
migration notification database, 106
authentication requirements, 80 configuring, 191
failure to run, 319 creating, 190
from other IBM Cognos products to IBM Cognos deleting tables, 323
8, 25 settings for DB2 on z/OS, 190
Migration Assistant support for DB2 on z/OS for version 8.4, 14
component description, 19 tablespaces for DB2 on z/OS, 191
does not work, 319 Novell Directory Server
migration components, 18 with an LDAP namespace, 170
Migration service, 291 NTLM, 181
Migration Service configuring, 181
component description, 19 enabling single signon, 182
mobile devices NTLM, See Also Windows native security (NTLM)
using to access reports, 29
monitor service, 291 O
moving OLAP data sources
deployment archives, 57 members missing or inaccessible, 330
Moving from trial upgrade to production environ- Open with Analysis Studio
ment, 60 component description, 19
multi_domain_tree, 154 Open with Report Studio
component description, 19
N Oracle
namespace application server, 269
Active Directory Server missing group member- creating connections strings, 103
ship, 330 creating connection strings, 76
cannot log on, 315 database JDBC drivers, 219
recreating, 327 deployment errors, 332
namespaces Oracle application server, 255
authentication, 149 Oracle Application Server
configuring custom authentication providers, 161 deploying IBM Cognos 8, 331
configuring for a gateway, 199 IBM Cognos 8 deployment failure, 321

Installation and Configuration Guide 349

Index

P setting up the sample for IBM Cognos 8 Power-

p2pd.war file for WebLogic, 322 Play, 139
packages PowerPlay Administration, 319
deploying, 55 PowerPlay BI Server, 319
page cache size PowerPlay for Windows component, 19
Derby, 292 PowerPlay Studio
page not found error component description, 18
starting IBM Cognos 8 in Windows 2003, 317 presentation service, 291
passports Presentation service
definition, 338 requirements, 289
passwords printing copyright material, 12
changing for Cognos Content Database, 188 problems opening IBM Cognos Configuration, 306
changing in unattended configuration, 298 processing log messages, 215
paths product
setting for cookies, 233 name changes, 15
PDF fonts product locale
mapping to built-in PDF fonts for faster report definition, 338
printing, 202 product locales
performance mapping for user interface, 230
improving for Apache Tomcat, 292 prompts
permissions definition, 338
deployment, 54 properties
for users, groups, and roles, 68, 85, 95, 126 changing in unattended configuration, 298
planning an upgrade, 48 configuring for application server, 265
Plumtree Portal temporary file location, 198
single signon using HTTP Basic authentication, 253 properties file
single signon using SiteMinder, 253 for dispatcher, 264
portal protocol
configuring secure access for users, 80, 109 IP address, 239
errors in starting, 317, 320 Public Folders
portal problems deploying, 54
unable to open, 317 purpose of document, 11
Portal Services, 243
availability on Linux, 31 Q
disabling anonymous logon in IBM Cognos 8, 244 quality of protection in SSL connections, 213
specifying the applications.xml file, 243 query databases, 20
portlets quick tours
definition, 338 using, 12
ports
changing, 192 R
default configuration settings, 33 readme
ports already in use, 309 reviewing before you install, 31
PowerCubes recreating the IBM Cognos namespace, 327
access in IBM Cognos 8, 28 related documentation, 11
requirements for successful language conversion, 28 relational data sources
settings, 68, 85, 95, 126 members missing or inaccessible, 330

350 PowerPlay®
 Index

remote log servers, 221 samples, 18

configuring, 221 Great Outdoors, 137
report conversion installing, 138
from ppr to ppx format, 19 SAP
report data service, 291 application server, 255
report distribution enabling single signon, 185
on a network, 293 using for authentication, 182
ReportNet SAP BW
to IBM Cognos 8 upgrade file, 307 authorization settings for IBM Cognos 8 administrat-
upgrading, 62 ors, 184
upgrading to IBM Cognos 8, 62 authorization settings for IBM Cognos 8 users, 182
report output connectivity, 184
reusing, 206 screen flicker, 334
saving to a file system, 205 scripts
sharing with users outside Cognos 8, 205 to delete tables from databases, 323
reports searching IBM Cognos 8 BI content, 29
changing default font, 204 secure flag
customizing language support, 227 setting for cookies, 233
decreasing delivery time, 293 secure LDAP communication, 175
testing before an upgrade, 52 Secure Sockets Layer, See SSL protocol
Report service security
list of embedded fonts for PDF reports, 204 configuring secure access to the portal, 80, 109
requirements, 289 issues with Integrated Windows Authentication, 329
report services, 291 Portal Services, 244
report settings, 68, 85, 95, 126 settings for Web browsers, 32
Report Studio security provider files
loading images, 81, 121 copying to application server JVM, 73, 100, 115,
required tasks 123, 260, 277
configuring, 93 security providers
resources definition, 338
adding, 296 Series 7 PowerCubes
response.ats file, 283 requirements for successful language conversion, 28
response files server components, 17
definition, 338 servers
reviewing the readme before you install, 31 system metrics, 289
root directory server time zones
for saving report output outside IBM Cognos 8, 205 changing, 231
routers services
configuring, 234 adjusting to improve performance, 289
runtime administration, 68, 85, 95, 126 agent, 290
batch report, 290
S Content Manager, 290
SaferAPIGetTrustedSignon function data integration, 290
using for authentication, 159 delivery, 290
sample PowerCube enabling and disabling, 199
setting up, 139 event management, 290

Installation and Configuration Guide 351

Index

fail to start after network outage, 316 SAP namespace, 185

IBM Cognos 8, 291 using IBM Cognos Series 7 namespace, 158
job, 290 using shared secret for Portal Services, 245
log, 290 SiteMinder
Metrics Manager, 291 single signon for Plumtree Portal, 253
Migration, 291 Solaris
migration service not working, 319 environment variables to install IBM Cognos 8, 70,
monitor, 291 97, 112, 118
presentation, 289, 291 special characters
report, 291 in LDAP namespace properties, 163
Report, 289 SSL
report data, 291 Active Directory Server, 154
setting the user account for shared network additional steps to configure on WebLogic 8, 320
access, 207 enabling for an application server, 272
starting, 76, 102, 115, 123 enabling on Web servers, 214
starting from the command line, 300 eTrust SiteMinder user directory, 180
stopping from the command line, 300 LDAP namespace, 175
system, 291 quality of protection, 213
system metrics, 289 setting up shared trust with other servers, 212
unable to start, 309 using IBM Cognos Series 7 namespace, 158
uninstalling, 88, 129, 136 SSL protocol
servlet gateway configuring, 209
configuring, 238 standby Content Manager, 24
setting configuring, 107
data source connections, 76 starting
shared secret IBM Cognos Configuration, 76, 102, 115, 123
single signon for Portal Services, 245 the IBM Cognos 8 service from IBM Cognos Config-
shared trust uration, 83
setting up between IBM Cognos 8 and other serv- starting the IBM Cognos 8 service
ers, 212 from the command line, 300
silent configurations, See unattended configurations startup
silent installations, See unattended installations configuration lock file, 306
silent mode, See unattended mode DB2 returns SQL1224N error when connecting from
silent uninstallation, 287 AIX, 316
Simplified Chinese download of resource fails, 316
requirements if using Internet Explorer 6, 203 IBM Cognos 8 service, 328
single signon page not found, 317
Active Directory namespace, 155 problems, 307
eTrust SiteMinder user directory, 180 script fails, 321
for Plumtree Portal using HTTP Basic authentica- unable to download cognos.xts, 320
tion, 253 unable to open IBM Cognos Connection, 317
for Plumtree Portal using SiteMinder, 253 unable to start service, 309
for WebSphere Portal using application server, 252 Startup
issues with Integrated Windows Authentication, 329 failure without error, 310
LDAP namespace, 176 startup scripts, See Also application servers
NTLM namespace, 182

352 PowerPlay®
 Index

stopping the IBM Cognos 8 service Tomcat

from the command line, 300 default configuration settings, 33
Sun Java Runtime Environment tuning, 292
replaced by IBM JRE, 15 transfer specification files (.ats)
Sun Java System configuration, 283
application server, 271 Transformer
Sun Java System Directory Server data access in IBM Cognos 8, 28
with an LDAP namespace, 172 requirements for Content Manager if using Series 7
Supplementary Languages Documentation namespace, 69, 157
installing, 145 uninstalling, 89, 130
new in version 8.4, 15 trial upgrade, 52
supported environments, 31 planning the move to the production environ-
Sybase ment, 60
creating connection strings, 76 troubleshooting, 305
database drivers, 75, 102 logging, 215
syslog trust domain error
destination for log messages, 221 when saving the configuration, 326
system requirements, 32 tuning
system service, 291 Apache Tomcat settings, 292
DB2 content store, 291
T
Tab key U
problems in IBM Cognos Configuration, 327 unable to open IBM Cognos Configuration, 306
tables unattended configuration
deleting from a database, 323 changing properties, 298
tablespaces, 291 unattended configurations
DB2 Notification Database on z/OS, 191 setting up, 283
template unattended installation, 287
changing the size of template, 200 unattended installations
temporary directories setting up, 283
deleting before reinstall, 326 unattended mode, 283
temporary file location uninstalling
configuring, 198 Cognos Content Database, 90, 131
properties, 198 Framework Manager, 89, 130
Temporary files location IBM Cognos 8, 88, 89, 129, 130, 136
configuring for Windows Vista, 240 Metric Designer, 89, 130
testing Transformer, 89, 130
deployment, 59, 60 unattended, 287
Thai email encoding UNIX
JRE requirements, 231 console-mode installation is deprecated, 16
third-party certificate authority environment variables for IBM Cognos 8, 70, 97,
configuring, 278 112, 118
third-party components, 20 font not found error, 329
time zones log messages, 221
changing, 231 starting and stopping the IBM Cognos 8 service, 300
system requirements, 67

Installation and Configuration Guide 353

Index

unregistering dispatchers, 273 W

unsupported characters, 311 WAR files, See Web archive files
updating Web aliases
java environment, 73, 100, 115, 123, 260, 277 IBM Cognos 8, 81, 121
upgrading Web archive files
create test environment, 53 deploying IBM Cognos 8, 301
from Metrics Manager, 47 Web browsers
from other IBM Cognos products to IBM Cognos configuring, 42
8, 25 errors in starting the Web portal, 320
from ReportNet, 47 errors when starting the web portal, 317
from Series 7, 47 security settings, 32
IBM Cognos 8, 62 WebLogic
planning the move from test to production environ- application server, 266, 271
ment, 60 could not deserialize context attribute, 322
preparation, 48 servlet class fails to load, 333
problems with cryptographic keys, 326 startup script, 262
process, 48 startup script fails, 321
ReportNet, 62 WebLogic 8
resources, 50 problem configuring SSL, 320
URI Web servers
changing, 192 configuring, 81, 121
default configuration settings, 33 enabling SSL, 214
user credentials servlet gateways, 238
changing in unattended configuration, 298 setting Report Studio load time, 81, 121
user interface single signon using Active Directory and IIS Web
customizing language support, 226 server, 155
mapping for product locale, 230 WebSphere
user locale application server, 265
mapping to content locale, 228 single signon using application server, 252
user logins WebSphere Application Server
configuring secure access to the portal, 80, 109 deploying IBM Cognos 8, 331
User lookup property IBM Cognos 8 deployment failure, 321
special characters for LDAP namespace, 163 startup script fails, 321
users Windows
changing for Cognos Content Database, 188 installing IBM Cognos 8 migration tool, 86, 127
definition, 338 system requirements, 67
UTF-8 Windows event log
encoding for email messages, 231 destination for log messages, 221
Windows IIS
V recommended gateway settings, 332
versions Windows integrated authentication, 155
supported ReportNet upgrades, 62 Windows native security (NTLM)
virtual directories enabling single signon, 182
IBM Cognos 8, 81, 121 using for authentication, 181
virtual servers Windows Vista
configuring for IBM Cognos 8, 81, 121 requirements for file locations, 240

354 PowerPlay®
 Index

won character, 147

Won character
font requirements, 146

Y
yen character, 147
Yen character
font requirements, 146

Installation and Configuration Guide 355