IBM Cognos Incentive Compensation Management (ICM)

Installation and Configuration Guide

Version 8.0

December 2012

This document contains confidential and proprietary information and is intended only for the person(s) to whom it is transmitted by
Varicent Software Inc, an IBM Company. Any reproduction of this document, in whole or in part, or the disclosure of any of the information
contained herein without the prior written consent of Varicent is prohibited. Varicent reserves any and all rights
to the information contained in this document. No warranites of any kind are contained in this document, and Varicent
shall not be held liable for any damages howsoever caused by reliance on or use of the information contained in this document.
Product Information
This document applies to IBM Cognos Incentive Compensation
Management (ICM) Version 7.3.0 and may also apply to subsequent
releases.

Copyright
Licensed Materials - Property of IBM Corp.

© Copyright IBM Corporation and other(s) 2005, 2012.

IBM, IBM logo, ibm.com, and Cognos are trademarks or registered

trademarks of International Business Machines Corp., registered in many
jurisdictions worldwide. A current list of IBM trademarks is available on
the Web at www.ibm.com/legal/copytrade.shtml. Java and all Java-based
trademarks and logos are trademarks or registered trademarks of Oracle
and/or its affiliates. Other product and service names might be
trademarks of IBM or other companies. This Program is licensed under
the terms of the license agreement accompanying the Program. This
license agreement may be either located in a Program directory folder or
library identified as "License" or "Non_IBM_License", if applicable, or
provided as a printed license agreement. Please read the agreement
carefully before using the Program. By using the Program you agree to
these terms.
Contents

Chapter 1: Admin Client Installation Preparation

Application Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Admin Client Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Application Server Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Installation Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
Pre-installation Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Microsoft SQL Database Permission Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Set Up IBM Cognos ICM as the Database Owner for Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . 14
Change the DEFAULT_SCHEMA Through SQL Server Management Studio . . . . . . . . . . . . . . . . . . . 14
Change the DEFAULT_SCHEMA Using a Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 2: Install the Admin Client and Service

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Install the Admin Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Install the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Set the IBM Cognos ICM Windows Service to Start Automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Edit the Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Edit the IBM Cognos ICM Configuration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Environments Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
AppSettings Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Edit the IBM Cognos ICM Service Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Configure Database Server Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Configure Access to Multiple Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Configure Service Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Change the Service Communication to HTTP or HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Configure IBM Cognos ICM Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Configure External Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Configure Email SSL Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Configure IBM Cognos ICM Mobile Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Mail Settings Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Set the Email Address of the IBM Cognos ICM Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Copyright © IBM Corporation and other(s) 2005, 2012 3

 Manage Portal Access Email Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Upgrade IBM Cognos ICM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Standard Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Upgrade Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
SQL Database Backup and Restoration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Upgrade the IBM Cognos ICM Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Upgrade Your IBM Cognos ICM Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Run Simultaneous Instances of IBM Cognos ICM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Edit the IBM Cognos ICM Windows Service Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Verifying the Installation of the Admin Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Test an Existing Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Test a New Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Integrate LDAP with the Admin Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Configure the IBM Cognos ICM Windows Service Configuration File for LDAP Authentication . . . . . . 43
Grant LDAP Users or LDAP Groups Access to the IBM Cognos ICM Client . . . . . . . . . . . . . . . . . . . . 44
Enable Data Tier Performance Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
CLR Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Enable Data Tier Performance Optimization in the Admin Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Chapter 3: Install and Use Admin Client Tools

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Console Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Install the Console Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Edit the ConsoleService.exe.config. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Start the Console Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
IBM Cognos ICM Windows Service Configuration File Encryption . . . . . . . . . . . . . . . . . . . . . . .48
Install the IBM Cognos ICM Configuration File Encrypter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Run the IBM Cognos ICM Configuration File Encrypter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
IBM Cognos ICM Model Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Install the Model Converter Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Convert a Model from SQL 2000 or 2005 to SQL 2008 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Convert a SQL Standard Model to a SQL Enterprise Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Convert a SQL 2005 Standard Edition model to SQL 2008 Enterprise Edition model . . . . . . . . . . . . . 51

Copyright © IBM Corporation and other(s) 2005, 2012 4

 Enterprise Size Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Using Certificates with IBM Cognos ICM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Required Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Generating Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Command-line Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Setting up Microsoft Management Console to use Digital Certificates . . . . . . . . . . . . . . . . . . . . . . . . . 56
Importing Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Import the necessary digital certificates contained in a PKCS #12 file . . . . . . . . . . . . . . . . . . . . . . 58
Identifying Server IP Address and Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Identify the IP Address of the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Identify an Unused Port Number on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Identifying the Server Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Identify the Server Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Configuring IBM Cognos ICM to use Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Configure the IBM Cognos ICM Client and the IBM Cognos ICM Windows Service to use Certificates
63
IBM Cognos ICM CLI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
IBM Cognos ICM CLI Pre-installation Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Install IBM Cognos ICM CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Configure IBM Cognos ICM CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Connecting to a Model Using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Executing Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Return Code from the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
IBM Cognos ICM API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
API Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
API Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
API Specifications - Processing and Calculation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
API Specifications - Data Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
API Specifications - Data Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Object Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
ColumnSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Earnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
EarningsDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
EarningsDetailsRow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Copyright © IBM Corporation and other(s) 2005, 2012 5

 Inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
InquiryComment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
NameValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
PayeeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
PeriodEarnings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
PeriodEarningsRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
PlanEarnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
PlanName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
PlanPosted. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
SignOff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
TableData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
TableDataRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
TableSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
WorkflowStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
DataRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
ColumnValuePair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
DataStore Object Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Exception Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
APIException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
InvalidArgumentException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
InvalidDataException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
RetiredEndpointException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
UserTypeException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
PermissionDeniedException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Microsoft Excel Add-in for IBM Cognos ICM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Service-side Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Set Up Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Modify the IBM Cognos ICM Windows Service Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . 86
Configure the Identity of the Server Hosting the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Identify the Server Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Client-side Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Required Software to Run the Excel Add-in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Install Office Primary Interop Assemblies Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Setup Certificates and Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Install the IBM Cognos ICM Microsoft Excel Add-in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Copyright © IBM Corporation and other(s) 2005, 2012 6

Chapter 4: Install and Configure the IBM Cognos ICM Web Client
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Installing the IBM Cognos ICM Web Client Using the Solaris Operating System . . . . . . . . . . . . . . . . . 92
Apache Tomcat Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Install and Configure Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Install and Configure Tomcat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Deploy the Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Configure Database Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Multi-language and Unicode Data Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
JBoss Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Install and Configure Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Install and Configure JBoss. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Configure Database Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Deploy the IBM Cognos ICM Web Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Multi-language and Unicode Data Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
WebSphere Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Download the IBM Cognos ICM Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Configure Database Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Start the Web Application Using the Admin Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Set a Web Container Custom Property on Websphere. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Multi-language and Unicode Data Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Property File Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Password Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
IBM Cognos ICM Web Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Configure IBM Cognos ICM Web Client in a Windows Environment . . . . . . . . . . . . . . . . . . . . . . . 108
Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Multi-language & Unicode Data Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Email Users when an Inquiry is Pending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
Prevent Presenter from Loading with a Large Amount of Data . . . . . . . . . . . . . . . . . . . . . . . . . 111
Changing the Appearance of the IBM Cognos ICM Web Client . . . . . . . . . . . . . . . . . . . . . . . .112
Tab Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Create a Web Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Move Web Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Copyright © IBM Corporation and other(s) 2005, 2012 7
 Edit a Web Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Delete a Web Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Add a Web Tab Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Remove a Web Tab From a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Set Access to Web Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Chapter 5: Authentication and Sign On

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
IBM Cognos ICM Communication Path Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
IBM Cognos ICM Admin Client to Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
IBM Cognos ICM Application Server to Database Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Web Client to IBM Cognos ICM Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
IBM Cognos ICM Web Application to Database Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Authentication Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
SiteMinder Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Configure the IBM Cognos ICM Web Client for CA SiteMinder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Accessing the IBM Cognos ICM Web Client with SiteMinder Configured . . . . . . . . . . . . . . . . . . . 121
OpenSSO Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
How it Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Download and Install OpenSSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
OpenSSO Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Identity Provider (IDP) Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Keystore Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Create and Configure IDP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Service Provider (SP) Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
First Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Endorsed Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Tomcat Version 6+ Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
IBM Cognos ICM Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Register IBM Cognos ICM as Service Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Verify the IBM Cognos ICM Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
LDAP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Validation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Copyright © IBM Corporation and other(s) 2005, 2012 8

 LDAP Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
ldap.properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Specifying Distinguished Names (Dn) in the ldap.properties File . . . . . . . . . . . . . . . . . . . . . . . . . 128
Web.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Chapter 6: Integration
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
Configuring the IBM Cognos ICM Web Client for Salesforce . . . . . . . . . . . . . . . . . . . . . . . . . .130
Accessing IBM Cognos ICM from Salesforce.com . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Integrate the IBM Cognos ICM Web Client with Oracle CRM . . . . . . . . . . . . . . . . . . . . . . . . . .134
Admin Client Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Web Configuration Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Customizing the Appearance of IBM Cognos ICM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
IBM Cognos ICM Web Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Admin Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Integrating with IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
Configure the IBM Cognos ICM Web Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Configure Tomcat to Accept Proxied Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Configure IIS to Forward Requests to IBM Cognos ICM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Integration with IWA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Set up for Internet Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Set up for Firefox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Set up for Google Chrome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Create Kerberos Configuration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Configure the Service Principal Name and Keytab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Set up the IBM Cognos ICM Web Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152

Copyright © IBM Corporation and other(s) 2005, 2012 9

Chapter 1: Admin Client Installation Preparation

IBM Cognos Incentive Compensation Management (ICM) is a valuable tool that can be used to manage
payment for individuals receiving variable compensation, including the sales force, management, or
distribution channels.

IBM Cognos ICM enables organizations to design, manage, and automate the calculation of variable
payment for dozens of plans and thousands of employees simultaneously. The application includes
several context sensitive dialogs and wizards designed to guide you through performing tasks.

Application Overview
IBM Cognos ICM is a distributed N-Tier application. The following three applications make up the
integrated solution:

1. Admin Client

2. Application server

3. Database server (see Figure 1-1)

A number of different database servers are supported. Microsoft SQL Server (2005, 2008, or 2012) is the
most popular.

Admin Client Details

• Provides the model administrator with several administrative options, including new model
creation, table customization, data import, calculation, and multiple reporting modes
• Contained on each model administrator’s workstation
• Communicates with the server in a true distributed environment and uses a configuration file
to specify the location of the Application Server
• Communicates with the Application Server through an encrypted channel written in C# using
the Microsoft .NET framework

Application Server Details

• Application layer can be run as a process on one or more servers to provide scalability
Copyright © IBM Corporation and other(s) 2005, 2012 10
 Application Overview

• Contains the business logic for the model

• Houses the calculation engine for processing data
• Uses the data layer to communicate with the specified database
• Contains IBM Cognos ICM Scheduler, which schedules and executes business events
• Written in C# using the Microsoft .NET framework, which results in a highly stable product

FIGURE 1-1 Admin Client Overview

Copyright © IBM Corporation and other(s) 2005, 2012 11

 Installation Files

Installation Files
The IBM Cognos ICM application comes with several installation files. In order to use the application, you
must install the Admin Client on the administrator’s workstation and the IBM Cognos ICM Service needs to
be installed and running on the server. Tools, such as Model Upgrader, Model Converter, CLI, the Microsoft
Excel Add-in, and Configuration File Encrypter, can be installed but are not required for running the core
application (see Table 1-1). For more information on installing these tools, see “Install and Use Admin
Client Tools” .

All tools and components of the Admin Client must be on the same product version. If you are upgrading
the Admin Client and Service, all other IBM Cognos ICM tools used in conjunction with the core
administrative application need to upgraded as well.

TABLE 1. Installation Files

Application Components and

Tools Installation File Name Description
Admin Client ICM-client The Admin Client must be installed to run the
application.
IBM Cognos ICM Windows Service ICM-service The IBM Cognos ICM Windows Service (or
Console Service) must be installed and running
for the IBM Cognos ICM application to work
correctly.
Console Service ICM-console The Console Service can be run as an
alternative to the IBM Cognos ICM Windows
Service. It is not required if the IBM Cognos ICM
Windows Service is being used.
CLI (Command-Line Interface) ICM-cli The CLI installer needs to be run in order to use
the CLI tool. It is not required for the core IBM
Cognos ICM application.
Excel Add-in ICM-exceladdin The Excel Add-in installer needs to be run in
order to use the IBM Cognos ICM Microsoft
Excel Add-in tool. It is not required for the core
IBM Cognos ICM application.
Configuration File Encrypter ICM-encrypter The Config File Encrypter installer needs to be
run in order to use the Configuration File
Encryption tool. It is not required for the core IBM
Cognos ICM application.

Copyright © IBM Corporation and other(s) 2005, 2012 12

 Pre-installation Checklist

TABLE 1. Installation Files

Application Components and

Tools Installation File Name Description
Model Converter ICM-modelconverter The Model Converter installer needs to be run to
convert models to a different version of SQL. It is
only required for model conversion.
Model Upgrader ICM-modelupgrader The Model Upgrader tool needs to be installed to
upgrade your IBM Cognos ICM model to a newer
version of IBM Cognos ICM. If the Admin Client
and Service have been upgraded, existing
models also need to be upgrader to work on the
new version of the software.

Pre-installation Checklist
Before beginning the installation, make sure you have all of the following:
• IBM Cognos ICM installation files
• Microsoft .NET Framework 3.5 SP1 installed on both the server and client (can be
downloaded from www.microsoft.com/downloads)
• Java 6
• Administrator access to all machines involved
• Sufficient database user rights or be the database owner

Microsoft SQL Database Permission Requirements

When deploying IBM Cognos ICM on a Microsoft SQL Server, IBM Cognos ICM does not require
administrative access to the database server, but database ownership rights need to granted in order to
access your database. When installing a model, make sure that IBM Cognos ICM is set up as the database
owner (dbo).

If it is not possible to grant IBM Cognos ICM dbo rights, a user with the following minimum permission
requirements will need to be created:
• Connect
• Create Table
• Create View
• Execute
Copyright © IBM Corporation and other(s) 2005, 2012 13
 Microsoft SQL Database Permission Requirements

• Select
• Delete
• Insert
• Update
• View Database State

NOTE: Granting IBM Cognos ICM dbo rights is preferred.

Set Up IBM Cognos ICM as the Database Owner for Microsoft SQL Server
You must create a database user to be used by IBM Cognos ICM to access the database and then make
this user the database owner.

1. Create a database user (ICMDBUser) to be used by IBM Cognos ICM to access the database.

2. Log in to Microsoft SQL Server as an administrator.

3. Connect to the database used by IBM Cognos ICM (ICMDatabase).

4. Run the following script:

USE [ICMDatabase]
GO
IF EXISTS (SELECT * FROM dbo.sysusers WHERE name = N’ICMDBUser’)
EXEC dbo.sp_revokedbaccess N’ICMDBUser’;
GO
sp_changedbowner N’ICMDBUser’

5. If you are using SQL Server 2005, there are the following additional security options:
• ICMDBUser needs to have database creation rights to the ICMDatabase
• ICMDBUser must have the DEFAULT_SCHEMA property set to dbo. This can be done
either through the Microsoft SQL Server Management Studio or with a query.

Change the DEFAULT_SCHEMA Through SQL Server Management Studio

1. In Microsoft SQL Server Management Studio, expand the ICMDatabase folder.

2. Expand the Security folder

3. Expand the Users folder.

Copyright © IBM Corporation and other(s) 2005, 2012 14

 Microsoft SQL Database Permission Requirements

4. Right-click on the ICMDBUser and select Properties.

5. Type or select dbo in the Default Schema field (see Figure 1-2).

FIGURE 1-2 Change DEFAULT_SCHEMA

Change the DEFAULT_SCHEMA Using a Query

1. Connect to the ICMDatabase with a SQL client.

2. Log on with an administrator account.

3. Run the following query:

ALTER USER “ICMDBUser” WITH DEFAULT_SCHEMA dbo;

Copyright © IBM Corporation and other(s) 2005, 2012 15

Chapter 2: Install the Admin Client and Service

Overview
The Admin Client is required to run the IBM Cognos ICM application. In the Admin Client, authorized users
will be able to create models, customize tables, import data, create calculations, and report on results. In
order for the Admin Client to run properly, the Service (or Console Service) must be installed and running.

Install the Admin Client

The Admin Client must be installed in order to run the application. The Admin Client should be installed on
the administrator’s desktop.

NOTE: If you are upgrading IBM Cognos ICM, please see “Upgrade IBM Cognos
ICM”.

1. Double-click on the ICM-client.exe installation file located in your release folder.

2. Click Next on the installer welcome screen.

3. Specify the folder where the Admin Client files will be copied, and then click Next.

4. Specify the Start Menu folder for the Admin Client’s shortcuts, and then click Next.

5. Verify the data entered.

6. Click Install to begin installation (see Figure 2-1).

Copyright © IBM Corporation and other(s) 2005, 2012 16

 Install the Service

FIGURE 2-1 Install Admin Client

Install the Service

The IBM Cognos ICM Service must be installed and running on the server for the application to run
properly. The Service should be installed on the application server. You will need to have the IBM Cognos
ICM Windows Service or the Console Service installed and running to log in to the Admin Client.

NOTE: If you are upgrading IBM Cognos ICM, please see “Upgrade IBM Cognos
ICM”.

1. Double click on the ICM-service.exe installation file located in your release folder.

2. Select the Default installation option and click Next on the installer welcome screen.

3. Specify the folder where the Service files will be copied to, and then click Next.

Copyright © IBM Corporation and other(s) 2005, 2012 17

 Install the Service

4. Specify the Start Menu folder for the Service shortcuts, and then click Next.

5. Verify the data entered and click Install to begin the installation (see Figure 2-2).

FIGURE 2-2 Install Service

NOTE: By default, the IBM Cognos ICM Service startup type will be set to manual,
which means that the user will manually have to start the service each time they
wish to launch IBM Cognos ICM.

Set the IBM Cognos ICM Windows Service to Start Automatically

You can change the startup type of the Service from manual to automatic.

1. Go to Control Panel > Administrative Tools > Services.

2. Select IBM Cognos ICM Service from the Services panel.

Copyright © IBM Corporation and other(s) 2005, 2012 18

 Install the Service

3. Right-click and select Properties.

4. Select Automatic as the Startup type and click OK.

Edit the Configuration Files

When installing or upgrading IBM Cognos ICM, the following two files need to be edited:
• IBM Cognos ICM Client.exe.config on the administrator’s workstation
• IBM Cognos ICM Windows Service.exe.config on the application server

If you are upgrading an existing version of IBM Cognos ICM, we recommend that you save a copy of IBM
Cognos ICM Windows Service.exe.config and IBM Cognos ICM Client.exe.config to use for comparison
with the upgraded configuration files. Specifically, you will want to make sure that the application settings in
the new configuration files match the settings in the saved configuration file from the previous version.

NOTE: You can comment out lines in the configuration file (i.e. lines that you do not
wish to use) by adding <!-- to the beginning of those lines. If you are commenting
lines out, make sure that you comment out the entire section and not just the first
line of that section.

Edit the IBM Cognos ICM Configuration File

The IBM Cognos ICM configuration file (i.e., the IBM Cognos ICM Client.exe.config file) indicates how the
Admin Client will communicate with the application server. When installing IBM Cognos ICM, you will
replace all instances of “localhost” with the name or IP address of your application server. This change
should be made to the configuration file that is located in the same directory as IBM Cognos ICM
Client.exe (i.e., the folder specified during the second step of the Admin Client installation).

The following two configuration sections in the IBM Cognos ICM Client.exe.config file need to be edited:
• Environments
• appSettings

Environments Configuration
The Environments section allows you to specify the environment for your models (see Figure 2-3).

1. Edit the environment name. This can be any name you give to your environment, e.g.
Production, Development, or Quality Assurance.

Copyright © IBM Corporation and other(s) 2005, 2012 19

 Install the Service

2. Edit the serviceAddress. This indicates the port that the service is using. Each environment
needs to be configured to use a different port.

3. Edit the securityMode. This determines how communication is to be encrypted between the
Admin Client and IBM Cognos ICM Windows Service. The following three different settings are
available:
• Transport layer security mode - clients are unauthenticated by the Windows
communication framework. The server must provide a trusted certificate for
authentication.
• Windows security mode - clients and servers are authenticated via Kerberos using the
domain controller as a trusted third party. No certificates are required.
• Unprotected mode - all security is disabled.

NOTE: Security settings for both IBM Cognos ICM Windows Service (IBM Cognos
ICM Windows Service.exe.config) and Admin Client (IBM Cognos ICM
Client.exe.config) need to be configured to run on the same security mode. Update
both files accordingly.

FIGURE 2-3 Environments Configuration

AppSettings Configuration
The AllowMultipleInstances value in the IBM Cognos ICM Client.exe.config file determines whether
multiple models can be open simultaneously on one machine. Typically, users only need one Admin Client
instance to be open on a machine. Some clients, however, need to run the Admin Client on a terminal
server and have multiple Admin Clients (see Figure 2-4).

Copyright © IBM Corporation and other(s) 2005, 2012 20

 Install the Service

FIGURE 2-4 AppSettings Configuration

Edit the IBM Cognos ICM Service Configuration File

The Service configuration file (i.e., the IBM Cognos ICM Windows Service.exe.config file) indicates how
the application server will communicate with the database server. This change should be made to the file
that is in the same directory as IBM Cognos ICM Windows Service.exe.

Configure Database Server Settings

You must edit the <databaseServers> block to correspond with your database server. By default, the file is
set up for connection to a SQL Server 2005 database.

1. Open the IBM Cognos ICM Windows Service.exe.config file.

2. In the databaseServers section, do the following:

2.a Modify the databaseServer Name. This can be an arbitrary name, such as Super Server,
and is intended to identify and distinguish the database server. If your database is a SQL
Server 2000 named instance or if you are using a SQL Server 2005 database, the value
for the DB Server field should follow the following format:
SERVER_NAME\INSTANCE_NAME.

2.b Modify the User. This is the same as the database user. For SQLServers, IBM Cognos
ICM requires SQL Authentication or Windows Authentication in order to connect.
Therefore, you will need to connect using a local database user. If you are using
Windows Authentication, both the User and Password should remain blank.

2.c Type the Password. This is the password that corresponds to the database user.

2.d Modify the Address. This address points to the location of the database. The Address
should follow the following format: SERVER_NAME\INSTANCE_NAME. If SQL Server is
not using the default port 1433, you must add the port number to the server address field
(i.e. SEVER_NAME\INSTANCE_NAME, PORT_NUMBER).

2.e Modify the Type of database, e.g. SQLServer2005.

2.f For SQL Server 2000/2005, modify the DiskPath (SQL Server 2000/2005 only). This is
the location where databases will be created and stored.

Copyright © IBM Corporation and other(s) 2005, 2012 21

 Install the Service

2.g Modify the TimeoutSeconds. This is the number of seconds before a timeout occurs.
The database timeout default is 90 seconds. This is the minimum amount of time that
clients will need to wait before IBM Cognos ICM can warn of a network or server issue.
For models with very long calculation times, this time may be increased to avoid a
database timeout during calculation.

Configure Access to Multiple Databases

If you have multiple database servers, the IBM Cognos ICM Windows Service.exe.config file allows
multiple database sections to be configured. This allows users to access both Unicode and non-Unicode
SQL models with a single service. By default, there is only one section in the configuration file, but others
can be added (see Figure 2-5). All models contained on each database server configured in the service
configuration file will be accessible from the login screen.

1. Complete a <databaseServer> section for each of your servers.

FIGURE 2-5 Database Server Settings

NOTE: IBM Cognos ICM cannot run without a service. It is not possible to enter
database information in the IBM Cognos ICM Client.exe.config file in order to
bypass the service and access the database directly.

Copyright © IBM Corporation and other(s) 2005, 2012 22

 Install the Service

Configure Service Settings

After configuring database server settings, you can modify the following sections in the IBM Cognos ICM
Windows Service configuration file to suit your IBM Cognos ICM Windows Service requirements:

1. Modify the ServiceAddress and port to point to the server name and port where the IBM
Cognos ICM Windows Service is located and running, e.g. localhost:13105 (see Figure 2-6).

2. Modify the SecurityMode. This determines how communication is to be encrypted between

the client and service. The following three different settings are available:
• Transport layer security (TLS) mode: clients are unauthenticated by the Windows
communication framework. The server must provide a trusted certificate for
authentication.
• Windows security mode: clients and servers are authenticated via Kerberos using the
domain controller as a trusted third party. No certificates are required.
• Unprotected mode: all security is disabled.

NOTE: Security settings for both IBM Cognos ICM Windows Service (IBM Cognos
ICM Windows Service.exe.config) and IBM Cognos ICM Client (IBM Cognos ICM
Client.exe.config) need to be configured to run on the same security mode. Update
both files accordingly.

3. If you are using TLS mode, modify the ServiceCertificateName to the subject name of a
certificate stored in the Windows Personal Certificate Store to be used for authentication in the
IBM Cognos ICM Windows Service.

4. If you are using the IBM Cognos ICM API Service, modify the APIAddress and value to point
to the server name and port where the IBM Cognos ICM API service is located and running,
e.g. localhost:13115.

5. If you are using certificates with the IBM Cognos ICM API Service, modify the
APISecureAddress and value to the server name and port where the IBM Cognos ICM API
service is located, running securely, and requiring certificate authentication, e.g.
MobileAPI:13125.

6. If you are using certificates with the IBM Cognos ICM API Service, modify the
APICertificateName to the subject name of a certificate (CN) stored in the Windows Personal
Certificate Store to be used for authentication in the IBM Cognos ICM API service.

Copyright © IBM Corporation and other(s) 2005, 2012 23

 Install the Service

FIGURE 2-6 Service Settings

Change the Service Communication to HTTP or HTTPS

By default, TCP communication is used between the admin client and the IBM Cognos ICM Windows
service. The communication method can be changed to HTTP or HTTPS communication by editing

Copyright © IBM Corporation and other(s) 2005, 2012 24

 Install the Service

settings in the IBM Cognos ICM Windows service configuration file and IBM Cognos ICM client
configuration file.

1. In the IBM Cognos ICM Windows service configuration file, uncomment the HTTP
Communication mode section and comment out the TCP Communication mode section.

2. To use HTTP communication, change the SecurityMode to None.

3. To use HTTPS communication, change the SecurityMode to TLS.

3.a Change the HttpsDefaultUsername and HttpsDefaultPassword values to the

username and password used to authenticate the IBM Cognos ICM environment and
database.

4. Change the CommunicationMode and SecurityMode in the IBM Cognos ICM client
configuration file to the same values as those in the IBM Cognos ICM Windows service
configuration file.

4.a If you are using HTTPS communication, change the HttpsDefaultUsername and
HttpsDefaultPassword values in the IBM Cognos ICM client configuration file to the
same values as those in the IBM Cognos ICM Windows service configuration file.

NOTE: Security settings for both IBM Cognos ICM Windows Service (IBM Cognos
ICM Windows Service.exe.config) and Admin Client (IBM Cognos ICM
Client.exe.config) need to be configured to run on the same security mode. Update
both files accordingly.

Configure IBM Cognos ICM Settings

After configuring database access, you can configure settings for Scheduler and Task Manager in the IBM
Cognos ICM Windows Service configuration file.

NOTE: In order to run Scheduler, IBM Cognos ICM Windows Service must be run as
a Windows Service. Make sure that Scheduler and IBM Cognos ICM API Windows
Service are started before scheduling any process.

1. Edit the SchedulerUser and SchedulerPassword to match the UserID and Password of the
user given the Scheduler role in the Manage Users window in the Admin Client. If the
SchedulerUser and SchedulerPassword are not updated here after being changed in the
Admin Client, the scheduled processes will not run (see Figure 2-7).

Copyright © IBM Corporation and other(s) 2005, 2012 25

 Install the Service

FIGURE 2-7 IBM Cognos ICM Settings

2. You can modify the SchedulerRefreshSeconds to indicate how often Scheduler will update
to include any changes that the user has made in the Scheduler module.

3. You can modify the SchedulerLogPath to update the location of the Scheduler log. By
default, this log resides in the Service directory. The SchedulerLogPath will need to be
updated if IBM Cognos ICM Windows Service is not installed to the default directory.

4. You can modify the TaskManagerLogPath to update the location of the Task Manager log. By
default, this log resides in the Service directory. The TaskManagerLogPath will need to be
updated if IBM Cognos ICM Windows Service is not installed to the default directory

5. You can modify the SchedulerErrorEmail to point to the email address of the administrator
you want to be notified when Scheduler encounters a problem.

6. You can modify the SchedulerSuccessEmail to point to the email address of the
administrator you want to be notified when Scheduler runs successfully.

7. You can modify the SchedulerStopProcessesOnErrors to determine whether or not an error

on a scheduled task within a process will cause the whole process to be aborted. When this is
set to False, if one scheduled task generates an error, Scheduler will continue on with the rest
of the scheduled tasks in the process.

8. You can modify the AllowAnonymousModelCreation to determine whether or not

administrators can create new models. If this is set to False, new models cannot be created.

9. You can modify the Language to the language you want to be used in the Audit module logs
(see Figure 2-8). Setting the Language to EnglishUS will set the date format to MM/DD/YYYY.
Setting the Language to EnglishGB will set the date format to DD/MM/YYYY. To change the
language of the Admin Client, see “Test a New Model” .

Copyright © IBM Corporation and other(s) 2005, 2012 26

 Install the Service

FIGURE 2-8 Language Settings

10. You can uncomment and modify the Saved Import File Directory to point to the location
where IBM Cognos ICM will look for source files for any of its data imports. This setting has to
be determined before any imports can be saved within IBM Cognos ICM and needs to refer to
a directory on the same machine as the IBM Cognos ICM Windows Service (see Figure 2-9).

FIGURE 2-9 Saved Import File Directory

11. You can uncommment and modify the Saved Publisher File Directory to point to the location
where IBM Cognos ICM will place published files that have been scheduled for publishing via
Scheduler. This setting has to be determined before publishing can be scheduled and needs
to refer to a directory on the same machine as the IBM Cognos ICM Windows Service (see
Figure 2-10).

12. You can uncomment and modify the Saved Image File Directory to point to the location
where IBM Cognos ICM will look for image files to be used as header graphics for scheduled
PDF publishing. This setting has to refer to a directory on the same machine as the IBM
Cognos ICM Windows Service (see Figure 2-10).

FIGURE 2-10 Saved Publisher File & Image Directory

Configure External Tools

The External Tools section determines the items that can be used to schedule and run processes that exist
outside of IBM Cognos ICM. Any external tools that are to be scheduled by Scheduler will have to reside in
the External Tool Directory (see Figure 2-11).

1. Uncomment and modify the ExternalToolDirectory to point to the location where IBM Cognos
ICM will look for items used outside of IBM Cognos ICM.

Copyright © IBM Corporation and other(s) 2005, 2012 27

 Install the Service

2. You can modify the ExternalToolMaxRunTime to change the maximum run time Scheduler
will allot for the tool to run. Once that time is up, Scheduler will continue down the list of
actions to perform.

FIGURE 2-11 External Tools

Configure Email SSL Settings

If the server is configured to send emails, then the connection to the email server can be encrypted with
SSL.

1. Uncomment the line under Email SSL Settings (see Figure 2-12).

2. Set the EnableSSLForServerEmails entry to “true”.

FIGURE 2-12 Email SSL Settings

Configure IBM Cognos ICM Mobile Settings

1. To enable handheld device configuration in IBM Cognos ICM, set the EnableHandheld value
to “true” and uncomment the line.

2. You can modify the MobileDataSynchFrequency to indicate how frequently (in seconds) data
on a handheld device running IBM Cognos ICM Mobile will be synchronized with the data
accessible through the IBM Cognos ICM API service, e.g. “3600”.

Mail Settings Configuration

To use the Portal Access email reminder system, the mail settings must be configured (see Figure 2-13).
Your system administrator can provide you with details of your company’s mail server.

The IBM Cognos ICM Web application uses the email address/server entered in the IBM Cognos ICM
Windows Service configuration file for sending out emails from Scheduler, e.g. when a task fails for Portal
Access period posts or when an administrator forces the approval of a period.

Copyright © IBM Corporation and other(s) 2005, 2012 28

 Install the Service

The smtp from field will usually be set to the administrator’s email address. When Portal Access emails are
generated, they will be sent from the email address indicated here.

FIGURE 2-13 Setting up Email Address

Set the Email Address of the IBM Cognos ICM Administrator

The email address of the IBM Cognos ICM Administrator must be set in the Admin Client.

1. Log in to IBM Cognos ICM.

2. Select Admin > Manage Users.

3. Select the Administrator.

4. Click Edit.

5. Set the email address.

6. Click OK.

Manage Portal Access Email Settings

You can choose to email users about sign offs and/or inquiries. Emails to users when a sign off is pending
is initiated from the admin client, so email settings must be configured in the IBM Cognos ICM Windows
Service (or Console Service) configuration file. Emails to users when an inquiry is pending are initiated
from IBM Cognos ICM Web Client, so email setting must be configured in the mail.properties file.

1. To send emails to users when a sign off is pending, you must configure the email settings in
the IBM Cognos ICM Windows Service configuration file (see Figure 2-13). If you are using the
Console Service, the email setting must be configured in the Console Service configuration
file.

2. To send emails to users when an inquiry is pending, you must configure the email settings in
the mail.properties file (see Figure 2-14). The mail.properties file is located in the following
directory:
...\webapps\IBM Cognos ICM\WEB-INF
Copyright © IBM Corporation and other(s) 2005, 2012 29
 Upgrade IBM Cognos ICM

NOTE: You will need to reload the ICM.war file after making changes to the
configuration files.

FIGURE 2-14 Configure Email Settings in the mail.properties file

3. In the admin client, on the Home tab, select Admin > Administrative Options.

4. Under the Portal Access tab, select Email users when a sign off is pending and/or Email
users when an inquiry is pending.

5. Click OK.

Upgrade IBM Cognos ICM

The IBM Cognos ICM application can be upgraded to a newer version. There are two ways to upgrade;
perform a standard upgrade to replace the initial installation or install a new service to run parallel with the
initial installation.

Standard Upgrade
A standard upgrade will replace the existing version of IBM Cognos ICM with a new version of IBM Cognos
ICM. For example, if you upgrade from version 6 to version 7, version 6 will no longer be available on your
machine after the upgrade. Before the new version of IBM Cognos ICM can be installed, the pervious
version of IBM Cognos ICM must be removed. All tools and components in IBM Cognos ICM must be the
same version in order for IBM Cognos ICM to work properly. Therefore, even optional tools, such as the
IBM Cognos ICM Microsoft Excel Add-in and IBM Cognos ICM CLI, must be removed and replaced with
the newer version.

Upgrade Preparation
It is recommended that you back up any existing IBM Cognos ICM models before you upgrade (see “SQL
Database Backup and Restoration”). We recommend saving copies of your configuration files prior to
upgrading so that database and environment settings can be compared with the settings in the
configuration files in the upgraded version of IBM Cognos ICM. When you upgrade, the settings in the IBM

Copyright © IBM Corporation and other(s) 2005, 2012 30

 Upgrade IBM Cognos ICM

Cognos ICM Windows Service configuration file and the IBM Cognos ICM configuration file will need to be
manually updated (see “Edit the Configuration Files” ).

1. Back up files. If you are upgrading an existing version of IBM Cognos ICM, you will need to
back up the following files:
• IBM Cognos ICM Client.exe.config
• IBM Cognos ICM Windows Service.exe.config

NOTE: You cannot use your existing configuration files with an upgraded version.

2. From the Windows Control Panel, select Add and Remove Programs and uninstall the
current version of IBM Cognos ICM, the IBM Cognos ICM Application Server, the Admin
Client, and the Model Upgrader, as well as any other IBM Cognos ICM tools you may have
installed, such as the IBM Cognos ICM Microsoft Excel Add-in, IBM Cognos ICM CLI, and
Configuration File Encrypter.

3. Back up models.

SQL Database Backup and Restoration

A database backup duplicates all the data contained in the database and creates a copy of the full
database. You can then recreate the entire database in one step by using the restore command. The
restored database will be an exact match of the database at the time the backup completed.

To backup a database do the following:

1. Using SQL Server Enterprise Manager, select Backup Database from the Tools menu.

2. Select one of the following Backup Types:

• Complete backup: makes a full backup of your database. You will almost always need to
start your backup strategy with a full backup of your database.
• Differential backup: stores all changes that have occurred to the database since the last
full backup.

3. You can modify the backup file destination. By default, the backup file will be stored in the
following location: C:\Program Files\Microsoft SQL Server\MSSQL\BACKUP\.

NOTE: The database can remain online and accessible to users while the backup is
being made.

Restore a Database Backup

Copyright © IBM Corporation and other(s) 2005, 2012 31
 Upgrade IBM Cognos ICM

In the backup file, SQL Server stores the names and locations of the files used in the database. Upon
restoring the database, SQL Server recreates all the necessary files and the database is restored to the
point in time that the backup finished.

1. To restore a database, select Restore Database from the Tools menu.

2. The Restore as Database field is the name of your newly restored database. It does not have
to be identical to the name of the original (backed up) database.

3. Define your restoration parameters by selecting the original database name and the stored
backup you want to be restored.

Using Backup and Restore to Transfer Databases Between Servers

You can restore a backup of a database on a new server by creating a backup of a database and saving it
to a location that is accessible from the server where you will be performing the restoration.

1. From the server that you want the database transferred to, open Enterprise Manager.

2. Select Restore Database from the Tools menu.

3. Type the name you want the database to be restored with in the Restore as database field.

4. Select to restore the database From device.

5. Select File name and type the location of the backup file.

Upgrade the IBM Cognos ICM Application

Once you have performed the Upgrade Preparation steps above and uninstalled your current version of
IBM Cognos ICM, you are ready to install the new version.

1. Install the IBM Cognos ICM Client (see “Install the Admin Client”)

2. Install the IBM Cognos ICM Windows Service (see “Install the Service”).

3. Edit the IBM Cognos ICM Client.exe.config and IBM Cognos ICM Windows
Service.exe.config files to match the saved versions from the previous model.

4. Install any additional IBM Cognos ICM tools such as, IBM Cognos ICM CLI.

Upgrade Your IBM Cognos ICM Model

Once you have completed upgrading an existing version of IBM Cognos ICM, you will need to upgrade
your models to the new version as well. The IBM Cognos ICM Model Upgrader is a tool that allows IBM

Copyright © IBM Corporation and other(s) 2005, 2012 32

 Upgrade IBM Cognos ICM

Cognos ICM database models to be upgraded in order to be compatible with newer versions of IBM
Cognos ICM.

Upgrade options allow control over the upgrade process for SQL Server models and can reduce the size of
transaction log files on the SQL server.

NOTE: If you are completing a new installation of IBM Cognos ICM, you do not need
to upgrade models. Models only need to be upgraded when IBM Cognos ICM is
being upgraded.

Install Model Upgrader

The Model Upgrader tool is required to upgrade your IBM Cognos ICM model to be compatible with your
upgraded IBM Cognos ICM application.

NOTE: If you already have a previous version of Model Upgrader installed, make
sure you have removed the older Model Upgrader before installing the new one.

1. Double-click on the ICM-modelupgrader.exe installation file located in your release folder.

2. Click Next on the installer welcome screen.

3. Specify the folder where the IBM Cognos ICM Model Upgrader files will be copied to, and click
Next.

4. Verify the data and click Install to begin the installation.

Run Model Upgrader

1. In the same install directory, double-click on the ModelUpgrader.exe file. The IBM Cognos
ICM Model Upgrader tool will open.

2. Type the Server Name. This is the name of the database server containing your model. If your
database is a SQL Server 2000 named instance, or if you are using a SQL Server 2005
database, the value for the DBServer field should follow this format:
SERVER_NAME\INSTANCE_NAME

3. Select the Database Type from the dropdown menu. This is the type of database that you are
connecting to, such as SQL Server 2000 or SQL Server 2005.

4. Type in the Database Name. This is the name of the database containing your IBM Cognos
ICM model.

Copyright © IBM Corporation and other(s) 2005, 2012 33

 Upgrade IBM Cognos ICM

4.a If you do not know the Database Name, click Browse.

4.b Select a model (see Figure 2-15) and click OK.

FIGURE 2-15 Browse Models

NOTE: You will see the database version in brackets beside each model.

5. Type in the Database Timeout. The default is 90 seconds and probably does not need to
change. However, you should change it here if you have increased the default timeout in the
IBM Cognos ICM Windows Service configuration file.

6. Type your User ID and Password. This refers to the database user with database altering
permissions. This is not the same as the IBM Cognos ICM administrator password.

7. Click Upgrade (see Figure 2-16).

Copyright © IBM Corporation and other(s) 2005, 2012 34

 Upgrade IBM Cognos ICM

FIGURE 2-16 Model Upgrader

Model Upgrader Options

If you select the Options button when running Model Upgrader, you will be able to set error protection (see
Figure 2-17). The following error protection options are available:
• None - This option uses the least amount of resources but offers no protection for the model
should an error occur. If an error occurs during the upgrade process, the model being
upgraded will be unsalvagable and will need to be restored from a backup.

NOTE: A backup must be created prior to using this option.

Copyright © IBM Corporation and other(s) 2005, 2012 35

 Upgrade IBM Cognos ICM

• Partial - If a model fails to upgrade and the partial protection option is selected, it is possible
that the error can be resolved without restoring the original backup of the model. Also,
upgrades that fail may always safely be restarted when using this option. This option uses less
resources than the Complete option but more than the None option.

NOTE: A backup must be created prior to using this option.

• Major Release - If the upgrade should fail, this option will roll back the database to the last
successful database version that corresponds to a major release. Users can then install the
matching major IBM Cognos ICM release and make the necessary changes to the model to
allow it to upgrade. After the changes have been made, Model Upgrader can be safely run
again.

NOTE: Making a model backup is recommended prior to selecting this option.

• Complete - The complete protection level guarantees that your model will be usable no matter
what errors are encountered during the upgrade process. If, for some reason, your model
cannot be completely upgraded to the database version of your choice, your model will be left
unchanged. This is the safest option, but it is also the option that uses the most resources.

Copyright © IBM Corporation and other(s) 2005, 2012 36

 Upgrade IBM Cognos ICM

FIGURE 2-17 Error Protection

Target Database Version

The target database version is an integer indicating the specific database version you are upgrading to.
The database version is different from the software version, e.g. 6.0.4. While there is a particular database
version for every software version, there is not a software version for every database version.

A user may want to select a database version to control the level of error protection at different points
during the upgrade. Selecting a target version also allows the user to perform the upgrade in smaller
increments to avoid running out of disk space.

Copyright © IBM Corporation and other(s) 2005, 2012 37

 Upgrade IBM Cognos ICM

Run Simultaneous Instances of IBM Cognos ICM

Sometimes it is necessary to keep previous versions of IBM Cognos ICM running along with a new
version. To meet this requirement, IBM Cognos ICM allows multiple IBM Cognos ICM Windows Services
(including Schedulers) to be installed on one machine. When using this upgrade option, previously
installed services do not need to be uninstalled. You must stop the IBM Cognos ICM Windows Service,
Scheduler Service, and IBM Cognos ICM API before installing more IBM Cognos ICM Windows Services.

1. Double-click the ICM-service.exe file located in your release folder.

1.a Select Named Instance and specify an instance name for the new service. For example,
Service2.

NOTE: Instance names must be unique for all IBM Cognos ICM Windows Services,
regardless of version number.

1.b Specify a directory to save the new IBM Cognos ICM Windows Service in. The directory
name must be unique for each IBM Cognos ICM Windows Service installation. For
example, type C:\Program Files\IBM Cognos ICM\Service2.

1.c Specify a Start menu folder. The Start menu folder must be unique for each IBM Cognos
ICM Windows Service installation. For example, type IBM Cognos ICM\Service2.

1.d Click Install.

NOTE: If the installation is not successful, uninstall and re-install the IBM Cognos ICM
Windows Service.

2. Repeat the steps above for as many IBM Cognos ICM Windows Services as you want to
install.

3. Go to Control Panel > Administrative Tools > Services.

4. Scroll down in the Services window and find IBM Cognos ICM Windows Service. There
should be the same number of IBM Cognos ICM Windows Services, IBM Cognos ICM APIs,
and Schedulers as you installed in the above steps.

5. Right-click on the IBM Cognos ICM Windows Service, for example, IBM Cognos ICM
Windows Service (SERVICE2), and select Properties.

6. Make sure the Path to executable is correct and pointing to the new IBM Cognos ICM
Windows Service installation.

7. Repeat steps 6 and 7 for the other IBM Cognos ICM Windows Services you installed.

Copyright © IBM Corporation and other(s) 2005, 2012 38

 Verifying the Installation of the Admin Client

Edit the IBM Cognos ICM Windows Service Configuration Files

You will need to make some changes to the IBM Cognos ICM Windows Service configuration files to
indicate how the application server will communicate with the database server, add the service instances,
and configure each service to run on a different port.

1. Open a new Service folder. For example, open the Service2 folder.

2. Open the IBM Cognos ICM Windows Service.exe configuration file and edit the
databaseServer section.

3. Edit the <add key=”ServiceAddress” value=”localhost:13105”/> line so this service uses a

different port from the other services (see Figure 2-18). For example, change the line to <add
key=”ServiceAddress” value=”localhost:13106”/>.

FIGURE 2-18 Service Address

4. In the IBM Cognos ICM Windows Service instance name section, make sure the <add
key=”ServiceInstanceName” value=”myinstance”/> has been uncommented and the value
of the name of the Service instance has been updated (see Figure 2-19). For example, <add
key=”ServiceInstanceName” value=”Service2”/>.

FIGURE 2-19 Service Instance Name

5. Make any other the edits and changes required then save and close the IBM Cognos ICM
Windows Service configuration file.

6. Repeats steps 1 - 5 for the any other Service folders you created.

7. Start the IBM Cognos ICM Windows Service(s).

Verifying the Installation of the Admin Client

Once you install or upgrade IBM Cognos ICM, you should log in to the Admin Client to make sure it is
working properly.

Copyright © IBM Corporation and other(s) 2005, 2012 39

 Verifying the Installation of the Admin Client

Test an Existing Model

If you have upgraded your model, log in to the Admin Client to make sure the upgrade was successful.

1. Open the Admin Client.

2. Select the Model Name from the dropdown menu (see Figure 2-20).

3. Type your User ID and Password.

4. Click Login.

FIGURE 2-20 Login Screen

Test a New Model

Open the Admin Client and create a model to make sure the Admin Client has been installed successfully.

Copyright © IBM Corporation and other(s) 2005, 2012 40

 Verifying the Installation of the Admin Client

1. Open the Admin Client.

2. Click Options to change the language of the Admin Client and/or set the date format. Select
EnglishGB to set the date format to DD/MM/YYYY or select EnlgishUS to set the date format
to MM/DD/YYYY.

3. Click New Model.

4. Name the model. IBM Cognos ICM will remove all spaces and punctuation from your model
name and use that as the database name on your database server. The model name can be
changed at any time from within IBM Cognos ICM, but the database name that is set initially
will remain for the life of the database.

5. Select when Your current fiscal year began. This is the first day in the current fiscal year.
IBM Cognos ICM will use this date and the number of payroll periods to construct a default
calendar for this new model. The default calendar can be modified and refined from within IBM
Cognos ICM, or replaced entirely if a mistake is made.

6. Select the Number of payroll periods. This is how many times per year this organization
pays employees, either weekly (52), biweekly (26), semimonthly (24), or monthly (12). The
number of pay periods is used to create the default calendar, which is used to set payment
schedules for calculated earnings. The default calendar can be modified or replaced entirely
once the new model has been created.

7. Select the currency. A currency should be added if it will be used for either collection or
payment. More than one currency can be selected. If you require a currency that is not in the
pick list, you can add additional currencies by clicking on Other Currencies.

NOTE: Currencies can be added without using the New Model wizard, so the list can
be expanded at a later time.

8. Select any IBM Cognos ICM hierarchies. Defining hierarchies specifies the columns that will
be used to define the data tables within IBM Cognos ICM. Columns for payees, accounts,
date, and value will be automatically generated. If your data file(s) contains more required
columns, such as, products, customers, territories, or promotion codes, you can add those
items to the list of hierarchies by either checking the appropriate box or typing their names in
the text box.

NOTE: It does not matter whether the data for these columns exists in a single data
file or if you are loading multiple data files.

9. Click Finish.

Copyright © IBM Corporation and other(s) 2005, 2012 41

 Integrate LDAP with the Admin Client

Integrate LDAP with the Admin Client

You can set up the Admin Client to allow users to sign in using LDAP authentication. LDAP users and/or
groups must be configured in the IBM Cognos ICM Windows Service configuration file and the Admin
Client. Users can only log in to the Admin Client if they have been mapped to a IBM Cognos ICM role, or if
they are a member of an LDAP group that has been mapped to a IBM Cognos ICM role. LDAP users must
be assigned to a IBM Cognos ICM user role, configured in the LDAP settings of the IBM Cognos ICM
Windows Service configuration file, and added to the LDAP tab in the Admin Client. Then, the users will be
able to log in to the Admin Client with their LDAP user IDs and passwords. LDAP groups must be assigned
to a IBM Cognos ICM role, configured in the LDAP settings of the IBM Cognos ICM Windows Service
configuration file, and added to the LDAP tab in the Admin Client. Then, LDAP users who are part of that
LDAP group can log in to the Admin Client using their SAMAccountNames and LDAP passwords.

Each employee or group in LDAP has a Distinguished Name (DN) that uniquely identifies it. The DN is
composed of attribute-value pairs (e.g. CN=Quality Assurance, OU=Internal, OU=Groups, OU=HQ,
DC=hq, DC=IBM Cognos ICM, DC=com). The first attribute of a DN is the Common Name (CN). Each user
or group has a CN to identify them (i.e., CN=Dan Huddle or CN=Quality Assurance). Users also have the
attributes “SAMAccountName”, which acts like a username (i.e. SAMAccountName=dhuddle), and
“memberOf”, which describes the groups that the employee belongs to (i.e. memberOf=All,All
Development,Quality Assurance).

TABLE 1. LDAP User Rules

Rules
1 LDAP users cannot log in if there is a pending password change in the account.
2 LDAP users cannot log in if their account is disabled.
3 LDAP users cannot log in twice in the same model.
4 If there is a IBM Cognos ICM user with the same username as the LDAP user, the IBM Cognos ICM
user takes priority (i.e. IBM Cognos ICM will ignore the existence of the LDAP user, and the rules that
apply to the IBM Cognos ICM user remain).
5 If the LDAP user is mapped to different IBM Cognos ICM roles, the union of the permissions are given.
6 The Administrator role can be renamed and mapped to any LDAP group and any user in this group will
have all Administrator permissions.
7 If an LDAP user is logged in to the Admin Client, the Change Password menu item is disabled.
8 LDAP users can write web messages and upload web documents.
9 An LDAP user can be the Scheduler (the same rules for a Scheduler user apply).
10 An LDAP user can log in to perform Migrations.

Copyright © IBM Corporation and other(s) 2005, 2012 42

 Integrate LDAP with the Admin Client

Configure the IBM Cognos ICM Windows Service Configuration File for LDAP
Authentication
You must make a few changes in the IBM Cognos ICM Windows Service configuration file to allow for
users to log in to the Admin Client with LDAP authentication.

1. In the IBM Cognos ICM Windows Service.exe.config file, uncomment the ldapSettings
section (see Figure 2-21).

2. Modify the ProviderUrl to point to the address of the LDAP server that should be searched.

3. Modify the ManagerDn. This is the account that should be used to perform the LDAP tree
search.

4. Modify the ManagerPassword. This is the password of the ManagerDn account.

5. Modify the UserSearchFilter. This is the LDAP attribute that an LDAP user should enter as
the User ID in the IBM Cognos ICM Client login window.

6. Modify the UserGroupAttribute. This is the LDAP attribute that should be used when
attempting to determine LDAP group membership.

FIGURE 2-21 LDAP Settings

7. Set UseKerberos to true to obtain and use the Kerberos token for authentication. Set
UseKerberos to false to use LDAP for authentication. When the UseKerberos field is set to
true, the ManagerDn and ManagerPassword fields will be ignored. Instead, the user under
which the IBM Cognos ICM Windows Service runs will be used to perform the search of the
LDAP tree.

NOTE: If your network is set up using IWA and you want to authenticate as a user
other than the user you are logged into your network as, you must use NTLM and
not Kerberos. Kerberos will only authenticate the currently logged in user.

Copyright © IBM Corporation and other(s) 2005, 2012 43

 Integrate LDAP with the Admin Client

8. Set UseSSL to true to use SSL (LDAPS) to communicate with the LDAP server. Set UseSSL
to false if you do not want to use SSL (LDAPS) to communicate with the LDAP server.

NOTE: When using LDAP authentication in a multi-domain environment, the

UseKerberos field and UseSSL field cannot both be simultaneously set to “true”.
Either SSL or Kerberos can be used on their own (or both can be set to “false”);
however, setting both to “true” will not work in a multi-domain environment.

Grant LDAP Users or LDAP Groups Access to the IBM Cognos ICM Client
LDAP users or LDAP groups must be added and granted access in the Admin Client. The LDAP user or
group must be associated with a IBM Cognos ICM user role.

1. In the Admin Client, go to Admin > Manage Users.

2. Click Add to add an LDAP user or group. The LDAP User Editor window will be displayed.

3. Select either LDAP User or LDAP group from the Type dropdown menu.

4. If you selected LDAP User, type the User ID that matches the value of the LDAP attribute
specified in the user’s LDAP profile in the IBM Cognos ICM Windows Service Configuration
file (by default, the attribute is SAMAccountName).

4.a Select the Role from the dropdown menu. This is the IBM Cognos ICM user role that is
associated with the user (see Figure 2-22).

4.b Click OK.

Copyright © IBM Corporation and other(s) 2005, 2012 44

 Enable Data Tier Performance Optimization

FIGURE 2-22 LDAP Users

5. If you selected LDAP Group, type the Group CN that matches the value of the
UserGroupAttribute in the IBM Cognos ICM Windows Service Configuration file.

5.a Select the Role from the dropdown menu. This is the IBM Cognos ICM user role that is
associated with the group.

5.b Click OK.

6. Click Save.

Enable Data Tier Performance Optimization

The Data Tier Performance Optimization feature can improve calculation performance, especially in
models that have a large number of calculations that perform multiplication and division operations. This
feature allows a larger portion of calculations to be processed by the database and reduces the need for
transfers between the database and IBM Cognos ICM Windows Service.

CLR Integration
In order to use this feature, the common language runtime (CLR) integration feature in Microsoft SQL
Server needs to be enabled by running a script to install a user-defined data type.

To enable CLR integration, use the clr enabled option of the sp_configure stored procedure.

Copyright © IBM Corporation and other(s) 2005, 2012 45

 Enable Data Tier Performance Optimization

sp_configure ‘clr enabled’, 1;

GO
RECONFIGURE;
GO

Enable Data Tier Performance Optimization in the Admin Client

After enabling the common language runtime (CLR) integration feature, performance optimization needs to
be turned on in the Admin Client.

1. Go to Admin > Administrative Options.

2. Click the Calculation tab.

3. Select the Enable data tier performance optimization checkbox (see Figure 2-23).

FIGURE 2-23 Enable Data Tier Performance Optimization

Copyright © IBM Corporation and other(s) 2005, 2012 46

Chapter 3: Install and Use Admin Client Tools

Overview
IBM Cognos ICM comes with several additional tools that are not required for the application to run when
initially setting up your model but can be installed later to perform functions such as converting your model,
importing data from your model into Microsoft Excel, or communicating with IBM Cognos ICM using a
command-line interface.

Console Service
The Console Service tool is a version of the IBM Cognos ICM Windows Service that is run from a
command prompt and uses the same configuration information as the IBM Cognos ICM Windows Service.
It is possible to run multiple console services on the same machine, as long as each service is installed in
a separate directory and is configured to use a different port.

Install the Console Service

1. Double-click on the ICM-console.exe installation file located in your release folder.

2. Click Next on the installer welcome screen.

3. Specify the folder where the IBM Cognos ICM Console Service files will be copied to, and click
Next.

4. Verify the data and click Install to begin the installation.

5. Navigate to the folder where you specified the Console Service to be copied to. By default, it is
located in the following directory: C:\Program Files\IBM Cognos ICM\ConsoleService.

Edit the ConsoleService.exe.config

1. Edit the databaseServer section in the ConsoleService.exe.config file to point to the correct
database.

2. Edit the ServiceAddress to point to a port that is different from any other service (<add
key="ServiceAddress" value="localhost:13112"/>).

Copyright © IBM Corporation and other(s) 2005, 2012 47

 IBM Cognos ICM Windows Service Configuration File Encryption

3. Edit the security settings to be the same as the security settings in the Admin Client.

Start the Console Service

1. Click Start > Run and type cmd in the Open field to start a command prompt.

2. In the directory that the Console Service is located in, type ConsoleService. A message will
be displayed reporting that the service is running.

NOTE: IBM Cognos ICM cannot run without a service. It is not possible to enter
database information in the IBM Cognos ICM Client.exe.config file in order to
bypass the service and access the database directly.

IBM Cognos ICM Windows Service Configuration File Encryption

IBM Cognos ICM allows the following settings in the Service (IBM Cognos ICM Windows
Service.exe.config) and Console Service (ConsoleService.exe.config) configuration files to be encrypted
using the IBM Cognos ICM Configuration File Encrypter tool: DBPassword, DBUser, SchedulerPassword,
SchedulerUser.

Install the IBM Cognos ICM Configuration File Encrypter

Before running the IBM Cognos ICM Configuration File Encrypter tool, you must first install it using the IBM
Cognos ICM Encrypter installation file.

1. Double-click the ICM-encrypter.exe installation file.

2. Click Next on the IBM Cognos ICM Configuration File Encrypter installation welcome screen.

3. Specify the folder where the IBM Cognos ICM Configuration File Encrypter files will be copied
to, and then click Next.

4. Verify the data and click Install to begin the installation.

Run the IBM Cognos ICM Configuration File Encrypter

After the IBM Cognos ICM Configuration File Encrypter tool has been installed, you can use it to encrypt
settings in the IBM Cognos ICM Windows Service and Console Service configuration files.

1. Launch the IBM Cognos ICM Configuration File Encrypter tool located in the IBM Cognos
ICM release folder.

Copyright © IBM Corporation and other(s) 2005, 2012 48

 IBM Cognos ICM Model Converter

2. Click Browse to search for the IBM Cognos ICM Windows Service.exe.config or
ConsoleService.exe.config file to be encrypted.

3. Select Encrypt (see Figure 3-1).

FIGURE 3-1 IBM Cognos ICM Configuration File Encrypter

4. Click Exit.

5. To decrypt a file, repeat the above steps but select Decrypt in Step 3.

NOTE: Encrypting a file will encrypt both sets of usernames and passwords in the
file (database and scheduler). You cannot choose to encrypt one or the other.

IBM Cognos ICM Model Converter

The Model Converter tool allows IBM Cognos ICM SQL models created in SQL 2000 or 2005 to be
converted to SQL 2008 models, and models created in SQL Standard edition to be converted to SQL
Enterprise.

Install the Model Converter Tool

The Model Converter tool is available on all IBM Cognos ICM installations, as of version 6.0 SP3. To use
the Model Converter, the IBM Cognos ICM Windows Service needs to be running.

1. Double-click the ICM-modelconverter.exe installation file located in your release folder.

2. Click Next on the Model Converter installation welcome screen.

3. Specify the folder where the Model Converter files will be copied to, and click Next.

Copyright © IBM Corporation and other(s) 2005, 2012 49

 IBM Cognos ICM Model Converter

4. Verify the data and click Install to begin the installation.

5. After the installation is complete, navigate to the folder where the Model Converter files were
copied to. By default they are located in C:\Program Files\IBM Cognos ICM\Converter.

NOTE: Models created in a SQL Standard edition can be restored on a SQL

Enterprise edition but the Model Converter is required to use Enterprise features.
Enterprise edition models cannot be restored on a standard version of SQL. Models
created on a 2000 or 2005 edition of SQL can be restored on SQL Server 2008, but
the Model Converter tool is required for SQL 2008 features to be available on those
models.

Convert a Model from SQL 2000 or 2005 to SQL 2008

A SQL Server 2000 can be converted to a SQL Server 2008.

NOTE: The IBM Cognos ICM Windows Service must be running when using the
Model Converter tool.

1. Install SQL Server 2008.

2. Restore your SQL 2000 or 2005 model on to the SQL 2008 server.

3. Launch the Model Converter tool.

4. Type the name of the SQL 2008 server in the Server Name field. This can be an arbitrary
name, such as Super Server, and is intended to identify and distinguish the database server. If
your database is a SQL Server 2000 named instance or if you are using a SQL Server 2005
database, the value for the database server field should be in the following format:
SERVER_NAME\INSTANCE_NAME.

5. Select the appropriate Database Type for the model you wish to convert. If you convert a
Unicode model, it will remain a Unicode model after the conversion.

NOTE: Because you have restored your model onto a SQL 2008 Server, you will
need to select either Microsoft SQL Server 2008 or Microsoft SQL Server 2008
Unicode even if your original model was SQL Server 2000 or 2005.

6. Browse for the model you wish to convert.

7. Select SQL Server 2008 from the Convert to menu.

8. Type your SQL Server login credentials.

Copyright © IBM Corporation and other(s) 2005, 2012 50

 IBM Cognos ICM Model Converter

Convert a SQL Standard Model to a SQL Enterprise Model

A SQL Standard Model can be converted to a SQL Enterprise Model.

1. Install SQL Server Enterprise Edition.

2. Restore your SQL Standard Edition model on to the SQL Enterprise server.

3. Launch the Model Converter tool (see Figure 3-2).

4. Type the name of the SQL Enterprise Edition server in the Server Name field. This can be an
arbitrary name, such as Super Server, and is intended to identify and distinguish the database
server. If your database is a SQL Server 2000 named instance or if you are using a SQL
Server 2005 database, the value for the Database Server field should be in the following
format: SERVER_NAME\INSTANCE_NAME.

5. Select the appropriate Database Type for the model you wish to convert. This will be the SQL
Server version that you are converting from. If you convert a Unicode model, it will remain a
Unicode model after the conversion.

6. Browse for the model you wish to convert.

7. Select SQL Server Enterprise Edition from the Convert to menu.

8. Type your SQL Server login credentials.

Convert a SQL 2005 Standard Edition model to SQL 2008 Enterprise Edition model
You can convert a SQL 2005 Standard Edition model to a SQL 2008 Enterprise Edition model. You need to
perform this conversion in the following two phases:

1. Convert your SQL 2005 Standard model to a SQL 2008 Standard model.

2. Convert your SQL 2008 Standard model to a SQL 2008 Enterprise edition model.

Enterprise Size Optimization

You can use the Enterprise Size Optimization feature in the Model Converter tool on SQL Enterprise
Edition models (both 2005 and 2008) to make the database size smaller and, potentially, reduce
calculation times. This feature converts a SQL Server column type that uses more space (decimal type) to
a SQL Server column type that uses less space (vardecimal type). The vardecimal data type is an
alternate storage format that can be used to minimize the disk space needed to store existing decimal and
numeric data types. Disk space can be saved by storing decimal and numeric data as variable length
columns as opposed to the fixed number of bytes in decimal type storage.

Copyright © IBM Corporation and other(s) 2005, 2012 51

 IBM Cognos ICM Model Converter

NOTE: As of IBM Cognos ICM version 7.2, all newly created SQL 2005 and 2008
Enterprise Edition models do not have the vardecimal data type enabled by default.

To use the vardecimal data type on models created prior to version 7.0, do the following:

1. Upgrade to IBM Cognos ICM version 7.0 or higher.

2. If your model was created on a Standard Edition of SQL, convert it to Enterprise Edition.

3. Using Model Converter, select Enterprise Size Optimization from the Convert To dropdown
menu (see Figure 3-2).

FIGURE 3-2 Model Converter Tool

Copyright © IBM Corporation and other(s) 2005, 2012 52

 Using Certificates with IBM Cognos ICM

Using Certificates with IBM Cognos ICM

This section will guide you through the process of generating digital Secure Sockets Layer (SSL)
certificates and configuring them for use with IBM Cognos ICM applications, including IBM Cognos ICM
and IBM Cognos ICM Command Line Interface (CLI).

Required Software
You will require the following additional software to work with digital certificates:

1. .NET Framework Redistributable

Go to http://msdn.microsoft.com to download this software.

NOTE: The 1.1 version is satisfactory, but the 3.0 and higher versions are necessary
for use with IBM Cognos ICM applications.

2. .NET Framework SDK\Windows SDK

Go to http://msdn.microsoft.com to download this software.

NOTE: The .NET Framework SDK has been superseded by the Windows SDK.
Obtain the SDK appropriate for the versions of the Windows operating system and
.NET Framework being used.

3. HTTP Configuration Utility

Go to http://www.stevestechspot.com/downloads/httpconfig.zip to download this software.

NOTE: You will likely need administrator privileges for the Windows machine
(server) where your digital certificates will be configured in order to successfully
complete the configuration steps in this document.

Generating Certificates
You can generate your own digital certificates for testing or troubleshooting purposes.

NOTE: It is highly recommended that digital certificates used in a production

environment are purchased from a trusted certificate authority (CA), such as
Thawte or VeriSign. Using the digital certificates generated by the steps below can
compromise the security of your production environment.

Copyright © IBM Corporation and other(s) 2005, 2012 53

 Using Certificates with IBM Cognos ICM

The Certificate Creation Tool (Makecert.exe) included in the .NET Framework\Windows SDK will be used
to generate a default self-signed (root) certificate (called “Root Agency”) and a certificate signed by this
root certificate.

1. Run the installed SDK Command Prompt and type the following command. You need to run
CMD as the Administrator. To do this, right-click on the CMD shortcut and select Run as
Administrator.

makecert -r -pe -n CN=”Apple” -b 01/01/2000 -e 01/01/2036 -eku 1.3.6.1.5.5.7.3.1 -ss my -sr

localmachine -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12

Command-line Switches
-r creates a self-signed certificate. A self-signed certificate is a certificate that is not signed by a certificate
authority. Because it is not signed by a certificate authority, it can be used for encryption required in SSL
but cannot be used for server authentication.

-pe marks the private key as exportable.

-n specifies the server name. This name must comply with the X.500 standard. The simplest form is
CN=”Name” and should specify the name of the server (case-insensitive) or the IP where it will be used.
For example, for a server named “Apple” the certificate subject name should be CN=”Apple”.

-b date value in mm/dd/yyyy format that specifies the start of the validity period for the certificate. The
default for this is the creation date of the certificate.

-e date value in mm/dd/yyyy format that specifies the end of the validity period for the certificate. If not
otherwise set, the default for this is 12/31/2039 11:59:59 GMT.

-eku Specifies a list of comma-separated, enhanced key usage object identifiers (OIDs) into the
certificate. For SQL Server, an SSL certificate that is valid for server authentication that has an OID of
1.3.6.1.5.5.7.3.1 is required.

-ss specifies the certificate store where the created certificate is saved. We recommend saving this in the
my store, although it can be saved anywhere in the certificate store.

Copyright © IBM Corporation and other(s) 2005, 2012 54

 Using Certificates with IBM Cognos ICM

-sr specifies the certificate store where the certificate is located. Location can be either: currentuser (the
default), or localmachine. Because this certificate is being created for a service, it should be placed in the
local computer.

-sky specifies the certificate key type. For RSA public key exchange algorithm, exchange is required
here. This is the type of key used to encrypt and decrypt session keys.

-sp specifies the CryptoAPI provider name. For certificates created for SQL Server, this can be set to
Microsoft RSA SChannel Cryptographic Provider.
-sy specifies the CryptoAPI provider type. When the provider is Microsoft RSA SChannel Cryptographic
Provider, this is 12.

2. Use the corresponding command to generate the digital certificate (see Figure 3-3):

FIGURE 3-3 Generating a Digital Certificate

The generated digital certificate is stored in a file called Apple.cer in the directory from which the above
command is executed. You can examine this digital certificate by opening the file (double-clicking on it in
Windows Explorer) and viewing its details (see Figure 3-4).

Copyright © IBM Corporation and other(s) 2005, 2012 55

 Using Certificates with IBM Cognos ICM

FIGURE 3-4 Digital Certificate

Notice that the Apple certificate appears below the Root Agency root certificate. This indicates that the
Root Agency root certificate has issued and signed the Apple certificate, thereby verifying its authenticity.

Setting up Microsoft Management Console to use Digital Certificates

Microsoft Management Console (MMC) can be used to view the digital certificates installed in the local
certificate repository, as well as import new digital certificates into the local certificate repository.

1. Run MMC.

1.a Click Start > Run.

1.b Type in mmc and click OK.

2. Go to the File menu and select Add/Remove Snap-in, or press Ctrl + M.

3. Click Add.

4. Select Certificates and click Add.

Copyright © IBM Corporation and other(s) 2005, 2012 56

 Using Certificates with IBM Cognos ICM

5. Select Computer account and click Next.

6. Leave the Local computer option selected and click Finish.

7. Click Close > OK (see Figure 3-5).

FIGURE 3-5 Local Certificates

Importing Certificates
Expand the Certificates node in the MMC window to view the logical stores in the local certificate repository
(see Figure 3-6).

Copyright © IBM Corporation and other(s) 2005, 2012 57

 Using Certificates with IBM Cognos ICM

FIGURE 3-6 Importing Certificates

You will need to import at least two digital certificates into the following logical stores:
• A root certificate into the Trusted Root Certification Authorities store.
• A server certificate signed by the root certificate into the Personal store.

If you have generated test certificates using the steps in “Generating Certificates” , then these digital
certificates have already been imported into the correct logical stores.

If you have purchased digital certificates from a trusted certificate authority, these digital certificates need
to be imported into the local certificate repository. Purchased digital certificates are usually delivered in one
Public-Key Cryptography Standards (PKCS) #12 certificate file (with either a PFX or P12 extension)
containing all of the necessary digital certificates and a private key for the signed server certificate. This file
is usually protected by a password.

Import the necessary digital certificates contained in a PKCS #12 file

1. Expand the Personal store.

2. Select the child Certificates node.

Copyright © IBM Corporation and other(s) 2005, 2012 58

 Using Certificates with IBM Cognos ICM

3. Right-click and select All Tasks > Import.

4. Click Next.

5. Click Browse and locate the PKCS #12 file.

6. You will need to change the Files of type selection to Personal Information Exchange.

7. Once you have located the file, select it, and click Open.

8. Click Next.

9. Type the private key password and click Next.

10. Leave the Place all certificates in the following store option selected.

11. Click Next.

12. Review the import settings if necessary and click Finish.

All of the digital certificates contained in the PKCS #12 file are now in the Personal store, but only the
server certificate belongs in this store. The server certificate can be identified as the certificate with the
server’s name, e.g. Apple, specified under the Issued To column (see Figure 3-7).

Copyright © IBM Corporation and other(s) 2005, 2012 59

 Using Certificates with IBM Cognos ICM

FIGURE 3-7 Personal Store

You can double-click this certificate to examine its details and make sure that the Certification path is
complete and that the Certificate status indicates that the certificate is “Okay”.

The topmost certificate in the Certification path is the root certificate, e.g. Root Agency, which belongs in
the Trusted Root Certification Authorities store. Move this certificate from the Personal store into the
Trusted Root Certification Authorities store by dragging and dropping or by cutting and pasting it.
Any certificates in the Certification path that are between the root certificate and server certificate are
known as intermediate certificates and belong in the Intermediate Certification Authorities store.
You can now close the MMC window. Saving the settings is not necessary.

Identifying Server IP Address and Port

The IP address of the server where the digital certificates have now been installed is necessary in order to
properly configure the server to identify itself. An unused port number is also necessary to listen for SSL
connections initiated by clients.

Copyright © IBM Corporation and other(s) 2005, 2012 60

 Using Certificates with IBM Cognos ICM

NOTE: If a hostname is being used instead of an IP address, the hostname needs to

be mapped with the IP address in the host file.

Identify the IP Address of the Server

1. Click Start > Run.

2. Type cmd and click OK.

3. Type the following in the Command Prompt window: ping <server_name>,

where <server_name> is the name of the server, e.g. Apple.

4. Note the IP address where the ping replies from.

5. Close the Command Prompt window.

Identify an Unused Port Number on the Server

1. Click Start > Run.

2. Type cmd and click OK.

3. Type the following in the Command Prompt window: telnet <server_name><port_number>,

where <server_name> is the name of the server, e.g. Apple, and <port_number> is the port
number to test for.

4. If the connection cannot be opened to the server using the given port number, this port number
is not being used. Note this port number.

NOTE: By default, IBM Cognos ICM applications use port numbers ‘13105’, ‘13115’,
and ‘13125’.

Identifying the Server Certificate

The server certificate must be specified as the digital certificate the server will present to any clients that
attempt to initiate SSL connections. This can be done using the HTTP Configuration Utility, i.e.
HttpConfig.exe.

Identify the Server Certificate

1. Run the HTTP Configuration Utility.

2. Select the SSL tab and click Add.

Copyright © IBM Corporation and other(s) 2005, 2012 61

 Using Certificates with IBM Cognos ICM

3. Type the IP address of the server in the IP Address field and a port number in the Port field.

NOTE: If a hostname is being used instead of an IP address, the hostname needs to

be mapped with the IP address in the host file. Go to C:\windows\system32\drivers\
to make this change.

4. Click Browse and select the server certificate.

5. Click OK.

6. Select the Permissions tab and make sure that permissions for the appropriate group of
users are granted.

7. Click OK in the SSL Configuration dialog. The HTTP Configuration Utility window should look
like the following image (see Figure 3-8):

FIGURE 3-8 HTTP Configuration Utility

8. Click OK to close the HTTP Configuration Utility.

Configuring IBM Cognos ICM to use Certificates

You are now ready to use the configured digital certificates to work with either IBM Cognos ICM or IBM
Cognos ICM CLI.

Copyright © IBM Corporation and other(s) 2005, 2012 62

 Using Certificates with IBM Cognos ICM

Configure the IBM Cognos ICM Client and the IBM Cognos ICM Windows Service to use
Certificates
You can configure IBM Cognos ICM to use digital certificates.

1. Open the IBM Cognos ICM Windows Service.exe.config service configuration file.

2. Modify the APISecureAddress value, where localhost is the name of the server and 13125 is
the port number configured to listen for SSL connections (see Figure 3-9).

3. Modify the APICertificateName value, where CommonName specifies the common name of
the configured server certificate, which should also be the name of the server (see Figure 3-9).

FIGURE 3-9 Configuring API 1

4. Save the IBM Cognos ICM Windows Service configuration file changes.

5. Start (or restart) the IBM Cognos ICM Windows Service for the service configuration file
changes to take effect.

6. Open the IBM Cognos ICM Client.exe.config file.

7. Modify the serviceAddress, where <server_name> and <port_number> are the values
specified in the IBM Cognos ICM Windows Service.exe.config file (see Figure 3-10).

FIGURE 3-10 Configuring API 2

8. Save the IBM Cognos ICM Client configuration file.

9. Start (or restart) the IBM Cognos ICM Admin Client.

Copyright © IBM Corporation and other(s) 2005, 2012 63

 IBM Cognos ICM CLI

IBM Cognos ICM CLI

IBM Cognos ICM CLI is a command-line interface that connects to models through the IBM Cognos ICM
API Windows service. The command-line interface can be used to perform a calculation on the model or
run a saved process.

IBM Cognos ICM CLI Pre-installation Checklist

In order for IBM Cognos ICM CLI to connect to models on a configured database you must do the
following:
• Start the IBM Cognos ICM Windows Service
• Specify values for the APIAddress, APISecureAddress, and APICertificateName keys in the
IBM Cognos ICM Windows Service.exe.config file
• Start the IBM Cognos ICM API Service
• Install a certificate on the machine running IBM Cognos ICM CLI and point the endpoint
addresses in the IBM Cognos ICM CLI configuration file to where the IBM Cognos ICM API
service is running (see “Using Certificates with IBM Cognos ICM”)

Install IBM Cognos ICM CLI

1. Double-click the ICM-cli.exe installation file located in your IBM Cognos ICM release folder.

2. Click Next on the IBM Cognos ICM Command-Line Interface installation welcome screen.

3. Specify the folder where the IBM Cognos ICM Command-Line Interface files will be copied to,
and then click Next.

4. Verify the data and click Install to begin the installation.

Configure IBM Cognos ICM CLI

You can configure IBM Cognos ICM CLI to use digital certificates.

1. Open the IBM Cognos ICM Windows Service.exe.config file.

2. Modify the APISecureAddress value, where <server_name> is the name of the server and
<port_number> is the port number configured to listen for SSL connections, e.g. ‘13125’ (see
Figure 3-11).

3. Modify the APICertificateName, where <common_name> specifies the common name of the
configured server certificate, which should also be the name of the server.

Copyright © IBM Corporation and other(s) 2005, 2012 64

 IBM Cognos ICM CLI

FIGURE 3-11 Configuring IBM Cognos ICM CLI 1

4. Save the IBM Cognos ICM Windows Service configuration file changes.

5. Start (or restart) the IBM Cognos ICM Windows Service for the service configuration file
changes to take effect.

6. Start (or restart) the API service for the service configuration file changes to take effect.

7. Open the ICM-CLI.exe.config configuration file.

8. Modify the ServiceAddress, where <server_name> and <port_number> are the values
specified in the IBM Cognos ICM Windows Service.exe.config file (see Figure 3-12).

FIGURE 3-12 Configuring IBM Cognos ICM CLI 2

9. Save the configuration file changes.

10. Execute IBM Cognos ICM CLI from within a Command Prompt window.

Connecting to a Model Using the CLI

To connect to a IBM Cognos ICM model, you need to know the model name, username, and the password
(if a password has been set).

1. Open the command prompt window.

2. Navigate to the directory where IBM Cognos ICM CLI is located. For example, type cd
C:\Program Files\IBM Cognos ICM\CLI.

3. From the command-line, type the following at a command prompt:

IBM Cognos ICM CLI –server <server name> –model <model name> – user <username>
– pass <password>

Where <server name> is the name of the database server that the model resides on as
Copyright © IBM Corporation and other(s) 2005, 2012 65
 IBM Cognos ICM CLI

defined in the configuration file (not necessarily the true name of the server), <model name>
is the name of the database containing the IBM Cognos ICM model, <username> is the
username used to log in to the model, and <password> is the password used to log in to the
model.

NOTE: If no password has been set up for the user, omit the password component.

Example:
IBM Cognos ICM CLI –server Server1 –model Softco –user admin

Executing Commands
The following execution commands are currently available:
• calcall: Calculate all objects in the model
• runproc <process>: Run a saved process named <process>
• enablewebuser “true” -payeeid <“payeeID of web user to enable”> -webpw <“web user’s
password”>: Enables a user for the IBM Cognos ICM web client
• enablewebuser “false” -payeeid <“payeeID of web to disable”>: Disables a web user
• changewebuserpassword -payeeid <“payeeID of web user to change password for”> -
webpw<“web user’s password”>: Changes a web user’s password

NOTE: All CLI Commands are case-sensitive.

1. Type the command after the model connection information.

Examples:
The following command will connect to the SoftCo model and calculate all objects in the model on a server
named MyServer:
IBM Cognos ICM CLI -server “MyServer” -model “Softco” -user admin -calcall

The following command will connect to the SoftCo2 model and calculate all objects in the model and run a
saved process called Imports on a server called MyServer:
IBM Cognos ICM CLI -server “MyServer” -model “SoftCo2” -user admin -pass secret -runproc Imports

The following command will connect to the SoftCo2 model and enable a user for the IBM Cognos ICM web
client in the model on a server named MyServer:

Copyright © IBM Corporation and other(s) 2005, 2012 66

 IBM Cognos ICM API

IBM Cognos ICM CLI -server “MyServer” -model “SoftCo” -user admin -pass secret -enablewebuser
“true”
-payeeid “E1000” -webpw “1234”

The following command will connect to the SoftCo2 model and disable a IBM Cognos ICM web client user
in the model on a server named MyServer:
IBM Cognos ICM CLI -server “MyServer” -model “SoftCo” -user admin -pass secret -enablewebuser
“false”
-payeeid “E1001”

The following command will connect to the SoftCo2 model and change a user’s password for IBM Cognos
ICM web client in the model on a server named MyServer:
IBM Cognos ICM CLI -server “MyServer” -model “SoftCo” -user admin -pass secret -
changewebuserpassword
-payeeid “E1000” -webpw “4321”

Return Code from the CLI

The third-party tool being used to call IBM Cognos ICM through the CLI may need to know if the called
process was able to complete successfully or if it failed. Determining the result of executing IBM Cognos
ICM CLI can be done by checking the value that is returned to the caller (either the operating system or
another process or tool). The following are the values that can be returned:
• A value of '0' (integer) indicates a successful execution
• A value of '-1' (integer) indicates failed execution

The procedure for collecting a return code depends entirely on the method used to launch the IBM Cognos
ICM application. It is up to the caller of IBM Cognos ICM CLI to capture these values so that this
information can be used to take further action.

IBM Cognos ICM API

Overview
The IBM Cognos ICM API is implemented by writing function calls in the program, which provides the
linkage required for execution. The API allows IBM Cognos ICM modules to be available or linked into an
existing program to perform the required tasks.

Copyright © IBM Corporation and other(s) 2005, 2012 67

 IBM Cognos ICM API

The intent of this API section is to provide client organizations wishing to access IBM Cognos ICM in a
programmatic way with an interoperable option. Some common use scenarios include the following:

1. Client organizations wishing to retrieve calculated or statistical data from IBM Cognos ICM for
use in other downstream applications, such as portal applications, reporting, or other systems

2. Client organizations wishing to leverage Web Services to more tightly integrate systems

3. Client organizations wishing to programmatically trigger IBM Cognos ICM with existing third-
party scheduling/application management software

4. Partner organizations wishing to integrate their solution more closely with IBM Cognos ICM

5. Client/partner organizations wishing to enable the IBM Cognos ICM mobility application

The above scenarios involve querying IBM Cognos ICM, retrieving data from the system, updating data
within the system, and adding data to the system.

Typically, the data is either of the following:

• Portal Access-related (e.g. access rights, inquiries, approvals, or denials)
• Statistical (e.g. transactions, rates, quotas, compensation amounts, hierarchical, or data)

All of this information is accessible via calls embedded into the IBM Cognos ICM API.

API Architecture Overview

IBM Cognos ICM provides a WS-I compliant API implemented using the Windows Communication
Foundation (WCF) introduced in Microsoft’s .NET Framework 3.0.

WCF supports WS-* security standards through configurable bindings and behaviors. This makes sure that
web services are interoperable while incorporating transaction support, end-to-end security, and reliability.

Transactions - WCF supports WS-AtomicTransaction and WS-Coordination, enabling two-phase commit

transactions.
Security - WCF supports WS-SecureConversation, WS-Security, and WS-Trust, enabling both transport-
level and message-level security.
Reliability - WCF supports WS-ReliableMessaging, enabling reliable end-to-end communication.

Any WS-I compliant application should be able to inter-operate with the IBM Cognos ICM API. We have
tested both .NET and java-based client applications.
Copyright © IBM Corporation and other(s) 2005, 2012 68
 IBM Cognos ICM API

A custom Web Services extension can be written for your deployment. To discuss this option, please
speak with an IBM Cognos ICM sales representative.

API Access
The API is hosted as a Windows Service, called ‘ IBM Cognos ICM API’. The IBM Cognos ICM API
Windows Service must be started in order to obtain access. Certificates also need to be installed and
configured properly in order to provide a secure connection between the service and an API-aware client
(see “Using Certificates with IBM Cognos ICM”).

Once the API service is started, connect an API-aware client to the following addresses:
https://localhost:13125/API/Calculations
https://localhost:13125/API/Security
https://localhost:13125/API/Table
https://localhost:13125/API/Scheduler

Once connected, a username and password are required to gain access. The username is given in the
following format:
<server>/<database>/<user_type>/<username>
<server> is the database server name specified in the IBM Cognos ICM Windows Service configuration
file
<database> is the database name of the IBM Cognos ICM model you want to connect to
<user_type> is “Web” (indicating a web-enabled user)
<username> is the email address of a web-enabled user

The password is the password specified for the web-enabled user.

The following is an arbitrary username and password example:
Username: Local/TestModel/Web/jsmith@corporation.com
Password: secret

To obtain the WSDL file, connect a web browser to the following address:

https://localhost:13125/API/Calculations?wsdl
https://localhost:13125/API/Security?wsdl
https://localhost:13125/API/Table?wsdl
https://localhost:13125/API/Scheduler?wsdl

Copyright © IBM Corporation and other(s) 2005, 2012 69

 IBM Cognos ICM API

API Specifications - Processing and Calculation

TABLE 1. RunProcess

RunProcess
(WSDL Address: https://localhost:13125/API/Scheduler?wsdl)
Description Run saved process (folder) in Scheduler
Input Process (folder) name (string)
Output None
Note Administrator users only
Exceptions InvalidArgumentException, InvaildDataException, RetiredEndpointException,
TokenException

TABLE 2. ComputeAll

ComputeAll
(WSDL Address: https://localhost:13125/API/Caculations?wsdl)
Description Compute all calculations
Input None
Output None
Note Administrator users only
Exceptions RetiredEndpointException, TokenException

TABLE 3. ComputePlan

ComputePlan
(WSDL Address: https://localhost:13125/API/Calculations?wsdl)
Description Compute results for given compensation plan
Input Plan ID (string)
Output None
Note Administrator users only
Exceptions InvalidArgumentException, RetiredEndpointException, TokenException

Copyright © IBM Corporation and other(s) 2005, 2012 70

 IBM Cognos ICM API

TABLE 4. ComputeTailoredReport

ComputeTailoredReport
(WSDL Address: https://localhost:13125/API/Calculations?wsdl)
Description Compute results for given tailored report
Input Tailored report ID (String)
Output None
Note Administrator users only
Exceptions InvaildArgumentException, RetiredEndpointException, TokenException

TABLE 5. ComputePayee

ComputePayee
(WSDL Address: https://localhost:13125/API/Calculations?wsdl)
Description Compute results for given payee
Input Payee ID (string)
Output None
Note Administrator users only
InvalidArgumentException, RetiredEndpointException, TokenException

TABLE 6. ComputeWebReport

ComputeWebReport
(WSDL Address: https://localhost:13125/API/Calculations?wsdl)
Description Compute results for given web form
Input Web Form ID (number)
Output None
Note Administrator users only
Exceptions InvalidArgumentException, RetiredEndpointException, TokenException

TABLE 7. ComputeWebForm

ComputeWebForm
(WSDL Address: https://localhost:13125/API/Calculations?wsdl)
Description Compute results for given web form
Input Web Form ID (number)
Output None

Copyright © IBM Corporation and other(s) 2005, 2012 71

 IBM Cognos ICM API

TABLE 7. ComputeWebForm

ComputeWebForm
(WSDL Address: https://localhost:13125/API/Calculations?wsdl)
Note Administrator users only
Exceptions InvalidArgumentException, RetiredEndpointException, TokenException

Copyright © IBM Corporation and other(s) 2005, 2012 72

 IBM Cognos ICM API

API Specifications - Data Management

TABLE 8. TableExists

TableExists
(WSDL Address: https://localhost:13125/API/Table?wsdl)
Description Determine if a table with the given name exists in the model
Input Table name (string)
Output The value “true” (boolean) if the table exists in the model and “false” (boolean)
otherwise
Note Administrator users only
Exceptions InvaildArgumentException, RetiredEndpointException, TokenException

TABLE 9. GetTablePermissions

GetTablePermissions
(WSDL Address: https://localhost:13125/API/Security?wsdl)
Description Get table permissions granted to the current user for the given table
Input Table name (string)
Output List of table permissions (strings) granted to the current user for the given table
Note Administrator users only
Table permissions can be one of the following: Add, Edit, Delete
Exceptions InvaildArgumentException, InvaildDataException, RetiredEndpointException

TABLE 10. GetTableSchema

GetTableSchema
(WSDL Address: https://localhost:13125/API/Table/wsdl)
Description Get the schema for the given table, including column types and key fields
Input Table name (string)
Output TableSchema object containing the table name (string) and a list of ColumnSchema
objects containing column name (string), column type (string) and whether column is a
key column (boolean)
Note Column types can be one of the following: Text Box, Date, Pick List, Numeric, Email,
URL, Comment
Administrator users only
Exceptions InvalidArgumentException, InvaildDataException, RetiredEndpointException,
PermissionDeniedException, TokenException

Copyright © IBM Corporation and other(s) 2005, 2012 73

 IBM Cognos ICM API

TABLE 11. GetTableRow

GetTableRow
(WSDL Address: https://localhost:13125/API/Table?wsdl)
Description Get a single data row from the given table
Input Table name (string) and list of ColumnValuePair objects that uniquely identifies the row
Output DataRow object that contains a list of ColumnValuePair objects that correspond to each
column and its value
Note Administrator users only
Exceptions InvalidArgumentException, InvalidDataException, RetiredEndpointException,
PermissionDeniedException, TokenException

TABLE 12. AddRow

AddRow
(WSDL Address: https://localhost:13125/API/Table?wsdl)
Description Add a row to the given table
Input Table name (string), and list of ColumnValuePair objects
Output None
Note Administrator users only
Exceptions InvalidArgumentException, InvalidDataException, RetiredEndpointException,
PermissionDeniedException, TokenException

TABLE 13. UpdateRow

UpdateRow
(WSDL Address: https://localhost:13125/API/Table?wsdl)
Description Update values for an existing row in the given table
Input Table name (string), list of original ColumnValuePair objects that correspond to a row in
the table, and a list of new ColumnValuePair objects that contain new values
Output None
Note Administrator users only
Exceptions InvalidArgumentException, InvalidDataException, RetiredEndpointException,
PermissionDeniedException, TokenException

Copyright © IBM Corporation and other(s) 2005, 2012 74

 IBM Cognos ICM API

TABLE 14. DeleteRow

DeleteRow
(WSDL Address: https://localhost:13125/API/Table?wsdl)
Description Delete a row from the given table
Input Table name (string) and list of ColumnValuePair objects that correspond to a row in the
table
Output None
Note Administrator users only
Exceptions InvalidArgumentException, InvalidDataException, RetiredEndpointException,
PermissionDeniedException, TokenException

HINT: You will need to provide full column names to update and/or delete a row. To get the
full column name, call ‘GetTableRow’ with the table name and key columns to get the
entire row.

API Specifications - Data Store

Service Address: https://localhost:13125/API/DataStore
WSDL: http://localhost:13115/API/DataStore/?wsdl

TABLE 15. GetDataStoreID

GetDataStoreID
Description Get ID of the DataStore for the given name
Input DataStore name (string)
Output The ID value (integer) for the given DataStore name
Exceptions TokenException, PermissionDeniedException

TABLE 16. GetDataStoreName

GetDataStoreName
Description Get name of the DataStore for the given ID
Input DataStore ID (integer)
Output The name value (string) for the given DataStore Name
Exceptions TokenException, PermissionDeniedException

Copyright © IBM Corporation and other(s) 2005, 2012 75

 IBM Cognos ICM API

TABLE 17. GetDataStoreIDToNameMapping

GetDataStoreIDToNameMapping
Description Get mapping of entire DataStore ID to DataStore name
Input DataStore ID (integer)
Output The value “true” (boolean) if the table exists in the model and “false” (boolean) otherwise
Exceptions TokenException, PermissionDeniedException

TABLE 18. GetDataStoreSchema

GetDataStoreSchema
Description Get table schema of the DataStore
Input DataStore ID (integer)
Output TableSchema (TableSchema) of the DataStore with the given ID
Exceptions TokenException, PermissionDeniedException

TABLE 19. GetDataStoreRowRange

GetDataStoreRowRange
Description Get rows for the given DataStore ID
Input DataStore ID (integer) ID of the DataStore
Restrictions (RestrictionBase) Restrictions to filter the data
StartIndex (integer) start index of the row of the result
Length (integer) number of the rows to retrieve
Output Array of DataRow (DataRow[])
Exceptions TokenException, InvalidArgumentException, InvalidDataException, LargeDataException,
PermissionDeniedException

TABLE 20. GetDataStoreRowCount

GetDataStoreRowCount
Description Get the number of rows for the given DataStore ID
Input DataStore ID (integer)
Restrictions (RestrictionBase) Restrictions to filter the data
Output Number of Rows in the DataStore (integer)
Exceptions TokenException, InvalidArgumentException, InvalidDataException,
PermissionDeniedException

Copyright © IBM Corporation and other(s) 2005, 2012 76

 IBM Cognos ICM API

Object Definitions

NOTE: The following objects are represented as class definitions written in C#.

ColumnSchema
public class ColumnSchema
{
public string Name;
public string Type;
public bool IsKey;
}

Earnings
public class Earnings
{
public PayeeName PayeeName;
public string PlanID;
public string Amount;
}

EarningsDetails
public class EarningsDetails
{
public string[] ColumnHeaders;
public EarningsDetailsRow[] Details;
}

EarningsDetailsRow
public class EarningsDetailsRow
{
public string[] ColumnData;
public string Payout;
}

Copyright © IBM Corporation and other(s) 2005, 2012 77

 IBM Cognos ICM API

Inquiry
public class Inquiry
{
public int ID;
public string Object;
public PayeeName Creator;
public PayeeName Assignee;
public string CreationDate;
public string Status;
public string Category;
public InquiryComment[] Comments;
}

InquiryComment
public class InquiryComment
{
public PayeeName Author;
public string CreationDate;
public string CommentText;
}

NameValue
public class NameValue
{
public string Name;
public string Value;
}

PayeeName
public class PayeeName
{
public string ID;
public string Name;
}

Copyright © IBM Corporation and other(s) 2005, 2012 78

 IBM Cognos ICM API

PeriodEarnings
public class PeriodEarnings
{
public string PeriodType;
public PeriodEarningsRow[] Earnings;
}

PeriodEarningsRow
public class PeriodEarningsRow
{
public string Period;
public string Amount;
}

PlanEarnings
public class PlanEarnings
{
public PayeeName PayeeName;
public string PlanID;
public string Earnings;
}

PlanName
public class PlanName
{
public string ID;
public string Name;
}

PlanPosted
public class PlanPosted
{
public PlanName PlanName;
public string LastPostedPeriod;
}

Copyright © IBM Corporation and other(s) 2005, 2012 79

 IBM Cognos ICM API

SignOff
public class SignOff
{
public int ID;
public string Name;
public int NodeID;
public string StartDate;
public string Object;
public string[] Signees;
}

TableData
public class TableData
{
public TableSchema Schema;
public TableDataRow[] Rows;
}

Copyright © IBM Corporation and other(s) 2005, 2012 80

 IBM Cognos ICM API

TableDataRow
public class TableDataRow
{
public string[] Values;
}

TableSchema
public class TableSchema
{
public string Name;
public ColumnSchema[] Columns;
}

WorkflowStatus
public class WorkflowStatus
{
public PayeeName PayeeName;
public int ApprovalStatus;
public bool HasOpenInquiries;
}

DataRow
{
public ColumnValuePair[] Values;
}

ColumnValuePair
public class ColumnValuePair
{
public string Column;
public string Value;
}

Copyright © IBM Corporation and other(s) 2005, 2012 81

 IBM Cognos ICM API

DataStore Object Definitions

Public abstract class RestrictionBase
{
}
Public abstract class RestrictionGroup : RestrictionBase
{
Public RestrictionBase[] RestrictionItems;
}
Public class AllGroup : RestrictionGroup
{
}
Public class AnyGroup : RestrictionGroup
{
}
Public class Restriction : RestrictionBase
{
Public ColumnSchema Column;
Public Operator OperatorType;
Public string Right;
}
Public enum Operator
{
LessThan,
LessThanEquals,
Equals,
NotEquals,
GreaterThan,
GreaterThanEquals,
IsNull,
IsNotNull
}

Copyright © IBM Corporation and other(s) 2005, 2012 82

 IBM Cognos ICM API

Exception Definitions

NOTE: These following objects are represented as class definitions written in C#.

APIException
public class APIException
{
public string Message;
}
Description: A base object that all exception objects extend to inherit the Message member, which is
used to store a description of the error causing the exception.

InvalidArgumentException
public class InvalidArgumentException : APIException
{
}
Description: This is thrown when an invalid argument (parameter value) for a method is discovered.

InvalidDataException
public class InvalidDataException : APIException
{
}
Description: This is thrown when invalid (non-existent) data is discovered.

RetiredEndpointException
public class RetiredEndpointException : APIException
{
}
Description: This is thrown when an endpoint (service method) is retired (i.e no longer exists).

UserTypeException
public class UserTypeException : APIException
{
}
Description: This is thrown when the user type for the user currently logged in is deemed incorrect or
invalid.

Copyright © IBM Corporation and other(s) 2005, 2012 83

 Microsoft Excel Add-in for IBM Cognos ICM

PermissionDeniedException
public class PermissionDeniedException : APIException
{
}
Description: This is thrown when the user does not have permission to perform the operation.

Microsoft Excel Add-in for IBM Cognos ICM

You can install an IBM Cognos ICM add-in for Microsoft Excel 2003 and 2007/2010 that gives users an
easy way to do self-reporting using up-to-date IBM Cognos ICM results. Once users are logged in to IBM
Cognos ICM through Excel, they will be able to select from a list of IBM Cognos ICM star schemas to be
included in the report. Using typical pivot functionality, users can define what to include along the Y-axis,
the X-axis, and what values to report on. Users will also be able to refresh the data with up-to-date IBM
Cognos ICM data.

Service-side Setup
You will have to set up certificates on the machine running the IBM Cognos ICM Windows Service and
modify the IBM Cognos ICM Windows Service configuration file.

Set Up Certificates
You will need to import a digital certificate into the Trusted Root Certification Authorities store and the
Personal store.

1. Run Microsoft Management Console.

1.a Click Start > Run.

1.b Type mmc and click OK.

2. Go to File > Add/Remove Snap-in.

3. Click Add.

4. Select Certificates and click Add.

5. Select Computer account and click Next.

6. Leave the Local computer option selected and click Finish.

7. Click Close then OK.

Copyright © IBM Corporation and other(s) 2005, 2012 84
 Microsoft Excel Add-in for IBM Cognos ICM

8. Expand Certificates and expand Trusted Root Certification Authorities.

9. Select the Certificates folder under Trusted Root Certification Authorities, right-click and
select All Tasks > Import.

10. In the Certificate Import Wizard, click Next.

11. Click Browse.

11.a Open the folder containing the certificate and select All Files from the Files of type
dropdown menu.

11.b Select the certificate and click Open. For this example, the certificate is called
MobileAPI.

12. Click Next.

13. Type the password for the private key (if any) and click Next.

14. Leave the Place all certificates in the following store option selected.

15. Click Next.

16. Review the import settings and click Finish.

17. Expand the Personal folder.

18. Select the Certificates folder, right-click and select All Tasks > Import.

19. Repeat steps 10 - 16. The Mobile API certificate will now be stored in both folders (see Figure
3-13).

20. Close the Microsoft Management Console. You do not need to save the settings.

Copyright © IBM Corporation and other(s) 2005, 2012 85

 Microsoft Excel Add-in for IBM Cognos ICM

FIGURE 3-13 Certificate

Modify the IBM Cognos ICM Windows Service Configuration File

In the IBM Cognos ICM Windows Service configuration file, you will need to set up a secure API address
and port and add the certificate required for access.

1. Under API secure address and port, change the Value to equal [certificate name]:[port
number]. For example, <add key=”APISecureAddress” value=”MobileAPI:13125”/>.

2. Under API certification required for access, change the Value to equal the certificate name.
For example, <add key=”APICertificateName” value=”MobileAPI”/> (see Figure 3-14).

Copyright © IBM Corporation and other(s) 2005, 2012 86

 Microsoft Excel Add-in for IBM Cognos ICM

FIGURE 3-14 IBM Cognos ICM Windows Service Configuration File Settings

Configure the Identity of the Server Hosting the Service

1. Go to C:\Windows\system32\drivers\etc and open the hosts file using Notepad.

2. Type the IP address of the machine hosting the service and type the certificate name. The IP
address and the certificate name should be separated by at least one space. For example,
127.0.0.1 MobileAPI (see Figure 3-15).

FIGURE 3-15 Configure Identity of Server

3. Save and close the file.

Copyright © IBM Corporation and other(s) 2005, 2012 87

 Microsoft Excel Add-in for IBM Cognos ICM

Identify the Server Certificate

1. Run the HTTP Configuration Utility. To download the HTTP Configuration Utility, (see
“Required Software”).

2. Click the SSL tab and click Add.

3. In the IP Address field, type the IP address of the server hosting the service.

4. In the Port field, type the SSL port you specified in the IBM Cognos ICM Windows Service
configuration file. For example, 13125 (see Figure 3-16).

5. Click Browse.

5.a Select the certificate.

5.b Click OK.

FIGURE 3-16 HTTP Configuration

6. Click the Permissions tab and click Add.

7. Type the URL. For example, https://MobileAPI:13125/.

8. Click Add to add users or a group that will have access.

9. Type the name of the users or group and click OK.

10. Click Apply then click OK.

11. Click OK to close the HTTP Configuration Utility.

Client-side Setup
If the server is using a private (self-signed) certificate, you will need to set up the certificates, identify the
server certificate and configure the identity of the server hosting the service on the machine running the

Copyright © IBM Corporation and other(s) 2005, 2012 88

 Microsoft Excel Add-in for IBM Cognos ICM

Admin Client using the same steps that were used in the Service-side setup. Certificates are required on
both sides for the Service to access the Client. However, if the server is using a Trusted certificate, it is not
necessary to add certificates to the machine running the Admin Client. You will need to install software to
run the IBM Cognos ICM Microsoft Excel Add-in; then install the IBM Cognos ICM Microsoft Excel Add-in
itself on the machine running the Admin Client.

Required Software to Run the Excel Add-in

Users will have to have the following software in order to run the Excel Add-in for Microsoft Excel 2007/
2010:
• Office Primary Interop Assemblies tools
• Visual Studio Tools for the Microsoft Office System (version 3.0 Runtime). It can be
downloaded here:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=54eb3a5a-0e52-40f9-a2d1-
eecd7a092dcb&displaylang=en
• Visual Studio Tools for the Microsoft Office System Service Pack 1 (x86). It can be
downloaded here:
http://www.microsoft.com/downloads/en/details.aspx?FamilyId=D8EB4921-891A-4B5E-973F-
0B96E6CCF376&displaylang=en
Users will have to have the following software in order to run the IBM Cognos ICM Microsoft Excel Add-in
for Microsoft Excel 2003:
• Office Primary Interop Assemblies tools
• Visual Studio 2005 Tools for the Office Second Edition Runtime (VSTO 2005 SE) (x86). It can
be downloaded here:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=f5539a90-dc41-4792-8ef8-
f4de62ff1e81&displaylang=en

Install Office Primary Interop Assemblies Tool

To run the IBM Cognos ICM Microsoft Excel Add-in, you must have the Office Primary Interop Assemblies
tool installed.

1. In the Control Panel, select Add or Remove Programs.

2. Select Microsoft Office and click Change.

3. Under Installation Options, expand Microsoft Office Excel and select .Net
Programmability Support.

4. Click the dropdown arrow and select Run from My Computer.

Copyright © IBM Corporation and other(s) 2005, 2012 89

 Microsoft Excel Add-in for IBM Cognos ICM

5. Click Continue.

6. When the configuration process is complete, click Close.

Setup Certificates and Services

Follow the steps outlined in the Service-side setup section including; “Set Up Certificates” , “Identify the
Server Certificate” , and “Configure the Identity of the Server Hosting the Service” on the Client-side
machine.

NOTE: Setting up certificates and services on the client-side is only necessary

when the server is using a private (self-signed) certificate. If the server is using a
Trusted certificate, you do not need to set up certificates and services on the client.

Install the IBM Cognos ICM Microsoft Excel Add-in

Once all the requirements have been met, you can install the IBM Cognos ICM Microsoft Excel Add-in.

NOTE: Before installing the IBM Cognos ICM Microsoft Excel Add-in, make sure the
IBM Cognos ICM Windows Service has been stopped and restarted after the
changes to the IBM Cognos ICM Windows Service configuration file were made and
make sure the IBM Cognos ICM API Service is running.

1. Run the ICM-exceladdin installer provided in the release.

1.a Close all other applications and click Next.

1.b Specify a folder to install the Excel add-in and click Next.

1.c Click Install.

1.d Click Finish.

2. Open Excel. A quick Add-in Install will run.

3. After running the Excel Add-in, you will see a IBM Cognos ICM tab on the menu bar in Excel.

4. Click on the IBM Cognos ICM tab (see Figure 3-17).

Copyright © IBM Corporation and other(s) 2005, 2012 90

 Microsoft Excel Add-in for IBM Cognos ICM

FIGURE 3-17 IBM Cognos ICM Tab in Excel

5. To connect to a model, type in the Service Address. This is the same address that you
specified in the IBM Cognos ICM Windows Service configuration file. For example,
MobileAPI:13125.

6. Type the Sever name. This is the server name that you specified in the databaseServers
section of the IBM Cognos ICM Windows Service configuration file. For example,
SQLServer2005 (local).

7. Type the Database name. This is the name of the database containing the IBM Cognos ICM
model you want to connect to. For example, Rivacent.

8. Click Login Information.

9. Type your Username and Password for the IBM Cognos ICM Admin Client and click Save.

10. Click Import Star Schema or Import Data Store to download data into Excel from your IBM
Cognos ICM model.

NOTE: You will not be able to import a data if you are already logged in to the Admin
Client with the same login information used on the IBM Cognos ICM tab in Excel.

Copyright © IBM Corporation and other(s) 2005, 2012 91

Chapter 4: Install and Configure the IBM Cognos ICM Web Client

Overview
This chapter will walk you through the installation and configuration of the IBM Cognos ICM web client
using either Apache Tomcat, JBoss, or WebSphere deployment based on a Windows operating system. If
you are using other operating systems, the steps will be similar.

Installing the IBM Cognos ICM Web Client Using the Solaris Operating System

1. Copy the ICM.war file to your deployment location.

2. Create a directory.

3. Move the ICM.war file to the directory.

4. Unzip the ICM.war file.

5. Deploy as per Windows instructions.

This chapter also explains multi-language and unicode data support and how to configure the appearance
of the IBM Cognos ICM web client. Before you begin, note that the IBM Cognos ICM web client requires
the IBM Cognos ICM Windows service (or the Console Service tool) to be installed and running on a server
along with a IBM Cognos ICM model in order to function correctly.

Copyright © IBM Corporation and other(s) 2005, 2012 92

 Apache Tomcat Deployment

Apache Tomcat Deployment

Once Java and Tomcat have been installed, the IBM Cognos ICM web client is easily deployed via Tomcat
Manager.

Install and Configure Java

1. Download and install Java 6 JRE from the following website:

http://java.sun.com/javase/downloads/index.jsp

Install and Configure Tomcat

1. Download and install Apache Tomcat from the following website:

http://tomcat.apache.org/download-60.cgi

If you are installing the IBM Cognos ICM web client on Windows, download and run the Windows Service
Installer Tomcat distribution. If you are not installing the IBM Cognos ICM web client on Windows, install
Tomcat using the archive provided on the following website: http://tomcat.apache.org.

NOTE: When Tomcat is run as a service, there will not be a tray icon present while
Tomcat is running. An exception to this rule occurs when opting to run Tomcat at
the end of the installation process. Then the installer will create shortcuts allowing
starting and configuring Tomcat. The Tomcat Web administration application can
only be used when Tomcat is running.

Deploy the Application

You can use Tomcat Manager to deploy the IBM Cognos ICM web client. Please contact Support to obtain
the IBM Cognos ICM web client installation files.

1. Go to http://localhost:8080. Apache Tomcat runs on port 8080 by default, but if you specified a
different port number during the installation of Tomcat, navigate to that port number instead.

2. Click the Tomcat Manager link and log in using the username and password specified during
the Tomcat installation.

3. On the Tomcat Manager page in the Deploy section, click Browse.

4. Find the ICM.war file and then click Deploy (see Figure 4-1). When the page refreshes, you
will see a /ICM link under the Applications heading (see Figure 4-2).

Copyright © IBM Corporation and other(s) 2005, 2012 93

 Apache Tomcat Deployment

FIGURE 4-1 WAR File

NOTE: IBM Cognos ICM requires uniquely named WAR files when deploying the
WAR file as part of an upgrade. Clients will need to either uninstall their current
WAR file before deploying a new one or change the name of the new WAR file.

FIGURE 4-2 Tomcat Applications

5. Click on the /ICM link to verify deployment.

NOTE: When you verify the deployment, you may see an IBM Cognos ICM web
client screen containing an internal error. This indicates that the IBM Cognos ICM
web client has been deployed, but access to the IBM Cognos ICM database needs
to be configured (see Figure 4-3).

Copyright © IBM Corporation and other(s) 2005, 2012 94

 Apache Tomcat Deployment

FIGURE 4-3 Internal Error

Configure Database Access

The next section outlines how to edit the Web configuration file to point to your IBM Cognos ICM model.
Once the application has been deployed in Tomcat, the JDBC.properties file needs to be edited. It can be
found in the following default location:
C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps\ICM\WEB-INF\jdbc.properties

1. Open the JDBC.properties file using a text editor such as, WordPad (see Figure 4-4). We
recommend that you do not use Notepad since it does not understand Unix text format well.

2. Modify Server with the hostname of your SQL Server machine (e.g localhost:1433). 1433 is
the default SQL Server port, but the port number may be different if you are connecting to a
named instance (e.g. a named instance at \\DBserver\SQL2000 runs on port 2140). Use SQL
Server Configuration Manager to check the port number.

3. Modify the database name with the name of the database containing the IBM Cognos ICM
model (it is case sensitive).

4. Modify Username and password with the username and password of the desired SQL Server
account with appropriate rights to access the IBM Cognos ICM database

FIGURE 4-4 SQL Database Configuration

5. Save the updated jdbc.properties file. You may also want to save a copy of the file in an
alternate location to use for reference when the application is redeployed (e.g. when
upgrading to a newer version).

Copyright © IBM Corporation and other(s) 2005, 2012 95

 Apache Tomcat Deployment

6. Go back to Tomcat Manager and click the Reload link for /ICM to propagate the changes.

7. Go to http://localhost:8080/ICM. If your server is running IBM Cognos ICM Windows Service

with an existing IBM Cognos ICM model, all the users that have been set up in Portal Access
through the .NET client will be able to log in.

Multi-language and Unicode Data Support

In order to support UTF-8 encoding or when accessing a link that contains French accented characters,
the web server must be configured to interpret URI’s as UTF-8. If you are using Apache Tomcat as your
web server, the default is not UTF-8 so you must change this setting.

1. Go to the following location: C:\Progam Files\Apache Software Foundation\Tomcat 6.0\conf.

2. Open the server.xml file.

3. Find the Connector that is using the HTTP protocol.

4. Add the following line: URIEncoding=”UTF-8” (see Figure 4-5).

FIGURE 4-5 Server.xml Configuration

5. Save the file.

6. Restart the Apache Service.

Copyright © IBM Corporation and other(s) 2005, 2012 96

 JBoss Deployment

JBoss Deployment
The IBM Cognos ICM web client can also be deployed using JBoss. There are the following three parts to
this installation:
• Install and configure Java
• Install and configure JBoss
• Deploy the ICM WAR file and configure database access

Install and Configure Java

The latest JBoss release requires Java Software Development Kit 5.0 or higher.

1. Download and install Java SDK (JDK 6 Update 16) from the following website: http://
java.sun.com/javase/downloads/index.jsp.

Install and Configure JBoss

Once your Java environment is in place, you can go to the JBoss Web site to download the application
server.

1. Go to the following JBoss website to download the web server:

http://www.jboss.org/jbossas/downloads.

2. From the Downloads page, select the JBoss Application Server version you want to
download.

3. Download the appropriate file and extract it to the directory of your choice (see Figure 4-6).

FIGURE 4-6 Install & Configure JBoss

Copyright © IBM Corporation and other(s) 2005, 2012 97

 JBoss Deployment

Configure Database Access

The next section outlines how to edit the Web configuration file to point to your IBM Cognos ICM model.
The jdbc.properties file needs to be pre-configured so that once the application has been deployed, the
jdbc.properties file can be copied and pasted into the ICM WAR file. JBoss will not automatically expand
the IBM Cognos ICM web WAR file.

1. Navigate to the location where your IBM Cognos ICM Web WAR file is stored.

2. Rename the WAR file to ICM.zip. This allows you to navigate to within the WAR file.

3. Open the ZIP file and navigate to the WEB-INF folder.

4. Copy the jdbc.properties file.

5. Navigate back out of the ZIP folder and paste the jdbc.properties file.

6. Rename the ZIP folder back to ICM.war.

7. Open the jdbc.properties file using a text editor such as, WordPad (see Figure 4-4). We
recommend that you do not use Notepad since it does not understand Unix text format well.

8. Modify Server with the hostname of your SQL Server machine (e.g localhost:1433). 1433 is
the default SQL Server port, but the port number may be different if you are connecting to a
named instance (e.g. a named instance at \\DBserver\SQL2000 runs on port 2140). Use SQL
Server Configuration Manager to check the port number.

9. Modify the database name with the name of the database containing the IBM Cognos ICM
model (it is case sensitive).

10. Modify Username and password with the username and password of the desired SQL Server
account with appropriate rights to access the IBM Cognos ICM database

11. Save the updated jdbc.properties file. You may also want to save a copy of the file in an
alternate location to use for reference when the application is redeployed, i.e. when upgrading
to a newer version.

Deploy the IBM Cognos ICM Web Client

After Java and JBoss have been installed and the jdbc.properties file has been configured, the IBM
Cognos ICM web client needs to be manually deployed. Please contact Support to obtain the IBM Cognos
ICM web client installation files. JBoss will not automatically deploy the WAR file, so a few steps need to be
followed to configure the IBM Cognos ICM web client.

Copyright © IBM Corporation and other(s) 2005, 2012 98

 JBoss Deployment

1. Create a file called jboss-web.xml and save this in an accessible location. It is a good idea to
save this file with your ICM.war file and your preconfigured jdbc.properties file.

1.a Using WordPad or a similar application, copy the following text into the jboss-web.xml
file:

<jboss-web>
<!--Uncomment the security-domain to enable security. You will need to edit the
htmladaptor login configuration to setup the login modules used to authenticate users.
<security-domain>java:/jaas/jmx-console</security-domain>
-->
</jboss-web>

1.b Save the jboss-web.xml file.

2. Copy the version of the desired WAR file into \jboss-[version].GA\server\default\deploy\. You
may rename the WAR file to something other than ICM for usability.

3. Change the file extension from .war to .zip. This allows you to navigate within the file to
\WEB-INF.

4. Replace the jdbc.properties file with the pre-configured jdbc.properties file.

5. Paste the jboss-web.xml file into the WEB-INF folder.

6. In \jboss-[version].GA\server\default\deploy, change the file extension from .zip back to .war.

7. Start JBoss by running the run.bat file, which can be found in the following location:
.......jboss-[version].GA\bin\run.bat

8. Navigate to http://localhost:8080/ICM, where ICM is the name of the WAR file (see Figure 4-
7).

Copyright © IBM Corporation and other(s) 2005, 2012 99

 JBoss Deployment

FIGURE 4-7 Local Host

Multi-language and Unicode Data Support

In order to support UTF-8 encoding or when accessing a link that contains French accented characters,
the web server must be configured to interpret URI’s as UTF-8. If you are using JBoss as your web server,
the default is not UTF-8 so you must change this setting.

1. Go to the following location: C:\Progam Files\JBoss\jboss-

[version].GA\server\default\deploy\jboss-web.deployer\

2. Open the server.xml file.

3. Find the Connector that is using the HTTP protocol.

4. Add the following line: URIEncoding=”UTF-8”

<Connector port="8080" address="${jboss.bind.address}"

maxThreads="250" maxHttpHeaderSize="8192"
emptySessionPath="true" protocol="HTTP/1.1"
enableLookups="false" redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true" URIEncoding="UTF-8"
/>

5. Save the file.

6. Restart the Web Service.

Copyright © IBM Corporation and other(s) 2005, 2012 100

 WebSphere Deployment

WebSphere Deployment
After installing and configuring WebSphere, you will need to install the IBM Cognos ICM WAR file and
configure the JDBC properties file.

NOTE: IBM Cognos ICM supports WebSphere version 7+.

Download the IBM Cognos ICM Web Application

Please contact Support to obtain the IBM Cognos ICM Web installation files.

1. Log in to the Admin Console and select Applications.

2. Select New Applications.

3. Select New Enterprise Application.

4. Browse to the WAR file you wish to deploy and click Next.

5. Select Detailed - Show all installation options and parameters and click Next.

6. Click Continue on the Application Security Warning screen.

7. Specify Application name, e.g. ICM730 (see Figure 4-8).

8. Highlight All File Permissions and click Next (see Figure 4-8).

Copyright © IBM Corporation and other(s) 2005, 2012 101

 WebSphere Deployment

FIGURE 4-8 WebSphere Installation Options

9. On Step 2, check the select box and click Next.

10. On Step 3, click Next.

11. On Step 4, check the select box that corresponds with the current application and click Next.

12. On Step 5, check the select box that corresponds with the current application and click Next.

13. On Step 6, check the selection box and click Next.

14. Specify a unique context root for the WAR file, e.g. /ICM730, and click Next.

15. Click Finish on the Summary page.

16. Click Save.

17. Select Servers > Server Types > WebSphere application server > server_name > Java
and Process Management > Process Definition > Java Virtual Machine > Custom
Properties.

18. Click New.

19. Specify the name as java.awt.headless and set the value to False (see Figure 4-9).

Copyright © IBM Corporation and other(s) 2005, 2012 102

 WebSphere Deployment

20. Click Apply, then click OK.

FIGURE 4-9 Java Custom Property

21. Select the Save directly to the master configuration option.

Configure Database Access

After deploying the WAR file, you will need to edit the jdbc.properties file in two locations to configure
database access.

For Windows systems, the file can be found in the following locations:
• C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\ [server
name]Node01Cell\ applications\CONTEXT ROOT_war.ear\deployments\CONTEXT
ROOT_war\CONTEXT ROOT.war\WEB-INF
• C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\installedApps\..\..\
ICM.war\WEB-INF
For Unix-like systems, the file can be found in the following locations:
• /AppServer/profiles/AppSrv01/installedApps/../../ICM.war/WEB-INF
For example,
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/installedApps/../../ICM.war/WEB-INF
• /AppServer/profiles/AppSrv01/config/cells/../applications/.../deployments/../../WEB-INF
For example,
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/../applications/.../deployments/
../../WEB-INF

1. Open the jdbc.properties file using a text editor such as, WordPad (see Figure 4-4). We
recommend that you do not use Notepad since it does not understand Unix text format well.
Copyright © IBM Corporation and other(s) 2005, 2012 103
 WebSphere Deployment

2. Modify Server with the hostname of your SQL Server machine (e.g localhost:1433). 1433 is
the default SQL Server port, but the port number may be different if you are connecting to a
named instance (e.g. a named instance at \\DBserver\SQL2000 runs on port 2140). Use SQL
Server Configuration Manager to check the port number.

3. Modify the database name with the name of the database containing the IBM Cognos ICM
model (it is case sensitive).

4. Modify Username and password with the username and password of the desired SQL Server
account with appropriate rights to access the IBM Cognos ICM database

5. Save the updated jdbc.properties file. You may also want to save a copy of the files in an
alternate location to use for reference when the application is redeployed, i.e. when upgrading
to a newer version.

Start the Web Application Using the Admin Console

1. Log in to the Admin Console.

2. Select Applications > Application Types > WebSphere enterprise applications.

3. Select the IBM Cognos ICM application.

4. Click Start.

NOTE: If you forget the associated context root, select the application name. Select
the Context Root for Web Modules option.

5. Open an internet browser on your local computer.

6. Navigate to the IBM Cognos ICM web client login page. For example: http://server:9080/
CONTEXT ROOT/login.html

Set a Web Container Custom Property on Websphere

To avoid the IBM Websphere error “Error 404:SRVEO19OE:File not found: /j_spring_security_check”
when attempting to log in to the IBM Cognos ICM web client, the following property must be set to true:
com.ibm.ws.webcontainer.invokefilterscompatibility = true.

1. In the administrative console, click Servers > Application Servers.

2. Click on the server to which the custom property is to be applied.

Copyright © IBM Corporation and other(s) 2005, 2012 104

 Property File Encryption

3. Under Configuration > Container Settings, select Web Container Settings > Web
Container.

4. Under Configuration > Additional Properties, select Custom Properties.

5. In the Custom Properties page, click New.

6. In the Settings page, type the name of the custom property to be added in the Name field and
the value to be set for the custom property in the Value field.

NOTE: Some properties are case-sensitive.

7. Click Apply or OK.

8. Restart the server for the custom property to take effect.

Multi-language and Unicode Data Support

In order to support UTF-8 encoding or when accessing a link that contains French accented characters,
the web server must be configured to interpret URI’s as UTF-8. If you are using WebSphere as your web
server, the default is not UTF-8 so you must change this setting.

1. Go to the following location: C:\Progam Files\IBM\WebSphere\AppServer\properties\

2. Open the encoding.properties file.

3. Replace “en=ISO-8859-1” with “en=UTF-8”

4. Save the file.

5. Restart the Web Service.

Property File Encryption

The IBM Cognos ICM web client can be configured to accept encrypted passwords across all properties
files, such as the jdbc.properties and ldap.properties files.

This provides additional local security in the form of obfuscation. Keep in mind that someone must still
have knowledge of the encryption key and passwords are transmitted in plain text, unless transmission
security, e.g. SSL, is enabled.

Copyright © IBM Corporation and other(s) 2005, 2012 105

 Password Encryption

Password Encryption
Encrypted strings can be obtained for the passwords to be secured using the Java Simplified Encryption
(Jasypt) toolset.

1. Download the latest Jasypt distribution.

2. Unzip the archive to a location that is easily accessible via command line, e.g. the Desktop.

3. Make sure the JAVA_HOME environment variable is set and points to the installed Java
distribution folder.

4. Open a command prompt window and navigate to the unzipped Jasypt folder.

The following image shows how property file encryption works within IBM Cognos ICM (see Figure 4-10).
In this example, the password is “secret” and the chosen encryption password is “varicent”. The encrypted
password will be substituted into the appropriate properties file using the following syntax:
ENC(1qZZsaIYYVQllTsjITcqfg==)

FIGURE 4-10 Property File Encryption

NOTE: If only Java 5 is available, users will also have to download ICU4J and
include the JAR when running the Jasypt CLI tools.

IBM Cognos ICM Web Configuration

The IBM Cognos ICM web client must be configured to understand property files containing encrypted
values. The applicationContext.xml file looks like the following before configuration (see Figure 4-11):

Copyright © IBM Corporation and other(s) 2005, 2012 106

 Password Encryption

FIGURE 4-11 Before IBM Cognos ICM Web Configuration

1. Open the applicationContext.xml file.

2. Uncomment the non-highlighted lines and comment out the highlighted lines (see Figure 4-
12).

Copyright © IBM Corporation and other(s) 2005, 2012 107

 Password Encryption

FIGURE 4-12 IBM Cognos ICM Web Configuration

Configure IBM Cognos ICM Web Client in a Windows Environment

A system environment variable containing the encryption password needs to be set before deployment so
the IBM Cognos ICM web client knows how to decrypt the encrypted passwords.

1. Right-click on My Computer and select Properties.

2. Navigate to the Advanced tab and click Environment Variables.

3. Under System Variables, click New.

4. Type VARICENT_KEY in the first field and your password in the second field.

5. Click OK to apply all changes.

6. If the Web application container service is configured to run under the Windows Local System
user account, Windows will need to be restarted.

Copyright © IBM Corporation and other(s) 2005, 2012 108

 Multi-language & Unicode Data Support

Deployment
To deploy the IBM Cognos ICM web client, the appropriate property file needs to be configured with the
encrypted passwords (see Figure 4-13).

FIGURE 4-13 Deployment

After saving the file, you will need to restart your the IBM Cognos ICM web application service (e.g.
Apache Tomcat service) for the changes to take effect. At this point, the environment variable containing
the encryption key can be removed.

Multi-language & Unicode Data Support

Users can set their locale on the IBM Cognos ICM web client with a URL parameter equal to a two- or four-
letter code that only needs to be passed once on any page.
For example, http://hostname/ICM/home.html?locale=fr to switch to French.

The following languages are available:

• English: en [Default]
*this will also set the language to English and the date format to mm/dd/yyyy*
• English: en_GB
*this will set the language to English and the date format to dd/mm/yyyy*
• French: fr
• German: de
Copyright © IBM Corporation and other(s) 2005, 2012 109
 Email Users when an Inquiry is Pending

• Spanish: es_ES
• Japanese: ja
• Chinese Simplified: zh_CN
• Chinese Traditional: zh_TW
• Korean: kr
• Italian: it
• Brazilian Portuguese: pt_BR
• Mexican Spanish: es_MX
• Turkish: tr
• Dutch: nl
• Swedish: sv
The following database types can technically be supported:
• SQL Server 2005, SQL Server 2005 Unicode
• SQL Server 2008, SQL Server 2008 Unicode
• SQL Server 2012, SQL Server 2012 Unicode
To enable Multi-language and Unicode data support, you need to edit the database type in both the IBM
Cognos ICM Windows Service.exe.config and the jdbc.properties files.

1. In IBM Cognos ICM Windows Service.exe.config:

<add key=”DBType” value=”SQLServer2005Unicode”/>

2. In jdbc.properties:
jdbc.productName=sqlserverunicode

Email Users when an Inquiry is Pending

You can choose to have an email sent automatically to the designated inquiry handler when an inquiry is
launched in the IBM Cognos ICM web client. You will need to configure settings in the admin client and the
IBM Cognos ICM web configuration files in order to have the email sent to the correct user after an inquiry
is launched.

1. Configure the email settings in the mail.properties file. The mail.properties file is located in
the following directory: ...\webapps\ICM\WEB-INF

NOTE: You will need to reload the ICM.war file after making changes to the
configuration files.

Copyright © IBM Corporation and other(s) 2005, 2012 110

 Prevent Presenter from Loading with a Large Amount of Data

2. In the admin client, go to Admin > Administrative options, and click on the Portal Access
tab.

3. Select the Email users when an inquiry is pending checkbox.

4. Click OK.

Prevent Presenter from Loading with a Large Amount of Data

By configuring the reporting.properties file in the WEB-INF folder of the IBM Cognos ICM WAR file, you
can limit the amount of rows displayed by an aggregate transformation in the IBM Cognos ICM web client.
If a Presenter report contains an aggregate transformation used by a data grid, chart, map, or pick list
control, and the aggregate transformation exceeds the row limit set in the reporting.properties file, the
report will not be displayed in the IBM Cognos ICM web client. By default, the value is set to ‘0’, which
means there is no limit to prevent the report from rendering.

1. Navigate to the WEB-INF folder in the ICM.war file.

2. Open the reporting.properties file.

3. Change the reporting.aggregateTransformationRowLimit value to the maximum number of

rows the aggregate transformation source can contain to allow the Presenter report to be
rendered.

FIGURE 4-14 Reporting Properties File

4. Restart the web server application that the IBM Cognos ICM web client is running on.

Copyright © IBM Corporation and other(s) 2005, 2012 111

 Changing the Appearance of the IBM Cognos ICM Web Client

Changing the Appearance of the IBM Cognos ICM Web Client

Tab Configuration
In the Portal Access module in the Admin Client, administrators can customize the tabs that appear in the
IBM Cognos ICM web client. They can select the name, type, and sequence of tabs. This allows for
administrators to build report-driven home pages that are appropriate for different Portal Access groups.

Web tabs can be created for individual plans, Presenter and tailored reports, and web forms. Module tabs
can also be created by selecting either Data Edit, Inquiries, Payee Ledger, Reporting, or Web Forms.
Users can organize tabs into web tab groups, which will create sub-tabs in the IBM Cognos ICM web client
(see Figure 4-15).

The following Web Tabs are available:

• Compensation Plan
• Draw Assignment
• Draw Report
• Module
• Data Edit
• Inquiries
• Payee Ledger
• Reporting
• Web Forms
• Presenter Report
• Tailored Report
• Web Form

Copyright © IBM Corporation and other(s) 2005, 2012 112

 Changing the Appearance of the IBM Cognos ICM Web Client

FIGURE 4-15 IBM Cognos ICM Web Tabs

When only one object is assigned to a web tab, no sub-tabs are shown, and the plan, report, or form is
rendered right away. When more than one object is assigned to a tab group, sub-tabs appear, and
selection is required before anything is rendered. After web tabs are created, administrators must assign
access to the tab itself and the objects that are included in the tab. If users do not have access to the web
tab or the sub-tabs, then they will not see them in the IBM Cognos ICM web client.

NOTE: If you are upgrading your 6.0 model to 7.0, the tabs you have already set up
will appear in Portal Access and the IBM Cognos ICM web client.

Create a Web Tab

You must add web tabs in Portal Access so users can see them in the IBM Cognos ICM web client.

1. In Portal Access, click the Web Tabs tab.

2. Click the Add Web Tab icon or right-click on the screen and select Add Web Tab.

3. Name the web tab.

4. Select the Type of web tab.

Copyright © IBM Corporation and other(s) 2005, 2012 113

 Changing the Appearance of the IBM Cognos ICM Web Client

5. Select the object that is assigned to the type of web tab. For example, if you select the
Compensation Plan type, you need to select a compensation plan (see Figure 4-16).

6. Click Finish.

NOTE: The first tab listed in Portal Access is the first tab that will be displayed on
the IBM Cognos ICM web client.

FIGURE 4-16 Web Tab Type

Move Web Tabs

You can change the order and placement of web tabs after you have created them.

1. In Portal Access, click the Web Tabs tab.

2. Press the Shift key and drag-and-drop the web tab to the location you want.

Copyright © IBM Corporation and other(s) 2005, 2012 114

 Changing the Appearance of the IBM Cognos ICM Web Client

Edit a Web Tab

After creating a web tab, you can modify the name, type, and object assigned to it.

1. In Portal Access, click the Web Tabs tab.

2. Right-click on a web tab and select Edit Web Tab.

3. Make your changes and click Finish.

Delete a Web Tab

You can remove web tabs that are no longer needed.

1. In Portal Access, click the Web Tabs tab.

2. Right-click on a web tab and select Delete.

Add a Web Tab Group

You can organize tabs into web tab groups.

1. In Portal Access, click the Web Tabs tab.

2. Click the Add Web Tab Group icon or right-click on the screen and select Add Web Tab
Group.

3. Double-click on the New Web Tab Group and type in a name.

4. Click on a web tab and drag it to the web tab group (see Figure 4-17).

FIGURE 4-17 Web Tab Group

Copyright © IBM Corporation and other(s) 2005, 2012 115

 Changing the Appearance of the IBM Cognos ICM Web Client

Remove a Web Tab From a Group

You can move a web tab from one group to another.

1. In Portal Access, click on the Web Tabs tab.

2. Click on a web tab and move it above the web tab group while holding down the Shift key.

Set Access to Web Tabs

The user needs access to both the web tab and the objects inside. For example, if you have a Reporting
web tab, you need to set access to the Reporting web tab and to the individual Presenter reports.

1. In Portal Access, click on the Assignment tab.

2. Click your mouse under a column to show the dropdown menu arrow.

3. From the dropdown menu, select the Access tree for the web tab (see Figure 4-18).

FIGURE 4-18 Web Tab Access

Themes
The color scheme and logo displayed at the top of the screen in the IBM Cognos ICM web client can be
customized.

1. In the Admin Client, select Tools > Themes.

2. Check the Enable Custom Header box (see Figure 4-19).

Copyright © IBM Corporation and other(s) 2005, 2012 116

 Changing the Appearance of the IBM Cognos ICM Web Client

FIGURE 4-19 Themes

3. Browse for the desired image.

3.a When the logo is displayed in the header preview, you can click-and-drag the image to
the desired location on the header.

4. Select either Standard or Salesforce.com for the Web Theme.

5. Click OK.

NOTE: Changes made here will be effective on both the Admin Client and the IBM
Cognos ICM Web screens. The web deployment may need to be reloaded for the
custom header to take effect on the IBM Cognos ICM web client.

Copyright © IBM Corporation and other(s) 2005, 2012 117

Chapter 5: Authentication and Sign On

Overview
This chapter examines communication and authentication options and explains SiteMinder, Open SSO,
and LDAP configuration for IBM Cognos ICM web client authentication.

IBM Cognos ICM Communication Path Options

IBM Cognos ICM consists of the following components and various communication options are available
between each:
• Admin Client
• Application Server
• Database Server
• Web Server
• IBM Cognos ICM web client

IBM Cognos ICM Admin Client to Application Server

The following security options are available in the IBM Cognos ICM Windows Service configuration file:

1. TLS Security – communication encryption

<!-- Transport Layer Security Mode -->
<!--Clients are unauthenticated by WCF when using TLS. Server must provide a trusted certificate to
authenticate itself-->
<add key="SecurityMode" value="TLS"/>
<add key="ServiceCertificateName" value="varicent.com"/>

2. Windows Domain – trusted network

<!-- Windows Security Mode -->
<!--Clients and servers are authenticated via Kerberos using the domain controller as a trusted 3rd
party. No certificates required.-->
<add key="SecurityMode" value="Windows"/>

Copyright © IBM Corporation and other(s) 2005, 2012 118

 IBM Cognos ICM Communication Path Options

3. No Security – no security
<!-- Unprotected Security Mode -->
<!--Set security mode="None" on both client and server to disable all security. -->
<add key="SecurityMode" value="None"/>

IBM Cognos ICM Application Server to Database Server

1. Trusted Network
Traditionally, both the Web application server and the database server are on the same trusted
network and channel encryption is not used.

2. Trusted Network and SSL

Our JDBC connector from the Web application to the database can optionally be configured to
use SSL to encrypt communication.

Web Client to IBM Cognos ICM Web Application

1. Traditional HTTP – un encrypted communication

Traditional HTTP is the default communication setting used for communication between the
Web client and the IBM Cognos ICM Web application.

2. Secure HTTP (HTTPS) – encrypted communication

Encrypted communication can be achieved using an SSL Certificate that is installed on the
Web Server.

IBM Cognos ICM Web Application to Database Server

1. Trusted Network
Traditionally, both the Web application server and the database server are on the same trusted
network and channel encryption is not used.

2. Trusted Network and SSL

Our JDBC connector from the Web application to the database server can optionally be
configured to use SSL to encrypt communication.

Copyright © IBM Corporation and other(s) 2005, 2012 119

 Authentication Options

Authentication Options
IBM Cognos ICM offers the following authentication options:

1. Native – IBM Cognos ICM-specific logins are determined in Portal Access, not single sign on
(SSO).

2. LDAP Directory – Typically, Microsoft Active Directory integration, which allows users to use
their network credentials to log in, but does not do so automatically.

3. Any SAML 2 compliant SSO resource (e.g. CA SiteMinder, Sun OpenSSO, PingIdentity) –
IBM Cognos ICM natively supports SAML2 authentication, automatically authenticating users
who have a SAML2 compliant credentialing resource. SSO is a method of access control that
enables a user to log in once and gain access to the resources of multiple software systems
without being prompted to log in again.

4. Custom SSO – Some clients have developed their own custom authentication options. These
are not supported directly by IBM Cognos ICM.

SiteMinder Configuration

NOTE: SiteMinder allows customers to manage users and privileges in an external

repository, including an LDAP directory. For more information on this, please
contact a IBM Cognos ICM Client support representative.

Configure the IBM Cognos ICM Web Client for CA SiteMinder

In order to use SiteMinder to access the IBM Cognos ICM web client, SiteMinder administrators will need
to make sure that the IBM Cognos ICM web client is included in the SiteMinder domain.

Once IBM Cognos ICM has been added to the domain, the IBM Cognos ICM web client web.xml file and
siteminder.properties configuration files need to be edited. The files can be found in the following default
location: C:\...\webapps\ICM\WEB-INF

1. Open web.xml in a text editor.

2. Change security.xml to security-siteminder.xml (see Figure 5-1).

Copyright © IBM Corporation and other(s) 2005, 2012 120

 SiteMinder Configuration

FIGURE 5-1 Sign on Security

3. In the siteminder.properties file, define what property is being used for authentication
purposes.

By default, IBM Cognos ICM looks at the SM_USER attribute in the SiteMinder header and matches the
Email field to the Email field in the IBM Cognos ICM Payee table. If you wish to use a different column for
authentication, change the siteminder.userKeyColumn value (see Figure 5-2).

FIGURE 5-2 SiteMinder Properties

4. Save web.xml and siteminder.properties.

5. Restart the IBM Cognos ICM web client via your web server’s management console. Users
will be able to log in to the IBM Cognos ICM web client with their CA SiteMinder
authentication.

Accessing the IBM Cognos ICM Web Client with SiteMinder Configured
To access the IBM Cognos ICM web client, users will go to the SiteMinder site and enter their username
and password. Once they are logged on to SiteMinder, they can navigate to the IBM Cognos ICM web
client home page without having to retype their login credentials.

The SiteMinder administrator may provide a link that takes users directly to the IBM Cognos ICM web
client home page from the SiteMinder site. If no link is provided, users can navigate to the IBM Cognos
ICM web client home page themselves after logging in to SiteMinder.

Copyright © IBM Corporation and other(s) 2005, 2012 121

 OpenSSO Configuration

Keep in mind that the URL used to navigate to the IBM Cognos ICM web client should take users directly
to the IBM Cognos ICM web client home page (or another post-authentication screen) and not the IBM
Cognos ICM web client login screen (i.e.http://....home.html and not http://….login.html). If users go to the
IBM Cognos ICM web client pre-authentication screen, they will be prompted to re-enter their username
and password.

OpenSSO Configuration

How it Works
IBM Cognos ICM natively supports authentication via Sun OpenSSO, a SAML 2 compliant identity
provider. The following diagram depicts how the SAML 2 language and the OpenSSO sign on solution
work to authenticate IBM Cognos ICM users in an IBM Cognos ICM On Demand environment (see
Figure 5-3).

NOTE: IBM Cognos ICM natively supports all SAML 2 compliant identity providers,
so while this document uses the OpenSSO example, the following diagram also
applies to other SAML 2 compliant identity providers.

OpenSSO can be deployed on a wide range of platforms and application containers including the
following:
• Sun Glassfish – a free and fully J2EE compliant application server
• Apache Tomcat – the easiest to configure

This document covers the installation of OpenSSO in a Tomcat environment.

Copyright © IBM Corporation and other(s) 2005, 2012 122

 OpenSSO Configuration

FIGURE 5-3 SAML2 Authentication

Download and Install OpenSSO

Before you begin, download the latest version of OpenSSO, as well as Apache Tomcat and Java. For
example, download the following:
• Java 6 Development Kit
• Apache Tomcat 6
• OpenSSO Enterprise 8

Once Java and Tomcat are installed and running, perform the following steps:

1. Set Tomcat's initial and maximum memory pool to 1024 MB.

2. Navigate to Tomcat Manager and deploy the opensso.war file found in the opensso/
deployable-war folder of the OpenSSO distribution.

Copyright © IBM Corporation and other(s) 2005, 2012 123

 OpenSSO Configuration

3. Navigate to http://ssohost.domain.com:8080/opensso and begin the OpenSSO configuration

wizard.

OpenSSO Configuration
When the OpenSSO configuration wizard is finished complete the following step:

1. Log in to the OpenSSO administration area using amadmin.

NOTE: Keep in mind that all URLs submitted must contain fully qualified domain
names, e.g. host.domain.com. Short names, e.g. localhost or host, are
unacceptable.

2. A user data store, such as Microsoft Active Directory, can be specified here. OpenSSO
provides a built-in service for development and testing use only. For production, Sun's
free OpenDS is recommended if no existing data store is available. The built-in service can be
used temporarily for this deployment until an external data store can be properly configured at
a later time.

NOTE: Additional information on OpenSSO installation can be found on the Sun

website at http://docs.sun.com.

Identity Provider (IDP) Configuration

Keystore Setup
See the OpenSSO Keystore Setup page on the Sun’s website for instructions:
http://docs.sun.com/app/docs/doc/820-3748/gghyy?a=view.

OpenSSO provides a default test key for testing purposes. This key should not be used in production.

Create and Configure IDP

1. From the Common Tasks tab under the Create SAMLv2 Providers heading, click Create
Hosted Identity Provider.

2. The IDP name should already be populated. Select the signing key imported previously.

3. Choose a name for the new circle of trust.

4. Map an attribute to use as the SAML NameID. This is usually the user's email address (the
mail attribute).

Copyright © IBM Corporation and other(s) 2005, 2012 124

 OpenSSO Configuration

5. Click Configure > Finish.

NOTE: If an external user data store was not specified in the OpenSSO
configuration wizard, a test user will need to be added through the OpenSSO
administration interface. The demo account can be used, but an email address will
still need to be entered in the user's profile.

Service Provider (SP) Configuration

First Steps
Before the IBM Cognos ICM web client can be deployed as a SAML service provider (SP), the following
three things must be obtained from the identity provider (IDP):
• IDP SAML meta data file (usually idp.xml)
• SSL keystore file (usually keystore.jks)
• Signing key credentials in keystore (alias and password)

Begin by deploying the ICM.war file in the web application server.

Endorsed Libraries
The IBM Cognos ICM web client’s SAML implementation requires the use of more advanced XML
components than what is available in the standard library. To use these components, the Java Virtual
Machine needs to be configured. The Java platform allows end users to override standard libraries through
the Endorsed Standards Override Mechanism, where the required libraries are copied into a special,
endorsed folder.

Tomcat Version 6+ Configuration

1. Create a new folder called common in the main Tomcat folder.

2. Copy the deployed <Tomcat Path>/webapps/ICM/WEB-INF/endorsed folder to the main

Tomcat folder, so that the endorsed files are in <Tomcat Path>/common/endorsed.

3. Restart the Tomcat service.

IBM Cognos ICM Configuration

1. Configure database access in the jdbc.properties file.

Copyright © IBM Corporation and other(s) 2005, 2012 125

 OpenSSO Configuration

2. Edit web.xml and change security.xml to security-saml.xml.

3. Copy the idp.xml and keystore.jks files obtained from the IDP to the deployed/ICM/WEB-
INF/saml folder.

4. Edit saml.properties.

5. Replace the signing key placeholders with the key alias and password obtained from the IDP.

6. Choose the appropriate Payee table column (specified by saml.userKeyColumn) if you are
not using an email address as the SAML NameID.

7. Reload IBM Cognos ICM.

Register IBM Cognos ICM as Service Provider

1. From the Common Tasks tab, under the Create SAMLv2 Providers heading, click Register
Remote Service Provider.

2. Enter the IBM Cognos ICM SAML meta data URL (see note below) in the first field. Make sure
it is added to the existing circle of trust, e.g. ICM, that was created when the IDP was
configured (this option is typically selected by default).

3. Verify that the service is running by navigating to the URL in a browser.

NOTE: The meta data URL, by default, is available in the /saml/metadata

subdirectory from the installed IBM Cognos ICM deployment. A typical deployment
matches the following pattern: http://<server name>/ICM/saml/metadata

4. Add the same attribute mapped in the IDP configuration (this is usually the mail attribute).

Verify the IBM Cognos ICM Login

1. Navigate to http://<server name>/ICM. The browser should automatically be redirected to the

OpenSSO login screen.

2. Log in. Once a user has been successfully authenticated by OpenSSO, the browser will
redirect to the IBM Cognos ICM web client home page.

NOTE: The signed-in user can log out of the IBM Cognos ICM web client, but will not
be logged out of single sign-on (SSO) until they log out of the IDP. This means that
logging out of the IBM Cognos ICM web client and immediately returning to any IBM
Cognos ICM view will automatically log the user back in.

Copyright © IBM Corporation and other(s) 2005, 2012 126

 LDAP Configuration

LDAP Configuration
For a streamlined log in process, LDAP can be used to define access to the IBM Cognos ICM web
application. The IBM Cognos ICM web client can be configured to retrieve user authentication information
from an LDAP directory with the following LDAP providers:
• Microsoft® Active Directory, Windows® 2000 with Service Pack 4
• Microsoft Active Directory, Windows 2003
• Open LDAP 2.0.27

NOTE: LDAP can be used to obtain user login credentials for the IBM Cognos ICM
web client, but it is not a SSO solution. IBM Cognos ICM web users will still need to
enter login credentials to access the web application.

Validation Requirements
The LDAP column that is being mapped to IBM Cognos ICM for validation needs to contain data that
matches the corresponding column in IBM Cognos ICM. By default, IBM Cognos ICM looks at the mail
attribute in the LDAP directory for validation and matches this field to the email address field in the Payee
table. If email addresses are being used by the IBM Cognos ICM web client for user validation, the payee
email addresses that are loaded in the IBM Cognos ICM Payee table must be identical to the email
addresses that are loaded in the LDAP directory.

LDAP Configuration
To setup the IBM Cognos ICM web application to use LDAP user authentication, you need to modify the
following two configuration files located on the Web server:

1. ldap.properties

2. web.xml

This will allow IBM Cognos ICM to obtain login credentials from the LDAP directory. By default these files
can be found in the following location: C:\Program Files\...\webapps\ICM\WEB-INF\

ldap.properties
The ldap.properties file defines the configuration details, such as the LDAP server name and the manager
password. Changes made to this file allow IBM Cognos ICM to connect to the client’s LDAP directory.

Copyright © IBM Corporation and other(s) 2005, 2012 127

 LDAP Configuration

1. Enter the LDAP server URL, as well as the port number that is used by the LDAP server. If the
DC\=yourdomain,DC\=com is not specified here, then it should be specified in the
ldap.managerDn line: ldap.providerUrl=ldap://localhost:389/dc=example,dc=com

Specifying Distinguished Names (Dn) in the ldap.properties File

The LDAP manager username and password are defined here – cn refers to the common name, e.g. Jane
Doe, and ou refers to the organizational unit.
ldap.managerDn=cn=Administrator,ou=Users
ldap.managerPassword=secret

When configuring the IBM Cognos ICM web client to use LDAP authentication, it is often best to use the
full distinguished name (Dn) for the managerDn and userSearchBase attributes.
ldap.managerDn=cn=Administrator,ou=Users,dc=example,dc=com
ldap.userSearchBase=ou=Accounts,dc=example,dc=com

NOTE: The DC components are specified in these strings. If you are using full Dns
that specify the DC components in the managerDn and userSearchBase strings,
you should not specify the DC components in the providerUrl string as well.

For example, use the following: ldap.providerUrl=ldap://localhost:389 and NOT the following:
ldap.providerUrl=ldap://localhost:389/dc=example,dc=com

2. Define the root of the user search tree. This information is specific to the client's LDAP setup,
and should be provided by their LDAP expert.
ldap.userSearchBase=ou=Accounts

3. The userSearchFilter field can be used to limit the search to the members of the group. This
field should not have to be changed.
ldap.userSearchFilter=(sAMAccountName={0})

4. Map the LDAP mail attribute internally to the appropriate column. Typically, the mail attribute
maps to email and should not have to be changed.
ldap.userKeyAttribute=mail
ldap.userKeyColumn=Email

Web.xml

1. In the Web.xml file, change /WEB-INF/security.xml to /WEB-INF/security-ldap.xml to enable

LDAP authentication (see Figure 5-4).

Copyright © IBM Corporation and other(s) 2005, 2012 128

 LDAP Configuration

FIGURE 5-4 Idap Security

2. Save web.xml and ldap.properties.

3. Restart the IBM Cognos ICM web client. Users will be able to log in to the IBM Cognos ICM
web client with the authentication credentials stored in the LDAP directory.

Copyright © IBM Corporation and other(s) 2005, 2012 129

Chapter 6: Integration

Overview
This chapter examines how to configure the IBM Cognos ICM web client so that it is integrated with or
accessible through external applications, such as salesforce.com.

Configuring the IBM Cognos ICM Web Client for Salesforce

After installing the IBM Cognos ICM web client, the web.xml web configuration file needs to be modified in
order for the IBM Cognos ICM web client to be accessible through salesforce.com. After deploying the IBM
Cognos ICM web client perform the following steps:

1. Navigate to the web.xml file found, by default, in the following location:

C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\ICM\WEB-INF

2. In the Parameters section, change security.xml to security-salesforce-composite.xml (see

Figure 6-1).

FIGURE 6-1 Web.xml File

3. After saving the file, restart the IBM Cognos ICM web client for the changes to take effect.

Copyright © IBM Corporation and other(s) 2005, 2012 130

 Accessing IBM Cognos ICM from Salesforce.com

Accessing IBM Cognos ICM from Salesforce.com

Perform the following steps to have the IBM Cognos ICM application accessible from a tab within
Salesforce:

1. Log in to salesforce.com with a user ID that has administrative rights.

2. Select the Setup link from the top of the screen (see Figure 6-2).

FIGURE 6-2 Log in to Salesforce.com

3. From the left pane, select Create > Tabs from the App Setup section (see Figure 6-3).

FIGURE 6-3 App Setup

4. Click New in the Web Tabs section (see Figure 6-4). This will allow you to create a custom tab
that displays IBM Cognos ICM content inside the Salesforce window.

FIGURE 6-4 Web Tabs

5. You have the option of using the full page width to display the IBM Cognos ICM application or
having the Salesforce sidebar displayed.

Copyright © IBM Corporation and other(s) 2005, 2012 131

 Accessing IBM Cognos ICM from Salesforce.com

FIGURE 6-5 Tab Layout

6. Click Next once you have made your selection.

7. Define the content and display properties for the IBM Cognos ICM tab (see Figure 6-6) by
doing the following:
• In the Tab Content Definition section, select URL from the Tab Type menu.
• In the Tab Label field, enter the text that you want displayed on the label.
• In the Tab Name field give the tab a unique name – this can be the same as the tab label.
• Choose the color of your tab by selecting a Tab Style from the styles screen.
• The Content Frame Height field allows you to indicate how tall (in pixels) the IBM Cognos
ICM content frame will be. A frame height of at least 800 pixels is recommended.

Copyright © IBM Corporation and other(s) 2005, 2012 132

 Accessing IBM Cognos ICM from Salesforce.com

FIGURE 6-6 Tab Content

8. You also have the option of enabling the IBM Cognos ICM tab for mobile use, specifying a
custom splash page, and entering a description for the tab. These fields, however, are not
mandatory.

9. Press the Next button when you are done entering the tab content definition and display
properties information.

10. From the URL details screen, define the address of the IBM Cognos ICM web application on
the web application server where IBM Cognos ICM has been deployed. There is no need to
define merge fields on this screen.

11. Enter the URL for the Home page of the IBM Cognos ICM web application and select Unicode
encoding.

If the IBM Cognos ICM web client is deployed at https://localhost8080/ICM, the IBM Cognos ICM web
client URL for Salesforce will be the same as the following:
https://localhost:8080/ICM/sforce_composite_login?SessionId={!API.Session_ID}
&ServerURL={!API.Partner_Server_URL_100}

NOTE: You must include the underscores in the URL.

12. Click Next when complete.

13. From the Add to Profiles screen, you can choose the user profiles that will be able to see the
new IBM Cognos ICM tab.

14. From the Add to Custom Apps page, you can choose the custom apps for which the new
IBM Cognos ICM tab will be visible.

Copyright © IBM Corporation and other(s) 2005, 2012 133

 Integrate the IBM Cognos ICM Web Client with Oracle CRM

15. Click Save. The IBM Cognos ICM application should now be accessible from the newly
created tab.

Integrate the IBM Cognos ICM Web Client with Oracle CRM
Oracle users can install an IBM Cognos ICM tab, allowing direct access to IBM Cognos ICM from the
Oracle CRM site. Users that are logged into Oracle CRM will not have to re-authenticate when navigating
to the IBM Cognos ICM Web tab.

NOTE: Once the IBM Cognos ICM Web application is configured for Oracle CRM
integration, users will not be able to connect directly to the IBM Cognos ICM web
client. The only way to access IBM Cognos ICM will be through the tab in Oracle
CRM.

Admin Client Configuration Steps

To integrate Oracle CRM with IBM Cognos ICM, a column needs to be added to the Payee table that
contains Oracle CRM user names for all payees.

1. In the model that will be accessed through Oracle CRM, add a text column to your Payee table
to use for Oracle integration. For example, add a text column called Oracle UserID (see
Figure 6-7).

Copyright © IBM Corporation and other(s) 2005, 2012 134

 Integrate the IBM Cognos ICM Web Client with Oracle CRM

FIGURE 6-7 Oracle Column in Payee Table

2. For each payee that will be accessing the IBM Cognos ICM web client through a tab in Oracle
CRM, add the payee’s Oracle CRM user name to the new column. For example, rivacent/
huddle.

3. Create a new web tab in Portal Access an enable users for web access.

3.a Go to Portal Access > Web Tabs and add a Module type web tab with a Data Edit
object assigned to it (see Figure 6-8).

Copyright © IBM Corporation and other(s) 2005, 2012 135

 Integrate the IBM Cognos ICM Web Client with Oracle CRM

FIGURE 6-8 Oracle Web Tab

3.b Create a Portal Access group containing all payees that will be accessing IBM Cognos
ICM through Oracle CRM. For example, create a group called Oracle Group that
contains all your payees.

3.c Create a Portal Access tree and add the Portal Access group to the tree. For example,
create a Portal Access tree called Oracle Access Tree that contains the Oracle Group.

3.d From the Assignment tab, give your Oracle Access Tree access to your Oracle web tab
(see Figure 6-9).

FIGURE 6-9 Assign Oracle Access Tree

3.e From the Groups tab, enable all users in your Oracle group with access to the IBM
Cognos ICM web client (see Figure 6-10).

Copyright © IBM Corporation and other(s) 2005, 2012 136

 Integrate the IBM Cognos ICM Web Client with Oracle CRM

FIGURE 6-10 Web Enable Oracle Users

NOTE: Although enabling each user for web access via the IBM Cognos ICM Admin
Client is required, the user will never use the password created in IBM Cognos ICM
to access the IBM Cognos ICM web client when Oracle CRM integration is in use.

Web Configuration Steps

In order to configure access to the IBM Cognos ICM web client via a tab in Oracle CRM, the
crmondemand.properties and web.xml files need to be edited. If the IBM Cognos ICM web client is
deployed on Apache Tomcat, these files can be found in the following default location: C:\Program
Files\Apache Software Foundation\Tomcat 6.0\webapps\ICM\WEB-INF.

1. Deploy the ICM.war file and configure the jdbc.properties file to point to your model.

2. Open up the crmondemand.properties file and make the edits to the authenticationURL
and userKeyColumn fields (see Figure 6-11).

2.a The authenticationURL field needs to contain the URL for the Oracle CRM instance
you are connecting from.

2.b The userKeyColumn contains the name of the column added to the IBM Cognos ICM
Payee table that contains the Oracle CRM user names.

Copyright © IBM Corporation and other(s) 2005, 2012 137

 Customizing the Appearance of IBM Cognos ICM

FIGURE 6-11 Edit the Configuration Files

3. Edit the security parameter in the web.xml file. Change /WEB-INF/security.xml to /WEB-INF/
security-crmondemand.xml (see Figure 6-12).

FIGURE 6-12 Edit Security Parameters

4. Restart your IBM Cognos ICM Web service.

5. Connect to the Oracle CRM instance, log in as a user referenced in the Payee table column
containing Oracle user names, and select the tab that was configured to connect to IBM
Cognos ICM. For information on adding custom tabs to Oracle instances, see the help section
on displaying external pages in tabs in the Oracle CRM On Demand help.

Customizing the Appearance of IBM Cognos ICM

IBM Cognos ICM Web Client

Once the IBM Cognos ICM tab has been set up in Salesforce, you may want to customize IBM Cognos
ICM’s appearance. This can be done in the Admin Client (see “Changing the Appearance of the IBM
Cognos ICM Web Client” ).

Copyright © IBM Corporation and other(s) 2005, 2012 138

 Customizing the Appearance of IBM Cognos ICM

Admin Client
When accessing IBM Cognos ICM from Salesforce, you may want to configure IBM Cognos ICM’s
appearance to be more consistent with the rest of Salesforce.

1. Select the Themes option from the Tools menu in the IBM Cognos ICM Admin Client.

2. In the Web Theme section, select salesforce.com (see Figure 6-13).

FIGURE 6-13 Header Settings

Copyright © IBM Corporation and other(s) 2005, 2012 139

 Integrating with IIS

Integrating with IIS

This section describes how to configure Microsoft's IIS web server with the IBM Cognos ICM web server
so that IIS forwards requests on to IBM Cognos ICM and responses back to the user. This is useful if you
already have IIS running serving web pages (e.g. http://mycompany.com) and wish to integrate IBM
Cognos ICM as just another URL (e.g. http://mycompany.com/ICM).

The IBM Cognos ICM web client is written as a J2EE Web application and needs a Java Application
Server (servlet container) to run. As IIS does not provide the services of a Java Application Server, it is not
possible to deploy the IBM Cognos ICM web client directly into IIS. It is possible to configure IIS to proxy
requests for the IBM Cognos ICM web client to an application server where IBM Cognos ICM is deployed.
Therefore, if your main website is running in IIS, it is possible to integrate IBM Cognos ICM into this
website.

If you need to integrate the IBM Cognos ICM web client with IIS, the IBM Cognos ICM web client needs to
be deployed into a Java Application Server that provides IIS integration capability. Apache Tomcat is one of
these application servers.

Configure the IBM Cognos ICM Web Client

You must first configure IBM Cognos ICM and test the deployment.

1. Install and configure the IBM Cognos ICM web client.

2. Deploy the WAR file into Apache Tomcat.

Configure Tomcat to Accept Proxied Requests

You must also configure Tomcat to accept proxied requests for IBM Cognos ICM from IIS and enable the
AJP/1.3 Connector in IBM Cognos ICM.

1. Enable AJP/1.3 Connector in Tomcat.

1.a Edit the server.xml file and make sure that the AJP/1.3 Connector is enabled (i.e. not
commented out). The server.xml file is found in the following location by default:
C:\Program Files\Apache Software Foundation\Tomcat 6.0\conf

1.b Remove the comment symbols (<!-- and -->) around the following section in the
conf/server.xml file:
<Connector port=”8009” protocol=”AJP/1.3” redirectPort=”8443”/>

Copyright © IBM Corporation and other(s) 2005, 2012 140

 Integrating with IIS

2. Restart Tomcat and make sure that no errors regarding used ports appear in the logs or in the
Tomcat Console.

3. Make sure that the AJP Connector is listening on the specified port (8009 by default). One
way to do this is to use the "netstat -na" command in the command window and see if port
8009 is listed in the output.

Configure IIS to Forward Requests to IBM Cognos ICM

You must then configure IIS to forward IBM Cognos ICM requests to Tomcat. The following steps must be
performed on the machine where IIS is deployed.

1. Download the ISAPI Redirect DLL from the Apache site.

2. When downloading, choose the version of Windows that IIS is running on (either win32 or
win64), and then choose the latest available jk version (jk-1.2.31).

NOTE: The file to download is named api_redirect_X.X.X.dll, where 'X.X.X' is the

version number. You will need to remove the version number from the DLL file (i.e.
it needs to be named isapi_redirect.dll).

3. Place the DLL and the associated properties files in an installation directory.
For example, assume the directory is C:\tomcat_iis_connector. Place the isapi_redirect.dll in
this directory.

4. Download the isapi_redirect.properties file and place this in the same directory as the
isapi_redirect.dll file.

5. Create a directory called conf in your installation directory (C:\tomcat_iis_connector\conf).

5.a Download the files uriworkermap.properties and workers.properties.minimal and

place them in the C:\tomcat_iis_connector\conf directory.

6. Create a directory called logs (C:\tomcat_iis_connector\logs). This is where the logs

associated with the isapi_redirect.dll execution will be placed.

7. In the C:\tomcat_iis_connector directory you may need to modify the

isapi_redirect.properties file. The isapi_redirect.properties file tells the connector where to
find its configuration files and where the DLL can be found in relation to the IIS server. The
following five properties are in this file:
• extension_uri — the path to the virtual directory that contains the isapi_redirect.dll
• log_file — the path to write the log file to
• log_level — the level at which the logs should be generated

Copyright © IBM Corporation and other(s) 2005, 2012 141

 Integrating with IIS

• worker_file — the path to your workers.properties.minimal file in your installation

• worker_mount_file — the path to your uriworkermap.propertiesl file in your installation

If you install the connector in C:\tomcat_iis_connector and you follow the instructions below for setting up
the virtual directory for the isapi_redirect.dll, then you should not have to change any properties in the
provided file.

8. In the C:\tomcat_iis_connector\conf directory, you may need to modify the

uriworkermap.properties and the workers.properties.minimal files.

8.a Edit the uriworkermap.properties and make sure that it contains the following mapping
for IBM Cognos ICM:
/ICM/*=worker1.

8.b Edit the workers.properties.minimal file and modify the worker.ajp13w.host property
if necessary. This property should be set to the host name or the IP address of the
machine where Tomcat is running. If Tomcat is running on the same machine as IIS then
you can leave the property set to localhost. If you have specified a host name as the
value of this property, please make sure that the IIS machine can correctly resolve it to
the appropriate IP address.

If you have modified the port for the AJP Connector you will need to modify the worker.ajp13w.port
property.

9. Open Control Panel > Administrative Tools > Internet Information Services.

NOTE: If you are using IIS 7.0, you will need to install ISAPI Extensions and ISAPI
Filters.

10. Navigate to Start Menu > All Programs > Administration Tools > Service Manager.

10.a Select Web Server (IIS)\\ > Roles.

10.b Click Add Role Services.

11. Add an ISAPI Filter to IIS in one of the following two ways:

If using IIS 6.0 or earlier,

• Right-click on Default Web Site (or the Web Site that should be responsible for proxying
requests to IBM Cognos ICM) > Properties.
• Click the ISAPI Filters tab.

Copyright © IBM Corporation and other(s) 2005, 2012 142

 Integrating with IIS

• Check if there is a filter that points to the isapi_redirect.dll file and that it is in the right
location. If not, click Add and create one.
• Type tomcat as the Filter Name and type the location of the isapi_redirect.dll file for the
executable.
• Click Apply, then OK.

If using IIS 7.0,

• Click the Default Web Site (or the Web Site that should be responsible for proxying requests
to IBM Cognos ICM), and click on ISAPI Filters.
• Click the ISAPI Filters icon.
• Check if there is a Filter that points to the isapi_redirect.dll file and that it is in the right
location. If not, click Add and create one.
• Type tomcat as the Filter Name and type the location of the isapi_redirect.dll file.
• Click OK.

12. Create a virtual directory for IBM Cognos ICM in IIS.

12.a Right-click on Default Web Site (or the Web Site that should be responsible for proxying
requests to IBM Cognos ICM) > New > Virtual Directory.

12.b Set the alias as the value of the Context Path (without slashes) that was set in the
Configure IBM Cognos ICM section of this document.

12.c This can point to any directory.

13. Create a virtual directory for access to the isapi_redirect.dll in IIS in on of the following two
ways:

If using IIS 6.0 or earlier,

• Right-click on Default Web Site (or the Web Site that should be responsible for proxying
requests to IBM Cognos ICM) > New > Virtual Directory.
• Set the alias to be jakarta.
• This must point to the directory in which the isapi_redirect.dll is installed. In our example, this
is C:\tomcat_iis_connector.
• Select the Execute checkbox.

If using IIS 7.0,

Copyright © IBM Corporation and other(s) 2005, 2012 143

 Integrating with IIS

• Right-click on Default Web Site (or the Web Site that should be responsible for proxying
requests to IBM Cognos ICM) > Add Virtual Directory.
• Set the alias.
• Physical Path must point to the directory in which the isapi_redirect.dll is installed. In our
example, this is C:\tomcat_iis_connector.
• Click the alias Virtual Directory and double-click Handler Mappings.
• Click Edit Feature Permissions in the Action panel.
• Select the Execute checkbox.

If using IIS 6.0 or 7.0, you will need to add the dll as a Web Service Extension in one of the following two
ways:

If using IIS 6.0,

• Right-click on Web Service Extensions > Add a new Web Service Extension.
• Type tomcat for the Extension Name.
• Add the isapi_redirect.dll file to the required files.
• Select the Set extension status to Allowed checkbox.
• Click OK.

If using IIS 7.0,

• Navigate to the servers and highlight your server.
• Navigate to ISAPI and CGI Restrictions.
• Add and allow the isapi_redirect.dll extension.
• J2EE compliant application server.
• Apache Tomcat – the easiest to configure.

Copyright © IBM Corporation and other(s) 2005, 2012 144

 Integration with IWA

Integration with IWA

You can configure the IBM Cognos ICM web client to have single sign on integration with Integrated
Windows Authentication (IWA). IBM Cognos ICM web users will be automatically signed in without having
to enter a Username and Password. If the authentication fails, then users will have to enter their Windows
account Username and Password.

Set up for Internet Explorer

If you are using Internet Explorer, you must enable Integrated Windows Authentication and add the IBM
Cognos ICM web client address to your Local Intranet zone.

1. Go to Tools > Internet Options > Advanced.

2. Under Security, select Enable Integrated Window Authentication.

3. Restart Internet Explorer

4. Go to Tools > Internet Options > Security.

5. Select the Local Intranet zone.

6. Click Sites.

7. Click Advanced.

8. Add the website address where the IBM Cognos ICM web client runs.

9. Click Close then OK.

10. Click Custom Level.

11. Under User Authentication, make sure Automatic logon only in Intranet zone is selected.

12. If you would like the webapp to ask you to authenticate manually, select Prompt for user
name and password instead.

Copyright © IBM Corporation and other(s) 2005, 2012 145

 Integration with IWA

Set up for Firefox

If you are using Firefox, you must make changes to a few settings to enable IWA functionality.

1. In the address bar, enter about:config as a URL and click Go.

2. If you receive a warning message, click I’ll be careful, I promise!

3. In the filter, type network.negotiate-auth.trusted-uris.

4. Double-click on network.negotiate-auth.trusted-uris and enter your server address.

Set up for Google Chrome

If you are using Chrome, you must make changes to a few settings to enable IWA functionality.

1. Click the Settings icon and select Options.

2. On the Under the Hood tab, click Change proxy settings.

3. On the Advanced tab, select Enable Integrated Windows Authentication.

4. Restart Chrome and repeat steps 1 and 2.

5. On the Security tab, select Local Intranet Zone.

6. Click Sites.

7. Click Advanced.

8. Add the website address where the IBM Cognos ICM web client runs to your Local Intranet
zone.

9. On the Security tab, select Custom Level.

10. Select Automatic logon only in Intranet zone.

11. If you would like the webapp to ask you to authenticate manually, select Prompt for user
name and password instead.

Create Kerberos Configuration File

You will need to create a Kerberos configuration file that is necessary for IWA.

1. On your web server, create a krb5.ini file and place it in the Windows directory (e.g.
C:\Windows).

Copyright © IBM Corporation and other(s) 2005, 2012 146

 Integration with IWA

A basic krb5.ini file will look like the following:

krb5.ini
------------------------------
[libdefaults]
default_realm = YOURDOMAIN.COM
default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
permitted_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
[realms]
YOURDOMAIN.COM = {
kdc = kdc.yourdomain.com
default_domain = YOURDOMAIN.COM
}
[domain_realm]
.YOURDOMAIN.COM = YOURDOMAIN.COM

2. Replace YOURDOMAIN.COM with your organization’s domain name.

3. Replace kdc.yourdomain.com with the address of your Active Directory Server.

4. Configure the lists of encryption types that you would like to use.

Configure the Service Principal Name and Keytab

You will need to configure a Service Principal Name (SPN) for your web server in the Active Directory and
generate a keytab file containing a shared secret key. Your organization's IT department can assist you
with this section.

1. Create a domain account for the web server in your Active Directory with the following
settings:
• Account name: "serviceaccount"
• Select a password (e.g. "secret")
• Deactivate "User must change password at next logon"
• Activate "Password never expires"

2. Create keytab file 'http-webserver.keytab' using ktpass.exe.

ktpass -out http-webserver.keytab
-princ HTTP/webserver.yourdomain.com@YOURDOMAIN.COM
-mapUser serviceaccount@YOURDOMAIN.COM
Copyright © IBM Corporation and other(s) 2005, 2012 147
 Integration with IWA

-mapOp set
-pass secret
-crypto RC4-HMAC-NT
-pType KRB5_NT_PRINCIPAL
-DesOnly

2.a Replace webserver.yourdomain.com with the address of your web server.

2.b Replace YOURDOMAIN.COM with your domain name.

2.c Replace secret with the password of the account created in step 1.

2.d Replace RC4-HMAC-NT with the encryption your Kerberos server uses.

3. Copy the keytab file generated in step 2 (http-webserver.keytab) to a secure location on the
web server that can only be accessed locally.

NOTE: In this case, the Service Principal Name (SPN) chosen is 'HTTP/
webserver.yourdomain.com@YOURDOMAIN.COM'. You will need this to configure
the IBM Cognos ICM web client.

Set up the IBM Cognos ICM Web Client

After your browser has been enabled for IWA functionality, you will have to enable the IBM Cognos ICM
web client for IWA functionality as well.

NOTE: All web users must be in the Payee table, have an email address, and be part
of a Portal Access group and Portal Access tree in your IBM Cognos ICM model.

1. Deploy the ICM.war file.

2. Configure database access in the jdbc.properties file.

3. Configure the web.xml file to use SPNEGO security by changing the security.xml param-
value to security-spnego.xml (see Figure 6-14). By default the file is located in C:\Program
Files\Apache Software Foundation\Tomcat 6.0\webapps\ICM\WEB-INF.

Copyright © IBM Corporation and other(s) 2005, 2012 148

 Integration with IWA

FIGURE 6-14 SPNEGO Security

4. Configure the spnego.properties file for your environment. By default, it is located in

C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\ICM\WEB-INF.

4.a Replace the service principal and keytab location values with the ones you obtained from
the previous section (see Figure 6-15).

4.b Configure the LDAP settings for your Active Directory. By default, the search filter is
userPrincipalName and should not be changed unless it is necessary.

4.c Configure the Active Directory account attribute (spnego.ldapUserKeyAttribute and

spnego.userKeyColumn) that will map to the Payee table column in your model (see
Figure 6-15).

FIGURE 6-15 Spnego.properties File

Copyright © IBM Corporation and other(s) 2005, 2012 149

Glossary D

Database Server: A server that houses the

Varicent database, which includes all application
A tables and data. No Varicent business or
presentation logic resides at the database level.
Active Directory: A technology created by
Microsoft that provides a variety of network
services, including LDAP directory services.
J

Administrator: Allows administrators to modify JBoss: An application server that provides an

previously calculated compensation. environment for Java code to run in cooperation
Adjustments allow for the correction of mistakes with a web server.
while preserving initial data values so that locked
period values always tie out to actual paid
compensation. L

Apache Tomcat: A servlet container that LDAP (lightweight directory access pro-
provides an environment for Java code to run in tocol): A protocol used to look up information
cooperation with a web server. from a server. LDAP defines the language used
for client programs to talk to servers.

Application Server: The server that is running

Varicent Service. It typically includes both an M
application layer and a data layer.
Microsoft SQL Server: A relational database
management system (RDBMS). It’s primary
C query languages are MS-SQL and T-SQL.

Calculation: The process used to transform a

series of records into a new result. Typically a Model: The database that Varicent uses to
calc is mathematical, but calcs may include maintain calculations and compensation plans.
sorting, shifting, or adding to a prior result. Cals
enable the model admin to select records from
their source data, perform operations on the data, P
segment results, and begin another calc based
on those results. Period: A division of time, such as quarters,
months, or weeks.

Copyright © IBM Corporation and other(s) 2005, 2012 150

 S

Server: Can refer to the machine that stores

files of many users and programs that can be
shared, or to the program that allows
communication with a browser.

Servlet Container: Java programs running on-

demand servers. A servlet container is a
specialized web server that supports servlet
execution.

Single Sign On (SSO): A language for

defining and manipulating relational database. It
is now the standard query language for retrieving,
adding, and updating information.

Web (HTTP) Server: The link between the

web browser and the web application server.

Web Application Server: Within the servlet

container, the Varicent Web application is
architechted as a multi-layer application that
receives business-level requests from the web
server. ,

WebSphere: An application server that

provides an environment for Java codes to run in
cooperation with a web server.

Copyright © IBM Corporation and other(s) 2005, 2012 151

Index DB2 33
definitions
exception definitions 83
object definitions 77
A deployment 92–??
development 19
digital certificates 53–64
Admin Client 10–16, 19, 20, 63, 112, 117, 118
directory 21
administrator 10, 19, 26, 28, 29, 120, 121
disk space 37
AllowMultipleInstances 20
download 93, 97, 141
Apache Tomcat 92–96, 140–142
Application Server 118, 140
authentication ??–129
E

B email 26–29, 127

English 109
environment 19
backup 31, 36
error 26, 94
error protection 35
External Tool Directory 27
C

C# 11, 77 F
calculation(s) 10
calendar 41
fiscal year 41
certificate creation tool 54
French 109
Chinese Simplified 110
Chinese Traditional 110
color 116, 132
command line interface 53, 62, 64 G
configuration 10, 28, 92
configuration file encrypter tool 48 German 109
configuration files 19, 22, 30, 95, 98, 130, 141
Console Service 47, 48
ConsoleService.exe.config 49
customer 41 H
customer relationship management 130
Home Page 121, 122
HTTP 119
HTTP Configuration Utility 61, 62
D

data imports 27
database 13, 21–??, 21, 33–37, 94–?? I
database server 118, 119
database server 10 IIS 140–144

Copyright © IBM Corporation ans other(s) 2005, 2012 152

import N
data import 10
install 93–141 Native 120
IP address 60, 62, 142 network 119
Italian 110 network 118
non-Unicode 22

J
P
Japanese 110
Java 93–??, 140 password 25, 65, 95–??, 98–??, 104–??, 122, 127
JBoss 92–?? payee table 127
JDBC 95–??, 98–103, 119 PDF 27
permissions 101

K
R
Kerberos 20
keyfile 21 redeployed 98
Korean 110 resources 36

L S
LDAP 127 sales performance management 19, 28, 68
LDAP configuration 118 Salesforce 130–139
LDAP directory 120, 129 Salesforce.com 117
Scheduler 11, ??–27
security 20, 25, 119
M securityMode 20
server 10, 19, 20, 95, 98, 104, 118, 128
Microsoft .NET Framework 10, 53, 54, 68 Microsoft SQL Server 10
Microsoft Management Console 56–60 server certificate 61
model 10, ??–20, 32–?? service address 20, 23
Unicode model 50, 51 single sing on 120
Model Converter SiteMinder 118–??
Model Converter tool 49, 51 Solaris 92
Model Upgrader 31, 33 solution 10
multilanguage support 92, 109 Spanish
110
SQL
SQL model 22, 51
SQL Server 95–??, 98–??, 104–??
SQL server 33

Copyright © IBM Corporation ans other(s) 2005, 2012 153

 SQL Server 2005 database 21, 33 WebLogic 92–??
SQL Server Configuration Manager 95, 98, 104 WebSphere 92–101
SQLServer2000 33 Windows Communication Foundation 68
SQLServer2005 33 Windows Domain 118
Windows Service Installer 93
Workflow 29, 68, 96
workstation 10, 19
T
WS-I compliant 68

table customization 10
Task Manager 25
Task Manager log 26
TLS Security 118

Unicode 22
uninstall 31
upgrade 19, ??–30, 32
URL 109, 122, 128, 140
username 65, 93–??, 122

Varicent API Service 23, 64

Varicent Application Server 10, 31
Varicent comand-line interface 64–67
Varicent keyfile 21
Varicent login 105
Varicent Service 17, 20, 25, ??–27, 64
Varicent Support 98
Varicent Web 28, ??–139
Varicent.exe.config 20, 25, 31, 63
Varicent.exe.config file 22
VaricentService.exe.config 19–21, 28, 49, 63, 64
VaricentService.exe.config 31

WAR file 98–140

Web Server 118
Web.xml file 128
Copyright © IBM Corporation ans other(s) 2005, 2012 154