IBM Planning Analytics

2.0

Installation and Configuration

IBM
 Note
Before you use this information and the product it supports, read the information in “Notices” on page
419.

Product Information
This document applies to IBM Planning Analytics Version 2.0 and might also apply to subsequent releases.
Licensed Materials - Property of IBM
Last updated: 2021-03-01
© Copyright International Business Machines Corporation 2007, 2021.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents

Introduction......................................................................................................... xi

Chapter 1. What's new in Planning Analytics.......................................................... 1

Planning Analytics [Link] - February 8, 2021........................................................................................... 1
Change to default value of FIPSOperationMode in [Link] and [Link]............................... 1
Disable DES and 3DES Ciphers in IBM Planning Analytics to mitigate false-positive security
scans.................................................................................................................................................. 1
Change in dimension hierarchy security................................................................................................ 2
Action Button is misaligned in Perspectives using Office Excel 2016 - 2019...................................... 3
Planning Analytics [Link] - December 17, 2020....................................................................................... 4
Secure Shell URL support in Git integration.......................................................................................... 4
HTTP proxy support in Git integration................................................................................................... 5
Improved member selection in query to TM1 Server when using multiple hierarchies...................... 5
The chore StartTime property time is stored and represented as Coordinated Universal Time
and does not vary for Daylight Saving Time .....................................................................................6
Enhanced SQL error logging in [Link]....................................................................................... 6
Planning Analytics [Link] - October 9, 2020.............................................................................................6
PMHub deprecation................................................................................................................................6
TM1 Server on Linux requires the Java shared object [Link] to be in the LD_LIBRARY_PATH....... 7
Planning Analytics [Link] - July 27, 2020................................................................................................. 7
TM1 Web is no longer part of the Planning Analytics long cadence (LC) release................................. 7
New installer for TM1 Web..................................................................................................................... 8
Planning Analytics [Link] - May 21, 2020................................................................................................. 8
Planning Analytics 2.0.9 - December 16, 2019.......................................................................................... 8
Manage a list of TM1 databases on the TM1 Admin Server.................................................................. 8
Use the ViewZeroOut TurboIntegrator function on MDX views.......................................................... 12
Use dynamic shapes and images in websheets.................................................................................. 12
Open a websheet on the active tab when you save a multi-tab websheet........................................ 13
Deprecation of TM1 Operations Console.............................................................................................13
Planning Analytics 2.0.8 - July 17, 2019.................................................................................................. 13
View process rollback and restart messages in TM1 logs.................................................................. 13
View and report on audit log data with the TM1 REST APIs............................................................... 14
Iterate through SQL rowsets to speed up drill through queries......................................................... 15
Review updates to the TM1 REST API metadata................................................................................ 16
Include user names and memory usage in TM1 Web logs................................................................. 16
Changes saved automatically in TM1 Application Web.......................................................................17
Configure login using TM1 Web URL API with Cognos Analytics security.......................................... 17
Relational data sources in TM1 Web websheets removed................................................................. 18
TM1 Package Connector removed from Planning Analytics Local......................................................18
Planning Analytics 2.0.7 - April 29, 2019................................................................................................. 18
Install IBM Planning Analytics Local on Windows Server 2019......................................................... 18
Upgrade to WebSphere Liberty Profile [Link]................................................................................. 18
Optimize the login process with a new [Link] parameter...............................................................19
Monitor threads with the Top logger....................................................................................................19
Run multiple processes on their own thread with a new TurboIntegrator function.......................... 21
Prepare for changes in behavior in TM1 Server...................................................................................21
Learn more about updates to TM1 REST APIs.................................................................................... 22
Use Git source control to deploy database assets between environments....................................... 23
Load websheets faster in TM1 Web.....................................................................................................24
Use the IFERROR Excel function in TM1 Web..................................................................................... 24

iii
 Take advantage of improved cell formatting in TM1 Web websheets................................................ 24
Check out updated TM1 Web configuration defaults.......................................................................... 25
Review deprecation notices................................................................................................................. 26
Planning Analytics 2.0.6 - October 11, 2018............................................................................................26
Upgrade to Java 8 and removal of Java 7............................................................................................27
ThirdPartyCertificateTool no longer supported................................................................................... 27
New TurboIntegrator functions to delete leaf elements from dimension or hierarchy..................... 27
New parameter to configure session timeout for TM1 Web............................................................... 27
TM1 REST API updates........................................................................................................................ 28
Planning Analytics 2.0.5 - June 25, 2018................................................................................................. 28
Local installation and configuration updates.......................................................................................28
TM1 Server updates............................................................................................................................. 29
TM1 REST API updates........................................................................................................................ 30
TM1 Web updates.................................................................................................................................31
Cognos Insight updates....................................................................................................................... 31
Planning Analytics 2.0.4 - February 16, 2018.......................................................................................... 32
Local installation and configuration updates.......................................................................................32
TM1 Server updates............................................................................................................................. 32
TM1 Performance Modeler updates.................................................................................................... 34
Cognos Insight updates....................................................................................................................... 34
Planning Analytics 2.0.3 - September 19, 2017.......................................................................................35
Local installation and configuration updates.......................................................................................35
TM1 Server updates............................................................................................................................. 35
TM1 Web updates.................................................................................................................................37
Planning Analytics 2.0.2 - June 1, 2017................................................................................................... 37
TM1 Server updates............................................................................................................................. 37
Planning Analytics 2.0.1 - February 7, 2017............................................................................................ 38
Planning Analytics 2.0.0 - December 16, 2016........................................................................................ 38
Local installation and configuration updates.......................................................................................38
TM1 Server updates............................................................................................................................. 39
TM1 Web updates.................................................................................................................................40
TM1 Performance Modeler updates.................................................................................................... 42
Cognos Insight updates....................................................................................................................... 42

Chapter 2. Planning your installation....................................................................45

Software requirements.............................................................................................................................. 45
Available installation programs................................................................................................................. 45
Available components............................................................................................................................... 47
TM1 Data Tier installation components...............................................................................................47
TM1 Web Tier installation components............................................................................................... 48
TM1 Rich Tier installation components............................................................................................... 50
Additional installation components not listed.....................................................................................51
TM1 Client Differentiation......................................................................................................................... 51
End-user clients................................................................................................................................... 52
Administration clients.......................................................................................................................... 53
Configuration overview.............................................................................................................................. 53
Default installation values....................................................................................................................54
TM1 Server and Cognos Configuration................................................................................................ 57
TM1 configuration files and parameters..............................................................................................58
User accounts for running TM1 services on Windows........................................................................ 59
Installing IBM Planning Analytics Local on Networks without domains............................................ 59
Accessibility............................................................................................................................................... 60
Keyboard shortcuts for the installation wizard....................................................................................60
Keyboard shortcuts for Cognos Configuration.....................................................................................61

Chapter 3. Planning Analytics Local architecture.................................................. 63

Planning Analytics architecture.................................................................................................................63

iv
 TM1 Admin Server overview................................................................................................................ 64
TM1 Server overview............................................................................................................................64
TM1 files overview................................................................................................................................66
Data directory overview....................................................................................................................... 66
TM1 Web architecture............................................................................................................................... 68
Accessing multiple TM1 servers from TM1 Web................................................................................. 69
Limiting access to a single TM1 Server from TM1 Web.......................................................................69
TM1 Applications architecture.................................................................................................................. 69
TM1 Data Tier: Data..............................................................................................................................70
TM1 Web Tier: Application servers...................................................................................................... 70
TM1 Rich Tier: Web clients...................................................................................................................71

Chapter 4. Deploying Planning Analytics Local......................................................73

Deploying Planning Analytics on a single Windows computer................................................................. 73
Deploying TM1 Admin Server and TM1 Server......................................................................................... 74
Deploying TM1 Applications components on a single computer............................................................. 74
Deploying TM1 Applications components on separate computers......................................................... 75
Deploying TM1 client applications............................................................................................................ 76

Chapter 5. Upgrading Planning Analytics Local..................................................... 77

Prerequisites for upgrading....................................................................................................................... 77
Upgrading from Planning Analytics version 2.0.0.....................................................................................78
Upgrading Planning Analytics for Microsoft Excel.................................................................................... 79
Upgrading from Cognos TM1 version 10.2.x.............................................................................................79

Chapter 6. Installing Planning Analytics Local on a single computer...................... 81

Install the prerequisite software............................................................................................................... 81
Install the basic Planning Analytics components..................................................................................... 82
Use Cognos Configuration to start Planning Analytics components........................................................ 82
Run Cognos TM1 Perspectives.................................................................................................................. 83
Run Cognos TM1 Architect........................................................................................................................ 84
Run Cognos TM1 Web................................................................................................................................84
Run Cognos TM1 Application Web............................................................................................................ 84
Run Cognos TM1 Performance Modeler....................................................................................................85
Run Cognos Insight....................................................................................................................................85
Use Cognos TM1 Application Web............................................................................................................ 86
Other Planning Analytics components...................................................................................................... 86

Chapter 7. Installing the Data Tier........................................................................89

TM1 Server installation..............................................................................................................................89
Installing IBM TM1 Server on Windows.............................................................................................. 89
Installing IBM TM1 Server on UNIX or Linux.......................................................................................91
TM1 language configuration.................................................................................................................95
Advanced TM1 Admin Server and TM1 Server configuration............................................................. 98
Monitoring TM1 Server license usage................................................................................................102
Cognos TM1 tools installation................................................................................................................. 103
Cognos TM1 sample databases installation........................................................................................... 104
Using the sample databases installed by default............................................................................. 105
Using the GO_Contributor and Outdoors Company sample databases............................................106
Using the Great Outdoors Sales server samples based on the sample database........................... 106
Upgrading the samples...................................................................................................................... 113
Install and configure the Planning Analytics Administration agent (local only).................................... 114
Configure the agent for Windows...................................................................................................... 114
Configure the agent for Linux.............................................................................................................115
Configure event notifications............................................................................................................. 115
Sample [Link] file.......................................................................................................116

v
 Chapter 8. Installing the Web Tier...................................................................... 119
TM1 Application Server installation........................................................................................................ 119
Install TM1 Application Server.......................................................................................................... 120
Configuring a TM1 Server to work with TM1 Application Web..........................................................124
TM1 Application Server advanced installation and configuration.................................................... 126
Monitoring TM1 Application Server logs........................................................................................... 129
Cognos TM1 Web installation..................................................................................................................131
Installing TM1 Web............................................................................................................................ 132
Post-installation configuration...........................................................................................................134
Cognos TM1 Operations Console installation.........................................................................................134
Installing Cognos TM1 Operations Console using the provided WebSphere® Liberty webserver
software.........................................................................................................................................135
Using Cognos Configuration to deploy Cognos TM1 Operations Console........................................ 135
Advanced Cognos TM1 Operations Console installation.................................................................. 136
Configuring the Cognos TM1 Operations Console.............................................................................139
Starting and logging into the Cognos TM1 Operations Console....................................................... 140

Chapter 9. Installing the Rich Tier...................................................................... 141

Installing Cognos TM1 Architect............................................................................................................. 141
Installing Cognos TM1 Performance Modeler........................................................................................ 142
Installing Cognos TM1 Performance Modeler using the installation program.................................143
Installing Cognos TM1 Performance Modeler from the Cognos TM1 Applications portal...............143
Remotely installing Cognos TM1 Performance Modeler on multiple computers.............................144
Configuring logging for Cognos TM1 Performance Modeler............................................................. 145
Installing Cognos TM1 Perspectives....................................................................................................... 146
Installing Cognos Insight.........................................................................................................................147
Installing Cognos Insight using the installation program................................................................. 148
Installing Cognos Insight from the Cognos TM1 Applications portal...............................................148
Remotely installing Cognos Insight on multiple computers............................................................. 149
Configuring Cognos TM1 TurboIntegrator function security in Cognos Insight............................... 151
Configuring logging for Cognos Insight..............................................................................................152
Installing Cognos TM1 APIs.................................................................................................................... 153

Chapter 10. Installing Planning Analytics Workspace Local.................................155

Planning Analytics Workspace Local architecture..................................................................................155
Prerequisites............................................................................................................................................156
Free ports.................................................................................................................................................157
Install Planning Analytics Workspace Local on Windows Server 2016................................................. 158
Install Planning Analytics Workspace Local on Red Hat Enterprise Linux 7..........................................160
Configuring Planning Analytics Workspace Local................................................................................... 161
Configure parameters........................................................................................................................ 161
Connect to TM1 and authentication servers..................................................................................... 165
Check the status of the services........................................................................................................168
View logs............................................................................................................................................ 168
Shut down MongoDB cleanly on Windows Server 2016................................................................... 169
Run the Planning Analytics Workspace administration tool from the command line on Linux....... 169
Access the Planning Analytics Workspace administration tool remotely on Windows Server........ 169
Access the Planning Analytics Workspace administration tool remotely on Linux..........................170
Back up or restore Planning Analytics Workspace Local.................................................................. 170
Upgrade Planning Analytics Workspace Local.................................................................................. 171
Uninstall Planning Analytics Workspace Local..................................................................................172

Chapter 11. Planning Analytics Workspace Distributed.......................................173

Install on Docker Swarm......................................................................................................................... 173
Docker Swarm architecture............................................................................................................... 174
Create the Docker Swarm.................................................................................................................. 178

vi
 Install Planning Analytics Workspace Distributed............................................................................ 180
Enable TLS for Planning Analytics Workspace Distributed............................................................... 183
Migrate to Planning Analytics Workspace Distributed...................................................................... 184
Back up and restore Planning Analytics Workspace Distributed......................................................184
Remove Planning Analytics Workspace Distributed......................................................................... 185
Upgrade Planning Analytics Workspace Distributed.........................................................................185
Install on OpenShift.................................................................................................................................186
Install OpenShift prerequisites..........................................................................................................186
Extract the Planning Analytics Workspace Distributed archive........................................................187
Configure basic OpenShift settings................................................................................................... 187
Deferred deployment......................................................................................................................... 189
Configure Red Hat OpenShift deployment........................................................................................ 190
Start Planning Analytics Workspace Distributed...............................................................................190
Reinstall or uninstall Planning Analytics Workspace Distributed..................................................... 190
Configure advanced OpenShift settings............................................................................................ 191

Chapter 12. Installing and configuring Planning Analytics for Microsoft Excel......199
What's new?.............................................................................................................................................199
New features in version 2.0.0............................................................................................................ 199
New features in version 10.3.0..........................................................................................................199
New features in version 10.2.0..........................................................................................................199
Installation overview............................................................................................................................... 200
Prerequisites for installing Planning Analytics for Microsoft Excel........................................................ 200
Find the version information for IBM Planning Analytics for Microsoft Excel.................................. 200
Install Microsoft .NET Framework..................................................................................................... 201
Primary interop assemblies (PIAs) for Microsoft Excel.................................................................... 201
Uninstall previous versions of IBM Cognos Analysis for Microsoft Excel......................................... 202
Connect to IBM Planning Analytics Workspace................................................................................ 203
Install TM1 Server..............................................................................................................................203
Set up connections for TM1 REST APIs.............................................................................................203
Configure your antivirus software......................................................................................................204
Ensure that you are using IBMid........................................................................................................204
Use Cognos security...........................................................................................................................204
Installation tasks..................................................................................................................................... 204
Installing IBM Planning Analytics for Microsoft Excel...................................................................... 204
Test IBM Planning Analytics for Microsoft Excel............................................................................... 205
Uninstall IBM Planning Analytics for Microsoft Excel....................................................................... 205
Register the IBM Cognos Office Reporting TM1 Addin using a script...............................................206
Configure IBM Planning Analytics for Microsoft Excel for use with high DPI displays.................... 207
Configure Planning Analytics for Microsoft Excel single sign-on........................................................... 207
Troubleshoot............................................................................................................................................208

Chapter 13. IBM Planning Analytics TM1 Web installation.................................. 209

Installing TM1 Web..................................................................................................................................210
Install and configure TM1 Web on Microsoft Windows.....................................................................210
Install and configure TM1 Web on Linux........................................................................................... 212
Configuring SSL for Planning Analytics TM1 Web/Spreadsheet Services........................................ 213
Configure SSL for new deployments of Planning Analytics TM1 Web/Spreadsheet Services......... 213
Configure SSL for Planning Analytics TM1 Web/Spreadsheet Services with an existing keystore..213
Relocating custom SSL files............................................................................................................... 215
Upgrade IBM Planning Analytics TM1 Web ...................................................................................... 216
Modifying TM1 Web configuration parameters.......................................................................................218
TM1 Web configuration parameters.................................................................................................. 219
Editing the TM1 Web configuration file............................................................................................. 225
Configuring the TM1 Web login page using AdminHostName and TM1ServerName parameters.. 225
Configuring a custom homepage for TM1 Web................................................................................. 226
Configuring TM1 Web startup and appearance settings...................................................................230

vii
 Changing the Cube Viewer page size.................................................................................................233
Setting the maximum number of sheets to export from a websheet............................................... 233
Wrapping string values in cube views................................................................................................234
Setting the TM1 Web session timeout...............................................................................................234
Configuring web browsers for Cognos TM1 Web.................................................................................... 235
Configuring web browser language for TM1 Web............................................................................. 235
Displaying and entering numbers in Cognos TM1 Web based on Regional Settings....................... 236
Configuring Internet Explorer for Cognos TM1 Web......................................................................... 236

Chapter 14. Integrating Planning Analytics Local with IBM Cognos software....... 239
TM1 as a datasource with Cognos Analytics...........................................................................................240
Import Cognos Analytics data into Planning Analytics Local with the TM1 Package Connector.......... 240
TM1 Package Connector requirements............................................................................................. 240
Installing the TM1 Package Connector..............................................................................................241
Configuring the TM1 Package Connector.......................................................................................... 241
Running the TM1 Package Connector............................................................................................... 243
Installing the TM1 Package Connector on UNIX .............................................................................. 243
Planning Analytics and Cognos Analytics security................................................................................. 243
Integrate SAP BW with Planning Analytics............................................................................................. 244
Cognos TM1 Applications integration with Cognos Analytics and the Cognos Connection portal....... 244

Chapter 15. Planning Analytics Local security.....................................................245

Authentication security .......................................................................................................................... 246
Standard Cognos TM1 authentication............................................................................................... 246
Integrated login..................................................................................................................................247
LDAP Authentication.......................................................................................................................... 258
Cognos security.................................................................................................................................. 261
ETLDAP utility.....................................................................................................................................274
Data transmission security ..................................................................................................................... 282
Overview.............................................................................................................................................282
Default configuration..........................................................................................................................283
Configure the Data Tier to use custom TLS....................................................................................... 284
Configure the Web Tier to use custom TLS....................................................................................... 291
Configure the Rich Tier to use TLS.....................................................................................................300
ThirdPartyCertificateTool command-line reference..........................................................................305
TM1 Server data encryption.................................................................................................................... 307
Run the TM1Crypt utility.................................................................................................................... 310

Chapter 16. Configuring and maintaining Planning Analytics Local...................... 315

Setting up unattended installations and configurations.........................................................................315
Set up an unattended installation for IBM Cognos components......................................................315
Set up unattended installations for IBM Planning Analytics for Microsoft Excel............................. 317
Set up an unattended configuration for IBM Cognos components.................................................. 319
Set up an unattended uninstallation for IBM Cognos components..................................................320
Maintaining your IBM Planning Analytics Local installation...................................................................320
Backing up data and configuration files for IBM Planning Analytics Local...................................... 321
Modifying Cognos TM1 installed components.................................................................................. 322
Uninstalling IBM Planning Analytics..................................................................................................322
Restoring data and configuration files in IBM Planning Analytics version 2.0.0..............................323
Restoring application and configuration files in Cognos TM1 Applications..................................... 325
Importing an application definition in Cognos TM1 Applications.....................................................325
The [Link] configuration file............................................................................................................ 326
Location of the [Link] file.............................................................................................................. 326
Sample [Link] file.......................................................................................................................... 327
Sample [Link] file................................................................................................................ 333
Parameters in the [Link] file..........................................................................................................336
The [Link] client configuration file......................................................................................................389

viii
 Location of the [Link] File..............................................................................................................389
Parameters in the [Link] file..........................................................................................................390

Chapter 17. Troubleshooting Planning Analytics Local........................................ 399

What if my TM1 Application Server deployment fails with a Java heap space error?...........................399
What if I use Microsoft Excel 2007 or earlier .xls worksheets?............................................................. 400
How do I save security rights when importing or restoring a Cognos TM1 10.2.x application?........... 400
How do I configure client computers to export TM1 data in PDF format?.............................................401
What timeout settings can I set?............................................................................................................ 401
How do I fix my Planning Analytics Workspace Local installation?....................................................... 402
Why can't I open Planning Analytics Workspace in a browser?........................................................402
Why doesn't the Planning Analytics Workspace administration tool start?..................................... 403
How do I handle errors when I run the start script?......................................................................... 403
How do I handle errors with the Host Network Service (HNS)?....................................................... 404
Why can't I access Planning Analytics Workspace on Windows Server 2016?............................... 405
What do I do if Docker for Planning Analytics Workspace hangs?................................................... 405
How do I resolve Planning Analytics Workspace connection issues on Windows Server 2016?....406
How do I change default port numbers for Planning Analytics Workspace on Windows Server
2016?............................................................................................................................................ 406
How do I change the IP configuration of Planning Analytics Workspace Local?............................. 406
What are some common errors when installing Planning Analytics for Microsoft Excel?.....................407
Configuration Issues.......................................................................................................................... 407
Processing issues............................................................................................................................... 411
Security Issues...................................................................................................................................413
Cognos Office Numbered Error Messages.........................................................................................414
IBM Planning Analytics for Microsoft Excel numbered error messages.......................................... 416

Notices..............................................................................................................419

Index................................................................................................................ 423

ix
x
Introduction
This document describes how to install, upgrade, and configure IBM® Planning Analytics Local software
components on Microsoft Windows and UNIX operating systems.

Audience
Planning Analytics Local integrates business planning, performance measurement, and operational data
to enable companies to optimize business effectiveness and customer interaction. Planning Analytics
provides immediate visibility into data, accountability within a collaborative process, and a consistent
view of information, allowing managers to quickly stabilize operational fluctuations and take advantage of
new opportunities.
To use this document, you should be familiar with:
• Installation concepts
• Security issues
• Basic Windows or UNIX administration skills
• The existing server environment and security infrastructure in your organization
• Your Planning Analytics system and network requirements

Finding information
To find documentation on the web, including all translated documentation, access IBM Knowledge Center
([Link]

Security considerations
For security considerations for IBM Planning Analytics Local, see Chapter 15, “Planning Analytics Local
security,” on page 245. Information on managing user and group authentication can be found in the
Managing Users and Groups chapter of the TM1 Operations documentation.

Accessibility features
Accessibility features help users who have a physical disability, such as restricted mobility or limited
vision, to use information technology products. The installation wizard has accessibility features. For more
information, see Accessibility features.
IBM HTML documentation has accessibility features. PDF documents are supplemental and include no
added accessibility features.

Accessibility checklist
This product's IBM Knowledge Center documentation is hosted in the IBM Knowledge Center - Hosted
Edition service. To request the current accessibility status for the IBM Knowledge Center, visit the IBM
Accessibility Research information web page ([Link]
accessibility_checklist.html) .

Forward-looking statements
This documentation describes the current functionality of the product. References to items that are not
currently available may be included. No implication of any future availability should be inferred. Any such
references are not a commitment, promise, or legal obligation to deliver any material, code, or
functionality. The development, release, and timing of features or functionality remain at the sole
discretion of IBM.

© Copyright IBM Corp. 2007, 2021 xi

 Samples disclaimer
The Sample Outdoors Company, Great Outdoors Company, GO Sales, any variation of the Sample
Outdoors or Great Outdoors names, and Planning Sample depict fictitious business operations with
sample data used to develop sample applications for IBM and IBM customers. These fictitious records
include sample data for sales transactions, product distribution, finance, and human resources. Any
resemblance to actual names, addresses, contact numbers, or transaction values is coincidental. Other
sample files may contain fictional data manually or machine generated, factual data compiled from
academic or public sources, or data used with permission of the copyright holder, for use as sample data
to develop sample applications. Product names referenced may be the trademarks of their respective
owners. Unauthorized duplication is prohibited.

xii IBM Planning Analytics: Installation and Configuration

Chapter 1. What's new in Planning Analytics
Read about what's new or updated in IBM Planning Analytics and components that are installed with
Planning Analytics, such as TM1® Server, TM1 Web, TM1 Performance Modeler, and TM1 Architect. Some
updates affect only IBM Planning Analytics Local.

Planning Analytics [Link] - February 8, 2021

IBM Planning Analytics Local version [Link] and the cloud release of IBM Planning Analytics version
[Link] includes updates for IBM TM1 Server version 11.8.4.
IBM Planning Analytics version [Link] includes numerous improvements and defect fixes, but does not
include new features.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

Change to default value of FIPSOperationMode in [Link] and

[Link]
As of IBM Planning Analytics [Link], the default value of the FIPSOperationMode configuration
parameter in [Link] and [Link] is FIPSOperationMode=2.
The default value in previous versions of Planning Analytics was FIPSOperationMode=1.
The change to FIPSOperationMode=2 is necessary to enable future security updates to third-party
libraries in IBM Global Security Kit (GSKit).

Disable DES and 3DES Ciphers in IBM Planning Analytics to mitigate false-
positive security scans
To address the vulnerabilities exploited by the SWEET32 Birthday attack (CVE-2016-2183), IBM Planning
Analytics [Link] has enabled the restriction of payload size to 32GB via GSKit. However, the DES and
3DES ciphers will continue to be available and will show up as false positives on security scans. To
prevent these false positives, remove the DES and 3DES ciphers from your Planning Analytics
configuration.

About this task

The configuration changes described here are applicable only to Planning Analytics Workspace Local. You
do not have to make any modifications to Planning Analytics Workspace on Cloud.

Procedure
1. Stop all of the TM1 Server database services and the TM1 Admin Server service in your environment.
2. Open Cognos Configuration for the TM1 Admin Server service and set the following ciphers in the
Supported Cipher Suites property:

TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256,
TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

© Copyright IBM Corp. 2007, 2021 1

 3. Add the following line to the [Link] file for each TM1 Server database:

tlsCipherList=TLS_RSA_WITH_AES_128_CBC_SHA256,
TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_GCM_SHA256,
TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

4. Start the TM1 Admin Server service and all of your TM1 Server database services.

Change in dimension hierarchy security

Planning Analytics [Link] introduces an enhancement to hierarchy security.
You can now define security for dimension hierarchies independent of the parent dimension in
the }DimensionSecurity control cube.
In previous version of Planning Analytics, dimension hierarchies inherited security from the parent
dimension. There was no need to explicitly define security for an hierarchy in the }DimensionSecurity
control cube. For example, here the North America user group inherited Read access for all hierarchies of
the Model dimension, while the South America user group inherited Reserve access for all hierarchies of
the dimension.

As of Planning Analytics [Link], hierarchies no longer inherit security from the parent dimension.
Important : If you want a user group to have access to a dimension hierarchy, you must explicitly define
hierarchy security in the }DimensionSecurity control cube. If you do not define security for a user group to
an hierarchy, members of the user group cannot see the hierarchy in Planning Analytics.

2 IBM Planning Analytics: Installation and Configuration

 You can assign hierarchy security equivalent to or lower than the security defined for the parent
dimension. A user group cannot have higher security access to a hierarchy than to the parent dimension.
Here's an example of how you define hierarchy security in Planning Analytics [Link] and later:

Each hierarchy has security explicitly set for all user groups. Note that a blank cell is equivalent to None
security.

Action Button is misaligned in Perspectives using Office Excel 2016 - 2019

An Action Button created in Excel 2016 - 2019 can sometimes appear misaligned or the text may be
improperly positioned on the button.
You can see this issue in the following image, where the Set Security text is improperly positioned on the
button and the button is misaligned to the grid.

To correct this issue:

1. Open the Excel sheet that contains the Action Button.
2. Right-click the button, then click Properties.
3. Clear and re-select the Resize Button to Caption option.
4. Click OK.

Chapter 1. What's new in Planning Analytics 3

Planning Analytics [Link] - December 17, 2020
IBM Planning Analytics Local version [Link] and the cloud release of IBM Planning Analytics version
[Link] includes updates for IBM TM1 Server version 11.8.3.
IBM Planning Analytics version [Link] includes numerous improvements and defect fixes, as well as
some new features.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

Secure Shell URL support in Git integration

Secure Shell (SSH) URL is supported to access the Git repository.
The REST API actions GitInit, GitStats, GitPull, GitPush, and GitDeploy can take three
additional parameters to pass the SSH credential. These additional parameters are PublicKey,
PrivateKey, and Passphrase.
The content of the PublicKey and PrivateKey parameters should be identical to the content of the
generated SSH key files. Passphrase is the same as was specified when generating the private key.
The PrivateKey and Passphrase will not be written to the server log.
The Git credential is cached in the HTTP session.
This example shows a GitInit with the supported SSH parameters:

POST /api/v1/GitInit
{
"URL": "git@[Link]:GithubAccountXXX/[Link]",
"Deployment": "prod",
"PublicKey": "ssh-rsa AAAAB3NzaC1yc2Exxx...",
"PrivateKey": "----BEGIN RSA PRIVATE KEY----\nMIIJKAIBxxx...",

4 IBM Planning Analytics: Installation and Configuration

 "Passphrase": "xxx"
}

Assuming Git is initialized with SSH URL, a full GitPull looks like this:

POST /api/v1/GitPull
{
"Branch": "DB_PlanSamp",
"PublicKey": "ssh-rsa AAAAB3NzaC1yc2Exxx...",
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIJKAIBxxx..."
"Passphrase": "xxx"
}

However, since the Git credential is cached, you can exclude the credentials in the GitPull request if you'd
like:

POST /api/v1/GitPull {
"Branch": "DB_PlanSamp"
}

Once Git is initialized with SSH URL, GitStats, GitPush, and GitDeploy can be used in the same
manner as GitPull, shown above.

HTTP proxy support in Git integration

The Git repository that the TM1 server connects to for Git integration functionality is frequently isolated
behind a firewall and only reachable via an HTTP proxy. Proxy access is supported on TM1 server.
Proxy support is provided via the Git [Link] parameter, which is defined at [Link]
docs/git-config.
[Link] specifies the URL of the HTTP proxy when invoking the actions GitInit and GitDeploy.
The proxy routes traffic to the Git repository that is specified by the URL parameter, which uses HTTPS
protocol.
For example, this GitInit routes traffic through the [Link] proxy to the repository
at [Link]

POST /api/v1/GitInit
{
"URL": "[Link]
"Deployment": "prod",
"Username": "GitUserXXX",
"Password": "xxx",
"Config":
{
"[Link]": "[Link]
}
}

Improved member selection in query to TM1 Server when using multiple

hierarchies
In previous releases of Planning Analytics, query member selection with multiple hierarchies could
sometimes include unnecessary members, leading to inconsistent query performance.
As of Planning Analytics [Link], members selection is now predictable and consistent, resulting in
consistent query performance.
In some limited circumstances, you might encounter a query that exceeds the current
MaximumViewSize server configuration setting. When this occurs, it is an effect of TM1 Server in [Link]
doing a better job of selecting the members for a multiple hierarchies query to guarantee consistent query
performance. We are working to reduce the additional memory usage for these limited cases in an
upcoming release.
If you encounter a query that exceeds the MaximumViewSize, the current work-around is to increase the
MaximumViewSize value in [Link] to accommodate the increased memory usage.

Chapter 1. What's new in Planning Analytics 5

 For details on the MaximumViewSize parameter, see [Link]
SSD29G_2.0.0/[Link].tm1_cloud_mg.[Link]/c_maximumviewsize_1.html.

The chore StartTime property time is stored and represented as Coordinated

Universal Time and does not vary for Daylight Saving Time
Documentation has been updated to reflect that the StartTime property for a chore is represented as
Coordinated Universal Time (UTC).

UTC is a fixed time that does not vary for Daylight Saving Time. Accordingly, a chore start time remains
concurrent with UTC, regardless of Daylight Saving Time status for any location.
When the TM1 server stores or returns a local time, or 'time relative location,' the server uses a
DateTimeOffset that represents a date/time value, together with an offset that indicates how much that
value differs from UTC in the physical location where the server resides. This offset does not vary for
Daylight Saving Time.
Users of the TM1 OData Rest API need to verify compliance with the standard [Link]
odata/odata-csdl-json/v4.01/[Link]#sec_DateTimeOffset. Failure to verify
compliance will result in user-built applications failing when the TM1 Server responds with
DateTimeOffset according to the standard

Enhanced SQL error logging in [Link]

As of Planning Analytics [Link], the TM1 Server now processes more ODBC driver errors and reports
them in the server message log ([Link]). As a result, you may see SQL errors in
[Link] that were not previously reported.
These errors from the ODBC driver have always existed, but were not written to the server message log
prior to Planning Analytics [Link]. The errors are discoverable using the tracing capability of your ODBC
administrator tool.
Any SQL errors reported in [Link] originate from the ODBC driver. You can use these errors to
review issues with your ODBC driver and to pursue support with your ODBC vendor.

Planning Analytics [Link] - October 9, 2020

IBM Planning Analytics Local version [Link] and the cloud release of IBM Planning Analytics version
[Link] includes updates for IBM TM1 Server version 11.8.2.
IBM Planning Analytics version [Link] includes numerous improvements and defect fixes. This version
does not include new features. However, PMHub is fully deprecated as of version [Link], as previously
announced in the IBM Planning Analytics 2.0 deprecation notices. For details about the impact of this
deprecation, see PMHub deprecation.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

PMHub deprecation
PMHub is fully deprecated as of IBM Planning Analytics version [Link], as previously announced in the
IBM Planning Analytics 2.0 deprecation notices.
IBM Planning Analytics for Microsoft Excel must use hubless mode when upgrading to [Link]. In hubless
mode, Planning Analytics for Microsoft Excel connects to Planning Analytics sources via Planning
Analytics Workspace.
Planning Analytics for Microsoft Excel version 2.0.41 and prior do not support hubless mode. If you have
version 2.0.41 or prior, please upgrade to the most recent version of Planning Analytics for Microsoft Excel
when you install IBM Planning Analytics version [Link]

6 IBM Planning Analytics: Installation and Configuration

 Planning Analytics for Microsoft Excel version 2.0.52 and later forces all non-overridden connections to
IBM Planning Analytics version 2.0.9 or later to use hubless mode.
If you currently use an overridden connection to IBM Planning Analytics, you must remove the override to
connect to IBM Planning Analytics version [Link].
An overridden connection looks like this: [Link] For example, http://
[Link]/?pmhub&rest.
You must remove the override and use [Link] For example, http://
[Link]/.
Note that Exploration Views and Quick Reports encode their host information internally. As long as the
<hostname> remains the same when moving from an overridden to a non-overridden connection, you do
not need to modify any views or reports. In any circumstance, it is preferable to update your connection
before interacting with any reporting content.

TM1 Server on Linux requires the Java shared object [Link] to be in the
LD_LIBRARY_PATH
As of TM1 Server version 11.8.2 (Planning Analytics [Link]), the TM1 Server executable ([Link])
requires the Java shared object [Link] to be in the server's LD_LIBRARY_PATH to successfully
start up or shut down a TM1 Server on Linux.
The TM1 Server requires Java to support the ExecuteJavaN or ExecuteJavaS TurboIntegrator
functions. Additionally, with the later versions of Java 8, the TM1 Server needs to be able to shut down
the JVM via the [Link] library. This library is required whether you use ExecuteJavaN or
ExecuteJavaS functions or not. The link to the [Link], which is necessitated to support the noted
Turbointegrator functions, is also required to successfully start or stop the TM1 Server. If the library is
missing, you cannot start or stop the server.
The start_tm1.sh script has been modified to find the required Java shared object [Link] by
looking for the JAVA_HOME environment variable and loading the required library according to processor
architecture.
Depending on your processor architecture, [Link] is located in one of these locations:
• ${JAVA_HOME}/lib/amd64/[Link] for x86_64
• ${JAVA_HOME}/lib/s390x/[Link] for s390x
• ${JAVA_HOME}/lib/ppc64le/[Link] for ppc64le
It is important to have Java 8 installed and the JAVA_HOME environment variable set, otherwise the TM1
Server cannot start up or shut down.

Planning Analytics [Link] - July 27, 2020

IBM Planning Analytics Local version [Link] and the cloud release of IBM Planning Analytics version
[Link] includes updates for IBM TM1 Server version 11.8.1.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

TM1 Web is no longer part of the Planning Analytics long cadence (LC)
release
As of the [Link] LC release of IBM Planning Analytics, TM1 Web is no longer included in the long cadence
release.
Instead, new versions of TM1 Web will be available approximately once a month, similar to the release
schedules of IBM Planning Analytics Workspace and IBM Planning Analytics for Microsoft Excel. The first
version of TM1 Web to be available on this new schedule is 2.0.55 SC.

Chapter 1. What's new in Planning Analytics 7

New installer for TM1 Web
As of the [Link] LC/2.0.55 SC releases of IBM Planning Analytics, TM1 Web is installed with the IBM
Planning Analytics Spreadsheet Services installer. TM1 Web is no longer part of the web tier within the
Planning Analytics Local installer.
For details on installing TM1 Web with the IBM Planning Analytics Spreadsheet Services installer, see
Installing and configuring Planning Analytics TM1 Web.

Planning Analytics [Link] - May 21, 2020

IBM Planning Analytics Local version [Link] and the cloud release of IBM Planning Analytics version
[Link] includes updates for IBM TM1 Server version 11.8.0.
IBM Planning Analytics version [Link] includes numerous improvements and defect fixes, but does not
include new features.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

Planning Analytics 2.0.9 - December 16, 2019

IBM Planning Analytics Local version 2.0.9 and the cloud release of IBM Planning Analytics version 2.0.9
includes updates and new features for IBM TM1 Server version 11.7.0.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

Manage a list of TM1 databases on the TM1 Admin Server

In TM1 Server version 11.7.0, you can set up one TM1 Admin Server that refers to the active TM1
databases for a model. All your users can point to the TM1 Admin Server and you can rapidly switch over
from one TM1 database to another TM1 database. The TM1 Admin Server doesn't need to be restarted,
which means that you can completely automate the failover to the backup system if a crash occurs on a
TM1 database.

GET the list of databases that are available

To see which databases are currently self-registered, you can retrieve the list of TM1 databases that are
registered with the TM1 Admin Server. You can use GET against the ~/api/v1/Servers resource to find
the list of all databases that are available.

GET [Link]

Example response body:

{
"@[Link]": "$metadata#Servers",
"value": [
{
"Name": "24retail",
"SelfRegistered": true,
"Host": "[Link]
"IPAddress": "[Link]",
"IPv6Address": "",
"PortNumber": 17414,
"ClientMessagePortNumber": 0,
"HTTPPortNumber": 8014,
"IsLocal": false,
"UsingSSL": false,
"SSLCertificateID": null,
"SSLCertificateAuthority": null,
"SSLCertificateRevocationList": null,
"ClientExportSSLSvrCert": false,

8 IBM Planning Analytics: Installation and Configuration

 "ClientExportSSLSvrKeyID": null,
"AcceptingClients": true,
"LastUpdated": "2020-01-09T13:44:04.566Z"
},
{
"Name": "GO_New_Stores",
"SelfRegistered": true,
"Host": "[Link]
"IPAddress": "[Link]",
"IPv6Address": "",
"PortNumber": 45557,
"ClientMessagePortNumber": 0,
"HTTPPortNumber": 5010,
"IsLocal": false,
"UsingSSL": true,
"SSLCertificateID": null,
"SSLCertificateAuthority": null,
"SSLCertificateRevocationList": null,
"ClientExportSSLSvrCert": false,
"ClientExportSSLSvrKeyID": null,
"AcceptingClients": true,
"LastUpdated": "2020-01-09T13:44:10.120Z"
},
{
"Name": "GO_Scorecards",
"SelfRegistered": true,
"Host": "[Link]
"IPAddress": "[Link]",
"IPv6Address": "",
"PortNumber": 44321,
"ClientMessagePortNumber": 0,
"HTTPPortNumber": 44312,
"IsLocal": false,
"UsingSSL": true,
"SSLCertificateID": null,
"SSLCertificateAuthority": null,
"SSLCertificateRevocationList": null,
"ClientExportSSLSvrCert": false,
"ClientExportSSLSvrKeyID": null,
"AcceptingClients": true,
"LastUpdated": "2020-01-09T13:44:09.360Z"
},
{
"Name": "Planning Sample",
"SelfRegistered": true,
"Host": "[Link]
"IPAddress": "[Link]",
"IPv6Address": "",
"PortNumber": 12345,
"ClientMessagePortNumber": 0,
"HTTPPortNumber": 12354,
"IsLocal": false,
"UsingSSL": true,
"SSLCertificateID": null,
"SSLCertificateAuthority": null,
"SSLCertificateRevocationList": null,
"ClientExportSSLSvrCert": false,
"ClientExportSSLSvrKeyID": null,
"AcceptingClients": true,
"LastUpdated": "2020-01-09T13:44:02.022Z"
},
{
"Name": "proven_techniques",
"SelfRegistered": true,
"Host": "[Link]
"IPAddress": "[Link]",
"IPv6Address": "",
"PortNumber": 53333,
"ClientMessagePortNumber": 0,
"HTTPPortNumber": 5011,
"IsLocal": false,
"UsingSSL": true,
"SSLCertificateID": null,
"SSLCertificateAuthority": null,
"SSLCertificateRevocationList": null,
"ClientExportSSLSvrCert": false,
"ClientExportSSLSvrKeyID": null,
"AcceptingClients": true,
"LastUpdated": "2020-01-09T13:44:10.173Z"
},
{
"Name": "SData",

Chapter 1. What's new in Planning Analytics 9

 "SelfRegistered": true,
"Host": "[Link]
"IPAddress": "[Link]",
"IPv6Address": "",
"PortNumber": 12346,
"ClientMessagePortNumber": 0,
"HTTPPortNumber": 8010,
"IsLocal": false,
"UsingSSL": true,
"SSLCertificateID": null,
"SSLCertificateAuthority": null,
"SSLCertificateRevocationList": null,
"ClientExportSSLSvrCert": false,
"ClientExportSSLSvrKeyID": null,
"AcceptingClients": true,
"LastUpdated": "2020-01-09T13:44:09.619Z"
},
{
"Name": "MyDB",
"SelfRegistered": true,
"Host": "[Link]
"IPAddress": "[Link]",
"IPv6Address": "",
"PortNumber": 60042,
"ClientMessagePortNumber": 0,
"HTTPPortNumber": 5001,
"IsLocal": false,
"UsingSSL": true,
"SSLCertificateID": null,
"SSLCertificateAuthority": null,
"SSLCertificateRevocationList": null,
"ClientExportSSLSvrCert": false,
"ClientExportSSLSvrKeyID": null,
"AcceptingClients": true,
"LastUpdated": "2020-01-09T13:44:09.475Z"
}
]
}

GET details for a specific database

You can do a GET against a specific database, for example, ~/api/v1/
Servers('<database_name>'), to retrieve details of that database.

GET [Link]

Example response body for GET [Link]

{
"@[Link]": "$metadata#Servers/$entity",
"Name": "SData",
"SelfRegistered": true,
"Host": "[Link]
"IPAddress": "[Link]",
"IPv6Address": "",
"PortNumber": 12346,
"ClientMessagePortNumber": 0,
"HTTPPortNumber": 8010,
"IsLocal": false,
"UsingSSL": true,
"SSLCertificateID": null,
"SSLCertificateAuthority": null,
"SSLCertificateRevocationList": null,
"ClientExportSSLSvrCert": false,
"ClientExportSSLSvrKeyID": null,
"AcceptingClients": true,
"LastUpdated": "2020-01-09T13:54:10.343Z"
}

10 IBM Planning Analytics: Installation and Configuration

POST a database to your list of available TM1 databases
You can add another TM1 database to your list of available databases. POST changes to the database list
on the TM1 Admin Server as a collection of Server entities.

POST [Link]

Example body with a database to add:

{
"Name":"MyModel1",
"IPAddress":"[Link]",
"PortNumber":12345,
"UsingSSL": true,
"ClientMessagePortNumber":61098,
"HTTPPortNumber":12999,
"ClientExportSSLSvrCert":true,
"ClientExportSSLSvrKeyID":"whateverExportSSLSvrKeyID",
"AcceptingClients":true
}

Example response body for POST, which shows defaults applied

{
"@[Link]": "$metadata#Servers/$entity",
"Name": "MyModel1",
"SelfRegistered": false,
"Host": null,
"IPAddress": "[Link]",
"IPv6Address": "",
"PortNumber": 12345,
"ClientMessagePortNumber": 61098,
"HTTPPortNumber": 12999,
"IsLocal": false,
"UsingSSL": true,
"SSLCertificateID": null,
"SSLCertificateAuthority": null,
"SSLCertificateRevocationList": null,
"ClientExportSSLSvrCert": true,
"ClientExportSSLSvrKeyID": "whateverExportSSLSvrKeyID",
"AcceptingClients": true,
"LastUpdated": "2020-01-09T22:09:19.838Z"
}

PATCH a database to your list of available TM1 databases

Use PATCH to upsert (insert or update) a database to your list of available databases. PATCH changes to
the database list on the TM1 Admin Server as a collection of Server entities.

PATCH [Link]

Example body with a database to insert or update:

Some properties are not required in the body. The response body shows you the defaults that are applied.

{
"Name": "MyModel2",
"IPAddress":"[Link]",
"PortNumber":12345,
"UsingSSL":false
}

Example response body for PATCH, which shows defaults applied

{
"@[Link]": "$metadata#Servers/$entity",
"Name": "MyModel2",
"SelfRegistered": false,
"Host": null,
"IPAddress": "[Link]",
"IPv6Address": "",
"PortNumber": 12345,
"ClientMessagePortNumber": 0,

Chapter 1. What's new in Planning Analytics 11

 "HTTPPortNumber": 0,
"IsLocal": false,
"UsingSSL": false,
"SSLCertificateID": null,
"SSLCertificateAuthority": null,
"SSLCertificateRevocationList": null,
"ClientExportSSLSvrCert": false,
"ClientExportSSLSvrKeyID": null,
"AcceptingClients": false,
"LastUpdated": "2020-01-09T13:51:13.770Z"
}

PATCH or DELETE a specific TM1 database

You can PATCH updates to individual TM1 databases or DELETE individual TM1 databases only if they
were added using the TM1 REST API. Both of these requests use the same format.
The request body for a PATCH to an individual database cannot have the Name property because this
property is implied by the URL.

PATCH [Link]

{
"IPAddress":"[Link]",
"PortNumber":12345,
"UsingSSL":false
}

You don't need a request body to DELETE an individual database.

DELETE [Link]

Use the ViewZeroOut TurboIntegrator function on MDX views

The ViewZeroOut TurboIntegrator function now works on MDX-based views. You can zero out the data of
views with intersections that are unique to elements that exist only in hierarchies. For all views, including
multi-hierarchy views, ViewZeroOut collects intersected leaf sets before it sets all data points in a view to
zero.
Related topics:
ViewZeroOut

Use dynamic shapes and images in websheets

Customize your websheets! In TM1 Web, you can dynamically insert shapes and images anywhere in your
websheet where you’d like the image to change when the value of a cell changes. You can dynamically
insert logos, employee pictures, flags, product images, and more.
A dynamic image can be created by assigning a named range that contains an INDIRECT or INDEX-based
formula to an image object. The formula resolves to a cell reference, and if an image is anchored to that
cell, the dynamic shape reflects that image object's content.
To support this feature, TM1 Web persists the assigned formula, and when it recalculates, TM1 Web
evaluates the named range formula to a cell reference. Using this cell reference, TM1 Web can then
update the image object's file name to match the referenced image.

12 IBM Planning Analytics: Installation and Configuration

Open a websheet on the active tab when you save a multi-tab websheet
If you have a websheet with multiple tabs in a book, Planning Analytics Workspace keeps track of the
active websheet tab when you save the book. Then, when you open the book in Planning Analytics
Workspace later, you are right where you left off in your work!

Using Planning Analytics version 2.0.9 and Planning Analytics Workspace version 2.0.46, when you open a
book with a websheet in Planning Analytics Workspace, the tab that you saved the websheet with is
active.
Note : You must be using Planning Analytics Workspace on IBM Planning Analytics version 2.0.9 to take
advantage of this feature of websheets in IBM Planning Analytics TM1 Web.
If you don't have Planning Analytics version 2.0.9, the default tab that the websheet was published with
(using TM1 Perspectives or Planning Analytics for Microsoft Excel) is active when you open the book in
Planning Analytics Workspace.

Deprecation of TM1 Operations Console

Deprecated in v2.0.9 In Planning Analytics version 2.0.9, TM1 Operations Console is no longer supported.
When you access the TM1 Operations Console URL, you see a general 500 error message that indicates
that the URL is not available. You can use IBM Planning Analytics Administration to monitor databases in
IBM Planning Analytics and IBM Planning Analytics Local.
Related topics:
Monitor and administer databases

Planning Analytics 2.0.8 - July 17, 2019

IBM Planning Analytics Local version 2.0.8 and the cloud release of IBM Planning Analytics version 2.0.8
includes updates and new features for IBM TM1 Server version 11.6.0.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

View process rollback and restart messages in TM1 logs

This update makes it easier to detect lock exceptions for TurboIntegrator processes, and makes it easier
to process the [Link] file with automation tools. When a TurboIntegrator process rolls back and
restarts, the process is now represented in the [Link] file as three steps: starting, restarting
because of lock contention or rollback, and then finishing. An entry was added to the [Link]
file that shows the TurboIntegrator process as restarting due to lock contention or rollback instead of just
starting. This logging is enabled by default without setting any specific debug options.

Example log

2364 [15] INFO 2019-01-09 20:30:37.986 [Link] Process

"[Link].DimensionWrite1" executed by user "CJP/stuart"

Chapter 1. What's new in Planning Analytics 13

 17088 [15] INFO 2019-01-09 20:30:37.987 [Link] Process
"[Link].DimensionWrite2" executed by user "CJP/stuart"
17088 [15] INFO 2019-01-09 20:30:41.058 [Link] Process
"[Link].DimensionWrite2" rolled back due to lock exception (2364). Process will restart
automatically"
2364 [15] INFO 2019-01-09 20:30:41.054 [Link] Process
"[Link].DimensionWrite1": finished executing normally, elapsed time 3.07 seconds
17088 [15] INFO 2019-01-09 20:30:41.058 [Link] Process
"[Link].DimensionWrite2" executed by user "CJP/stuart"
17088 [15] INFO 2019-01-09 20:30:44.064 [Link] Process
"[Link].DimensionWrite2": finished executing normally, elapsed time 3.00 seconds

View and report on audit log data with the TM1 REST APIs
You can retrieve audit logs by using the TM1 REST APIs the same way that you retrieve other logging data
such as transaction and message logs. You can also use ODATA filters such as top, skip, and select for
querying the details of audit logs. The contents of the audit log is unchanged.
If you are authorized to get audit logs, you can use the following query to retrieve audit logs:

/api/v1/AuditLogEntries

Note : If you are not authorized to get audit logs, for example if you are not an administrator, the result of
this query is empty.
If the audit log has details, you can expand the AuditDetails by using the following query:

/api/v1/AuditLogEntries?$expand=AuditDetails

You can use filter options, such as top, skip, and select, to create queries based on any data field,
including the time stamp. For example:

$filter=TimeStamp gt 2019-04-23T11:13:45Z
$filter=contains(Description, 'New')
$filter=ObjectType eq ‘Dimension’
$select=UserName,Description,ObjectType,ObjectName
$count=true
$skip=2
$top=4

You can also use change tracking. When you set the Prefer header to [Link]-changes, a delta
link is appended to each response body.
You can use TailAuditLog() to obtain the current timeStamp only. Then, you can use /api/v1/
AuditLogEntries/!delta('<timestamp>') to retrieve any audit logs that occur after that
timeStamp. For example:

/api/v1/AuditLogEntries
/api/v1/AuditLogEntries/!delta('<timestamp>')

Or:

/api/v1/AuditLogEntries?$select=User,ObjectType,ObjectName,Details&$expand=
AuditDetails($select=ID,User,Description,ObjectType,ObjectName)

Example of an auditLog entry

{
"ID":"<id>",
"TimeStamp":"2019-01-16T13:57:46Z",
"User":"",
"Description":"Server 'lemonade' was shutdown.",
"ObjectType":"Server",
"ObjectName":"SYSTEM"
}

14 IBM Planning Analytics: Installation and Configuration

 Example auditLogEntry with AuditDetails

{
"ID":"<id>",
"TimeStamp":"2019-01-16T13:59:50Z",
"User":"",
"Description":"Server 'lemonade' was started.",
"ObjectType":"Server",
"ObjectName":"SYSTEM",
"AuditDetails":[
{
"DetailID":"<id>",
"TimeStamp":"2019-01-16T13:59:50Z",
"User":"",
"Description":"Property ChangedSinceLoaded was set to 'FALSE' for server 'lemonade'.",
"ObjectType":"Server",
"ObjectName":"SYSTEM"
}
]
}

TM1 REST API updates

The following entity types were added to support audit logging:
• AuditDetail
• AuditLogEntry
The following function was added to support audit logging:
• TailAuditLog

What's next?
For more information about audit logging in general, see Using the audit log.

Iterate through SQL rowsets to speed up drill through queries

You can use TM1 REST API actions and entities to execute a relational drill through and retrieve results as
a rowset entity. You can use the rowset to iteratively retrieve subsequent subset rows. This approach
improves the performance of retrieving drill through results.

Actions
In Planning Analytics version 2.0.8, you can use the following actions to execute relational drillthroughs
but return rowsets:
• Use ExecuteRelationalDrillthroughWithRowset to execute a relational drill through to get a rowset of a
relational table.
• Use [Link] to drill into a cell to get a rowset of a relational table.

Entity types
In Planning Analytics version 2.0.8, you can use the following entity types:
• A Rowset represents the result of an execution of a relational drill through. A rowset is session-scoped
and must be deleted after you use it. Closing a session invalidates all of its rowsets.
• A RowsetRow represents a row in a rowset. The RowsetRow can be retrieved in subsequent requests.
These subsequent requests do not cause the drillthrough process to be re-executed.

Example: Drill into a cell to get a rowset

POST /api/v1/Cubes('x')/Views('x')/[Link]
POST /api/v1/Cellsets('x')/Cells(N)/DrillthroughScripts('x')/[Link]

Chapter 1. What's new in Planning Analytics 15

 GET /api/v1/Rowsets('x')?$expand=Rows($top=1000)
DELETE /api/v1/Rowsets('x')

Example: Use a transient process to open a CSV rowset

POST /api/v1/ExecuteRelationalDrillthroughWithRowset?$expand=Rows($select=A,B)
{
"DrillthroughProcess":
{
"EpilogProcedure": "#****Begin: Generated Statements***\r\nReturnCsvTableHandle;\r
\n#****End: Generated Statements****",
"DataSource": {
"Type": "ASCII",
"asciiDelimiterChar": ",",
"asciiDelimiterType": "Character",
"dataSourceNameForServer": "CSV_FILENAME.csv"
}
}
}

Review updates to the TM1 REST API metadata

IBM Planning Analytics Local version 2.0.8 and the cloud release of IBM Planning Analytics version 2.0.8
includes the following updates to the TM1 REST APIs for IBM TM1 Server version 11.6.0.

Metadata updates
The following entity types were changed in 11.6.0:
• Added AuditDetail
• Added AuditLogEntry
• Added Rowset
• Added RowsetRow
The following functions were changed in 11.6.0:
• Added TailAuditLog
The following actions were changed in 11.6.0:
• Added ExecuteRelationalDrillthroughWithRowset
• Added [Link]
• Added [Link]
• Added [Link]
To learn more, see What's new in 11.6.0 ([Link]
SSD29G_2.0.0/[Link].tm1_rest_api.[Link]/
r_restapi_v1_csdl_whats_new.html#restapi_v1_csdl_whats_new_11_6_0).

Include user names and memory usage in TM1 Web logs

User names and memory usage are included in TM1 Web logs. This update makes it easy to see when a
user runs an active form, workbook, or cube that renders too many rows. To turn on this optional logging,
the logging level of [Link].tm1 must be set to DEBUG in the
\tm1_64\webapps\tm1web\WEB-INF\configuration\[Link] file. You can review the
audit logs and reduce the number of rows in the rendering.
The following information is included in logs:
• Timestamp
• Application and Active Form name
• Number of rows that were generated

16 IBM Planning Analytics: Installation and Configuration

 • User name
• Current heap memory after the websheet renders

Example log when you open an active form

"<TIMESTAMP>:CLASSNAME:Constructed view for <ActiveFormViewid> contains <#> rows, by user

'<username>'.
<TIMESTAMP>:CLASSNAME:Current heap memory usage: <MB>".

Example log when you open a workbook

"<TIMESTAMP>:CLASSNAME:Creating WorkbookMetaData for <sheet name>, by user '<username>'.

<TIMESTAMP>:CLASSNAME:Current heap memory usage: <MB>".

Example log when you open a cube view

"<TIMESTAMP>:CLASSNAME:Exit from getUpdatedCubeViewData, updatedData: class name, username:

<username>.
<TIMESTAMP>:CLASSNAME:Current heap memory usage: <MB>".

Changes saved automatically in TM1 Application Web

In Planning Analytics version 2.0.8, the Save confirmation dialog box in IBM TM1 Application Web has
been removed. When you close a view, you are not prompted to save changes. All data changes are saved
automatically when you close the application. Your changes are available when you reopen the
application. This change applies to all web browsers.

Configure login using TM1 Web URL API with Cognos Analytics security
In Planning Analytics version 2.0.8, a new parameter CSPHeaderFrameSource is available in the
tm1web_config.xml file. If you use the TM1 Web URL API configured with integrated security mode 5
(Cognos® Analytics security authentication), you must set this parameter to allow users to log in. This
parameter controls security of the context that is loaded in the <frame> element, which is used by TM1
Web URL API. The CSPHeaderFrameSource parameter defines allowed sources for Content-Security-
Policy (CSP) frame-src policy.

Syntax
<add key="CSPHeaderFrameSource" value="" />

If the CSPHeaderFrameSource is specified, it sets the allowed sources for the frame-src policy. If the
value is left blank or the parameter is not set, the default value is '*', which allows content from all sources
to load.
Remember : In IBM Planning Analytics Local version 2.0.8, you install a new version of the
tm1web_config.xml file that is called tm1web_config.[Link] and your existing
tm1web_config.xml file is preserved. To take advantage of fixes that are applied to this release, you
must rename the tm1web_config.[Link] file to tm1web_config.xml and you must reapply any
changes that you made to your previous configuration settings.

Example

<add key="CSPHeaderFrameSource" value="'self'" />

Sets the frame-src policy to 'self'.

Allows contents from the site's origin to load.

Chapter 1. What's new in Planning Analytics 17

 Example

<add key="CSPHeaderFrameSource" value="[Link] http://

TM1WEB_HOST:TM1WEB_PORT" />

Sets the frame-src policy to [Link] [Link]

Allows contents from CAM_HOST:PORT and TM1WEB_HOST:PORT to load.

What to do next
For more information on how to define sources for frame-src, see Sources on the MDN web docs site.

Relational data sources in TM1 Web websheets removed

Removed in v2.0.8 The ability to use relational data sources in TM1 Web has been removed from IBM
Planning Analytics Local version 2.0.8. The IBM Data Server Driver for JDBC and SQLJ 4.17 ([Link])
have also been removed from the installation kit ([Link], [Link], [Link], [Link]).
Planning Analytics version 2.0.7 was the last release with support for relational data sources in TM1 Web
websheets.

TM1 Package Connector removed from Planning Analytics Local

Removed in v2.0.8 With IBM Planning Analytics Local version 2.0.8, the IBM Cognos Package
Connector is no longer included in the Planning Analytics Local installation kit. This change does not affect
Planning Analytics on cloud. Cognos Package Connector is not available or supported in Planning
Analytics on cloud.

Planning Analytics 2.0.7 - April 29, 2019

IBM Planning Analytics Local version 2.0.7 and the cloud release of IBM Planning Analytics version 2.0.7
includes updates and new features for IBM TM1 Server version 11.5.0.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

Install IBM Planning Analytics Local on Windows Server 2019

IBM Planning Analytics Local is now supported on Windows Server 2019.
To learn more, see Planning Analytics Local Installation and Configuration ([Link]
support/knowledgecenter/SSD29G_2.0.0/[Link].tm1_inst.[Link]/pa_install.html)..

Upgrade to WebSphere Liberty Profile [Link]

The WebSphere Liberty Profile has been upgraded to [Link]. This upgrade requires a manual change to
the [Link] file for existing IBM Planning Analytics Local installations that upgrade to Planning
Analytics Local version 2.0.7.
In Planning Analytics Local version 2.0.7, the [Link] file has been updated to add the following
property to disable sending server version information in response headers.
<webContainer disableXPoweredBy="true"/>
The response header is informational and not required for operations. It is now disabled by default to
minimize thread surface.
Remember : In Planning Analytics Local version 2.0.7, you install a new version of the [Link] file
that is called [Link] and your existing [Link] file is preserved. To take advantage of

18 IBM Planning Analytics: Installation and Configuration

 fixes that are applied to this release, you must rename the [Link] file to [Link] and you
must reapply any changes that you made to your previous configuration settings.
For more information, see Upgrading Planning Analytics Local ([Link]
knowledgecenter/SSD29G_2.0.0/[Link].tm1_inst.[Link]/
c_tm1_inst_upgradingfromearlierversionsoftm1.html).

Optimize the login process with a new [Link] parameter

A new parameter, OptimizeClient, has been added to the [Link] file to prevent obtaining a lock
when serializing objects when a user authenticates. This parameter determines whether private objects
are loaded when the user authenticates during TM1 Server startup.
Note : A new user that was dynamically added, who logs in with CAM authentication, is still subject to lock
contention because a new element must be added to the }clients dimension.
Organizations with many users, or users with many private objects, can set which users this parameter is
applied to. This approach impacts the server load and potentially the amount of memory that is consumed
at startup.
The OptimizeClient parameter can be set as follows:
• None = 0
• OperationsAdmin = 1
• Admin = 2
• All = 3
For more information, see OptimizeClient ([Link]
SSD29G_2.0.0/[Link].tm1_inst.[Link]/c_optimizeclient.html).

Monitor threads with the Top logger

TM1 Server dynamically monitors the threads that are running and now outputs thread status to the
[Link] file by using the Top logger. You can also log information about the sandboxes and job
queue for a specific database.
You can use the new Top logger in IBM Planning Analytics on cloud and IBM Planning Analytics Local. You
can download the logs from IBM Planning Analytics Administration. For more information, see Download
database log files.
Note : The content of the [Link] file is the same as the TM1Top logs. The TM1Top utility is
scheduled for deprecation on Planning Analytics Local.

Configure [Link] parameters

The Top logger is Off by default. To enable logging, you must add TopLogging=T to the [Link] file
before you start your TM1 Server.
Note : This parameter cannot be configured in Planning Analytics Administration.
The following settings can be configured in the [Link] file:
TopLogging
Enables dynamic logging of the threads running in an instance of the TM1 Server. The Top logger can
also display information about the sandboxes and job queue for a specific database.
Boolean, dynamic
Default=FALSE
TopScanFrequency
The logging frequency (interval) in seconds.
Integer, dynamic
Default is 5 seconds

Chapter 1. What's new in Planning Analytics 19

 0 disables the Top logger.
[Link]
Enables logging of the current processing state of each thread. This information includes the name of
the user or process that started the thread, the API function that the thread is executing, the lock
status of the last object that was locked, the number of objects that are used by the thread, and the
total time, in seconds, that the current API function or chore process has been processing.
Default = T
[Link]
Enables logging of the active sandboxes for the current server, the total memory that is consumed for
all sandboxes by a user, and the number of sandboxes for this user.
Default = F
[Link]
Enables logging of sandbox queue metrics. The name of the node for the sandbox, the status of the
sandbox in the queue, and the length of time the sandbox was in the queue before it was processed is
logged for each sandbox in the queue.
Default = F
For more information, see Parameters in the [Link] file.
If TM1 Server starts with TopLogging turned on, the server adds the Top logger configuration to the
[Link] file if the configuration is not already there. The log level is INFO. The special
log format is controlled by the format parameter of the definition, which must be set to TM1Top.
The following configuration information is added:

[Link]=INFO, S_Top
[Link].S_Top=[Link]
[Link].S_Top.MemorySize=5 MB
[Link].S_Top.MaxFileSize=100 MB
[Link].S_Top.MaxBackupIndex=20
[Link].S_Top.File=[Link]
[Link].S_Top.Format=TM1Top

After the Top logger is enabled and the configuration settings are added to the [Link],
you can disable or enable the Top logger without restarting the TM1 Server.

TM1 REST API support

The Top logger and its settings can be read and modified by using the TMI REST API:

GET /api/v1/ActiveConfiguration/Administration/TopLog
PATCH /api/v1/StaticConfiguration/Administration/TopLog
{
"ScanFrequency": "P0DT00H00M02S"
}
GET /api/v1/Loggers('Top')
PATCH /api/v1/Loggers('Top')
{
"Level": "Off"
}

For more information, see TopLogSettings and TopScanMode.

Log example

===== 2019-01-09 22:20:54 GMT 2019-01-09 17:20:54 local ===== Server:Planning Sample
===========
10744 Th:Pseudo - Idle - -
- - 0
22584 Th:DynamicConfig - Idle - -
- - 0
676 Admin :1 Idle - -
- - 0
4920 Sa Architect Idle - -

20 IBM Planning Analytics: Installation and Configuration

 - - 0
===== 2019-01-09 22:20:56 GMT 2019-01-09 17:20:56 local ===== Server:Planning Sample
===========
8120 C:SleepEvery10s - Run:R - Process SyncSleep_10 Prolog
(6) 0
10744 Th:Pseudo - Idle - -
- - 0
22584 Th:DynamicConfig - Idle - -
- - 0
676 Admin :1 Run:R - POST /api/v1/Cubes('plan_BudgetPlan')/Views('def')/
[Link] - 1
22620 > Work unit for 676 - - -
- - 0
3284 > Work unit for 676 - - -
- - 0
22376 > Work unit for 676 - - -
- - 0
17568 > Work unit for 676 - - -
- - 0
2940 > Work unit for 676 - - -
- - 0
128 > Work unit for 676 - - -
- - 0
20552 > Work unit for 676 - - -
- - 0
4920 Sa Architect Idle - - -
- 0

Run multiple processes on their own thread with a new TurboIntegrator

function
You can now run TurboIntegrator processes in parallel, each on its own thread that is managed by TM1
Server, by using the new RunProcess function. This approach speeds up data load and other operations
where TurboIntegrator processes are used to divide the work.
You can use the new RunProcess(ProcessName, [ParamName1, ParamValue1,ParamName2,
ParamValue2]); function to run TurboIntegrator processes in parallel on a separate thread within the
server. By using the RunProcess function, issues such as external encrypted credentials can be avoided.
For more information, see RunProcess.

Prepare for changes in behavior in TM1 Server

IBM Planning Analytics Local version 2.0.7 and the cloud release of IBM Planning Analytics version 2.0.7
includes updates that change behavior in IBM TM1 Server version 11.5.0. Review this list to prepare for
your upgrade.

Default logging level of [Link] logger

In IBM Planning Analytics version 2.0.7 or later, the [Link] logger reports syntax errors only
when set to DEBUG level.
Previously, in IBM Planning Analytics version 2.0.6 or earlier, the [Link] logger reported
syntax errors when it was set to ERROR level. However, when Planning Analytics for Microsoft Excel or
Planning Analytics Workspace generated invalid MDX internally, the tm1server log filled up quickly with a
large number of entries in the form:

11276 [6b5] ERROR 2017-10-16 13:51:10.237 [Link]

Syntax error at or near: 'hildren},{[Entity].[]})}', character position 21

These errors now appear only when the logging level is set to DEBUG. For more information, see System
and performance monitoring ([Link]
[Link].tm1_op.[Link]/c_systemandperformancemonitoring_n160007.html).

Chapter 1. What's new in Planning Analytics 21

 Default value of RulesOverwriteCellsOnLoad parameter
In IBM Planning Analytics version 2.0.7 or later, if the RulesOverwriteCellsOnLoad parameter is not
present in the configuration file then it is assumed to be False by default. This is a change in behavior.
Previously, in IBM Planning Analytics version 2.0.6 or earlier, if this parameter was not present in the
configuration file then it was assumed to be True by default.
For more information, see RulesOverwriteCellsOnLoad ([Link]
knowledgecenter/SSD29G_2.0.0/[Link].tm1_inst.[Link]/
c_rulesoverwritecellsonload.html).

Searching large transaction logs

In IBM Planning Analytics version 2.0.7 or later, if there are too many INVALID records, for example more
than 500 invalid records in one search in the transaction logs, search stops and an error message is
generated in the server log. User intervention is required to clean up the transaction logs. This change
prevents the server from searching for long periods and blocking other activities.
For example, the error message contains the following text:
Starts from <file name>, over 500 bad transaction records found, transaction
log searching stopped.
The error message indicates where the search was started. For example, if the user searched from
December 1 to December 12, the server searches multiple log files. The "Starts from" indicates where in
the transaction logs the cleanup must start.
This change in the behavior of searching large transaction logs prevents the TM1 Server from generating
large logs. However, user intervention is required to clean up the invalid records if the logs become too
large.

Learn more about updates to TM1 REST APIs

IBM Planning Analytics Local version 2.0.7 and the cloud release of IBM Planning Analytics version 2.0.7
includes the following updates to the TM1 REST APIs for IBM TM1 Server version 11.5.0.

Metadata updates
The following entity types were changed in 11.5.0:
• Added GitPlan
• Added GitPullPlan
• Added GitPushPlan
The following complex types were changed in 11.5.0:
• Added Git
• Added GitCommit
• Added GitRemote
• Added TopLogSettings
The following enumerated types were changed in 11.5.0:
• Added GitPlanExecutionMode
• Added TopScanMode
The following actions were changed in 11.5.0:
• Added [Link]
• Added [Link]
• Added GitDeploy

22 IBM Planning Analytics: Installation and Configuration

 • Added GitInit
• Added GitPull
• Added GitPush
• Added GitStatus
• Added GitUninit
The following properties were changed in 11.5.0:
• Deprecated property ID in Entry
• Added property Active in Session
To learn more, see What's new in 11.5.0 ([Link]
SSD29G_2.0.0/[Link].tm1_rest_api.[Link]/
r_restapi_v1_csdl_whats_new.html#restapi_v1_csdl_whats_new_11_5_0).

Support for hiding hierarchies

The Visible property of a Hierarchy ([Link]
SSD29G_2.0.0/[Link].tm1_rest_api.[Link]/
r_restapi_v1_csdl_alltypes.html#restapi_v1_csdl_entitytype_Hierarchy) entity has been extended to
allow a client to filter any collection of hierarchies.
For example:

GET /api/v1/Dimensions('dim')/Hierarchies?$filter=Visible eq true

By default, the Visible property is determined by the Visible dimension property (currently this is in
the }DimensionProperties cube, which includes every individual hierarchy). This property defaults to True.
If a control cube exists with the name }HierarchyVisibility_{{DIMNAME}}, which has two
dimensions: }Hierarchies_{{DIMNAME}} and }Groups, then more specific values here will overwrite the
default dimension property (if TRUE or FALSE is written to the appropriate cell). Similar to security, if a
user belongs to multiple groups, and any of those groups sets the hierarchy as visible, then the hierarchy
will be visible.
Determining the value of the Visible property uses the following logic:
• Is there a value of TRUE anywhere in the }HierarchyVisibility_{{DIMNAME}} cube for this hierarchy or any
group the current user belongs to? Then, Visible = true.
• Is there a value of FALSE anywhere in the }HierarchyVisibility_{{DIMNAME}} cube for this hierarchy or
any group the current user belongs to? Then, Visible = false.
• Is the value of the VISIBILITY dimension property (note that this is per hierarchy) set to TRUE? Then,
Visible = true.
• Is the value of the VISIBILITY dimension property set to FALSE? Then, Visible = false.
• Otherwise, Visible = true.

Use Git source control to deploy database assets between environments

As an administrator of a TM1 database, you can deploy database assets between environments (for
example, from development to production) without stopping the database or manually copying and
pasting assets. The source specifications of models and their database assets are created and managed
with Git commands. You can see the structure of the database assets in Git and use Git commands to add
and remove versions of your assets easily.

Why is this useful?

• You can see your database assets in an easy to read format. Assets can include chores, cubes,
dimensions, processes, and more.
• You can build different versions of your database assets by using Git branches.

Chapter 1. What's new in Planning Analytics 23

 • You can control which versions of your database assets you use for your environments. Use one branch
for your development environment and another for your production environment.
• You can see the differences between versions of your database assets easily. You can even revert to
previous versions if you need to.
• You can deploy your database assets directly to your environment by using Git commands.
Note : This capability is available only in Planning Analytics Local.
To learn more, see Managing TM1 database assets with Git ([Link]
knowledgecenter/SSD29G_2.0.0/[Link].tm1_rest_api.[Link]/
c_tm1_restapi_model_deployment.html).

Load websheets faster in TM1 Web

To optimize loading of websheets in TM1 Web, you can set a new feature flag
OptimizeCssForHiddenContent. The feature flag can be added in tm1_64\webapps\tm1web\WEB-
INF\configuration\[Link].
When OptimizeCssForHiddenContent is set to true, CSS style information that comes from hidden
content (sheets, rows, columns, cells, or controls) is excluded during websheet loading.
OptimizeCssForHiddenContent is set to false by default.

Example

{
"NestedDbsEvaluation": false,
"NewIrrAlgorithm": false ,
"OptimizeCssForHiddenContent": true
}

Use the IFERROR Excel function in TM1 Web

IBM Planning Analytics TM1 Web now supports the use of the IFERROR function in websheets.
The IFERROR function traps errors in a formula and returns an alternative result, such as text, when an
error is detected.

Take advantage of improved cell formatting in TM1 Web websheets

The cell formatting of currency, fractions, phone numbers, and social security numbers in TM1 Web
websheets has improved.
The following changes have been made to formatting of cells in websheets:
• For numbers with more than 15 digits, cells in websheets round up the number to the first 15 digits. For
example, "123456789123456992.00" appears as "123456789123457000.00". In Excel, only the first
15 digits are stored and remaining digits are replaced by zeros. For example,
"123456789123456992.00" appears as "123456789123456000.00".
• Currency appears with no space after the $ sign. Negative currency also appears with no space after the
dollar sign. For example, "$99.00" and "-$999.00".

24 IBM Planning Analytics: Installation and Configuration

 • Fractions are formatted to appear in fraction format "# ??/??" with a space between the whole number
and the fraction. When the number is a whole number, the cell is formatted without a space after the
whole number.
• Phone numbers are formatted as "(nnn) nnn-nnnn" as in Excel.
• Social security numbers are formatted with the first 9 digits. Any digits that follow the first 9 digits are
truncated. For example, "1849348202" appears as "184-93-4820" with the last digit "2" truncated.
This formatting is different in Excel. For numbers with more than 9 digits, Excel adds the format to the
last 9 digits while the additional digits at the beginning don't change. For example, in Excel,
"1849348202" appears as "1849-34-8202".

TM1 Web version 2.0.6 or TM1 Web version 2.0.7 or later Cell formatting in Excel
earlier

This cell formatting is enabled by default in TM1 Web websheets with the feature flag
NewDataFormatter. The feature flag can be set in tm1_64\webapps\tm1web\WEB-INF
\configuration\[Link].

Example

{
"NestedDbsEvaluation": false,
"NewIrrAlgorithm": false ,
"NewDataFormatter": true
}

Check out updated TM1 Web configuration defaults

The following TM1 Web configuration parameters have new default settings. These settings were
previously recommendations. They are now default settings in the tm1web_config.xml file for new
installations of TM1 Web.
Note : Some default configuration parameter values for Planning Analytics on cloud are different than in
Planning Analytics Local.
ExportCellsThreshold
Specifies the maximum number of cells that an export of a websheet or a cube view can contain.
Default changed from blank to 1000000.
MaximumConcurrentExports
Specifies the maximum number of concurrent exports that can be executed from TM1 Web.
The default value in Planning Analytics on cloud is set to 3. This default value is unchanged.
The default value in Planning Analytics Local is changed from 5 to 4.
MaximumSheetsForExport
Specifies the maximum number of sheets that are allowed to export.
Default changed from 100 to 50.

Chapter 1. What's new in Planning Analytics 25

 WorkbookMaxCellCount
Specifies the maximum cell count of a workbook as a number with no thousands separators.
Default changed from -1 to 500000.
For more information, see TM1 Web configuration parameters.

Review deprecation notices

The following tools and components are deprecated or scheduled for deprecation in IBM Planning
Analytics version 2.0.7. Review deprecation details for IBM Planning Analytics version 2.0.7 in
Deprecation notices for IBM Planning Analytics.
• Relational data sources in TM1 Web websheets (local only)
Planning Analytics version 2.0.7 is the last release with support for relational data sources in TM1 Web
websheets.
• IBM TM1 Package Connector (local only)
Planning Analytics version 2.0.7 is the last release of TM1 Package Connector.
• Advanced Rules Editor (TM1 Architect and TM1 Perspectives only)
As of Planning Analytics version 2.0.7, the AdvancedRulesEditor parameter in the [Link] file is
ignored. The Advanced Rules Editor does not launch in TM1 Architect and TM1 Perspectives, only the
basic rule editor launches.
• IBM TM1 Operations Console
IBM TM1 Operations Console is scheduled for deprecation. You can use IBM Planning Analytics
Administration to monitor databases in IBM Planning Analytics and IBM Planning Analytics Local.
To learn more, see Monitor and administer databases ([Link]
SSD29G_2.0.0/[Link].tm1_prism_gs.[Link]/c_paw_administer_servers.html)..
• IBM Cognos Performance Management Hub
IBM Cognos Performance Management Hub (PMHub) is scheduled for deprecation.
In Planning Analytics version 2.0.7, the following features have been disabled in PMHub because of
security vulnerabilities:
– Watchlists ([Link])
– Async job API ([Link])
– Pmpsvc passthrough support for PMHub ([Link])
– Support for old PMHub TM1 v1 requests ([Link])
If you currently use these features, you have the option of maintaining a TM1 Server that is installed
with Planning Analytics version 2.0.6 (ring-fenced by a firewall if necessary) and change any systems
that use these features to reference this server.
• IBM TM1 Top utility
The TM1 Top utility is scheduled for deprecation.

Planning Analytics 2.0.6 - October 11, 2018

IBM Planning Analytics Local version 2.0.6 and the cloud release of IBM Planning Analytics version 2.0.6
includes updates and new features for IBM TM1 Server version 11.4.0.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

26 IBM Planning Analytics: Installation and Configuration

Upgrade to Java 8 and removal of Java 7
Planning Analytics Local has been upgraded to Java™ [Link].
Important : You must stop all related IBM Cognos TM1 and IBM Planning Analytics services before you
upgrade to Planning Analytics version 2.0.6.
On Windows, if the installation detects an existing JRE 7, a new JRE 8 is installed during the installation,
and the JRE 7 cacerts file is copied to the Java80\jre\lib\security location. If you have an
existing Java80 folder, the cacerts file is not copied over. The existing Java70 folder is removed. On
Linux®, you must install Java [Link].
Note : With the upgrade to Java 8 in Planning Analytics version 2.0.6, some tools such as the IBM Key
Management tool ([Link]), are now located in the <PA_install_directory>\jre\bin
directory of the Planning Analytics installation or in the IBM JRE installation if Linux used.
For more information, see Upgrading from Planning Analytics version 2.0.0 ([Link]
support/knowledgecenter/SSD29G_2.0.0/[Link].tm1_inst.[Link]/
t_tm1_inst_upgrade_200.html).

ThirdPartyCertificateTool no longer supported

Not supported in v2.0.6 + The ThirdPartyCertificateTool requires Java 7 and is not supported in
Planning Analytics version 2.0.6 or later.

New TurboIntegrator functions to delete leaf elements from dimension or

hierarchy
You can use TurboIntegrator functions to delete leaf elements from a dimension or hierarchy using a
subset of elements for higher performance.
DimensionDeleteElements( dimension, subset)
The subset provides the list of elements to delete from the indicated dimension. The subset is usually
temporary.
HierarchyDeleteElements( dimension, hierarchy, subset)
If you use HierarchyDeleteElements and the indicated hierarchy is the Leaves hierarchy, then the
subset should list those leaves that should be deleted, and they are removed completely from the
dimension.

New parameter to configure session timeout for TM1 Web

In IBM Planning Analytics Local version 2.0.6, there is a new parameter in the tm1web_config.xml
file called HttpSessionTimeout. This parameter defines the session timeout (in minutes) of the HTTP
session for TM1 Web.
If the HttpSessionTimeout parameter is not specified (missing or blank), the value is less than 1 or not
a numerical value, the default session-timeout that is defined in the [Link] file is used.
Important : As of IBM Planning Analytics Local version 2.0.6, you must not change the session-
timeout value in the [Link] file.
For more information, see Setting the TM1 Web session timeout ([Link]
knowledgecenter/SSD29G_2.0.0/[Link].tm1_ug.[Link]/
t_paw_troubleshooting_web_timeout.html).
Remember : In IBM Planning Analytics Local version 2.0.6, you install a new version of the
tm1web_config.xml file that is called tm1web_config.[Link] and your existing
tm1web_config.xml file is preserved. To take advantage of fixes that are applied to this release, you
must rename the tm1web_config.[Link] file to tm1web_config.xml and you must reapply any
changes that you made to your previous configuration settings.

Chapter 1. What's new in Planning Analytics 27

TM1 REST API updates
IBM Planning Analytics Local version 2.0.6 and the cloud release of IBM Planning Analytics version 2.0.6
includes the following updates to the TM1 REST APIs for IBM TM1 Server version 11.4.0.

Metadata updates
The following functions were introduced in 11.4.0:
• [Link]
• GetOIDCKeys
The following actions were introduced in 11.4.0:
• [Link]
• RemoveOIDCKeyFromCache
To learn more, see What's new in 11.4.0 ([Link]
SSD29G_2.0.0/[Link].tm1_rest_api.[Link]/
r_restapi_v1_csdl.html#restapi_v1_csdl_whats_new_11_4_0).

Planning Analytics 2.0.5 - June 25, 2018

IBM Planning Analytics Local version 2.0.5 and the cloud release of IBM Planning Analytics version 2.0.5
includes updates and new features for IBM TM1 Server version 11.3.0.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

Local installation and configuration updates

IBM Planning Analytics Local version 2.0.5 includes the following updates to installation and
configuration.

Planning Analytics Administration agent installation

The Planning Analytics Administration agent is required for the following features in Planning Analytics
Workspace Local:
• Adding dimension members and attributes using drag and drop
• Importing data into a cube using drag and drop
For more information, see Planning Analytics Administration agent installation ([Link]
support/knowledgecenter/SSD29G_2.0.0/[Link].tm1_inst.[Link]/
c_tm1_install_paa.html).

Not supported 32-bit version of Planning Analytics no longer available

Planning Analytics Local version 2.0.5 does not include a 32-bit version of the installation program. For
more information, see [Link]

28 IBM Planning Analytics: Installation and Configuration

TM1 Server updates
IBM Planning Analytics Local version 2.0.5 and the cloud release of IBM Planning Analytics version 2.0.5
includes the following features for IBM TM1 Server version 11.3.0.

Change in the behavior of the STR function

The behavior of the STR function has been updated. This may cause a behavior change in usage
depending on which version of IBM Planning Analytics you are upgrading from.
For more information, see STR ([Link]
[Link].tm1_ref.[Link]/r_tm1_ref_str.html.

Change in the behavior of TI process rollback

A TurboIntegrator process that encounters a major error now rolls back instead of committing any
changes.
This change in behavior impacts only major errors. The entire TurboIntegrator process is a single atomic
transaction. Either the entire process succeeds and is committed, or the entire process fails and rolls
back. For example, errors such as the data source failing to open or attempting to write to a cube that
doesn't exist are major errors and now trigger a rollback.
The handling of minor errors is unchanged. For example, errors such as having a malformed input line in a
data source logs a minor error and continues running the next data source record.

Multi-threaded loading of individual cubes

You can enable multi-threaded loading of individual cubes, which delivers better speeds than the
approach that is enabled by the MaximumCubeLoadThreads setting. The following [Link] settings
are available to enable and configure this feature:
• MTCubeLoad
• [Link]
• [Link]
• [Link]
• IndexStoreDirectory
• [Link]
• [Link]
• [Link]
Using MTCubeLoad also eliminates the risk of changing feeder generation sequences. When MTCubeLoad
is enabled, the MaximumCubeLoadThreads configuration option is ignored.
TM1 Server administrators can use new [Link] settings ([Link],
[Link], and [Link]) to configure
preallocation memory and optimize scale-up and performance results.
The following loggers have been added:
[Link]=DEBUG
Allows you to capture individual timing of TM1 Server loading stages: DeSerializeDimensions,
DeSerializeAttributeCubes, DeSerializeRegularCubes, GenerateServerSecurity.
[Link]=DEBUG
Captures cube loading time, separately for .cub and .feeder files.
For more information, see MTCubeLoad ([Link]
SSD29G_2.0.0/[Link].tm1_inst.[Link]/c_tm1_inst_mtcubeload.html).

Chapter 1. What's new in Planning Analytics 29

 New operational administrator
IBM Planning Analytics has a new system's user group, OperationsAdmin, whose sole purpose is to do
maintenance and operational work. The members of this group do not see any of TM1 metadata, nor any
cube or any other data. However, members of this group can perform tasks such as unlock users,
disconnect users, and cancel threads.
For more information, see Administrative groups and authority ([Link]
knowledgecenter/SSD29G_2.0.0/[Link].tm1_op.[Link]/
c_understandingadministrativegroupsandauthority_n1701b8.html).

Reference a public subset by name in MDX

You can use the TM1SubsetToSet ([Link]
[Link].tm1_ref.[Link]/r_tm1_ref_tm1subsettoset.html) function to return the
members of a public TM1 subset. If a private and a public subset have identical names, enter the optional
scope parameter as public to return the members of the public TM1 subset. If the scope parameter is
not specified, the server searches first for a private subset.

TM1 REST API updates

IBM Planning Analytics Local version 2.0.5 and the cloud release of IBM Planning Analytics version 2.0.5
includes the following updates to the TM1 REST APIs for IBM TM1 Server version 11.3.0.

Batch request capability

To execute a set of cell updates as autonomous requests, each of which can individually succeed or fail,
you can batch multiple requests in one request.
The 11.3.0 version of the OData v4.0 based REST APIs partially implements the JSON format based
$batch implementation, as specified in Chapter 19 of the OData Committee Specification 1: Batch
Requests and Responses ([Link]
[Link]).
To learn more, see Batch options ([Link]
[Link].tm1_rest_api.[Link]/
dg_tm1_odata_additional_ops.html#dg_tm1_odata_batch_query_update_options).

Metadata updates
The following types were introduced in 11.3.0:
• ErrorLogFile
• ProcessExecuteResult
• ProcessExecuteStatusCode
The following entity types were deprecated in 11.3.0:
• ProcessErrorLog
The following functions and actions were introduced in 11.3.0:
• TailMessageLog
• TailTransactionLog
• ExecuteProcessWithReturn
• [Link]
The following actions were deprecated in 11.3.0:
• [Link]
• ExecuteProcess

30 IBM Planning Analytics: Installation and Configuration

 To learn more, see What's new in 11.3.0 ([Link]
SSD29G_2.0.0/[Link].tm1_rest_api.[Link]/
r_restapi_v1_csdl.html#restapi_v1_csdl_whats_new_11_3_0).

Documentation updates
The TM1 REST API documentation has been updated to include information about data spreading. To
learn more, see Data spreading with the TM1 REST API ([Link]
SSD29G_2.0.0/[Link].tm1_rest_api.[Link]/c_spreading_rest_api.html).

TM1 Web updates

IBM Planning Analytics Local version 2.0.5 and the cloud-only release of IBM Planning Analytics version
2.0.5 includes the following features for TM1 Web.

Changes to [Link] file

If you are upgrading IBM Planning Analytics TM1 Web with this installation of IBM Planning Analytics
Local version 2.0.5, you install a new version of the [Link] file called [Link] and your existing
[Link] file is preserved.
To take advantage of fixes applied to this release, you must use the [Link] file and you must
reapply any changes that you made to your previous configuration settings. In particular, restore your
values for session-timeout.
1. Back up the existing [Link] file in <PA_installation_location>/webapps/tm1web/WEB-
INF. For example, rename [Link] to [Link]. This step backs up your current settings.
2. Rename [Link] to [Link]. This step uses the new version of [Link] that is supplied with
IBM Planning Analytics Local version 2.0.5.
3. Replace the entry for session-timeout in [Link] with the entry from [Link]. This step
restores any changes that you made to this property previously.
For example:

<session-config>
<session-timeout>20</session-timeout>
</session-config>

Exporting to PDF
Exporting a websheet to PDF uses the print area information. If you define a print area in a worksheet,
only the data in that area is exported to PDF. This behavior is the same as printing from Excel.

Cognos Insight updates

IBM Planning Analytics Local version 2.0.5 includes updates for Cognos Insight.

Deprecated Cognos Insight - Distributed mode

IBM Planning Analytics version 2.0.5 is the last release of Cognos Insight – Distributed mode when used
with TM1 Applications. Cognos Insight in Connected mode and TM1 Application Web will continue to be
supported.
This change does not affect the functionality of the client, with the exception of work offline. If the ability
to work offline is an important capability, IBM recommends the use of IBM Planning Analytics for
Microsoft Excel.

Chapter 1. What's new in Planning Analytics 31

Planning Analytics 2.0.4 - February 16, 2018
IBM Planning Analytics Local version 2.0.4 and the cloud release of IBM Planning Analytics version 2.0.4
includes updates and new features for IBM TM1 Server version 11.2.0.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

Local installation and configuration updates

IBM Planning Analytics Local version 2.0.4 includes the following updates to installation and
configuration.

Deprecated 32-bit version of TM1 Server client installation

Planning Analytics Local version 2.0.4 is the last release of the 32-bit version of the TM1 Server client
installation program.
For more information, see [Link]

TM1 Server updates

IBM Planning Analytics Local version 2.0.4 and the cloud release of IBM Planning Analytics version 2.0.4
includes the following features for IBM TM1 Server version 11.2.0.

Encryption at rest
TM1 Server uses a two-tier key management system to encrypt and decrypt server data. TM1 APIs enable
and disable data encryption. With the TM1 Server command line utility, you can perform primary key
rotations for added security. And, if you need to, you can restore files by using the TM1Crypt utility. For
more information, see the TM1 Server data encryption in the Planning Analytics Installation and
Configuration documentation.
Note : Encryption is not supported for IBM Planning Analytics on cloud. Encryption is available for
Planning Analytics Local customers only. Encryption is not supported on a TM1 Server that is using
replication and sync. Blobs are excluded from server artifacts that are encrypted by encryption at rest.

Server stability and improved server shutdown

The TM1 Server performs the following tasks to safely shut down the server:
1. Terminates all spawned external processes.
2. Cancels all running threads (which is the same as an administrator logging in and canceling all running
threads).
3. Collects and produces information and metrics for the shutdown process.
4. Sends data to the event log and the server log.
You can use IBM Planning Analytics Administration to start and stop databases.

Change to reporting of memory consumed by feeders in TM1 Server

TM1 Server now reports the memory that is consumed by feeders only once. If there are no changes to
rules or cube data, the memory consumption represents a static value that is recorded after the server
successfully starts. If there are changes to rules, feeders, or cube data during the running of the server,
the Memory Used for Feeders value in the }StatsByCube control cube is updated the next time that the
server starts.
Note : The memory accounting is accurate at start-up time. You cannot change your feeders and see what
kind of memory profile is generated without restarting the server.

32 IBM Planning Analytics: Installation and Configuration

For more information, see Performance Monitoring Control Cubes([Link]
knowledgecenter/SSD29G_2.0.0/[Link].tm1_op.[Link]/
c_performancemonitoringcontrolcubes_n608ec.html).

Selectively enable multi-threaded query processing

The MTQQuery parameter in the [Link] file is now set to True by default. You can use a new TI function,
EnableMTQQuery(), to selectively enable or disable multi-threaded query processing when calculating
a view to be used in a TI process.

TM1 support for localizable attributes for View, Subset, and TI Processes
TM1 Server supports localizable attributes. You can provide a localized value for the attributes of
Dimension, Element, and Cube. TM1 Server automatically returns the correct value for an attribute based
on the user-supplied language locale or preferred language locale setting. You don't need to create an
alias attribute or text attribute for each language.
In this version of TM1 Server, the View, TI Process, and Subset objects can also have attributes that are
localizable. For more information, see Attributes and localization.

Sandbox comparisons
To enable sandbox comparisons, you can set EnableSandboxDimension parameter in your [Link]
file.
For more information, see EnableSandboxDimension.

REST API updates

The following changes were made to the TM1 REST APIs:
• You can use the REST API actions ExecuteCubeDrillthrough and
ExecuteRelationalDrillthrough to preview a datasource. For more information, see Preview a
datasource.
• You can rename or copy a folder in the TM1 Server by using the Copy and Move actions that are bound
to the Entry entity. Copy creates an Entry with a different name in the target destination and leaves the
source Entry the same. Move creates an Entry with a different name in the target destination and
removes the source Entry. You can specify whether the Entry that is created should be public or private.
If the target folder is unspecified, the parent folder of the source is used. If the target Name is
unspecified, the name of the source is used.
• You can retrieve elements by supplying either alias or invariant name: The OData-compliant REST API
requires an application to know the type of the key when asked for dimension element. The supplied
key can either be invariant name or alias. However, when the type is not known, that is, can be either
invariant name or alias, the application cannot determine which one to use. For more information, see
Retrieve elements by supplying either alias or invariant name.
• You can now execute a PUT on the reference of the subset element collection to update the collection.
You can execute a DELETE on the reference of the collection to empty the collection. The $filter query
option can be used to specify which element to be removed. For more information, see Update all
elements in a static set.
To learn more, see What's new in 11.2.0 ([Link]
SSD29G_2.0.0/[Link].tm1_rest_api.[Link]/
r_restapi_v1_csdl.html#restapi_v1_csdl_whats_new_11_2_0).

Chapter 1. What's new in Planning Analytics 33

TM1 Performance Modeler updates
IBM Planning Analytics Local version 2.0.4 and the cloud release of IBM Planning Analytics version 2.0.4
includes updates to IBM Cognos TM1 Performance Modeler.
In IBM Planning Analytics version 2.0.4, TM1 Performance Modeler is started as a Java application
without a console window.
If you are trying to locate the TM1 Performance Modeler process in Task Manager, you must look for
[Link]. Previously, this process appeared in Task Manager as [Link].

When TM1 Performance Modeler is starting up, the icon in the taskbar might appear as .

Cognos Insight updates

IBM Planning Analytics Local version 2.0.4 includes new features for Cognos Insight.
The following features were introduced in IBM Planning Analytics Local version 2.0.4. For more
information, see the Cognos Insight documentation in IBM Knowledge Center.

Autosum
For any widget with numeric values in the grid, you can highlight cells and display their sum and average
at the lower left side of the widget with a count of the number of cells selected.
1. To enable this feature for any widget, from the drop-down menu at the upper left of the widget, select
Show Autosum.
2. Click in the grid to close the menu.
3. Highlight any range of numeric cells. For disconnected cells, use Ctrl+click to multi-select cells.
If you select any cells that contain strings, these cells are not included in the count of selected cells.
If none of the cells you select contain numeric data, the average displays NaN (not a number).

Context-sensitive action buttons

You can add parameters that can be synchronized with your TM1 data to an action button that runs a
TurboIntegrator (TI) process. When the TI process runs, the parameter is dynamically replaced by the
name of the currently selected member of the specified dimension.
For more information, see Adding action buttons that run a script ([Link]
knowledgecenter/SSD29G_2.0.0/[Link].dsk_ug.[Link]/t_dsk_work_script.html).

Changes to startup
In IBM Planning Analytics 2.0.4, Cognos Insight is started as a Java application without a console
window.
If you are trying to locate the Cognos Insight process in Task Manager, you must look for [Link].
Previously, this process appeared in Task Manager as [Link].

When Cognos Insight is starting up, the icon in the taskbar might appear as .

Deprecation of Cognos Insight - Distributed mode

As of IBM Planning Analytics version 2.0.4, IBM announces the intent to deprecate the use of Cognos
Insight – Distributed mode when used with TM1 Applications. Cognos Insight in Connected mode and
TM1 Application Web will continue to be supported.
This change does not affect the functionality of the client, with the exception of work offline. If the ability
to work offline is an important capability, IBM recommends the use of IBM Planning Analytics for
Microsoft Excel.

34 IBM Planning Analytics: Installation and Configuration

Planning Analytics 2.0.3 - September 19, 2017
IBM Planning Analytics Local version 2.0.3 and the cloud release of IBM Planning Analytics version 2.0.3
includes updates and new features for IBM TM1 Server version 11.1.0.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

Local installation and configuration updates

IBM Planning Analytics Local version 2.0.3 includes the following updates for installation and
configuration.

Support for TM1 Server on IBM POWER8 little endian (LE)

You can now install IBM TM1 Server on Red Hat Enterprise Linux (RHEL) Server 7.1 operating system on
POWER8 LE hardware. The IBM Planning Analytics version 2.0.3 POWER8 LE install kit provides TM1
Server only. The kit contains no applications or other components.
Note :
• You cannot use the IBM Cognos Configuration tool with this version of TM1 Server. You must use
provided scripts to start and stop the TM1 Server. For more information, see Use scripts to start a TM1
Server on UNIX or Linux.
• This installation uses a subset of the TM1 Server configuration parameters in the [Link] file.
For more information, see The [Link]figuration file.
For more information, see Installing IBM TM1 Server on UNIX or Linux. For more information about
supported operating systems, create a report for IBM Planning Analytics Local by using Software Product
Compatibility Reports.

Not supported AIX for Planning Analytics Local version 2.0.3

Important :
Planning Analytics Local version 2.0.2 is the last release with AIX® support.
Planning Analytics Local version 2.0.3 is not supported on AIX.

New runtime C/C++ libraries for TM1 Server installed on UNIX or Linux
If you are running TM1 Server on Red Hat Enterprise Linux, you must install the runtime C/C++ libraries
before you install Planning Analytics Local version 2.0.3. You can create a detailed system requirements
report by using the Software Product Compatibility Reports tool ([Link]
compatibility/clarity/[Link]).

Deprecated 32-bit version of TM1 Server

There is no longer a 32-bit installation program for TM1 Server. Planning Analytics Local for Windows 32-
bit can be used only to install TM1 components.

TM1 Server updates

IBM Planning Analytics Local version 2.0.3 and the cloud release of IBM Planning Analytics version 2.0.3
includes the following features for IBM TM1 Server version [Link].

Updates to the TM1Crypt utility

The TM1Crypt utility has been updated. For more information, see Running the TM1Crypt utility.

Chapter 1. What's new in Planning Analytics 35

 Enhanced cube rule area definition support for model using multiple hierarchies
Cube rules have changed as of IBM TM1 Server version [Link]. You can use a single rule statement to
cover a set of same-named consolidated elements across hierarchies of the same dimension. This
approach gives you greater flexibility with hierarchies.
For more information, see Use the Or operator to specify cube rules across hierarchies.

Changes to default behavior for [Link] parameter

As of IBM TM1 Server version [Link], if the [Link] parameter is not specified in the [Link]
file (default), the retry logic is applied to all files in the logs directory only.
For more information, see [Link].

New [Link] parameter ODBCTimeoutInSeconds

The ODBCTimeoutInSeconds parameter specifies the timeout value that is sent to the ODBC driver using
the SQL_ATTR_QUERY_TIMEOUT and SQL_ATTR_CONNECTION_TIMEOUT connection attributes.
For more information, see ODBCTimeoutInSeconds.

New [Link] parameter SQLRowsetSize

The SQLRowsetSize parameter specifies the maximum number of rows to retrieve per ODBC request.
For more information, see SQLRowsetSize.

New logger introduced

The TM1 server uses monitoring code to generate log messages that are pushed out to the [Link].
Critical events that are pushed out to this logger include the following:
• Threads and their state
• Thread state of interest
• High contention
• Pool memory size
• Chore failure
To learn more, see Logging essential server information and Set database configuration parameters.

Updates to TM1 REST APIs

Types, actions, and functions have been added or changed in the TM1 REST API schema for IBM Planning
Analytics Local version 2.0.3. These include the following features for TM1 server version [Link]:
• Locking and unlocking cubes or dimensions.
• Rule tracing, which includes tracing the calculation of a single cell. The result contains any components
of the calculation.
• Ability to set the Context on a Session to better identify sessions and their associated threads. The
client or consumers sets a context, which in turn allows consumers of this information to know who the
client or consumer is.
• New properties in the Document, ExternalDatabaseSettings, and Session entities.
For more information, see the Release notes in TM1 REST API documentation.

36 IBM Planning Analytics: Installation and Configuration

TM1 Web updates
IBM Planning Analytics Local version 2.0.3 and the cloud-only release of IBM Planning Analytics version
2.0.3 includes the following features for TM1 Web.

Display the current TM1 database label in TM1 Web

The TM1DatabaseLabel parameter displays the TM1 database label in the banner beside the user name.
For more information, see TM1DatabaseLabel Parameter and TM1 Web Configuration Parameters.

Specify the maximum cell count of a workbook

The WorkbookMaxCellCount parameter specifies the maximum cell count of a workbook as a number with
no thousands separators. You can use WorkbookMaxCellCount to avoid issues opening workbooks with
many cells.
For more information, see TM1 Web Configuration Parameters.

Limit the number of cells that can be exported from websheets

The ExportCellsThreshold parameter specifies the maximum number of cells that an export of a websheet
or a cube view can contain. If the number of selected cells exceeds the threshold, a warning message is
displayed and the export does not start.
For more information, see TM1 Web Configuration Parameters.

Hide dimensions in the cube viewer

The CubeViewerHiddenDimensionsEnabled parameter allows you to hide dimensions in the TM1 Web
cube viewer.
For more information, see TM1 Web Configuration Parameters.

Waterfall chart support

TM1 Web supports excel-based Waterfall charts in websheets. These charts were released in Microsoft
Excel 2016.

Planning Analytics 2.0.2 - June 1, 2017

IBM Planning Analytics Local version 2.0.2 and the cloud release of IBM Planning Analytics version 2.0.2
includes updates and new features for IBM TM1 Server version 11.0.2.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

TM1 Server updates

IBM Planning Analytics Local version 2.0.2 and the cloud release of IBM Planning Analytics version 2.0.2
includes the following features for IBM TM1 Server version 11.0.2.

HTTP support enabled by default

The HTTPPortNumber [Link] parameter was optional is earlier releases. To support REST API features
and applications that use the APIs, this option must be specified. If HTTPPortNumber is not defined in
your [Link] file, then port number "5001" is assigned automatically.

Chapter 1. What's new in Planning Analytics 37

 MDXSelectCalculatedMemberInputs enabled by default
The MDXSelectCalculatedMemberInputs [Link] parameter is no longer optional. This [Link]
parameter is now enabled by default.

New configuration parameters to prevent automatic TM1 server shutdown

You can prevent automatic TM1 server shutdowns when network issues block access to transaction logs.
This feature is enabled by using three new [Link] parameters: [Link],
[Link], and [Link].

Planning Analytics 2.0.1 - February 7, 2017

IBM Planning Analytics Local version 2.0.1 and the cloud release of IBM Planning Analytics version 2.0.1
includes fixes for IBM TM1 Server version 11.0.1.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

Planning Analytics 2.0.0 - December 16, 2016

IBM Planning Analytics Local version 2.0.0 and the cloud release of IBM Planning Analytics version 2.0.0
includes updates and new features for IBM TM1 Server version 11.0.0.
Note : Updates to each version of IBM Planning Analytics are cumulative. If you are upgrading IBM
Planning Analytics, review all updates since your installed version to plan your upgrade and application
deployment.

Local installation and configuration updates

IBM Planning Analytics Local version 2.0.0 includes the following updates for installation and
configuration.

WebSphere Liberty Profile is the default application server

IBM Planning Analytics installs a WebSphere® Liberty Profile as the default application server. Apache
Tomcat is no longer installed as the default application server as it was for IBM TM1 Server.
Note : In IBM Planning Analytics Local version 2.0.0, Performance Manager Hub can deploy only to
another WebSphere Liberty Profile server; other versions of WebSphere are not supported.
WebSphere Liberty Profile uses the same default port numbers as were used for the Apache Tomcat
server. For example, the default port number 9300 is also used for the WebSphere Liberty Profile.

Changes to selectable components in the TM1 Server installation wizard

In the TM1 Server installation wizard, the tiers that contain the selectable components were renamed.
• The TM1 Application Tier was renamed the TM1 Data Tier.
• The Web Application Tier was renamed the TM1 Web Tier.
• The TM1 Client Tier and the Developer Tier were merged to form the newly named TM1 Rich Tier.
• The Samples component was moved under the TM1 Data Tier.

38 IBM Planning Analytics: Installation and Configuration

TM1 Server updates
IBM Planning Analytics version 2.0.0 includes all features that were introduced in IBM TM1 Server version
[Link].
The following features were introduced in IBM TM1 Server version [Link]. For more information about
these features, see the TM1 for Developers, TM1 Reference, and TM1 REST API documentation in IBM
Knowledge Center.

Hierarchies
You can now create multiple hierarchies inside dimensions. This capability is supported through TM1
REST APIs, TurboIntegrator processes, and Planning Analytics Workspace modeling. This enhancement
provides the following benefits:
• More efficient cube design
• Faster cube processing
• Attribute analysis
• Structured dimensions
• Dynamic analysis
• Re-org scenario planning
• Planning Analytics Workspace integration and modeling capabilities

New Control dimensions

The following control dimensions were added:
• The }Subsets_DimensionName dimension is used to track the subsets in each dimension. Each element
in this dimension represents a subset.
• The }Views_CubeName dimension is used to track the views in each cube. Each element in this
dimension represents a view.

Multi-threaded feeders
Multi-threaded feeders improve the performance of bulk feeder construction and cube feeder updates by
using the number of available CPU cores. Three [Link] settings (MTFeeders,
[Link], and [Link]) were added to enable and configure this
feature. For more information, see multi-threaded feeders in the TM1 Rules documentation.

MDX views as a TI data source

Previously, a view could be created and saved by using MDX expressions. In this release, the MDX-based
view can now be used as a TurboIntegrator data source.

Support for multiple cores on Microsoft Windows

TM1 server multi-threaded queries are no longer limited to 64 CPU cores. Microsoft Windows Platforms
with more than 64 processors can take full advantage of this feature and its performance benefits.

Deprecated IPAddress [Link] parameter deprecated

The IPAddress [Link] parameter is obsolete and has been replaced with IPAddressV4 and
IPAddressV6. You can use these parameters to specify whether TM1 client requests are routed through
the public or private adapter. The default behavior uses the public IP adapter, which requires
modifications to firewall profiles.

Chapter 1. What's new in Planning Analytics 39

 New TurboIntegrator Transactional rollback functions
Four new TurboIntegrator functions have been added to assist with managing chores: ChoreRollback,
ProcessExitByChoreRollback, ProcessRollback, and ProcessExitByProcessRollback. For
more information, see the TM1 Reference documentation.

New TM1 REST APIs

Types, actions, and functions have been added or changed in the TM1 REST API metadata for IBM TM1
Server version [Link]. These include support for TurboIntegrator debug contexts.
For more information, see the Metadata in TM1 REST API documentation.

TurboIntegrator Debugger tool

You can access a TurboIntegrator Debugger tool on IBM developerWorks. This tool provides a user
interface where you can set breakpoints and step through TurboIntegrator processes to identify possible
issues or errors in your TurboIntegrator scripts. The TurboIntegrator Debugger, which is built on the new
TurboIntegrator process debugging capabilities of the TM1 REST API, is in preview release and is not a
supported component of IBM Planning Analytics Local version 2.0.0.

TM1 Web updates

IBM Planning Analytics Local version 2.0.0 includes all features that were introduced in TM1 Web 10.3.0,
which was introduced for IBM Planning Analytics on Cloud.
The following features were introduced in IBM Planning Analytics Local version 2.0.0. For more
information about these features, see the TM1 Web documentation in IBM Knowledge Center.

Hierarchies in TM1 Web

TM1 websheets can display more than one hierarchy in a dimension.
Note : Hierarchies can be viewed in TM1 Web, however, you cannot create hierarchies in TM1 Web. You
must create hierarchies in Planning Analytics Workspace. For more information, see Planning Analytics
Workspace in IBM Knowledge Center.
You can open hierarchies by using Quick Reports in IBM Planning Analytics for Microsoft Excel.
Quick Reports (formerly Flex Views) are published as live websheets. A live websheet maintains its
connection to the TM1 server. If the data on the server changes, the live websheet reflects the change.
For more information about Quick Reports, see Planning Analytics for Microsoft Excel in IBM Knowledge
Center.
Note : Relative proportional spreading and relative percent adjustments are not supported in Quick
Reports that are opened in TM1 Web.

TM1 Web API enhancements

The TM1 Web API has the following new functionality:
• As of IBM Planning Analytics Local version 2.0.0, it is no longer mandatory to use the version of Dojo
that is provided with TM1 Web to load the TM1 Web JavaScript Library modules. TM1 Web now supports
using the AMD loader from Dojo version 1.7 and later to load the JavaScript Library modules.
• The HTML <head> and <body> tags that are required to use the JavaScript library are simpler.
• The tm1web/api/session/session module in the JavaScript library allows users to log in, retrieve
session information based on a session token, and destroy a session based on a session token.
• The tm1web/api/session/LoginDialog module in the JavaScript library allows users to display or
destroy a login dialog box.

40 IBM Planning Analytics: Installation and Configuration

• The tm1web/api/Workbook class in the JavaScript library exposes execution information after an
action button is executed. The onActionButtonExecution method API allows users to replace an
existing Workbook or create a new one when an action button is clicked.
• The tm1web/api/Workbook class and the tm1web/api/CubeViewer class include subset and
subsets set properties and methods.
For more information, see TM1 Web API in the TM1 for Developers documentation.

Relational websheets
TM1 Web now allows you to view relational data on the same websheet as TM1 data. By defining a
relational query in an Excel file and then uploading the file to TM1 Web, you can view the results on the
same websheet or tab. This allows you to report on OLAP and relational data together.
For more information, see Working with relational data in websheets ([Link]
knowledgecenter/SSD29G_2.0.0/[Link].tm1_ug.[Link]/
c_relational_data_websheets.html) in IBM Knowledge Center.

TM1 Web Accessibility

TM1 Web includes accessibility features to help you perform tasks by using only a keyboard. These
features include keyboard navigation and keyboard access to menus and dialog boxes that are related to
websheets.
• Context menus are accessed by using Shift+F10. The Up Arrow and Down Arrow keys select items from
within the context menu.
• To expand or collapse a row in a websheet, you can use the Space bar.
• To access the set selector, you can use the Space bar. The Tab key moves you between the search, the
Arrow keys, and the tree. Up Arrow and Down Arrow keys move you between items in the tree. The
Enter key selects the focused item in the tree.
Note : When you access the set selector, if you press Esc to exit after you make changes, you lose your
focus on the cell that you originally launched from. You are focused on the main page.

Support for Excel shapes in workbooks

Excel shapes, including basic shapes, arrows, banners, equation shapes, and lines, can be added to
workbooks in TM1 Web. To see the list of supported and unsupported Excel shapes, see the List of
Microsoft Excel-supported functionality by menu in IBM TM1 Web version 10.2.2 and later.

Single sign-on for TM1 Web

You can configure single sign-on for IBM TM1 Web by using Integrated Login (Kerberos) and the
application server's security layer. Single sign-on enables HTTP users to log in only once to TM1 Web.
For more information, see Configuring Integrated Login for TM1 Web using Kerberos and SPNEGO in the
Planning Analytics Installation and Configuration documentation.

TM1 worksheet functions

The following worksheet functions are now available:
TM1ELLIST
Returns a set of element values from a TM1 model by using a single formula.
TM1GLOBALSANDBOX
Returns the current global active sandbox that was selected from the toolbar.
TM1INFO
Returns information about the current TM1 version and client.

Chapter 1. What's new in Planning Analytics 41

 TM1PRIMARYDB
Returns the primary TM1 server name that the user is authenticated through, even if the user is
implicitly logged in to multiple TM1 servers.

TM1 Performance Modeler updates

IBM Planning Analytics Local version 2.0.0 also includes all features that were introduced in Cognos TM1
Performance Modeler version 10.3.0, which was introduced for IBM Planning Analytics on Cloud.
The following features were introduced in IBM Planning Analytics Local version 2.0.0. For more
information about these features, see the IBM Cognos TM1 Performance Modeler documentation.

Regenerate rules for the whole model

You can now regenerate rules for the whole model instead of having to regenerate rules one cube at a
time. In the Model Design pane, right-click the server name and select Generate Rules.

Quick access to control cubes

You can quickly create a view for a control cube by double-clicking the control cube. Previously you right-
clicked the control cube and selected New view. The view is named the same as the control cube,
without the curly bracket.

Filter and search for objects in Model Design view

You can find and filter on objects that match specific criteria in the Model Design view. For example, you
can find all objects that include sales, including rules, cubes, processes, subsets, links, views,
dimensions, and chores. You can also do a selective search where you specify which objects that you
want to search on. For example, you might want to list all rules that contain the word tent.

Search for elements in a dimension

When you edit large dimensions, navigation can be difficult. To make it easier, you can search through
existing elements of the dimension that is open in the dimension editor.

Delete and rename imported terms in a cube calculation

You can now delete and rename terms that are used in a cube calculation. The cube calculation
dynamically updates to match the term and checks to ensure that the calculation is valid.

Cognos Insight updates

IBM Cognos Insight is now installed as a component of IBM Planning Analytics Local. IBM Planning
Analytics Local version 2.0.0 includes all features that were introduced in fix packs for Cognos Insight
version 10.2.2, and also Cognos Insight version 10.3.0, which was introduced for IBM Planning Analytics
on Cloud.
Note : For more information about new features in previous versions of Cognos Insight, see New features
in the Cognos Insight documentation in IBM Knowledge Center.
The following features were introduced in IBM Planning Analytics Local version 2.0.0. For more
information, see the Cognos Insight documentation in IBM Knowledge Center.

Row and column headers are highlighted when a cell is selected

When a cell is selected in a grid, the corresponding row and column headers are highlighted as they are in
Excel. The color of the highlighting matches the color of the cell.

42 IBM Planning Analytics: Installation and Configuration

Search for objects in the content pane
You can search for objects in the content pane. You can type characters to filter on when you are unsure of
an exact object name, or if you want to find objects that match specific criteria. The search finds all
objects in the tree that match the criteria.

Search for members in the dimension editor

When you edit large dimensions, navigation can be difficult. To make it easier, you can search through
existing elements of the dimension that is open in the dimension editor.

New right-click menu options for cells

Two new options available on the right-click menu for a cell:
• Export to
• Freeze panes
Previously, these options were available only from the widget toolbar.

Chapter 1. What's new in Planning Analytics 43

44 IBM Planning Analytics: Installation and Configuration
Chapter 2. Planning your installation
You can decide how to install and configure IBM Planning Analytics Local to provide the best possible
performance. The installation and configuration choices that you make depend on your requirements,
resources, and preferences.

Software requirements
Before you install IBM Planning Analytics Local or client components, review system requirements and
set up prerequisite software in your environment.

Supported environments
For an updated list of environments that are supported by IBM Planning Analytics including information
about operating systems, servers, and databases, create a detailed system requirements report with the
Software Product Compatibility Reports tool.

Prerequisite software
Planning Analytics requires the installation of specific software components before it can be installed and
used.
Download and install the following components on the target system before you install the related
Planning Analytics components.

Prerequisite Component Description

Microsoft Excel Required for Planning Analytics for Microsoft Excel and IBM TM1
Perspectives.

Microsoft .NET Framework Required for IBM TM1 Perspectives and IBM TM1 Architect.

Available installation programs

IBM Planning Analytics Local provides installation programs for Planning Analytics components on
different operating systems and for different deployment scenarios. You can download all of the Planning
Analytics Local installation programs from IBM Passport Advantage®.
The installation programs and component options are organized by operating system and architecture tier
to support deployment in single and multiple computer environments.
Planning Analytics Local for Windows 64-bit
Includes a combined collection of 32-bit and 64-bit components for installation on a 64-bit Microsoft
Windows system.
This installation program runs only on a 64-bit Windows system.
Use this installation program to install all components on a single 64-bit Windows system or to
selectively install individual components, such as the IBM TM1 Admin Server and IBM TM1 Server, on
separate 64-bit Windows systems.
By default, this installation program automatically installs the IBM Cognos Configuration tool for
managing the TM1 Admin Server, TM1 Server, and TM1 Applications components.
Planning Analytics Local for UNIX and Linux
Includes only the UNIX and Linux versions of the following TM1 components.
• TM1 Server
• TM1 Admin Server

© Copyright IBM Corp. 2007, 2021 45

 • IBM Planning Analytics TM1 Web application servers:
– IBM Planning Analytics TM1 Web
– Cognos TM1 Applications
– Cognos TM1 Operations Console (Deprecated in v2.0.9)
Use the TM1 UNIX installation program to install these components on any of the supported UNIX or
Linux operating systems. A separate installation program is available for each of these supported
operating systems.
By default, this installation program automatically installs the IBM Cognos Configuration tool for
managing the TM1 Admin Server and TM1 Server components.
Planning Analytics Local for IBM POWER8® little endian (LE)
Includes only the following “TM1 Data Tier installation components” on page 47.
• TM1 Server
– TM1 Tools
– TM1 Samples
• TM1 Admin Server
This installation program does not install the utility for managing the TM1 Admin Server and TM1
Server components. You must use the following scripts to start and stop the TM1 Server:
• startup_tm1admsrv.sh
• startup_tm1admsrv.sh
• startup_tm1s.sh
• shutdown_tm1s.sh
Note : This installation does not provide PMPSVC scripts. If you want to edit the configuration
parameters for this installation, you must edit the [Link] file in a text editor. The
[Link] file contains a subset of the parameters in the [Link] file.
For more information about TM1 configuration parameters, see “Parameters in the [Link] file” on
page 336.
IBM Planning Analytics Workspace
Use this installation program to install Planning Analytics Workspace as part of your Planning
Analytics Local on-premises installation. Planning Analytics Workspace is the web-based interface for
IBM Planning Analytics.
Before you install Planning Analytics Workspace, you must have IBM Planning Analytics Local version
2.0.0 or greater installed.
For more information, see Chapter 10, “Installing Planning Analytics Workspace Local,” on page 155.
IBM Planning Analytics for Microsoft Excel
Use this installation program to distribute and install Planning Analytics for Microsoft Excel.
Planning Analytics Local includes samples that you can use with Planning Analytics for Microsoft
Excel.
For more information, see Chapter 12, “Installing and configuring Planning Analytics for Microsoft
Excel,” on page 199.
Planning Analytics Local Client-only
Includes only the standard IBM TM1 clients / user interfaces and related TM1 API support files. These
components are only available as 32-bit versions.
• IBM TM1 Architect
• IBM TM1 Perspectives
• IBM TM1 APIs
• IBM TM1 Performance Modeler

46 IBM Planning Analytics: Installation and Configuration

 • IBM Cognos Insight®
Use this installation program to distribute and install TM1 clients to multiple computers in your
environment.
Note : You can also use the TM1 Client installation program to enable IBM Cognos Analytics reporting
against TM1 data sources. Using the TM1 Client installation program for this purpose installs the TM1
API files on your Cognos Analytics servers that are running report services on Microsoft Windows.
TM1 Package Connector for Cognos Analytics Removed in v2.0.8
Optional installation program, which installs components that support IBM Planning Analytics
connectivity to Cognos Analytics packages with SAP Business Warehouse data sources and other
relational and ODBC data sources.
You can also set up an unattended installation and configuration.

Available components
IBM Planning Analytics Local includes a collection of server and client components for administering,
monitoring, modeling, analyzing, and interacting with TM1 data.
The installation program organizes TM1 components into groups based on architecture tier. You can
install different combinations of components onto a single computer or across multiple computers,
depending on your specific requirements, operating system and environment. Each component requires a
specific operating system and software environment.
By default, IBM Planning Analytics uses a WebSphere Application Server Liberty Profile as the application
server. You can configure Planning Analytics to run on other supported application servers that you
currently use in your environment.

TM1 Data Tier installation components

The Data Tier in the IBM Planning Analytics installation program includes the fundamental components
such as the IBM TM1 Admin and IBM TM1 Server components.
The following table includes the description and operating system for each TM1 component in the Data
Tier. For more information, see Chapter 7, “Installing the Data Tier,” on page 89.

Table 1. System requirements for TM1 Data Tier components

Component Operating System Description
TM1 Server 64-bit Windows The TM1 Server manages requests from TM1
clients. It loads the names of all available
64-bit UNIX
permanent objects, such as cubes and dimensions
64-bit Linux into memory. It responds to client requests by
completing calculations, consolidations, and
updates as required.
The TM1 Server also manages security by granting
or denying access to server objects and maintaining
a log of changes to the database.
See “TM1 Server installation” on page 89.

Chapter 2. Planning your installation 47

 Table 1. System requirements for TM1 Data Tier components (continued)
Component Operating System Description
TM Admin Server 64-bit Windows A process that tracks all TM1 servers that run on a
network. An Admin Server runs on an Admin Host
64-bit UNIX
server.
64-bit Linux
When a TM1 server starts, the server registers itself
with an Admin Server that is running on a specified
Admin Host.
TM1 clients reference the Admin Server to
determine which TM1 servers are available on the
network.
See “TM1 Server installation” on page 89.

TM1 Tools Supported operating Includes the following collection of tools and
systems vary by tool. utilities for TM1 administrators, developers, and
modelers:
TIRunTI
TM1xfer
See “Cognos TM1 tools installation” on page 103.

Samples 64-bit Windows Installs TM1 samples databases:

64-bit UNIX See “Cognos TM1 sample databases installation”
on page 104.
64-bit Linux

Planning Analytics 64-bit Windows Installs the Planning Analytics Administration

Administration agent agent, which is required in Planning Analytics
64-bit UNIX
Workspace Local.
64-bit Linux
See “Install and configure the Planning Analytics
Administration agent (local only)” on page 114.

TM1 Web Tier installation components

The TM1 Web Tier installation components require a web application server on which to run. By default,
they are configured to work with the provided Java web application server.
The following table includes the description and operating system for each TM1 component in the TM1
Web Tier. For more information, see Chapter 8, “Installing the Web Tier,” on page 119.

Table 2. TM1 Web Tier components

Component Operating System Description
TM1 Application 64-bit Windows Java web component that provides the provisioning
Gateway of the TM1 Performance Modeler and Cognos
Insight components to remote users.
This component is installed with the IBM TM1
Application Server.
See “TM1 Application Server installation” on page
119.

48 IBM Planning Analytics: Installation and Configuration

Table 2. TM1 Web Tier components (continued)
Component Operating System Description
TM1 Application Server 64-bit Windows Java web application that provides the primary
support for IBM TM1 Applications.
TM1 Applications component is used to design,
deploy, and run managed planning and
contribution-based applications on TM1 data. This
component also interacts with TM1 Performance
Modeler and Cognos Insight components.
This component requires a Java web application
server and the Java Runtime Environment (JRE).
You can use the WebSphere® Liberty application
server that is installed by default or your own
instance of an application server such as IBM
WebSphere Application Server.
An IBM JRE is installed automatically with TM1
Applications. If you are using an application server,
use the JRE that is installed with it.
See “TM1 Application Server installation” on page
119.

TM1 Web 64-bit Windows Web server and client components that run on the
provided Java web application server.
TM1 Web enables users to connect to TM1 Servers
and interact with data using one of the supported
web browsers.
See “Cognos TM1 Web installation” on page 131.

TM1 Operations Console 64-bit Windows Java web application that provides a web-based
monitoring tool for TM1 administrators to monitor
and act on TM1 server activity.
The IBM TM1 Operations Console provides a simple
and effective way to understand how TM1 servers
and user loads are working.
You can use this component with the WebSphere®
Liberty application server that is installed by default
or your own installation of a supported application
server.
An IBM JRE is installed automatically with TM1 on
Windows. If you are using an application server, use
the JRE that is installed with it.
See “Installing Cognos TM1 Operations Console
using the provided WebSphere® Liberty webserver
software” on page 135.

Chapter 2. Planning your installation 49

TM1 Rich Tier installation components
The TM1 Rich Tier contains tools for end-users and a collection of TM1 APIs.
The following table includes the description and operating system for each TM1 component in the Rich
Tier. For more information, see Chapter 9, “Installing the Rich Tier,” on page 141.

Table 3. Rich Tier components

Component Operating System Description
TM1 Architect 32-bit Windows A Windows desktop application for administering,
creating, and maintaining data and metadata on
both local and remote TM1 servers.
See “Installing Cognos TM1 Architect” on page
141.

TM1 Performance 32-bit Windows Java, Eclipse-based rich client interface that is
Modeler started from the Cognos TM1 Applications portal
page.
Enables developers to build planning and analysis
models in the TM1 environment.
Available as a selectable component in the Client-
only, and 64-bit Windows installation programs.
By default, this component is available but not
selected in the 64-bit Windows installation
programs.
See “Installing Cognos TM1 Performance Modeler”
on page 142.

TM1 Perspectives 32-bit Windows Cognos TM1 add-in client for Microsoft Excel.
Lets you use the features of Excel to perform
complex analysis on data that is stored in a TM1
server. Can also create and maintain objects and
data on both local and remote TM1 servers.
See “Installing Cognos TM1 Perspectives” on page
146.

Cognos Insight 32-bit Windows Java , Eclipse-based rich client interface that can
be started independently or from the Cognos TM1
Applications portal page.
Available as a selectable component in the Client-
only, and 64-bit Windows installation programs.
By default, this component is available but not
selected in the 64-bit Windows installation
programs.
See “Installing Cognos Insight” on page 147.

50 IBM Planning Analytics: Installation and Configuration

 Table 3. Rich Tier components (continued)
Component Operating System Description
TM1 APIs Dependent upon Installs the required files that enable developers to
specific APIs work with the following TM1 application
programming interfaces (APIs).
TM1 API - Allows developers to create custom C, C
++ and VB applications that interact with TM1.
TM1 Java API - Allows developers to create
custom Java applications that interact with TM1.
TM1 .NET API - Allows developers to create
custom Microsoft .NET applications that interact
with TM1.
See “Installing Cognos TM1 APIs” on page 153.

Additional installation components not listed

Some components are not listed or selectable in the installation program.
The following table includes the description and operating system for required components that are not
listed or selectable in the installation program but are installed by default with the installation of other
selectable components.

Table 4. Additional Planning Analytics components not listed in the installation wizard
Component Operating System Description
Planning Analytics 64-bit Windows A web-based interface for IBM Planning Analytics.
Workspace It provides an interface to TM1 data, with ways to
plan, create, and analyze your content.
See Chapter 10, “Installing Planning Analytics
Workspace Local,” on page 155.

Planning Analytics for 64-bit Windows A Microsoft Excel-based tool that professional
Microsoft Excel report authors use to build sophisticated, multiple-
sheet, multiple-query reports against multiple
databases.
See Chapter 12, “Installing and configuring
Planning Analytics for Microsoft Excel,” on page
199.

TM1 OLE DB Provider 64-bit Windows A tool that allows third-party software to retrieve
Application cube data from the IBM TM1 Server by using MDX
queries.

TM1 Client Differentiation

IBM Planning Analytics provides multiple clients for developers, administrators, and users. Understanding
these clients and their differences can help you decide which client is most appropriate for your needs.
All clients are described fully in the Planning Analytics documentation.

Chapter 2. Planning your installation 51

End-user clients
You can use several user clients to interact with TM1 data.

IBM Planning Analytics Workspace

IBM Planning Analytics Workspace is a web-based interface for IBM Planning Analytics. You can connect
to TM1 data to plan, create, and analyze your content.
For more information, see Planning Analytics Workspace installation on IBM Knowledge Center (https://
[Link]/support/knowledgecenter/SSD29G_2.0.0/[Link].tm1_inst.[Link]/
c_paw_install_overview.html).

IBM Planning Analytics for Microsoft Excel

IBM Planning Analytics for Microsoft Excel is intended for users who work in global networked
environments. It is the client of choice for users who primarily employ Microsoft Excel for analyzing TM1
information and build their own custom layouts by using Microsoft Excel functions. Planning Analytics for
Microsoft Excel is also beneficial for users who need to access both TM1 and Cognos Analyticsdata from
the same Excel client interface.
Planning Analytics for Microsoft Excel offers the following benefits:
• Optimized for wide area networks
• Provides a familiar spreadsheet environment that does not require a power-user level of knowledge in
Excel to analyze and contribute to TM1 data
• Combines the capabilities of Microsoft Excel with a drag and drop approach to analyzing TM1 cubes
• Provides a flexible range-based mode to add formats and user calculations directly within a
spreadsheet
• Provides access to TM1 data objects, such as cubes, views, dimension subsets, aliases, and sandboxes
• Combines read/write Microsoft Excel-based TM1 Planning with read-only analysis against Cognos
Analytics data sources in the same spreadsheet interface
For more information, see Planning Analytics for Microsoft Excel installation and configuration on IBM
Knowledge Center ([Link]
[Link].tm1_inst.[Link]/c_ig_cor_overview.html).

IBM Cognos TM1 Web

IBM Cognos TM1 Web is a zero-footprint web client that you can use to analyze and modify TM1 data from
any supported web browser. You cannot use TM1 Web to access the TM1 Application Web workflow page.
Therefore, you cannot participate in TM1 Applications with TM1 Web.

IBM Cognos TM1 Application Web

IBM Cognos TM1 Application Web is a zero-footprint web client that you can use to open Cognos TM1
Applications with any supported web browser. From the Cognos TM1 Application Web workflow page, you
can open a node, take ownership, enter data, and contribute to a plan. Cognos TM1 Application Web is
most useful when a corporate policy prohibits the installation of a local client, or when you use an
operating system other than Microsoft Windows.

IBM Cognos Insight

IBM Cognos Insight is a client for TM1 Application Web and a personal analysis tool that you can use to
analyze almost any set of data. In the context of Cognos TM1 Application Web, Cognos Insight is a full
client application that is provisioned locally or as a remote download. When used as a client for Cognos
TM1 Application Web, you can use the Connected Mode.

52 IBM Planning Analytics: Installation and Configuration

 Connected Mode
Connected Mode creates a live, bidirectional connection to the IBM TM1 Server. Any data that is
updated on the TM1 Server is updated in the Insight client when you perform a recalculation in
Insight. This approach ensures that the data on the Insight client is always current when you analyze
or contribute to a plan. The trade-off for the live connection to the TM1 Server is that more traffic is
generated on the LAN and a heavier load is placed on the TM1 Server.
Connected Mode should be used by users who have a fast connection to the TM1 Server and do not
suffer from any network latency.

Administration clients
You can use IBM Planning Analytics administration clients to administer your TM1 data and models.

IBM Cognos TM1 Performance Modeler

IBM Cognos TM1 Performance Modeler is a TM1 modeling tool, which you can use to create or generate
dimensions, cubes, rules, processes, and other objects. Performance Modeler simplifies the modeling
process by automatically generating the rules and feeders that are required for your applications.
Performance Modeler also introduces guided import, a simplified process for importing data and
metadata into a TM1 server. Performance Modeler should be used as the primary development and
maintenance tool for all new and existing TM1 models.

IBM Cognos TM1 Architect

IBM Cognos TM1 Architect is an older TM1 modeling tool that supports the creation and maintenance of
all TM1 objects. TM1 Architect does not support automatic feeder and rules generation, and does not
provide guided import capabilities. Architect users are encouraged use Cognos TM1 Performance Modeler
as the primary development environment for all TM1 models.

IBM Cognos TM1 Perspectives

IBM Cognos TM1 Perspectives is the TM1 Excel Add-In. Cognos TM1 Perspectives can be used for TM1
model development and for analyzing data with Microsoft Excel capabilities. Like Cognos TM1 Architect,
Perspectives support the creation and maintenance of all TM1 objects, but do not provide the advanced
capabilities of Performance Modeler. Users that require an Excel Add-In interface and the ability to use
Microsoft Excel functions, such as charting of TM1 data, can use Perspectives. Otherwise, administrators
are encouraged to use Performance Modeler as the primary development environment for all TM1
models.

IBM Cognos TM1 Operations Console (Deprecated in v2.0.9)

IBM Cognos TM1 Operations Console is a web-based operations tool that is designed to facilitate the
monitoring, support, and management of TM1 servers, providing greater insight into day-to-day server
operations. The Cognos TM1 Operations Console lets you monitor threads that run on multiple TM1
servers at the same time dynamically. You can sort and filter thread activity, and schedule the logging of
server activity. The Operations Console also provides a health check feature that determines the current
state of each TM1 server that is being monitored. The Operations Console should be the interface of
choice for TM1 administrators who are managing an enterprise-scale TM1 environment.

Configuration overview
After you install IBM Planning Analytics Local, use the Cognos Configuration tool and the TM1
configuration file parameters to configure the program for optimal performance.

Chapter 2. Planning your installation 53

Default installation values
IBM Planning Analytics Local uses the following default configuration values.

Table 5. Default configuration values for Planning Analytics installation

Item Description and Default Value

Default installation location On a 64-bit Microsoft Windows system:

C:\Program Files\IBM\cognos\tm1_64

Admin Server port number The TCP/IP port number on which the Admin
Server listens for client requests.
The default value is 5495 (unsecured).
This value is set in IBM Cognos Configuration.

Admin Server SSL port number The TCP/IP port number on which all TM1
components communicate with the Cognos TM1
Admin Server using Transport Layer Security (TLS).
The default value is 5498 (secured)
This value is set in IBM Cognos Configuration.

TM1 server port number The port on which the TM1 server runs. This
parameter is used to distinguish multiple TM1
servers running on the same computer. Valid port
values fall between 5000 and 65535.
The default value is 12345.
This value is set with the PortNumber parameter
in the [Link] server configuration file.

54 IBM Planning Analytics: Installation and Configuration

Table 5. Default configuration values for Planning Analytics installation (continued)

Item Description and Default Value

TM1 Client Message port number This port number establishes a secondary port for
client progress messages to use when a lengthy
operation is waiting to be canceled.
This value is set with the
ClientMessagePortNumber parameter in the
[Link] server configuration file.
The default value is blank.
By default, this port number is automatically and
dynamically assigned when the TM1 server starts.
You do not have to set
ClientMessagePortNumber to a specific
number unless firewalls or other network issues
require the listener port to be a well-known
number.
CAUTION : If you choose to set a specific
value for the ClientMessagePortNumber
parameter, instead of having it dynamically
assigned, be sure to assign unique port
numbers for all the TM1 server and client
message ports you are using. If you have
two servers running on the same machine
using the same port number, the message
activity may cause a system conflict or
hang.

Admin Server to REST API unsecured Specifies the HTTP port number that is used by
communication port number TM1 Admin Server to communicate with the TM1
(tm1AdminHTTPPortNumber) REST API for unsecured communication.
The default value is 5895.
This value cannot be changed using IBM Cognos
Configuration.
For more information, see Appendix 1: TM1 Admin
Host in the TM1 REST API documentation.

Admin Server to REST API secured communication Specifies the HTTPS port number that is used by
port number (tm1AdminHTTPSPortNumber) TM1 Admin Server to communicate with the TM1
REST API for secured (SSL) communication.
The default value is 5898.
This value cannot be changed using IBM Cognos
Configuration.
For more information, see Appendix 1: TM1 Admin
Host in the TM1 REST API documentation.

Chapter 2. Planning your installation 55

 Table 5. Default configuration values for Planning Analytics installation (continued)

Item Description and Default Value

Admin Server host name Specifies the computer name or IP address of the
Admin Host on which a Cognos TM1 Admin Server
is running.
The default value is blank, which uses localhost
to represent the computer on which the installation
is run.
This value is set with the AdminHost parameter in
the [Link] and [Link] configuration files.

Sample TM1 server names Planning Analytics Sample

PlanSamp
SData
GO_New_Stores
PData
Proven_Techniques
GO_scorecards
24Retail
Login credentials:
User name: admin
Password: apple

Default port numbers for sample servers PlanSamp - port 12354

SData - port 8010
GO_New_Stores - port 5010
PData - port 8011
Proven_Techniques - port 5011
GO_scorecards - port 44312
24Retail - port 8014
You can change a port number for a server by
editing the HTTPPortNumber value in the [Link]
file. For more information, see “HTTPPortNumber”
on page 351.

56 IBM Planning Analytics: Installation and Configuration

 Table 5. Default configuration values for Planning Analytics installation (continued)

Item Description and Default Value

Default data directory for sample TM1 servers C:\Program Files\IBM\cognos

\tm1_64\samples\tm1\PlanSamp
C:\Program Files\IBM\cognos
\tm1_64\samples\tm1\SData
C:\Program Files\IBM\cognos
\tm1_64\samples\tm1\GO_New_Stores
C:\Program Files\IBM\cognos
\tm1_64\samples\tm1\PData
C:\Program Files\IBM\cognos
\tm1_64\samples\tm1\Proven_Techniques
C:\Program Files\IBM\cognos
\tm1_64\samples\tm1\GO_scorecards
C:\Program Files\IBM\cognos
\tm1_64\samples\tm1\24Retail

Security mode A Standard installation uses Cognos TM1

Authentication. In this mode, the TM1 server
prompts users for a user name and password when
they log in to TM1 components.

TM1 Server and Cognos Configuration

The IBM Cognos Configuration tool is used to start, stop, configure, and save the setting for each IBM TM1
Server.
Use Cognos Configuration to manage the following components and tasks:

Table 6. Cognos Configuration tasks

Component/task Action

TM1 Admin Server Start and stop the server.

TM1 Server Start, stop, and add TM1 Servers (also known as TM1 databases).

TM1 Application Server Start and stop the provided WebSphere® Liberty web application
server that supports the following TM1 clients:
• IBM TM1 Web
• IBM TM1 Applications
• IBM TM1 Operations Console (Deprecated in v2.0.9)
In Cognos Configuration Explorer, navigate to Local Configuration >
Environment > IBM Cognos TM1 services and right-click IBM Cognos
TM1.

Chapter 2. Planning your installation 57

 Table 6. Cognos Configuration tasks (continued)
Component/task Action

Saving configuration When you save the configuration setting in Cognos Configuration, the
information tool:
• verifies the configuration
• generates cryptographic information
• checks integrity of encrypted data
• saves configuration for TM1 servers
• backs up configuration files
• saves configuration parameters

Creating war files for If you want to deploy the TM1 Applications server with your own web
deployment application server, use Cognos Configuration to create the required
web application (war) file.
In Cognos Configuration click Actions > Build Application Files.

TM1 configuration files and parameters

IBM Planning Analytics uses a collection of configuration files and parameters to control the behavior of
IBM TM1 Server and client components.

Table 7. Summary of configuration options for different TM1 components

Configuration Description

[Link] file TM1 Server configuration

See “The [Link] configuration file” on page 326.

[Link] file Client configuration for Cognos TM1 Architect and Cognos TM1
Perspectives
See “The [Link] client configuration file” on page 389.

Cognos TM1 Web Cognos TM1 Web configuration and settings

tm1web_config.xml file See “Modifying TM1 Web configuration parameters” on page 218.

Cognos TM1 Applications Cognos TM1 Applications configuration files

pmpsvc_config.xml Client settings are stored in the pmpsvc_config.xml file.
fpmsvc_config.xml Server settings are stored in the fpmsvc_config.xml file.

Cognos TM1 Operations Cognos TM1 Operations Console configuration

Console (Deprecated in
See “Installing Cognos TM1 Operations Console using the provided
v2.0.9)
WebSphere® Liberty webserver software” on page 135.

Planning Analytics Planning Analytics Administration agent configuration files

Administration agent
See “Sample [Link] file” on page 116.
[Link] file

58 IBM Planning Analytics: Installation and Configuration

User accounts for running TM1 services on Windows
When you use IBM Cognos Configuration to start the Cognos TM1 Admin Server and IBM TM1 Server, they
are registered to run as Windows services with the predefined Microsoft Windows Local System Account.
You must manually change these services to run under a specific user account.
Note : If TM1 Server requires access to external data sources with ODBC or ODBO, you must manually
change it to run under a specific user account that has access to these data sources.

Run TM1 services under a specific Windows user account

By default, Cognos Configuration registers the following TM1 services to run under the Microsoft Windows
Local System Account:
• IBM TM1 Server
• Cognos TM1 Admin Server
Important : Change these TM1 services to run under a specific user account on Microsoft Windows.
For more information, see “Changing TM1 services to run as a specific user account on Windows” on page
90.
After you make these changes, you will still be able to use Cognos Configuration to start and stop these
services.

Required privileges for a specific Windows user account

The user account for running TM1 services on Windows must be included in the database owner group to
access SQL tables and views.
The user account must have read and write privileges to the TM1 database and log directories.
The account must have the following privileges on the local computer:
• Act as part of the operating system
• Bypass traverse checking
• Increase quotas (Adjust memory quotas for a process)
• Replace a process level token
• Log on as a service
• Have read and write privileges on the Windows Registry item
Note : Not all of these properties are available in all versions of Windows, such as Windows Server 2012
and newer. Refer to Microsoft Windows documentation for the currently available properties.
You can use the Security Settings and Group Policy features in Microsoft Windows to configure these
security privileges. For example, in Microsoft Windows 7, click Administrative Tools > Local Security
Policy, and then click to expand Security Settings > Local Policies > User Rights Assignment.
To set read and write privileges for the Windows Registry, use the Windows Registry editor.

Installing IBM Planning Analytics Local on Networks without domains

If you install IBM Planning Analytics Local in a network that does not use a domain controller, you can set
your TM1 services to use local accounts.
For details on configuring TM1 services, see “Changing TM1 services to run as a specific user account on
Windows” on page 90.
If you use one or more local accounts for your TM1 services, you must be sure these accounts have the
following privileges on their local machines:
• Act as part of the operating system
• Bypass traverse checking

Chapter 2. Planning your installation 59

 • Increase quotas
• Replace a process-level token
• Log on as a service
If you set up file shares in your Windows network for use by TM1 components, be sure that each local
account that you set up to run a TM1 service has access to those shares.
Note : If you install on a machine that does not participate in a Microsoft Windows domain, you cannot
use Integrated Login.

Local machine syntax

Do not use dot (.) as an abbreviation for the local machine domain when you specify login information.
You must explicitly enter the machine name. In certain configurations, using the .\username syntax may
cause serious problems.

Accessibility
Accessibility features help users who have a physical disability, such as restricted mobility or limited
vision, to use information technology products.
For more information about the commitment that IBM has to accessibility, see the IBM Accessibility
Center at [Link]

Keyboard shortcuts for the installation wizard

Keyboard shortcuts, or shortcut keys, provide you with an easier and often faster method of navigating
and using software.
The installation wizard uses standard Microsoft Windows operating system navigation keys in addition to
application-specific keys.
Note : The following keyboard shortcuts are based on US standard keyboards.
The following table lists the keyboard shortcuts that you can use to perform some of the main tasks in the
installation wizard on the Windows operating system.

Action Shortcut key

Move to the next field on a page Tab
Return to the previous field on a page Shift+Tab
Close the installation wizard Alt+F4
Move to the next configuration step Alt+N
Return to the previous configuration step Alt+B
Move to the next selection in a list Down arrow
Move to the previous selection in a list Up arrow

The following table lists the keyboard shortcuts you can use to perform some of the main tasks in the
installation wizard on the UNIX or Linux operating system.

Action Shortcut key

Move to the next field on a page Tab
Return to the previous field on a page Shift+Tab
Close the installation wizard Alt+F4

60 IBM Planning Analytics: Installation and Configuration

 Action Shortcut key
Move to the next selection in a list Down arrow
Move to the previous selection in a list Up arrow

The following table lists the keyboard shortcuts you can use to perform some of the main tasks in the
License Agreement page of the installation wizard.

Action Shortcut key

Accept the license agreement Alt+A
Decline the license agreement Alt+D
Quit the installation wizard Alt+x

Keyboard shortcuts for Cognos Configuration

Keyboard shortcuts, or shortcut keys, provide you with an easier and often faster method of navigating
and using software.
The following keyboard shortcuts are based on US standard keyboards.
The following table lists the keyboard shortcuts that you can use to perform some of the main tasks in
IBM Cognos Configuration on the Windows operating system.

Action Shortcut key

Save the current configuration Ctrl+S
Close Cognos Configuration Alt+F4
Rename the selected item F2
Display the File menu Alt+F
Display the Edit menuAlt+H Alt+E
Display the View menu Alt+V
Display the Actions menu Alt+A
Display the Help menu Alt+H

The following table lists the keyboard shortcuts that you can use to perform some of the main tasks in
Cognos Configuration on the UNIX or Linux operating system.

Action Shortcut key

Save the current configuration Tab
Close Cognos Configuration Shift+Tab
Rename the selected item Alt+F4

Chapter 2. Planning your installation 61

62 IBM Planning Analytics: Installation and Configuration
Chapter 3. Planning Analytics Local architecture
To understand the architecture of the major IBM Planning Analytics Local components, you should be
familiar with your information technology infrastructure and with the business needs of people in your
organization who will use Planning Analytics Local.
For details about Planning Analytics Local login authentication and communication security, see
“Authentication security ” on page 246.

Planning Analytics architecture

IBM Planning Analytics employs a distributed, client-server architecture that consists of the IBM TM1
Server to which a combination of different clients can connect.

Figure 1. High-level overview of the IBM Planning Analytics client-server architecture

Planning Analytics provides the following clients and user interfaces:

• Cognos TM1 Perspectives
• Cognos TM1 Architect
• Cognos TM1 Web client
• Cognos TM1 Application portal and workflow (using the Cognos TM1 Application Server)
• Cognos TM1 Performance Modeler
• Cognos Insight
In this environment, corporate data resides on remote servers, which authorized clients can access.
Depending on how you set up the system, clients can access one or more remote TM1 Servers to obtain
different kinds of data.

Windows desktop clients

TM1 Perspectives and TM1 Architect can connect to a local TM1 Server, which acts as a repository for
private TM1 data. If you have permission, you can copy data from a remote server to your local server by
replicating that data, and then synchronize your updates back to the remote server.
TM1 Perspectives, TM1 Architect, and TM1 Client are standard TM1 clients. In a normal LAN or WAN
environment, these clients all communicate with a remote server using the TCP/IP network protocol.

© Copyright IBM Corp. 2007, 2021 63

TM1 Admin Server overview
The IBM Cognos TM1 Admin Server is a process that keeps track of all TM1 servers running on a network.
An Admin Server runs on a computer known as an Admin Host.
When the IBM TM1 Server starts, the server registers itself with an Admin Server that is running on a
specified Admin Host. TM1 clients reference the Admin Server to determine which TM1 servers are
available on the network.
The Admin Server maintains the following information for each available TM1 Server:
• Server name
• IP address
• Protocol
• Port number
All this information is supplied by the TM1 Server when the server registers itself on the Admin Server.
An Admin Server must be running before a TM1 Server can start. If you have specified an Admin Host in
the [Link] file or the server command line, the TM1 Server will attempt to connect to an Admin Server
on that host. The TM1 Server will fail to come up if it is unable to connect to the Admin Server for any
reason.
If you have not specified an Admin Host, the TM1 Server attempts to connect to an Admin Server on the
local machine. If an Admin Server is not currently running on the local machine, the TM1 Server starts a
new Admin Server and connects to it.
The Admin Server becomes aware of a TM1 Server on the network by listening for notification from the
server. Usually, the TM1 Server sends notification of its presence at a regular interval called the
"heartbeat interval," which is 60 seconds by default. When the Admin Server detects theTM1 Server, that
server becomes registered and available to clients on the network. However, if the Admin Server does not
detect the presence of a registered TM1 Server over a period equal to three times the heartbeat interval,
that TM1 Server is removed from the list of servers available on the network. Consequently, the TM1
Server will not be available to clients on the network.
By default, the Admin Server uses port 5495. If port 5495 is already in use, you can assign a new port
number by creating a new service called Tm1admsrv. All TM1 applications look for a named service called
Tm1admsrv, and if that service exists, the applications use the port number assigned to the service. If the
service does not exist, TM1 applications use port 5495.

TM1 Server overview

The IBM TM1 Server manages access to the TM1 data directory for TM1 clients.
The following figure illustrates the operations of a remote TM1 Server server. These operations are
explained in the text that follows.

64 IBM Planning Analytics: Installation and Configuration

1. When the TM1 server is started, all TM1 data is loaded from the TM1 data directory into RAM on the
server machine. At the same time, the server opens a new transactional log file called [Link] in the
data directory. After the cubes are loaded, the remote server is available.
The remote TM1 Server registers itself with one or more Admin Servers so that clients can connect to
the remote TM1 Server. Client applications contact Admin Servers to locate available TM1 Servers. The
clients log into the TM1 Servers whose data they want to access.
2. While the TM1 server is running, all cube data resides in RAM. All edits received from TM1 clients are
stored in a transaction log file named [Link].
As new values are received from clients, the TM1 Serverwrites the records to the [Link] file, keeping
track of every data change, including the date and time the edit occurred, and the ID of the client who
made the edit.
3. TM1 clients retrieve cube values from the server. Clients also send edits to cube values to the TM1
server. As the server calculates new values in response to client requests, the server stores them in
memory, increasing the amount of memory used by the server.
4. When the TM1 server is shut down, or when an explicit Save Data command is issued, any changes to
cube values are written from the transactional log file to the data directory.
All records in the [Link] file are saved to disk, and the transaction log file is renamed by appending a
date/time stamp to it. The [Link] file is saved in the server's data directory to back out data
transactions. For details, see the topic Backing out transactions using the transaction log in the TM1
Operations documentation.
If the server is intentionally shut down without saving the changes, the log file is saved with a time/
date stamp and the extension is changed to .rej. You can process the [Link] file
through TurboIntegrator to recover the transactions.
To save all changes to the data on a TM1 Server at any time without shutting down the server, right-
click a server in Server Explorer and click Save Data. All records in the [Link] file are immediately
written to disk, the transaction log file is renamed by appending a date/time stamp to it, and a new
[Link] file is created to accept any subsequent edits to cube values.
Any changes to the metadata, such as dimension definitions and cube definitions, are immediately
saved to disk. The changes to the metadata are not written to the transaction log file.

Chapter 3. Planning Analytics Local architecture 65

TM1 files overview
IBM TM1 Server requires many object and system files, most of which are stored in the TM1 Server's data
directory.
Some of these files are installed with the product, while others are generated for each dimension and
cube you create. Yet other files are generated by TM1 to store metadata, such as security information.
The following table lists the files that define cubes, dimensions, and other TM1 objects. These files are
located in the data directory, which is described later in this documentation.

Table 8. Files that define cubes, dimensions, and other objects

File Extension Description

.blb Cube formatting file

.cho Chore definition file

.cub Cube database file

.dim Compiled dimension

.dit ASCII dimension source file

.pro TurboIntegrator process definition file

.rux Compiled rule

.sub Dimension subset

.tbu ASCII source for view file

.tqu Saved query

.tru ASCII source for a rule file

.vue Saved view

Data directory overview

The data directory contains the cubes, dimensions, and system information that are loaded into memory
when an IBM TM1 Server is started. When you access a server from any TM1 client, TM1 reads data from
that server's data directory.
When you run TM1, the changes you make to cube values are immediately stored in memory and in the
transaction log ([Link]). TM1 then saves the data back to the data directory when any of the following
occur:
• TM1 Server is shut down.
• An administrator right-clicks a server icon in Server Explorer and chooses Save Data from the menu.
TM1 saves the changes to the selected server.
• An administrator chooses File > Save Data All in Server Explorer. TM1 saves the changes to all the
connected servers, if you have the proper authority.
• A user saves the batch updates.
Choose the path for your data directory when you install TM1 Server.

66 IBM Planning Analytics: Installation and Configuration

Table 9. Default Data Directory Paths

Data Directory Default Path

Local TM1 Server installation_location\custom\tm1data

\pdata

Remote Windows TM1 Server for sample data installation_location\custom\tm1data

\sdata

UNIX TM1 Server installation_location/custom/tm1data/

sdata

Required network access

A client's ability to save data is determined by the IBM TM1 security scheme.
For more information, see the TM1 Developer documentation.
Important : Make this directory visible only to administrators and to the login account that is used by the
server.

Multiple data directories

You can specify that you want IBM TM1 Server to use multiple data directories by separating the directory
names with semicolons. When you specify multiple data directories, TM1 does the following.
• Accesses cubes and dimensions from each of the specified directories. If there is a duplicate object,
TM1 accesses the object from the first directory specified.
• Writes changes to the directory where the object is located. When you create a new object, TM1 writes
to the first directory you had specified.
For example, suppose you want to store dimensions in a directory called tm1dims, and cubes in a
directory called tm1cubes. You would specify the following in the [Link] file:

DatabaseDirectory="c:\tm1dims;c:\tm1cubes"

By concatenating the two directories, you can access these objects through Server Explorer as if they
were in a single location.
Note : You cannot store cube (.cub) and rules (.rux) files in separate data directories. The .rux file must
reside in the same directory as the .cub file with which it is associated. If the .rux file is not in the same
directory as the associated .cub file, rules will not load properly.

Data directory location

You specify the location of the data directory differently for local and remote servers.
• For a local server, specify the location of the data directory by naming this directory in the
DataBaseDirectory parameter of the [Link] file.
You can change the .ini file by using the IBM Cognos TM1 Options menu in Server Explorer.
For more information, see “The [Link] client configuration file” on page 389.
• For a remote server, specify the location of the data directory by using either the DatabaseDirectory
parameter in the [Link] file or the -d command-line parameter when you bring up the server.
For information on server parameters, see “The [Link] configuration file” on page 326.
A remote server must be able to recognize the drive where the data directory resides. If the directory is on
a remote drive, you must map that drive to a local drive letter.

Chapter 3. Planning Analytics Local architecture 67

 Tip : When you access a remote server, you do not need to map to the drive where the server data
directory resides.
If you do not specify the location of the data directory, the IBM TM1 Server cannot start and the following
error message displays.

Data Directory not specified. Aborting server startup.

TM1 Web architecture

IBM Cognos TM1 Web uses a multi-tiered architecture that enables users to access and interact with TM1
data using any supported web browser.
The IBM TM1 Web multi-tiered architecture includes web client, web application server, and data
component tiers.

Figure 2. TM1 Web architecture overview diagram

Tier 1: Web clients

The web clients tier allows users to access and interact with TM1 data using any of the supported web
browsers. Users can work with TM1 cubes and TM1 Websheets.
For an updated list of environments that are supported by TM1 including information about operating
systems, TM1 servers, and databases, create a detailed system requirements report using the Software
Product Compatibility Reports tool ([Link]
[Link]).

Tier 2: Web application server

TM1 Web runs on a Java-based web application server.
This tier provides support for converting and displaying Microsoft Excel worksheets as TM1 Websheets.
This service also exports Websheets back to Microsoft Excel and PDF formats.

Tier 3: Data
This tier includes the TM1 Admin Server and at least one TM1 Server.

68 IBM Planning Analytics: Installation and Configuration

 IBM TM1 Admin server
The TM1 Admin Server can be installed on any computer on your LAN but it must reside in the same
LAN segment as your TM1 Server. Typically, the TM1 Server and the TM1 Admin Server are installed
on the same computer.
IBM TM1 server
The TM1 server can be installed on the same computer that hosts your Web server, but installing on a
separate computer is more efficient.
The version of the TM1 Server that is used in your TM1 Web environment must be equal to or more
recent than the version of TM1 Web that you are running. If the version of TM1 Web you are running is
more recent than the version of the TM1 server, users will receive an error when attempting to log in
to TM1 Web.

Accessing multiple TM1 servers from TM1 Web

IBM Cognos TM1 Web provides multi-database support, allowing users to access multiple TM1 Servers
that are registered on the same TM1 Admin Server and where users have the same user name and
password combination.
When you log in, TM1 Web displays the Navigation pane for the primary server that you selected on the
login screen. However, if your user name and password combination matches other TM1 Servers
registered under the same TM1 Admin Server, then TM1 Web will automatically log you in to these other
servers on an as-needed basis. This behavior is different from TM1 Architect and TM1 Perspectives where
you have to log into other TM1 Servers as a separate, manual step.
Multi-database support mainly applies to Websheets because they can contain TM1 formulas and
references that point to other TM1 Servers. For example, if you open a Websheet that does contain TM1
references to another server registered under the same Admin Server, TM1 Web will attempt to log you
into this other server using your current user name and password.

Limiting access to a single TM1 Server from TM1 Web

If you want to prevent TM1 Web users from using multi-database support to access other TM1 servers
under the same Admin Server, you can use a different Admin Server to register each IBM TM1 Server.
For example, with this configuration, if you log into TM1 Web and try to open a Websheet that references
another TM1 Server registered under a different Admin Server, the data will not display even if you have
the same user name and password for that server.
Tip : If you configure your TM1 servers to run under separate Admin Servers, but still want to access them
from TM1 Web, TM1 Architect, or TM1 Perspectives , you can use the AdminHost parameter. This
parameter lets you specify multiple Admin Hosts so users can access any TM1 Servers that are registered
with the Admin Servers on the specified hosts.
• For information about configuring TM1 Web to access multiple Admin Servers, see "Configuring the
Login Page using AdminHostName and TM1ServerName" in TM1 Operation.
• For information about configuring TM1 Architect and TM1 Perspectives to access multiple Admin
Servers, see “Specifying multiple Cognos TM1 Admin Hosts” on page 100.

TM1 Applications architecture

IBM TM1 Applications has a multi-tiered architecture that consists of three tiers: Web clients in the Rich
tier, Web application servers in the Web tier, and data in the Data tier.
The following diagram shows the multi-tiered architecture and basic communication paths for all the TM1
Applications components.

Chapter 3. Planning Analytics Local architecture 69

 Tier 1: Rich Tier

Cognos TM1 Applications

Data contribution clients

Cognos TM1 Cognos Insight Cognos Insight Cognos TM1 Cognos Insight
Application Web (Connected) (Distributed) Performance Modeler

Tier 2: Web Tier

Cognos TM1 Web Cognos TM1 Application Server

Cognos TM1 Application Gateway

Java-based web application server

(IBM WebSphere)

Tier 3: Data Tier

Cognos TM1 Admin Server

Cognos TM1 Server

The lines in the TM1 Applications architecture diagram show the typical communication paths required
for the tasks managed by the TM1 Application Server, such as keeping track of workflow states.
In addition to these communication lines, TM1 Performance Modeler and Cognos Insight also require a
direct connection to the underlying IBM TM1 Server at all times.

TM1 Data Tier: Data

The data tier for IBM TM1 Applications includes the IBM TM1 Admin Server and one or more IBM TM1
Servers running on either a Microsoft Windows or UNIX-based system. The TM1 Application Server and
related client interfaces communicate with the components in the data tier to access TM1 data.

IBM TM1 Server

The TM1 Server contains the data for the applications that you build and deploy with TM1 Applications.

TM1 Admin Server

The TM1 Admin Server is a process that keeps track of all TM1 Servers running on a network. The TM1
Application Server communicates with the TM1 Admin Server to determine which TM1 Servers are
available on the network.

TM1 Web Tier: Application servers

The Web Tier contains the required Java-based web application server.

Java web application server

The following components require a Java-based web application server. You can use the version of
WebSphere Liberty that is provided with the installation or your own installation of one of the supported
Java-based web application servers.
TM1 Application Server
Java-based web application that provides the primary support for IBM TM1 Applications.

70 IBM Planning Analytics: Installation and Configuration

 TM1 Application Gateway
Java-based web component that provides the provisioning of the TM1 Performance Modeler and
Cognos Insight components to remote end users.
TM1 Application Web client
An optional user interface based on TM1 Web technology for viewing and editing application data. If
you are using this option, the supporting files for it run on this same web application server.

Using security and web server provided by Cognos Analytics

If you use TM1 Applications with an IBM TM1 Server that is using IBM Cognos security, you can deploy
the TM1 Application Server with the WebSphere Liberty web server that is supplied with IBM Cognos. For
details, see “Using Cognos TM1 Applications with Cognos security” on page 269.

TM1 Rich Tier: Web clients

The Rich tier contains all the user interfaces for IBM TM1 Applications. These user interfaces are used by
end-users, administrators, and planning application developers.

TM1 Applications
The main TM1 Applications client is a web browser-based user interface supported by a Java-based web
application server, such as the provided installation of WebSphere Liberty. The user interfaces for TM1
Applications are organized into two main sub-pages and three different data contribution clients.
TM1 Applications page (portal page)
The TM1 Applications page (portal page) is the main starting point for both administrator and non-
administrator users. This page provides a list of available applications that is filtered for the current
user. Clicking on an application in this page opens the workflow page.
Administrators and application developers can also open TM1 Performance Modeler and Cognos
Insight from the TM1 Applications toolbar.
TM1 Application page (workflow page)
The TM1 Application page (workflow page) allows you to manage tasks within a single application.
This client displays each node that a user is responsible for contributing to and/or reviewing in a
specific plan. Depending on how you configure the application, the user can open the Cognos Insight
client or TM1 Application Web client for any accessible node in this client.
Data contribution clients
The following table summarizes the TM1 Applications data contribution clients that enable users to
work with data in grid and chart formats.

Table 10. TM1 Applications - data contribution clients

Client Description

IBM TM1 Application Web Default client. Processing is in real time with the server. Enables users
to view and edit application data in a grid format using TM1 cube views
or TM1 Websheets based on infrastructure from TM1 Web

IBM Cognos Insight - IBM Cognos Insight client. Processing is in real time with the server.
Connected Enables users to view and edit application data in a dashboard or
workspace format.
This client can be provisioned and installed from the TM1 Application
Gateway or installed remotely by a system administrator using a
Windows Installer command line and other software management
tools.

Chapter 3. Planning Analytics Local architecture 71

 TM1 Performance Modeler
The TM1 Performance Modeler client provides the user interface for administrators and developers to
design and deploy applications.
This user interface must be installed locally on the user's computer. Users can provision and install this
client from the TM1 Application Gateway the first time they open the client. System administrators can
also distribute and install the program remotely using Windows Installer and other software management
tools. For details, see “Installing Cognos TM1 Performance Modeler” on page 142.

Cognos Insight
Cognos Insight can run separate from TM1 Applications to enable users to create workspaces to use
within an application.
This user interface must be installed locally on the user's computer. It can be provisioned from the TM1
Application Gateway and installed by the user the first time they open the client. System administrators
can also distribute and install the program remotely using a Windows Installer command line and other
software management tools. For details, see “Installing Cognos Insight” on page 147.

72 IBM Planning Analytics: Installation and Configuration

Chapter 4. Deploying Planning Analytics Local
You can install and deploy components on a single computer or across multiple computers in a networked
environment.
For each component you want to install on a different computer, run the Cognos TM1 Installation Wizard
on that computer.

Server components
You can install the following server components on separate dedicated computers:
• Cognos TM1 Admin Server and IBM TM1 Server
• Cognos TM1 Application Server

Client components
You can install the following client components on multiple computers:
• Cognos TM1 Perspectives
• Cognos TM1 Architect
• Cognos TM1 Performance Modeler
• Cognos Insight

Deploying Planning Analytics on a single Windows computer

Installing IBM TM1 components on one computer running Microsoft Windows is a practical approach for
proof of concept, test, demonstration, development and training environments.
Installation on a single Windows computer is primarily intended for a single user on 64-bit Windows
operating systems. However these are not server class, production level operating systems and this type
of deployment should only be used for individual use and not in a production environment with multiple
users.

Typical single computer installation

A typical TM1 installation on a single Windows computer includes the following components:
TM1 Data Tier
• IBM TM1 Server
• TM1 Admin server
• TM1 Tools
• TM1 Samples
TM1 Web Tier
• TM1 Application Gateway
• TM1 Application Server
• Cognos Access Manager
TM1 Rich Tier
• TM1 Architect
• Performance Modeler
• TM1 Perspectives

© Copyright IBM Corp. 2007, 2021 73

 • Cognos Insight
• TM1 APIs
You can adjust which components you install based on your specific needs.

Deploying TM1 Admin Server and TM1 Server

You can install the IBM TM1 Server and IBM Cognos TM1 Admin Server components on a separate
Microsoft Windows and UNIX computer in your hardware environment.
For each component you want to install on a different computer, run the IBM Planning Analytics wizard on
that computer.
You can install the Cognos TM1 Admin Server on the same computer on which the IBM TM1 Server is
installed or another computer on your network.
When a TM1 Server is running, it registers itself on the specified Admin Server. TM1 clients then connect
to this Admin Server to obtain information about TM1 servers available on a network.
If you distribute the server components throughout your network, you must know certain information
about where your components will be installed, and the configuration of those components. The following
list provides information about what you need to know to install each component.

Table 11. Installing TM1 server components

Component Description

IBM TM1 Server To install and configure the TM1 Server, you must know the name of the
computer on which the TM1 Admin Server is running.

Cognos TM1 Admin This can be installed without any knowledge of your network topology.
Server

Important Notes on Distributed Installations

TM1 services must run on computers set to the same locale. You cannot, for example, install some
services on a computer running the US English locale, and other services on a computer running the
German locale. Set the locale using the Standards and Formats option in Microsoft Windows Start Menu,
Regional and Local Settings.

Deploying TM1 Applications components on a single computer

For development, testing, or demonstration purposes, you may want to install all of the required
components for IBM TM1 Applications onto a single computer running Microsoft Windows.
Deploying TM1 Applications to a single computer is the quickest way to get the program up and running.

Installation program
Use the 64-bit installation program for Windows to install TM1 Applications on a single Windows-based
computer.

Required TM1 components

The following components are required to deploy and run TM1 Applications on a single Windows-based
computer.
• IBM TM1 Server
• Cognos TM1 Admin Server
• Cognos TM1 Application Server

74 IBM Planning Analytics: Installation and Configuration

 • Cognos TM1 Application Gateway
• Cognos TM1 Web
• Cognos TM1 Sample databases (optional) - Allows you to easily run a sample TM1 Server for testing
purposes.
By default, the Cognos Configuration tool is required and automatically installed with this configuration.
After completing the installation, you use Cognos Configuration to deploy and start the TM1 Application
Server and manage your TM1 servers.
A version of WebSphere Liberty web application server is also automatically installed for use with TM1
Applications.
TM1 Web is required if you plan to use the TM1 Applications Web client.

Required web application servers

TM1 Applications requires a Java-based web application server.
You can deploy TM1 Applications to one of the following Java-based web application servers:
• Use the version of IBM WebSphere Liberty that is provided with the installation
• Use your own instance of IBM WebSphere Liberty

Deploying TM1 Applications components on separate computers

Deploying some or all of the IBM TM1 Applications components on separate, dedicated computers can
improve performance, availability, and capacity.
Depending on your network environment and business requirements, you can distribute the TM1 Web Tier
and TM1 Data Tier across multiple computers in a number of different ways.

Deploy TM1 Web Tier and TM1 Data Tier on separate computers.
This configuration combines the Java web application server for TM1 Applications and IBM TM1 Web on
the same computer but locates the TM1 Data Tier (IBM TM1 Server) on a separate computer.

Deploy web application servers on separate computers

This configuration places the Java web application server for TM1 Applications and TM1 Web on their own
computers. The TM1 Data Tier could also be installed on one of these computers or its own dedicated
computer.

Deploy all components on separate computers

This configuration places the Java web application servers for TM1 Applications and TM1 Web and the
TM1 Admin Server and the IBM TM1 Server all on separate computers.

Checklist for deploying TM1 Applications

Use the following checklist to help you install the IBM TM1 Application Server and related components on
separate computers.

Table 12. Installation scenarios for deploying IBM TM1 Applications

Installation scenario Installation steps

Running all the Java web Use the TM1 installation program to install the TM1 Application
applications together on a separate Server, TM1 Application Gateway, and TM1 Web on the computer
computer running the Java web application server.

Chapter 4. Deploying Planning Analytics Local 75

 Table 12. Installation scenarios for deploying IBM TM1 Applications (continued)
Installation scenario Installation steps

Running TM1 Web on a separate Use the TM1 installation program to install TM1 Web on a separate
computer computer.
The installation wizard installs the required files for the TM1
Application Web client - one of the client interfaces for viewing and
editing application data.

Running the TM1 Data Tier on a Use the TM1 installation program to install the TM1 Admin Server
separate computer and TM1 Server components on that computer.
For more information, see “Deploying TM1 Admin Server and TM1
Server” on page 74

Deploying TM1 client applications

This section describes how to deploy the different IBM TM1 client (user interfaces) in your network
environment.
TM1 clients include:
• Cognos TM1 Perspectives
• Cognos TM1 Architect
• Cognos TM1 Performance Modeler
• Cognos TM1 Web (using a URL or web link)
• Cognos TM1 Applications (using a URL or web link)
• Cognos Insight

76 IBM Planning Analytics: Installation and Configuration

Chapter 5. Upgrading Planning Analytics Local
You should upgrade an earlier version of IBM Cognos TM1 to the current version of IBM Planning Analytics
in stages. Follow these basic steps to upgrade.

Procedure
1. Required: Stop all related IBM Cognos TM1 and IBM Planning Analytics services.
2. Back up your existing data, configuration settings, and applications.
3. Optional: Remove the previous version of the product.
4. Install the new version of the product.
5. Restore your data, configuration settings, and applications with the new version of the product.
6. Restart all required IBM Cognos TM1 and IBM Planning Analytics services.

Prerequisites for upgrading

Before you upgrade, back up your existing data, application, and configuration files to a safe place. You
must also stop all related IBM Cognos TM1 and IBM Planning Analytics services before performing an
upgrade.

Back up your existing data

Depending on your network architecture and deployment of IBM Planning Analytics, your TM1 data might
be on more than one computer. Make a list of where this data is located and create a plan to back up the
data.
The following files must be backed up:
• IBM TM1 Server configuration and database files
• Planning Analytics Administration agent configuration files ([Link])
• Cognos TM1 Admin Server configuration files
• Cognos TM1 Web server configuration and custom files
• Cognos TM1 Architect client configuration file
• Cognos TM1 Perspectives client configuration file
• Cognos TM1 Contributor application and configuration files

Before you upgrade

Extra steps are required if you are also upgrading a previous version of Cognos TM1 to IBM Planning
Analytics. Review the following considerations before you upgrade.
IBM TM1 Server
In Planning Analytics Local version 2.0.7, the [Link] file has been updated to add the following
property to disable sending server version information in response headers.
<webContainer disableXPoweredBy="true"/>
The response header is informational and not required for operations. It is now disabled by default to
minimize thread surface.
If you are upgrading to IBM Planning Analytics Local version 2.0.7, you install a new version of the
[Link] file that is called [Link] and your existing [Link] file is preserved. To
take advantage of fixes that are applied to this release, you must rename the [Link] file to

© Copyright IBM Corp. 2007, 2021 77

 [Link] and you must reapply any changes that you made to your previous configuration
settings.
Cognos TM1 Admin Server
As of IBM Cognos TM1 version 10.1.0, the TM1 Admin Server configuration file, [Link], is
no longer used or supported by TM1. You must use Cognos Configuration to configure the Cognos TM1
Admin Server.
Cognos TM1 Applications
Attention : You will need to edit your previous applications in Cognos TM1 Performance
Modeler in the following cases:
• Dynamic Subsets cannot be used as the approval hierarchy in Cognos TM1 Applications.
• Applications cannot share the same approval cubes in Cognos TM1 Applications.
A version of WebSphere® Liberty web application server is installed with the new version of TM1. You
can use this instance of WebSphere® Liberty to run Cognos TM1 Applications and manage it using
Cognos Configuration.
If you plan to use Cognos TM1 Applications without Microsoft Excel installed on the web server where
you are running Cognos TM1 Web, you will need to explicitly set the ExcelWebPublishEnabled
parameter to True (T) in the [Link] configuration file for your TM1 servers. Earlier versions of
Cognos TM1 Contributor did not require this parameter to be set.

Upgrading from Planning Analytics version 2.0.0

When you upgrade IBM Planning Analytics Local from version 2.0.0 to version 2.0.x, you do not need to
uninstall the previous version. You can install IBM Planning Analytics Local version 2.0.x directly over
version 2.0.0.
Note : A change made in IBM Planning Analytics version 2.0.2 IF4 updates a data type field in the Cognos
TM1 database. If you upgrade to version 2.0.2 or any later version, you can't downgrade to an earlier
version. For more information, see Database structure change affects Cognos TM1 and Planning Analytics.
Planning Analytics Local supports Java 8 starting in Planning Analytics version 2.0.6. If you install
Planning Analytics version 2.0.6 over an older version of Planning Analytics, your installation removes the
existing Java 7 directories and installs the Java 8 directories.
Important : You must stop all related IBM Cognos TM1 and IBM Planning Analytics services before you
upgrade to a new version of Planning Analytics.
If you use the Cognos TM1 samples and want to keep any updates you made to them, you must back
them up before you start the upgrade. After you upgrade, you can copy or move the samples back to the
installation location. For more information, see “Upgrading the samples” on page 113.
For more information, see the following topics, depending on your computer environment and which TM1
components you want to install.
• Chapter 6, “Installing Planning Analytics Local on a single computer,” on page 81
• Chapter 7, “Installing the Data Tier,” on page 89
• Chapter 8, “Installing the Web Tier,” on page 119
• Chapter 9, “Installing the Rich Tier,” on page 141
• Chapter 10, “Installing Planning Analytics Workspace Local,” on page 155
• Chapter 12, “Installing and configuring Planning Analytics for Microsoft Excel,” on page 199
• Chapter 14, “Integrating Planning Analytics Local with IBM Cognos software,” on page 239
Note : If you are upgrading to Planning Analytics version 2.0.6 on top of version 2.0.5 plus a fix pack on a
single computer on Windows, you must uninstall and reinstall IBM TM1 Performance Modeler and IBM®
Cognos Insight to take advantage of the upgrade to Java 8:
1. Install Planning Analytics version 2.0.6.

78 IBM Planning Analytics: Installation and Configuration

 2. Uninstall IBM TM1 Performance Modeler and IBM® Cognos Insight.
3. Reinstall IBM TM1 Performance Modeler and IBM® Cognos Insight by running the
[Link] and [Link] in pa_installation_location
\webapps\pmpsvc\rcp_installs.

Upgrading Planning Analytics for Microsoft Excel

When you upgrade IBM Planning Analytics for Microsoft Excel, you need to uninstall the previous version
and then install the current version. You cannot install Planning Analytics for Microsoft Excel directly over
the previous version.

Before you begin

You must back up existing data and configuration files before you uninstall the previous version.

Procedure
1. Close all Microsoft Excel windows.
2. Back up existing data and configuration files.
3. Uninstall the previous version of Planning Analytics for Microsoft Excel. For more information,
see“Uninstall IBM Planning Analytics for Microsoft Excel” on page 205.
4. Download and extract the installation program.
5. Install the new version of Planning Analytics for Microsoft Excel. For more information, see “Installing
IBM Planning Analytics for Microsoft Excel” on page 204.
Note : If you are upgrading from Cognos Analysis for Microsoft Excel to Planning Analytics for Microsoft
Excel, you must delete the C:\Users\<user>\AppData\Local\Cognos\Office Connection
folder.

Upgrading from Cognos TM1 version 10.2.x

When you upgrade IBM Cognos TM1 version 10.2.x to IBM Planning Analytics version 2.0.0, you need to
uninstall the previous version and then install the current version. You cannot install IBM Planning
Analytics version 2.0.0 directly over version 10.2.x. You should also plan to back up existing data and
configuration files before uninstalling the previous version.

About this task

The following steps provide guidelines for upgrading Cognos TM1 version 10.2.x to the current version.

Procedure
1. Back up existing data and configuration files:
You should plan to back up existing data and configuration files to a safe location for all computers
where Cognos TM1 components were installed. For details see the following topics:
• “Backing up data and configuration files for IBM Planning Analytics Local” on page 321
2. Uninstall all Cognos TM1 components:
If you installed the previous version of Cognos TM1 in a distributed environment, you will need to
uninstall the TM1 components from each computer.
• “Uninstalling IBM Planning Analytics” on page 322
3. Install the current version of IBM Cognos TM1:
Refer to the following topics, depending on your computer environment and which Cognos TM1
components you want to install.
• Chapter 6, “Installing Planning Analytics Local on a single computer,” on page 81

Chapter 5. Upgrading Planning Analytics Local 79

 • “TM1 Server installation” on page 89
• “TM1 Application Server installation” on page 119
• Chapter 9, “Installing the Rich Tier,” on page 141
• “Installing Cognos TM1 Operations Console using the provided WebSphere® Liberty webserver
software” on page 135
4. After installing the new version of Cognos TM1 Applications, remove the cache of your web browser. If
the cache is not removed, the browser may mix old Cognos TM1 Applications and new Cognos TM1
Applications files together.
5. Restore previous Cognos TM1 data and configuration files:
Depending on which components you installed, update each computer with your previous data and
configuration files.
• “Restoring data and configuration files in IBM Planning Analytics version 2.0.0” on page 323
• “Restoring application and configuration files in Cognos TM1 Applications” on page 325

80 IBM Planning Analytics: Installation and Configuration

Chapter 6. Installing Planning Analytics Local on a
single computer
This type of installation puts Planning Analytics on a single computer running the Microsoft Windows
operating system and using default settings. Use this kind of installation to get up and running quickly
with Planning Analytics or to install a test or evaluation environment.

The single computer installation explains how to install and run:

• TM1 Admin Server
• TM1 Server
• IBM TM1 Application Server
• Cognos TM1 Application Web
• Cognos TM1 Perspectives
• Cognos TM1 Architect
• Cognos TM1 Performance Modeler
• Cognos Insight
This installation scenario assumes:
• You are on a single 64-bit computer running the Microsoft Windows operating system.
• You use the WebSphere® Liberty web server software installed by the Planning Analytics installation.
• You use the default standard TM1 authentication.
• You accept the default configurations including English as the language.
Remember : Your browser may use a slightly different interface than the browser used in the steps
described here.

Install the prerequisite software

You need the prerequisite software before you can install IBM Planning Analytics. If you do not have these
prerequisites in place, the installation wizard displays a message about them. If you are missing any of
the prerequisites, you need to install them before you can continue. You might already have this software
installed.

About this task

Review the environments that are supported by Planning Analytics including information on operating
systems, patches, web servers, and web browsers, by using the Software Product Compatibility Reports
tool.

Procedure
1. For IBM Planning Analytics for Microsoft Excel and IBM TM1 Perspectives, install or confirm that you
have
• Microsoft Excel
2. For IBM TM1 Perspectives or IBM TM1 Architect, install or confirm that you have:
• Microsoft .NET Framework

© Copyright IBM Corp. 2007, 2021 81

Install the basic Planning Analytics components
Use the installation program to select the components you want to install and the location on your
computer where you want to install them.

Before you begin

• Ensure that you have administrator privileges for the computer on which you are installing software.
• Ensure that the computer has a TEMP system variable that points to the directory where you want to
store temporary files. During installation, files are temporarily copied to this directory.
• Ensure that the directories where you install Planning Analytics components contain only ASCII
characters in the path name. Some Microsoft Windows web server software does not support non-ASCII
characters in directory names.
• Ensure that all of the prerequisite software has been installed.

Procedure
1. To start the installation:
• Go to the download location for the IBM Planning Analytics installation program that you want to
use.
• If the installation wizard does not open automatically, go to the operating system directory to locate
the [Link] command.
2. Right-click the [Link] file and click Run as Administrator.
3. Follow the directions in the installation wizard to select all of the components.
The components that you need to run the software are selected by default.
If you do not want to install Cognos Insight or Cognos TM1 Performance Modeler, skip to step “6” on
page 82.
4. To include Cognos Insight in the installation, expand the TM1 Rich Tier and then select Cognos
Insight.
5. To include Cognos TM1 Performance Modeler in the installation, expand the TM1 Rich Tier and then
select TM1 Performance Modeler.
6. Click Next until the installation begins.
The installation runs until all components have been installed. This may take a significant amount of
time.
Tip : For earlier Windows operating systems, you can check Start Cognos Configuration on the last
screen of the installation to immediately run the configuration tool. On Microsoft Windows 7 or later
and Windows Server operating system software, do not check that box and instead use the Start menu
so you can choose Run as Administrator when launching the Cognos Configuration tool.
7. Click Finish.

Use Cognos Configuration to start Planning Analytics components

Before you can use Planning Analytics, you need to start the IBM TM1 Admin Server, the IBM TM1
Application Server, and at least one IBM TM1 sample database server. This action registers the servers in
the Windows service registry. Then you need to configure the services so that they run under a specific
user. Servers that are running in a Microsoft Windows environment are referred to as services.

Procedure
1. If it is not already running, start the configuration tool by clicking Start > All Programs > IBM Cognos
TM1 > IBM Cognos Configuration.

82 IBM Planning Analytics: Installation and Configuration

 Remember : Right-click and use Run as Administrator on Windows and Windows Server operating
system software.
2. In the Cognos Configuration Explorer pane, expand Local Configuration > Environment.
3. Right-click the TM1 Admin Server component and select Start.
Start the TM1 Admin Server first since that server must be running before any sample database can
run.
The Cognos Configuration tool prompts you to save any edits made to the configuration settings. This
process will take longer the first time you save a setting as the cryptographic settings and other actions
take place for the first time. Click Yes in response to the message asking you to save the settings. You
will also see this type of message when you close Cognos Configuration.
4. Expand IBM Cognos TM1 services. Right-click IBM Cognos TM1 and select Start.
If TM1 Application Server is not installed in your environment, see “Install TM1 Application Server
with your own installation of WebSphere” on page 126.
5. Expand the Data Access > TM1 Server node and right-click each TM1 sample database server that
you want to start and select Start.
For example, start the provided sample databases:
a) SData
b) Planning Sample
c) GO_New_Stores
6. Click File > Save.
7. Now that the services are all registered in the Windows services registry, you can reconfigure them to
use a specific user account:
a) In Cognos Configuration, right-click each service you want to change and select Stop.
b) Open Windows Services.
c) Right-click on each service and select Properties.
d) Enter a user name and password valid on your system with the appropriate rights for the service.
See “ User accounts for running TM1 services on Windows” on page 59.
e) Close Windows Services.
8. In Cognos Configuration, right-click each server and select Start.
9. Close Cognos Configuration.

Run Cognos TM1 Perspectives

After installation, you can run IBM Cognos TM1 Perspectives.

Procedure
1. From the Windows Start menu, click IBM Cognos TM1 > Perspectives.
If the component does not start, ensure that the servers you started with Cognos Configuration are still
running.
2. Click Enable Macros when the security warning displays.
3. Click TM1 > Server Explorer, then expand TM1 to see the servers that are available.
4. Double-click a TM1 Server to log in.
For SData, Planning Sample, or GO_New_Stores use these login credentials:
• User name: admin
• Password: apple
Tip : To load Cognos TM1 Perspectives automatically whenever you start Microsoft Excel, add
TM1_location/[Link] to Microsoft Excel's add-in tool list, where TM1_location is the file

Chapter 6. Installing Planning Analytics Local on a single computer 83

 directory where TM1 is installed. After completing this step, "TM1" displays on the Microsoft Excel
menu bar.

Run Cognos TM1 Architect

After installation, you can run IBM Cognos TM1 Architect.

Procedure
1. From the Windows Start click All Programs > IBM Cognos TM1 > Architect. If Cognos TM1 Architect
does not start up, ensure that the servers you started with Cognos Configuration are still running.
2. Expand TM1 to see the servers that are available.
3. Double-click a TM1 Server to log in.
4. Use these credentials to log into the SData, Planning Sample, or GO_New_Stores sample databases:
• User name: admin
• Password: apple

Run Cognos TM1 Web

The IBM Planning Analytics installation configures IBM Cognos TM1 Web to run with the provided version
of the WebSphere® Liberty web application server.

Procedure
1. In a web browser, enter the following URL: [Link]
You can use the "localhost" term to make the computer location default to use your current computer.
Or you can explicitly enter the IP address or name for the computer where you installed Planning
Analytics.
2. Depending on what other components you have launched, the Log In box values will usually be
automatically entered for you. If they are not, you can enter or change those values as needed.
3. Click Log In.

Run Cognos TM1 Application Web

IBM Cognos TM1 Application Web is the web-based client and portal used to run planning applications
built using IBM TM1 data.

About this task

Cognos TM1 Application Web is also used to launch IBM Cognos TM1 Performance Modeler and can be
used to launch IBM Cognos Insight.

Procedure
1. In a web browser, enter the following URL: [Link] where 9510 is the
usual port used by Cognos TM1 Application Server. If you used a different port when you installed,
enter that other value here.
2. Specify the configuration settings the Admin Host, server, types of clients, and the URL for Cognos TM1
Application Web.
3. Click OK.
4. Enter admin and apple for the username and password for the sample TM1 servers.
5. To complete the installation, dismiss the message about editing the following parameters in the
[Link] file.

84 IBM Planning Analytics: Installation and Configuration

 • AllowSeparateNandCRules
• ForceReevaluationOfFeedersForFedCellsOnDataChange
• DistributedPlanningOutputDir
You do not need to edit these parameters until you begin working with the clients.
The portal is empty until you build an application using Cognos TM1 Performance Modeler or import an
existing application.

Run Cognos TM1 Performance Modeler

IBM Cognos TM1 Performance Modeler is available as an unselected component of the IBM Planning
Analytics installation. You launch Cognos TM1 Performance Modeler from the IBM Cognos TM1
Applications portal.

About this task

After Cognos TM1 Performance Modeler is installed, you can also start the program from the desktop icon
that gets installed or from the Microsoft Windows Start menu. Click Start > All Programs > IBM Cognos
TM1 Performance Modeler > IBM Cognos TM1 Performance Modeler.

Procedure
1. From the Cognos TM1 Applications portal, click the Open Performance Modeler icon.
Remember : Depending on your browser, you may see slightly different steps used to install
downloaded components such as Cognos TM1 Performance Modeler.
2. Click OK with the Open with IBM Cognos RCP Application Updater selected on the
provagent.cogrcp_modeler dialog box.
3. Click OK to dismiss the configuration settings message and complete the installation.
You do not need to edit those parameters until you begin working with the clients.
4. Click the Model Design tab to see the GO_New_Stores data cubes and structure.
5. Click the Application Design tab to build a new application using GO_New_Stores.
The TM1 Performance Modeler documentation provides details on building models.

Run Cognos Insight

IBM Cognos Insight is available as an unselected component of the IBM Planning Analytics installation.
Cognos Insight can be used as a client for contributing to applications and also as a dynamic workspace
builder for creating interactive contributing user experiences.

Procedure
1. To run Cognos Insight, complete one of the following actions:

• From the Cognos TM1 Applications portal, click the Cognos Insight icon .
Or you can:
• Right-click a node of an application that has been configured to use Cognos Insight.
• You can also click the Cognos Insight desktop icon that gets installed.
• Use the Microsoft Windows Start menu. Click Start > All Programs > IBM Cognos Insight > IBM
Cognos Insight.
• Cognos Insight can also be installed as a stand-alone component.
Remember : Depending on your browser, you may see slightly different steps used to install
downloaded components such as Cognos Insight.

Chapter 6. Installing Planning Analytics Local on a single computer 85

 2. Click OK with the Open With IBM Cognos RCP Application Updater selected on the
provagent.cogrcp_insight dialog box.
3. If you see an Executable file warning, click OK to proceed with the installation.

What to do next
See the Cognos Insight documentation for details about creating Cognos Insight workspaces and using
Cognos Insight as a client for contributing to applications.

Use Cognos TM1 Application Web

The IBM Cognos TM1 Application Web is a web-based client used to contribute to planning applications
and to work with IBM TM1 Websheets.

Before you begin

You need a planning application before you can use Cognos TM1 Application Web. The application
designer identifies which clients can be used with a particular application.
Tip : You can see which clients the designer made available for an application by right-clicking a node of
the application when it is displayed in the IBM Cognos TM1 Application Web.

Procedure
1. In Cognos TM1 Application Web, click a planning application.
2. Click Open Cognos TM1 Application to launch the Cognos TM1 Application Web client.
See the TM1 Web, TM1 Architect and Perspectives, and the TM1 Applications documentation for details
on how to contribute to an application using Cognos TM1 Application Web.

Other Planning Analytics components

The IBM Planning Analytics installation makes many other components available and has many other
ways to customize the installation.
See the following the documentation and components for details about other ways to install, deploy, and
configure Planning Analytics:

Other Planning Analytics components

See the related documentation for details on these additional components for Planning Analytics.
IBM Planning Analytics Workspace Local
Use IBM Planning Analytics Workspace Local with IBM TM1 data sources to plan, create, and analyze
your content.
IBM Planning Analytics Administration
Use IBM Planning Analytics Administration to monitor your IBM TM1 data sources.
IBM Planning Analytics for Microsoft Excel
Use IBM Planning Analytics for Microsoft Excel with IBM TM1 data sources to enter and write back
values to TM1 cubes.
IBM Planning Analytics TM1 Web
Use the zero-footprint IBM Planning Analytics TM1 Web client to analyze and modify TM1 data from
any supported web browser.
IBM Cognos TM1 Operations Console (Deprecated in v2.0.9)
The IBM Cognos TM1 Operations Console is a tool used by administrators to monitor the activity of
TM1 servers on the network. See TM1 Operations for more information.

86 IBM Planning Analytics: Installation and Configuration

Scorecarding with Planning Analytics
Scorecarding with Planning Analytics integrates scorecarding and strategy management capabilities
into Planning Analytics to provide better integration of performance management with planning. You
can create scorecard solutions that contain interactive impact diagrams, strategy maps, and custom
diagrams that monitor your key performance indicators (KPIs). For more information, see TM1
Performance Modeler.

Planning Analytics integration with other IBM Cognos software

IBM Cognos Analytics security
You can configure the IBM TM1 Server to authenticate users using IBM Cognos Analytics security.
IBM Cognos TM1 Package Connector Removed in v2.0.8
The IBM Cognos TM1 Package Connector is used to import IBM Cognos Framework Manager
packages. See TM1 TurboIntegrator for more information.
IBM Cognos Analytics reporting
You can configure IBM Cognos Analytics to access TM1 servers and cubes from Cognos Analytics
applications such as Cognos Report Studio and Cognos Query Studio.
iWidgets in IBM Cognos Workspace
You can display IBM Cognos TM1 Web data objects, such as cube views, charts, and Websheets as
iWidgets in IBM Cognos Workspace.
For more information, see Chapter 14, “Integrating Planning Analytics Local with IBM Cognos software,”
on page 239.

Chapter 6. Installing Planning Analytics Local on a single computer 87

88 IBM Planning Analytics: Installation and Configuration
Chapter 7. Installing the Data Tier
You can install Data Tier components using the IBM Planning Analytics Local installation program.
You can install the following Data Tier components:
• TM1 Server
• TM1 Tools
• TM1 Samples
• Planning Analytics Administration agent

TM1 Server installation

You can install and configure the IBM TM1 Admin Server and IBM TM1 Server on a dedicated computer
running either the Microsoft Windows, UNIX, or Linux operating system.
The TM1 Admin Server can reside on the same computer as the TM1 Server or another computer on your
network.
The server components can be installed on a 64-bit computer running Microsoft Windows, UNIX, or Linux
operating systems.

Server components
The TM1 Server components include the following:
• TM1 Admin Server (required)
• TM1 Server (required)
• TM1 Tools (optional)
These components are grouped together under the TM1 Data Tier in the installation program.

IBM Cognos Configuration

By default, IBM Cognos Configuration is also installed with the required components on Windows, UNIX,
and Linux as the primary tool for managing the TM1 Admin Server and TM1 Server. This tool provides a
user interface for stopping and starting the server components.

Installing IBM TM1 Server on Windows

You can install the TM1 Server server components on 64-bit computers running the Microsoft Windows
operating system. Use this type of installation to install and run the TM1 Server on a dedicated computer
that remote users can access.

Install IBM TM1 Server components on Windows

Install the IBM TM1 Server components on a computer that uses Microsoft Windows.

Procedure
1. Choose the installation program that matches the type of computer being used for the TM1 Server:
2. Right-click the [Link] file and click Run as Administrator.
3. Follow the directions in the installation wizard and advance to the Component Selection page.
4. Clear all the components. By default, all components are initially selected.
5. Expand the TM1 Data Tier and select the following components:
• TM1 Server

© Copyright IBM Corp. 2007, 2021 89

 • TM1 Admin Server
• TM1 Tools (optional)
• TM1 Samples (optional)
6. Follow the directions in the installation wizard to complete the installation.
7. In the Finish page of the installation wizard, click Finish.

Use Cognos Configuration to start TM1 servers on Windows

Before you can use the IBM TM1 Server, you need to start the IBM TM1 Admin Server in IBM Cognos
Configuration. Servers that are running in a Microsoft Windows environment are referred to as services.

About this task

By default, Cognos Configuration registers TM1 Server components to run as Windows services using the
predefined Local System account. However, the TM1 components should be run as a specific user.
Important : Change the following TM1 services that are created by Cognos Configuration so that the
services run under a specific user account on Microsoft Windows:
• TM1 Admin Server
• TM1 Server
For details, see, “ User accounts for running TM1 services on Windows” on page 59.

Procedure
1. If it is not already running, start the configuration tool by clicking Start > All Programs > IBM Cognos
TM1 > IBM Cognos Configuration.
Remember : Right-click and use Run as Administrator on Windows and Windows Server operating
system software.
2. In the Cognos Configuration Explorer pane, expand Local Configuration > Environment.
3. Right-click each server that you want to start and select Start:
a) TM1 Admin Server
Tip : The Cognos Configuration tool prompts you to save any edits made to the configuration
settings. This process will take longer the first time you save a setting as the cryptographic settings
and other actions take place for the first time. Click Yes in response to the message asking you to
save the settings. You will also see this type of message when you close Cognos Configuration.
4. Expand the Data Access > TM1 Server node and right-click each TM1 sample database server that
you want to start and select Start.
For example, start the provided sample databases:
a) SData
b) Planning Sample
c) GO_New_Stores
5. Click File > Save.
6. Edit the entries for the TM1 components in Windows Services so that they run under a specific user
account.
For details, see, “Changing TM1 services to run as a specific user account on Windows” on page 90.

Changing TM1 services to run as a specific user account on Windows

When you use IBM Cognos Configuration to manage TM1 services, you need to change the default user
account that runs the Microsoft Windows services for the TM1 Admin Server and any TM1 servers that you
start with Cognos Configuration. By default, Cognos Configuration registers these services under the

90 IBM Planning Analytics: Installation and Configuration

 predefined Microsoft Windows Local System account. However, these services should be changed to run
as a specific user account.

Before you begin

Review the required account privileges for using a user account other than Local System account. For
details, see “ User accounts for running TM1 services on Windows” on page 59.

About this task

Use Windows Services to change the user account for a TM1 component that is configured to run as a
service.

Procedure
1. Open IBM Cognos Configuration.
2. Expand the Explorer > Local Configuration tree:
a) Expand the Local Configuration > Environment node.
b) Expand the Data Access > TM1 Server node.
3. Right-click on each TM1 component you want to change and select Stop.
• TM1 Admin Server
• TM1 Server name - the name for each server you have in Cognos Configuration.
Tip : You don't need to stop the IBM Cognos TM1 component in IBM Cognos TM1 services.
4. Open Windows Services.
5. Locate the TM1 component that you want to update and change the user account for the Windows
service that runs it:
a) Right-click on the service, select Properties and then click the Log On tab.
b) Enter a new user name and password for the service.
c) Repeat these steps for any other TM1 component running as a Windows service that you want to
change.
6. Close Windows Services.
7. In Cognos Configuration, right-click on the item and select Start to restart each service that you
changed.
8. Close Cognos Configuration.

Installing IBM TM1 Server on UNIX or Linux

You can install the TM1 Server components on a 64-bit computer that is running either a UNIX or Linux
operating system. Use this type of installation to install and run the TM1 Server on a dedicated computer
that remote users can access.

Prerequisites
As of IBM Planning Analytics version 2.0.2, IBM TM1 Server uses nmap() or nunmap() for large block
allocation on Linux. Therefore, you must be aware of the vm.max_map_count limit. By default on Linux,
the vm.max_map_count is 65530 and this count is insufficient when large data models are used.
When the limit of 65530 is reached, you might receive an error message that TM1 Server is unable to
allocate memory for a large block or a memory leak might occur.
To update the vm.max_map_count, run the following command as root:

sysctl -w vm.max_map_count=655300

Chapter 7. Installing the Data Tier 91

 To set this value permanently, update the vm.max_map_count setting in your /etc/[Link] file.
To verify the setting, after you restart your TM1 Server, run the following command:

sysctl vm.max_map_count

Managing components after installation

After you install, you can use the start and stop scripts that are provided with the installation to manage
your TM1 Server. You can also use IBM Cognos Configuration to manage the servers you want to run in
some cases.
Note : You cannot use IBM Cognos Configuration to start and stop your IBM TM1 Server on IBM POWER8
LE. You must use the start and stop scripts that are provided.

Accessing and viewing data

To view and interact with the data that is stored in a TM1 Server on UNIX or Linux, use one of the TM1
clients on a computer that is running Microsoft Windows.
Tip : You can use Cognos TM1 Architect on a computer that is running Microsoft Windows to remotely log
in to a server that is running on a UNIX or Linux system.

Install IBM TM1 Server components on UNIX or Linux

You can use the installation wizard to select the server components for installation and the installation
location on your computer.
For a complete list of supported UNIX and Linux operating systems, create a detailed system
requirements report for IBM Planning Analytics Local software by using the Software Product
Compatibility Reports tool ([Link]

Before you begin

When you install TM1 Server on UNIX or Linux operating systems, configure the components to run as a
user with appropriate permissions for TM1 binary files and TM1 databases.
Note : Only the TM1 Server components can run on UNIX or Linux. You cannot run TM1 clients on UNIX or
Linux.
Complete the following prerequisites:
• Familiarize yourself with TM1 terms and concepts.
For more information, see the TM1 for Developers documentation.
• Determine which components you want to install and how they must be distributed across your
hardware environment.
For more information on how to design the optimal TM1 environment, see Chapter 3, “Planning
Analytics Local architecture,” on page 63 and Chapter 4, “Deploying Planning Analytics Local,” on page
73.
• Determine your hardware and software requirements.
Review a list of supported environments, including operating systems, patches, web servers, and web
browsers, by creating a detailed system requirements report for IBM Planning Analytics Local software
with the Software Product Compatibility Reports tool ([Link]
compatibility/clarity/[Link]).
– If you plan to import data from another relational database, install your database software first.
– If you are running Oracle on UNIX, install the appropriate UNIX client software for your Oracle
database on the UNIX machine. Use the Oracle Network Configuration Assistant to specify a local net
service name.

92 IBM Planning Analytics: Installation and Configuration

 – If you are running on Red Hat Enterprise Linux, install the required runtime C/C++ libraries that are
listed in the Prerequisites tab of the Detailed Systems Requirements Report or verify that they are
already available. Additional libraries might need to be installed, depending on your version of Red
Hat Enterprise Linux. For example, on Red Hat Enterprise Linux (RHEL) Server 7, run the following
command to install additional libraries:

yum -y install libstdc++ libstdc++.i686 motif [Link].4 libXtst

• Optional: Install your own copy of the Java Runtime Environment (JRE) if necessary. The TM1
installation does not provide a JRE for UNIX installations.
Note : If you are installing on IBM POWER8 LE, you do not need to install a JRE.
• Optional: Check the X-server software on your UNIX machine.
To run the Graphical User Interface UNIX Installation Wizard, X-server software must be installed on the
machine that hosts your TM1 components. You must install X-server client software on the machine
from which you run the TM1 Installation Wizard. If X-server software is not installed on the UNIX
machine, run the console installation.
Note : If you do not use X-server software, you must use an unattended installation. For more
information, see “Setting up unattended installations and configurations” on page 315.
• Optional: Install and configure the TM1 components to run as a user with appropriate permissions for
TM1 binary files and TM1 databases.

Procedure
1. Go to the location where the installation files were downloaded and extracted, or insert the product
disk.
2. Go to the operating system directory and then type the following command:
./issetup
3. Follow the directions in the installation wizard and copy the required files to your computer.
4. Select the components that you want to install. By default, all components are installed.
5. In the Finish page of the installation wizard, click Finish.

Use Cognos Configuration on UNIX or Linux

You can IBM Cognos Configuration to configure your TM1 components and to start and stop services.

Before you begin

You must have set the JAVA_HOME environment variable before you can start IBM Cognos Configuration.
Ensure that the JAVA_HOME environment variable is set to a valid JRE location.
Note : You cannot use the IBM Cognos Configuration tool with IBM TM1 Server on POWER8 LE. You must
use provided scripts to start and stop the TM1 Server.
To use IBM Cognos Configuration to start and stop your IBM TM1 Server on UNIX, follow these steps.

Procedure
1. Go to the install_location/bin64 directory and then type
./[Link]
2. In the Explorer window, click Local Configuration > Environment.
3. Right-click Cognos TM1 Admin Server, and click Start.
4. Under Data Access > Cognos TM1 Server, right-click a server, and click Start.

Chapter 7. Installing the Data Tier 93

 Use scripts to start a TM1 Server on UNIX or Linux
You can use the start and stop scripts that are provided with the installation to start and stop your IBM
TM1 Server on UNIX or Linux.

About this task

On UNIX or Linux, you can use the following commands and scripts to start and stop TM1 Server. See
"Starting a UNIX TM1 Server" and "Stopping a UNIX TM1 Server" in the TM1 Operations documentation
for more details.
• startup_tm1admsrv.sh - start TM1 Admin Server
• shutdown_tm1admsrv.sh - shut down TM1 Admin Server
• startup_tm1s.sh - start TM1 Server
• [Link] - utility for stopping a TM1 Server
• shutdown_tm1s.sh - alternate method to shut down a TM1 Server
• startup_pmpsvc.sh - start TM1 Application Server
• shutdown_pmpsvc.sh - shut down TM1 Application Server
On POWER8 LE, the following commands are not available.
• [Link] - utility for stopping a TM1 Server
• startup_pmpsvc.sh - start TM1 Application Server
• shutdown_pmpsvc.sh - shut down TM1 Application Server

Character Encoding for TM1 Object Names on UNIX and Windows Systems
The following guidelines are related to ensuring correct and consistent character encoding in your TM1
object names for objects such as cubes, views, dimensions, and subsets.

Moving TM1 Databases Between Windows and UNIX Systems

Do not manually move and use TM1 database files from a Microsoft Windows system to a UNIX system (or
from UNIX to Windows) when your TM1 object names contain non-ASCII characters (characters beyond
the original 128 ASCII character set).
Manually moving files is an issue because of the possible incompatible character encoding or mapping
between these two platforms. The Windows operating system stores directory and file names in UTF-16
character encoding, while the UNIX operating system can store names using different character
encodings, depending on which locale is currently being used.
For example, TM1 object names for cubes and dimensions that include non-ASCII characters would not
display correctly in TM1 client applications if the TM1 database files were copied from one platform and
run on another where different character encoding is used.
Instead of manually moving files, use the tm1xfer utility to move TM1 data between different platforms.

Use the tm1xfer utility

The tm1xfer utility compresses and moves TM1 server objects from one platform to another platform
while preserving mixed case names for objects on both Microsoft Windows and UNIX platforms. For more
information, see the "tm1xfer" topic in TM1 Operations.

Use the same locale as the UNIX system when starting a TM1 Server with non-ASCII
characters in the name
If your TM1 object names (for cubes, views, dimensions, subsets, etc.) include non-ASCII characters, use
the same locale when starting up a TM1 Server on a UNIX system.

94 IBM Planning Analytics: Installation and Configuration

 This ensures that TM1 object names and the related TM1 directory and file names on the UNIX system
always use the same character encoding. Starting the TM1 Server under a different locale than previously
used could cause TM1 object names to display incorrectly if the names were originally created and stored
in a different locale.
For example, TM1 object names for cubes and dimensions that are saved when the server is running
under the en_US locale might not display correctly if the server is re-started using the ja_JP locale.

TM1 language configuration

IBM Planning Analytics automatically configures language for the IBM TM1 Server, client user interfaces,
and messages by detecting the current language of the operating system user account or web browser
where they are running. You can override this automatic configuration and configure TM1 Server to use a
specific language from any of the supported languages.
For details about supported languages, see “TM1 language codes” on page 96.

Automatic detection of language

TM1 uses the following process to automatically detect and configure language at runtime:
1. The TM1 Server and clients that run in Microsoft Windows try to detect and use the language that is
configured in the locale of the operating system for the current user. On Windows, this is configured
with Regional and Language Options. The detected language will be used if it matches one of the
supported languages.
Important : By default, any TM1 Server that you start with IBM Cognos Configuration is initially
configured to run as a Windows service using the Windows Local System reserved user account. If you
want the TM1 Server to use the language based on a specific user account, change the service to run
as that user and configure the language for the user with the Windows Regional and Language
Options. For details, see “Changing TM1 services to run as a specific user account on Windows” on
page 90.
2. The server and client components also check for an override based on the TM1 Language
configuration parameter:
• The server checks the Language parameter in the [Link] configuration file. If a valid language
code is configured, that language is used for the server messages.
• The client components check the Language parameter in the [Link] configuration file. If a valid
language code is configured, that language is used in the user interface.
3. If the language configured in any of the above does not match a valid supported language, English is
used.

Language configuration for TM1 components

Languages are set separately for the following TM1 components.

Table 13. Summary of language configuration for TM1 components

Component Language Configuration
TM1 Server Use the Language parameter in the [Link] file to configure a
specific language for a TM1 Server.
For details, see “Configuring language for the IBM TM1 Server” on
page 97

Chapter 7. Installing the Data Tier 95

 Table 13. Summary of language configuration for TM1 components (continued)
Component Language Configuration

TM1 Architect, Use the Language parameter in the [Link] file to configure a
specific language for TM1 clients that run on Microsoft Windows.
TM1 Perspectives
For details, see “Configuring language for TM1 clients on Windows”
on page 97

TM1 Web Use the language settings in your web browser to select a specific
language for TM1 Web.
For details, see “Configuring web browser language for TM1 Web” on
page 235

TM1 language codes

The following table summarizes the language codes for the supported languages in IBM TM1.

Language Code
Brazilian Portuguese bra
Croatian hrv
Czech csy
Chinese (Simplified) sch
Chinese (Traditional) tch
Danish dan
Dutch nld
German deu
Finnish fin
French fra
Hungarian hun
Italian ita
Japanese jpn
Kazakh kaz
Korean kor
Norwegian nor
Polish pol
Romanian rom
Russian rus
Spanish esp
Slovenian slv
Swedish sve
Thai tha

96 IBM Planning Analytics: Installation and Configuration

Language Code
Turkish trk

Configuring language for the IBM TM1 Server

Use the Language parameter in the [Link] file to configure a specific language for the IBM TM1
Server.

About this task

The Language configuration parameter for the TM1 Server controls the language for messages generated
by the server. The parameter also applies to the user interface of the dialog box when you run the server
as an application instead of a Windows service.
For more details about the TM1 Server Language parameter, see Language parameter in the [Link]
file.
Note : If you want the TM1 Server to use a language based on a user account instead of the Language
parameter, change the Microsoft Windows service that runs the TM1 Server to run as a specific user. For
details, see “Changing TM1 services to run as a specific user account on Windows” on page 90.

Procedure
1. Use a text editor to open the TM1 Server configuration file, [Link].
For location details, see “Location of the [Link] file” on page 326.
2. Edit or add the Language parameter with the language code you want to use.
For example:

Language=deu

For a list of supported language codes, see “TM1 language codes” on page 96.
3. Save and close the [Link] file.
4. Restart the TM1 Server.

Configuring language for TM1 clients on Windows

Use the Language parameter in the [Link] file to configure a specific language for IBM TM1 clients
that run on Microsoft Windows such as Cognos TM1 Architect and Cognos TM1 Perspectives.

About this task

For details about this parameter, see Language parameter in the [Link] file.
Note : The Language parameter for TM1 clients is separate from the parameter of the same name for the
TM1 Server.

Procedure
1. Use a text editor to open the TM1 client configuration file, [Link].
For location details, see “Location of the [Link] File” on page 389.
2. Edit or add the Language parameter with the language code you want to use.
For example:
Language=sch
For a list of supported language codes, see “TM1 language codes” on page 96.
3. Save and close the [Link] file.

Chapter 7. Installing the Data Tier 97

 4. Restart the TM1 client.

Advanced TM1 Admin Server and TM1 Server configuration

You can use advanced configuration to customize IBM TM1 Server for your specific business requirements
and environment after you have completed the initial installation steps.

Creating a new empty TM1 Server in Cognos Configuration

You can use IBM Cognos Configuration to create a new empty IBM TM1 Server.

About this task

These steps create the [Link] configuration file and other required files for a new empty TM1 Server.
Perform these steps only on an empty directory that does not contain any other files.
Tip : If you want to add an existing TM1 Server to Cognos Configuration, see “Adding an existing TM1
Server in Cognos Configuration” on page 99.

Procedure
1. Use your operating system to create an empty folder for the new TM1 Server files.
2. Open IBM Cognos Configuration.
3. In the Explorer panel, under Data Access, right click TM1 Server, and click New Resource > TM1
Server Instances.
4. In the Name box, enter a name for your server.
5. In the Type box, select TM1 Server instance and click OK.
The new server is added under the TM1 Server node and the properties for it are displayed in the
TM1 Server instances - Resource Properties list.
6. In the Resource Properties list, click the entry box and click the edit icon.
7. Enter or browse to the path for the empty folder where you want to create the new TM1 Server.
Tip : Do not include the file name in this path. You only need to select the folder.
8. Click Select.
9. Click File > Save.
A new [Link] file is automatically created in the folder. Values for the following configuration
parameters are automatically added to the file.
• The ServerName parameter is set to the server name that you specified.
• The DataBaseDirectory parameter is set to the data directory that you specified.
• The PortNumber parameter is set to a random auto-generated port number.
10. If you are using this database with TM1 Applications, edit the [Link] file with the required
parameter values.
For details, see “Configuring a TM1 Server to work with TM1 Application Web” on page 124.
11. In the Cognos Configuration Explorer panel, right-click the new server and click Start.
The basic files for the new TM1 Server are created in the folder.
12. To test the new TM1 Server, start TM1 Architect and log in to the database with user name admin
and no password.

98 IBM Planning Analytics: Installation and Configuration

Adding an existing TM1 Server in Cognos Configuration
You can manage an existing IBM TM1 Server by adding it to IBM Cognos Configuration.

Before you begin

This procedure requires that you have an existing TM1 data directory with a valid [Link] file.

Procedure
1. Open IBM Cognos Configuration.
2. In the Explorer panel, under Data Access, right click TM1 Server, and click New Resource > TM1
Server Instances.
3. In the Name box, enter the same name that is set for the ServerName parameter in the [Link]
file.
4. In the Type box, select TM1 Server instance and click OK.
The new server is added under the TM1 Server node and the properties for it are displayed in the
TM1 Server instances - Resource Properties list.
5. In the Resource Properties list, click the box to the right of the TM1 Server configuration path and
click the edit icon.
6. Enter or browse to the path for the existing TM1 data directory.
Tip : Do not include the file name in this path. You only need to select the folder.
7. Click Select.
8. Click File > Save.
9. In the Cognos Configuration Explorer panel, right-click the new server and click Start.
10. To test this TM1 Server, start TM1 Architect and log in to the database.

Specifying the location of the Cognos TM1 Admin Host

You specify the location of the IBM Cognos TM1 Admin Host differently for clients (user interfaces) and
remote servers.

About this task

The Admin Host is the computer where the Cognos TM1 Admin Server is running.

Procedure
1. To specify the Admin Host referenced by clients such as Cognos TM1 Architect or Cognos TM1
Perspectives:
• Change the [Link] file by using the Cognos TM1 Options menu in Server Explorer.
• You can also manually edit the AdminHost parameter in the [Link] client configuration file.
For more information, see “The [Link] client configuration file” on page 389.
2. To specify the Admin Host with which remote servers register, use one of the following methods:
• Edit the AdminHost parameter in the [Link] file.
• Use the -v command-line parameter when you bring up the Windows version of the IBM TM1
Server.
For information, see “The [Link] configuration file” on page 326.

Chapter 7. Installing the Data Tier 99

 Specifying multiple Cognos TM1 Admin Hosts
You can configure an IBM Cognos TM1 client to reference multiple Admin Hosts by separating host names
with semicolons.

About this task

A client that specifies multiple Admin Hosts can access any TM1 servers that are registered with the
Cognos TM1 Admin Servers on the specified hosts.

Procedure
To specify multiple Admin Hosts referenced by clients such as Cognos TM1 Architect or Cognos TM1
Perspectives, separate the host names with semicolons:
• Change the [Link] file by using the Cognos TM1 Options menu in Server Explorer.
• You can also manually edit the AdminHost parameter in the [Link] client configuration file.
For more information, see “The [Link] client configuration file” on page 389.

Changing default port numbers for TM1 Admin Server

If you change the default values for the TM1 Admin Server host port number or the TM1 Admin Server
SSL port number in IBM Cognos Configuration, you need to manually update the new values in the UNIX
and Microsoft Windows services file across all the affected computers in your environment. This operating
system file is not updated by TM1.

About this task

Update the operating system services file on any computer running TM1 components that need to
communicate with the TM1 Admin Server. For example:
• IBM TM1 Server
• TM1 desktop clients such as Cognos TM1 Architect or Cognos TM1 Perspectives
• TM1 Web (web server only)
• Custom TM1 applications created with the TM1 API

Procedure
1. Locate and open the services file for the specific operating system.
• For UNIX, the typical location of the services file is:
/etc/services
• For Windows, the typical location of the services file is:
C:\WINDOWS\system32\drivers\etc\services
2. Add or edit the following entries in the services file with the new port numbers. For example:
tm1adminsvr 5400/tcp # Added by IBM Cognos TM1
tm1admsrv_ssl 5403/tcp # Added by IBM Cognos TM1
3. Save and close the file.
4. Repeat these steps for each computer running TM1 components that communicate with the TM1
Admin Server.
5. Edit the tm1web_config.xml file to specify the port number of the Admin Server.
• If you are using TLS, edit the AdminHostSSLPort parameter.
• If you are not using TLS, edit the AdminHostPort parameter.

100 IBM Planning Analytics: Installation and Configuration

 The tm1web_config.xml file is located in <TM1 install location>\webapps\tm1web\WEB-
INF\configuration\.
For more details about the tm1web_config.xml file, see “Editing the TM1 Web configuration file” on
page 225 and “TM1 Web configuration parameters” on page 219.

Configuring TM1 Server to use IPv6

By default, TM1 uses IPv4. To use IBM TM1 Server with internet protocol version 6 (IPv6), you configure a
combination of TM1 parameters and an operating system environment variable.

About this task

You can configure TM1 to use one of the following modes to specify which internet protocol that you want
TM1 to use with your network.
ipv4
Default setting. Used for IPv4 networks.
dual
Used to transition from IPv4 to IPv6. Both protocols are supported.
ipv6
Used for IPv6 networks.

Procedure
1. Configure the TM1 Admin Server:
a) On the computer where the TM1 Admin Server is running, open Cognos Configuration.
b) Expand the Local Configuration > Environment node and click TM1 Admin Server.
c) In the Component Properties pane, set the TM1 Admin Server IP support option to either Dual
(IPv4 and IPv6), IPv4, or IPv6.
d) If needed, add the IPv6 address to the /etc/hosts operating system file on UNIX and Microsoft
Windows. In some cases, depending on your network environment and DNS configuration, you may
need to perform this additional step to successfully run the TM1 Admin Server and TM1 Server in
IPv6 mode.
e) Add the TM1_IPVersion environment variable as described in step 3.
2. Configure the TM1 Server:
a) On the computer where the TM1 Server is running, open the [Link] file.
b) Set the IPversion parameter to the IP mode that you want to use.
For example, to specify that your network uses the IPv6 protocol, add the parameter as follows:
IPVersion=ipv6
For more details, see “IPVersion” on page 354.
c) If needed, add the IPv6 address to the /etc/hosts operating system file on UNIX and Microsoft
Windows.
d) Add the TM1_IPVersion environment variable as described in step 3.
3. Add the TM1_IPVersion environment variable to the operating system for each computer that
communicates directly with the TM1 Admin Server or TM1 Server.
Use the following variable name and value format:
TM1_IPVersion=ip_mode
where ip_mode can be one of the following values:
• Dual
• IPv6

Chapter 7. Installing the Data Tier 101

 • IPv4
The TM1_IPVersion environment variable is required on any computer that is running any of the
following TM1 components:
• TM1 Admin Server
• TM1 Server
• TM1 administrator tools
• TM1 Web (web server only)
• TM1 Application server
• TM1 clients:
– Cognos TM1 Architect
– Cognos TM1 Perspectives
– Cognos TM1 Performance Modeler
– Cognos Insight
• Custom applications that use the Cognos TM1 API.
Note : You do not need to set this environment variable on computers that use only a web browser to
access TM1 Web.
4. Restart any TM1 servers that you modified.
5. Test the connection between your TM1 server and client applications.

Monitoring TM1 Server license usage

IBM TM1 Server generates IBM Software License Metric Tag (SLMT) files. Versions of IBM License Metric
Tool that support SLMT files can generate License Consumption Reports that provide information about
license usage for your TM1 Server.
For complete details on installing and using IBM License Metric Tool, see IBM License Metric Tool on IBM
Knowledge Center.
The initial generation of SLMT files is determined by the LicenseMetricTime [Link] parameter.
When the generation of SMLT files is enabled with LicenseMetricTime, a new SLMT file is created
every 24 hours.

The AUTHORIZED_USER metric

The AUTHORIZED_USER metric can have the following subtypes:
• IBM Cognos Enterprise Planning TM1 Modeler - Any user that is a member of the Admin, DataAdmin, or
SecurityAdmin user groups on the TM1 Server.
• IBM Cognos Enterprise Planning TM1 Contributor - Any user that is not a Modeler, but is assigned to a
group with write access to at least one cube on a TM1 Server. A group is defined to have write access for
a cube if the group is assigned one of the following security permissions for the cube: Write, Lock,
Reserve, or Admin.
• IBM Cognos Enterprise Planning TM1 Explorer - Any user that is not a Modeler or a Contributor.
For each of these subtypes, the AUTHORIZED_USER metric records the number of users who have logged
on to the TM1 Server during the period identified in the SLMT file.

Location of Software License Metric Tag files

On all operating systems, the SLMT files are created in the slmtag directory at the same level as the
bin64 directory in the TM1 install location. For example, C:\Program Files\IBM\cognos
\tm1_64\slmtag. All SLMT files use the .slmtag file extension.

102 IBM Planning Analytics: Installation and Configuration

 Troubleshooting
To help you understand how the number of Modelers, Contributors, and Explorers are calculated when
producing an SLMT file, the TM1 server also produces an identically named file, but with the .slmtagraw
file extension. These .slmtagraw files are created in a folder named slmtagraw, which exists at the same
level as the slmtag folder.
The .slmtagraw files are not consumed by the IBM License Metric Tool. They exist solely to provide you
with insight regarding metric calculation. For instance, in the following excerpt from a .slmtagraw file you
can see that the user named Planner is a Contributor. The user belongs to the BUDGET PLANNER group,
and that group has WRITE permission on the plan_BudgetPlan cube.

<Metric LogTime="2016-10-18T14:45:20Z">
<Type>GROUP_INFO</Type>
<SubType>GROUP_DETAIL</SubType>
<Value><![CDATA[Group BUDGET PLANNER is a contributor
group: Group BUDGET PLANNER has
WRITE permission on cube plan_BudgetPlan.]]>
</Value>
<Period>
<StartTime>2016-10-18T14:44:50Z</StartTime>
<EndTime>2016-10-18T14:45:20Z</EndTime>
</Period>
</Metric>

<Metric LogTime="2016-10-18T14:45:20Z">
<Type>USER_INFO</Type>
<SubType>MODELER</SubType>
<Value><![CDATA[User Planner is a Contributor.
Belongs to group BUDGET PLANNER.
Group BUDGET PLANNER has WRITE permission
on cube plan_BudgetPlan.]]>
</Value>
<Period>
<StartTime>2016-10-18T14:44:50Z</StartTime>
<EndTime>2016-10-18T14:45:20Z</EndTime>
</Period>
</Metric>

Cognos TM1 tools installation

Cognos tools and utilities are installed when the TM1 Data Tier > TM1 Tools component is selected
during installation.
These tools are optional components that you can choose not to install by clearing the TM1 Tools
component check box during installation. These tools are installed in <install_location>/bin64.
The tools that are installed in this group include:
TM1RunTI
TM1RunTI is a command line interface tool that can initiate a TM1 TurboIntegrator (TI) process from
within any application capable of issuing operating system commands.
Location: <install_location>/bin64
Filename: [Link]
See the Editing Advanced Procedures chapter of TM1 TurboIntegrator.
tm1xfer
The tm1xfer utility compresses and moves IBM Cognos TM1 server objects from one platform to
another platform while preserving mixed case names for objects on both Microsoft Windows and
UNIX platforms.
Location: <install_location>/bin64
Filename: [Link] and [Link]
See the Tools and Utilities chapter of TM1 Operations.

Chapter 7. Installing the Data Tier 103

 Cognos TM1 Operations Console (Deprecated in v2.0.)
The Cognos TM1 Operations Console can monitor multiple TM1 servers and provides extensive
formatting capabilities for log files. See the Using the IBM Cognos TM1 Operations Console chapter of
TM1 Operations for details.
TM1 Top
TM1 Top monitors a single Cognos TM1 server. Installed by default. See the System Performance and
Monitoring chapter of TM1 Operations for details.
odbc_test
The odbc_test tool is used to diagnose and test an IBM Cognos TM1 ODBC connection on UNIX. See
the Tools and Utilities chapter of TM1 Operations for details.

Cognos TM1 sample databases installation

IBM Cognos TM1 samples illustrate product features and technical and business best practices. You can
also use them for learning the product, testing, and troubleshooting.

Cognos TM1 samples overview

Cognos TM1 samples are available for a variety of uses and are optimized for different clients. Some of the
samples are ready to use right after installation while others require extra steps to use them. Cognos TM1
samples are installed in the following places:
TM1_installation_location\samples\tm1
Installed by default
TM1_installation_location\webcontent\samples
Optional to install. You can choose to install these when you run the installation wizard.
Important : If you are upgrading Planning Analytics Local and don't need to keep your existing Cognos
TM1 samples, then delete the files in TM1_installation_location\samples\tm1 before you install
Planning Analytics Local. If you want to keep your existing Cognos TM1 samples, see “Upgrading the
samples” on page 113.
The product samples are installed as follows:
SData, Planning Sample, GO_New_Stores, GO_Scorecards, Proven_Techniques, and 24Retail
These samples are installed by default in the TM1_installation_location\samples\tm1
location.
SData and Planning Sample were specifically designed to be used with Cognos TM1.
To use them, start each sample database in Cognos Configuration after installation.
GO_New_Stores and Proven_Techniques are designed to highlight Cognos TM1 Performance
Modeler, TM1 Applications, and Cognos Insight features.
The Proven_Techniques sample highlights cube calculations and functions. You can also import
multiple applications in the portal and view them using Cognos Insight Connected mode.
The GO_Scorecards sample includes data that is optimized for use with the IBM Cognos Scorecard
features found in Cognos TM1 Performance Modeler.
The 24Retail sample represents a fictitious company, named 24Retail, that sells cellphones,
computers, and other widgets. Its data can be used by Planning Analytics Workspace, Planning
Analytics for Microsoft Excel, Architect, and TM1 Web.
See “Using the sample databases installed by default” on page 105 for more information.
PData, Rules_Guide_Data, TI_Data
These samples are designed specifically for Cognos TM1. To use them you must first add each server
in Cognos Configuration and then start them individually. They are installed into the
TM1_installation_location\samples\tm1 location.

104 IBM Planning Analytics: Installation and Configuration

 GO_Contributor.zip, sample_outdoors.zip, advanced_techniques.zip,
[Link], and [Link]
These samples are installed only if you select the TM1 Samples component in the TM1 Data Tier in
the installation wizard. They are installed to the TM1_installation_location\webcontent
\samples\datasources\cubes\amdtool directory.
The [Link] samples require you to restore a database and connect to the
database using an OLAP data source. The database files are installed with the samples, and are
provided for IBM Db2®, Microsoft SQL Server, and Oracle databases.
The other samples are based on .csv files for their content and do not require a database to be
restored. See “Using the GO_Contributor and Outdoors Company sample databases” on page 106 for
more information.
[Link], [Link] and [Link].
A set of .cdd and data samples have been specifically designed for use with Cognos Insight
workspace builder. These samples with localized versions are available TM1 installation
location\webcontent\samples\datasources\cubes\amdtool\Source_files\desktop.
These samples are installed only if you select the TM1 Samples component in the TM1 Data Tier in
the installation wizard.
On UNIX, use the ./startup_tm1s.sh command to start sample database servers. See" Starting a
UNIX TM1 Server" and "Stopping a UNIX TM1 Server" in TM1 Operations for more details.

Using the sample databases installed by default

The following sample databases are installed by default and can all be started from Cognos Configuration

About this task

These databases are installed by default into the sample database location.
For example C:/Program Files/IBM/cognos/tm1/samples/tm1/SData
SData
Data designed for use with TM1.
PlanSamp
Data designed for use with the Planning clients.
GO_New_Stores
Data designed for use with TM1 Applications, Cognos Insight, and Cognos TM1 Performance Modeler.
GO_Scorecards
Data designed for use the TM1 Scorecarding in TM1 Performance Modeler.
Proven_Techniques
This sample database uses cube calculations and features from more recent releases. This database
is also designed for use with the TM1 Scorecard features in Cognos TM1 Performance Modeler.

Procedure
1. In Cognos Configuration, right click the database you want to start and select Start.
2. To open the databases, in TM1 Architect or TM1 Performance Modeler, double-click the database and
use the default username of admin and password of apple.

Chapter 7. Installing the Data Tier 105

Using the GO_Contributor and Outdoors Company sample databases
The following GO_Contributor and Outdoors Company samples are installed as .zip files that you must
unzipped in order to use them.

Procedure
1. On the computer where you installed the TM1 server component, go to the tm1_location
\webcontent\samples\datasources\cubes\amdtool folder.
2. Extract the contents of the GO_Contributor.zip or the Outdoors_Company.zip file.
Be sure to do the extraction close to the root location such as c: so that the file path is not too long.
3. In the folder where you extracted the filea, go to the Data Files folder, and open the [Link] file
in a text editor.
a) Ensure that the DatabaseDirectory location, the LoggingDirectory location, and the
DistributedPlanningOutputDir use the correct path for the Data Files folder location
where you extracted the Go_Contributor.zip and Outdoors_Company.zip files.
b) Save and close the files.
4. Open IBM Cognos Configuration.
5. In the Explorer panel, under Data Access, right click TM1 Server, and click New Resource > TM1
Server Instances.
a) In the Name box, enter GO Contributor or Outdoor Company.
b) For the TM1 Server configuration path value, enter the path to the Data Files folder where you
extracted the files.
For example, tm1_location\samples\GO_Contributor
c) In the Explorer panel, right-click GO Contributor or Outdoor Company and click Start.
6. Test that the new servers are available to Architect.
a) Open Architect.
b) Double click the server.
c) In the Server Login box, enter admin in the UserName box and apple in the Password box.
7. To test that the new servers are available in the IBM Cognos Applications portal:
a) Open the portal by typing the following: [Link]
b) Click the Administer IBM Cognos TM1 Application icon.
c) Under Server Names, click Add.
d) Type the server name in Admin Host and then click the Refresh button.
e) Select the sample you just added, and click OK.

Using the Great Outdoors Sales server samples based on the sample
database
The Great Outdoors Sales sample uses data from a database. To use this sample you must restore the
database, create an ODBC connection to the database, and then add the sample server to your system.
The database is provided for IBM Db2, Microsoft SQL Server, and Oracle.
The sample database and the Cognos TM1 server using the database are installed with Cognos TM1
server in the tm1_location/webcontent/samples/datasources folder.
When you create your ODBC connection, use GOSALESDW as the data source name. On Microsoft Windows
operating systems, create the ODBC connection as a System DSN.

106 IBM Planning Analytics: Installation and Configuration

Restoring backup files for IBM Db2
Use the script that is provided to restore sample databases on IBM Db2.
To set up the sample database, you must extract the GS_DB [Link] file, customize a configuration file,
and run the setup script.

Procedure
1. Go to the tm1_location/webcontent/samples/datasources folder.
2. Extract the GS_DB.[Link] file and retain the original directory structure.
If you use WinZip to extract the GS_DB.[Link] file on a Microsoft Windows operating system, ensure
that the TAR file smart CR/LF conversion option is not selected.
3. On Linux and UNIX operating systems, modify the file permissions on the [Link] file so that it
is executable.
For example,

chmod u+x [Link]

4. If you want to change the sample configuration file to use settings other than the default values, edit
the GOSalesConfig file.
The configuration file on Windows is [Link]. The configuration file on Linux and UNIX
is [Link].
The GOSalesConfig configuration file contains the default configuration options that are used when
creating the GOSALES data. The default configuration settings are listed in the following table

Table 14. Default configuration settings for GOSALES data

Configuration Setting Default Description

GOSALES_INST GS_DB Used to set the name or alias of

the database.

GOSALES_CREATEDB Optional: Causes an existing

database with the same name to
be dropped.

GOSALES_DB_TERRITORY US When creating a database this is

the territory of the UTF-8
database that is created.

GOSALES_BP GOSALES_BP Optional: Enter the buffer pool

and tablespace name, if these
GOSALES_TS GOSALES_TS
are to be created by the script.

GOSALES_GRANTEES GOSALES, DB2ADMIN Enter the list of users, groups or

PUBLIC that will have CONTROL
permissions for the GOSALES,
GOSALESHR, GOSALESMR and
GOSALESRT schemas. This
string needs to follow the syntax
of the GRANT command.

Chapter 7. Installing the Data Tier 107

 Table 14. Default configuration settings for GOSALES data (continued)

Configuration Setting Default Description

GOSALESDW_GRANTEES GOSALESDW Enter the list of users, groups or

PUBLIC that will have CONTROL
DB2ADMIN
permissions for the
GOSALESDW schema.

GOSALES_DPF N Change to 'Y' if installing a

database partitioned
environment (DPF)

GOSALES_SCHEMA GOSALES Enter the names to be used for

each schema.
GOSALESHR_SCHEMA GOSALESHR
GOSALESMR_SCHEMA GOSALESMR
GOSALESRT_SCHEMA GOSALESRT
GOSALESDW_SCHEMA GOSALESDW

By default, the GS_DB database name is used and permissions are granted to the DB2ADMIN (Linux,
UNIX, Windows) and GOSALES users.
5. To run the setupGSDB script in interactive mode, run following command:
• On Windows computers, in an IBM Db2 command window, change to the GS_DB\win directory and
run the [Link] script.
• On UNIX computers, from a shell prompt, source the db2profile, change to the GS_DB/unix
directory, and run the [Link] script.
The script displays a summary of your choices before you commit to changes to your environment. If
you approve the choices, press Enter.
6. To run the setupGSDB script from the command line, run the following command:
• On Windows computers, run the [Link] script.
• On UNIX computers, run the [Link] script.
You can run the setupGSDB script with the following options:

Option Description

-createdb Creates the database. This option drops any

existing database with the same name. It creates
the required buffer pool and table space.

-database database name Specifies the name of the database. This value
overrides the default value of GS_DB.

-userid administration_user_ID Specifies the name of the Db2 administrator user

ID that is used to create the database.

-password administration_user_ID Specifies the password for the Db2 administrator

user ID.

108 IBM Planning Analytics: Installation and Configuration

 Option Description

-noprompt Indicates that no prompt will display. This option

runs the script in silent mode. Any missing
information causes the script to fail. You will not
be prompted for any confirmations.

For example, if you are an IBM Db2 administrator and want to create the default GS_DB database on
the local node, use the following command:

setupGSDB -createDB -noprompt

If you want to create the tables in an existing database named SAMPLE, and you want to use the
administrator user ID db2admin, run the following command:

setupGSDB -database SAMPLE -userid db2admin

The script prompts you for the password when it connects to the database. The script will replace any
tables that already exist in the database, unless you choose to drop the database.
7. If the GS_DB sample database is installed on a remote server in your environment, you can link to it by
cataloguing the remote database on your local computer and then running the setup script locally.
a) If the sample database does not yet exist on the remote server, create it by using CREATE
DATABASE command.
The database requires a UTF-8 codeset and a default table space with a pagesize of 16 KB or larger.
For example, on the remote server, create the database by running the following command:

CREATE
DATABASE GS_DB USING CODESET UTF-8 TERRITORY US PAGESIZE 16k

b) On your local computer, catalog the remote database by using the following command:

db2
catalog tcpip node nodename remote ipaddr server port_number
db2 catalog database GS_DB as GS_DB at node nodename

c) On your local computer, run the following command:

setupGSDB -database GS_DB -userid administration_user_ID

You are prompted for a password to connect to the database.

Restoring backup files for Oracle

Use the scripts that are installed with TM1 to quickly and conveniently restore backup files for sample
databases in Oracle.

About this task

To set up the sample database, you must extract the GS_DB_ORA.[Link], file, customize a
configuration file, and run the setup script.

Procedure
1. Go to the tm1_location/webcontent/samples/datasources.
2. Extract the GS_DB_ORA.[Link] file and retain the original directory structure.
3. On Linux and UNIX operating systems, modify the file permissions on the [Link] file so that it
is executable:

Chapter 7. Installing the Data Tier 109

 chmod u+x [Link]

4. Ensure that the user ID used to set up the Oracle database has authority to create users and run the
import utility.
5. Optional - If you want to change the sample configuration file to use settings other than the default
values, edit the GOSalesConfig file.
The configuration file on Windows is [Link]. The configuration file on UNIX is
[Link].
The GOSalesConfig configuration file contains the default configuration options that are used when
creating the GOSALES data. The default configuration settings are listed in the following table

Table 15. Default configuration settings for GOSALES data

Configuration Setting Default Description

GOSALES_IMP_CMD imp If necessary can be modified

to specify the complete path
to the correct version of the
import utility.

GOSALES_INST Oracle host string.

GOSALES_TS GOSALES_TS If users are created by scripts,

used to enter the tablespace
name to assign to users.

GOSALES_CREATE_TS Optional: Used to create the

default tablespace for users.

GOSALES_TEMP_TS If users are created by scripts,

used to name a temporary
tablespace to assign to users.
Leave blank to use the default
temporary tablespace.

GOSALES_SCHEMA GOSALES Used to enter the username

and password for the
GOSALES_SCHEMA_PW GOSALESPW
GOSALES user. You will be
prompted for a password if
not entered.

GOSALESHR_SCHEMA GOSALESHR Used to enter the username

and password for the
GOSALESHR_SCHEMA_PW GOSALESHRPW
GOSALESHR user. You will be
prompted for a password if
not entered.

GOSALESMR_SCHEMA GOSALESMR Used to enter the username

and password for the
GOSALESMR_SCHEMA_PW GOSALESMRPW
GOSALESMR user. You will be
prompted for a password if
not entered.

110 IBM Planning Analytics: Installation and Configuration

 Table 15. Default configuration settings for GOSALES data (continued)

Configuration Setting Default Description

GOSALESSRT_SCHEMA GOSALESRT Used to enter the username

and password for the
GOSALESRT_SCHEMA_PW GOSALESRTPW
GOSALESRT user. You will be
prompted for a password if
not entered.

GOSALESDW_SCHEMA GOSALESDW Used to enter the username

and password for the
GOSALESDW_SCHEMA_PW GOSALESDWPW
GOSALESDW user. You will be
prompted for a password if
not entered.

GOSALES_GRANTEES GOSALES Used to enter the users that

will have SELECT, INSERT,
DELETE, UPDATE, and ALTER
permissions for GOSALES,
GOSALESHR, GOSALESMR
and GOSALESRT schemas.
Note: The owner of the
GOSALES_SCHEMA will
always be granted SELECT,
INSERT, DELETE, UPDATE and
ALTER privilege on all
schemas.

GOSALESDW_GRANTEES GOSALESDW Used to enter the users that

will have SELECT, INSERT,
DELETE, UPDATE and ALTER
permissions for GOSALESDW
schema.

6. To run the setupGSDB script in interactive mode, run following command:

• On Windows computers, in a DOS command window, change to the GS_DB_ORA\win directory and
run the [Link] script.
• On UNIX computers, from a shell prompt, change to the GS_DB_ORA/unix directory, and run the
[Link] script.
Press Enter to proceed. The script displays a summary of your choices before you commit to changes
to your environment. If you approve the choices, press Enter and the script makes the changes
7. To run the setupGSDB script from the command line, run the following command:
• On Windows computers, run the [Link] script.
• On UNIX computers, run the [Link] script.
You can run the setupGSDB script with the following options:

Option Description

-createdb Creates the database. This option drops any

existing database with the same name. It creates
the required buffer pool and table space.

Chapter 7. Installing the Data Tier 111

 Option Description

-database database name Specifies the name of the database. This value
overrides the default value of GS_DB.

-userid administration_user_ID Specifies the name of the Db2 administrator user

ID that is used to create the database.

-password administration_user_ID Specifies the password for the Db2 administrator

user ID.

-noprompt Indicates that no prompt will display. This option

runs the script in silent mode. Any missing
information causes the script to fail. You will not
be prompted for any confirmations.

For example, if you are an Oracle administrator and want to create the default sample database
schemas, run the following command:

setupGSDB -createDB -noprompt

You want to create the tables in the existing schemas specified in the configuration file, and you want
to use the administrator user ID sys. run the following command:

setupGSDB -YourOracleInstance-userid sys -sysdba

The script prompts you for the password when it connects to the Oracle instance. The script deletes
any existing tables or views in the specified schemas and replaces them.

Restoring backup files for Microsoft SQL Server

Use the Microsoft SQL Server database management tool to quickly and conveniently restore backup files
for sample databases.

Procedure
1. On the computer where you installed TM1 server, go to the following directory:
tm1_location/webcontent/samples/datasource/Source files/sqlserver
2. If required, copy the backup files for the samples databases to your database backup directory.
3. Restore the database from a device, and ensure that the restore locations are correct for the .ldf
and .mdf database files.
4. Create at least one user who has select permissions for all the tables in the restored databases.

Setting up Great Outdoors Sales sample

The Great Outdoors Sales sample uses data from the database you restored.

Procedure
1. Create an ODBC data source connection to the restored database.
Use GOSALESDW as the data source name. On Windows operating systems, create the ODBC
connection as a System DSN.
2. On the computer where you installed the TM1 server component, go to the tm1_location
\webcontent\samples\datasources\cubes\amdtool folder.
3. Extract the contents of the [Link] file.

112 IBM Planning Analytics: Installation and Configuration

 Be sure to do the extraction close to the root location such as c: so that the file path is not too long.
4. In the folder where you extracted the [Link] file, go to the DataFiles folder,
and open the [Link] file in a text editor.
a) Ensure that the DatabaseDirectory location and the LoggingDirectory location use the
correct path for the location where you extracted the [Link] file.
b) Save and close the file.
5. Open IBM Cognos Configuration.
6. In the Explorer panel, under Data Access, right click TM1 Server, and click New Resource > TM1
Server Instances.
a) In the Name box, enter GreatOutdoorsSales.
b) For the TM1 Server configuration path value, enter the path to the DataFiles folder where you
extracted the [Link] file.
For example, tm1_location\webcontent\samples\datasources\cubes\amdtool
\GreatOutdoorsSales\DataFiles
c) In the Explorer panel, right-click GreatOutdoorSales and click Start.
7. Test that the new GreatOutdoorsSales server is available to Architect.
a) Open Architect.
b) Double click the GreatOutdoorsSales server.
c) In the Server Login box, enter admin in the UserName box and apple in the Password box.
8. Test that the new GreatOutdoorsSales server is available in the IBM Cognos Applications portal.
a) Open the portal by typing the following: [Link]
b) Click the Administer IBM Cognos Application icon on the far right hand side
c) Under Server Names, click Add.
d) Type the server name in Admin Host and then click the Refresh button.
e) Select the GreatOutdoorsSales sample you just added, and click OK.

Upgrading the samples

If you use the samples in IBM Planning Analytics Local version 2.0.0 or higher and you want to keep any
updates that you made to them, follow these steps as part of the upgrade to a new version of IBM
Planning Analytics Local.

About this task

Important : Follow these steps only if you want to carry your existing samples database forward with the
upgrade. If you don't need to keep your samples database, then upgrade IBM Planning Analytics Local as
described in “Upgrading from Planning Analytics version 2.0.0” on page 78.

Procedure
1. Before you start the upgrade of Planning Analytics Local, back up the following files.
• The \PA_installation_location\tm1\samples\tm1\PlanSamp\[Link] file.
• The sample databases that you use, located in \PA_installation_location\tm1\samples
\tm1.
2. After you finish the upgrade of IBM Planning Analytics Local, merge the [Link] backup file with the
newly installed [Link]. When you merge the files, overwrite the values in the newly installed file
with the values from the backup file.
3. Put the merged [Link] file into the new installation location in \tm1_location\tm1\samples
\tm1\PlanSamp\.

Chapter 7. Installing the Data Tier 113

 4. Copy the samples files that you backed up to the samples installation location in \tm1_location
\tm1\samples\tm1\.
5. Start the services.

Install and configure the Planning Analytics Administration agent

(local only)
If you have IBM Planning Analytics Local version 2.0.5 or later installed, you can install and configure
the Planning Analytics Administration agent for Microsoft Windows or Linux operating systems.
To use IBM Planning Analytics Administration on Planning Analytics Workspace Local, you must install
and configure the Planning Analytics Administration agent wherever you have installed IBM TM1 Server.
The default port of the Planning Analytics Administration agent is 9012.
By default, the Planning Analytics Administration agent is selected as a component when you install
Planning Analytics Local but it is not configured or started.
Note : You can upgrade your Planning Analytics Administration agent by installing a new version of
Planning Analytics Local or by downloading a new version of the agent from Planning Analytics
Workspace. For more information, see Planning Analytics Administration agent in Download additional
components.
To upgrade an Planning Analytics Administration agent as part of a Planning Analytics Local upgrade, you
must stop the Planning Analytics Administration agent service, back up your [Link]
file, upgrade Planning Analytics Local selecting the Planning Analytics Administration agent component in
the installation wizard, and then restart the Planning Analytics Administration agent. For more
information, see Upgrading Planning Analytics Local.
Your changes to the [Link] file are preserved when you upgrade the Planning Analytics
Administration agent, however, the version of the agent is updated. On Windows, the version is updated
when you upgrade using the Planning Analytics Local installation wizard. On Linux, the version is updated
when you run ./startup_agent.sh install.
After you install or upgrade the agent, you must configure it. For more information, see “Configure the
agent for Windows” on page 114 or “Configure the agent for Linux” on page 115.

Configure the agent for Windows

Procedure
1. Open the Windows Services desktop application.
2. Stop the IBM Planning Analytics Administration Agent service if it is running.
3. Navigate to <PA_install_location>/paa_agent/bin.
4. Run [Link] to set JAVA_HOME for your Planning Analytics Administration
agent.
5. Start the IBM Planning Analytics Administration Agent Windows service.
Note : You can also navigate to <PA_install_location>/paa_agent/bin and run the
[Link] script to start the Planning Analytics Administration agent Windows service.

What to do next
Navigate to Planning Analytics Administration in Planning Analytics Workspace Local and verify that the
TM1 databases appear.
Note : If you change the [Link] file later, you must restart the IBM Planning
Analytics Administration Agent Windows service by running [Link] script.

114 IBM Planning Analytics: Installation and Configuration

Configure the agent for Linux

Before you begin

Set the RunningInBackground parameter in your [Link] file to RunningInBackground=T.
Note : The RunningInBackground parameter is required for Linux only. It is used to suppress the
prompts displayed by TM1 Server. Since Planning Analytics Administration uses scripts to start and stop
databases on TM1 Server, you must set RunningInBackground=T on Linux.

Procedure
1. Navigate to <PA_install_location>/paa_agent/bin.
2. Run the ./shutdown_agent.sh command to stop the IBM Planning Analytics Administration
Agent if it is running.
3. Navigate to <PA_install_location>/paa_agent/wlp/usr/servers/kate-agent.
4. In a text editor, open the [Link] file.
5. Set the full path of the directory that contains TM1 databases data directories to SERVERS_DIR.
Note : Multiple paths must be separated by a semicolon. For example, /opt/ibm/cognos/tm1_64/
samples/tm1/;/srv/prod/servers/.
6. Save and close the [Link] file.
7. Navigate to <PA_install_location>/paa_agent/bin.
8. Run ./set_java_home.sh <Full path to JRE> to set JAVA_HOME for your Planning Analytics
Administration agent.
9. Run ./startup_agent.sh install to set up the Planning Analytics Administration agent service.
Note : You must have root or sudo privileges to perform this step.
10. Run ./startup_agent.sh command to start the Planning Analytics Administration agent.

What to do next
Navigate to Planning Analytics Administration in Planning Analytics Workspace Local and verify that the
TM1 databases appear.
Note : If you change the [Link] file later, you must restart the IBM Planning
Analytics Administration Agent by running ./startup_agent.sh command.

Configure event notifications

About this task

To get notifications from Planning Analytics Administration for Planning Analytics Local, you must
configure the following functionality:

Procedure
1. Set the following bootstrap properties for SMTP notifications:
For example, set these properties:

SMTP_EMAIL_PORT=587
SMTP_EMAIL_AUTH=true
SMTP_EMAIL_HOST=[Link]
SMTP_EMAIL_USERNAME=user@[Link]
SMTP_EMAIL_PASSWORD=Analytics123
PAA_EMAIL_ADDRESS=noreply@[Link]

Chapter 7. Installing the Data Tier 115

 The PAA_EMAIL_ADDRESS must be a registered alias, otherwise set it to a primary alias, for example,
the user name noreply@[Link].
2. Optional: Set SMTP_EMAIL_START_TLS_ENABLE=true and add the certificates to the TLS certificate
store:
a) Run the following command in a command prompt on Windows or a terminal on Linux.

openssl s_client -showcerts -starttls smtp -crlf -connect [Link]

This command prints two certificates that begin with "-----BEGIN CERTIFICATE-----" and
end with "-----END CERTIFICATE-----".
b) Copy these two certificates (including the BEGIN CERTIFICATE and END CERTIFICATE lines) to
Example_1.cer and Example_2.cer and remember the location.
For example, <PA install directory>/paa_agent/wlp/usr/servers/kate-agent/
resources/security. You use this location in the next step.
c) Import Example_1.cer to the Planning Analytics Administration agent store by using the
following command and the location of the Example_1.cer file from step “2.b” on page 116.
On Windows:

[Link] -importcert -keystore "<PA install directory>/paa_agent/wlp/usr/servers/kate-

agent/resources/security/server_store.p12" -storetype PKCS12
-trustcacerts -storepass applix -file "<PA install directory>/paa_agent/wlp/usr/servers/
kate-agent/resources/security/Example_1.cer" -alias example1

On Linux:

./keytool -import -keystore "<PA install directory>/paa_agent/wlp/usr/servers/kate-agent/

resources/security/server_store.p12" -storetype PKCS12
-trustcacerts -storepass applix -file "<PA install directory>/paa_agent/wlp/usr/servers/
kate-agent/resources/security/[Link]" -alias example1

d) Repeat the previous step to import the second certificate, Example_2.cer.

What to do next
You can get notifications for chore failures, threads that are in a run state, threads in a wait state, and
more. For more information, see Set system resource thresholds and alerts in the Planning Analytics
Workspace documentation.

Sample [Link] file

# General properties
SERVERS_DIR=<PA_install_location>/samples/tm1
EXE_PATH=<PA_install_location>/bin64/[Link]
SERVER_INFO_PATH=<PA_install_location>/paa_agent/paaAgentCache

TM1_SERVER_INFO_PROCESS_TIME_INTERVAL=20000
NOTIFICATION_MEM_USAGE_INTERVAL=30000
NOTIFICATION_SERVER_UNRESPONSIVE_INTERVAL=40000
FILE_TAILER_REFRESH_INTERVAL=86400000
PAA_EMAIL_ADDRESS=administration@[Link]
MODEL_UPLOAD=model_upload
SCRIPT_TIMEOUT=15

# SMTP Properties
SMTP_EMAIL_PORT=<port>
SMTP_EMAIL_AUTH=false
SMTP_EMAIL_HOST=<host>
SMTP_EMAIL_START_TLS_ENABLE=false
SMTP_EMAIL_USERNAME=<username>
SMTP_EMAIL_PASSWORD=<encrypted_pwd>

# Logging properties
[Link]=OFF
[Link]="*\=audit\:[Link].*\=warning"
[Link]=10
[Link]=4

116 IBM Planning Analytics: Installation and Configuration

 VERSION=[Link]

General properties
SERVERS_DIR
This parameter is applicable to Linux only. It specifies the full path of the directory that contains the
TM1 databases directories.
Note :
Multiple paths must be separated by a semicolon. For example,
SERVERS_DIR=C:/tm1/samples/tm1/;C:/prod/servers/
You can specify the parent directory of your databases. You don't need to specify each database
separately.
EXE_PATH
Internal use only. Do not change.
SERVER_INFO_PATH
Internal use only. Do not change.
TM1_SERVER_INFO_PROCESS_TIME_INTERVAL
Internal use only. Do not change.
Time in milliseconds between successive task executions. Used in the scheduler that checks system
health.
NOTIFICATION_MEM_USAGE_INTERVAL
Internal use only. Do not change.
Not currently used.
NOTIFICATION_SERVER_UNRESPONSIVE_INTERVAL
Internal use only. Do not change.
Time in milliseconds between successive task executions. Used in the scheduler that checks for
server unresponsiveness.
FILE_TAILER_REFRESH_INTERVAL
Internal use only. Do not change.
Time in milliseconds between successive task executions. Used in scheduler that tails server logs for
every TM1 Server.
PAA_EMAIL_ADDRESS
Internal use only. Do not change.
MODEL_UPLOAD
Internal use only. Do not change.
SCRIPT_TIMEOUT
Internal use only. Do not change.

SMTP properties
SMTP_EMAIL_PORT
Set to a free port. For example, 2500.
SMTP_EMAIL_AUTH
Default is false.
SMTP_EMAIL_HOST
Set based on your email server. For example, localhost.
SMTP_EMAIL_START_TLS_ENABLE
Default is false. Whether you need to configure certificates and set START_TLS_ENABLE=true
depends on your email server configuration.

Chapter 7. Installing the Data Tier 117

 SMTP_EMAIL_USERNAME
Full email address. For example, example@my [Link].
SMTP_EMAIL_PASSWORD
Email password for SMTP_EMAIL_USERNAME.

Logging properties
[Link]
This setting controls the granularity of messages that go to the console.
When this log is enabled, a [Link] is generated with the agent [Link] at
<PA_install_location>/paa_agent/wlp/usr/servers/kate-agent/logs.
Valid values are: INFO, AUDIT, WARNING, ERROR, and OFF.
Default is OFF.
[Link]="*=audit:[Link].*=warning"
This setting is used to selectively enable trace.
This entry refers to the agent [Link].
Valid values are: INFO, AUDIT, WARNING, ERROR, and OFF.
A restart of the Planning Analytics Administration agent is required for a logging value to take effect
when you change this property.
[Link]
The maximum size (in MB) that a log file can reach before it is rolled.
Default is 10. For more information, see Logging and Trace.
[Link]
If an enforced maximum file size exists, this setting is used to determine how many of each of the logs
files are kept.
Default is 4. For more information, see Logging and Trace.

118 IBM Planning Analytics: Installation and Configuration

Chapter 8. Installing the Web Tier
You can install Web Tier components using the IBM Planning Analytics Local installation program.
You can install the following Web Tier components:
• TM1 Application Gateway
• TM1 Application Server
• Cognos Access Manager

TM1 Application Server installation

You can install the web application server components for IBM Planning Analytics on a separate,
dedicated computer so that users in a network environment can access them. These components include
the TM1 Application Server and the TM1 Application Gateway.
The TM1 Application Server must be deployed on a Java-based web application server. When installing
TM1 Application Server, first determine which of the following web application servers you want to use:
• The WebSphere Liberty Profile application server that is provided
• Your own installation of IBM WebSphere Application Server
For more information about TM1 Application Server architecture and deployment, see:
• “TM1 Applications architecture” on page 69
• “Deploying TM1 Applications components on a single computer” on page 74
• “Deploying TM1 Applications components on separate computers” on page 75

Deploying with the provided version of WebSphere Liberty Profile server

The fastest and easiest way to install and deploy TM1 Application Server is to use the version of
WebSphere Liberty Profile server that is provided and installed with the Planning Analytics installation
program. This method uses Cognos Configuration to start and stop the TM1 Application Server.
For more information, see “Install TM1 Application Server” on page 120.

Deploying to your own web application server

To deploy TM1 Application Server with your own instance of a Java-based web application server, use
Cognos Configuration to first create the [Link] web application archive file, and then manually
deploy the file. For more information, see “Install TM1 Application Server with your own installation of
WebSphere” on page 126.

TM1 Application Server with x64 Windows

When running TM1 Application Server on an x64 Microsoft Windows system with WebSphere Liberty
Profile server, use the same 64-bit versions of the Java Runtime Environment (JRE) and WebSphere
Liberty Profile web server. Do not mix platform versions. For example, if you are using the 64-bit version of
JRE, then you should also use the 64-bit version of WebSphere Liberty Profile.

Integrating TM1 Application Server with Cognos Analytics and Cognos Connection
portal
If your Planning Analytics installation uses Cognos security for authentication, your Cognos Analytics
users can use the Cognos Connection portal to open Planning Analytics applications instead of the TM1
Applications Web portal. However, administrators still need to use TM1 Applications Web to configure and
manage applications.

© Copyright IBM Corp. 2007, 2021 119

 When you configure TM1 Application Server to use Cognos security, you also enable the Cognos
Connection portal to display a folder that contains links to the available Planning Analytics applications.
The exact list of displayed applications depends on the rights of the current user.
The [Link] file provides the information for Cognos Analytics and the Cognos Connection portal
to display links to Planning Analytics applications. For more information, see “Using Cognos TM1
Applications with Cognos security” on page 269.

Install TM1 Application Server

You can install IBM TM1 Application Server on a separate computer and deploy it with the instance of
WebSphere Liberty Profile that is provided with the installation. This type of installation is intended for an
environment where the TM1 Admin Server and TM1 Server are running on another computer.

Installing TM1 Web Tier components

Follow these steps to install the required files for TM1 Application Server and its components on a
separate computer. If you plan to use the TM1 Web client, you need an installation of TM1 Web on either
the same computer or a different computer in your network.

About this task

Note : To install TM1 Web on a different computer, see “Cognos TM1 Web installation” on page 131.

Procedure
1. Right-click the [Link] file and click Run as Administrator to run the IBM Planning Analytics
installation program.
2. In the installation program select only the following components:
• TM1 Application Gateway
• TM1 Application Server
• TM1 Web - This component is optional. Select this to install TM1 Web on the same computer as TM1
Application Server.
3. Follow the prompts to complete the installation.

Deploying the TM1 Application Server with the provided WebSphere Liberty
Profile application server
The TM1 Application Server runs in the WebSphere Liberty Profile application server that is provided with
the installation. Use Cognos Configuration to deploy and start WebSphere Liberty and TM1 Application
Server.

Procedure
1. Click Start > All Programs > IBM Cognos TM1 > IBM Cognos Configuration.
If you installed the product from the Program Files (x86) directory on a computer running Windows 7,
start IBM Cognos Configuration as an Administrator.
2. In the Cognos Configuration Explorer panel, expand the Local Configuration > Environment > IBM
Cognos TM1 Services , right-click IBM Cognos TM1 and select Start.
This will start the provided version of WebSphere Liberty Profile server and then deploy and start the
TM1 Application Server.
3. Click File > Save and close IBM Cognos Configuration.

120 IBM Planning Analytics: Installation and Configuration

Configuring authentication security for TM1 Application Web
For IBM TM1 Server used with TM1 Application Web, use either TM1 standard security authentication or
IBM Cognos security.

About this task

Configure the authentication login mode using the IntegratedSecurityMode parameter in the
[Link] file of each TM1 Server that you want to use.
TM1 Application Web is compatible only with the following TM1 security authentication modes:
• Authentication mode 1 - TM1 standard security authentication
• Authentication mode 5 - Cognos security
Important : Do not use a combination of different security authentication modes for the same installation
of TM1 Application Web.
For best practice, determine the security mode before you configure TM1 Application Web to use a TM1
Server and use that same security mode with any additional servers you add.
For more details about security authentication and the IntegratedSecurityMode parameter, see:
• “Authentication security ” on page 246
• “IntegratedSecurityMode” on page 352

Procedure
1. Open the file TM1 server data directory/[Link]
2. Set the IntegratedSecurityMode parameter for the TM1 Server.
• To use TM1 standard security authentication, set IntegratedSecurityMode=1
• To use Cognos security, set IntegratedSecurityMode=5
For details about using Cognos security, see:
• “Using Cognos TM1 Applications with Cognos security” on page 269
• “Cognos security” on page 261
3. Save and close the [Link] file.
4. Restart the TM1 Server.
5. Repeat these steps for any other TM1 Server you want to use with TM1 Application Web.

Configuring the server and client environment for TM1 Application Web
Before you use IBM TM1 Application Web, you need to specify the TM1 Admin Host, TM1 Server, and
client user interfaces that you want to use. The first time that you start TM1 Application Web, the program
prompts you to configure these options.

Before you begin

Ensure that the TM1 Admin Server and at least one TM1 Server is running on the local computer or a
remote computer that you can access.
Ensure that each TM1 Server that you want to use is configured with the required parameter values. For
more information, see “Configuring a TM1 Server to work with TM1 Application Web” on page 124 .
If you plan to use Cognos TM1 Application Web, ensure that you know the web server name and port
number where Cognos TM1 Web is running.

Chapter 8. Installing the Web Tier 121

 Procedure
1. Start and log in to TM1 Application Web:
a) In a web browser, type the URL for TM1 Application Web:
[Link]
b) Replace localhost with the name of the computer where the TM1 Application Server is installed.
2. Open the Cognos TM1 Application Configuration page:
• If this is the first time that TM1 Application Web has been started since the installation, the
Configuration page opens.
• If TM1 Application Web has already been configured, you are prompted for a user name and
password and then you can open the configuration page by clicking the Administer IBM Cognos TM1
Applications button on the toolbar of the Cognos TM1 Application Web main page.
3. In the Admin Host field, enter the name or IP address of the computer where the TM1 Admin Server is
running.
Note : The Admin Host and Server Name fields appear blank if you have not started the TM1 Admin
Server and at least one TM1 Server.
4. In the Server Name field, enter the name of the TM1 Server that you want to use with TM1 Application
Web.
For example, you can specify the sample TM1 Server GO_New_Stores.
Click the Refresh button to refresh the list of available servers.
5. Select the data contribution clients that you want to use with TM1 Application Web.
These clients will be available when you create applications with TM1 Performance Modeler.
• Include Cognos Insight - Connected - Cognos Insight client using real time processing with the
TM1 Server.
• Include TM1 Application Web - Default client. Processing is in real time with the server. This
option uses the data grid and charting client infrastructure from TM1 Web and requires that you
enter a value for the TM1 Application Web URL option.
6. If you selected the Include TM1 Application Web option, enter a value for the TM1 Application Web
URL option.
This URL points to the [Link] file on the web server that is hosting TM1 Web.
For example:
[Link]
where WebServer is the name of the computer where TM1 Web is installed.
7. Click OK.
8. If prompted, enter the username and password for the server and click Login.
Tip : Use admin and apple for the user name and password if you are using one of the installed
sample databases.
The TM1 Application Web main page displays. This page appears blank until you build and deploy
applications inside of TM1 Application Web.

Results
The following message indicates that the TM1 Server that you are using is not properly configured for use
with TM1 Application Web:
The new server can be added but it may not be configured with all the options
required by IBM Cognos TM1 Applications.

122 IBM Planning Analytics: Installation and Configuration

For information on how to configure this server, see “Configuring a TM1 Server to work with TM1
Application Web” on page 124.

TM1 Application Server settings in Cognos Configuration

You can configure settings for IBM TM1 Application Server in IBM Cognos Configuration.
In Cognos Configuration, click Environment > TM1 Applications.
Session timeout (min)
Time after which if there is no activity that the TM1 Server disconnects. Default is 60 minutes.
Force qualified paths
When set to True, a machine name that is provided as the Admin Host resolves to a fully qualified
domain name. When set to False, only the machine name is used.
Notifications provider
• DLS (Delivery Service): If a mail server is configured, emails are sent but no notifications display in
the Cognos Inbox.
• HTS (Human Task Service): Notifications are sent to the Cognos Inbox, and emails also sent if a mail
server is configured.
By default, left blank for no notifications.
Enable Business Viewpoint
True means Business Viewpoint can interact with this installation. False prevents Business Viewpoint
from interacting.
Cognos Connection Folder Name
Specifies the name of the Cognos Connection folder in which hyperlinks to deployed TM1 applications
are contained. Default is IBM Cognos TM1 Application - My Applications
TM1 Application Server Dispatcher URI
The URI used for the dispatcher servlet, for example [Link]
dispatcher/servlet
User ID and Password
User ID and Password used to authenticate.
Under TM1 Applications, click TM1 Clients.
Provisioning URI
Specifies a URI to use to manually set the msi locations.
Allow provisioned installs
True permits users without the clients installed to provision and install them from TM1 Application
Server. False blocks users from provisioning and installing client software.
Allow provisioned updates
True permits updates that are installed on the TM1 Application Server such as a Fix Pack version to be
provisioned to clients when users next connect. False prevents updates from being provisioned.
Enable publish from Cognos Insight
True permits a user with Admin rights to publish from Cognos Insight. False disallows the Publish
operation for all users.
Cognos Insight ping frequency (seconds)
Determines the frequency with which Cognos Insight verifies connectivity to the TM1 Application
Server. Default is 30 seconds.

Chapter 8. Installing the Web Tier 123

Configuring a TM1 Server to work with TM1 Application Web
Before you use IBM TM1 Server with IBM TM1 Application Web, edit the TM1 Server configuration file
([Link]) to include the required parameters and values.

About this task

The following configuration parameters in the [Link] file support different subcomponents of TM1
Application Web.
AllowSeparateNandCRules
Supports TM1 Performance Modeler with TM1 Application Web.
See “AllowSeparateNandCRules” on page 337.
ForceReevaluationOfFeedersForFedCellsOnDataChange
Supports TM1 Performance Modeler with TM1 Application Web. When this parameter is set, a feeder
statement is forced to be re-evaluated when data changes.
See “ForceReevaluationOfFeedersForFedCellsOnDataChange” on page 351.

Procedure
1. Open the TM1 Server configuration file, [Link].
2. To support TM1 Performance Modeler, edit or add the following line:
AllowSeparateNandCRules=T
3. Edit or add the ForceReevaluationOfFeedersForFedCellsOnDataChange parameter.
4. Save the [Link] file.
5. Restart the TM1 Server.
6. Repeat these steps for any other TM1 Servers you want to use with TM1 Application Web.

Determining the URL startup link for TM1 Application Web

The exact link to start and log on to Cognos TM1 Application Web depends on which web server you are
running and how it is configured.
You can see the default startup URL for TM1 Application Web in IBM Cognos Configuration.
1. Open Cognos Configuration.
2. Click to expand Local Configuration > Environment and then select TM1 Applications.
3. The URL is listed in the value column for the TM1 Application Server Gateway URI field.
For example: [Link]

Link Parameters
Use the following format for the URL to log in to TM1 Application Web.
[Link]

124 IBM Planning Analytics: Installation and Configuration

Table 16. TM1 Application Web - URL parameters
Parameter Description

WebServer Can be one of the following:

The keyword localhost if you are currently logged on to the web server that
is running TM1 Application Server.
The machine name or domain name of the web server hosting the TM1
Application Server.
The IP address of the web server hosting the TM1 Application Server.

PortNumber The port number you configured with web application server.
IBM WebSphere - Click the Web Server link in the WebSphere Administrative
Console to view and edit port settings.

Link Examples
Table 17. TM1 Application Web - link examples
Web Application
Server Header
WebSphere Liberty The default link when using the provided version of WebSphere Liberty Profile
Profile provided with is:
the installation
[Link]

IBM WebSphere The usual link for TM1 Application Web running on IBM WebSphere
Application Server Application Server is:

[Link]

Configuring TM1 Application Web

IBM Planning Analytics Local uses IBM Cognos TM1 Web to support the Cognos TM1 Application Web
client. TM1 Application Web enables users to view and edit planning application data in grid format. If you
want to allow users to use TM1 Application Web, you need to configure this option.

About this task

When you install TM1 Web, the required files for TM1 Application Web are copied to the TM1 Web
installation location.
The main file for TM1 Application Web is:
[Link]
The default install location is:
PA_install_location\webapps\tm1web
Configure the TM1 Application Web URL parameter in TM1 Application Web to point to the
[Link] file in this location.

Procedure
1. Open the Configuration page in TM1 Application Web:

Chapter 8. Installing the Web Tier 125

 • If you are running TM1 Application Web for the first time, use the Configuration page that opens
when you start the program.
For more details, see “Configuring the server and client environment for TM1 Application Web” on
page 121.
• If you are already using TM1 Application Web, you can re-open the Configuration page by clicking the
Administer IBM Cognos TM1 Applications button on the toolbar in TM1 Application Web.
2. In the TM1 Application Web URL field, enter the URL location of the [Link] file.
Use the format:
[Link]
For example:
[Link]
3. Click OK.
The Login page for TM1 Application Web is displayed.

TM1 Application Server advanced installation and configuration

You can perform advanced installation and configuration tasks to customize your installation of the IBM
TM1 Application Server components.

Install TM1 Application Server with your own installation of WebSphere

You can install IBM TM1 Application Server on a separate computer and deploy it with your own
installation of IBM WebSphere.
This installation is intended for an environment where the TM1 Admin Server and TM1 Server are running
on another computer.
To deploy the TM1 Application Server to WebSphere, complete these tasks:
1. Build the application files using Cognos Configuration. See “Building application files for a WebSphere
server” on page 126.
A [Link] file is created. The default location is <PA_install_directory>\ibm\cognos
\TM1\.
Note : You can use the EAR file format instead of WAR.
2. Deploy the [Link] file to the WebSphere application server.

Building application files for a WebSphere server

You use IBM Cognos Configuration to build application files to deploy to an IBM WebSphere server.

About this task

You can create a web archive (WAR) file or enterprise archive (EAR) file for the following TM1 applications:
• TM1 Planning Services: [Link]/ear
• TM1 Web and TM1 Applications Web [Link]/ear
• TM1 Operations Console: [Link]/ear (Deprecated in v2.0.9)
You can then deploy the WAR or EAR files to WebSphere.

Procedure
1. Click Start > All Programs > IBM Cognos TM1 > IBM Cognos Configuration.
2. Click Actions > Build Application Files.
3. Under Application, select TM1 Application Server.

126 IBM Planning Analytics: Installation and Configuration

4. Under Application Server Type, select IBM WebSphere. Click Next.
5. Select the file type.
6. Specify where to save the application files.
The default location is <PA_install_directory>\ibm\cognos\TM1\. Click Next.
7. Wait for the Build Application Wizard to complete the process. Click Finish.

What to do next
You can deploy the application files to your WebSphere Application Server. See “Deploying TM1
Application Server to a WebSphere Application Server” on page 127.

Deploying TM1 Application Server to a WebSphere Application Server

You can deploy and run IBM TM1 Application Server to an IBM WebSphere Application Server.

Before you begin

• Install IBM WebSphere Application Server.
• Create a profile using the Profile Management Tool.
• Start the WebSphere Application Server using the profile that you created.
In Microsoft Windows, click Start > All Programs > IBM WebSphere Application Server > Profiles >
[Profile Name] > Start the server.
A command window opens and displays the start progress. After the start process is complete, the
command window displays the message, "Server started." You can minimize this command window, but
do not close it. This window must remain open while WebSphere is running.
• Build the application files using Cognos Configuration. See “Building application files for a WebSphere
server” on page 126.
For information about installing WebSphere and creating a profile, see the WebSphere documentation.

About this task

These steps are based on IBM WebSphere Application Server 8.5.5. The steps for version 8.5 are similar.
Note : After you start completing steps in the WebSphere application installation wizard, click Cancel to
exit if you decide not to install the application. Do not move to another administrative console page
without first clicking Cancel on an application installation page.

Procedure
1. Verify that you have a minimum of 6 GB of free disk space on the computer where WebSphere is
installed.
On UNIX, ensure that the disk mounted to /tmp has at least 6 GB available. Use df to check both the
total space and percent used for tmpfs.
Note : Do not deploy TM1 Application Server until you have verified that sufficient disk space is
available.
2. Open the WebSphere administrative console.
• In Windows, click Start > All Programs > IBM WebSphere Application Server > Profiles > [Profile
Name] > Administrative console. Or, go to [Link]
• In UNIX, click Applications > IBM WebSphere > IBM WebSphere Application Server > Profiles >
[Profile Name] > Admin Console. Or, go to [Link]
3. Log in using the WebSphere profile that you created.
The administrative console opens.
4. Set the JVM stack memory size.

Chapter 8. Installing the Web Tier 127

 a) Click Servers > Server Types > WebSphere application servers.
b) Click the server where you are deploying TM1 Application Server.
c) Under Server Infrastructure, click Java and Process Management > Process Definition.
d) Under Additional Properties, click Java Virtual Machine.
e) In the Generic JVM arguments field, add -Xmso512k.

DANGER : Do not deploy TM1 Application Server until you have set the stack memory.

Do not use the [Link] file to set the stack memory size. WebSphere removes the -
Xmso setting from the file when the server starts and overrides it with the default value, which is
too small.
f) Click Apply, and then click OK. Click Save.
5. Click Applications > New Application, and then click New Enterprise Application.
6. Click Browse to locate and select the [Link] file that you generated using the Build
Application File command in Cognos Configuration. Click Open.
7. Click Next.
8. Click Fast Path, and then click Next.
9. Click Step 4: Map context roots for Web modules.
10. In the Context Root box, enter /pmpsvc. Click Next.
11. Click Finish.
WebSphere installs the application. This process can take a few minutes to complete.
When installation is complete, WebSphere displays "Application pmpsvc_war installed successfully."
12. Click Save.
13. Click Applications > Application Types > WebSphere Enterprise Applications.
14. Select the check box next to pmpsvc_war, and then click Start.
WebSphere displays "Application pmpsvc_war on server server_name and node node started
successfully. The collection may need to be refreshed to show the current status."

What to do next
See “What if my TM1 Application Server deployment fails with a Java heap space error?” on page 399

Configuring TM1 Application Web to use multiple TM1 Servers

When you start IBM TM1 Application Web for the first time, you can enter only one IBM TM1 Server that
you want to work with.
To enter more servers, use the Configuration page in TM1 Application Web.
Important : To use multiple TM1 Servers in Cognos TM1 Application Web, the servers must all use the
same security authentication (either TM1 standard authentication or Cognos Analytics security) and
include the same administrator user name and password. For more information, see “Security
considerations when using Cognos TM1 Applications” on page 246.
After you add multiple TM1 Servers, they are available when you use IBM TM1 Performance Modeler to
design your planning applications.
For more details, see the TM1 Performance Modeler documentation.

Procedure
1. Log in to Cognos TM1 Application Web.
2. On the toolbar, click the Administer Cognos TM1 Applications button .
The IBM Cognos TM1 Applications Configuration page opens

128 IBM Planning Analytics: Installation and Configuration

 3. In the Server Names section, click Add.
The Add Server dialog box opens.
4. Enter the following values:
• Admin Host - Specify the computer name or IP address of the Admin Host on which the Cognos TM1
Admin Server is running.
Click the Refresh button to update the Server Name list with the available servers for the Admin
Host you entered.
• Server Name - Select a TM1 Server to use with Cognos TM1 Application Web. For example: Planning
Sample.
5. Click OK.
If you receive a warning message about the configuration of the TM1 Server, make a note of the
warnings and then click Close to continue. For more information, see “Configuring a TM1 Server to
work with TM1 Application Web” on page 124.
The Admin Host and TM1 Server name you entered are added to the Server Names section.
6. To add more servers, click Add and repeat the steps.
7. When you are finished adding TM1 Servers, click OK on the IBM Cognos TM1 Applications
Configuration page.

Results
The TM1 Servers you added can now be used to design your planning applications.

Disabling the X-Frame-Options header

The X-Frame-Options header is enabled by default to help prevent cross-frame scripting attacks. If
necessary, you can disable it.

Procedure
1. Locate the fpmsvc_config.xml file in the Cognos_TM1_install_location\webapps\pmpsvc
\WEB-INF\configuration directory.
2. Set the value attribute of the httpHeader element to empty string.
For example, <httpHeader name="XFrames" value=""/>

Monitoring TM1 Application Server logs

You can monitor the activity and performance of IBM TM1 Application Server by configuring and viewing
the TM1 Application Server log file.
The TM1 Application Server uses the log4j framework to control the Planning Services (pmpsvc) logging.
The logging settings are dynamic. Any changes that you make to the logging properties file will be
detected while the service is running.

Logging properties file

Logging is configured in the following file:
<tm1_installation_location>\webapps\pmpsvc\WEB-INF\configuration
\[Link]
For example, the default installation location on a 64-bit Microsoft Windows system is:
C:\Program Files\IBM\cognos\tm1_64\webapps\pmpsvc\WEB-INF\configuration\

Chapter 8. Installing the Web Tier 129

 Log file output
By default, the service is configured to log only ERROR messages into a text file which contains all the log
entries for a 24 hour period. The log file and directory are located here:
<tm1_installation_location>\webapps\pmpsvc\WEB-INF\logs\[Link]
Older log files for previous days are named with the format:
[Link]-MM-DD

Log file message levels

There are four levels of detail which can be logged. Each level contains all log entries for that level and
each higher level.

Table 18. Level Description

Level Description
ERROR Outputs exceptional events which cause the service not to be able to complete
the current operation.

WARNING Outputs conditions from which the service can continue but should be addressed
by an administrator.

INFO Outputs information for each of the service operations.

DEBUG Outputs details tracing information for the service operations.

Examples of enabling logging

The logging level of information is controlled by changing the level under the following two roots of the
service:
• [Link]
• [Link]
All the components of the service are situated beneath these trees, so changing the logging level for these
will log all events at that level.
For example, to change the service to log at the INFO level, change these entries to the following:

#System logging settings

[Link]=ERROR, TextFile
[Link]=INFO
[Link]=INFO

More specific logging is available by changing the logging level for classes lower than these top levels. For
example, it is possible to get WARNING logging for everything but to log TurboIntegrator process calls at
the DEBUG level.

#System logging settings

[Link]=ERROR, TextFile
[Link]=WARNING
[Link]=WARNING
[Link]=DEBUG

You can enable performance logging in the service by commenting out the standard logging and including
the following performance entries in the properties file:

# System logging settings

#[Link]=ERROR, Console, TextFile
#[Link]=DEBUG

130 IBM Planning Analytics: Installation and Configuration

 #[Link]=DEBUG
#[Link]=ERROR
#[Link]=ERROR

# Performance logging settings

[Link]=ERROR, perfConsole, perfText
[Link]=DEBUG

Cognos TM1 Web installation

You can install IBM Cognos TM1 Web on a computer that is separate from the computer where you
installed the Cognos TM1 Server and other Cognos TM1 components.
Note : Starting with the [Link] LC release of Planning Analytics Local, TM1 Web is no longer part of the
web tier within the Planning Analytics Local installer. Instead, TM1 Web is installed with the IBM Planning
Analytics Spreadsheet Services installer. The IBM Planning Analytics Spreadsheet Services installer is
part of the 2.0.55 SC and later releases.
This documentation describing how to install TM1 Web as part of the web tier within Planning Analytics
Local is provided for customers who are installing an LC release prior to [Link] and have not yet upgraded
to the 2.0.55 SC (or later) release of TM1 Web. If you need details on installing TM1 Web with the IBM
Planning Analytics Spreadsheet Services installer, see Chapter 13, “ IBM Planning Analytics TM1 Web
installation,” on page 209.
You can deploy TM1 Web on an IBM WebSphere Application Server. For more information, see “Installing
TM1 Web” on page 132.
When you install TM1 Web, TM1 Applications Web is also installed. For more information, see “TM1 Web
architecture” on page 68.
Note : Add the <PA_install_directory>\bin64\ directory to the library path environment variable
(LD_LIBRARY_PATH). This is required only when you install IBM TM1 Web on a computer that is separate
from the computer where you installed TM1 Server .

Check for changes to [Link] file

If you are upgrading IBM Planning Analytics TM1 Web with IBM Planning Analytics Local version 2.0.5,
you install a new version of the [Link] file called [Link] and your existing [Link] file is
preserved.
To take advantage of fixes applied in this release, you must use the [Link] file and you must
reapply any changes that you made to your previous configuration settings. In particular, restore your
values for session-timeout.
1. Back up the existing [Link] file in <PA_installation_location>/webapps/tm1web/WEB-
INF. For example, rename [Link] to [Link]. This step backs up your current settings.
2. Rename [Link] to [Link]. This step uses the new version of [Link] that is supplied with
IBM Planning Analytics Local version 2.0.5.
3. Replace the entry for session-timeout in [Link] with the entry from [Link]. This step
restores any changes that you made to this property previously.
For example:

<session-config>
<session-timeout>20</session-timeout>
</session-config>

Install Cognos TM1 Web

The following items are an overall checklist for installing Cognos TM1 Web.
1. Check prerequisites. For more information, see “Check for changes to [Link] file” on page 131.
2. Install Cognos TM1 Web.

Chapter 8. Installing the Web Tier 131

 3. Use the WebSphere administrative console to start the application server.
4. Run and test Cognos TM1 Web from your network environment.
5. Edit the Cognos TM1 Web configuration file to support a multiple computer environment.
6. Configure the TM1 Web login page using AdminHostName and TM1ServerName parameters.
7. Configure authentication and data transmission security.
8. Modify CognosTM1 Web configuration parameters.
9. Configure the web browsers in your environment.

Installing TM1 Web

You can install Cognos TM1 Web on a separate computer and deploy it with the instance of WebSphere®
Liberty that is provided with the installation.
The IBM Cognos TM1 installation configures Cognos TM1 Web to run with the provided version of the
WebSphere® Liberty web application server.
After you have installed the Cognos TM1 Web on the separate computer, edit the Cognos TM1 Web
configuration file to identify the remote computer where the Cognos TM1 Admin Server is running.

Install and configure Cognos TM1 Web on Microsoft Windows

These steps describe how to install IBM Cognos TM1 Web on a separate computer that is running
Microsoft Windows. These steps apply when you are using the provided WebSphere Liberty application
server.

About this task

This procedure also installs the IBM Cognos Configuration utility. You use Cognos Configuration to start
and stop the application server.
When IBM Cognos TM1 Web is installed on a separate computer, edit the configuration file to identify the
IBM Cognos TM1 Admin Server and IBM Cognos TM1 servers in your network that you want to use with
Cognos TM1 Web.

Procedure
1. Run the installation program that matches the type of computer being used for Cognos TM1 Web:
2. Right-click the [Link] file and click Run as Administrator.
3. Select only the following TM1 Web Tier components: TM1 Web, TM1 Application Server, and
Cognos Access Manager.
Deselect all the other components.
Important :
Cognos Access Manager must be installed as part of the web tier installation. If Cognos Access
Manager is not installed, then Cognos TM1 Web and the PMPSVC web application cannot connect to
the Cognos TM1 Admin Server and the Cognos TM1 Server.
4. Follow the prompts in the installation wizard to complete the installation.
5. Start IBM Cognos Configuration.

Attention : If you installed the product from the Program Files (x86) directory on a computer
running Windows 7, start IBM Cognos Configuration as an Administrator.
6. In the Cognos Configuration Explorer panel, expand the Local Configuration > Environment node,
right-click TM1 Application Server and select Start.
This starts the provided web application server for Cognos TM1 Web.
7. Confirm that Cognos TM1 Web is running by entering the URL for Cognos TM1 Web in a web browser.
For example:

132 IBM Planning Analytics: Installation and Configuration

 [Link]
On a remote computer, replace localhost with the name or IP address of the computer where
Cognos TM1 Web is running.
8. Configure Cognos TM1 Web to connect to remote Cognos TM1 servers in your network.
If you want Cognos TM1 Web to connect to a specific Cognos TM1 Admin Server or Cognos TM1
server in your network, configure the AdminHostName and TM1ServerName parameters in the
Cognos TM1 Web configuration file, tm1web_config.xml.
See “Configuring the TM1 Web login page using AdminHostName and TM1ServerName parameters”
on page 225.
9. Configure security options for Cognos TM1 Web.
You can configure authentication security, such as Integrated Login or IBM Cognos Security, and data
transmission security, such as TLS, depending on your system and network environment.
See Chapter 15, “Planning Analytics Local security,” on page 245.
10. Configure additional options in the CognosTM1 Web configuration file.
See “Modifying TM1 Web configuration parameters” on page 218.
11. Review the steps for web browser configuration.
You can configure web browser options such as language and regional settings for your users.
See “Configuring web browsers for Cognos TM1 Web” on page 235.

Install and configure TM1 Web on UNIX

Installing IBM TM1 Web on a UNIX system requires that you import the certificate to the Java keystore on
UNIX. These steps apply if you are using the provided WebSphere® Liberty application server.

Before you begin

You must set the JAVA_HOME environment variable before you can start IBM Cognos Configuration.
Cognos Configuration is used for starting the web application server for TM1 Web.
You must also add the <PA_install_directory>\bin64\ directory to the library path environment
variable (LD_LIBRARY_PATH). This setting is required only when you install IBM TM1 Web on a Linux
server, separate from where you installed TM1 Server.

About this task

Importing the certificate to the Java keystore on UNIX is required to enable TM1 Web to display the list of
the available TM1 Servers.

Procedure
1. Run the installation program:
a) Go to the location where the installation files were downloaded and extracted, or insert the product
disk.
b) Go to the operating system directory and then type
./issetup
c) Advance to the Component Selection screen.
d) Select the following TM1 Web Tier components: TM1 Web , TM1 Application Server, and Cognos
Access Manager..
Clear all the other components.

Chapter 8. Installing the Web Tier 133

 Important : Cognos Access Manager must be installed as part of the web tier installation. If Cognos
Access Manager is not installed, then TM1 Web and the PMPSVC web application cannot connect to
the TM1 Admin Server and the TM1 Server.
e) Follow the prompts in the installation wizard to complete the installation.
2. Import the certificate to the Java keystore on UNIX.
a) Change directory to the bin64 location that is associated to JAVA_HOME.
b) Run the following command:
keytool -import -file "/bin64/ssl/[Link]" -keystore "/usr/
java8/jre/lib/security/cacerts" -storepass "changeit"
3. Add the <PA_install_directory>\bin64\ directory to the library path environment variable
(LD_LIBRARY_PATH).
4. Start IBM Cognos Configuration:
Go to the install_location/bin64 directory and then type the following command:
./[Link]
5. Start the web application server for TM1 Web:
In the Cognos Configuration Explorer panel, expand the Local Configuration > Environment > IBM
Cognos TM1 node, right-click IBM Cognos TM1 and select Start.
6. Confirm that TM1 Web is running by entering the URL for TM1 Web in a web browser on a remote
computer. For example:
[Link]
Replace <unix_web_server> with the name or IP address of the computer where TM1 Web is running.

What to do next
Depending on your system and network environment, perform the following additional configuration
steps:
• Configure TM1 Web to connect to a specific TM1 Admin Server or TM1 Server in your network.
See “Configuring the TM1 Web login page using AdminHostName and TM1ServerName parameters” on
page 225.
• Configure security options for TM1 Web.
See Chapter 15, “Planning Analytics Local security,” on page 245.
• Configure additional options in the TM1 Web configuration file.
See “Modifying TM1 Web configuration parameters” on page 218.
• Review the steps for web browser configuration.
See “Configuring web browsers for Cognos TM1 Web” on page 235.

Post-installation configuration
After installing TM1 Web, you can modify configuration parameters to customize TM1 Web for your
specific requirements. You can also configure web browsers to optimize the use and display of TM1 Web.
For details, see:
• “Modifying TM1 Web configuration parameters” on page 218
• “Configuring web browsers for Cognos TM1 Web” on page 235

Cognos TM1 Operations Console installation

Deprecated in v2.0.9 The IBM Planning Analytics installation program installs the IBM Cognos TM1
Operations Console with the provided web application server. You can also install TM1 Operations

134 IBM Planning Analytics: Installation and Configuration

 Console with your own web application server. The TM1 Operations Console is a Java-based, optional
component used to monitor the activity of Cognos TM1 servers.

Installing Cognos TM1 Operations Console using the provided WebSphere®

Liberty webserver software
Deprecated in v2.0.9 The IBM Cognos TM1 Operations Console is a Java-based tool that is used to
monitor the activity of TM1 Servers. The Cognos TM1 Operations Console is installed by default when you
install Planning Analytics Local and uses the provided WebSphere® Liberty web server software.

Before you begin

• Ensure that the Planning Analytics Local prerequisite software is installed.
• Ensure that the TM1 Admin Server, the TM1 Application Server, the TM1 Server that you want to
monitor, and the TM1 databases are installed and running.
• Ensure that you can start Cognos TM1 Architect and can log in as an administrator to the TM1 Server
that you want to monitor.
• All services must be running under a single domain account. The IBM Planning Analytics Local
installation wizard sets the parameters of the domain account for you, but you must create the account
under which the services run before you run the installation. If services are running under different
accounts, they will not be able to communicate with each other.
Before you upgrade Cognos TM1 Operations Console:
• After upgrading to Planning Analytics Local version 2.0.2, you might find that servers that were
previously configured for monitoring are no longer visible in Operations Console. Similarly, Watchdog
rules might not work as expected after upgrade.
Both of these issues occur when there are spaces in a user name, either the user name used to log in to
Operations Console or a user name referenced in a Watchdog rule. To resolve this issue:
1. Stop the IBM Cognos TM1 service.
2. Open the [Link] file.
3. Change any user names that include spaces to use a plus sign (+) in place of spaces. For example,
change "joe doe" to "joe+doe".
4. Save the [Link] file.
5. Restart the IBM Cognos TM1 service.
For more information, see Issues when upgrading to Planning Analytics version 2.0.2 TM1 Operations
Console ([Link]

Procedure
1. On Microsoft Windows, right-click the [Link] command and click Run as Administrator. For
other operating systems, double-click the [Link] file on the Planning Analytics Local
installation disk or from the location where the TM1 installation files were downloaded and extracted.
2. Ensure the TM1 Data Tier and the TM1 Web Tier are selected.
Remember : Install IBM TM1 components in a directory that contains only ASCII characters in the
path name. Some Windows web servers do not support non-ASCII characters in directory names.

Using Cognos Configuration to deploy Cognos TM1 Operations Console

Deprecated in v2.0.9 Start the TM1 Applications Server in Cognos Configuration to deploy the
WebSphere® Liberty server needed to run the TM1 Operations Console.

Chapter 8. Installing the Web Tier 135

 Before you begin
If you installed the product from the Program Files (x86) directory on a computer running Microsoft
Windows 7 operating system software, start IBM Cognos Configuration as an Administrator.

Procedure
1. Click Start > All Programs > IBM Cognos TM1 > IBM Cognos Configuration.
2. Right-click TM1 Application Server and click Start.
This step starts the version of WebSphere® Liberty provided with TM1, and automatically deploys the
Cognos TM1 Operations Console.
3. Save the configuration data by clicking File > Save.
4. Close Cognos Configuration by clicking File > Exit.

Advanced Cognos TM1 Operations Console installation

Deprecated in v2.0.9 The following topics provide additional information about other ways to install
Cognos TM1 Operations Console.

Installing Cognos TM1 Operations Console on a separate machine

Deprecated in v2.0.9You can install only the Cognos TM1 Operations Console on a machine that is
separate from the servers being monitored.

Procedure
1. Install Cognos TM1 following the usual process, but select only the TM1 Operations Console from the
Web Components list.
By default this also installs the Cognos TM1 Applications Server and other services.
2. After installation, on the separate machine stop the TM1 Application Service.
3. Delete the installation_location/webapps/pmpsvc directory and the
installation_location/webapps/p2pd directories.
4. Restart the TM1 Application Service.

Installing Cognos TM1 Operations Console to IBM WebSphere

Deprecated in v2.0.9You can deploy Cognos TM1 Operations Console to IBM WebSphere Application
Server.
When you deploy Cognos TM1 Operations Console, Performance Management Hub is also deployed.
This installation is intended for an environment where the TM1 Admin Server and TM1 servers are running
on another computer.
To deploy Operations Console to WebSphere, complete these tasks:
• Build the application files using Cognos Configuration. See “Building application files for a WebSphere
server” on page 126. A [Link] file is created in the same location as the [Link] and
[Link] files. The default location is <your installation location>\ibm\cognos
\TM1\[Link].
Note : You can use the EAR file format instead of WAR.
• Deploy the [Link] file to the WebSphere application server
• Retrieve certificates from the TM1 Admin Server and TM1 servers
• Configure outgoing communications from WebSphere to the TM1 Admin Server

136 IBM Planning Analytics: Installation and Configuration

Deploying Cognos TM1 Operations Console to use an IBM WebSphere Application
Server
Deprecated in v2.0.9 Use the IBM WebSphere administrative console to deploy and run TM1 Operations
Console on a WebSphere Application Server.

Before you begin

• Install IBM WebSphere Application Server.
• Create a profile using the Profile Management Tool.
• Start the WebSphere Application Server using the profile that you created.
In Microsoft Windows, click Start > All Programs > IBM WebSphere Application Server > Profiles >
[Profile Name] > Start the server.
A command window opens and displays the start up progress. After the start up process is complete,
the command window displays the message, "Server started." You can minimize this command window,
but do not close it. This window must remain open while WebSphere is running.
• Build the application files using Cognos Configuration. See “Building application files for a WebSphere
server” on page 126. Operations Console and Performance Management Hub are contained in the
[Link] file.
For information about installing WebSphere and creating a profile, see the WebSphere documentation.

About this task

These steps are based on IBM WebSphere Application Server 8.5.5. The steps for version 8.5 are similar.
Note : After you start completing steps in the WebSphere application installation wizard, click Cancel to
exit if you decide not to install the application. Do not simply move to another administrative console page
without first clicking Cancel on an application installation page.

Procedure
1. Open the WebSphere administrative console.
• In Windows, click Start > All Programs > IBM WebSphere Application Server > Profiles > [Profile
Name] > Administrative console. Or, go to [Link]
• In UNIX, click Applications > IBM WebSphere > IBM WebSphere Application Server > Profiles >
[Profile Name] > Admin Console. Or, go to [Link]
2. Log in using the WebSphere profile that you created.
The administrative console opens.
3. Set the JVM stack memory size.
a) Click Servers > Server Types > WebSphere application servers.
b) Click the server where you are deploying Operations Console.
c) Under Server Infrastructure, click Java and Process Management > Process Definition.
d) Under Additional Properties, click Java Virtual Machine.
e) In the Generic JVM arguments field, add -Xmso512k.
Note : Do not deploy Operations Console until you have set the stack memory. If you do so,
Operations Console will be deployed but the WebSphere Application Server will not start.
Do not use the [Link] file to set the stack memory size. WebSphere removes the -
Xmso setting from the file when the server starts and overrides it with the default value, which is
too small.
f) Click Apply, and then click OK. Click Save.
4. Click Applications > New Application, and then click New Enterprise Application.

Chapter 8. Installing the Web Tier 137

 5. Click Browse to locate and select the [Link] file that you generated using the Build Application
File command in Cognos Configuration. Click Open.
6. Click Next.
7. Click Fast Path, and then click Next.
8. Click Step 4: Map context roots for Web modules.
9. In the Context Root box, enter /pmhub. Click Next.
10. Click Finish.
WebSphere installs the application. This process can take a few minutes to complete.
When installation is complete, WebSphere displays "Application pmhub_war installed successfully."
11. Click Save.
12. Click Applications > Application Types > WebSphere Enterprise Applications.
13. Select the check box next to pmhub_war, and then click Start.
WebSphere displays "Application pmhub_war on server server_name and node node started
successfully. The collection may need to be refreshed to show the current status."

What to do next
The next step is to retrieve SSL certificates from the TM1 Admin Server and TM1 servers.

Retrieving SSL certificates from the TM1 Admin Server and TM1 servers
Deprecated in v2.0.9 After you have deployed the applications file, [Link], to the IBM WebSphere
Application Server, the next step is to retrieve SSL certificates from the TM1 Admin Server and TM1
servers.

Procedure
1. In the IBM WebSphere administrative console, expand Security and then click SSL certificate and
key management.
2. Under Related Items, click Key stores and certificates.
3. Click the NodeDefaultTrustStore keystore.
4. Under Additional Properties, click Signer certificates.
5. Click Retrieve from port. Enter the following information:
• In the Host field, enter the host name of the TM1 Admin Server.
• In the Port field, enter 5498, the port number of the TM1 Admin Server.
• In the Alias field, enter TM1AdminServer_cert.
6. Click Retrieve signer information. WebSphere retrieves the SSL certificate from the TM1 Admin
Server.
7. Verify that the certificate information is for a certificate that you can trust.
8. Click Apply, and then click Save.
9. Repeat these steps for the TM1 servers you want to monitor with Operations Console.
For example:
• In the Host field, enter the host name of the TM1 server.
• In the Port field, enter the port number of the TM1 server.
• In the Alias field, enter TM1ServerName_cert.
Tip : The port number of a TM1 server is configured in the [Link] file in the PortNumber
parameter
10. Save your changes.

138 IBM Planning Analytics: Installation and Configuration

 What to do next
The next step is to configure outgoing communications between WebSphere and the TM1 Admin Server.

Configuring outgoing communications to the TM1 Admin Server

Deprecated in v2.0.9 After you have deployed the applications file, [Link], to the IBM WebSphere
Application Server and retrieved SSL certificates, the next step is to set up outgoing communications from
WebSphere to the TM1 Admin Server.

Procedure
1. In the WebSphere administrative console, expand Security and click SSL certificate and key
management.
2. Under Configuration settings, click Manage endpoint security configurations.
3. Expand Outbound > [node]Node01Cell > nodes.
4. Click [[node]Node01Cell, where node is the name of the server where you are deploying Operations
Console.
5. Under Related Items, click Dynamic outbound endpoint SSL configurations.
6. Click the NodeDefaultTrustStore keystore.
7. Click New.
8. In the Name field, enter tm1admin.
9. In the Description field, enter ssl connection.
10. Under Connection Information, enter *,*,5498, and then click Add.
Note : The value 5498 is the SSL port number of the TM1 Admin Server as specified in Cognos
Configuration.
11. Click Apply, and then click OK.
12. Save your changes.
13. Restart the WebSphere Application Server.
14. In a web browser, enter the URL to run Operations Console, [Link]
opsconsole/.
Replace port with the port number of the virtual host where you deployed [Link].
For example: [Link]
The Operations Console login page is displayed.

Configuring the Cognos TM1 Operations Console

Deprecated in v2.0.9 By default the Cognos TM1 Operations Console is configured to use a sample
adminhost of localhost, server of sdata, and a group called admin for authentication so you can get up and
running quickly. If you prefer, you can edit these configurations to customize the authentication server.

Procedure
1. Enter [Link] number/pmhub/pm/admin to open the configuration screen.
2. To change the default adminhost, server, and group for monitoring, expand Configurations >
Operations Console TM1 Monitors . Click in each setting to change it.
If you want to use Microsoft Internet Explorer 8 with the Cognos TM1 Operations Console see the
Microsoft Internet Explorer documentation and ensure these settings:
• Enable the option to refresh web pages with every visit
• Disable the options for script debugging

Chapter 8. Installing the Web Tier 139

Starting and logging into the Cognos TM1 Operations Console
Deprecated in v2.0.9 To open the IBM Cognos TM1 Operations Console, enter the URL that identifies the
port and server name for the component.

Procedure
1. In a web browser, type the following web address: [Link]
pmhub/pm/opsconsole
where
• servername is the computer where the Cognos TM1 Operations Console and your web application
server are installed. You can use the keyword localhost if you are currently logged on to the Web
server that is running Cognos TM1 Application Web. Or you can use the machine name, domain
name, or IP address of the Web server hosting the application.
• port_number is the port number where your web application server is running. For the version of
WebSphere® Liberty that is provided with the Cognos TM1 installation, the default port number is
9510.
2. On the log in page, enter values for the following fields, and then click Log In.
To use the default monitoring group, enter
• Namespace: Use the pull-down to select the available Namespace. If the system is a CAM-secured
system, the namespace is the Cognos Analytics namespace that the TM1 system is secured against.
If the system isn't CAM secured the namespace is adminhost/tm1 server for example localhost/
SData
• User Name: admin
• Password: apple
See Setting up the Cognos TM1 Operations Console to get started.

140 IBM Planning Analytics: Installation and Configuration

Chapter 9. Installing the Rich Tier
You can install Rich Tier components using the IBM Planning Analytics Local installation program or the
TM1 client installation program.
You can install the following Rich Tier components:
• TM1 Architect
• Performance Modeler
• TM1 Perspectives
• Cognos Insight
• Cognos TM1 APIs
For information about using the TM1 APIs to enable Cognos Analytics reporting against Cognos TM1 data
sources, see “TM1 as a datasource with Cognos Analytics” on page 240.

Installing Cognos TM1 Architect

You can install IBM Cognos TM1 Architect by performing the following steps.

Before you begin

Before you install Cognos TM1 Architect, complete the following tasks:
• Install the software that is necessary for you to run Cognos TM1 Architect. For more information, see
“Install the prerequisite software” on page 81.
• Ensure that the Cognos TM1 Admin Server and the Cognos TM1 Server that you want to connect to are
running on an accessible computer in your network. For details, see “TM1 Server installation” on page
89.
• Ensure that users have access to the Cognos TM1 servers that they need to use running under that
Cognos TM1 Admin Server. As a Cognos TM1 administrator, you must set up a user name and password
for each user before a user can access that server.

About this task

You can configure IBM Cognos TM1 Architect to locate a Cognos TM1 Administration Server on your
network, and then connect to a server. You can also create an unattended installation.
Attention : If you are upgrading and leave your old [Link] client configuration files in place,
you might need to update the directory path in the file for the AdminSvrSSLCertAuthority
parameter. For example, if you are using the default Cognos TM1 SSL certificate, manually change
the value for this parameter to the new install path C:\Program Files\IBM\cognos
\tm1\bin64\ssl\[Link].

Procedure
1. Install Cognos TM1 Architect:
a) Right-click the [Link] file and click Run as Administrator.
b) On the Component Selection page, expand TM1 Rich Tier, and select the TM1 Architect check
box.
Leave all the other check boxes unselected.
c) Follow the prompts and click Finish to complete the installation.
2. Run Cognos TM1 Architect:
a) Click Start > IBM Cognos TM1 > Architect.

© Copyright IBM Corp. 2007, 2021 141

 If the component does not start, ensure that the servers you started with Cognos Configuration are
still running.
3. Configure Cognos TM1 Architect to locate a Cognos TM1 Admin Server:
a) Open Server Explorer.
b) Select TM1.
c) Click File > TM1 Options.
d) In the Admin Host field, specify the name of the computer on which the TM1 Admin Server is
running. You must enter a name, not an IP address, in the Admin Host field.

Tip : If you want to access servers registered on different Admin Servers, use a semicolon to
separate the name of each Admin Host.
e) Click OK.
f) When prompted about disconnecting from currently accessed servers, click Yes if you want to
access a new list of servers. Servers available through Admin Server on the specified Admin Host
appear. If you want to continue to see the current list of remote servers during this session, click
No.
4. Double-click a Cognos TM1 Server to log in.
For either Planning Sample or SData, use these login credentials:
• User name: admin
• Password: apple
5. If you want to install Cognos TM1 Architect on multiple computers, use the previous steps to create an
unattended installation. For details, see “Setting up unattended installations and configurations” on
page 315.

Installing Cognos TM1 Performance Modeler

You can choose different ways to distribute and install IBM Cognos TM1 Performance Modeler across
multiple computers.
The following table summarizes the different ways to distribute and install Cognos TM1 Performance
Modeler across multiple computers.

Table 19. Multiple computer installation options for Cognos TM1 Performance Modeler
Installation option Description

“Installing Cognos TM1 Administrators or end users can install Cognos TM1 Performance
Performance Modeler using the Modeler on a single computer using the IBM Cognos TM1 Client-
installation program” on page 143 only installation program.

Optionally, use these steps to create an unattended installation to

install Cognos TM1 Performance Modeler on multiple computers.

“Installing Cognos TM1 As a prerequisite, an administrator must install Planning Analytics

Performance Modeler from the Applications.
Cognos TM1 Applications portal” on
This allows Planning Analytics users to install Cognos TM1
page 143
Performance Modeler onto their computers the first time that
they launch it from the IBM Cognos Applications Portal. This is
called a provisioned installation.
For more information about publishing workspaces, see IBM
Cognos TM1 Performance Modeler.

142 IBM Planning Analytics: Installation and Configuration

 Table 19. Multiple computer installation options for Cognos TM1 Performance Modeler (continued)
Installation option Description

“Remotely installing Cognos TM1 An administrator can use third-party network installation tools to
Performance Modeler on multiple push Cognos TM1 Performance Modeler out to multiple remote
computers” on page 144 client systems.

Installing Cognos TM1 Performance Modeler using the installation program

You can interactively install a stand-alone version of IBM Cognos TM1 Performance Modeler on one or
more computers.

Procedure
1. Right-click the [Link] file and click Run as Administrator to run the IBM Planning Analytics
installation program.
2. On the Component Selection page, expand TM1 Rich Tier, and select the Performance Modeler
check box.
Leave all the other check boxes unselected.
3. Follow the prompts and click Finish to complete the installation.
4. To test the installation, open Cognos TM1 Performance Modeler from the toolbar of the Cognos TM1
Applications portal page.
a) In a web browser, type the Cognos TM1 Applications URI:
For example, [Link]
• Replace localhost with the name of the computer where the Cognos TM1 Application Server is
installed.
• If required, change the port number if you used a different value in IBM Cognos Configuration for
the TM1 Application Server Gateway URI property.

b) From the Cognos TM1 Applications portal, click the Open Performance Modeler icon.
5. If you want to install the program on multiple computers, use the previous steps to create an
unattended installation. For details, see “Setting up unattended installations and configurations” on
page 315.

Installing Cognos TM1 Performance Modeler from the Cognos TM1

Applications portal
You can install IBM Cognos TM1 Performance Modeler the first time you run the component from the IBM
Cognos TM1 Applications portal.

Before you begin

Before you install Cognos TM1 Performance Modeler from the Cognos TM1 Applications portal, the
administrator must install Cognos TM1 Applications.

Procedure
1. In a web browser, type the Cognos TM1 Applications portal URI:
For example, [Link]
a) Replace localhost with the name of the computer where the Cognos TM1 Application Server is
installed.
b) If required, change the port number if you used a different value in IBM Cognos Configuration for
the TM1 Application Server Gateway URI property.

Chapter 9. Installing the Rich Tier 143

 2. From the Cognos TM1 Applications portal, click the Open Performance Modeler icon.
If this is the first time you have used Cognos TM1 Performance Modeler, the Install Now icon displays
to indicate that you are about to install the Cognos TM1 Performance Modeler client to your computer.
3. Click Install Now.
4. Click Finish to complete the installation.

What to do next
For information on using IBM Cognos TM1 Performance Modeler, see the TM1 Performance Modeler
documentation.

Remotely installing Cognos TM1 Performance Modeler on multiple

computers
As an administrator, you can push the IBM Cognos TM1 Performance Modeler installation to users
automatically. First, you make the Cognos TM1 Performance Modeler installer file available in a shared
folder on your network. You can then use an application such as Microsoft Active Directory to
automatically install the client application to authenticated users.

About this task

Cognos TM1 Performance Modeler is installed using an installer file that you put in a shared location. You
can use Active Directory to install Cognos TM1 Performance Modeler directly to users' computers.
Use the [Link] file to install Cognos TM1 Performance Modeler. This file is installed
to the following location when you install the Cognos TM1 Application Gateway component:
tm1 location\webapps\pmpsvc\rcp_installs
You can use the [Link] file with Windows Installer command line options and also
use Active Directory or other software management tools to push the install out to remote computers.
The [Link] file is a standard Microsoft Windows Installer file. You can use the
[Link] file with Windows Installer command line options and also use Active
Directory or other software management tools to push the install out to remote computers.
The following table lists some of the property values that administrators can use to install the
[Link] file. For complete details, see the Microsoft developer web site for
documentation about the "Windows Installer Guide" and "Windows Installer Property Reference".

Table 20. Property values for Cognos TM1 Performance Modeler

Property Property Value Description
ALLUSERS 1 Installs Cognos TM1 Performance Modeler for all
users.
This property value ensures that the registry
entries for Cognos TM1 Performance Modeler are
located in HKEY_LOCAL_MACHINE.
Note : You must use this property with the
TARGETDIR property.

ALLUSERS "" (default value) Installs Cognos TM1 Performance Modeler only for
the user who is running the installation. Only that
user will have access to the application.

144 IBM Planning Analytics: Installation and Configuration

 Table 20. Property values for Cognos TM1 Performance Modeler (continued)
Property Property Value Description
TARGETDIR "Performance Specifies the installation location for Cognos TM1
Modeler_install location" Performance Modeler.
For example, TARGETDIR="C:\Program Files"

TARGETDIR "" (default value) Sets the installation location for Cognos TM1
Performance Modeler when TARGETDIR is not
specified and ALLUSERS is specified as follows:
When used with ALLUSERS="":
On Windows 7, the installation location is
C:\Users\username\AppData\Roaming\IBM
\Cognos TM1 Performance Modeler
When used with ALLUSERS=1:
On Windows 7, the installation location is
C:\Program Data\IBM\Cognos TM1
Performance Modeler

NOUPDATE Yes Prevents Cognos TM1 Performance Modeler users

from receiving automatic updates.
This value is recommended when end users do not
have write access to the application installation
location. Auto-updating requires that Cognos TM1
Performance Modeler users can write to the
location specified, or defaulted to, by the
TARGETDIR property.

NOUPDATE No (default value) Allows Cognos TM1 Performance Modeler users to

receive automatic updates.

An example is shown in the following steps.

Procedure
1. Open a command prompt, and navigate to the location of the [Link] file.
2. To install Cognos TM1 Performance Modeler for all users, type the following command

[Link] TARGETDIR="install_location" ALLUSERS=1

Configuring logging for Cognos TM1 Performance Modeler

You can enable logging for IBM Cognos TM1 Performance Modeler using the same logging framework as
other components in IBM Cognos TM1.

Procedure
1. Locate the provagent_NOT.ini and rename the file to [Link].
This file is located here:
C:\Users\<user_name>\AppData\Roaming\IBM\Cognos Performance Modeler
2. Edit the [Link] to uncomment the following line.
Change #app-debug=true to app-debug=true.

Chapter 9. Installing the Rich Tier 145

 3. In this same directory location, open and edit the [Link] file to configure logging.
Note : By default, logging is configured to log ERROR level messages for day-to-day purposes and
typically does not need to be adjusted. This can be changed to WARNING, INFO, or DEBUG level
messages to get varying levels of logging information. Work with IBM Customer Support to change the
logging configuration to record more specific messages.

Results
Log files are typically written out to the following location:
%appdata%/IBM/application_name/logs

Installing Cognos TM1 Perspectives

You can install IBM Cognos TM1 Perspectives, which is an add-in for Microsoft Excel.

Before you begin

Before you install IBM Cognos TM1 Perspectives, complete the following tasks:
1. Install the software that is necessary for you to run Cognos TM1 Perspectives. For more information,
see “Install the prerequisite software” on page 81.
2. Ensure that the Cognos TM1 Admin Server and the Cognos TM1 Server that you want to connect to are
running on an accessible computer in your network. For details, see “TM1 Server installation” on page
89.
3. Ensure that users have access to the Cognos TM1 servers that they need to use running under that
Cognos TM1 Admin Server. As a Cognos TM1 administrator, you must set up a user name and
password for each user before a user can access that server.

About this task

The following steps install Cognos TM1 Perspectives on a single computer, configure it to locate a Cognos
TM1 Administration Server on your network, and then connect to a server. You can also create an
unattended installation.
Attention : If you are upgrading and leave your old [Link] client configuration files in place,
you might need to update the directory path in the file for the AdminSvrSSLCertAuthority
parameter. For example, if you are using the default Cognos TM1 SSL certificate, manually change
the value for this parameter to the new install path C:\Program Files\IBM\cognos
\tm1_64\bin64\ssl\[Link].

Procedure
1. Install Cognos TM1 Perspectives:
a) Right-click the [Link] file and click Run as Administrator.
b) On the Component Selection page, expand TM1 Rich Tier, and select the TM1 Perspectives check
box.
Leave all the other check boxes unselected.
c) Follow the prompts and click Finish to complete the installation.
2. Run Cognos TM1 Perspectives:
a) Click Start > IBM Cognos TM1 > Perspectives for MS Excel.
If the component does not start, ensure that the servers you started with Cognos Configuration are
still running.
b) Click Enable Macros when the security warning displays.
3. Configure Cognos TM1 Perspectives to locate a Cognos TM1 Admin Server:

146 IBM Planning Analytics: Installation and Configuration

 a) In Microsoft Excel, click TM1 > Options.
The TM1 Options dialog box opens.
b) In the Admin Host field, specify the name of the computer on which the Cognos TM1 Admin Server
is running. If you want to access servers registered on different Admin Servers, use a semicolon to
separate the name of each Admin Host. You must enter a name, not an IP address, in the Admin
Host field.
c) Click OK.
d) When prompted about disconnecting from currently accessed servers, click Yes if you want to
access a new list of servers. Servers available through Admin Server on the specified Admin Host
appear. If you want to continue to see the current list of remote servers during this session, click
No.
4. Launch Server Explorer.
5. Double-click a Cognos TM1 Server to log in.
For either Planning Sample or SData, use these login credentials:
• User name: admin
• Password: apple
Tip : To load Cognos TM1 Perspectives automatically whenever you start Microsoft Excel, add
TM1_location/[Link] to Microsoft Excel's add-in tool list. The default location is C:\Program
Files\IBM\cognos\tm1_64\bin64\. After completing this step, "TM1" displays on the Microsoft
Excel menu bar.
6. If you want to install Cognos TM1 Perspectives on multiple computers, use the previous steps to
create an unattended installation that can. For details, see “Setting up unattended installations and
configurations” on page 315.

Installing Cognos Insight

You can choose different ways to distribute and install IBM Cognos Insight across multiple computers.
Depending on your computer network environment and business needs, you can install the application,
allow users to install as needed, or remotely push the application out.
The following table summarizes the different ways to distribute and install IBM Cognos Insight across
multiple computers.

Table 21. Multiple computer installation options for Cognos Insight

Installation option Description

“Installing Cognos Insight using the Administrators or end users can install Cognos Insight on a
installation program” on page 148 single computer using the IBM Cognos TM1 Client-only
installation program.
Optionally, use these steps to create an unattended
installation to install Cognos Insight on multiple computers.

“Installing Cognos Insight from the As a prerequisite, an administrator must install Cognos TM1
Cognos TM1 Applications portal” on Applications.
page 148
This allows Cognos TM1 users to install Cognos Insight onto
their computers the first time that they launch it from the IBM
Cognos TM1 Applications portal. This is called a provisioned
installation.

“Remotely installing Cognos Insight on An administrator can use third-party network installation tools
multiple computers” on page 149 to push Cognos Insight out to multiple remote client systems.

Chapter 9. Installing the Rich Tier 147

Installing Cognos Insight using the installation program
You can interactively install a stand-alone version of IBM Cognos Insight on one or more computers.

Procedure
1. On Microsoft Windows, right-click the [Link] file and click Run as Administrator.
2. On the Component Selection page, expand TM1 Rich Tier and select the Cognos Insight check box.
Leave all the other check boxes unselected.
3. Follow the prompts and click Finish to complete the installation.
4. To test the installation, open Cognos Insight from Start > Programs > IBM Cognos Insight > IBM
Cognos Insight.
5. To install the program on multiple computers, use the previous steps to create an unattended
installation. For details, see “Setting up unattended installations and configurations” on page 315.

Installing Cognos Insight from the Cognos TM1 Applications portal

You can install IBM Cognos Insight the first time you run the component from the toolbar of the IBM
Cognos TM1 Applications portal.

Before you begin

Before you install Cognos Insight from Cognos TM1 Applications, the administrator must install Cognos
TM1 Applications.

Procedure
1. In a web browser, type the Cognos TM1 Applications portal URI:
For example, [Link]
a) Replace localhost with the name of the computer where the Cognos TM1 Applications Portal is
installed.
b) If required, change the port number if you used a different value in IBM Cognos Configuration for
the TM1 Application Gateway URI property.

2. From the Cognos TM1 Applications portal, click the Open IBM Cognos Insight icon .
If this is the first time you have used Cognos Insight, the Install Now icon displays to indicate that you
are about to install the Cognos Insight client to your computer.
3. Click Install Now.
4. Click Finish to complete the installation.

What to do next
Cognos Insight is now installed in a folder on your computer. You will be able to run and use Cognos
Insight in the following ways:

• You can launch Cognos Insight using the Open Cognos Insight icon in Cognos TM1 Applications.
• You can launch the Cognos Insight client by right-clicking a node of an application that has been
configured to use Cognos Insight.
Cognos Insight is available as a client from an application only if you configured the client environment
for Cognos TM1 Applications to use the Cognos Insight Connected client. For more information, see
“Configuring the server and client environment for TM1 Application Web” on page 121.
• You can launch Cognos Insight as a stand-alone product from the Windows Start > Programs > IBM
Cognos Insight menu.

148 IBM Planning Analytics: Installation and Configuration

Remotely installing Cognos Insight on multiple computers
As an administrator, you can push the IBM Cognos Insight installation to users automatically. First, you
make the Cognos Insight installer file available in a shared folder on your network. Then, you can use an
application such as Microsoft Active Directory to directly install the client application to authenticated
users.

About this task

Cognos Insight is installed by using the [Link] file that you put in a shared location. This
file is installed to the following location when you install the IBM Cognos TM1 Application Gateway
component:
tm1 location\webapps\pmpsvc\rcp_installs
The [Link] file is a standard Microsoft Windows Installer file. You can use the
[Link] file with Windows Installer command line options and also use Active Directory or
other software management tools to push the install out to remote computers.
The format for the command is the Cognos Insight MSI file name followed by the property values. For
example, you could enter [Link] TARGETDIR="C:\Program Files" USERDATADIR=
%%USERNAME%%.
You can use the following property values alone or in combination with each other.

Table 22. Property values for Cognos Insight

Property Property Value Description
ALLUSERS 1 Installs Cognos Insight for all users.
Setting this property value sets the default
installation location to C:\Program
Files.

ALLUSERS "" (default value) Installs Cognos Insight only for the user
who is running the installation. Only that
user will have access to the application.
Setting ALLUSERS="" or omitting the
ALLUSERS property installs Cognos Insight
in the user's context, and sets the
TARGETDIR property to C:\Users
\username\AppData\Local\Programs
\IBM\Cognos Insight.

TARGETDIR "Cognos_Insight_install_location" Specifies the installation location for

Cognos Insight.
For example, TARGETDIR="C:\Program
Files"

Chapter 9. Installing the Rich Tier 149

 Table 22. Property values for Cognos Insight (continued)
Property Property Value Description
TARGETDIR (default value) Sets the installation location for Cognos
Insight when TARGETDIR is not specified
and ALLUSERS is specified as follows:
When used with ALLUSERS="":
On a Microsoft Windows 7 operating
system, the installation location is
C:\Users\username\AppData\Local
\Programs
When used with ALLUSERS="1":
On a 64-bit Microsoft Windows operating
system, the installation location is
C:\Program Files (x86)

NOUPDATE Yes Prevents Cognos Insight users from

receiving automatic updates.
This value is recommended when users do
not have write access to the application
installation location. Automatic updates
require that Cognos Insight users can write
to the installation location specified by the
TARGETDIR property.

NOUPDATE No (default value) Allows Cognos Insight users to receive

automatic updates.
USERDATADIR "location" Specifies the location for
the .CognosInsight folder.
The .CognosInsight folder contains
Cognos Insight themes, IBM Cognos TM1
data that is copied to your computer when
you work from a Cognos TM1 server, and
the thumbnail graphics of recent
workspaces that appear on the Getting
Started page of Cognos Insight.
USERDATADIR "" (default value) When USERDATADIR is not specified,
the .CognosInsight folder is located in
C:\Users\username\.CognosInsight.
When ALLUSERS=1, and you want to
specify the USERDATADIR, the
USERDATADIR property should include an
environment variable that will resolve
differently for each user.
For example, the command
[Link] ALLUSERS=1
USERDATADIR=^%USERPROFILE^%
specifies that Cognos Insight be installed
at C:\Program Files and that
the .CognosInsight folder be installed in
each user's user profile folder.

150 IBM Planning Analytics: Installation and Configuration

 For complete details, see the Microsoft developer website for documentation about the Microsoft
Windows Installer Guide and Microsoft Windows Installer Property Reference.
An example is shown in the following steps.

Procedure
1. Open a command prompt, and navigate to the location of the [Link] file.
2. To install Cognos Insight for all users, type the following command

[Link] TARGETDIR="install_location" ALLUSERS=1

Configuring Cognos TM1 TurboIntegrator function security in Cognos Insight

When you open an IBM Cognos Insight workspace that has been shared through IBM Cognos Connection,
you might want to restrict the execution of some TurboIntegrator functions, especially functions that can
destroy or modify data files.
Several TurboIntegrator functions exist that can write files, delete files, and execute commands. When
you receive a shared Insight workspace, it is possible that TurboIntegrator processes within the
workspace might include functions that perform undesirable actions. To prevent processes from
performing potentially harmful actions, your Insight installation includes a configuration file that is named
[Link], which can be used to prevent or restrict the execution of TurboIntegrator functions.
Any TurboIntegrator function can be entirely prevented from executing. The ASCIIOutput,
TextOutput, and ASCIIDelete functions can also be configured to run in restricted mode. When a
function runs in restricted mode, it is limited to acting upon files within the TM1 server data directory and
its subdirectories.
When you install IBM Cognos Insight, a default version of the [Link] file is created in
<pa_install_directory>\tm1_64\coginsight\bins\bin_10.3.1.1514\tm1\bin. You can
modify this configuration file to further restrict function execution or allow function execution.
The default version of the [Link] file appears as follows:

ExecuteCommand=0
AsciiOutput=1
TextOutput=1
AsciiDelete=1

When a function is set to 0 in [Link], the function is prevented from executing. Any attempt
to execute that function causes TurboIntegrator to throw a security exception.
When a function is set to 1 in [Link], the function runs in restricted mode. Only the
ASCIIOutput, TextOutput, and ASCIIDelete functions can be set to run in restricted mode.
When a function is not present in [Link], it runs completely unrestricted.

Examples of functions running in restricted mode

When a function is configured to run in restricted mode, any relative path passed as an argument to the
function is assumed to be rooted in the TM1 server data directory and is allowed. Any absolute path to a
directory above the TM1 server data directory prevents the function from executing and causes a security
exception to be thrown at runtime.

Editing the [Link] file

1. Open the [Link] file in a text editor.
2. To completely prevent a function from executing, set the function name to 0. For example,
ExecuteCommand=0 or ServerShutdown=0.

Chapter 9. Installing the Rich Tier 151

 3. To allow a function to run in restricted mode, set the function name to 1. For example,
AsciiDelete=[Link] the ASCIIOutput, TextOutput, and ASCIIDelete functions can be set to
run in restricted mode.
4. To allow a function to run unimpeded, delete the function name from the [Link] file.
5. Save and close the [Link] file.

Example 1
Assume AsciiDelete=1 in [Link]. In this case, the function
ASCIIDelete(‘logs\[Link]');
is allowed and deletes the file [Link] from the logs subdirectory of the TM1 server data directory.
However, the function
ASCIIDelete(‘c:\[Link]');
will not execute and will cause a security exception because it specifies a file at the root level of the drive,
which is above the TM1 server data directory.

Example 2
Assume TextOutput=1 in [Link]. In this case, the function
TextOutput(‘logs\[Link]', ‘this is sample text');
is allowed and writes a string to the [Link] file in the logs subdirectory of the TM1 server data
directory.
Conversely, the function
TextOutput(‘c:\[Link]', ‘del *.* -r –f');
is not allowed due to the path being specified at the root level of the drive. This function will cause a
security exception to be thrown at runtime.

Configuring logging for Cognos Insight

You can enable logging for IBM Cognos Insight using the same logging framework as other components in
IBM Cognos TM1.

Procedure
1. Locate the provagent_NOT.ini and rename the file to [Link].
This file is located here:
C:\Users\<user_name>\AppData\Local\Programs\IBM\Cognos Insight
2. Edit the [Link] to uncomment the following line:
Change #app-debug=true to app-debug=true.
3. In this same directory location, open and edit the [Link] file to configure logging.
Note : By default, logging is configured to log ERROR level messages for day-to-day purposes and
typically does not need to be adjusted. This can be changed to WARNING, INFO, or DEBUG level
messages to get varying levels of logging information. Work with IBM Customer Support to change the
logging configuration to record more specific messages.

Results
Log files are typically written out to the following location:
%appdata%/IBM/application_name/logs

152 IBM Planning Analytics: Installation and Configuration

Installing Cognos TM1 APIs
Use the TM1 API installation option to install the required files that enable programmers to work with the
Cognos TM1 application programming interfaces (APIs). This installation option can also be installed on
Cognos Analytics servers to enable Cognos Analytics reporting against Cognos TM1 data sources.

About this task

This option installs files for the following Cognos TM1 APIs:
TM1 API
Allows developers to create custom C, C++, and VB applications that interact with TM1.
TM1 Java API
Allows developers to create custom Java applications that interact with TM1.
TM1 .NET API
Allows developers to create custom Microsoft .NET applications that interact with TM1.
Attention : For information about using the TM1 APIs to enable Cognos Analytics reporting against
Cognos TM1 data sources, see “TM1 as a datasource with Cognos Analytics” on page 240.

Procedure
1. Right-click the [Link] file and click Run as Administrator to run either the full IBM Planning
Analytics installation program or the client-only installation program:
2. Select the installation location on the Installation Location page:
• If you are planning on using the TM1 APIs for programming, accept the default installation.
• If you are using the TM1 APIs to enable Cognos Analytics reporting against Cognos TM1 data
sources, select an adjacent directory on the Cognos Analytics server that is running report services
on Microsoft Windows.
3. On the Component Selection page:
a) Expand the TM1 Client Tier and select the TM1 APIs option.
b) Clear the check boxes for all the other components.
4. Follow the prompts and click Finish to complete the installation.

Chapter 9. Installing the Rich Tier 153

154 IBM Planning Analytics: Installation and Configuration
Chapter 10. Installing Planning Analytics Workspace
Local
IBM Planning Analytics Workspace Local is a web-based interface for IBM Planning Analytics. It provides
an interface to TM1 databases, with ways to plan, create, and analyze your content.
In IBM Planning Analytics Workspace Local version 2.0.44 or later, it is much simpler to install on
Windows Server 2016. When you run the start.ps1 script, validation checks run automatically and the
host server is repaired if possible. The script checks your Windows Server version, prerequisite software,
network configuration, and free ports. It also checks for unsupported anti-virus software that conflicts
with Planning Analytics Workspace Local. You can jump directly to “Install Planning Analytics Workspace
Local on Windows Server 2016” on page 158.
In IBM Planning Analytics Workspace Local version 2.0.45 or later, it is also simpler to install on Red Hat
Enterprise Linux 7. When you run the [Link] script, validation checks run automatically and Docker
container runtime for RHEL 7 is installed. You can jump directly to “Install Planning Analytics Workspace
Local on Red Hat Enterprise Linux 7” on page 160.
For information about Planning Analytics Workspace, see the Planning Analytics Workspace
documentation.

Planning Analytics Workspace Local architecture

IBM Planning Analytics Workspace Local can be co-located with IBM Planning Analytics Local or it can be
installed on its own dedicated server. Installing Planning Analytics Workspace on its own server is
recommended. In both cases, Planning Analytics Workspace must connect to the TM1 databases in your
Planning Analytics Local system and to an authentication system.
The following diagram shows where Planning Analytics Workspace fits into your Planning Analytics Local
architecture:

© Copyright IBM Corp. 2007, 2021 155

 Users in Planning Analytics Workspace
The first user that logs in to IBM Planning Analytics Workspace is given the administrator role. Users that
log in after the first user are given the analyst role.
For more information about managing users, see the Planning Analytics Workspace documentation.

Authentication modes
You can use a TM1 Server configured in any authentication mode to authenticate Planning Analytics
Workspace users.

Prerequisites
Before you install IBM Planning Analytics Workspace, you must install IBM Planning Analytics Local
version 2.0.0 or later.
Important : To review an up-to-date list of operating systems supported by IBM Planning Analytics Local,
create a detailed system requirements report by using the Software Product Compatibility Reports tool
([Link]
Planning Analytics Workspace is included as part of IBM Planning Analytics Local. For more information,
see the IBM Planning Analytics Local download document for instructions.
If you are using IBM Cognos Analytics as your authentication provider, then you must have IBM Cognos
Analytics 10.2.2 or later installed.
Planning Analytics Workspace communicates with TM1 servers by using the TM1 REST API. In the
[Link] file for all TM1 Servers, set the HTTPPortNumber property to a free port on the server.
The following list contains information about requirements and the installation kit name for different
operating systems that are supported by Planning Analytics Workspace.
Microsoft Windows Server 2016
• The installation kit is ipa_workspace_local_win_<version>.zip.
• When you run the start.ps1 script, validation checks run automatically and the host server is
repaired if possible. The script checks your Windows Server version, prerequisite software, network
configuration, and free ports. It also checks for unsupported anti-virus software that conflicts with
Planning Analytics Workspace Local. You can jump directly to “Install Planning Analytics Workspace
Local on Windows Server 2016” on page 158.
• Docker runs on a physical Microsoft Windows Server 2016 or a VM with Microsoft Windows Server
2016 running under VMware or Microsoft Hyper-V..
• You must have at least 100 GB of free space on the C:\ drive for Microsoft Windows Server 2016. By
default, Docker stores its images and containers in C:\ProgramData\Docker. You can configure
Docker to store its data on another drive. For more information, see Configure Docker with a
configuration file on the Docker documentation website ([Link]
virtualization/windowscontainers/manage-docker/configure-docker-daemon#configure-docker-
with-a-configuration-file).

Red Hat Enterprise Linux 7

• The installation kit is ipa_workspace_local_<version>.zip.
• When you run the [Link] script, validation checks run automatically and Docker container
runtime for RHEL 7 is installed. You can jump directly to “Install Planning Analytics Workspace Local
on Red Hat Enterprise Linux 7” on page 160.
• For all currently supported Linux distributions, overlay2 is the preferred storage driver and
requires no extra configuration. For more information, see Docker storage drivers at https://
[Link]/storage/storagedriver/select-storage-driver/.

156 IBM Planning Analytics: Installation and Configuration

 • Storage requirements can vary, you need at least 100 GB for the /var/lib/docker directory and
sufficient space for at least two Planning Analytics Workspace installation packages wherever you
choose to install them.

Community Enterprise Operating System (CentOS)

CentOS is a free, community-supported, open source Linux distribution.
Planning Analytics Workspace Local on CentOS needs Docker Community Edition.
Docker Community Edition (CE) is free for anyone to use.
For more information, see Docker Engine - Community.

Free ports
The following ports are required for Planning Analytics Workspace Local.

Port Protocols Description

80 TCP The PAGatewayHTTPPort is an
HTTP port that is mapped to the
host by pa-gateway. The default
value is 80.
443 TCP The PAGatewayHTTPSPort is an
HTTPS port that is mapped to the
host by pa-gateway. The default
value is 443.
9012 TCP To use IBM Planning Analytics
Administration on Planning
Analytics Workspace Local, you
install and configure the Planning
Analytics Administration agent
wherever you install IBM TM1
Server. The default port of the
Planning Analytics Administration
agent is 9012.

Chapter 10. Installing Planning Analytics Workspace Local 157

 Port Protocols Description
8888 TCP By default, the Planning Analytics
Workspace administration tool is
accessible on http://
[Link]:8888.
In IBM Planning Analytics
Workspace Local version 2.0.44
or later, if port 8888 is not free,
you can configure Planning
Analytics Workspace Local to
access the Planning Analytics
Workspace administration tool
remotely on Windows Server. For
more information, see “Access
the Planning Analytics
Workspace administration tool
remotely on Windows Server” on
page 169.
If you can't run a browser on the
localhost interface, you can
configure Planning Analytics
Workspace Local to access the
Planning Analytics Workspace
administration tool on another IP
address. For more information,
see “Access the Planning
Analytics Workspace
administration tool remotely on
Linux” on page 170.

Install Planning Analytics Workspace Local on Windows Server

2016
Improved v2.0.44 To install Planning Analytics Workspace Local version 2.0.44 or later directly on
Windows Server 2016, run the ./Start.ps1 script.

About this task

In Planning Analytics Workspace Local version 2.0.44 or later, configuration parameters control whether
validation checks are performed automatically when you install Planning Analytics Workspace Local on
Windows Server 2016.
VALIDATE_HOST
Indicates whether to perform host validation and repair.
Set to "true" to validate until Start.ps1 is successful and then don't validate when Start.ps1 is
run again. The default is "true".
Set to "always" to always validate.
Set to "false" to never validate.
Host validation runs as the first step of executing the Start.ps1 script. Successful validation is
marked by writing the config/HostValidated file with the current time stamp. If
$env:VALIDATE_HOST is true, validation is skipped if the confing/HostValidated file exists. If
you are upgrading, validation is performed because that file is absent in the new kit.

158 IBM Planning Analytics: Installation and Configuration

VALIDATE_ANTI_VIRUS
Indicates whether to check for unsupported anti-virus software while validating the host. If anti-virus
software is found, the validation process fails.
Set to "true" to check for anti-virus software. The default is "true".
Set to "false" to skip checks for anti-virus software.
FREE_SPACE_REQUIRED_GB
Indicates how much free space is required (in GB) before you are notified that it might be insufficient.
Set to "0" to suppress warning messages.
Default is "50".
If free space is below this value, the script warns you but continues to load images because it is
difficult to know how much space is required for the images. This check is done outside of the main
container host validation because it is related to image loading instead, and it is not controlled by the
$env:VALIDATE_HOST setting.
The start script performs the following checks:
1. Checks that you are running the Start.ps1 script as an administrator. If the PowerShell is not
running elevated, the script does not run.
2. Verifies the version of Windows Server 2016 is supported. Currently, only Windows Server 2016 LTSC
(Long-Term Servicing Channel) is supported.
3. Checks for unsupported anti-virus software installed. If the script finds any unsupported software, it
displays an error and exits. You must uninstall the anti-virus software and run the script again.
4. Checks to make sure that the required modules, such as HostNetworkingService PowerShell, and
features, such as Hyper-V PowerShell and Containers, are installed and configured correctly on the
server. If it can, the script installs the required software or updates the configuration.
5. Checks for an existing version of Docker and validates that it is a supported version. Verifies that the
Docker service exists and is configured as Automatic (Delayed Start). If a Docker service doesn't
exist, the script extracts the Docker .zip file that is bundled with Planning Analytics Workspace into
the C:\Program Files directory. Then, it appends the folder to the system PATH environment
variable and registers the Docker service.
6. Checks that the Docker service is running, the [Link] is on the PATH, and Docker is registered in
the EventLog service. If the state of the service is not "Running", the script starts it. If it fails to start,
the script displays an error and exits. If it is not on the PATH, it automatically adds it. If the service is
not registered, it is repaired.
7. Verifies permission to use the Docker daemon.
8. Checks that [Link] is installed. If [Link] is not found on the PATH, the
script copies it from the Planning Analytics Workspace installation location to C:\Program Files
\docker\[Link].
9. Validates that Windows container settings are correct and updates any that are required.
10. Checks that there are free ports available. Ensures that the defined Planning Analytics Workspace
ports (80 and 443 by default) are free. If the pa-gateway container is running, these tests are not run.
11. Checks that there is sufficient space to install the required software. First, it reads the currently
configured Docker storage directory. Then, it fetches the free space on its drive and converts it to GB.
It outputs the amount of free space on the drive. If the free space is less than
$env:FREE_SPACE_REQUIRED_GB, a warning is displayed that indicates you might have insufficient
space to load the images. A link is displayed where you can read how to switch the "Docker Root Dir"
to another drive.
12. Installs the Planning Analytics Workspace Docker images.
13. Opens the Planning Analytics Workspace administration tool.
Any check that results in an unrepairable error causes the script to exit and the following message to be
displayed:

Chapter 10. Installing Planning Analytics Workspace Local 159

 Run Start.ps1 again to revalidate your system after resolving the identified
issues.
Follow these steps to install Planning Analytics Workspace Local.

Procedure
1. Open a PowerShell terminal window, go to the directory where you extracted the installation kit, and
type the following command:

./Start.ps1

2. Install the software that the validation requires and then restart your server. After a restart, run ./
Start.ps1 to continue the validation and installation.
Note : The first time that you run the start script, it automatically installs the Docker images. The next
time that you run the start script, you can skip installing or updating the Docker images and go straight
into the administration tool.
3. Reply "y" when you are asked whether you want to start the administration tool.
The Planning Analytics Workspace administration tool opens in your browser.
Note : Keep the command or terminal window open. Closing the window stops the administration tool.

What to do next
• If there are any warnings or errors that can't be resolved, view container host validation errors in the
log\[Link] file. View Windows event logs in the .log\docker_event_logs.csv file.
• If the administration tool doesn't open, copy and paste the address shown in the command or terminal
window into a browser window.
• If you are using a Mongo database on a system that is running Planning Analytics Workspace on
Windows Server 2016, you must add the shutdown.ps1 script to your Windows Settings > Scripts
(Startup/Shutdown) > PowerShell Scripts configuration. For more information, see “Shut down
MongoDB cleanly on Windows Server 2016” on page 169.
• If you have other issues when you connect to Planning Analytics Workspace, see “How do I fix my
Planning Analytics Workspace Local installation?” on page 402

Install Planning Analytics Workspace Local on Red Hat Enterprise

Linux 7
Improved v2.0.45 To install Planning Analytics Workspace Local version 2.0.45 or later directly on Red
Hat Enterprise Linux 7, run the ./[Link] script.

About this task

The start script performs the following checks:
1. Checks the /etc/redhat-release directory to see if Docker is found on this path. If Docker is not
found, the script tries to install it.
2. Verifies the version of Linux is Red Hat Enterprise Linux 7. If it is RHEL 8, the script prints a message
stating that Docker Enterprise Edition must be installed or you can install IBM Planning Analytics
Workspace Distributed with Kubernetes instead.
3. If the Docker package is available, the script continues. Otherwise, if this Red Hat system is not
registered with the Red Hat subscription manager, the script displays an error and exits.
4. If this Red Hat system is subscribed, the script completes the following steps:
• Installs the Docker package. Planning Analytics Workspace ships with docker-compose. The script
appends the Planning Analytics Workspace software directory to the PATH variable.

160 IBM Planning Analytics: Installation and Configuration

 • Adds the Docker group.
• Adds the user to the Docker group.
• Starts the Docker service.
• Configures the Docker service to start on reboot.
• Prints the Docker version to the terminal window.
• Prints a success message and tells you that you must log off and log on again to the group
membership to take effect.
5. Opens the Planning Analytics Workspace administration tool.
Follow these steps to install Planning Analytics Workspace Local.

Procedure
1. Open a terminal window, go to the directory where you extracted the installation kit, and type the
following command:

./[Link]

Note : The first time you run the start script, it automatically installs the Docker images. The next time
you run the start script, you can skip installing or updating the Docker images and go straight into the
administration tool.
2. Reply "y" when you are asked if you want to start the administration tool.
The Planning Analytics Workspace administration tool opens in your browser.
Note : Keep the command or terminal window open. Closing the window stops the administration tool.

What to do next
If the administration tool doesn't open, copy and paste the address shown in the command or terminal
window into a browser window. If you have issues connecting to Planning Analytics Workspace on Linux
OS, see:
• “Run the Planning Analytics Workspace administration tool from the command line on Linux” on page
169
• “Access the Planning Analytics Workspace administration tool remotely on Linux” on page 170

Configuring Planning Analytics Workspace Local

Perform administration tasks to monitor, configure, and upgrade Planning Analytics Workspace Local.

Configure parameters
You can change the configuration of Planning Analytics Workspace Local by modifying a paw configuration
file.
Note : When you change the paw configuration file, you must run ./scripts/paw for your operating
system or click Start in the Planning Analytics Workspace administration tool for your changes to take
effect. Only services that are affected by the configuration change will restart.
Important : Do not change the values in defaults.ps1. Use paw.ps1 to override a value in
defaults.ps1.
Do not change the values in [Link]. Use [Link] to override a value in [Link].
The default values for the configuration parameters are stored in defaults.ps1 for the Microsoft
Windows operating system and [Link] for Linux. If you want to change any of the parameters,
open the paw.ps1 file or [Link] in a text editor, and add the parameters. If a parameter is specified in
paw.ps1 or [Link], the value in paw.ps1 or [Link] overrides the value in defaults.ps1 or
[Link].

Chapter 10. Installing Planning Analytics Workspace Local 161

 Tip : When you specify a parameter in paw.ps1, use the format that is shown in defaults.ps1. When
you specify a parameter in [Link], use the format that is shown in [Link]. Some parameters
are specified with quotation marks and some are not, depending on your operating system.
The following list describes the parameters in [Link] and defaults.ps1.
ADMINTOOL_PORT Added in v2.0.44
In IBM Planning Analytics Workspace Local version 2.0.44 or later, you can access the Planning
Analytics Workspace administration tool remotely on Windows Server by specifying the
ADMINTOOL_PORT environment variable in the config/paw.ps1 file.
For example:

$env:ADMINTOOL_PORT="8888"

This configuration parameter applies to Planning Analytics Workspace Local installed on a Windows
Server only.
API_ALLOW_ORIGINS Added in v2.0.46
This parameter allows cross-origins to access API endpoints. Set to a space-separated list of
domains. You can use * for global matching. By default, only same-origin is allowed. For example,

API_ALLOW_ORIGINS="*.[Link] [Link]

This parameter is required to embed URL links to Planning Analytics Workspace within an iframe in
another product such as IBM Cognos Analytics. This technique is an example of Cross-Origin
Resource Sharing (CORS).
For more information, see Access-Control-Allow-Origin and Same-origin policy.
CSP_FRAME_ANCESTORS Added in v2.0.46
This parameter enables the HTTP Content Security Policy frame-ancestors directive. Enter values as
the list of valid parent frame sources separated by a space. The default is self.
This parameter is required to embed URL links to Planning Analytics Workspace within an iframe in
another product such as IBM Cognos Analytics. This technique is an example of Cross-Origin
Resource Sharing (CORS).
For more information, see CSP: frame-ancestors.
EnableIPv6
Flag to enable IPV6 on the bridge network. Value is false.
ENABLE_INTENT_BAR
Set to false to disable the natural language search on the intent bar. You might want to set this
parameter to false to avoid long running search processes that are created with the intent bar.
Default is True.
ENABLE_PASTE_SPECIAL
Set to true to enable mixed cell paste. For more information, see Paste values to a mixed range of
leaves and consolidated cells ([Link]
[Link].tm1_prism_gs.[Link]/c_paw_paste_special.html).
Default is False.
EnableSSL
Set to true if you are using SSL. Default is false. Leave all other SSL options at default values if you
want to run by using a self-signed test certificate.
ENABLE_USER_IMPORT
Default is true.
If set to true, when a user logs in, they are immediately added as a user in Planning Analytics
Workspace. When this parameter is set to true, you cannot activate, deactivate, or delete users from
the Administer page of Planning Analytics Workspace.
If set to false, a user must first be added to Planning Analytics Workspace before they can log in to
Planning Analytics Workspace. If a user has not been added and tries to log in, they see an error

162 IBM Planning Analytics: Installation and Configuration

 message. Users are added by an administrator. For more information, see Add users (https://
[Link]/support/knowledgecenter/SSD29G_2.0.0/
[Link].tm1_prism_gs.[Link]/t_prism_administer.html).
When this parameter is set to false, an administrator can activate, deactivate, and delete users. For
more information, see Activate or deactivate a user ([Link]
SSD29G_2.0.0/[Link].tm1_prism_gs.[Link]/
t_paw_activate_deactivate_users_locally.html) and Delete a user ([Link]
knowledgecenter/SSD29G_2.0.0/[Link].tm1_prism_gs.[Link]/
t_paw_delete_users_locally.html).
ENABLE_VIEW_EXCHANGE Added in v2.0.44
Set to true to enable Exploration View exchanges between Planning Analytics Workspace and
Planning Analytics for Microsoft Excel in the Content Store.
For more information, see Save to the Planning Analytics Workspace Content Store(https://
[Link]/support/knowledgecenter/SSD29G_2.0.0/[Link].ug_cxr.[Link]/
t_pax_save_commonview.html).
Note : If you are using Planning Analytics for Microsoft Excel version 2.0.43 or earlier, setting this
parameter to true will prevent Planning Analytics for Microsoft Excel from connecting to TM1 and
authentication servers with security modes 2 or 3 enabled.
FREE_SPACE_REQUIRED_GB
Indicates how much free space is required (in GB) before you are notified that it might be insufficient.
Set to "0" to suppress warning messages.
Default is "50".
If free space is below this value, the script warns you but continues to load images because it is
difficult to know how much space is required for the images. This check is done outside of the main
container host validation because it is related to image loading instead, and it is not controlled by the
$env:VALIDATE_HOST setting.
LOG_DIR
Host directory for storing service logs. Ensure that services can create directories here. Value is log.
PAGatewayHTTPPort
HTTP port that is mapped to the host by pa-gateway. Value is 80.
PAGatewayHTTPSPort
HTTPS port that is mapped to the host by pa-gateway. Value is 443.
PAW_NET
Name of the PAW bridge network. Value is paw_net.
PAW_V6_SUBNET
IPV6 subnet for Docker containers. Value is fdfb:297:e511:0:d0c::/80.
ProxyTimeoutSeconds
Maximum number of seconds the gateway waits for a backend service response. Value is 120.
REGISTRY
Docker registry. Value is pa-docker:5000/planninganalytics.
ServerName
Domain name that is used to access Planning Analytics Workspace. This value is used by the gateway
as the redirect target for non-SSL requests. Value is pa-gateway.
SessionTimeout
The amount of time a Planning Analytics Workspace login session can go unused before it is no longer
valid. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or
seconds (s).
For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For
example, 1m30s is equivalent to 90 seconds.
Default is 60 minutes.
For example, export SessionTimeout="60m".

Chapter 10. Installing Planning Analytics Workspace Local 163

 SslCertificateFile
Path to a PEM-encoded file that contains the private key, server certificate, and optionally, the entire
certificate Trust Chain. Value is config/ssl/[Link] on Microsoft Windows Server
2016 OS or config/[Link] on Linux OS.
TM1APIPort
Port for the TM1 Admin Host. The value is empty, which means to use the default port.
TM1CredentialStoreKeyFile
Path to and name of the random credential store key, which is generated the first time that you start
Planning Analytics Workspace. Value is config/credential_store.key.
VALIDATE_HOST
Indicates whether to perform host validation and repair.
Set to "true" to validate until Start.ps1 is successful and then don't validate when Start.ps1 is
run again. The default is "true".
Set to "always" to always validate.
Set to "false" to never validate.
Host validation runs as the first step of executing the Start.ps1 script. Successful validation is
marked by writing the config/HostValidated file with the current time stamp. If
$env:VALIDATE_HOST is true, validation is skipped if the confing/HostValidated file exists. If
you are upgrading, validation is performed because that file is absent in the new kit.
VALIDATE_ANTI_VIRUS
Indicates whether to check for unsupported anti-virus software while validating the host. If anti-virus
software is found, the validation process fails.
Set to "true" to check for anti-virus software. The default is "true".
Set to "false" to skip checks for anti-virus software.
VIRTUAL_BOX_AS_SERVICE
If you are running the VM as a service using "VBoxVmService", set this parameter to true to suppress
scripts from probing or starting the VM by using VirtualBox tools. Value is false.
X_FRAME_OPTIONS Added in v2.0.46
This parameter enables the X-Frame-Options header as an alternative to Content-Security-Policy
(CSP) frame-ancestors for browsers that don't support CSP (Internet Explorer). The default is
sameorigin.
This parameter is required to embed URL links to Planning Analytics Workspace within an iframe in
another product such as IBM Cognos Analytics. This technique is an example of Cross-Origin
Resource Sharing (CORS).
For more information, see X-Frame-Options.
You configure the following values as part of the Planning Analytics Workspace installation process by
using the Planning Analytics Workspace administration tool. After the initial installation, you can change
these values by modifying the paw.ps1 or [Link] file in a text editor or through the Planning Analytics
Workspace administration tool. For more information about the Planning Analytics Workspace
administration tool, see “Connect to TM1 and authentication servers” on page 165.
CAMLoginNamespace
IBM Cognos Analytics CAM authentication namespace ID. Specify only when PAAuthMode = cam.
IBMCognosGateway
Gateway URI of the IBM Cognos Analytics server. Specify only when PAAuthMode = cam. To enable
SSO for Planning Analytics Workspace, you must enter a value in this field.
IBMCognosServlet
Dispatcher URI of your IBM Cognos Analytics server. Specify only when PAAuthMode = cam.
PAAuthMode
Supported authentication modes. Value must be cam for IBM Cognos Analytics security authentication
or tm1 for standard TM1 authentication.

164 IBM Planning Analytics: Installation and Configuration

 TM1ApplicationsLocation
URI of the TM1 Application Server. Value is [Link]
TM1Location
URI of the TM1 Admin Host. Value is [Link]
TM1LoginServerURL
URI of the TM1 server to be used for Planning Analytics Workspace authentication. Specify only when
PAAuthMode = tm1.

Connect to TM1 and authentication servers

You must use the Planning Analytics Workspace administration tool to configure the TM1 URIs that point
to the TM1 servers and authentication servers.

About this task

Use fully qualified host names or IP addresses for the URIs. Do not use localhost.
Important : If Planning Analytics Workspace is installed on a Microsoft Windows Server 2016 OS, then
you must access it from a different computer. This is a limitation of the Microsoft NAT network driver.
Here's a short video that shows how to do the configuration:
[Link]

Procedure
1. In the Planning Analytics Workspace administration tool on the Configuration tab, enter the following
server URIs:
TM1 Admin Server URI
You can specify multiple URIs. Separate each entry by a semi-colon. This is useful if your system
has redundant TM1 Admin Hosts or you have groups of servers managed by different Admin Hosts.
Note : The default value for the HTTPS REST API port is 5898, and 5895 for the HTTP REST API
port.
TM1 Application Server Gateway URI
The TM1 Application Gateway provides access to TM1 Applications.
2. Under Authentication Mode, select TM1 or CAM.
Choose TM1 if you're using standard TM1 authentication or Integrated Windows Authentication.
Choose CAM if you're using IBM Cognos security for authentication.
a) If you selected TM1, enter the value for the TM1 Login Server URI.
Planning Analytics Workspace users authenticate to the system by logging in to the TM1 Login
Server. Users must have the same credentials on any other TM1 server they access. You can specify
a TM1 server that uses any security mode (1 - 5) for authentication. The following security modes
are commonly used:
Security mode 1
Standard (native) TM1 authentication
Security mode 3
Integrated Windows Authentication
Security mode 2
Security modes 1 and 3 are supported. When a user logs in to Planning Analytics Workspace,
they can choose between standard TM1 authentication or Integrated Windows Authentication.
b) If you selected CAM, enter the following values:
• IBM Cognos BI Gateway URI To enable SSO for Planning Analytics Workspace, you must enter a
value in this field.
• IBM Cognos BI Dispatcher URI

Chapter 10. Installing Planning Analytics Workspace Local 165

 • IBM Cognos BI Authentication Namespace ID
3. Click Validate.
Planning Analytics Workspace verifies that it can communicate with the servers and that they are
configured for use with it. If a server is not successfully validated, an error message is displayed.
4. Click OK.
5. Click Update and OK to save your configuration settings.

What to do next
• Verify that the Planning Analytics Workspace services started. For more information, see “Check the
status of the services” on page 168.
• Access Planning Analytics Workspace by entering [Link] where <host-name> is the
host name or IP address of your computer, in the address field of your browser.

Configure TLS for Planning Analytics Workspace Local

To configure Transport Layer Security (TLS) for IBM Planning Analytics Workspace, you create a privacy
enhanced mail (pem) file that contains your security certificates.

Before you begin

You must have the private key, primary, intermediate, and root certificates from your certificate authority
provider.

Procedure
1. Open a text editor and paste the body of each certificate into the file in the following order. Make sure
you include the beginning and end tags on each certificate:
private key
<your_domain_name>.key
primary certificate
<your_domain_name>.crt
intermediate certificate
[Link]
root certificate
[Link]
Here is an example:

-----BEGIN RSA PRIVATE KEY-----

(Your Private Key: your_domain_name.key)
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
(Your Server certificate: your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your Intermediate certificate: [Link])
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your Root certificate: [Link])
-----END CERTIFICATE-----

2. Save the file as [Link] and then copy or move it to the following location:
• <paw_install_location>/config/ssl directory for Microsoft Windows Server 2016 OS.
• <paw_install_location>/config directory for Linux OS.
If the [Link] already exists in the directory, overwrite it.
3. For Microsoft Windows Server 2016 OS:

166 IBM Planning Analytics: Installation and Configuration

 a) Open the <paw_install_location>/config/paw.ps1 file and add the following lines at the
end:

$env:EnableSSL="true"
$env:ServerName="<paw-server-name>"

where <paw-server-name> is the name of the server on which Planning Analytics Workspace is
installed.
b) Save the <paw_install_location>/config/paw.ps1 file.
4. For Linux OS:
a) Open the <paw_install_location>/config/[Link] file and add the following lines at the
end:

export EnableSSL=true
export ServerName=<paw-server-name>

where <paw-server-name> is the name of the server on which Planning Analytics Workspace is
installed.
b) Save the <paw_install_location>/config/[Link] file.
5. Open the Planning Analytics Workspace administration tool and restart all services.
For information about how to open the administration tool, see “Check the status of the services” on
page 168.

Configure TLS between Planning Analytics Workspace Local and other

servers
If you are using self-signed certificates for TM1 servers or IBM Cognos Analytics, you might need to add
the certificate authority certificates for them to the list of CA certificates that are used by IBM Planning
Analytics Workspace.

About this task

This task creates a file called cacerts that contains your CA certificates. The cacerts file is used by the
Java services in Planning Analytics Workspace.
If you get a Java certificate chaining error when you log in to Cognos Analytics, performing these steps
will resolve it.

Procedure
1. Put the certificate authority (CA) certificates files in the paw_install_location>/config/certs
directory.
2. Run the paw_install_location>/scripts/process_certs.ps1 (Microsoft Windows Server
2016 OS) or process_certs.sh (Linux OS) script.
3. Open the Planning Analytics Workspace administration tool and restart all services.
For information about how to open the administration tool, see “Check the status of the services” on
page 168.

What to do next
The cacerts file is created in the <paw_install_location>/config directory. If you need to change
the set of CA certificates, put the CA certificates into the <paw_install_location>/config/certs
directory and run the process_certs script again.

Chapter 10. Installing Planning Analytics Workspace Local 167

Check the status of the services
The Status tab in the Planning Analytics Workspace administration tool displays the status, up time, CPU
usage, memory usage, and percentage of memory used for each service.

About this task

Here's a short video overview of the Status tab:
[Link]

Procedure
1. Run the Start.ps1 (Microsoft Windows Server 2016) or [Link] (Linux) script.
2. Reply "n" when you are prompted to install the Docker images.
3. Reply "y" when you are prompted to start the administration tool.
If the administration tool doesn't open, copy and paste the address shown in the command or terminal
window into a browser window.
4. In the Planning Analytics Workspace administration tool, click the Status tab.
5. Click Refresh and then verify that all services in the list have a status of "running".
When you are installing, wait until all services have started (the CPU % for services drops) before
accessing Planning Analytics Workspace.
6. To stop, start, or restart one service, select (highlight) it in the list, and then click Stop, Start, or
Restart.
7. To stop, start, or restart all services, make sure that no services are selected in the list, and then click
Stop, Start, or Restart.

View logs
You can use the Status tab of the Planning Analytics Workspace administration tool to view logs.

About this task

The log directory in the installation directory contains a subdirectory for each service.
Here's a short video that shows how to access the Planning Analytics Workspace Local log files:
[Link]

Procedure
1. Run one of the following scripts from the <paw_install_location> folder:
Operating system Script to run
Microsoft Windows Server 2016 Start.ps1
Linux [Link]
2. Reply "n" when you are prompted to install the Docker images.
3. Reply "y" when you are prompted to start the administration tool.
If the administration tool doesn't open, copy and paste the address shown in the command or terminal
window into a browser window.
4. In the Planning Analytics Workspace administration tool, click the Status tab.
5. To see the logs of one service, select (highlight) a service in the list by clicking it, and then clicking
Logs.
The last 1000 lines in the log file for the service are displayed.

168 IBM Planning Analytics: Installation and Configuration

 Tip : If you want to see more content, you can open the file from the log directory in a text editor. This
is also a way to view the logs without using the administration tool.

Shut down MongoDB cleanly on Windows Server 2016

When you shut down Planning Analytics Workspace on Windows 2016, you must make sure that you shut
down the MongoDB container cleanly. To perform this shutdown safely, use the Local Group Policy Editor
to add the Planning Analytics Workspace shutdown.ps1 script to the scripts that are launched at
shutdown.

About this task

Important : You must not stop the MongoDB container by using docker commands such as docker
stop. Always use the Planning Analytics Workspace administration tool or the scripts/paw.ps1 script.
The scripts/paw.ps1 script calls the scripts/shutdown.ps1 script whenever an operation that might shut
down MongoDB is invoked. Use the Local Group Policy Editor to add the scripts/shutdown.ps1 to the
scripts that are launched at shutdown.

Procedure
1. Locate the scripts/shutdown.ps1 script in your Planning Analytics Workspace installation folder.
2. Copy the scripts/shutdown.ps1 script to a permanent location on your system.
3. In a command window, open the Group Policy Editor (GPE) by running [Link].
4. Expand Computer Configuration and select Windows Settings.
5. Double-click Scripts (Startup/Shutdown).
6. Switch to the PowerShell Scripts tab.
7. Click Add and add the shutdown.ps1 script from the location in step “2” on page 169.

Run the Planning Analytics Workspace administration tool from the

command line on Linux
You can access the Planning Analytics Workspace administration tool from the command line on Linux.
Here's a short video that shows how to run the Planning Analytics Workspace administration tool from the
command line on Linux.
[Link]

Access the Planning Analytics Workspace administration tool remotely on

Windows Server
On Windows Server, by default you access the Planning Analytics Workspace administration tool from the
computer that it is installed on using port 8888. To access the administration tool remotely, you can set
the ADMINTOOL_PORT environment variable.

About this task

This task applies to Planning Analytics Workspace Local version 2.0.44 or later installed on a Windows
Server only.
Note : Accessing the Planning Analytics Workspace administration tool locally on port 8888 is the
preferred configuration for security reasons.

Procedure
1. Open the <paw_install_location>/config/paw.ps1 file and add the ADMINTOOL_PORT
environment variable in the file:

Chapter 10. Installing Planning Analytics Workspace Local 169

 $env:ADMINTOOL_PORT="<admintool_port>"

where <admintool_port> is a free port on the localhost.

2. Run the Start.ps1 script.
3. Reply "n" when you are prompted to install the Docker images.
4. Reply "y" when you are asked whether you want to start the administration tool.
The Planning Analytics Workspace administration tool opens in your browser on the port specified.
Note : Keep the command or terminal window open. Closing the window stops the administration tool.

What to do next
• If the administration tool doesn't open, copy and paste the address shown in the command or terminal
window into a browser window.

Access the Planning Analytics Workspace administration tool remotely on

Linux
By default you access the Planning Analytics Workspace administration tool from the computer on which
it is installed. To access the administration tool from another computer, you can set the ADMINTOOL_IP
environment variable.

About this task

This task applies to Planning Analytics Workspace Local installed on a Linux OS only.
Here's a short video that shows how to access the Planning Analytics Workspace administration tool if the
website does not appear on Linux.
[Link]
Important : Running the Planning Analytics Workspace administration tool this way is not secure so you
might want to restrict access to specific remote IP addresses using the OS firewall.

Procedure
1. In a terminal window, enter the following command:

export ADMINTOOL_IP=<ip address>

Where <ip address> is the IP address of the computer that is running Planning Analytics Workspace
Local.
2. Run the [Link] script.
3. Access the administration tool from the remote computer by copying and pasting the address that is
shown in the command or terminal window into a browser window on the remote computer.

Back up or restore Planning Analytics Workspace Local

When you back up Planning Analytics Workspace Local, you are saving user information such as
preferences, book assets, chat history, recently visited sites, and book marks.

About this task

All data is backed up or restored. You can't selectively back up or restore.
You should back up Planning Analytics Workspace Local regularly to be prepared for disaster recovery.
To perform disaster recovery, follow the steps to install Planning Analytics Workspace Local on a new
system. Then follow the steps to restore the application from a backup.

170 IBM Planning Analytics: Installation and Configuration

 Important : You must perform this task during a system maintenance window because services are
stopped and started.

Procedure
To back up:
1. Run one of the following scripts from the <paw_install_location>/scripts folder:
• For Microsoft Windows Server 2016, use the backup.ps1 <folder-name> script.
• For Linux, use the [Link] <folder-name> script.
where <folder-name> is the file path and name of the folder to back up to. If you omit <folder-name>, a
folder with the current time is created in the backup directory.
To restore:
2. Run one of the following scripts from the <paw_install_location>/scripts folder:
• For Microsoft Windows Server 2016, use the restore.ps1 <folder-name> script.
• For Linux, use the [Link] <folder-name> script.
where <folder-name> is the path and name that contains the data to restore.

Upgrade Planning Analytics Workspace Local

To upgrade Planning Analytics Workspace Local, you install a new version of Planning Analytics
Workspace Local in a new location.

Before you begin

Go to Fix Central ([Link] and download the version of Planning
Analytics Workspace Local software that you want to upgrade to. Put the
ipa_workspace_local_<version>.zip file in a directory that is different from your current installation and
extract it.
Important : You must upgrade during a system maintenance window because services are stopped and
started.

Procedure
1. Copy the <paw_install_location>/config/paw.ps1 file from your current installation to the
new installation location.
2. Copy the <paw_install_location>/config/certs directory from your current installation to the
new installation location.
3. Optional: If you configured SSL, copy the <paw_install_location>/config/ssl directory from
your current installation to the new installation location.
4. Install Planning Analytics Workspace Local in the new installation location. See Chapter 10, “Installing
Planning Analytics Workspace Local,” on page 155.
Reply "y" when you are prompted to install the Docker images. Reply "y" when you are prompted to
open the administration tool.
5. In the Planning Analytics Workspace administration tool, verify that all of the TM1 URIs are defined
correctly, and restart all the services.

What to do next
Planning Analytics Workspace Local includes a /clean script in the <paw_install_location>/
scripts folder. Running the /clean.ps1 or /[Link] script removes images for the release in which
it is run. After you upgrade, you can run this script to remove images from the installation location of the
previous release.

Chapter 10. Installing Planning Analytics Workspace Local 171

Uninstall Planning Analytics Workspace Local
When you follow these steps to uninstall Planning Analytics Workspace Local, you delete all Docker
containers, databases, images, networks, and volumes that were created for Planning Analytics
Workspace Local.

Procedure
1. If you are uninstalling Planning Analytics Workspace Local from a Microsoft Windows Server 2016 OS,
open a command window, go to the directory where you extracted the installation kit, and enter the
following command:

scripts/paw.ps1 down --rmi all -v

2. If you are uninstalling Planning Analytics Workspace Local from a Linux OS, open a terminal window,
go to the directory where you extracted the installation kit, and enter the following command:

scripts/[Link] down --rmi all -v

3. Some utility containers and images might remain. You can remove them individually by using the
following commands:
a) Show all containers: docker ps -a
b) Remove a specific container: docker rm <container-id>
c) Show all images: docker images
d) Remove a specific image: docker rmi <image-id>
e) Show all networks: docker network ls
f) Remove a specific network: docker network rm <network-id>
Note : On recent versions of Docker, the command docker system prune -a can be used to
remove all unused items.
4. Delete the files in the directory where you extracted the installation kit.

172 IBM Planning Analytics: Installation and Configuration

Chapter 11. Planning Analytics Workspace
Distributed
IBM Planning Analytics Workspace Distributed is an installation of IBM Planning Analytics Workspace that
can be deployed in a container orchestration engine for high availability, fail-over, scalability, and fault
tolerance. In a production system, you can use a load balancer in front of each Planning Analytics
Workspace instance to provide a common endpoint to users.
What is an orchestration engine?
• Deploys and manages containers on a cluster of computers
• Declare resources and their configuration
• Obeys specified constraints (CPU, memory, labels) of the deployment
• Monitors the cluster continuously and ensures its state converges to your declaration
• Popular orchestration engines include Kubernetes and Docker Swarm
When you run [Link] to install Planning Analytics Workspace Distributed, you are prompted to select
your orchestration engine. You can choose [K]ubernetes or [S]warm.

Install on Docker Swarm

Docker Swarm is an orchestration engine that is built into the Docker Engine. An orchestration engine
manages a cluster of nodes that are running Docker Engine.

For more information, see Docker: Enterprise Container Platform for High-Velocity Innovation at https://
[Link].
Note : Planning Analytics Workspace Distributed on Docker Swarm is supported on Red Hat Enterprise
Linux (RHEL) and Community Enterprise Operating System (CentOS). CentOS is a free, community-
supported, open source Linux distribution. Planning Analytics Workspace Distributed on CentOS needs
Docker Community Edition.
To review an up-to-date list of environments supported by Planning Analytics Workspace Distributed,
create a detailed system requirements report by using the Software Product Compatibility Reports tool
([Link]

© Copyright IBM Corp. 2007, 2021 173

Docker Swarm architecture
The Planning Analytics Workspace Distributed application is defined using a declarative service model
that specifies details of the Planning Analytics Workspace Distributed microservices. Docker Swarm
ensures that tasks run to match the service declarations.

Docker Swarm benefits

Running Planning Analytics Workspace Distributed under the Docker Swarm orchestration engine offers
benefits that include cluster management, scaling, automatic fail-over and more.
See Swam mode overview at [Link] for more details.
Cluster management integrated with Docker Engine
Creating a Docker Swarm cluster does not require any additional software to be installed. It is simple
to create a Swarm.
Scaling
Stateless services can be easily scaled by setting the desired number of replicas. Swarm
automatically runs the desired number of service replicas.
Automatic fail-over
If the state of the Swarm does not match the service declarations, Docker Swarm automatically
reconciles any differences. For instance, if a service instance crashes, Swarm automatically starts a
new instance.
Multi-host networking
Swarm supports multi-host virtual networks, called overlay networks. Planning Analytics Workspace
Distributed enables IPsec encryption on overlay networks. Services belong to only those networks
they require to improve service isolation.
Service discovery
Service discovery is built into the Swarm using DNS.
Load balancing
Swarm load balances to service replicas via virtual IP address or DNS round robin.
Secure communication
Swarm nodes use mutual TLS authentication and encryption.

Swarm configuration
Planning Analytics Workspace Distributed is designed to tolerate failure of a single node in the cluster.
In the event of a failure, Planning Analytics Workspace Distributed will continue to run and be operational
until you recover the node.
To achieve this fault tolerance, Swarm requires deployment of a cluster with three manager nodes (you
may optionally add any number of worker nodes for performance reasons). Planning Analytics Workspace

174 IBM Planning Analytics: Installation and Configuration

Distributed configures its database services to use replication or clustering to achieve the same level of
fault tolerance. Planning Analytics Workspace Distributed does not require a distributed filesystem.
Planning Analytics Workspace Distributed services are exposed via the PA Gateway service on port 80
(HTTP) and 443 (HTTPS) through the Swarm routing mesh. All Swarm nodes accept connections on these
ports and route traffic to a node with an active PA Gateway service replica. To expose Planning Analytics
Workspace Distributed to your users as a single endpoint you can use a load balancer, virtual IP address,
DNS or other mechanisms.
The diagram below illustrates a typical Planning Analytics Workspace Distributed deployment using a
three manager Swarm cluster fronted by a load balancer. The load balancer forwards inbound
connections to [Link] to any node in the cluster. Even though an instance of the
PA Gateway service is not running on [Link], Docker Swarm's ingress routing mesh will
forward traffic to a node running the service.

Services
The services that are used in Planning Analytics Workspace Distributed are shown in the following table
with a description of their use in the application.

Service name Description

paw_bss Manages accounts, tenants, users, roles,
capabilities
paw_bss-init Provides initial configuration of BSS
paw_cdn3p Apache proxy serves up static files to browser
clients
paw_couchdb1/2 Instances of CouchDB replicated database
paw_glass Manages components in the Planning Analytics
Workspace user interface
paw_mongo1/2/3 Instances of MongoDB replicated database
paw_mysql-data1/2 Instances of MySQL NDB Cluster Data Nodes
paw_mysql-mgmt MySQL NDB Cluster Management Server
paw_mysql-server MySQL Server instances
paw_neo-idviz Planning Analytics Workspace Content Store to
store books, and views.
paw_neo-provision Planning Analytics Workspace Content Store
configuration agent

Chapter 11. Planning Analytics Workspace Distributed 175

 Service name Description
paw_pa-gateway Main Apache gateway into Planning Analytics
Workspace
paw_monitor TM1 database administration
paw_tm1proxy Used by Planning Analytics for Microsoft Excel
paw_prism-app Dashboard service
paw_prism-platform Query engine, modeling support, and ancillary
services
paw_prism-proxy Apache proxy in front of paw_prism-app and
paw_prism-platform
paw_redis1/2/3 Instances of Redis replicated database
paw_sentinel1/2/3 Instances of Redis sentinels to manage fail-over
paw_share-app Share UX service
paw_share-platform Share core service
paw_share-proxy Apache proxy in front of paw_share-app and
paw_share-platform
paw_social Chat service
paw_user-admin User administration service
paw_wa-proxy Planning Analytics Workspace proxy
paw_welcome Welcome page service

Networks
Planning Analytics Workspace Distributed is a multi-tier application that uses a variety of Docker Swarm
encrypted overlay networks for its services.
The different networks are described as follows.
web
The PA Gateway service resides in the web network. It passes requests to the Planning Analytics
Workspace Distributed Proxy service. Only the PA Gateway service exposes ports on the Swarm
ingress routing mesh.
app
The Planning Analytics Workspace Distributed Proxy service is also a member of the "app" network,
along with most other services. Inter-service communication occurs in the application tier.
couchdb, mongo, mysql, mysql_ndb, redis
Each database resides in its own network. Only those services that need to communicate directly with
a database also belong to the respective network. For MySQL, only MySQL servers are on the storage
engine mysql_ndb network.

Databases
Planning Analytics Workspace Distributed uses several different databases to store assets.
Each database is automatically configured for replication. Replicas are pinned to specific nodes in the
Swarm (and hence their data volumes on local disk) by labeling Swarm nodes as discussed in “Create the
Docker Swarm” on page 178.

176 IBM Planning Analytics: Installation and Configuration

MySQL
MySQL relational database is used to store accounts, tenants, users, roles, and capabilities. MySQL is
configured to use the NDB Cluster storage backend. This database is a high-availability, high-
redundancy version of MySQL.
Redis
Redis is an in-memory key/value store used by Planning Analytics Workspace Distributed to persist
user settings, favorites, and bookmarks. Redis Sentinel instances elect a primary from among the
three Redis instances. Sentinels monitor the health of the Redis servers and promote one to primary
in event of failure.
MongoDB
MongoDB is a document-oriented database. Assets such as books and views are stored here. Planning
Analytics Workspace Distributed deploys a three-member replica set to survive most system failures.
CouchDB
CouchDB is a highly available document-centric database that is used to store user chats. Planning
Analytics Workspace Distributed configures two nodes. Because CouchDB supports primary-primary
replication, this configuration is sufficient to tolerate single node failure.

Docker Registry
You can configure Planning Analytics Workspace Distributed to use your own private registry.
By default, Planning Analytics Workspace Distributed starts a private Docker Registry in the Swarm for
image distribution.
Refer to settings in the [Link] file in your Planning Analytics Workspace Distributed release.
If you configure Planning Analytics Workspace Distributed against your own registry, the [Link] script
automatically retags Planning Analytics Workspace Distributed images and pushes them to your registry.

Typical Planning Analytics Workspace Distributed deployment

Distribution of service replicas among nodes in the Swarm can vary because Swarm is free to distribute
workloads according to the constraints specified in the service specification.
The following diagram shows a typical distribution of service instances. Services that are pinned to nodes
by label are marked with a *. Do not configure more replicas of these services as they are databases that
cannot be arbitrarily scaled.

Chapter 11. Planning Analytics Workspace Distributed 177

 You can change the number of replicas for stateless services (services that are not marked with a * in the
image). Consider increasing the number of replicas only to address a performance bottleneck.

Monitoring Planning Analytics Workspace Distributed

You can monitor Planning Analytics Workspace Distributed by using the Docker CLI.
Many third-party monitoring tools for Docker Engine and Docker Swarm are available, including free and
commercial options.

Create the Docker Swarm

The following instructions provide the basic steps to configure Docker Swarm. You must install Docker
Swarm on an operating system that is supported by IBM Planning Analytics Local.
To review an up-to-date list of environments supported by Planning Analytics Local, create a detailed
system requirements report using the Software Product Compatibility Reports tool (https://
[Link]/software/reports/compatibility/clarity/[Link]).
For more information and deployment options for Docker Swarm, see Swarm mode overview at https://
[Link]/engine/swarm/.

Check Swarm prerequisites

A minimum of three nodes must be available to build the Swarm. A minimum of 16 GB of memory and 4
CPUs is recommended for each node.
• Minimum hardware: 4 core / 8 GB RAM / 200 GB hard disk for three nodes
• Recommended hardware: 8 core / 16 GB RAM / 200 GB hard disk for three nodes
• Optional hardware: 8 core+ / 16 GB RAM+ / 200 GB+ hard disk for six nodes
1. Place these nodes in different availability zones according to your requirements. A three node Swarm
can tolerate failure of a single node. Manager nodes must use fixed IP addresses.
For test or development purposes, you can install Planning Analytics Workspace Distributed on a
single node Swarm configuration. This configuration will lack the fail-over characteristics of a multi-
host Docker Swarm.
2. To access Planning Analytics Workspace Distributed through a single address or host name, configure
a load balancer, virtual IP, or other mechanism against the Swarm nodes that you configure.
3. Install Docker Engine on each node. Follow the instructions for your operating system. For more
information, see About Docker Enterprise at [Link]
4. Validate your Docker installation with the following command:

docker info

Verify free ports for Swarm

You must open ports for Swarm and Planning Analytics Workspace Distributed to operate.
The following ports/protocols must be open for the Swarm to operate:

Port Protocols Description

2377 TCP Cluster management
communications
7946 TCP, UDP Inter-node communication
4789 UDP Overlay network traffic
50 ESP Encrypted IPsec overlay network
(ESP) traffic

178 IBM Planning Analytics: Installation and Configuration

The following ports/protocols must be open for Planning Analytics Workspace Distributed to operate:

Port Protocols Description

80 TCP Planning Analytics Workspace
Distributed Gateway port
443 TCP Planning Analytics Workspace
Distributed Gateway SSL port

Additionally, Planning Analytics Workspace Distributed must be able to make outbound connections to
any external systems you configure (for example, TM1 Servers and TM1 Admin Server).

Initialize the Swarm

Select one node to initialize the Swarm.
Enter the following command:

docker swarm init

Add managers to the Swarm

You can add two more managers to the Swarm to configure a three node Swarm that supports fail-over.
On the first node, get the command to join other managers to the swarm:

docker swarm join-token manager

Copy the output of that command and run it on the other two nodes:

docker swarm join --token SWMTKN-1-

3p1xj2bq2kuyuenqp9b3yx0tob1snwr6uoayljbifq90cxu9qu-3p1t9aqjiwj6v8b03d2iqrx58
[Link]:2377

You can review the Swarm with the command:

docker node ls

Label Swarm nodes

You must label Swarm nodes to control placement of various database containers in the Swarm.
1. Use the following command to list the Swarm node IDs:

docker node ls

Note : Backup and restore scripts are designed to run on the node labeled pa.replica1. Assign that
label with this in mind.
2. Run the following commands to label each node according to your requirements:

docker node update --label-add pa.replica1=true [node id]

docker node update --label-add pa.replica2=true [node id]
docker node update --label-add pa.replica3=true [node id]

3. If you are building a single node Swarm for testing or development purposes apply all three labels to
the same node.
4. If you have chosen to add additional worker nodes to your Swarm, label the nodes according to your
deployment design.

Chapter 11. Planning Analytics Workspace Distributed 179

 Lock the Swarm
You can enable autolock for the Swarm to provide extra security.
For more information, see Enable or disable autolock on an existing swarm at [Link]
engine/swarm/swarm_manager_locking/#enable-or-disable-autolock-on-an-existing-swarm.

Install Planning Analytics Workspace Distributed

Follow these steps to install Planning Analytics Workspace Distributed on a Swarm manager node.
Before you can install Planning Analytics Workspace Distributed, you must complete the steps to create a
Docker Swarm.
Note : You must install Planning Analytics Workspace Distributed to a Swarm manager node. For more
information, see “Add managers to the Swarm” on page 179.

Unzip the Planning Analytics Workspace Distributed archive

To unzip the Planning Analytics Workspace Distributed archive, enter the following command in a
terminal.

unzip ipa_workspace_local_dist_<version>.zip -d <destination folder>

To unzip and upgrade, enter the following command in a terminal.

unzip -o <archive-name>.zip -d <destination-folder>

The unzip command creates the destination folder if it does not exist.

Configure a private registry

Optionally, you can configure Planning Analytics Workspace Distributed against an existing private Docker
registry. If you do not have an existing registry, skip this step.
Before you start Planning Analytics Workspace Distributed, add the following to the [Link] file (create
it if it does not exist):

export RUN_PRIVATE_REGISTRY=false
export REGISTRY="my-registry:5000"
export REPO_NAME="planninganalytics"

Replace my-registry:5000 with the name and port of your private registry.
If your registry requires authentication, make sure that you are logged in and add the following line to the
[Link] file:

export WITH_REGISTRY_AUTH="--with-registry-auth"

Start Planning Analytics Workspace Distributed

Follow these steps to start Planning Analytics Workspace Distributed.
1. Run the [Link] script:

./[Link]

The script checks your environment. If any prerequisites are not satisfied, review the output and
update your environment.
2. Next, the script loads all the release's Docker images into the local image cache. After they are loaded,
they are pushed to the Docker registry.

180 IBM Planning Analytics: Installation and Configuration

3. After the images are pushed to the registry, you will be prompted to start the Planning Analytics
Workspace administration tool. For more information, see “Connect to TM1 and authentication
servers” on page 165.
4. By default, the Planning Analytics Workspace administration tool is accessible only on http://
[Link]:8888. If you are not able to run a browser on the localhost interface, press CTRL+C and
add the following setting to the config/[Link] file and run [Link] again:

export ADMINTOOL_IP=<externally accessible IP address>

5. After you validate and update your configuration settings, close the browser and press CTRL+C in the
terminal.
The script then creates Docker configuration and services if they do not exist.
6. The script creates all the Planning Analytics Workspace Distributed services and notifies you when
Planning Analytics Workspace Distributed is configured and ready to access. You can monitor the
container activity on each node with the docker stats command or a Swarm monitoring tool of your
choice.
7. To access Planning Analytics Workspace Distributed, navigate to any of the Swarm nodes in your
browser. Alternatively, if you configured a load balancer or virtual IP address, navigate to that address.

Contents of the Planning Analytics Workspace Distributed installation

Learn more about the directories in your Planning Analytics Workspace Distributed installation folder.

Top level
config directory
This directory is explained in detail in “config directory” on page 181.
release directory
The top level directory contains a directory with a name that corresponds to the Planning Analytics
Workspace Distributed release you installed.
This directory is named with the format <paw_2.[Link]>.
This directory is explained in detail in “release <paw_2.[Link]> directory” on page 182.
tools directory
This directory is explained in detail in “tools directory” on page 182.
[Link] script
The [Link] script is at the top level of the installation. This script installs and runs Planning
Analytics Workspace Distributed.
[Link] file
The [Link] is also located in this directory.
The [Link] is generated every time you run [Link].

config directory
The config directory contains user-defined configuration settings. When you configure Planning
Analytics Workspace Distributed through the Planning Analytics Workspace administration tool, your
settings are stored in the [Link] file in this folder.
[Link] file
certs directory
The certs directory contains .pem files with SSL certificates to be trusted by Planning Analytics
Workspace Distributed when it connects to TM1 or Cognos Analytics servers. As part of the [Link]
script, Planning Analytics Workspace Distributed creates a Java keystore to store the certificates. If
you are using your own SSL certificates, put your .pem files in this directory so Planning Analytics
Workspace Distributed can validate its access to your servers.

Chapter 11. Planning Analytics Workspace Distributed 181

 current file
The current file defines an environment variable that points to the version of Planning Analytics
Workspace Distributed to run. When you upgrade Planning Analytics Workspace Distributed, this file is
updated to the newer release folder.
[Link] file
oe file
[Link] file
Contains settings that you have overridden to be different from the [Link] file.
[Link] file
The [Link] contains entries that are typically generated by running the Planning Analytics
Workspace administration tool. You can choose to create the [Link] file by hand and use the
[Link] file as a starting point.

release <paw_2.[Link]> directory

This release directory contains all the Planning Analytics Workspace Distributed release-specific files.
config folder
The config folder contains deployment specifications that are used by Docker Swarm to define the
Planning Analytics Workspace Distributed services. You normally don't need to edit these files.
This folder also contains the [Link] file. This file contains default values for Planning
Analytics Workspace Distributed for this release.
images folder
The images folder contains the [Link] file and the [Link] file.
The [Link] file specifies Docker image versions for this release of Planning Analytics
Workspace Distributed. It is processed by the [Link] script.
The [Link] file contains all the Docker images for this release of Planning Analytics Workspace
Distributed. The [Link] script automatically loads these images into the local image cache and
pushes them to a registry that is accessible to the Swarm.
The [Link] and [Link] scripts are automatically run by the [Link] script. They are used to
retag Docker images if they are required and push them to the registry.
kubernetes folder
licenseAccepted file
This file is generated when you accept the license for this release in the Planning Analytics Workspace
administration tool to record your acceptance.
licenses folder
The licenses folder contains language-localized licenses as displayed in the Planning Analytics
Workspace administration tool. You must read and accept these license agreements for each Planning
Analytics Workspace Distributed release.
swarm folder
The swarm folder contains the [Link] file.
The [Link] file specifies default configuration settings for this release. If you want to
customize any settings, add entries to the config/[Link] file to override the defaults.
swidtag folder
[Link] file
The [Link] file contains release version information.

tools directory
This directory contains some utility scripts for maintaining your Planning Analytics Workspace Distributed
installation.

182 IBM Planning Analytics: Installation and Configuration

 [Link] script
The [Link] script starts the Planning Analytics Workspace administration tool. Normally you
do not need to run this script directly because the Planning Analytics Workspace administration tool
starts automatically when the [Link] script is run.
[Link] script
The [Link] script is run to take a backup of your Planning Analytics Workspace Distributed
installation. For more information, see “Back up and restore Planning Analytics Workspace
Distributed” on page 184.
[Link]
[Link] script
The [Link] script is run to restore a Planning Analytics Workspace Distributed installation from
a backup. For more information, see “Back up and restore Planning Analytics Workspace Distributed”
on page 184.
[Link] script
The [Link] script checks Planning Analytics Workspace Distributed
prerequisites. Normally you do not need to run this script directly because it runs automatically when
the [Link] script is run.
[Link] script
This script captures logs for all Planning Analytics Workspace Distributed services, writes them to the
a ./logs folder, and creates a timestamped archive file. Use this script to capture logs for support.

Enable TLS for Planning Analytics Workspace Distributed

By default, Planning Analytics Workspace Distributed creates a self-signed certificate. You can configure
Transport Layer Security (TLS) to use your own certificate.

Use your own certificate

To use your own certificate, first prepare a .pem file with the following contents.

-----BEGIN RSA PRIVATE KEY-----

(Your Private Key: your_domain_name.key)
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
(Your Server certificate: your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your Intermediate certificate: [Link])
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your Root certificate: [Link])
-----END CERTIFICATE-----

Remove the paw_pa-gateway service so the existing secret can be removed.

Note : Planning Analytics Workspace Distributed becomes inaccessible during this time.

docker service rm paw_pa-gateway

Remove any existing secret file:

docker secret rm pa_gateway_pem

Specify the path to your .pem file:

export PA_GATEWAY_PEM_FILE=[absolute path to .pem file]

Chapter 11. Planning Analytics Workspace Distributed 183

 Configure TLS
To configure TLS, edit the config/[Link] file and add the following entries and then run [Link] for
the changes to take effect.

export EnableSSL=true
export ServerName=<your server's FQDN>

The ServerName setting is used to redirect clients to the HTTPS endpoint.

Important : When these settings are updated, run the [Link] script for the changes to Planning
Analytics Workspace Distributed to take effect.
If you used your own .pem file you can now delete it. The information is securely managed by Docker
Swarm.

Migrate to Planning Analytics Workspace Distributed

Migration to Planning Analytics Workspace Distributed by using Planning Analytics Workspace Local
backup is a seamless upgrade.
1. Back up Planning Analytics Workspace Local.
2. Then, follow the instructions to restore on Planning Analytics Workspace Distributed.

Back up and restore Planning Analytics Workspace Distributed

You must manage your Docker Swarm appropriately. Restore should only be performed for disaster
recovery purposes on a newly installed Planning Analytics Workspace Distributed.
Review Administer and maintain a swarm of Docker Engines at [Link]
admin_guide/ for detailed information on managing your Swarm.

Back up
Backups are performed online and do not disrupt the availability of Planning Analytics Workspace
Distributed.
To back up the Planning Analytics Workspace Distributed databases, run the tools/[Link] script:

tools/[Link]

If no parameters are supplied, the script creates a folder that is called backup in the current working
directory and stores the backup data in a folder with a name generated based on the current date and
time.
You can also supply a folder path for the backup. If the folder exists, it must be empty. If the path does
not exist, the script creates it.

tools/[Link] my/backup/folder

Schedule backups according to your business requirements. You might want to compress and encrypt the
contents of the backup folder before you archive it.

Restore
You can rebuild and restore a failed Docker swarm or restore Planning Analytics Workspace Distributed.
Attention : Restore should only be performed for disaster recovery purposes on a newly installed
Planning Analytics Workspace Distributed.

184 IBM Planning Analytics: Installation and Configuration

 Restore a failed Swarm
Follow the steps in Recover from disaster at [Link]
#recover-from-disaster to rebuild your Swarm.
When the swarm is recovered, install Planning Analytics Workspace Distributed. If the configuration
settings from your backup are applicable to your recovered Planning Analytics Workspace Distributed
instance, you can copy the relevant files such as [Link] to the config directory before you start Planning
Analytics Workspace Distributed. Start Planning Analytics Workspace Distributed as usual and then
restore your Planning Analytics Workspace Distributed databases.

Restore Planning Analytics Workspace Distributed databases

When Planning Analytics Workspace Distributed is running, to restore Planning Analytics Workspace
Distributed databases, run the tools/[Link] script:

tools/[Link] path-to-backup-folder

Remove Planning Analytics Workspace Distributed

You can completely remove Planning Analytics Workspace Distributed by following these steps.

Procedure
1. Remove the paw-related stacks.

docker stack rm paw

docker stack rm paw_image_pull
docker stack rm paw_registry

2. Wait for all services and networks to be removed.

3. Remove the paw-related secrets and configs.

docker secret rm $(docker secret ls -f name=pa_ -q)

docker config rm $(docker config ls -f name=pa_ -q)

4. For each node with databases, follow these steps:

a) Remove stopped containers.

docker rm $(docker ps -a -q -f "name=paw")

b) Remove volumes.

docker volume rm $(docker volume ls -q -f "name=paw")

Upgrade Planning Analytics Workspace Distributed

You can upgrade Planning Analytics Workspace Distributed without uninstalling.
Unzip the new release of Planning Analytics Workspace Distributed to the same directory as your existing
installation.

unzip -o <archive-name>.zip -d <destination-folder>

Your custom settings in the config folder are not overwritten.

Run the [Link] script to update the services and switch to the new release:

./[Link]

Chapter 11. Planning Analytics Workspace Distributed 185

 When you are satisfied with the upgrade, you can delete the folder for the previous release. If you need to
roll back you can either edit the config/current file to point to an older release, or extract the previous
release again.

Install on OpenShift
Planning Analytics Workspace Distributed supports deployment on Red Hat OpenShift Container Platform,
a container orchestration system for automating application deployment, scaling, and management of
containerized applications..

An OpenShift environment can have one or more of the following features activated:
• A private docker registry for the OpenShift deployment
• An active helm within the OpenShift deployment
• An ingress controller configured for the OpenShift environment

Install OpenShift prerequisites

Before you install Planning Analytics Workspace Distributed on OpenShift, make sure that you have the
following prerequisites.
OpenShift
You must use OpenShift version 3.11.
Docker
You must use Docker version 1.13 or higher. Podman is not currently supported.
Worker node requirements
Planning Analytics Workspace Distributed requires worker nodes that meet or exceed the following
capacities.
• 4 CPUs
• 8 Gb of random-access memory (RAM)
• 400 Gb of storage
The install script automatically detects worker nodes in the cluster if they are assigned one of the
following labels:

186 IBM Planning Analytics: Installation and Configuration

 • [Link]/compute
• [Link]/worker
If you want the start script to automatically detect the worker nodes to use, make sure that one of
these labels is specified for the worker node.
Or, you can manually configure the OpenShift node configuration file.
Environment
The following utilities must be available on the system where you run the deployment scripts:
• Bash version 3 or higher must be present on the system where the deployment scripts run.
• The sed utility must be present on the system.
• If the tee utility is on your system, then the deployment scripts display the output from the
initialization job on the screen. Otherwise, it waits until initialization finishes.
If your environment employs a docker registry for image management, you must also install the
docker client on your system. Otherwise, the following utilities must be available:
• scp
• ssh
If you don't have this configuration, see “Configure advanced OpenShift settings” on page 191 to
configure the installation so that it does not assume these options.

Extract the Planning Analytics Workspace Distributed archive

To extract the Planning Analytics Workspace Distributed archive, enter the following command in a
terminal.

unzip -o <archive-name>.zip -d <destination-folder>

The unzip creates the destination folder if it does not exist.

Configure basic OpenShift settings

In most cases, the default configuration settings are sufficient for your OpenShift cluster. All default
configuration settings can be found in kubernetes/config/[Link]. If the default
configuration settings are not sufficient, you can override any settings in a config/[Link] file.
Note : Do not change the values in kubernetes/config/[Link]. Use config/[Link] to
override a value in [Link].
Other advanced options also exist that allow different configuration. For more information, see “More
basic configuration settings” on page 194.

Configure the OpenShift project

By default, the start script configures an OpenShift project named paw. If you wish to use a different
name, add export PA_KUBE_NAMESPACE=<project> to [Link].
For example: export PA_KUBE_NAMESPACE=myns
Important : Do not specify the default project, or any of the OpenShift system projects as the value of
PA_KUBE_NAMESPACE.

Configure deployment of images

You can configure Planning Analytics Workspace Distributed to copy the docker image files to all worker
nodes or employ a private docker registry if one is configured for the OpenShift cluster.
The start script asks whether you want to use a private registry. If you don't want to use a private registry,
the start script uses ssh and scp to copy the image archive to all designated worker and storage nodes.

Chapter 11. Planning Analytics Workspace Distributed 187

 Note : A worker node must have at least 5 Gb of space for the image copy to succeed.
By default, the scripts assume that the same ssh user is to be used on all nodes. If your cluster uses
different ssh users, set SSH_SAME_USER to false in config/[Link].
If you want to use a private registry, then the docker command is used to push the images to the
configured private registry. The start script prompts for the host name and port of the private registry. You
are prompted for the registry user name and password when applicable.
You can use more configuration settings to change the image copy path, tag prefix, and to support
unattended installs. For more information, see “Advanced image deployment settings” on page 195.

Configure an ingress controller

By default, an ingress controller is assumed to be configured for the OpenShift deployment. A TLS
certificate is generated for the ingress controller to use.
If you have your own key and certificate that you want to use instead, see “Advanced ingress controller
configuration settings” on page 196.

Configure storage
The storage services in Planning Analytics Workspace Distributed employ OpenShift persistent volume
claims to persist data.
Three storage types are supported:
• local
• shared
• dedicated
The desired storage type is configured by specifying local, shared, or dedicated as the value for
PA_KUBE_STORAGE_TYPE in [Link]. If PA_KUBE_STORAGE_TYPE is not specified, the start script
prompts you for the desired storage type.

Configure local storage

By default, Planning Analytics Workspace Distributed uses the local storage type. The local storage type
uses OpenShift local persistent storage that is pinned to three worker nodes, as specified by the
PA_KUBE_STORAGE_NODES environment variable in [Link].
The storage containers are also pinned to these same nodes, allowing the application to continue to
function if one of the nodes becomes inactive. If PA_KUBE_STORAGE_NODES is not specified, then the
start script selects three worker nodes to act as the storage nodes.
Local storage employs three persistent volume claims, one for each of the three storage nodes. Storage
containers are grouped into three sets: storage-node1, storage-node2, and storage-node3.
For local persistent storage to work properly, the root location on each storage node must exist before the
node can be used. The start script asks you whether you would like the script to configure the storage
location on each storage node automatically. Note that this requires ssh access to the three storage
nodes. If you do not have ssh access to the storage nodes, or wish to configure the storage nodes
manually, specify n when prompted.

Configure shared storage

Shared storage employs a single persistent volume claim that is shared by all storage containers. If you
are planning to use NFS or another shared storage provider such as Portworx, select shared when
prompted. PA_KUBE_STORAGE_NODES is not used with shared storage.
Shared storage supports two types of volumes: NFS and other. The volume type is configurable via the
PA_KUBE_VOLUME_TYPE environment variable in [Link]. If PA_KUBE_VOLUME_TYPE is not specified,
you are prompted to select the desired type. Shared storage employs a single persistent volume claim,
and all storage services reference the single volume claim.

188 IBM Planning Analytics: Installation and Configuration

 Configure dedicated storage
Dedicated storage employs a separate persistent volume claim for each storage container. This allows for
a finer grain of persistence to be specified, allowing storage providers to make optimal decisions
regarding placement.
Dedicated storage supports three types of volumes: local, NFS, and other. The volume type is
configured with the PA_KUBE_VOLUME_TYPE environment variable in [Link].
If PA_KUBE_VOLUME_TYPE is not specified, you are prompted to select the desired type. If local is
specified for the volume type, then storage exhibits the same semantics as if PA_KUBE_STORAGE_TYPE
was set to local. Storage is pinned to three worker nodes, as specified by the
PA_KUBE_STORAGE_NODES environment variable in [Link]. The storage containers are also pinned to
these same nodes, allowing the application to continue to function if one of the nodes becomes inactive.

Set the desired storage class

Some storage providers expose storage classes that need to be specified in any persistent volume claims.
If the storage provider configured for your cluster employs such storage-classes,
PA_KUBE_STORAGE_CLASS can be set to specify the desired storage class. If
PA_KUBE_STORAGE_CLASS is not specified in [Link], you are prompted to specify the desired storage
class.

Storage providers and init container execution

Some storage providers may require that the ownership of the mounted volumes be changed within the
pods. If the storage class that you are using requires this action, set PA_KUBE_INIT_CONTAINERS to
true within [Link].
Note that this also requires that your cluster be configured to allow the init containers to run as root. To
minimize the security exposure, the installation configures a service account called pa-allow-rootuid
that is used for all storage pods. The pa-allow-rootuid service account must be added to the
appropriate security context object in your cluster that allows containers to run as root.

Set OpenShift resource limits

By default, all Planning Analytics Workspace Distributed containers execute without any limits on the
amount of CPU and memory that they consume. However, some environments may require that explicit
limits be specified for all containers running in the cluster.
If your deployment has such a requirement, set PA_KUBE_EXPLICIT_LIMITS to true in [Link]. The
default configuration values can be found in kubernetes/config/[Link]. If you need to
increase the values, override the appropriate environment variable in [Link].

Deferred deployment
If your environment employs a DevOps pipeline environment, you may want to deploy Planning Analytics
Workspace Distributed via the pipeline, as opposed to executing [Link]. To support such
environments, Planning Analytics Workspace Distributed contains two scripts: [Link] and
[Link].
The [Link] script lets you push container images as an independent operation.
The [Link] scripts performs the same operations as [Link], but it does not deploy the
application. It simply prepares the Helm chart or standalone YAML files (depending on configuration), so
that the objects can be deployed by another process. The [Link] script may also generate a
[Link] script, which contains commands that must be executed before deploying the
application.
Standard YAML files are generated by configuration. Use the following standard OpenShift or Helm
commands to deploy the application:
• oc apply
• helm install

Chapter 11. Planning Analytics Workspace Distributed 189

Configure Red Hat OpenShift deployment
For Red Hat OpenShift, the following configuration settings must be performed on the deployment.
Log in with a user that has the cluster-admin role, then execute the following commands:

oc new-project paw
oc adm policy add-scc-to-user nonroot -z pa-config-secret -n paw
oc adm policy add-scc-to-user nonroot -z default -n paw

If the storage provider configured for your cluster requires that the ownership of the mounted volumes be
changed within the pods, then execute the following additional commands:

oc create serviceaccount pa-allow-rootuid -n paw

oc adm policy add-scc-to-user anyuid -z pa-allow-rootuid -n paw

Note : Replace paw in the above commands if you have overridden the default project value.

Start Planning Analytics Workspace Distributed

Follow these steps to start Planning Analytics Workspace Distributed.

Procedure
1. Run the [Link] script:

./[Link]

The script checks your cluster environment. If any prerequisites are not satisfied, review the output,
update your environment, and rerun the script.
2. Provide values for the configuration prompts that the start script presents:

Enter the host name of your primary node: [Link]

Helm detected - configuring install to use helm for deployment
Would you like to use a private docker registry? (default 'n'):
Worker nodes configuration successfully validated
Kubernetes version successfully validated
Storage class (default: 'paw-storageclass'):
Storage type - dedicated | local | shared (default: 'local'):
Storage root for local persistent volumes (default: '/opt/ibm/planninganalytics/paw'):
Storage nodes configuration successfully validated
Ingress type - controller | nodeport | none (default: 'controller'):
Ingress host (default: ‘[Link]'):

3. Verify that the script created all Planning Analytics Workspace Distributed services. Wait a few minutes
for the system to complete its initial configuration.

Reinstall or uninstall Planning Analytics Workspace Distributed

To reinstall or uninstall Planning Analytics Workspace Distributed, run the ./paw_x.[Link]/
kubernetes/scripts/[Link] script.
The script asks whether you want to clean up the persistent storage used by the installation. If you are
reinstalling and want to reuse your existing content, answer 'n' to the prompt.
The script also asks whether you want to remove the project configuration from the cluster. If you want to
completely uninstall Planning Analytics Workspace Distributed from your cluster, answer 'y' to the
prompt.

190 IBM Planning Analytics: Installation and Configuration

Configure advanced OpenShift settings
You can used advanced configuration settings to customize your installation of Planning Analytics
Workspace Distributed.

Node configuration
The node configuration file, found at config/[Link], specifies information about the OpenShift nodes
that the installation needs.
The configuration file contains four environment variables: COPY_NODE, WORKER_NODES,
STORAGE_NODES, and NFS_SERVER:

Example node configuration

#
# If you are not employing a docker registry, specify the
# host portion of the primary node URI returned from the
# [Link] script.
#
export COPY_NODE=()

#
# Specify the values of all worker nodes returned from the [Link] script.
# Space separated. e.g. (value1 value2 value3) where value is hostname of each worker.
#
export WORKER_NODES=()

#
# Specify the values of three of the nodes listed in the above WORKER_NODES variable.
# Space separated. e.g. (value1 value2 value3) where value is hostname of each worker.
#
export STORAGE_NODES=()

#
# Specify the IP address of the nfs server if employing nfs
# based persistent volumes
#
export NFS_SERVER=()

Configure the persistent volume locations on the storage nodes

By default, the storage services use OpenShift local persistent volumes within the designated storage
nodes. The start script asks you whether you would like the script to configure the storage locations
automatically.

About this task

Note : If you changed the value of PA_KUBE_STORAGE_ROOT, replace /opt/ibm/
planninganalytics/paw in these commands with the new value.

Procedure
1. If you have ssh access to the storage nodes, specify y when you are prompted. The start script will ask
you to log in to each storage node and will configure the storage folders for you.
2. If you do not have ssh access to the storage nodes, an administrator must complete the following
steps:
a) Log on to first storage node that you have specified in the config/[Link] file and run the
following command:

sudo mkdir -p /opt/ibm/planninganalytics/paw/storage-node1

b) Log on to the second storage node and run the following command:

sudo mkdir -p /opt/ibm/planninganalytics/paw/storage-node2

Chapter 11. Planning Analytics Workspace Distributed 191

 c) Log on to the third storage node and run the following command:

sudo mkdir -p /opt/ibm/planninganalytics/paw/storage-node3

What to do next
If you want to use another volume type, see “Configure a different storage type” on page 192.

Configure the NFS persistent volume locations

If you decide to use a Network File System (NFS) server for storage, you must perform the following
operations.

About this task

Note : If you changed the value of PA_KUBE_STORAGE_ROOT, replace /opt/ibm/
planninganalytics/paw in these commands with the new value.

Procedure
1. Add the following lines to config/[Link]:

export PA_KUBE_STORAGE_TYPE=shared
export PA_KUBE_VOLUME_TYPE=nfs

2. 2. Add the IP address of the NFS server to config/[Link].

3. 3. Configure the storage folders on the NFS server.
4. If the OpenShift cluster does not support dynamic provisioning for NFS persistent volumes, log on to
the NFS server and execute the following commands:

sudo mkdir -p /opt/ibm/planninganalytics/paw/storage-node1

sudo mkdir -p /opt/ibm/planninganalytics/paw/storage-node2
sudo mkdir -p /opt/ibm/planninganalytics/paw/storage-node3

5. Configure your NFS server to export the following location:

/opt/ibm/planninganalytics/paw

6. On each of the three storage nodes, mount the following NFS directory:

/opt/ibm/planninganalytics/paw

Configure a different storage type

If your deployment uses a different storage type, for example, GlusterFS, you must modify the contents of
the [Link] file in the kubernetes/templates/volumes directory.

Before you begin

The [Link] file contains all persistent volume definitions that are required for the storage services.
You can update the persistent volume definitions; however, the metadata section of each persistent
volume definition must remain as specified.

Procedure
1. Add the following line to config/[Link]:

export PA_KUBE_STORAGE_TYPE=shared
export PA_KUBE_VOLUME_TYPE=other

2. Configure the volume definitions in templates/volumes/[Link]. Each persistent volume

definition in templates/volumes/[Link] contains a comment block. Replace the comment
block with details associated with the storage type.

192 IBM Planning Analytics: Installation and Configuration

 #
# Place your volume configuration here
#

Configure Red Hat OpenShift security

To enable the OpenShift cluster to create Planning Analytics Workspace Distributed secrets, the
installation configures the pa-config-secret service account.
If your storage provider requires that the ownership of mounted volumes be changed within the container,
the installation configures a service account called pa-allow-rootuid that is used for all storage pods.
The pa-allow-rootuid service account must be added to the appropriate security context object in
your cluster that allows containers to run as root.
Both of these service accounts are restricted to the Planning Analytics Workspace Distributed project,
which is paw by default. These service accounts are used only by the containers that are associated with
Planning Analytics Workspace Distributed.
1. The pa-allow-rootuid service account allows the Planning Analytics Workspace Distributed
storage services to temporarily run as root so that correct file permissions can be set. After this step
completes, the storage services run as a non-root user.
2. The pa-config-secret service accounts allow the installation to create secrets in the cluster.
Secrets are created in the cluster by a configuration container that is run during the installation of
Planning Analytics Workspace Distributed. The installation also configures pa-config-secret role
and role-binding objects that restrict the service account to manage only secrets within the Planning
Analytics Workspace Distributed project.
Note : Secrets configuration runs during the installation, it does not run as part of Planning Analytics
Workspace Distributed itself.

Configure the primary node and worker nodes

Use the tools/[Link] command to determine the values to specify within each section of
config/[Link].

Procedure
1. Run the tools/[Link] command to determine the values for each section of the config/
[Link].
The command returns information on the primary node and worker nodes in the OpenShift cluster.
For example:

Kubernetes primary is running at [Link]

Worker nodes:
[Link]
[Link]
[Link]
[Link]

2. Configure the host of the primary node that is returned from step “1” on page 193 in the COPY_NODE
environment variable so that image archives are placed on the worker nodes.
For example:

export COPY_NODE=([Link])

3. Copy the list of returned worker nodes that are returned from step “1” on page 193 to the
WORKER_NODES environment variable to specify the addresses of all worker nodes in the
deployment..

Chapter 11. Planning Analytics Workspace Distributed 193

 For example:

export WORKER_NODES=([Link] [Link] [Link] [Link])

4. Select three worker nodes to act as storage nodes and specify them within the STORAGE_NODES
environment variable.
Planning Analytics Workspace Distributed pins the storage services to three worker nodes. All other
services are distributed across all worker nodes as OpenShift determines.
For example:

export STORAGE_NODES=([Link] [Link] [Link])

More basic configuration settings

You can use more basic configuration options to customize projects, logging, and backup capabilities for
Planning Analytics Workspace Distributed.
KUBERNETES_CMD
Possible values: any valid path
Default value: kubectl
Name of kubectl command. Specify a fully qualified path if kubectl is not already within your path.
PA_KUBE_CHART
Possible values: any
Default value: pa-workspace
Helm chart name. Must not be blank.
PA_KUBE_HOST
Possible values: any
Default value: none
Hostname of external access point for Planning Analytics Workspace.
This value is typically the hostname of your proxy node, or an external load balancer. Must not be
blank.
If not specified, you are prompted for a value.
PA_KUBE_INGRESS_CONTROLLER
Possible values: true | false
Default value: ()
Indicates whether an ingress controller is configured for the OpenShift cluster.
If not specified, the deployment script automatically tries to detect the existence of an ingress
controller.
PA_KUBE_INGRESS_HOST
Possible values: any
Default value: The value of PA_KUBE_HOST
Allows for the specification of an ingress host for your application.
If not specified, you are prompted whether you would like an ingress host, and if so, what the host
value should be.
PA_KUBE_NAMESPACE
Possible values: ()
Default value: paw
Specifies the OpenShift project.
PA_LOG_MODE
Possible values: file | console

194 IBM Planning Analytics: Installation and Configuration

 Default value: file
Indicates whether the deployment script writes logs to the console or to a file.
PA_ZIP_BACKUP
Possible values: true | false
Default value: false
Indicates whether backups are to be stored as a compressed file.

Advanced image deployment settings

If ssh and scp are not already within your path, you can update the following settings to point to their
locations.
PA_KUBE_USE_PRIVATE_REGISTRY
Possible values: true | false
Default value: none
Indicates whether to use a private docker registry.
If not specified, you are prompted for a value.
PA_KUBE_PRIVATE_REGISTRY_SECRET
Possible values: any
Default value: pa-registry-secret
Indicates the name of the private registry secret that is used to pull images. If the specified value is
the default, then you are prompted to create the secret, otherwise it is assumed to already exist.
SCP_CMD
Possible values: any valid path
Default value: scp
Name of scp command. Specify a fully qualified path if scp is not already within your path.
SCP_PATH
Possible values: any valid path
Default value: .
Location on worker node where to place image archives. Can either be an absolute or relative path.
SSH_CMD
Possible values: any valid path
Default value: ssh
Name of ssh command. Specify a fully qualified path if ssh is not already within your path.
SSH_SAME_USER
Possible values: true | false
Default value: true
Indicates whether the ssh user is the same on all worker and storage nodes.
If docker is not already within your path, update the DOCKER_CMD setting:
DOCKER_CMD
Possible values: any valid path
Default value: docker
Name of docker command. Specify a fully qualified path if docker is not already within your path.
For unattended installs, you can specify the user name, password, and email address of the docker
private registry user:
REGISTRY
Possible values: (any)
Default value: [Link]:5000

Chapter 11. Planning Analytics Workspace Distributed 195

 Docker private registry host and port. Must not be blank.
REGISTRY_USER
Possible values: any
Default value: none
Docker private registry user. If blank, you are prompted for the value.
REGISTRY_PASSWORD
Possible values: any
Default value: none
Docker private registry password. If blank, you are prompted for the value.
REGISTRY_EMAIL
Possible values: any
Default value: none
Docker private registry user email address. If blank, you are prompted for the value.
The shipped images are predefined to use an image tag prefix of planninganalytics. If you want to
change the default value, update the following setting:
REPO_NAME
Possible values: any
Default value: planninganalytics
Image tag prefix. Must not be blank.

Advanced helm configuration settings

If the helm command is not already on your path, you can update the following settings.
HELM_CMD
Possible values: any valid path
Default value: helm
Name of helm command. Specify a fully qualified path if helm is not already within your path.
HELM_CONFIGURED
Possible values: true | false
Default value: true
Indicates whether helm is configured for the deployment.
HELM_TLS
Possible values: true | false
Default value: true
Indicates whether helm uses HTTPS/TLS.

Advanced ingress controller configuration settings

By default, a TLS certificate is generated for the ingress controller to use. If you have your own TLS key
and certificate that you want to use instead, update the following settings.
PA_KUBE_INGRESS_KEY
Possible values: any valid path
Default value: none
Path to key to be used by the ingress controller.
PA_KUBE_INGRESS_CERT
Possible values: any valid path
Default value: none
Path to certificate to be used by the ingress controller.

196 IBM Planning Analytics: Installation and Configuration

Advanced storage service configuration settings
You can use the following settings to customize storage requirements for Planning Analytics Workspace
Distributed.
PA_KUBE_INIT_CONTAINERS
Possible values: true | false
Default value: false
Indicates whether storage provider requires ownership of mounted volumes be changed by the pods.
PA_KUBE_NUM_STORAGE_NODES
Possible values: 1-3
Default value: 3
Number of nodes in the cluster that are to be used for storage nodes. All storage services are pinned
to run only on these nodes.
PA_KUBE_STORAGE_CLASS
Possible values: any
Default value: pa-local-storage
OpenShift storage class.
PA_KUBE_STORAGE_DYNAMIC_PROVISIONING
Possible values: true | false
Default value: false
Indicates whether the storage type supports dynamic provisioning.
PA_KUBE_STORAGE_ROOT
Possible values: any
Default value: /opt/ibm/planninganalytics/paw
Path to local storage on each worker node that runs the storage services. Can either be an absolute or
relative path.
PA_KUBE_ STORAGE_SIZE
Possible values: > 1Gi
Default value: 10Gi
Space requirements for the storage services configured on each storage node. The value must be of
the format 'xxGi', where xx is an integer value.
PA_KUBE_STORAGE_TYPE
Possible values: dedicated | local | shared
Default value: local
Indicates whether storage is local or shared.
PA_KUBE_VOLUME_TYPE
Possible values: local | nfs | other
The value local is only valid when PA_KUBE_STORAGE_TYPE is set to shared.
Default value: none
Indicates which OpenShift volume type to use when PA_KUBE_STORAGE_TYPE is set to shared.

Chapter 11. Planning Analytics Workspace Distributed 197

198 IBM Planning Analytics: Installation and Configuration
Chapter 12. Installing and configuring Planning
Analytics for Microsoft Excel
IBM Planning Analytics for Microsoft Excel is a Microsoft Excel-based tool that professional report authors
use to build sophisticated, multiple-sheet, multiple-query reports against multiple databases.
Users can build sophisticated multiple-sheet, multiple-query reports in Excel from different kinds of data
sources, and analyze and explore IBM Cognos dimensionally modeled data. The application provides
formula-based data access so that users can solve business problems and present key results in a format
that is most convenient to them.
For IBM Cognos Analytics, this application is used to analyze enterprise data to identify trends,
opportunities, problems, or project characteristics.
For IBM Planning Analytics, this application is used by financial analysts and planners who plan and
measure business and operational data.

What's new?
This section contains a list of new or changed features for this release. It helps you to plan your upgrade
and application deployment strategies and the training requirements for your users.

New features in version 2.0.0

• IBM Planning Analytics for Microsoft Excel requires Microsoft .NET Framework 4.6.1 or later to be
installed.
• IBM Planning Analytics for Microsoft Excel supports security authentication modes 1, 2, 3, 4, 5.
Previous versions supported modes 1 and 5.
However, when connecting to IBM Planning Analytics Workspace, only security authentication modes 1
and 5 can be used.
Forms based authentication is no longer supported for IBM Planning Analytics servers in IBM Planning
Analytics for Microsoft Excel.

New features in version 10.3.0

• If your servers use Transport Layer Security (TLS), you must use Microsoft .NET Framework 4.5 or later
with IBM Cognos Analysis for Microsoft Excel. New servers, and servers that have been patched to
address the POODLE security vulnerability in SSL use TLS.

New features in version 10.2.0

• IBM Cognos Office products, such as IBM Cognos Analysis for Microsoft Excel and IBM Cognos BI for
Microsoft Office now require the use of Microsoft .NET Framework 4.
This updated conformance has implications for upgrading systems. If you are a current user of an IBM
Cognos Office product and installed only Microsoft .NET Framework 2, you must also install .NET
Framework 4. You must install the updated .NET Framework before installing IBM Cognos Office
products. Microsoft .NET Framework versions can work along side each other. You do not need to
uninstall previous versions.
• The following additional languages are available for IBM Cognos Office products: Croatian, Danish,
Kazakh, Slovenian, and Thai.

© Copyright IBM Corp. 2007, 2021 199

Installation overview
To use IBM Planning Analytics for Microsoft Excel, you must install Microsoft .NET Framework and the
IBM Planning Analytics for Microsoft Excel components.
IBM Cognos TM1 includes samples that you can use with IBM Planning Analytics for Microsoft Excel. The
samples illustrate product features and technical and business best practices using fictitious data. You
can also use the samples to experiment with and share report design techniques, and for troubleshooting.
To use the samples, your administrator must set up and configure them. Contact your administrator to
find out where they are installed.
Uninstall older versions of IBM Planning Analytics for Microsoft Excel before you install a new version.

Procedure
1. Complete the prerequisite tasks.
a) Install [Link] Framework.
For more information, see Installing Microsoft .NET Framework.
b) Install Primary Interop Assemblies.
For more information, see Installing Primary Interop Assemblies.
c) Uninstall previous versions of IBM Planning Analytics for Microsoft Excel.
For more information, see “Uninstall previous versions of IBM Cognos Analysis for Microsoft Excel”
on page 202.
d) “Connect to IBM Planning Analytics Workspace” on page 203.
e) Configure your antivirus software to allow connections from Microsoft .NET Runtime and Microsoft
Excel.
f) “Ensure that you are using IBMid” on page 204.
g) “Use Cognos security” on page 204.
2. Install IBM Planning Analytics for Microsoft Excel components.
For more information, see Installing IBM Cognos Analysis for Microsoft Excel components.
3. Test IBM Planning Analytics for Microsoft Excel.
For more information, see Testing IBM Cognos Analysis for Microsoft Excel.

Prerequisites for installing Planning Analytics for Microsoft Excel

You must complete the tasks in this section before you install Planning Analytics for Microsoft Excel.

Find the version information for IBM Planning Analytics for Microsoft Excel
You can find the version information for Planning Analytics for Microsoft Excel in the IBM Planning
Analytics ribbon.

Procedure
1. Click the IBM Planning Analytics tab to open the IBM Planning Analytics ribbon.
2. Click the Help drop down, located in the Getting Started group.
3. Click About.
4. Click Show Version... to open the version text file.
5. The CORCSP_version line contains the version number for your installation of Planning Analytics for
Microsoft Excel.

200 IBM Planning Analytics: Installation and Configuration

 Example
If the value of CORCSP_version is COR-AW64-ML-RTM-[Link]-0, the version number is 47.4.

Install Microsoft .NET Framework

IBM Planning Analytics for Microsoft Excel requires Microsoft .NET Framework version 4.6.1 or later to be
installed on all user computers.
For a list of supported versions of Microsoft .NET Framework, see the IBM Software Product Compatibility
Reports ([Link]
When you install Microsoft .NET Framework on a non-English operating system, Microsoft .NET error
messages, shortcuts, and utilities appear in English.
For a language other than English, you can apply the Microsoft .NET Framework Language Pack to view
error messages, shortcuts, and utilities in the language of your operating system. For example, if your
operating system is French and you installed Microsoft .NET Framework, you must also apply
Microsoft .NET French Language Pack.

Procedure
1. Go to the Microsoft download website.
2. Search for .NET Framework 4.6.1 or later, select the redistributable package, and follow the
instructions to download it.
3. Check for other security updates that relate to your version of .NET Framework and download them.

Primary interop assemblies (PIAs) for Microsoft Excel

To use the features of IBM Planning Analytics for Microsoft Excel, you must have installed the primary
interop assemblies (PIAs) for Excel. Typically, the PIAs are installed automatically when you install
Microsoft Office on the computer. However, in some cases you might need to install the PIAs separately.
Computer workstations must have the PIAs installed and registered in the global assembly cache to run
Office solutions that target .NET Framework.
You can install the complete set of PIAs in the global assembly cache in two ways:
• Modify the Microsoft Office setup.
If you did not install .NET Framework before you installed the Office system, the PIAs are not installed
with your Office installation. If you installed .NET Framework after you installed the Office system, you
can install the PIAs by modifying the Office setup.
• Install them from the redistributable PIA package.
The Microsoft Office PIAs are installed in the global assembly cache in drive:/WINDOWS/assembly or
drive:/WINNT/assembly.

Modify the Microsoft Office setup to install primary interop assemblies for
Excel
If you did not install .NET Framework before you installed the Office system, the PIAs are not installed
with your Office installation. If you installed .NET Framework after you installed the Office system, you
can install the PIAs by modifying the Office setup.

Before you begin

The Microsoft Office PIAs are installed in the global assembly cache in drive:/WINDOWS/assembly or
drive:/WINNT/assembly.
You must be an administrator on the computer to install the .NET Framework and the Microsoft Office
PIAs.

Chapter 12. Installing and configuring Planning Analytics for Microsoft Excel 201
 Procedure
1. From the Start menu, click Control Panel, and then click Programs and Features.
2. In the list of programs, click the Microsoft Office version, and then click Change.
3. In the Microsoft Office Setup wizard, select Add or Remove Features, and then click Continue.
4. In the Installation Options page, expand Microsoft Excel.
5. Click the symbol next to the .Net Programmability Support feature, and then click Run from my
computer.
6. Click Continue.
7. Click Close.

Install PIAs for Microsoft Excel

If you did not install .NET Framework before you installed the Office system, the PIAs are not installed
with your Office installation. You can install them from the redistributable PIA package.

Before you begin

Computer workstations must have the PIAs installed and registered in the global assembly cache to run
Office solutions that target the .NET Framework 4.5 or later.
The Microsoft Office PIAs are installed in the global assembly cache in drive:/WINDOWS/assembly or
drive:/WINNT/assembly.
You must be an administrator on the computer to install .NET Framework and the Microsoft Office PIAs.

Procedure
1. Ensure that .NET Framework is installed. For more information, see “Install Microsoft .NET
Framework” on page 201.
2. Go to the Microsoft download website.
3. Follow the instructions in the download page to install the primary interop assemblies.

Uninstall previous versions of IBM Cognos Analysis for Microsoft Excel

Previous versions of IBM Planning Analytics for Microsoft Excel were called IBM Cognos Analysis for
Microsoft Excel. If you have a version of Cognos Analysis for Microsoft Excel, you must uninstall it before
you can install the new version of IBM Planning Analytics for Microsoft Excel.
The uninstall does not completely remove all application files or directories during the uninstall process;
therefore, you may have to perform this action manually.
If you installed more than one component in the same location, you can choose the packages to uninstall
using the uninstall wizard. All components of the package will be uninstalled.

Before you begin

Before uninstalling, close all Microsoft Office applications.

Procedure
1. From the Start menu, click Programs, IBM Cognos for Microsoft Office, Uninstall IBM Cognos,
Uninstall IBM Cognos.
The Uninstall wizard appears.
Tip : IBM Cognos for Microsoft Office was the default name of the Program Folder that was created
during previous installations. If you chose another name, go to that folder to find the program.
2. Follow the instructions to uninstall the component.

202 IBM Planning Analytics: Installation and Configuration

 The cognos_uninst_log.txt file records the activities that the Uninstall wizard performs while
uninstalling files.
Tip : To find the log file, look in the Temp directory.
3. If you are upgrading to Planning Analytics for Microsoft Excel or migrating another version of Cognos
Analysis for Microsoft Excel, you must ensure that the Office Connection directory is removed
before installation. The Office Connection directory can be found at the following location:

C:\Users\<user name>\AppData\Local\Cognos\Office Connection

Connect to IBM Planning Analytics Workspace

Before users run Planning Analytics for Microsoft Excel, they must connect to an instance of Planning
Analytics Workspace.
Planning Analytics Workspace is required in order to use the set editor and the cube viewer.

Install TM1 Server

Some features of IBM Planning Analytics for Microsoft Excel require the use of TM1 Server. Install TM1
Server to ensure that you are getting the best experience with Planning Analytics for Microsoft Excel.
For information on installing TM1 Server, see “TM1 Server installation” on page 89.
Note : Planning Analytics for Microsoft Excel version 2.0.30 or later require TM1 Server version 2.0.3 or
later.

Set up connections for TM1 REST APIs

IBM Planning Analytics for Microsoft Excel requires the use of TM1 REST APIs. To enable these APIs in
IBM TM1 Server, an administrator may need to configure the HTTP port number in the IBM TM1 Server
configuration files for each TM1 Server.

Before you begin

When an IBM TM1 Server is created, the HTTP port number may not be set by default. This task requires
you to edit the configuration file for each IBM TM1 Server and set the HTTP port number. Contact your
administrator if you do not have access to the configuration file.

Procedure
1. Stop the TM1 Server
2. Locate the [Link] file. The location of the file may differ depending on the type of server you are
using.
3. Open the [Link] file in an editor.
4. Locate the line containing the following: HTTPPortNumber = XXXX.
5. Replace XXXX with a valid port number which is not currently in use.
6. Save the [Link] file.
7. Restart IBM TM1 Server

Results
IBM Planning Analytics for Microsoft Excel will have access to TM1 Server data through the TM1 REST
APIs.

Chapter 12. Installing and configuring Planning Analytics for Microsoft Excel 203
Configure your antivirus software
To run Planning Analytics for Microsoft Excel, you must first configure your antivirus software to allow
connections from both Microsoft .NET Runtime and Microsoft Excel.
If you do not configure your antivirus software to allow these two connections, an error message may
appear, as described in “COI-ERR-2019 Connection failed” on page 415.

Ensure that you are using IBMid

To use Planning Analytics for Microsoft Excel, you must enter your IBMid to authenticate yourself.
Tip : To register for your IBMid, go to the IBMid registration page ([Link]

Use Cognos security

(Deprecated in v2.0.9) To log in to Planning Analytics for Microsoft Excel with Cognos security
authentication enabled, you must meet certain requirements.
• Ensure that Planning Analytics for Microsoft Excel is pointing to the same Planning Analytics Workspace
URL as in the Cognos TM1 Operations Console.
• Update the [Link] and [Link] files to include the Planning Analytics Workspace URL.
• Ensure that the settings in the Cognos TM1 Operations Console are correct. For more information, see
“Configuring Cognos TM1 Operations Console to use Cognos security” on page 268.
If you do not configure Planning Analytics for Microsoft Excel for use with Cognos security, you might not
be able to log in to Planning Analytics for Microsoft Excel.

Installation tasks
Perform the tasks in this section to install Planning Analytics for Microsoft Excel.

Installing IBM Planning Analytics for Microsoft Excel

Installing IBM Planning Analytics for Microsoft Excel is fast and easy. You can download and run an
installation program to help you with this process.
IBM Cognos TM1 includes sample data, which you can use in Planning Analytics for Microsoft Excel. If you
want to use the samples, your IBM Cognos administrator must install the samples on the IBM Cognos
system.

Before you begin

Planning Analytics for Microsoft Excel is available as a 32-bit or 64-bit installation. The corresponding
installation must be installed on either the 32-bit or 64-bit version of Microsoft Office.
Tip : Consider using the 64-bit version of Microsoft Office and Planning Analytics for Microsoft Excel if you
anticipate performing large reporting activities.
Before you update and install components, ensure that the following statements are true:
• You have administrative privileges on the computer.
• Microsoft .NET Framework 4.6.1 or later is installed.
• Any previous version of IBM Planning Analytics for Microsoft Excel is uninstalled.
• If you are installing a version of Planning Analytics for Microsoft Excel that is older than the version
currently installed, back up your connection data. Replacing a newer version of Planning Analytics for
Microsoft Excel with an older version might cause your connection data to be lost.
• Acquire the appropriate license to use your IBM Cognos for Microsoft Office product.
• Configure your antivirus software to allow or unblock connections from the following two applications:

204 IBM Planning Analytics: Installation and Configuration

 – Microsoft .NET Runtime
– Microsoft Excel

Procedure
1. Close all Microsoft Excel windows.
2. Download and extract the installation program.
3. If you have the 32-bit version of Microsoft Office, browse to the win32 folder. If you have the 64-bit
version of Microsoft Office, browse to the winx64h folder.
4. Right-click the [Link] file and select Run as Administrator.
The Welcome page appears in a new window.
5. Select the language to use for the installation.
The language that you select determines the language of the installation user interface. The language
of the product user interface is defined by the display/primary language settings in Microsoft Windows.
6. In the Component Selection page, select Planning Analytics for Microsoft Excel.
7. Follow the directions in the installation wizard to copy the necessary files to your computer.

Test IBM Planning Analytics for Microsoft Excel

You can test the installation of the client components by starting the application.

Before you begin

For full access to IBM Planning Analytics for Microsoft Excel, you should be a member of the Express
Authors or Report Administrators role in IBM Cognos Analytics. An administrator must configure these
privileges using IBM Cognos Administration.

Procedure
1. Start Microsoft Excel or open a Microsoft Excel spreadsheet.
2. Confirm that IBM Planning Analytics appears in the ribbon.
If the IBM Planning Analytics tab is not displayed on the ribbon, see “The Cognos Office interface fails
to initialize in Microsoft Office ” on page 408.
3. Click the IBM Planning Analytics tab, and then click Task Pane.
The IBM pane is displayed.

What to do next
To start working with IBM Planning Analytics for Microsoft Excel, you must configure connections to IBM
Planning Analytics servers. See the IBM Planning Analytics for Microsoft Excel User Guide.

Uninstall IBM Planning Analytics for Microsoft Excel

This topic describes how you can uninstall the current version of IBM Planning Analytics for Microsoft
Excel.
If you installed more than one component in the same location, you can choose the packages to uninstall
using the uninstall wizard. All components of the package will be uninstalled.

Before you begin

Before uninstalling, close all Microsoft Office applications.

Chapter 12. Installing and configuring Planning Analytics for Microsoft Excel 205
 Procedure
1. From the Start menu, click Programs, IBM Planning Analytics for Microsoft Office, Uninstall IBM
Office Addins, Uninstall IBM Office Addins.
The Uninstall wizard appears.
Tip: IBM Planning Analytics for Microsoft Office is the default name of the Program Folder that is
created during the installation. If you chose another name, go to that folder to find the program.
2. Follow the instructions to uninstall the component.
You can find log files that record the uninstall process in the install_location/ibm/cognos/IBM
for Microsoft Office/instlog/ directory

Results
Planning Analytics for Microsoft Excel is uninstalled.
Note : The uninstall may not completely remove all application files or directories during the uninstall
process. You can remove the application files or directories manually, or edit the \uninstall
\[Link] file and set the RemoveAllCompsFlag parameter to 1 before running the uninstall
wizard.

Register the IBM Cognos Office Reporting TM1 Addin using a script
You can use a script to register the IBM Cognos Office Reporting TM1 Addin ([Link])
with Microsoft Excel. You can use a registry command or you can modify and then use the Register
Cognos [Link] script.

Register the IBM Cognos Office Reporting TM1 Addin using a registry
command
You can use a registry command to register the IBM Cognos Office Reporting TM1 Addin
([Link]) with Microsoft Excel.
The following sample script shows the basic registry command to add the [Link]
reference to Microsoft Excel.

[HKEY_CURRENT_USER\Software\Microsoft\Office\15.0\Excel\Options]
"OPEN"="/R \"C:\\Program Files\\IBM\\cognos\\Cognos for Microsoft
Office\\[Link]\""

Note : This is a sample only. You must modify the command to use the appropriate path and key for your
environment.

Register the IBM Cognos Office Reporting TM1 Addin using the Register
Cognos [Link] script
Cognos Analysis for Microsoft Excel provides a VBS script called Register Cognos [Link]. By
default, this script is set up to register [Link], which is the Cognos for Microsoft Office
Addin. You can modify this script to register the IBM Cognos Office Reporting TM1 Addin. You can then
run the script directly or include it in a deployment script.

Procedure
1. Go to the location where Cognos Analysis for Microsoft Excel is installed.
On Windows 7, the default installation location is C:\Program Files (x86)\IBM\cognos
\Cognos for Microsoft Office.
2. Create a backup copy of Register Cognos [Link].
3. Open the file Register Cognos [Link] in a text editor.
4. On line 19, set the path to the location of the [Link] file.

206 IBM Planning Analytics: Installation and Configuration

 For example:

path = "C:\Program Files (x86)\IBM\cognos\Cognos for Microsoft Office\”

5. On line 20, replace [Link] with [Link].

For example:

file = "[Link] "

6. Save the file.

Configure IBM Planning Analytics for Microsoft Excel for use with high DPI
displays
If you are using IBM Planning Analytics for Microsoft Excel version 2.0.53 or earlier, you may need to
configure your display settings to ensure that elements are rendered properly on high DPI displays.

About this task

Missing elements can include but are not limited to the IBM Task Pane and the Overview Area. For more
information, see Office support for high definition displays. The Optimize for compatibility option is
enabled by default, starting in Planning Analytics for Microsoft Excel version 2.0.54.

Procedure
1. Open Microsoft Office.
2. Click File > Option > General.
3. Select Optimize for compatilitiy.
4. Click OK.
5. Restart the application.

Configure Planning Analytics for Microsoft Excel single sign-on

Planning Analytics for Microsoft Excel allows you to use single sign-on for your convenience. This topic
shows you how to configure Planning Analytics for Microsoft Excel to use single sign-on.

About this task

Planning Analytics for Microsoft Excel supports single sign-on modes 2,3, and 5. You may have to
configure Planning Analytics for Microsoft Excel differently, depending on the single sign-on mode you
use.
Mode 2
Single sign-on mode 2 allows you to choose between native or Windows login.
Single sign-on mode 2 is configured in Planning Analytics Workspace. See the following topic to
configure single sign-on mode 2: “Connect to TM1 and authentication servers” on page 165
Mode 3
Single sign-on mode 3 uses Windows login by default.
Single sign-on mode 3 is configured in Planning Analytics Workspace. See the following topic to
configure single sign-on mode 3: “Connect to TM1 and authentication servers” on page 165
Mode 5
Single sign-on mode 5 uses CAM. Use mode 5 if you're using IBM® Cognos security for authentication.
Planning Analytics for Microsoft Excel single sign-on mode 5 requires some files to be dropped into
the IBM Cognos Analytics Gateway installation location and some configuration settings to be
implemented. Planning Analytics for Microsoft Excel requires an instance of Cognos Analytics

Chapter 12. Installing and configuring Planning Analytics for Microsoft Excel 207
 Gateway for a dedicated entry point. This Cognos Analytics Gateway instance must be enabled
according to the steps described in . This ensures that the Gateway installation is supplemented by
the three files that are required ([Link], [Link], and variables_plan.xml).
The required files are included in the bi_interop.zip file that is located in the directory <TM1
installation location>\bi_interop.
Procedure:
1. On the Cognos Analytics Gateway installation that is selected for the Planning Analytics for
Microsoft Excel entry point, navigate to Cognos_root\templates\ps\portal\ where
Cognos_root is the installation location of Cognos Analytics.
2. Open the file variables_plan.xml.
3. Verify that the <url>../[Link]</url> tag exists below <url>../
[Link]</url>.
The following text is an example of the variables_plan.xml file:

<?xml version="1.0" encoding="UTF-8"?>

<CRNenv>
<urls>
<url>../[Link]</url>
<url>../[Link]</url>
</urls>
<cookies>
<param name="cam_passport"/>
<param name="CRN"/>
</cookies>
</CRNenv>

4. Close the file.

5. Navigate to Cognos_root\webcontent where Cognos_root is the installation location of Cognos
Analytics.
6. Open [Link] to edit it.
7. Add the fully qualified Planning Analytics Workspace domain name and port number (if applicable).
This enables SSO to operate.
8. Make sure that the user account that is running the web server has permission to access
[Link]. If you cannot access the [Link] in a web browser, check the [Link] file
properties.

Troubleshoot
Use troubleshooting information as a resource to help you solve specific problems you may encounter
during or after the installation of IBM Planning Analytics for Microsoft Excel.
For more information, see “What are some common errors when installing Planning Analytics for
Microsoft Excel?” on page 407

208 IBM Planning Analytics: Installation and Configuration

Chapter 13. IBM Planning Analytics TM1 Web
installation
You can install IBM Planning Analytics TM1 Web on a computer that is separate from the computer where
you installed the TM1 database and other TM1 or Planning Analytics components.
Note : As of the 2.0.55 SC release of IBM Planning Analytics in July 2020, TM1 Web is installed with the
IBM Planning Analytics Spreadsheet Services installer. TM1 Web is no longer part of the web tier within
the Planning Analytics Local installer.
This documentation describes how to install TM1 Web with the IBM Planning Analytics Spreadsheet
Services installer. If you need details on installing TM1 Web as part of the web tier within the Planning
Analytics Local [Link] LC or earlier, see Chapter 8, “Installing the Web Tier,” on page 119.
For a list of frequently asked questions about the TM1 Web deployment introduced with the 2.0.55 SC
release, see Changes to TM1 Web deployment.
For conformance documentation that describes compatibility between versions of Planning Analytics TM1
Web, Planning Analytics for Microsoft Excel, and Planning Analytics Workspace, see IBM Planning
Analytics TM1 Web conformance requirements.

Check for changes to [Link] file

If you are upgrading IBM Planning Analytics TM1 Web to a new version, you install a new version of the
[Link] file called [Link] and your existing [Link] file is preserved.
To take advantage of fixes applied in the new release, you must use the [Link] file and you must
reapply any changes that you made to your previous configuration settings. In particular, restore your
values for session-timeout.
1. Back up the existing [Link] file in <installation_location>/webapps/tm1web/WEB-INF. For
example, rename [Link] to [Link]. This step backs up your current settings.
2. Rename [Link] to [Link]. This step uses the new version of [Link] that is supplied with
the latest version of TM1 Web.
3. Replace the entry for session-timeout in [Link] with the entry from [Link]. This step
restores any changes that you made to this property previously.
For example:

<session-config>
<session-timeout>20</session-timeout>
</session-config>

Install TM1 Web

The following items are an overall checklist for installing TM1 Web.
1. Check prerequisites.
2. Install TM1 Web.
3. Start the IBM Planning Analytics Spreadsheet Services service.
4. Run and test TM1 Web from your network environment.
5. Edit the TM1 Web configuration file to support a multiple computer environment.
6. Configure the TM1 Web login page using AdminHostName and TM1ServerName parameters.
7. Configure authentication and data transmission security.
8. Modify TM1 Web configuration parameters.

© Copyright IBM Corp. 2007, 2021 209

 9. Configure the web browsers in your environment.
10. Configure JVM settings for TM1 Web/Planning Analytics Spreadsheet Services.

Installing TM1 Web

You can install TM1 Web on a separate computer and deploy it with the instance of WebSphere® Liberty
web application server that is provided with the installation.
After you have installed TM1 Web on the separate computer, edit the TM1 Web configuration file to
identify the remote computer where the TM1 Admin Server is running.

Install and configure TM1 Web on Microsoft Windows

These steps describe how to install TM1 Web on a separate computer that is running Microsoft Windows.
These steps apply when you are using the provided WebSphere Liberty application server.

Procedure
1. The IBM Planning Analytics Spreadsheet Services installer for TM1 Web is delivered in a .zip archive.
The zip archive contains two files: the repository for TM1 Web and the IBM Planning Analytics
Spreadsheet Services installer.
Extract the contents of the zip file into a single separate directory.
2. Run the IBM Planning Analytics Spreadsheet Services installer.
3. Select your installation language and click Next.
4. Select IBM Planning Analytics Spreadsheet Services and click Next.
5. Accept the license agreement and click Next.
6. Specify the Installation location and Shortcut folder, then click Next.
The default installation location is C:\Program Files\ibm\cognos\tm1web.
The default shortcut folder is IBM Planning Analytics Spreadsheet Services. You can optionally
choose to make the shortcut visible to user on the Windows Start menu.
7. Review the Pre-installation Summary, then click Install.
8. Click OK when you view the Pre-Installation Action message.
9. Click Done when installation is complete.
10. Click OK when you view the Post-Installation Action message.

Results
If you had previously installed TM1 Web as part of a Planning Analytics web tier installation, the
tm1web_config.xml file is copied to the new installation location, preserving your configuration
settings.
The installation creates a new service named IBM Planning Analytics Spreadsheet Services. The service is
configured with an Automatic startup type, but is not started as part of the installation process. You
should review the tm1web_config.xml file and confirm configuration before starting the IBM Planning
Analytics Spreadsheet Services service and using TM1 Web.
If you had previously installed TM1 Web as part of a Planning Analytics web tier installation, the TM1 Web
service was named IBM Cognos TM1. This service is disabled and set to Manual startup when you install a
new version of TM1 Web with the IBM Planning Analytics Spreadsheet Services installer.
Note : After installing TM1 Web, you might receive an error when validating your configuration with the
IBM Planning Analytics Workspace Administration tool. The error indicates that the TM1 Application
Server Gateway cannot be found.

210 IBM Planning Analytics: Installation and Configuration

This error is the result of an attempt to verify the presence of pmhub. As TM1 Web does not use pmhub,
you can dismiss this error and continue using your applications.

Configure and run unattended TM1 Web installations on Windows

You can set up an unattended installation and configuration to install an identical configuration of TM1
Web across several computers on your network.

About this task

An unattended installation requires you to create a response file, which is generated based on your
responses to a regular graphic installer. The responses you provide during the graphic installation are
applied to all unattended installations.

Procedure
1. Create a response file to be used for unattended installations by running the IBM Planning Analytics
Spreadsheet Services graphic installer from a command line with this command: analytics-
[Link] -DREPO=<TM1 Web repository name> -r
<FullPathOfYourResponseFile>.
2. Complete all steps required to complete the installation.
3. To run an unattended installation, run this command from a command line: analytics-installer-
[Link] -DREPO=<TM1 Web repository name> -f
<FullPathOfYourResponseFile> -i silent.

Chapter 13. IBM Planning Analytics TM1 Web installation 211

Install and configure TM1 Web on Linux
These steps describe how to install TM1 Web on a separate computer that is running Linux. These steps
apply when you are using the provided WebSphere Liberty application server.

Procedure
1. The IBM Planning Analytics Spreadsheet Services installer for TM1 Web is delivered in a .gz archive.
The .gz archive contains two files: the repository for TM1 Web and the IBM Planning Analytics
Spreadsheet Services installer.
Extract the contents of the .gz archive into a single separate directory.
2. Run the IBM Planning Analytics Spreadsheet Services installer, analytics-installer-nnnn-
[Link].
3. Select your installation language and click Next.
4. Select IBM Planning Analytics Spreadsheet Services and click Next.
5. Accept the license agreement and click Next.
6. Specify the Installation location, then click Next.
The default installation location is /opt/ibm/cognos/tm1web.
Note : If you have previously installed TM1 Web as part of the web tier in a multi-component Planning
Analytics installation, you must install to a different location when initially installing TM1 Web with
the IBM Planning Analytics Spreadsheet Services installer.
7. Review the Pre-installation Summary, then click Install.
8. Click OK when you view the Pre-Installation Action message.
9. Click Done when installation is complete.
10. Click OK when you view the Post-Installation Action message.

Configure and run unattended TM1 Web installations on Linux

You can set up an unattended installation and configuration to install an identical configuration of TM1
Web across several computers on your network.

About this task

An unattended installation requires you to create a response file, which is generated based on your
responses to a regular graphic installer. The responses you provide during the graphic installation are
applied to all unattended installations.

Procedure
1. Create a response file to be used for unattended installations by running the IBM Planning Analytics
Spreadsheet Services graphic installer from a command line with this command: analytics-
[Link] -DREPO=<TM1 Web repository name> -r
<FullPathOfYourResponseFile>.
2. Complete all steps required to complete the installation.
3. To run an unattended installation, run this command from a command line: analytics-installer-
[Link] -DREPO=<TM1 Web repository name> -f
<FullPathOfYourResponseFile> -i silent.

Example
For example, a full command to run a silent install looks like this:
[Link] -DREPO=/workspace/install/
[Link] -f /workspace/install-props/
[Link] -i silent

212 IBM Planning Analytics: Installation and Configuration

Configuring SSL for Planning Analytics TM1 Web/Spreadsheet Services
When configuring SSL for TM1 Web/Spreadsheet services, custom key stores and certificates should be
stored in a directory outside of the installation directory. A directory "next to" (at the same level as) the
installation directory is recommended.
For example if your installation directory is C:\Program Files\ibm\cognos\tm1web, the key stores
and certificates could be placed in C:\Program Files\ibm\cognos\certificates.
This is necessary because the TM1 Web/Spreadsheet upgrade process removes most files under the
installation directory, preserving only selected files. Placing the certificates outside the installation
directory ensures that they are not deleted during an upgrade.

Configure SSL for new deployments of Planning Analytics TM1 Web/

Spreadsheet Services
You can configure the SSL settings for new deployments of Planning Analytics TM1 Web/Spreadsheet
Services.
Planning Analytics TM1 Web/Spreadsheet Services does not include a user interface for generating and
configuring SSL. To configure the SSL for a new deployment of Planning Analytics, you need to enable SSL
communication in WebSphere Liberty and your associated JRE. For more information, see Enabling SSL
communication in Liberty. You can also see Configuring the Java Runtime Environment to use SSL for an
example of JRE configuration.
You can copy the default or generated materials, such as the keystore file or key stash file, from your TM1
deployment environment. Alternatively you can also install IBM Cognos TM1 Web [Link], generate or
configure the SSL using the included UI tools, and then update that installation to Planning Analytics
Spreadsheet Services.
For more information on configuring SSL in Planning Analytics, see the following links:
• How to Configure SSL on Planning Analytics Data Tier using GSKit (New Certificate Signing Request)
• How to Configure SSL on Planning Analytics Web Tier using GSKit (Using Existing Signed Certificate)
• How to Configure Custom SSL Certificates for Planning Analytics 2.0 and 2.0.1
• Configure the Web Tier to use custom TLS

Configure SSL for Planning Analytics TM1 Web/Spreadsheet Services with

an existing keystore
These procedures let you secure TM1 Web/IBM Planning Analytics Spreadsheet Services using a custom
keystore.

About this task

The following conditions must be met before you can configure SSL for TM1 Web/IBM Planning Analytics
Spreadsheet Services:
• Your keystore/certificate file must already be in PKCS12/PFX format and contain the complete
certificate chain.
• The file must be placed in a location outside the IBM Planning Analytics Spreadsheet Service
installation directory. A directory "next to" (at the same level as) the installation directory is
recommended. For example if your installation directory is C:\Program Files\ibm\cognos
\tm1web, the file could be placed in C:\Program Files\ibm\cognos\certificates.
• In this document, we use the path C:\Program Files\ibm\cognos\certificates to refer to the
location of your keystore file, and C:\Program Files\ibm\cognos\certificates
\[Link] as the file path for your keystore file. Your actual file path will differ.
• The file must be placed in the <install_dir>\tm1web\bin64\ssl\ directory.

Chapter 13. IBM Planning Analytics TM1 Web installation 213

 • The IBM Planning Analytics Spreadsheet Service must be stopped before you can proceed with
configuration.
You must also know the location of the following items before executing the keytool command:
• [Link] - located in <install_dir>\tm1web\jre\bin\
• [Link] - located in <install_dir>\tm1_64\bin64\ssl

Procedure
1. Configure the Planning Analytics Spreadsheet Services service with a custom keystore.
a) Open Windows Services and check the status of your IBM Planning Analytics Spreadsheet Services.
If the service is running, stop it before you proceed to the next step.

b) Open <install_dir>\tm1web\wlp\usr\servers\tm1web\[Link] in a text editor.

c) Update the httpPort and httpsPort parameters to reflect the ports you would like to use. To
disable HTTP altogether, set httpPort="-1". For example,

<httpEndpoint id="defaultHttpEndpoint" httpPort="-1" httpsPort="9510" host="*"

removeServerHeader="true">
</httpEndpoint>

d) In [Link], replace the existing keyStore entry with:

<keyStore id="defaultKeyStore" location="C:\Program Files\ibm\cognos\certificates

\[Link]" password="your_password" />

If [Link] does not have a keyStore entry, add the following line immediately following the
last <application> tag in [Link]:

<keyStore id="defaultKeyStore" location="C:\Program Files\ibm\cognos\certificates

\[Link]" password="your_password" />

e) Save and close the [Link] file.

f) Open a Command Prompt as an administrator, then go to <install_dir>\tm1web\jre\bin\.
g) Because TM1 Web is using a new keystore, you must include the TM1 Server certificates in the
keystore file. If the TM1 Server certificates are not present, you can't see your TM1 Servers in TM1
Web. Execute the following command:

keytool -importcert -keystore "C:\Program Files\ibm\cognos\certificates

\[Link]" -storepass your_password -storetype pkcs12 -noprompt -alias ibmtm1 -
file ..\..\bin64\ssl\[Link]

h) If you communicate with any other TM1 Servers or applications that use different certificates, you
must repeat the previous step, importing any additional certificates you require.
i) Restart IBM Planning Analytics Spreadsheet Services in Windows Services.
2. Validate your SSL configuration.
The following validation steps apply to the Chrome web browser. If you are using another browser,
you'll need to adjust the steps as necessary.
a) After the IBM Planning Analytics Spreadsheet Services service starts, access your TM1 Web URL
using Chrome, for example: [Link]
You may encounter a warning. If you do, it is likely because you haven't told your computer to trust
the Root Certificate Authority and Intermediate Certificate Authority that are used to sign the
Planning Analytics certificate. To resolve the untrusted certificate warning, see the following
technote: [Link]
b) If your certificates are valid and trusted, you should see something similar to this on the Security
tab of the Chrome developer tools:

214 IBM Planning Analytics: Installation and Configuration

 c) If you don't see a particular TM1 Server in your list of servers in TM1 Web, you may not have
imported the TM1 Server certificate in to your keystore. Please see step 1h above for details on
importing TM1 Server certificates to your keystore.

Relocating custom SSL files

If you have installed custom SSL files in a location under the IBM Planning Analytics Spreadsheet Service
installation directory, you must relocate these files to a directory outside the installation directory and
update your [Link] to the new location. This ensures that the files are not deleted during an upgrade
and the installation continues to work correctly after upgrade.

About this task

This procedure assumes that the outside directory is C:\Program Files\ibm\cognos
\certificates and your custom SSL keystore file is [Link]. The full path for the
relocated file is thus C:\Program Files\ibm\cognos\certificates\[Link].

Procedure
1. Open Windows services and check the status of your IBM Planning Analytics Spreadsheet Services. If
the service is running, stop it before you proceed to the next step.
2. Move the custom key store and other files to the new location.

Chapter 13. IBM Planning Analytics TM1 Web installation 215

 For example if your custom key store is at <install_dir>\tm1web\bin64\ssl
\[Link], you would move that file to C:\Program Files\ibm\cognos
\certificates\[Link].
If you located any other custom SSL files such as certificates under <install_dir>, you should also move
those files to the external location so they are not deleted by an upgrade.
3. Edit the [Link] to use the new location of the custom key store.
a) Open <install_dir>\tm1web\wlp\usr\servers\tm1web\[Link] in a text editor.
b) Find the keyStore configuration line, which may look like:

<keyStore id="defaultKeyStore" location="${[Link]}/../../bin64/ssl/

[Link]" password="your_password" />

c) Change the location in that line to reference the new location of the key store using the full path, for
example:

<keyStore id="defaultKeyStore" location="C:/Proram Files/ibm/cognos/certificates/

[Link]" password="your_password" />

d) Save and close [Link].

4. Validate your SSL configuration as described in “Configure SSL for Planning Analytics TM1 Web/
Spreadsheet Services with an existing keystore” on page 213.

Upgrade IBM Planning Analytics TM1 Web

Whether you have never installed TM1 Web before or are performing an upgrade, the installation
procedure is identical.
However, you should be aware of these issues when performing an upgrade.
Upgrading from a previous Planning Analytics web tier installation
If you had previously installed TM1 Web as part of a Planning Analytics web tier installation, the TM1
Web service was named IBM Cognos TM1. This service is disabled and set to Manual startup when
you install a new version of TM1 Web with the IBM Planning Analytics Spreadsheet Services installer.
If you had previously installed TM1 Web as part of a Planning Analytics web tier installation, the
tm1web_config.xml file is copied to the new installation location, preserving your configuration
setting.
TM1 Application Web (pmpsvc) configuration
The IBM Planning Analytics Spreadsheet Services installer includes only TM1 Web and the evaluation
service. If you use TM1 Application Web, you must configure it to use the correct ports to connect to
TM1 Web. See “Configure TM1 Application Web to connect to TM1 Web on Windows” on page 216 or
“Configure TM1 Application Web to connect to TM1 Web on Linux” on page 217, depending on your
environment.

Configure TM1 Application Web to connect to TM1 Web on Windows

If you upgrade to TM1 Web 2.0.54 SC or later from a previous version of TM1 Web that was installed as
part of the web tier in a multi-component Planning Analytics installation, you must configure TM1
Application Web (pmpsvc) to maintain the connection between TM1 Application Web and the TM1 Web
server. This configuration is not necessary if you don’t use TM1 Application Web.

About this task

Previously, TM1 Web was released coincidental with the Planning Analytics TM1 Server. In this scenario,
TM1 Web was installed as part of the web tier in a large, multi-component Planning Analytics installation.
As of Planning Analytics 2.0.55 SC, TM1 Web is installed independent of other components using the IBM
Planning Analytics Spreadsheet Services installer.

216 IBM Planning Analytics: Installation and Configuration

This configuration is necessary only when you upgrade from a large, multi-component Planning Analytics
installation to a new version of TM1 Web using the IBM Planning Analytics Spreadsheet Services installer.
The configuration described here is not necessary when upgrading from one Planning Analytics TM1 Web
[Link] SC version to a later [Link] SC version.

Procedure
1. After you complete your TM1 Web installation, open Windows Services.

The IBM Cognos TM1 service is the old version of TM1 Web that was installed with a prior multi-
component Planning Analytics installation. Note that this service is disabled and the startup type is
Manual.
The IBM Planning Analytics Spreadsheet Services service is the new version of TM1 Web that was
installed using the IBM Planning Analytics Spreadsheet Services installer. This service is not running
and the startup type is Automatic.
Note : If the IBM Planning Analytics Spreadsheet Services service is running, stop it before
proceeding. Keep the Windows Services open, you'll return to it shortly.
2. Open the [Link] file located in the C:\Program Files\ibm\cognos\tm1web\wlp\usr
\servers\tm1web directory.
Note : You must open and save the [Link] file as an administrator.
3. Change the httpPort attribute value within the httpEndpoint element from 9510 to 9511, then
save the [Link] file.
Note : If your httpPort attribute value is other than 9510, change it to a different unique value and
take note of the port number. You'll need it later in the configuration process.
4. In Windows Services, start both the IBM Planning Analytics Spreadsheet Services and IBM Cognos
TM1 services.
5. Log in to IBM TM1 Application Web.
6. Click the Settings icon on the My Applications screen.
7. Click the General tab.
8. Select tm1web under Clients and click Edit.
9. Change the URL to [Link] If you set the
httpPort attribute to a value other than 9511 in step 3, substitute that value for the localhost:
port number.
10. Click OK.
11. Log out of IBM TM1 Application Web.
12. Log in to IBM TM1 Application Web again.

Configure TM1 Application Web to connect to TM1 Web on Linux

If you upgrade to TM1 Web 2.0.54 SC or later from a previous version of TM1 Web that was installed as
part of the web tier in a multi-component Planning Analytics installation, you must configure TM1
Application Web (pmpsvc) to maintain the connection between TM1 Application Web and the TM1 Web
server. This configuration is not necessary if you don’t use TM1 Application Web.

Chapter 13. IBM Planning Analytics TM1 Web installation 217

 About this task
Previously, TM1 Web was released coincidental with the Planning Analytics TM1 Server. In this scenario,
TM1 Web was installed as part of the web tier in a large, multi-component Planning Analytics installation.
As of Planning Analytics 2.0.55 SC, TM1 Web is installed independent of other components using the IBM
Planning Analytics Spreadsheet Services installer.
This configuration is necessary only when you upgrade from a large, multi-component Planning Analytics
installation to a new version of TM1 Web using the IBM Planning Analytics Spreadsheet Services installer.
The configuration described here is not necessary when upgrading from one Planning Analytics TM1 Web
[Link] SC version to a later [Link] SC version.

Procedure
1. After you complete your TM1 Web installation, go to the /opt/ibm/cognos/tm1web/bin64
directory.
2. Run ./[Link].
3. Open the [Link] file located in the /opt/ibm/cognos/tm1web/wlp/usr/servers/
tm1web directory.
Note : You must open and save the [Link] file as an administrator.
4. Change the httpPort attribute value within the httpEndpoint element from 9510 to 9511, then
save the [Link] file.
Note : If your httpPort attribute value is other than 9510, change it to a different unique value and
take note of the port number. You'll need it later in the configuration process.
5. In /opt/ibm/cognos/tm1web/bin64, run ./[Link].
6. Log in to IBM TM1 Application Web.
7. Click the Settings icon on the My Applications screen.
8. Click the General tab.
9. Click Add under Server Names.
10. Enter [Link] in the Admin Host box, then click OK.
11. Select tm1web under Clients and click Edit.
12. Change the URL to [Link] If you set the httpPort attribute to a
value other than 9511 in step 4, substitute that value for the localhost: port number.
13. Click OK.
14. Log out of IBM TM1 Application Web.
15. Log in to IBM TM1 Application Web again.

Results
You can now connect to the new installation of TM1 Web from TM1 Application Web.

Modifying TM1 Web configuration parameters

The tm1web_config.xml file is an XML file that contains configuration parameters for TM1 Web.
The parameters in this file control the following IBM TM1 Web features.
• View node
• Cube Viewer page size
• Number of sheets to export from a Cube Viewer
• IBM TM1 Web startup and appearance settings
• Session timeouts

218 IBM Planning Analytics: Installation and Configuration

TM1 Web configuration parameters
The configuration parameters for IBM Planning Analytics TM1 Web are stored in the
tm1web_config.xml file.
The tm1web_config.xml file is located in the following location:
<TM1 install location>\webapps\tm1web\WEB-INF\configuration\
The following parameters are available.
ActionButtonFullRecalculationEnabled
Determines the level of recalculation that occurs as part of the execution of an action button. This
parameter is only applicable to action buttons that use Automatically Recalculate Sheet as the
Calculation type.
If set to true, a full recalculation occurs on the target workbook.
If set to false, a partial recalculation occurs on the target workbook. Only the visible portions of the
target workbook are recalculated. This recalculation includes any Active Forms, DBS/DBSW/DBR/
DBRW/DBRA/DBSA formulas, and dependencies of cells in the visible area. Any portions beyond the
scrolling boundary of the target workbook are not recalculated. False is the default value, which can
result in improved performance, especially in large workbooks.
AdminHostName
If set, users are not asked to enter a value for Admin Host during login.
See “Configuring the TM1 Web login page using AdminHostName and TM1ServerName parameters”
on page 225.
AdminHostPort
If set, the client tries to use this port instead of the default Admin Host port.
AdminHostSSLPort
If set, the client tries to use this port instead of the default Admin SSL Host port.
CamLoginApiRedirectEnabled
Default value is false.
When enabled, CAM authentication from the TM1 Web API (either URL API or JavaScript Library)
performs a redirect to the CAM login page of Cognos Analytics. This behavior differs from the default
behavior of showing CAM login page of Cognos Analytics in a dialog box. This parameter must be
enabled in cases where Cognos Analytics includes an X-Frame-Options header with a value of
SAMEORIGIN or DENY, which is used to improve protection against Click-jacking attacks.
CleanDimensionMetaDataCache
During websheet calculation, the CleanDimensionMetaDataCache parameter specifies whether
dimension elements are retrieved from the TM1 Server or by using cached elements from TM1 Web.
Default value: false
• If CleanDimensionMetaDataCache is set to false, elements from the tm1web cache are used.
• If CleanDimensionMetaDataCache is set to true: tm1web dimension elements are cleaned from the
cache and the elements are retrieved directly from the TM1 Server.
CrossDomainAccessList
Specifies a list of cross-domain URLs that are allowed to access TM1 Web.
You can use this parameter to specify the domain where IBM Cognos Workspace is running, if it's
running on a domain separate from TM1 Web.
Use an asterisk (*) to allow any domain to access TM1 Web.
If you specify multiple URLs, separate each one by using a comma.

Chapter 13. IBM Planning Analytics TM1 Web installation 219

 If this parameter is not set or the parameter value is empty, no cross-domain access to TM1 Web is
allowed.
CubeViewerColumnPageSize
Specifies the number of columns to fetch in a page of Cubeviewer.
See “Changing the Cube Viewer page size” on page 233.
CubeViewerHiddenDimensionsEnabled
Hides dimensions in the TM1 Web cube viewer.
Hidden dimensions are part of the context of a view, but do not show up as context dimensions in the
TM1 Web cube viewer. Instead, they reside in a region of the dimension bar labeled Hidden.
To use hidden dimensions in the TM1 Web cube viewer, you must set
CubeViewerHiddenDimensionsEnabled" ="true" in the tm1web_config.xml file. When the
feature is enabled, the Hidden region appears on the cube viewer.
You can drag dimensions to and from the Hidden region just as you can for the Rows, Columns, and
Context regions.
When a view includes hidden dimensions, the number of hidden dimensions is displayed below the
Hidden label. When you click the Hidden region, you can see which dimensions and elements are
hidden.
You cannot change the element for a hidden dimension. If you want to change an element, you must
show the dimensions by dragging it to the Rows, Columns, or Context region, and then change the
element. You can then return the dimension to the hidden region.
CubeViewerRowPageSize
Specifies the number of rows to fetch in a page of Cubeviewer.
See “Changing the Cube Viewer page size” on page 233.
CubeviewerStringWrap
Settings for string cell wrapping in the Cubeviewer.
See “Wrapping string values in cube views” on page 234.
CustomCAMLogoutUrl
Specifies the URL of a dedicated Logout page for CA SiteMinder when TM1 Server is configured to use
CAM security (mode 4 or 5). This Logout page must be accessed on logout so that the SiteMinder
session cookie can be invalidated.
When a user clicks Logoff in TM1 Web, the CAM logout occurs first. Then, the SiteMinder Logout page
is called.
EvaluationServiceURL
Specifies the location of the evaluation service. The evaluation service is included with IBM Planning
Analytics Spreadsheet Services. It is used for rendering quick reports within TM1 Web and Planning
Analytics websheets.
Valid value is hostname:port_number.
If no value is assigned, the default value is assumed to be [Link]
ExportCellsThreshold
Specifies the maximum number of cells that an export of a websheet or a cube view can contain. If the
number of selected cells exceeds the threshold, a warning message is displayed and the export does
not start.
As of IBM Planning Analytics version 2.0.7, the default value is 1000000.
Edit the ExportCellsThreshold parameter in the tm1web_config.xml file by using the following
format:

<add key="ExportCellsThreshold" value="CellsThreshold" />

220 IBM Planning Analytics: Installation and Configuration

 where CellsThreshold is the cell count threshold that is determined by multiplying the number of
rows by the number of columns per sheet, and then multiplying that result by the number of iterations
and context members that the export is selected for.
For example, if a websheet has two sheets and each sheet has 1000 rows and 25 columns, and the
export is selected for four context members, the cell count is calculated as 25,000 * 2 sheets * 4
context members = 200,000 cells. If the <CellsThreshold> is 150, 000, this websheet export would
be rejected.
ExternalUrl
Set the ExternalUrl parameter if you are using TM1 Web and Cognos security (CAM) authentication
with an external load balancer that modifies the original startup URL for TM1 Web. The ExternalUrl
parameter provides the correct URL so that Cognos security can successfully redirect back to TM1
Web.
Set the value to the same URL that you use to start TM1 Web, for example

<add key="ExternalUrl" value="[Link] />

GzipCompressionEnabled
Determines whether the web server responses will be compressed. Valid values are true/false.
HideCubeviewerToolBar
If set to true, all Cubeviewer toolbars are not displayed.
See “HideCubeviewerToolBar parameter” on page 232.
HideTabBar
If set to true, multiple tabs are not displayed.
See “HideTabBar parameter” on page 231.
HideWebsheetToolBar
If set to true, all websheet toolbars are not displayed.
See “HideWebsheetToolBar parameter” on page 232.
HomePageObject
If set, the object of type of websheet, Cubeviewer, or URL will be displayed after a user logs in.
See “Configuring a global homepage for all users” on page 228.
HttpSessionTimeout
This parameter defines the session timeout (in minutes) of the HTTP session for TM1 Web. If the
parameter is missing, the value is less than 1, blank, or not a numerical value, the default session
timeout that is defined for TM1 Web in the [Link] file is used.
See “Setting the TM1 Web session timeout” on page 234.
Note : As of IBM Planning Analytics Local version 2.0.6, you should not change the session-
timeout value in the [Link] file.
LegacyUrlApiSessionDiscoveryEnabled
Use the LegacyUrlApiSessionDiscoveryEnabled configuration parameter to control how the
TM1 Web URL API handles login sessions. Configure this parameter to specify whether the URL API
tracks separate unique login sessions.
This parameter enables the URL API session to be reused based on the specified admin host, TM1
Server, and (optional) user name.
If you are using the session token login approach with the URL API, you must set the
LegacyUrlApiSessionDiscoveryEnabled configuration parameter in the tm1web_config.xml
file to False.
See TM1 Web API session login.
Use this format:

Chapter 13. IBM Planning Analytics TM1 Web installation 221

 <add key="LegacyUrlApiSessionDiscoveryEnabled" value=True or False/>
For example:
<add key="LegacyUrlApiSessionDiscoveryEnabled" value="False"/>
The default value is True.
• True
TM1 Web tries to match new login request with an existing login session based on the provided
information (TM1 Admin host, TM1 Server, user name).
This parameter should be set to True only if a single login will occur for a unique TM1 Admin Host,
TM1 Server, and user name combination.
• False
Specifies that a session token must be provided every time that you open a TM1 Web object with the
TM1 Web URL API. Otherwise, the user is prompted.
Set this parameter to False if you plan to use multiple login sessions with TM1 Web URL API. You
also use this configuration if you are using multiple login sessions with the URL API and other TM1
Web clients such as TM1 Web and TM1 Application Web. This configuration uses the session token
to keep the user sessions separate and unique.
MaximumConcurrentExports
Specifies the maximum number of concurrent exports that can be executed from TM1 Web. The
default value is 5.
Before IBM Planning Analytics version 2.0.7, the default value is 5.
As of IBM Planning Analytics version 2.0.7, the default value is 4.
You can set MaximumConcurrentExports to 0 to allow an unlimited number of concurrent exports.
This setting is analogous to export behavior in TM1 Web before version 10.3.
If the maximum number of concurrent exports is reached, and more exports are then initiated, the
additional exports are queued until an export slot is available. The initiator of a queued export does
not receive notification of queuing.
The optimal parameter setting depends on your RAM capacity and your user requirements. Generally,
the more RAM you have available to TM1 Web, the higher the parameter setting can be. Increasing the
value results in increased memory consumption, but reduces export queuing. (Setting the parameter
to 0 eliminates export queuing.) Conversely, decreasing the parameter value reduces memory
consumption that results from exports, but can result in more frequent export queuing.
MaximumSheetsForExport
Specifies the maximum number of sheets that are allowed to export.
Before IBM Planning Analytics version 2.0.7, the default value is 100.
As of IBM Planning Analytics version 2.0.7, the default value is 50.
See “Setting the maximum number of sheets to export from a websheet” on page 233.
MixedCellPaste
If the MixedCellPaste parameter is set to true, when you copy values to a mixed range of leaves and
consolidated values in a websheet, the pasted values match exactly. The default value is False.
Note : This parameter applies to websheets only; it does not apply to CubeViewer.
NavTreeCollapsedOnStart
Determines whether the navigation panel will be collapsed or expanded after a user logs in.
See “NavTreeCollapsedOnStart parameter” on page 231.
NavTreeDisplayServerView
Specifies whether to display the Server View node in the navigation tree. Valid values are Y and N.

222 IBM Planning Analytics: Installation and Configuration

 See “Displaying or hiding the Views node in the navigation pane” on page 232.
NavTreeHidden
Determines whether the navigation panel will be displayed after a user logs in.
See “NavTreeHidden parameter” on page 230.
RecalcOnActivate
If RecalcOnActivate is set to true, a recalculation is performed each time a websheet or cubeview is
activated in TM1 Web, for example, when you switch tabs.
Valid values are true or false.
RecalcOnDataValidationChange
Specifies whether the default recalculation behavior will be overridden when you change the value of
a data validation list.
If set to true, a recalculation will be triggered when a value in a data validation list is changed.
If set to false, a recalculation will not be triggered when a value in a data validation list is changed.
RecalcOnPicklistChange
Specifies whether the default recalculation behavior will be overridden when you change the value of
a picklist.
If set to true, a recalculation will be triggered when a value in a picklist is changed.
If set to false, a recalculation will not be triggered when a value in a picklist is changed.
RelationalResultMaxRows
If a value greater than -1 is specified, then relational query ResultSets are limited to returning the
specified number of rows.
TM1DatabaseLabel
If set to "Y", the name of the database is displayed beside the user on the TM1 Web banner. For
example, "Welcome: Admin / Planning Sample". The default is "N". When this option is set to "N",
nothing is displayed beside the user.
See “TM1DatabaseLabel parameter” on page 233 in Configuring IBM TM1 Web Startup and
Appearance Settings.
TM1ServerName
If set, users will not be asked to select a TM1 Server to connect to during login.
See “Configuring the TM1 Web login page using AdminHostName and TM1ServerName parameters”
on page 225.
UseBookRecalcSetting
The UseBookRecalcSetting parameter is included in the tm1web_config.xml file. When set to true,
the web server honors the mode in which the Excel sheet was published. If the Excel sheet was
published in Manual recalc mode, websheet data is not resent to the client until a recalculation is
performed.
The UseBookRecalcSetting parameter uses the following format in the tm1web_config.xml file:

<add key="UseBookRecalcSetting" value="false" />

where value is either "false" or "true"

If you set UseBookRecalcSetting to true, TM1 Web honors the recalculation settings in the Excel
worksheet.
When Calculation Options is set to Automatic:
• If you set UseBookRecalcSetting = "true", the websheet is recalculated automatically when
you change the SUBNM function.

Chapter 13. IBM Planning Analytics TM1 Web installation 223

 • If you set UseBookRecalcSetting = "false", the websheet is recalculated automatically when
you change the SUBNM function.
When Calculation Options is set to Manual:
• If you set UseBookRecalcSetting = "true", the websheet is not recalculated automatically. To
recalculate, you must manually click the recalc button.
• If you set UseBookRecalcSetting = "false", the websheet is recalculated automatically when
you change the SUBNM function.
WebsheetBackgroundRecalculationMode
Specifies the level of background recalculation that occurs for a websheet.
[Link] calls can take several seconds because the data is not readily
available. Use the WebsheetBackgroundRecalculationMode parameter to recalculate the book in the
background so that the necessary data is ready when it is requested.
If set to 0 (default value), only the buffered (visible) area is calculated on a refresh of a sheet.
If set to 1, the area that is adjacent to the buffered area is calculated, in addition to the buffered area.
This improves wait times if the user scrolls slightly away from the initially visible area.
If set to 2, the entire current worksheet is calculated. This improves wait times if the user scrolls to
any area of the current sheet.
If set to 3, the entire current workbook is calculated. This improves wait times if the user moves to
any area of the current worksheet or to another worksheet.
Note : The higher the setting number, the more cells are calculated meaning that there would be a
higher load on the web server.
WorkbookMaxCellCount
Specifies the maximum cell count of a workbook as a number with no thousands separators.
The TM1Web application server validates the size of a workbook that is published to TM1 Server.
Workbooks that contain ActiveForms might be uploaded only with their control row. At publish time,
the workbook can have multiple rows but when it is opened and rebuilt it can display many more
rows. You can use WorkbookMaxCellCount to avoid issues when you open workbooks with many cells.
If this parameter is present in tm1web_config.xml and it is not the default, when the user opens a
workbook, the server validates its cell count against WorkbookMaxCellCount. If the cell count of the
workbook exceeds WorkbookMaxCellCount, an error message is logged and the workbook is not
opened. The user sees the <book_name> exceeds maximum cell count error message in the
[Link] file.
See Using IBM Planning Analytics TM1 Web Logging.
• Leaving this parameter blank or setting it to 0 or less indicates that an unlimited cell count for
workbooks is allowed.
• Before IBM Planning Analytics version 2.0.7, the default value is -1, which indicates an unlimited
number of cells are allowed in a workbook.
• As of IBM Planning Analytics version 2.0.7, the default value is 500000.
Note : Changes to this parameter require a restart of the application server.
X-Frame-Options
The X-Frame-Options parameter sets the X-Frame-Options response header value. The parameter
(and the response header value) specifies whether a browser should be allowed to render a TM1 Web
page in a <frame>, <iframe>, or <object>. Use this parameter to prevent Click-jacking attacks and
ensure that TM1 Web content is not embedded into other sites. There are three possible parameter
values.
• 0 corresponds to the DENY response header value, which prevents any domain from framing TM1
Web content.

224 IBM Planning Analytics: Installation and Configuration

 • 1 corresponds to the SAMEORIGIN response header value, which allows only the current domain to
frame TM1 Web content.
• 2 corresponds to the ALLOW-FROM response header value. In this case, TM1 Web checks the
CrossDomainAccessList parameter in tm1web_config.xml for the list of cross-domain URLs that
are allowed to access and frame TM1Web content.
The ALLOW-FROM response header does not have universal browser support. TM1 Web uses the
values in CrossDomainAccessList to determine whether the domain is allowed or not. If not, TM1
Web includes the DENY response header value, which prevents framing. In certain circumstances,
TM1 Web might be unable to determine the requesting domain. In this case, the SAMEORIGIN
response header value is included.
If the X-Frame-Options parameter is missing or empty, 2 is the default value.
The .jsp files in TM1Web include the response header X-Frame-Options only for the DENY and
SAMEORIGIN values. If the domain is confirmed to be allowed, then no X-Frame-Options header is
included.

Editing the TM1 Web configuration file

You can edit the IBM TM1 Web configuration file to configure different parameters.
The TM1 Web configuration file is an xml file and should be opened only with an XML-type editor. Opening
it using a regular text editor such as Microsoft Wordpad can result in incorrect characters being added
that may corrupt the file.
As of TM1 Web version 10.2, the new tm1web_config.xml file replaces the [Link] file from
previous TM1 Web versions.

Procedure
1. Locate and open the tm1web_config.xml file in the following location:
<TM1 install location>\webapps\tm1web\WEB-INF\configuration\
Note : The tm1web_config.xml file is an xml file and should be opened only with an XML-type
editor. Opening it using a regular text editor such as Microsoft Word Pad can result in incorrect
characters being added that may corrupt the file.
2. Edit the parameters and save your changes.
3. Log in to IBM TM1 Web to see the result of your edits.

Configuring the TM1 Web login page using AdminHostName and

TM1ServerName parameters
The AdminHostName and TM1ServerName parameters control whether the IBM TM1 Web login page
prompts the user to enter values for the TM1 Admin Host and TM1 server.
If you set a value for either of these parameters in the tm1web_config.xml file, then the login process
uses the specified value and does not prompt the user for this information.

AdminHostName Parameter
This parameter specifies the name of the Admin Host on which a TM1 Admin Server is running. Edit the
AdminHostName parameter in the tm1web_config.xml file using the following format:

<add key="AdminHostName" value="HostName"/>

where HostName can be one of the following values:

• If HostName is blank (default value), then the login page displays the Admin Host prompt.

Chapter 13. IBM Planning Analytics TM1 Web installation 225

 • If HostName is set to the name of a valid TM1 Admin Host, then IBM TM1 Web uses that Admin Host for
the login process and does not prompt the user.

TM1ServerName Parameter
This parameter sets the name of the TM1 server. Edit the TM1ServerName parameter in the
tm1web_config.xml file using the following format:

<add key="TM1ServerName" value="ServerName"/>

where ServerName can be one of the following values:

• If ServerName is blank (default value), then the TM1 server prompt is displayed on the IBM TM1 Web
login page.
• If ServerName is set to a valid TM1 server name, then the login page does not display a prompt for
either the Admin Host or the TM1 server.
• If the AdminSvrSSLCertID parameter is incorrectly configured, the server name pull-down displays as
empty and an error is logged in the TM1 Web log file. For more information, see Running TM1 in Secure
Mode using SSL in TM1 Operation.
After the user enters a valid User Name and Password, IBM TM1 Web will log in to the TM1 server
specified by the TM1ServerName parameter in the tm1web_config.xml file.
For example, the TM1ServerName parameter could be set to planning sample, as shown in the following
code.

<add key="TM1ServerName" value="planning sample" />

Configuring a custom homepage for TM1 Web

You can configure a custom homepage for IBM TM1 Web to display a websheet, cube view, or a URL after
users have successfully logged into IBM TM1 Web. This homepage can provide users with a starting point
for accessing and working with TM1 data.
A homepage can be configured globally for all IBM TM1 Web users or assigned individually for different
users or sets of users. For example, if you configure the homepage option to display an HTML file or other
type of web page, then you can provide users with instructions, tasks, links, or any other content that can
be displayed in a web page.
If a homepage is configured, it displays on the first tab in IBM TM1 Web and cannot be closed by users.
When configured, a Home link is displayed in the header area of IBM TM1 Web that allows users to easily
return to the homepage.
An IBM TM1 Web homepage can be configured in one of the following two ways:
Different homepage for different IBM TM1 Web users
Use the Client Settings dialog in TM1 Architect and Server Explorer to configure a startup homepage
for different clients (users) of IBM TM1 Web.
Global homepage for all IBM TM1 Web users
Use the HomePageObject parameter in the tm1web_config.xml file to configure a homepage that
applies globally to all IBM TM1 Web users.
Note : Any homepage assignment you make with the Client Settings dialog can override the global setting
in the tm1web_config.xml file if you set AllowOverwrite=true in the HomePageObject parameter
of the tm1web_config.xml file.

226 IBM Planning Analytics: Installation and Configuration

Configuring different homepages for individual users
The Client Settings dialog box, in Architect and Server Explorer, configures a startup homepage for
different IBM TM1 Web clients (users).
For example, you can assign one homepage for TM1 Web users in the Sales department and another
homepage for users in the Finance department.
Note : You can use the Client Settings dialog box to assign homepages for specific users, over-riding the
global homepage setting for the HomePageObject parameter in the tm1web_config.xml file.

Procedure
1. In Architect or Server Explorer, right click the server and select Security, Clients/Groups.
The Clients/Groups dialog box opens.
2. Click Settings.
The Client Settings dialog box opens.
3. Select the client from the Current Client list for which the homepage setting will apply.
4. Enter a websheet, cube view, or URL for the homepage as follows:
• To display a URL, type the URL address, including the http:// protocol, into the Homepage box. You
can enter a URL for either a website or an individual file.
• To select a websheet or cube view as the homepage, click Browse. The Select an TM1 Web
Homepage dialog box opens where you can select a reference to a websheet or cube view from the
Application tree.
After selecting a websheet or cube view reference, click OK to return to the Client Settings dialog box.
5. Select the settings that control the appearance of the Navigation pane.
Note : The Navigation pane settings you set here will only apply if the corresponding parameter in the
tm1web_config.xml file is set to AllowOverwrite=true. For more information, see “Configuring
TM1 Web startup and appearance settings” on page 230.
The available settings for controlling the appearance of the Navigation pane include:
• Include the Navigation Pane - Determines whether the Navigation pane is displayed or not
displayed when the selected client logs in to TM1 Web.
• Open pane on Login - Sets the Navigation pane to display in the expanded mode when the selected
client logs in to TM1 Web.
• Close pane on Login - Sets the Navigation pane to display in its minimized mode when the selected
client logs in to TM1 Web.
• Save Client's Navigation Pane Settings - Determines whether the personal settings for the
Navigation pane are saved when the client logs out of TM1 Web.
6. Select one of the options from the Apply To list to configure which client or clients will be able to view
the homepage.
The available options include:
• Current Client - Applies the homepage setting for only the client selected in the current Client list.
• Selected Clients - Enables the Select button so you can open the Subset Editor to select a collection
of clients that will use the same homepage setting.
If you choose Selected Clients, and then click Select, the Subset Editor opens so you can select a
subset of TM1 clients that can use the homepage.
Use the Subset Editor to select a subset of clients and then click OK to return to the Client Settings
dialog box. The number of clients selected in the Subset Editor is summarized in the Client Settings
dialog box.
• All Clients - Applies the same homepage setting to all TM1 clients.

Chapter 13. IBM Planning Analytics TM1 Web installation 227

 7. Click Apply Settings to configure the homepage for the client or clients that you selected in the Apply
To list.
8. Repeat steps 4, 5, 6, and 7 to configure a homepage for a different set of TM1 clients.
9. Click OK to close the Client Settings dialog box.
You have now configured a homepage for TM1 Web. The selected TM1 Web clients will see the
assigned homepage the next time they successfully log in to TM1 Web.

Configuring a global homepage for all users

The HomePageObject parameter, in the tm1web_config.xml file, enables a global homepage that
displays for all IBM TM1 Web users.
Note : You can override the global HomePageObject parameter by using the Client Settings dialog to
assign different homepage's for individual TM1 users. For more information, see “Configuring different
homepages for individual users” on page 227
The HomePageObject parameter works for three types of objects:
• Cubeviewer
• Websheet
• URL
The homepage object displays after the user successfully logs in to TM1 Web.

Using the HomePageObject parameter

How to use the HomePageObject parameter.
The HomePageObject parameter uses the following format:
<add key="HomePageObject" value="ObjectPath ;Type= ObjectType ;Description= ObjectTitle ;
AllowOverwrite =true" />
where:
• ObjectPath is the path to the websheet, cube view, or URL object that you want to open. The exact
format of the path depends on the type of object.
• ObjectType is the keyword for the object you want to open; websheet, cubeviewer, or URL.
• ObjectTitle is a brief title you assign to the object that displays in the title bar of the web browser and on
the homepage tab in IBM Cognos TM1 Web.
• AllowOverwrite can be set to a value of true or false as follows:
If you set AllowOverwrite=true then the HomePageObject parameter can be overridden by setting a
different homepage for individual clients using the Client Settings dialog in Architect and Server Explorer.
If you set AllowOverwrite=false then the HomePageObject parameter applies globally to all TM1 users
and can not be individually configured with the Client Settings dialog in Architect and Server Explorer.
The following sections describe using the HomePageObject parameter for websheets, cube views, and
URLs.

Setting a global TM1 Web homepage to a Cube View

Use the following format to set a cube view as the homepage for IBM TM1 Web.

value=CubeName$$ViewName$$Status

where the following arguments are separated by $$ characters:

• CubeName is the name of cube to which the view belongs.
• ViewName is the name of the cube view to display.
• Status is the public or private status of the cube view.

228 IBM Planning Analytics: Installation and Configuration

Note : You must include a value of either PUBLIC or PRIVATE to correctly identify the specific cube view
that you want to open.
For example, to open a public view named Price from the SalesCube:

&ltadd key="HomePageObject" value="SalesCube$$Price$$Public;Type=cubeviewer;

Description=MyStartCube;AllowOverwrite=true"
/>

Setting a global TM1 Web homepage to a websheet

You can assign a websheet as the IBM TM1 Web homepage, depending on how the Excel file was added
to TM1.

Opening a websheet that references an Excel file outside of TM1

You can open a websheet that references an Excel file.

Procedure
Use the format:

value="WebsheetPath

where WebsheetPath is the location and name of the Excel file. This can be either a path for a local file, or
a UNC path for a file located on a network.
For example, to set a UNC network path for websheet:

value=//MySystem/Samples/classic_slice.xls

Results
The complete HomePageObject parameter looks like this:

<add key="HomePageObject" value="//MySystem/Samples/classic_slice.xls;Type=websheet;

Description=MyWebsheet;AllowOverwrite=true"/>

Opening a websheet object that was uploaded to the TM1 server

You can open a websheet object that was uploaded.

Procedure
1. In Server Explorer, use the Properties pane to find the TM1 assigned name for the uploaded Excel file.

Figure 3. Example of an assigned name for an uploaded Excel file in Server Explorer
2. Set the value parameter using the following format:

Chapter 13. IBM Planning Analytics TM1 Web installation 229

 value="TM1://ServerName/blob/PUBLIC/.\}Externals\
TM1_Filename

where:
• ServerName is the name of the TM1 sever where the Excel file is located.
• TM1_Filename is the name that TM1 assigned to the uploaded Excel file.
For example:

value="TM1://sdata/blob/PUBLIC/.\}Externals\Report_2006.xls_20070123212746.xls

The complete HomePageObject parameter line looks like this:

<add key="HomePageObject" value="TM1://sdata/blob/PUBLIC/.\}Externals\

Report_2006.xls_20070123212746.xls;Type=websheet;Description=My
Uploaded Websheet;AllowOverwrite=true" />

Setting a global TM1 Web homepage to a URL

You can set the HomePageObject parameter to a URL.
Use this format:

value="URL_Path

Where URL_Path can point to a web site or an individual web page file.
For example:
• To set the homepage to a URL that points to a file:

<addkey="HomePageObject" value="[Link];Type=URL;

Description=MyStart Page;AllowOverwrite=true"
/>

• To set the homepage to a URL that points to a web site:

<addkey="HomePageObject" value="[Link]

Description=IBM;AllowOverwrite=true"/>

Configuring TM1 Web startup and appearance settings

You can control the appearance of the Navigation pane, tab bar, and websheet and Cubeviewer toolbars
when users log in to IBM TM1 Web.
These parameters are located in the tm1web_config.xml file and apply globally to all users of TM1
Web.
Note : For more information on using the HomePageObject parameter to set a custom homepage, see
“Configuring a custom homepage for TM1 Web” on page 226.

NavTreeHidden parameter
The NavTreeHidden parameter determines if the Navigation pane displays when users log in to IBM TM1
Web.
This can be helpful if you are displaying a custom homepage for users and you want to completely hide
the Navigation pane.

230 IBM Planning Analytics: Installation and Configuration

The NavTreeHidden parameter uses the following format in the tm1web_config.xml file:

<add key="NavTreeHidden" value="false;AllowOverwrite=true"

/>

where:
value can be either true or false
• If set to false, the Navigation pane will be displayed when user's log in to TM1 Web.
• If set to true, the Navigation pane will not be displayed when user's log in to TM1 Web.
AllowOverwrite can be set to true or false as follows:
• If you set AllowOverwrite=true, the NavTreeHidden parameter is assigned globally to all users, but
can be overridden for individual clients using the Client Settings dialog in Architect and Server Explorer.
• If you set AllowOverwrite=false, the NavTreeHidden parameter applies globally to all TM1 users
and can not be overridden for individual clients using the Client Settings dialog in Architect and Server
Explorer.

NavTreeCollapsedOnStart parameter
The NavTreeCollapsedOnStart parameter determines if the Navigation pane will be minimized or
expanded when users log in. If collapsed, a small vertical bar displays to provide the user with a way to
restore the pane.
The NavTreeCollapsedOnStart parameter uses the following format in the tm1web_config.xml file:

<add key="NavTreeCollapsedOnStart" value="false;AllowOverwrite=true"

/>

where:
value can be either true or false.
• If value is set to false, the Navigation pane will be expanded and display in its default mode when user's
log in to TM1 Web.
• If value is set to true, the Navigation pane will be collapsed when user's log in to TM1 Web.
AllowOverwrite can be set to true or false as follows:
• If you set AllowOverwrite=true, the NavTreeCollapsedOnStart parameter is assigned globally to all
users, but can be overridden for individual clients using the Client Settings dialog in TM1 Architect and
Server Explorer.
• If you set AllowOverwrite=false, the NavTreeCollapsedOnStart parameter applies globally to all
TM1 users and cannot be overridden for individual clients using the Client Settings dialog in TM1
Architect and Server Explorer.

HideTabBar parameter
The HideTabBar parameter determines if IBM TM1 Web can display multiple tabs when a user opens
multiple TM1 Web objects, or if only one view is displayed.
This can be useful if you want to limit users to one view at a time.

Chapter 13. IBM Planning Analytics TM1 Web installation 231

 The HideTabBar parameter uses the following format in the tm1web_config.xml file:

<add key="HideTabBar" value="false;AllowOverwrite=true"/>

where value can be either true or false.

• If value is set to false, multiple tabs can be displayed. This is the default behavior of TM1 Web.
• If value is set to true, multiple tabs are not displayed and only one object can be opened at a time.
The AllowOverwrite option is not currently used for this parameter.

HideWebsheetToolBar parameter
The HideWebsheetToolBar parameter determines if the websheet toolbar is displayed when users open a
websheet.
The HideWebsheetToolBar parameter uses the following format in the tm1web_config.xml file:

<add key="HideWebsheetToolBar" value="false;AllowOverwrite=true"

/>

where value can be either true or false.

• If value is set to false, the websheet toolbar will display in TM1 Web.
• If value is set to true, the websheet toolbar will not display in TM1 Web.
The AllowOverwrite option is not currently used for this parameter.

HideCubeviewerToolBar parameter
The HideCubeviewerToolBar parameter determines if the Cubeviewer toolbar is displayed when users
open a cube view.
The HideCubeviewerToolBar parameter uses the following format in the tm1web_config.xml file:

<add key="HideCubeviewerToolBar" value="false;AllowOverwrite=true"

/>

where value can be either true or false.

• If value is set to false, the websheet toolbar will display in TM1 Web.
• If value is set to true, the websheet toolbar will not display in TM1 Web.
The AllowOverwrite option is not currently used for this parameter.

Displaying or hiding the Views node in the navigation pane

You can display or hide the Views node in the Navigation pane.

Procedure
1. Edit tm1web_config.xml in the TM1 Web virtual directory.

232 IBM Planning Analytics: Installation and Configuration

 2. Locate the NavTreeDisplayServerView, which controls the display of the Server View node. The default
value, Y, displays the Views node in the Navigation pane.

<!--NavTreeDisplayServerView: Y/N - Wether to display

"Server View" node in navigation tree -->

<add key="NavTreeDisplayServerView" value="Y" />

3. To hide the Views node, change the NavTreeDisplayServerView value to N.

4. Save tm1web_config.xml.
5. Log in to TM1 Web.
Now the Navigation pane displays without the View node.

TM1DatabaseLabel parameter
This parameter displays the TM1 database label in the banner beside the user name.
Edit the TM1DatabaseLabel parameter in the tm1web_config.xml file using the following format:

<add key="TM1DatabaseLabel" value="Y"/>

where TM1DatabaseLabel can be either N or Y.

• If TM1DatabaseLabel is set to N, the database label is not displayed. This is the default behavior of
TM1 Web.
• If TM1DatabaseLabel is set to Y, the database label appears in beside the logged in user name in the
banner as "Welcome: <user name> / <TM1 database label>".

Changing the Cube Viewer page size

You can change the number of rows and columns displayed in the Cube Viewer of IBM TM1 Web.
By default, Web Cube Viewer displays pages of TM1 data with 20 columns and 100 rows, and includes the
dimensions list in the row count.

Procedure
1. Edit tm1web_config.xml.
2. Locate the following code:
CubeViewerRowPageSize
CubeViewerColumnPageSize
3. Change the value for the row and/or column page size.
4. Save tm1web_config.xml.
5. Log in to TM1 Web.
For example, if you set the row page size to 10, the Cube Viewer displays nine rows of data, plus the
row of dimensions.

Setting the maximum number of sheets to export from a websheet

By default, the maximum number of sheets you can export from a websheet to a printer is 100. You can
configure IBM TM1 Web to export more sheets.

Procedure
1. Edit tm1web_config.xml.
2. Locate the following code:

Chapter 13. IBM Planning Analytics TM1 Web installation 233

 MaximumSheetsForExport

3. Change the value for the maximum number of sheets to export.

4. Save tm1web_config.xml.
5. Log in to TM1 Web.

Wrapping string values in cube views

Use CubeviewerStringWrap to set the parameters used when viewing string element cells in a Web Cube
View.
To control the way a view is displayed and wrapped, set the values using the CubeviewerStringWrap
parameter and save the web configuration file. Cells that are not displayed are still editable in a scrollable
area by clicking in the wrapped region.
Enabled
Turn wrapping of string cells in this view on or off. When set to "False" the column width is as wide as
the longest string for any row in the current view. Set to "True" by default to turn on wrapping using
these default parameters.
MinCharactersToWrap
Set the minimum number of characters needed before wrapping. For instance, string values with less
than 50 characters will not wrap within a cell. Set to 50 by default.
MaxDisplayCharacters
Set the maximum number of characters to display within the string cell. The cell may contain more
than this number of characters, but they will only be displayed when double-clicking on the cell. If the
MinCharactersToWrap is 50 and the MaxDisplayCharacters is 200, string cells containing 200 or more
characters will consume approximately 4 lines. Set to 200 by default.
WidthOfWrapCell
Set the number of characters used in the wrapped portion of the display. Set to 240 by default.
Use the following format in the tm1web_config.xml file (the following listing has a return in it for clarity
but you should not enter a return).

<add key="CubeviewerStringWrap" value="Enabled=true;MinCharactersToWrap=50;

MaxDisplayCharacters=200;WidthOfWrapCell=240" />

Remember : CubeviewerStringWrap does not apply to websheets.

Setting the TM1 Web session timeout

The default TM1 Web session timeout is 20 minutes. When TM1 websheets are deployed to IBM Planning
Analytics Workspace, you might encounter TM1 Web session timeouts. You can modify this setting in your
environment.

About this task

When TM1 websheets are deployed to Planning Analytics Workspace, the recommended session timeout
is 60 minutes.
Note : As of IBM Planning Analytics Local version 2.0.6, you must not change the session-timeout
value in the [Link] file.
In IBM Planning Analytics Local version 2.0.6, there is a parameter in the tm1web_config.xml file
called HttpSessionTimeout. You can use this parameter to customize the session timeout (in minutes)
of the HTTP session for TM1 Web.
If the HttpSessionTimeout parameter is not specified (missing or blank), the value is less than 1 or not
a numerical value, the default session-timeout that is defined in the [Link] file is used.

234 IBM Planning Analytics: Installation and Configuration

 If you are using IBM Planning Analytics Local version 2.0.6 or later, to customize the session timeout for
TM1 Web, set the HttpSessionTimeout parameter in tm1web_config.xml. See step “1” on page
235.
If you are using IBM Planning Analytics Local version 2.0.5 or earlier, to change the default session
timeout, set the <session-timeout> parameter in [Link]. See step “2” on page 235.

Procedure
1. To customize the session timeout, follow these steps.
a) Open thetm1web_config.xml in a text editor.
The tm1web_config.xml file is located in your <pa_installation_directory>\webapps
\tm1web\WEB-INF\configuration directory.
For example, C:\Program Files\IBM\cognos\tm1_64\webapps\tm1web\WEB-INF
\configuration.
b) Change the HttpSessionTimeout to 60 or a value that is required by your environment.

<add key="HttpSessionTimeout" value="60" />

c) Save and close the tm1web_config.xml.

2. If you are using IBM Planning Analytics Local version 2.0.5 or earlier, to change the default session
timeout, follow these steps.
a) Open [Link] in a text editor.
The [Link] file is located in your <pa_installation_directory>\webapps\tm1web\WEB-
INF directory.
For example, C:\Program Files\IBM\cognos\tm1_64\webapps\tm1web\WEB-INF.
b) Change the <session-timeout> value to 60 or a value that is required by your environment.

<session-config>
<session-timeout>20</session-timeout>
</session-config>

c) Save and close [Link].

3. Restart the IBM TM1 Application Server service.

Configuring web browsers for Cognos TM1 Web

This section describes web browser configuration steps for IBM Cognos TM1 Web that may be needed for
your environment after you complete the initial installation.
Users connect to Cognos TM1 Web using one of the supported web browsers running on their own
computers. Some additional configuration may be required.

Configuring web browser language for TM1 Web

The language settings in your web browser determine which language is used in the IBM TM1 Web
interface.

About this task

Follow these general steps to configure Microsoft Internet Explorer and Mozilla Firefox to display IBM
TM1 Web in your primary language. For more detailed information, see the documentation for your web
browser.

Procedure
1. Depending on which web browser you are using, use the available language options to select and
configure your primary language.

Chapter 13. IBM Planning Analytics TM1 Web installation 235

 • In Internet Explorer, the language options are typically located under Tools menu > Internet
Options > General > Languages.
• In Firefox, the language options are typically located under Tools menu > Options > Content >
Languages.
2. Add your language to the language list.
3. Organize the list so that your preferred language is at the top of the list.

Displaying and entering numbers in Cognos TM1 Web based on Regional

Settings
If you are running the IBM Cognos TM1 Web client in a language other than the language of your operating
system, you must ensure that your web browser language and Microsoft Windows regional setting are set
to the same value.
This will enable you to display and enter numbers in Cognos TM1 Web based on a specific regional
setting.
For example, if you have an English OS, but want to run Cognos TM1 Web in French, your browser
language must be set to French and your computer's regional setting language must be set to French.

Windows Regional and Language Settings

Access the Windows regional settings by opening the Regional and Language Options feature in the
Windows Control Panel.

Web Browser Language Settings

Access the web browser language setting as described in the section “Configuring web browser language
for TM1 Web” on page 235.

Configuring Internet Explorer for Cognos TM1 Web

If you are using IBM Cognos TM1 Web with Microsoft Internet Explorer, make sure you have this security
setting enabled to allow Cognos TM1 Web dialog windows to display correctly.
Change the security settings as follows:
• Allow websites to open windows without address bars or status bars.
• Allow script-initiated windows without size or position constraints.
If Internet Explorer is not configured correctly, some Cognos TM1 Web dialogs can appear truncated.

Running Cognos TM1 Web on a WAN Server and exporting Excel and PDF files
If you are running IBM Cognos TM1 Web on a WAN (Wide Area Network) server and want to allow users to
export Microsoft Excel and PDF files from Cognos TM1 Web, you need to configure specific security
settings in Microsoft Internet Explorer.
Because a WAN server resides in the Internet zone, Internet Explorer applies a different security profile
as compared to servers in the Local Intranet zone. To successfully export files from Cognos TM1 Web in a
WAN environment, you must add the Cognos TM1 Web server as a trusted site in the security settings for
Internet Explorer.

Adding Cognos TM1 Web as a trusted site in Internet Explorer

If you are using Microsoft Internet Explorer and running IBM Cognos TM1 Web on a WAN server, you must
add the Cognos TM1 Web server as a trusted site and then customize the security settings for trusted
sites.

236 IBM Planning Analytics: Installation and Configuration

Procedure
1. Open Microsoft Internet Explorer.
2. Click Tools >Internet Options.
The Internet Options dialog opens.
3. Click the Security tab.
4. Click Trusted Sites and then click the Sites button.
5. Enter the URL of the Cognos TM1 Web server in the Add this Web site to the zone box.
6. Click Add.
7. Close the Trusted Sites dialog box.
8. On the Security tab of the Internet Options dialog, click Trusted sites and then click the Custom
Level button.
The Security Settings - Trusted Sites Zone dialog opens.
9. Locate the settings for Downloads and click Enable for the Automatic prompting for file downloads
option.
10. Click OK.

Chapter 13. IBM Planning Analytics TM1 Web installation 237

238 IBM Planning Analytics: Installation and Configuration
Chapter 14. Integrating Planning Analytics Local with
IBM Cognos software
You can integrate IBM Planning Analytics with IBM Cognos Analytics and IBM Cognos applications. This
topic summarizes some of the most typical integration approaches and includes links to the related
documentation.
The main options for integrating Planning Analytics with Cognos software include authentication security,
data reporting, and data/object interaction. Configuring integration between Planning Analytics and
Cognos Analytics involves a combination of installation and configuration tasks on the computers hosting
the server and web server components. In some cases, installation and configuration is required on
individual end-user computers.
The following image illustrates an overview of Planning Analytics integration with IBM Cognos
applications.

Authentication Security
You can configure the IBM TM1 Server to authenticate users using Cognos Analytics security. With this
configuration, any TM1 user interface or other custom application must use a valid user name and
password from the Cognos Analytics server to access TM1 data.
Importing Cognos Analytics data into Planning Analytics
Deprecated in v2.0.8 The IBM Cognos TM1 Package Connector is supported in Planning Analytics
version 2.0.7 and earlier for use with IBM Cognos Analytics packages against SAP Business
Warehouse and other relational and ODBC data sources. You can use the Cognos TM1 Package
Connector to import data from these sources into Planning Analytics using a Cognos TM1
TurboIntegrator process.

© Copyright IBM Corp. 2007, 2021 239

 Using TM1 as a datasource with Cognos software
You can configure IBM Cognos Analytics to access TM1 servers and cubes from Cognos Analytics
applications such as Cognos Report Studio and Cognos Query Studio.
You can also access TM1 data inside of IBM Planning Analytics for Microsoft Excel.
Displaying and interacting with TM1 data objects
You can access, view, and interact with the following TM1 data objects in IBM Cognos Workspace and
IBM Cognos Insight:
• TM1 cube views and charts
• TM1 Websheets
• TM1 Scorecarding cubes and diagrams

TM1 as a datasource with Cognos Analytics

You can configure IBM Cognos Analytics to access IBM TM1 Server and cubes from Cognos Reporting and
Dashboards.
To enable Cognos Analytics reporting against TM1 data sources, configure a Planning Analytics data
source and publish a package .
For more details about Cognos Analytics, see the following resources:
• IBM Cognos Analytics 11.0 documentation on IBM Knowledge Center ([Link]
knowledgecenter/SSEP7J_11.0.0).
• Administration Guide > "Data Sources and Connections" > "TM1 Data Sources"

Import Cognos Analytics data into Planning Analytics Local with

the TM1 Package Connector
Removed in v2.0.8 The IBM TM1 Package Connector is supported for use with IBM Cognos Analytics
packages against SAP Business Warehouse and other relational and ODBC data sources. You can use the
TM1 Package Connector to import data from these sources into Planning Analytics Local by using a TM1
TurboIntegrator process.
Note : The IBM TM1 Package Connector was removed as an optional component in IBM Planning
Analytics Local version 2.0.8.
This component must be installed on both the TM1 server and the administrative client machines where
TurboIntegrator processes are being created against a BW package.
• For more information, see "Importing Data Using the IBM TM1 Package Connector" chapter in IBM TM1
TurboIntegrator.
• See also, Cognos Analytics documentation.
• See also, IBM Cognos Framework Manager about creating packages.
• See your SAP documentation for SAP related topics.
• See also, Software Product Compatibility Reports tool ([Link]
compatibility/clarity/[Link]) for specifics on supported software.

TM1 Package Connector requirements

Removed in v2.0.8 Refer to the IBM Cognos Analytics and IBM Planning Analytics Knowledge Centers for
more details on the supported platforms, versions, and requirements.
The TM1 Package Connector requires the following components:
• TM1 10.1 or later. The TM1 Package Connector must be installed on both the TM1 server and the
administrative client machines where TurboIntegrator processes are being created for any datasource
you are using.

240 IBM Planning Analytics: Installation and Configuration

 • For an updated list of environments that are supported by TM1 including information about operating
systems, Cognos servers, and databases, create a detailed system requirements report using the
Software Product Compatibility Reports tool ([Link]
clarity/[Link]).
• IBM Cognos Analytics Server. For information about the specific supported versions, see IBM Cognos
Analytics 11.0 documentation on IBM Knowledge Center ([Link]
knowledgecenter/SSEP7J_11.0.0).
• IBM Cognos Framework Manager for package creation.
• If your datasource is SAP, then SAP Business Warehouse is required.
• 32-bit database client software is required on all platforms where the TM1 Package Connector is
installed for the specific data source being used. For SAP BW, this requires the SAP GUI or the SAP
RFCSDK library files and DLLs.
To obtain these files on Microsoft Windows, install the SAP GUI. For UNIX see “Installing the TM1
Package Connector on UNIX ” on page 243.
.

Installing the TM1 Package Connector

Removed in v2.0.8 Follow these steps to install the IBM TM1 Package Connector:

About this task

Microsoft Windows 7 applications are not allowed to write in the Program Files location. This can result in
an error when choosing the TM1 Package Connector from TM1 Perspectives on Windows 7.
Tip : To avoid this problem, choose Run as Administrator when running Microsoft Excel. Or, in the Cognos
Configuration for TM1 Package Connector you can change the Temporary files location setting to a
directory that is writable by the user.

Procedure
1. Insert the TM1 Package Connector disc into the IBM TM1 Server machine.
2. Run [Link] found in the system folder for your operating system, for example win64.
This launches the Cognos Installer.
3. Complete the installation prompts as appropriate for your installation.
Install the TM1 Package Connector into its own directory. Do not install it into an existing Cognos
Analytics folder.
4. On the Finish screen, select the Start IBM Cognos Configuration check box to launch the
configuration window automatically. If you prefer, you can leave this box unchecked and launch the
Cognos Configuration manually after you have installed.

Configuring the TM1 Package Connector

Removed in v2.0.8 When you have installed the IBM Cognos Analytics TM1 Package Connector, you have
access to the IBM Configuration tool.
If the Cognos Configuration tool did not launch automatically, you can use the Start Menu > IBM Cognos
> IBM Cognos Configuration option to launch it.

Procedure
1. Launch or open Cognos Configuration.
2. Select the Environment node on the Local Configuration Explorer window. The current settings for URI
display.

Chapter 14. Integrating Planning Analytics Local with IBM Cognos software 241
 3. Set the Gateway URI to point to the Cognos Analytics server where packages are deployed.
The Gateway URI is in the form of

http[s]://<host IP address>:<port>/<BI_SERVER_virtual_dir>/cgi-bin/[Link].

See the TM1 Operations documentation or the Cognos Analytics documentation for more information
on URIs.
4. Enter the URI in the Value column of the Other URI settings node.
The Dispatch URI is in the form of

http[s]://<host IP address>:<port>/p2pd/servlet/dispatch.

5. Once the URI is set, Save the configuration.

The configuration progress window checks the status of your entries. When it is complete, click Close.
If you encountered an error, check your settings and re-enter the values.
6. Close the Cognos Configuration window.

Setting the environment variable

Removed in v2.0.8 On Microsoft Windows, after you have installed the IBM TM1 Package Connector, the
TM1_PACKAGE_CONNECTOR system environment variable is set to the installation directory specified in
the installation, for example C:\Program Files\ibm\Cognos\c10\bin.
You can change this location if necessary by editing the variable or creating a system environment
variable.
The system variable is created by the most recent installation of the TM1 Package Connector.
The default Microsoft Windows installation location for TM1 Package Connector10 is C:\program
Files\ibm\cognos\c10.

Setting the TM1 server configuration parameter (optional)

Removed in v2.0.8 For the IBM TM1 TurboIntegrator process to run on the IBM TM1 Server, add the
CognosTM1InterfacePath parameter to the TM1 Server configuration file ([Link]) for the TM1
Server where your data will reside after the import from the Cognos Analytics package.
Attention : The following information applies only when using a MIcrosoft Windows operating
system.
The value of CognosTM1InterfacePath tells the TM1 Server where to find the TM1 Package Connector.
This is not needed if the TM1_PACKAGE_CONNECTOR environment variable is defined. If this parameter
is defined, it overrides the TM1_PACKAGE_CONNECTOR environment variable.
Enter the TM1 Package Connector location into the TM1 server [Link] file where the TM1 Package
Connector is installed, for example:

CognosTM1InterfacePath=C:\Program Files\ibm\cognos\c10\bin

Remember :
The CognosTM1InterfacePath variable is required only when using the TM1 Package Connector on
UNIX.
The TM1_Package_CONNECTOR is a system environmental variable that identifies the TM1 Package
Connector installation location on a Windows operating system.
The CognosTM1InterfacePath variable is used in the TM1 server's [Link] on UNIX, however if it is
added to a TM1server's [Link] file on Windows, it can overwrite the value set in
TM1_Package_Connector.

242 IBM Planning Analytics: Installation and Configuration

 TM1 Package Connector on the client computer
Removed in v2.0.8 After you have installed and configured the IBM TM1 Package Connector on the IBM
TM1 Server, install and configure another copy on the admin client computer. Use the same settings for
both installations.

Running the TM1 Package Connector

Removed in v2.0.8 See "Importing Data Using the IBM TM1 Package Connector" in the TM1
TurboIntegrator documentation for details on how to run the TM1 Package Connector.

Installing the TM1 Package Connector on UNIX

Removed in v2.0.8 To install the IBM TM1 Package Connector on UNIX, follow the same instructions as
for the Microsoft Windows installation making the following adjustments:

Procedure
1. Use 32 bit Java Standard Edition 6 (or 32-bit Java SE 6).
2. Set the environment variable JAVA_HOME=<java_location> where <java_location> is the 32-bit
Java installation location.
3. Copy the files at <Package_Connector_install_location>/bin/jre/6.0/lib/ext* to
JAVA_HOME/jre/lib/ext.
4. Start [Link] from the <Package_Connector_install_location>/bin.
5. Place the 32-bit SAP RFCSDK library files and DLLs on the UNIX machine.
6. Set a locale that uses the UTF-8 code page to handle Unicode data. This is optional.
7. Configure the IBM TM1 Server by adding the parameter to the [Link] file:

CognosTM1InterfacePath=/<Package_Connector_install_location>/bin

8. Configure your environment to use the SAP DLLs and the TM1 Package Connector:
a) Include RFCSDK's lib directory in the search path of:, $LD_LIBRARY_PATH or $LIBPATH
b) Export (make public) these variables: $LIBPATH and $LD_LIBRARY_PATH
• Where the libraries are found is different on various UNIX platforms:
Solaris and Linux: LD_LIBRARY_PATH
HPUX: SHLIB_PATH

Planning Analytics and Cognos Analytics security

You can configure the IBM TM1 Server to authenticate users using Cognos Analytics security.
With this configuration, any TM1 user interface or other custom application must use a valid user name
and password from the Cognos Analytics server to access TM1 data. You can also configure IBM Cognos
TM1 Applications to use Cognos Analytics security.
For more information, see the following topics:
• “Cognos security” on page 261
• “Using Cognos TM1 Applications with Cognos security” on page 269

Chapter 14. Integrating Planning Analytics Local with IBM Cognos software 243
Integrate SAP BW with Planning Analytics
You can use Cognos Integration Server to integrate SAP Business Warehouse (BW) with IBM Planning
Analytics.

About this task

IBM Cognos Integration Server integrates with both SAP BW and IBM Planning Analytics by using APIs. It
is bidirectional and supports both the cloud and local versions of IBM Planning Analytics.
Cognos Integration Server supports regular SAP BW InfoCubes and SAP BW InfoQuerys and SAP BW
4HANA.
To integrate SAP BW with Planning Analytics, you need to create a Selection in Cognos Integration Server.
For more information, see Creating a Selection.
You can view this video to learn how to use Cognos Integration Server to integrate SAP Business
Warehouse (BW) with IBM Planning Analytics. Enable closed captioning in the video to follow along.
[Link]

Cognos TM1 Applications integration with Cognos Analytics and

the Cognos Connection portal
If your TM1 installation uses Cognos security for authentication, your Cognos Analytics users can use the
Cognos Connection portal to open TM1 applications instead of the TM1 Applications portal. However,
administrators still need to use TM1 Applications to configure and manage applications.
When you configure TM1 Applications to use Cognos security, you also enable the Cognos Connection
portal to display a folder that contains links to the available TM1 applications. The exact list of displayed
applications depends on the rights of the current user.
The [Link] file provides the information for Cognos Analytics and the Cognos Connection portal
to display links to TM1 Applications. For more information, see “Using Cognos TM1 Applications with
Cognos security” on page 269.
Note : You must have the TM1_PATH environment variable specified before connecting to Cognos TM1
under a UNIX environment.

244 IBM Planning Analytics: Installation and Configuration

Chapter 15. Planning Analytics Local security
After you install IBM Planning Analytics Local, you can configure the specific authentication and security
modes that you want to use.
Configuration of authentication and data transmission security is part of the installation and configuration
process. The steps for setting user, group, and object security are typically done after the initial
installation and configuration process and are described in separate documentation.

Authentication security
Authentication or login security configuration includes selecting the type of login security that controls
user access to the different Planning Analytics components.
For information about users in Planning Analytics Workspace, see Administer users in Planning Analytics
Workspace.

Data transmission security

Security configuration includes configuring Planning Analytics to use an encrypted communication
protocol for secure data transmission. The Planning Analytics Data Tier is deployed to IBM WebSphere
Liberty Profile (WLP). Properties of encrypted communication for WLP such as protocols, ciphers, and the
location and password of a keystore that contains required server key and certificates, must be configured
through Cognos Configuration.

User and Group security

Planning Analytics manages security by organizing users into groups. Planning Analytics includes a set of
three predefined administrative groups. You can create your own custom groups. Users can belong to one
or multiple groups.
For information about configuring Planning Analytics user and group security, see Managing Users and
Groups in TM1 Operations.

Object security
Another level of Planning Analytics security is object security. You can use this type of security to control
access to the specific TM1 objects in your data model, but it is not configured during the initial installation
and configuration process.
For more information about setting security for TM1 objects, see Controlling Access to TM1 Objects in
TM1 Developer.
For more information about setting security for Planning Analytics Workspace objects, Security in
Planning Analytics Workspace.
Related topics:
“TM1 Application Server advanced installation and configuration” on page 126
You can perform advanced installation and configuration tasks to customize your installation of the IBM
TM1 Application Server components.
“Configuring authentication security for TM1 Application Web” on page 121
For IBM TM1 Server used with TM1 Application Web, use either TM1 standard security authentication or
IBM Cognos security.
“Configure TLS for Planning Analytics Workspace Local” on page 166
To configure Transport Layer Security (TLS) for IBM Planning Analytics Workspace, you create a privacy
enhanced mail (pem) file that contains your security certificates.
“Configure TLS between Planning Analytics Workspace Local and other servers” on page 167

© Copyright IBM Corp. 2007, 2021 245

 If you are using self-signed certificates for TM1 servers or IBM Cognos Analytics, you might need to add
the certificate authority certificates for them to the list of CA certificates that are used by IBM Planning
Analytics Workspace.
Using Cognos security in Planning Analytics for Microsoft Excel

Authentication security
Authentication or login security configuration includes selecting the type of login security that will control
user access to the different IBM TM1 components.
You can configure IBM TM1 Server to use a specific authentication mode to control user login access.
By default, when you install the TM1 Server it is configured to use the standard Cognos TM1
authentication.
After you install the TM1 Server, you can change the authentication method by changing the parameters
in the TM1 configuration files.

Standard Cognos TM1 authentication

With IBM Cognos TM1 authentication, the Cognos TM1 server checks the user name and password
against the user names and passwords in the Cognos TM1 database.
The following image shows the process of authenticating with the TM1 server.

TM1 Server asks you for a user name and password, and validates the login information against the
security cube login information.

Security considerations when using Cognos TM1 Applications

You can use either IBM Cognos TM1 standard security authentication or IBM Cognos security for the TM1
servers you use with Cognos TM1 Applications.
Do not use a combination of different security authentication modes for the same installation of Cognos
TM1 Applications.
Determine the security mode before you configure Cognos TM1 Applications to use a TM1 Server and use
that same security mode with any additional servers you add.
For details about using Cognos security, see: “Using Cognos TM1 Applications with Cognos security” on
page 269.

246 IBM Planning Analytics: Installation and Configuration

 Using the IntegratedSecurityMode parameter with Cognos TM1 Applications
To set the Cognos TM1 security authentication mode use the IntegratedSecurityMode parameter in
the [Link] file of each TM1 Server you want to use.
Important : The Cognos TM1 Applications component is compatible only with Cognos TM1 security
authentication modes 1 and 5.
For example, to use Cognos TM1 standard security authentication, set the IntegratedSecurityMode
parameter to 1 for each server.

IntegratedSecurityMode=1

To use IBM Cognos security, set the IntegratedSecurityMode parameter to 5.

IntegratedSecurityMode=5

For more details about the IntegratedSecurityMode parameter, see the "TM1 System Configuration"
section in TM1 Operations.
If IntegratedSecurityMode=5 is used for the TM1 Server and IBM Cognos TM1 Applications, it is not
possible to assign rights to native TM1 groups within the Manage rights dialog. Only Cognos Groups
imported into the TM1 Server, are available. This means you cannot use native TM1 groups and Cognos
groups in parallel because the SecMode is limiting which groups can be used

Configuring Cognos TM1 Applications security for multiple TM1 Servers

If you want to use multiple TM1 servers with Cognos TM1 Applications, they must all be configured to use
the same security authentication (either Cognos TM1 standard authentication or Cognos security) and
include the same administrator user name and password.
For more details, see “Configuring TM1 Application Web to use multiple TM1 Servers” on page 128.

Integrated login
Integrated login enables you to use Microsoft Integrated Windows Authentication (IWA) and control
access to IBM TM1 data based on Users and Groups defined in Microsoft Active Directory (AD).
Note : Integrated login is supported on Microsoft Windows only. You cannot use integrated login to access
TM1 Server running on UNIX.
In integrated login mode (security mode 3), TM1 authentication compares the user's domain-qualified
Microsoft Windows login name to the contents of the UniqueID element of the }ClientProperties
cube.
If there is a match, the user is authenticated to TM1. If Active Directory groups have been imported into
the TM1 Server, Active Directory group memberships are honored.
If no match is found, TM1 displays an error message stating that the client name does not exist. TM1
Server does not prompt for login information.
To populate the UniqueID elements and import groups from Microsoft Active Directory, you can use the
“ETLDAP utility” on page 274, TurboIntegrator jobs, or manual steps. For more information, see
“Configure integrated login for the IBM TM1 Server” on page 249.
Users who want to access TM1 data in a server that is configured for integrated login must authenticate to
Microsoft Windows first and then use TM1 clients to access the TM1 Server.

Example
Suppose a user with the user name "Robert", which is defined in the Windows domain
"[Link]", logs in to his Windows workstation. When Robert uses a TM1 client that uses
integrated login, such as TM1 Architect, to access a TM1 Server configured for security mode 3, the TM1
client forwards Robert's Windows login information to the TM1 Server using Integrated Windows

Chapter 15. Planning Analytics Local security 247

 Authentication. The TM1 Server looks for a match to "Robert@EMEA" in the UniqueID elements of
the }ClientProperties cube. If there is a match, Robert is authenticated by TM1 successfully.
Note : Only the name of the actual domain that the user is defined in can be used. Using the fully qualified
domain name (for example, "[Link]") will fail.

Integrated login prerequisites

Use the following checklist as guidelines to configure IBM Planning Analytics components for integrated
login.
1. Complete the installation of the IBM TM1 Server and make sure that you are able to run and log in to it.
2. Run the ETLDAP Utility to extract the user and group login data from your LDAP directory and load that
data into the TM1 security cube. ETLDAP creates TM1 users from the LDAP data that you specify.
These users are members of the same group to which they were assigned in your LDAP directory.
For more information, see “Running ETLDAP” on page 275.
3. Configure the TM1 Server and client components to use integrated login.

Table 23. Integrated login configuration for Planning Analytics components

Component Configuration

TM1 Server Configure the integrated login parameters in the

[Link] file for any TM1 database that you want to use
with integrated login.
For more information, see “Configure integrated login for
the IBM TM1 Server” on page 249.

IBM Planning Analytics Workspace Local Configure the URIs that point to the authentication
servers.
For more information, see “Connect to TM1 and
authentication servers” on page 165.

IBM Planning Analytics for Microsoft Configure files the IBM® Cognos® Analytics Gateway
Excel installation location and enable single sign-on
configuration settings.
For more information, see “Configure Planning Analytics
for Microsoft Excel single sign-on” on page 207.

TM1 Web Configure parameters in the tm1web_config.xml file

that enable integrated login.
For more information, see “Configure integrated login for
TM1 Web” on page 249 and “Enable web browsers for
integrated login” on page 257.

Other Planning Analytics clients Enable the Use Integrated Login option for Cognos TM1
Architect and Cognos TM1 Perspectives.
For more information, see “Configure Cognos TM1
Perspectives to use integrated login” on page 258 and
“Configure Cognos TM1 Architect to use integrated login”
on page 257.

4. Set access permissions for TM1 users.

For more information, see “Configure access rights for Cognos TM1 users” on page 258.

248 IBM Planning Analytics: Installation and Configuration

Configure integrated login for the IBM TM1 Server
You can modify an IBM Planning Analytics installation to use integrated login without re-installing IBM
TM1 Server. To do so, run ETLDAP and modify several TM1 configuration files.

Procedure
1. Run ETLDAP and import the user and group information from your LDAP server, as described in
“Running ETLDAP” on page 275.
2. Shut down the TM1 Server.
3. Edit the following parameters in the [Link] file located in your TM1 Server data directory:
• Set the IntegratedSecurityMode parameter to 3.
• Set the SecurityPackageName parameter to the security protocol you use for integrated login.
In the following example, the server is configured to use Kerberos.

[TM1S]
SecurityPackagename=Kerberos
IntegratedSecurityMode=3
Servername=myserver
DatabaseDirectory=C:\Program Files\

4. Save and close the [Link] file.

5. Restart the TM1 Server.
6. Optional: Configure the TM1 clients to use integrated login by setting the Use Integrated Login option
in the associated user interface.

What to do next
• Connect Planning Analytics Workspace to authentication servers.
• “Configure Planning Analytics for Microsoft Excel single sign-on” on page 207.
• “Configure integrated login for TM1 Web” on page 249.
• “Configure Cognos TM1 Architect to use integrated login” on page 257.
• “Configure Cognos TM1 Perspectives to use integrated login” on page 258.

Configure integrated login for TM1 Web

You can configure TM1 Web for integrated login. You can also set up single sign-on (SSO) for HTTP-based
clients by using Integrated Windows Authentication (IWA) using the Kerberos protocol.

Overview
TM1 Web does not authenticate users but defers to TM1 Server for authentication. When you log in to
TM1 Web, you are prompted for credentials based on the security mode that is configured on the IBM
TM1 Server. When a user provides credentials, TM1 Web uses TM1 Server authentication on the user's
behalf with the provided credentials. For integrated login, the server that is being accessed by TM1 Web
must be configured for integrated login.
Integrated login works without any configuration in TM1 Web. You can select a server that is configured
for integrated login and TM1 Web prompts for your credentials. When you enter your credentials, TM1
Web sends them to the TM1 Server for authentication.
Important : If you set up TM1 Server, TM1 Web, and Planning Analytics Workspace Local using security
mode 2 or 3 (integrated login), websheets cannot be used in Planning Analytics Workspace. For more
information, see “Configure security mode 2 or 3 to use websheets in Planning Analytics Workspace” on
page 256.
You might want to configure single sign-on so that users are not prompted for credentials when they
access TM1 Web. For this approach to work, TM1 Web must be configured to integrate with Windows

Chapter 15. Planning Analytics Local security 249

 Authentication (Kerberos) to accept a user's forwarded Windows credentials and then perform an
integrated login to a TM1 Server on the user's behalf with those credentials. Since TM1 Web does not
support Kerberos for authentication directly, you must set up the security features of the WebSphere
Liberty Profile server that TM1 Web is deployed to.
The setup process requires the following double-hop authentication:
Single sign-on from the client to IBM WebSphere Liberty Profile
First, you must enable the IBM WebSphere Liberty Profile (WLP) application server's security. Next, a
user registry must be configured for WebSphere Liberty Profile to authenticate users against it. Last,
WebSphere Liberty Profile must be configured to allow SSO to it.
For Integrated Windows Authentication, you must use the Simple and Protected GSS-API Negotiation
Mechanism (SPNEGO) web authentication provider. This provider allows Kerberos enabled clients to
achieve single sign-on to WebSphere Liberty Profile. A user who is logged in to Windows using a client
that supports Integrated Windows Authentication can authenticate to WebSphere Liberty Profile
without getting prompted because of the Kerberos protocol.
Single sign-on from IBM WebSphere Liberty Profile to TM1 Server using TM1 Web
Single sign-on from IBM WebSphere Liberty Profile to each TM1 Server that is configured for
integrated login uses the Java Generic Security Services API (JGSS) and Java Authentication and
Authorization Services (JAAS) to delegate the received Kerberos user credentials to TM1 Web. TM1
Web performs a Kerberos-based authentication with TM1 Server on the user's behalf.
After you implement this setup successfully, users who are using browsers that are enabled for Integrated
Windows Authentication can authenticate to TM1 Web configured to access a TM1 Server that is running
security mode 2 or 3 (integrated login) with their Windows user credentials.

Before you begin

Make sure that the following prerequisites are configured:
• All computers that participate in the setup are running Microsoft Windows and are joined to a Windows
domain.
• Mutual trust is set up between all domains that any computer from the setup is registered to.
• All computers in the setup can resolve the fully qualified domain name of all other computers and
Windows domain controllers that are used in the configuration.
• An instance of TM1 Server is configured for integrated login. For more information, see “Configure
integrated login for the IBM TM1 Server” on page 249. The following settings must be configured:
– A Service Principal Name (SPN) is registered to a Windows account that runs the Windows service for
the TM1 Server instance.
– The SPN is specified in the ServicePrincipalName parameter in the [Link] file.
– The IntegratedSecurityMode in the [Link] file is set to 2 or 3.
– The SecurityPackageName is set to Kerberos.
– For all users who access the TM1 Server, the UniqueID element in the }ClientProperties
dimension is set to a string with the syntax <sAMAccountName>@<DOMAIN>.
• An instance of TM1 Application Server is installed on a computer in the setup.
• A domain user can log in to a client computer that is different from the computer that the TM1
Application Server components are installed on. The user must be able to run a supported browser to
access TM1 Web. For more information, see “Enable web browsers for integrated login” on page 257.

Conventions
The setup uses the following conventions:
<PA>
The Planning Analytics installation root folder.

250 IBM Planning Analytics: Installation and Configuration

<PA_APP_DOMAIN>
The name of the Microsoft Windows domain, for example, [Link].
<PA_APP_REALM>
The <PA_APP_DOMAIN> in uppercase, for example, [Link].
<PA_APP_HOST>
The fully qualified host name of the computer where TM1 Application Server is installed, for example,
[Link].
<PA_APP_ACCOUNT>
A user account from a Windows domain that is used to run TM1 Application Server.
<PA_SPN>
A string composed of "HTTP" (in uppercase), the "/" delimiter, and the <PA_APP_HOST>. For example,
"HTTP/[Link]".

Set up an account for the TM1 Application Server

1. As a domain administrator, create a domain user account or find an existing domain user account that
will be used to run the TM1 Application Server service. This user account is referred to as
<PA_APP_ACCOUNT>. For example, mydomain/pa11.
2. Ensure <PA_APP_ACCOUNT> has sufficient file system permissions on <PA_APP_HOST>. In particular,
the account requires modify permission on the following folders:
• <PA>/wlp
• <PA>/logs
• <PA>/temp
3. On <PA_APP_HOST>, make sure the "IBM Cognos TM1" service that runs the TM1 Application Server
(WLP) is started by <PA_APP_ACCOUNT>. (See “1” on page 251).
a. Using the Windows Services control pane, right-click the "IBM Cognos TM1" service and click
Properties.
b. On the Log On tab, add the <PA_APP_ACCOUNT> and password.
c. Click OK.
4. On <PA_APP_HOST>, get a domain Administrator to create a Kerberos keytab file by using the
Microsoft ktpass tool.
Note : WebSphere Liberty Profile requires server credentials for supporting Kerberos authentication to
it. These credentials are stored in a keytab file. To create this file, you must use the Microsoft ktpass
tool.
In a CMD window, type the following command:

ktpass -out <keytab_file> -princ <PA_SPN>@<PA_APP_REALM>

-mapuser <PA_APP_ACCOUNT> -pass <password> -mapOp set
-ptype KRB5_NT_PRINCIPAL

For example:

ktpass -out [Link] -princ HTTP/[Link]@[Link]

-mapUser mydomain\pa11 -pass pssw0rd -mapOp set -ptype KRB5_NT_PRINCIPAL

This command creates a [Link] file in the current folder that contains the Kerberos server
credentials.
Note : The keytab contains keys that are encrypted using a specific encryption scheme called
"encryption type" in Windows. The Active Directory administrator knows which ones are supported by
the Active Directory infrastructure. If in doubt, put keys into the keytab for all supported encryption
types by using the append -crypt all option.
When you use the ktpass tool, several things happen:

Chapter 15. Planning Analytics Local security 251

 • The principal specified in the -princ parameter will be registered as an SPN to the account
specified for the -mapuser parameter.
• The UserPrincipalName (=User Login Name) of the account will be changed in Active
Directory to the SPN specified for the -princ parameter. This is intended and required and must not
be reverted manually.
• The output of this command is a binary keytab file. The file can be moved. It does not depend on a
host or host name.

CAUTION : The keytab contents can get invalidated if changes are applied to the
PA_APP_ACCOUNT in Active Directory after the keytab has been created. If the supported
encryption types for the Active Directory account or the User Login Name get changed, re-
create the keytab.
Tip :
You can use the JRE klist tool in <PA>\jre\bin\ to view the contents of the keytab file. For
example:

klist -k -t <PA>/[Link]

5. Ensure that the account is trusted for delegation.

a. Ask an Active Directory administrator use the Active Directory Users and Computers tool to
investigate the account's properties.
b. Navigate to the Delegation tab.
c. Ensure that the account is set to Trust this user for delegation to any service (Kerberos).

Configure SPNEGO/Kerberos web authentication for WebSphere Liberty Profile

1. On <PA_APP_HOST>, create a Kerberos configuration file for WebSphere Liberty Profile.
• Using a text editor, create a text file in the <PA> folder named [Link].
• Copy and paste the following lines into the [Link] file.

[libdefaults]
default_realm = <PA_APP_REALM>
default_keytab_name = FILE:<keytab_file>
default_tkt_enctypes = aes128-cts-hmac-sha1-96
default_tgs_enctypes = aes128-cts-hmac-sha1-96
forwardable = true
renewable = true
noaddresses = true
clockskew = 300
udp_preference_limit = 1
[realms] <PA_APP_REALM> =
{
kdc = <PA_APP_DOMAIN>:88
default_domain = <PA_APP_DOMAIN>
}
[domain_realm]
.<PA_APP_DOMAIN> = <PA_APP_REALM>

• Replace the variables with actual values in your environment and save the file as [Link].
Note :
• The entry for default_keytab_name = must refer to the keytab file that is created in “4” on page
251.
• The entry for default_tkt_enctypes = aes128-cts-hmac-sha1-96 is an example from
Windows 2012 R2. You must use the encryption types that are supported in your environment. Refer
to your Active Directory Administrator for that information.
• Depending on the structure of the domain trees in the Active Directory forest, the Kerberos
configuration file might require more entries in the [realms] and [domain_realm] sections.
Contact your Active Directory Administrator to learn about your domain structure. For more

252 IBM Planning Analytics: Installation and Configuration

 information about the Kerberos configuration file, see The Kerberos configuration file in the
WebSphere Application Server Network Deployment documentation.
A configuration based on the example values might look like the following example:

[libdefaults]
default_realm = [Link]
default_keytab_name = FILE:<PA>\[Link]
default_tkt_enctypes = aes128-cts-hmac-sha1-96
default_tgs_enctypes = aes128-cts-hmac-sha1-96
forwardable = true
renewable = true
noaddresses = true
clockskew = 300
udp_preference_limit = 1
[realms]
[Link] =
{
kdc = [Link]
default_domain = [Link]
}
[domain_realm]
.[Link] = [Link]

2. Optional: Use the kinit tool in <PA>\jre\bin\ to verify the Kerberos configuration file:
a. Copy the [Link] file to <PA>\jre\lib\security folder. The file must be named
[Link] for this test. When the test is complete, you will remove the file.
b. Request a Kerberos ticket for <PA_SPN>:

kinit -k -t <keytab_file> HTTP/<PA_APP_HOST>

For example:

kinit -k -t <PA>\[Link] HTTP/[Link]

The tool confirms that a ticket has been stored to the default ticket cache.
c. Optional: Use the JRE klist tool in <PA>\jre\bin\ to view the Kerberos ticket.
For example:

klist

d. Remove the [Link] file from <PA>\jre\lib\security folder to prevent confusion. It is not
required in this location anymore.

Modify WebSphere Liberty Profile configuration

The following steps change the WebSphere Liberty Profile configuration file manually. These manual
changes are reverted when you make any other changes that require regenerating the application server
configuration file in Cognos Configuration. Therefore, you must back up the [Link] file when these
manual configuration changes are complete and potentially restore it when Cognos Configuration
overwrites the file.
1. Stop the TM1 Application service.
2. In a text editor, open the <PA>/wlp/usr/server/tm1/[Link] file.
3. Add the following feature elements before the </featureManager> element:

<feature>appSecurity-2.0</feature>
<feature>ldapRegistry-3.0</feature>
<feature>spnego-1.0</feature>

4. Before the <application id=”tm1”...> tag, add the following element:

<ldapRegistry
id="ldap"
realm="<PA_APP_DOMAIN>"

Chapter 15. Planning Analytics Local security 253

 host="<PA_APP_DOMAIN>"
port="389"
ignoreCase="true"
baseDN="<base_DN>"
bindDN="<binduser_accountDN>"
bindPassword="<binduser_password>"
ldapType="Microsoft Active Directory"
/>

Tip : You can use the IBM WebSphere securityUtility to encode passwords in the [Link]
file.
By using the domain name for host, the Microsoft DNS locator feature is used, which prevents a single
point of failure in case the referenced Domain Controller becomes unavailable. The baseDN is
generally composed of the string cn=Users and a comma-separated list of dc elements that represent
each part of the domain name.
For example:

Domain: [Link]
BaseDN: cn=Users,dc=mydomain,dc=sample,dc=com

The binduser_accountDN must be the Distinguished Name of a user account from the referenced
domain, which has browsing privileges to all user entries in that domain.
Tip : You can also use the User Principal Name syntax.
For example:

cn=admin1,cn=Users,dc=mydomain,dc=sample,dc=com

Or

bindDN="admin1@[Link]"

The LDAP registry element tells WebSphere Liberty Profile where to look up information for the user
who tries to authenticate. Therefore, the LDAP registry must reference the domain that the
authenticating user is from. For users from multiple domains to be able to authenticate, you must
define one LDAP registry for each domain. Multiple LDAP registries will automatically become
federated without explicit configuration. Add multiple <ldapRegistry> elements as required.
5. Optional: If user names in Active Directory contain the" /" character (forward slash), you must add
another configuration element because the forward slash is a special character in WebSphere security
realms.
After the last <ldapRegistry> element, add the following <federatedRepository> element,
which will configure WebSphere Liberty Profile to use the pipe character "|" instead so that it can
tolerate the forward slash in user names.

<federatedRepository>
<primaryRealm name="TM1Web Kerberized" delimiter="|" allowOpIfRepoDown="true">
<participatingBaseEntry name="<baseDN_ofRegistry>"/>
<uniqueUserIdMapping inputProperty="uniqueName" outputProperty="uniqueName"/>
<userSecurityNameMapping inputProperty="principalName"
outputProperty="principalName"/>
<userDisplayNameMapping inputProperty="principalName"
outputProperty="principalName"/>
</primaryRealm>
</federatedRepository>

Remember : Adjust the <baseDN_of_Registry> value in the <participatingBaseEntry>

element to the value of the baseDN setting of your <ldapRegistry>. If you are using multiple
<ldapRegistry> entries, add a <participatingBaseEntry> element for each <ldapRegistry>
with the correct value set.
For more information, see Configuring LDAP user registries in Liberty in the IBM Knowledge Center.

254 IBM Planning Analytics: Installation and Configuration

6. To enable SPNEGO/Kerberos based authentication for the WebSphere Liberty Profile, add the following
element after the <ldapRegistry> element:

<spnego
id="mySpnego"
krb5Config="<[Link]>"
krb5Keytab=”<keytab_file>"
servicePrincipalNames="HTTP/<PA_APP_HOST>@<PA_APP_REALM>"
canonicalHostName="true"
disableFailOverToAppAuthType="false"
/>

Remember : Replace <[Link]> and <keytab_file> with the path to the respective files
created earlier.

Configure TM1 Web for WebSphere Liberty Profile security

1. In the [Link] file, find the TM1 Web application entry and modify it as shown in the following
example:

<application id="tm1web"
location="${[Link]}/../../webapps/tm1web"
name="tm1web"
type=”war” context-root=”tm1web”>
<application-bnd>
<security-role name="AllAuthenticated">
<special-subject type="ALL_AUTHENTICATED_USERS" />
</security-role>
</application-bnd>
</application>

2. Save the [Link] file and back it up.

3. Add security constraints in the [Link] file of TM1 Web.
On the <PA_APP_HOST>, use a text editor to edit the <PA>/webapps/tm1web/WEB-INF/[Link]
file.
Before the first <filter> element, add the following content:

<login-config>
<auth-method>BASIC</auth-method>
<realm-name>[Link]</realm-name>
</login-config>
<security-role>
<role-name>AllAuthenticated</role-name>
</security-role>
<security-constraint>
<web-resource-collection>
<web-resource-name>tm1web</web-resource-name>
<url-pattern>/*</url-pattern>
<url-pattern>/</url-pattern>
<http-method>POST</http-method>
<http-method>GET</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>AllAuthenticated</role-name>
</auth-constraint>
</security-constraint>

4. Save the file.

5. Start the TM1 Application server service.
6. In a browser on a remote computer (not on <PA_APP_HOST>), open a Kerberos enabled browser and
access the following address:

HTTP://<PA_APP_HOST>:9510/tm1web

When the TM1 Server instance is selected, you are authenticated without being prompted.

Chapter 15. Planning Analytics Local security 255

 Configure security mode 2 or 3 to use websheets in Planning Analytics Workspace
If you set up TM1 Server, TM1 Web, and Planning Analytics Workspace Local using security mode 2 or 3
(integrated login), websheets cannot be used in Planning Analytics Workspace.
Note : Websheets will still work when accessed directly in TM1 Web.
To work around this limitation, you can choose to set up another instance of TM1 Web that is not
configured for integrated login.
There are three possible scenarios:
• If you plan to consume websheets only in Planning Analytics Workspace, you can use a single instance
of TM1 Web that is not configured for integrated login.
• If you plan to consume websheets only in TM1 Web and not Planning Analytics Workspace, you should
set up a single instance of TM1 Web that is configured for integrated login.
• If you need to consume websheets in both TM1 Web and Planning Analytics Workspace, you must set
up two instances of TM1 Web as follows.
– One instance of TM1 Web must be configured for integrated login that will be accessed directly by
users who use TM1 Web.
– A second instance of TM1 Web must be configured without integrated login, and Planning Analytics
Workspace must be configured to use this instance of TM1 Web with the Planning Analytics
Workspace administration tool or directly in the [Link] file. For more information, see “Connect to
TM1 and authentication servers” on page 165. You must not provide this URL directly to users.

Troubleshoot
• Make sure that your browser is correctly configured for SPNEGO/Kerberos. For more information, see
“Enable web browsers for integrated login” on page 257 and Configuring the client browser to use
SPNEGO.
• Access TM1 Web by host name. Accessing by IP address prevents Kerberos or SPNEGO authentication.
• Make sure that the Windows user that you are testing with is not a domain administrator. Domain
administrators cannot be delegated through Kerberos.
• Make sure that testing is performed on a remote computer. If the browser is run on the same computer
as TM1 Web, SPNEGO might fail.
• Optional: Edit the logging settings to add output for WebSphere authentication and SPNEGO to
WebSphere logs.
Edit the <logging> element in the WebSphere Liberty Profile [Link] file.
For example:

<logging
consoleLogLevel="WARNING"
traceSpecification="*=info:[Link].
*=all:[Link].
*=all:[Link].
*=all"
logDirectory="${[Link]}/../../logs"
messageFileName="tm1_messages.log"
maxFiles="2"
maxFileSize="20"
/>

1. Stop the TM1 Application service.

2. Empty the /logs folder.
3. Start the TM1 Application server to reproduce the issue.
• Enable Kerberos logging for the JRE that is running WebSphere Liberty Profile.
1. Stop the TM1 Application Service.

256 IBM Planning Analytics: Installation and Configuration

 2. In a text editor, open the <PA>/wlp/usr/server/tm1/[Link] file.
3. Append the following lines:

-[Link]=all
-[Link].krb5.Krb5Debug=all

4. Save the file.

5. Restart TM1 Application Service and reproduce the issue.
• Investigate errors with the kinit tool:
– Ensure [Link] is copied to the specified location.
– Run ping -4 <PA_APP_HOST> to learn the IP address returned by DNS. Then, run ping -4 -a
<IP> to ensure that the IP resolves to the same host name used in PA_SPN.
– Ensure that the keytab file is showing the correct host name.
– Ensure the account that PA_SPN is mapped to was not altered (encryption modes, user login name).
If it was altered, re-create keytab and try again.

Enable web browsers for integrated login

You must enable web browsers to forward Microsoft Windows authentication information to Planning
Analytics components that support integrated login.

Procedure
1. If you are using Microsoft Internet Explorer or Edge, specify that the TM1 Web URL is a trusted site and
enable Automatic logon with current username and password option and the Enable Integrated
Windows Authentication option in Internet Explorer.
For more information, see your Microsoft documentation.
2. If you are using Chrome or Firefox, locate and edit the following preferences so they include a comma-
separated list of URL prefixes or domains for the location of your TM1 Web server.

[Link]-uris

[Link]-uris

[Link]-uris

Enter localhost if you are running TM1 Web locally or enter the server name if you are running TM1
Web on a dedicated web server.
For more information, see your Chrome or Firefox documentation.

Configure Cognos TM1 Architect to use integrated login

After you set up integrated login for IBM TM1 Server, you can use it to access your TM1 data in TM1
Architect.

Procedure
1. Run Cognos TM1 Architect.
2. Click File > Options.
3. Verify that the Use Integrated Login check box is selected.
4. Click OK.
5. In the Tree pane of the Server Explorer, double-click to open the list of servers.
6. Double-click the server into which you exported your LDAP user and group information.
You should be logged in without being prompted to enter a user name or password.

Chapter 15. Planning Analytics Local security 257

 Configure Cognos TM1 Perspectives to use integrated login
After you set up integrated login for IBM TM1 Server, you can use it to access your TM1 data in TM1
Perspectives.

Procedure
1. Run Microsoft Excel.
2. Click TM1 > Server Explorer.
The TM1 Server Explorer displays.
3. Click File > Options.
4. Verify that the Use Integrated Login check box is selected.
5. Click OK.
6. In the Tree pane of the Server Explorer, double-click to open the list of servers.
7. Double-click the server into which you exported your LDAP user and group information.
You should be logged in without being prompted to enter a user name or password.

Configure access rights for Cognos TM1 users

For an IBM Cognos TM1 user to access any data, you might have to assign that user to other Cognos TM1
groups.

About this task

You can add a user to the Admin group. For example, for a user to publish public objects to the Web
through Cognos TM1 Web, the user must be a member of the Cognos TM1 Admin group.

Procedure
1. Start Cognos TM1 Architect.
2. Click File > Options.
3. Clear the Use Integrated Login option.
4. Click OK.
5. In the Tree pane of Server Explorer, double-click TM1 to open the list of servers.
6. Double-click a server name.
7. Log in using your administrator login ID and password.
• Administrator name (default) - admin
• Administrator password (default) - apple
8. Right-click the server name, and click Security > Clients and Groups.
9. Select a user to add to the admin group. Use the scroll bar to scroll to the left, where the list of groups
displays.
10. To add the user to the Admin group, select the check box in the ADMIN column for that user.
11. Click OK.

LDAP Authentication
TM1 Server asks you for a user name and password, and validates the login information against an
external LDAP server.
Planning Analytics supports LDAP authentication for TM1 Server on Microsoft Windows. LDAP
authentication is not supported for TM1 Server on Linux or other platforms.

258 IBM Planning Analytics: Installation and Configuration

LDAP Authentication overview
With LDAP authentication, an LDAP security service that is external to IBM TM1 authenticates a login. You
can add, modify, and delete user security information from one location - the LDAP server or Microsoft
Windows Active Directory.
The following image illustrates the process of authenticating by using LDAP.

Validating users with an LDAP server

LDAP validation allows you to centralize all of your user passwords in an external LDAP server.
When your TM1 users log in, the user name and password they provide is validated against the
information held in your LDAP server. You can specify a password and key to use before the server
connects for LDAP authentication, or the server can directly connect without the use of a password.
As a prerequisite to setting up LDAP authentication, you must have significant knowledge of LDAP and its
role in your network security structure. If you are not the LDAP administrator for your network, consult
with your LDAP administrator to properly set up TM1 Server to use LDAP authentication.
Note : Your LDAP server must be configured to use SSL to successfully communicate with TM1 Server.

LDAP authentication parameters

Use the following parameters in the [Link] file to configure and support LDAP authentication.
• “PasswordSource” on page 372
• “LDAPHost” on page 357
• “LDAPPasswordFile” on page 357
• “LDAPPasswordKeyFile” on page 357
• “LDAPPort” on page 357
• “LDAPSearchBase” on page 357
• “LDAPSearchField” on page 358

Chapter 15. Planning Analytics Local security 259

 • “LDAPSkipSSLCertVerification” on page 358
• “LDAPSkipSSLCRLVerification” on page 358
• “LDAPUseServerAccount” on page 358
• “LDAPVerifyCertServerName” on page 358
• “LDAPVerifyServerSSLCert” on page 359
• “LDAPWellKnownUserName” on page 359

Configuring LDAP validation

To configure LDAP validation, you will change the password in the [Link] file so that you can then
import names from your LDAP directory and modify group assignments for new users. Then change the
password back to the LDAP credentials.

Before you begin

To configure LDAP validation, you need the following information:
• A name that the TM1 Server can use to log in to LDAP. You can test the validity of this name using
ETLDAP.
• The SSL port on which your LDAP server is running. The default is 636.
• The name or IP address of the LDAP server you want to use for validation.

Procedure
1. To use your TM1 credentials to log in, change the password parameter in [Link] by completing
these actions:
a) Edit [Link] in your TM1 Server data directory.
b) Modify PasswordSource=LDAP to read PasswordSource=TM1
c) Save and exit [Link].
d) Restart your TM1 Server.
2. To import names from your LDAP directory into TM1 Server, complete these actions:
a) Use the procedure described in “ETLDAP utility” on page 274.
b) Use the following TM1 login information:
• Admin user (default) - Admin
• Admin password (default) - apple
Use the user that you specified during the installation to log in to LDAP.
3. To modify group assignments for new users, complete the following actions:
a) Log in to TM1 Server as an administrator.
b) Right-click the server name in Server Explorer and click Security, Clients and Groups.
c) Modify the groups assignments for your new users as required.
For each TM1 user ETLDAP added to your database, you must assign that user to the same group
they belong to in the LDAP directory. For example, if NadiaC is a member of the group gymnasts in
your LDAP directory, ETLDAP creates the user Nadiac, and creates the group gymnasts within TM1.
Nadiac displays in the Clients/groups dialog box as a member of gymnasts.
4. To change the password back to the LDAP credentials, complete these actions:
a) Edit [Link] in your TM1 Server data directory.
b) Modify PasswordSource=TM1 to read PasswordSource=LDAP
c) Define the connection status:
• To directly connect to the server, add the following line:

260 IBM Planning Analytics: Installation and Configuration

 LDAPUseServerAccount=T

• To use a password before connecting to the server, add the following lines:
LDAPPasswordFile= file
LDAPPasswordKey= key
d) Save and exit [Link] file.
e) Restart your TM1 Server.
You should now be able to log in to TM1 Server with a name that you added from your LDAP
directory.

Troubleshooting LDAP authentication

This topic describes error log messages that can arise when LDAPVerifyServerSSLCert=T in the [Link]
file.
The following message indicates that the certificate does not match any of the names that are listed in
LDAPVerifyCertServerName. Verify the certificate name and ensure that it has a
LDAPVerifyCertServerName entry in the [Link] file.

LDAP ERROR: 0x800b0109 - Error verifying server certificate chain validity

LDAP ERROR: Error verifying server certificate no match for <server>
LDAP ERROR: 0x51 - ldap_connect failed.

The following message indicates an issue with the trust of the LDAP server certificate by Microsoft
Windows. Ensure that the certificate has been imported into the Microsoft Windows Certificate Store.

LDAP ERROR: 0x800b010f - Error verifying server certificate chain validity

LDAP ERROR: Error verifying server certificate no match for <server>
LDAP ERROR: 0x51 - ldap_connect failed.

The following message indicates that either the certificate is revoked or TM1 is looking for the CRL
certificate but cannot find it in the Microsoft Windows Certificate Store. To correct the error, skip the CRL
check (set LDAPSkipSSLCRLVerification=T) or import the CRL certificate from the CA into the Microsoft
Windows Certificate Store.

LDAP ERROR: 0x80092012 - Error verifying server certificate chain validity

LDAP ERROR: Error verifying server certificate no match for <server>
LDAP ERROR: 0x51 - ldap_connect failed.

Cognos security
The IBM TM1 Server can authenticate users using IBM Cognos security.
Cognos security is a component of the IBM Cognos framework that manages user access to data. Cognos
security manages authorization and authentication through third-party security providers, such as LDAP
or Active Directory.
When a user is authenticated through Cognos security, they are provided with a Cognos security passport.
This passport is used by TM1 applications to determine the user's permissions (role and group
membership) and identity.

Overview to Cognos security

The IBM Cognos TM1 server can authenticate users using IBM Cognos security.
When you use Cognos security, a Cognos passport is required to connect to Cognos TM1. A user is
presented with a logon screen requiring a namespace, a user name, and a password when first logging in
to Cognos TM1 or any other Cognos security-enabled components. A passport is issued to the user when
they are authenticated by Cognos security. This passport automatically provides the user's credentials
when accessing any other Cognos security-enabled application (including Cognos TM1). When a user

Chapter 15. Planning Analytics Local security 261

 connects to the Cognos TM1 server using a specific Cognos server that is configured for common logon,
no direct user input is required to access additional Cognos TM1 servers (or other Cognos applications)
that are configured to reference the same Cognos server.
When a user attempts to access the Cognos TM1 server, the server validates the passport to authenticate
the user. This is done by querying a Cognos server for the identity of the passport. If the passport is valid,
the query returns a collection of security and authentication information for the user. This information
contains the roles and groups that the user has membership to, and the account (user name) associated
with the passport. If the user name exists in Cognos TM1, their existing membership is validated against
the existing Cognos TM1 groups. If the user does not exist, they are added and assigned to the
appropriate user groups on the Cognos TM1 server.
If a user runs the client program as an administrator (by right-clicking on the program file name and
selecting Run as administrator), two new folders are created after the client connects to CAM:
• installation_location\configuration
This folder contains the [Link] file.
• installation_location\logs
This folder contains the file [Link], if applicable.
By default, the [Link] file specifies that no log files are created in the logs folder, unless an error
occurs. You can edit the [Link] file if you want to have log files. You can also change the name of the
log file by editing the LogFilePath section. Before your changes can take effect, you must restart your
Cognos services.

Verifying the configuration of IIS for Cognos Analytics 11.0

To configure TM1 CAM authentication using Cognos Analytics 11.0, you must verify your configuration of
Microsoft Internet Information Service (IIS).
You can use the CA_IIS_config.bat script found in the technical note Automate the configuration of
Microsoft Internet Information Service to support IBM Cognos Analytics or manually complete the IIS
configuration that is described in Configuring IIS in Cognos Analytics 11.0.4 and later versions.
Remember : Take note of the alias name set in the CA_IIS_config.bat file before the script is run.
You should also verify the following items:
• The URLs in Cognos Configuration for Cognos Analtyics 11 must use the fully qualified domain name
(FQDN).
• The Gateway URL in Cognos Configuration for Cognos Analytics must be configured as follows:

[Link] name>/bi/v1/disp

Where [Link] is the FQDN for the Cognos Analytics gateway server and <alias name> is
the alias that was set in CA_IIS_config.bat before running the script.
• The .\<cognos analytics 11>\webcontent\[Link] and .\<cognos analytics 11>
\webcontent\[Link] files must be verified. If necessary, update the line that starts with <meta
http-equiv="refresh" as follows:

<meta http-equiv="refresh" content="0; URL=/<alias name>/bi/">

Where <alias name> is the alias used in the CA_IIS_config.bat script file.

262 IBM Planning Analytics: Installation and Configuration

Configuring the TM1 Server to use Cognos security
You can configure the IBM TM1 Server to use IBM Cognos security for authentication instead of the
default standard TM1 authentication.

Before you begin

To successfully complete these procedures, your IBM TM1 Server must not be configured to allow
anonymous access. If anonymous access is enabled on the TM1 Server, you cannot log on to a namespace
from TM1 when you import Cognos groups into TM1.

About this task

To enable IBM Cognos security authentication on the IBM TM1 Server, you must add or modify several
configuration parameters in the server's [Link] configuration file.
Note : If you want to reconfigure a TM1 Server that is already using Cognos security to use a different
instance of Cognos, you must remove any existing Cognos users and groups that were imported from the
first Cognos instance and then import users and groups from the new Cognos instance.
The Cognos Analytics gateway is optional. You can set up Cognos Analytics without the gateway for CAM
authentication. Some configuration steps different when the Cognos Analytics gateway is used. See also
step “3” on page 264.

Procedure
1. Open the [Link] configuration file in a text editor.
The [Link] file is located in the TM1 Server data directory. For more information, see “The
[Link] configuration file” on page 326.
2. Edit or add the following parameters in the [Link] configuration file.
a) Configure the ServerCAMURI parameter.
The URI for the internal dispatcher that the TM1 Server should use to connect to IBM Cognos
security. The URI is specified in the form:
http[s]://host IP address:port/p2pd/servlet/dispatch
Note : To find the URI, ask your IBM Cognos administrator to perform the following steps:
i) On the system hosting IBM Cognos, open IBM Cognos Configuration.
ii) Click to expand the Environment node.
iii) In the Properties pane, locate the Dispatcher Settings section and use the value from either
the External dispatcher URI or the Internal dispatcher URI property.
Note : In Planning Analytics version 2.0.9 or later, you can configure your TM1 Server CAM URI with
a Server Name Indication (SNI). The SNI can be set using the existing ServerCAMURI parameter in
the format of SNI;URI.
For example, without a Cognos Analytics gateway:

ServerCAMURI=[Link]

For example, with a Cognos Analytics gateway:

ServerCAMURI=[Link]

b) Configure the ClientCAMURI parameter.

The value for the IBM Cognos Analytics Gateway URI used to authenticate TM1 clients. The URI is
specified in the form:
http[s]://host:port/ibmcognos/bi/v1/disp or http[s]://host:port/bi/v1/disp

Chapter 15. Planning Analytics Local security 263

 Note : The values for host and ibmcognos are variables and depend on the exact settings that are
used. Contact your IBM Cognos administrator for more information about these settings.
For example, without a Cognos Analytics gateway:

ClientCAMURI=[Link]

For example, with a Cognos Analytics gateway:

ClientCAMURI=[Link]

For example, if your Cognos system is using Microsoft Internet Information Services (IIS):

ClientCAMURI=[Link]

c) Configure the ClientPingCAMPassport parameter.

Indicates the interval, in seconds, that a client should ping the IBM TM1 Server to keep their
passport alive.
If an error occurs or the passport expires, the user will be disconnected from the TM1 Server.
For example:

ClientPingCAMPassport=900

d) Configure the CAMPortalVariableFile parameter.

The path to the variables_TM1.xml file in your installation. In most cases, the path will be:

CAMPortalVariableFile = <portal>\variables_TM1.xml

The CAMPortalVariableFile parameter is required only when running TM1 Web.

CAMPortalVariableFile=templates\ps\portal\variables_TM1.xml

3. Take note of configuration differences with or without a Cognos Analytics gateway.

Without a Cognos Analytics gateway
The [Link] file would typically be configured as follows:

ServerCAMURI=[Link]
ClientCAMURI=[Link]

In the Cognos Analytics app tier install, the [Link] and [Link] files are stored in
the <Cognos Analytics>/webcontent directory. The [Link] file is stored in the
<Cognos Analytics>/webcontent/tm1/web/ directory.
With a Cognos Analytics gateway
The [Link] file would typically be configured as follows:

ServerCAMURI=[Link]
ClientCAMURI=[Link]

In the Cognos Analytics gateway install, the [Link] and [Link] file are stored in
the <Cognos Analytics>/webcontent/bi/ directory. The [Link] file is stored in the
<Cognos Analytics>/webcontent/bi/tm1/web/ directory
4. Set the IntegratedSecurityMode parameter to the default mode of 1.
Note : Setting the IntegratedSecurityMode parameter to 1 allows you to complete additional
configuration steps in TM1 using standard TM1 security before switching to Cognos security. After you
complete these additional steps, you can change this parameter to either 4 or 5 to use Cognos
security.
For example:

IntegratedSecurityMode=1

264 IBM Planning Analytics: Installation and Configuration

5. Save and close the [Link] file.
6. Restart the TM1 Server.
7. Perform the required steps for your Cognos Analytics installation.
a) Define a Cognos user to function as a Planning Analytics administrator.
b) Import Cognos groups into Planning Analytics.
For more information, see “Managing TM1 users, groups, and objects when using Cognos security” on
page 265.
8. Configure the TM1 Server to start using Cognos authentication.
a) Shut down the TM1 Server.
b) Open the [Link] configuration file in a text editor.
c) Set the IntegratedSecurityMode parameter to indicate that the server should use Cognos
authentication.
The exact parameter value depends on the specific TM1 components you are using:
• If you are not using the TM1 Applications component, set the parameter to 4.

IntegratedSecurityMode=4

• If you are using TM1 Applications with Cognos security, set the parameter to 5 to support user
groups from both Planning Analytics and Cognos.
IntegratedSecurityMode=5
d) Save and close the [Link] file.
e) Restart the TM1 Server.

What to do next
See the following configuration topics to complete the configuration:
• “Configuring Cognos TM1 clients to use Cognos security” on page 267
• “Configuring Cognos TM1 Web to use Cognos security” on page 268
• “Using Cognos TM1 Applications with Cognos security” on page 269

Managing TM1 users, groups, and objects when using Cognos security
To successfully administer IBM Cognos TM1 while using IBM Cognos Analytics security for authentication,
an existing Cognos user must be added to the Cognos TM1 ADMIN group.

Defining a Cognos user to function as a Cognos TM1 administrator

You must define a Cognos user as the Cognos TM1 administrator who will be used to import Cognos
groups into Cognos TM1.
Important : The initial steps for this configuration must be done with the Cognos TM1
IntegratedSecurityMode parameter set to 1. You then change this parameter to use Cognos Analytics
security at a later point in the steps.

Procedure
1. Log in to Cognos TM1 as an administrator.
2. From the Server Explorer, click Server > Security > Clients/Groups.
3. From the Clients/Groups dialog box, click Clients > Add New Client.
The Cognos logon dialog box appears.
4. Enter your Cognos user ID and password, then click OK.
5. In the Name box, click the namespace to which you are currently logged in.

Chapter 15. Planning Analytics Local security 265

 Note : Only users from the namespace to which you are logged in can be imported into Cognos TM1.
Other namespaces may appear in the Name box, but you cannot import users from them.
The contents of the Name box update to display the directories available on the selected namespace.
6. Enable the Show users in the list option.
7. Navigate to the directory containing the Cognos user you want to define as a Cognos TM1
administrator. In most circumstances, you will define your own Cognos user as a Cognos TM1
administrator, as you must know the Cognos user's ID and password to complete administrative
tasks.
8. Select the user.
9. Click the green arrow icon to move the selected user to the Selected Entries list.
10. Click OK to import the Cognos user into Cognos TM1.
The user appears as a new client in the Client/Groups window, but is not assigned to any Cognos TM1
groups.
11. Assign the new user to the ADMIN group and click OK.
12. Shut down the Cognos TM1 server.
13. Open the [Link] configuration file in a text editor.
14. Set the IntegratedSecurityMode parameter to indicate that the server should use IBM Cognos
authentication. The exact parameter value depends on the specific Cognos TM1 components you are
using:
• If you are not using the Cognos TM1 Applications component, set the parameter to 4.

IntegratedSecurityMode=4

• If you are using Cognos TM1 Applications with Cognos security, set the parameter to 5 to support
user groups from both Cognos TM1 and Cognos.

IntegratedSecurityMode=5

15. Save and close [Link].

16. Restart the Cognos TM1 server.

Importing Cognos groups into Cognos TM1

After an IBM Cognos user is defined as the Cognos TM1 administrator, that user can import Cognos
groups into Cognos TM1.
You should import only the Cognos groups that you want to allow to access the Cognos TM1 server.

Procedure
1. In the Server Explorer, double-click your Cognos TM1 server.
The Cognos logon dialog box appears.
2. Log on as the Cognos user that you have defined as the Cognos TM1 administrator.
3. From the Server Explorer, click Server, then Security, then Clients/Groups.
4. From the Clients/Groups window, click Groups, then Add New Groups.
5. In the Names box, click the namespace to which you are currently connected.
Note : Only groups from the namespace to which you are connected can be imported into Cognos TM1.
Other namespaces may appear in the Name box, but you cannot import groups from them.
6. Navigate through the directory structure and select the Cognos groups you want to import into Cognos
TM1.
7. Click the green arrow icon to move the selected user to the Selected Entries list.
8. Click OK to import the Cognos groups into Cognos TM1.

266 IBM Planning Analytics: Installation and Configuration

 If you review the User Group Assignment section of the Clients/Groups window, you should see the
Cognos groups added to your server.

Creating TM1 users when using Cognos security

When the IBM Cognos TM1 server is configured to use Cognos authentication, you cannot create new
clients directly on the Cognos TM1 server.
Instead, all client administration is performed in Cognos security.
When a Cognos user accesses Cognos TM1, the user is validated and automatically assigned to the
appropriate Cognos TM1 groups. There is no need to manually assign users to groups in Cognos TM1.

Administering Cognos TM1 object security when using Cognos authentication security
While IBM Cognos authentication automatically manages users on the IBM Cognos TM1 server, the
Cognos TM1 administrator must still manage object security to allow Cognos users to view and use
Cognos TM1 objects.
For details on administering Cognos TM1 object security, see Cognos security in the TM1 Developer
documentation.

Configuring Cognos TM1 clients to use Cognos security

You must add two parameters to your [Link] file to allow you to perform IBM Cognos security-related
administrative tasks from your Cognos TM1 client.

Procedure
1. Open the [Link] configuration file in a text editor.
For information on the location of the [Link] file, see “Location of the [Link] File” on page 389.
2. Add the following parameters to the [Link] file.

Table 24. Parameters for the [Link] file

Parameter Name Description

CognosGatewayURI The URI for the Cognos Analytics Gateway. The URI is specified in the
form
http[s]://host:port/bi/v1/disp or (with a web server) http[s]://host:port/
ibmcognos/bi/v1/disp
For example:[Link] or http://
[Link]/ibmcognos/bi/v1/disp.

AllowImportCAMClients Determines if Cognos clients can be imported into Cognos TM1. This
parameter must be set to T when setting up Cognos security in Cognos
TM1.

Your [Link] file should include parameters similar to the following:

AllowImportCAMClients = T

CognosGatewayURI = [Link]

or

CognosGatewayURI = [Link]

3. Save and close [Link].

4. Restart your Cognos TM1 client.

Chapter 15. Planning Analytics Local security 267

 Configuring Cognos TM1 Web to use Cognos security
Follow these steps to configure IBM Cognos TM1 Web to use IBM Cognos authentication security.

Before you begin

Note : If you applied a Cognos Analytics updater kit to your Analytics installation, you might need to make
specific updates to the [Link] file.
The [Link] file supports Cognos TM1 Web to use IBM Cognos authentication security. However, it
does not get updated when you apply a Cognos Analytics updater kit. Instead, an updated file that is
called [Link] is placed in the same Cognos Analytics ...\webcontent\tm1\web directory
as the original file. Use the newer version of [Link] and update it with any changes you made in
the original [Link] file.

About this task

These steps include editing configuration files on your Cognos TM1 Web system and copying them over to
your Cognos Analytics system.

Procedure
1. Locate and extract the following Cognos TM1 Web gateway files in your Cognos TM1 Web installation
directory.
variables_TM1.xml
This file is located in templates\ps\portal.
[Link]
This file is located in webcontent\tm1\web.
These files are compressed into the bi_interop.zip file here:
\<TM1 installation location>\bi_interop\
For example:
C:\Program Files\IBM\cognos\tm1_64\bi_interop\
2. Copy the files to your IBM Cognos Analytics installation.
variables_TM1.xml
Copy this file to <Cognos location>\templates\ps\portal on every server where the TM1
Web Tier is running on your IBM Cognos Analytics system.
[Link]
Copy this file to <Cognos location>\webcontent\bi\tm1\web on every server where the
Cognos Analytics Gateway is running on your IBM Cognos Analytics system.
3. Edit the [Link] file to point to where Cognos TM1 Web is running.
var tm1webServices = ["[Link]
For example:
var tm1webServices = ["[Link]

Configuring Cognos TM1 Operations Console to use Cognos security

Deprecated in v2.0.9 You can configure IBM Cognos TM1 Operations Console to use IBM Cognos
Analytics security, also called Cognos Access Manager (CAM) authentication.

Before you begin

At least one TM1 server must be configured for IBM Cognos Analytics security. This is required in order to
store the Operations Console user group information. You must know the name of this TM1 server to

268 IBM Planning Analytics: Installation and Configuration

complete the steps in this topic. For complete details and configuration steps, see “Cognos security” on
page 261 and “Configuring the TM1 Server to use Cognos security” on page 263

About this task

To configure Operations Console to use IBM Cognos Analytics security, you work with files on the
computers hosting these two components.

Procedure
1. Open Performance Management Hub by going to [Link]
2. Expand Configurations > Operations Console TM1 Monitors.
3. Verify the values in the DefaultAdminHost, DefaultGroup, and DefaultServer fields. See “Configuring
the Cognos TM1 Operations Console” on page 139.
4. Expand PMHub Security.
5. Set CAMBIURL to the Cognos Analytics Server dispatcher URL.
You can find this value in Cognos Configuration under Environment > External dispatcher URI. The
value in the ServerCAMURI parameter of the [Link] file should be similar.
For example: [Link]
6. Set CAMGatewayURL to the Cognos Analytics Server gateway.
You can find this value in Cognos Configuration under Environment > Gateway URI. The value in the
ClientCAMURI parameter of the [Link] file should be similar.
For example: [Link]
7. Copy the ..\tm1_64\bi_interop\bi_interop.zip file from the TM1 installation location to the
root of the Cognos Analytics Server installation directory (the ..\c10_64 directory).
If you are using a distributed Cognos Analytics server environment, copy the file to the computer that
is running the TM1 Data Tier or TM1 Web tier.
8. Extract bi_interop.zip so the directory structure is maintained.
The [Link] file should be in the ..\c10_64\webcontent directory.
9. Edit line 51 in the [Link] file to include the fully qualified domain name and port number of the
IBM Cognos TM1 Applications Service that runs the TM1 Operations Console.

• If you are using the WebSphere Liberty Profile web server provided with TM1, this is the server
where TM1 Application Server is running.
• If you are using your own web server, this is the server where you deployed [Link].
For example:

var pmhubURLs = ["[Link]

You can also include multiple URLs if the TM1 Operations Console is used on multiple systems. For
example:

var pmhubURLs = ["[Link]

"[Link]

Using Cognos TM1 Applications with Cognos security

You can configure IBM Cognos TM1 Applications to use IBM Cognos Analytics security. This configuration
requires users to log in to Cognos TM1 Applications as a valid user that exists in the Cognos Analytics
server. This configuration also integrates Cognos TM1 Applications with Cognos Analytics by displaying
links to Cognos TM1 Applications in the IBM Cognos Connection portal.
When you use Cognos TM1 Applications with Cognos Analytics Security, the Cognos TM1 Application
Server can be hosted on a web application server in one of the following ways:

Chapter 15. Planning Analytics Local security 269

 • On a different computer with the WebSphere® Liberty server that was provided with the Cognos TM1
installation
• On a different computer with your own installation of IBM WebSphere
In all cases, you must edit the [Link] file and copy this file to the Cognos Analytics server so
that the Cognos Analytics server knows the location of the Cognos TM1 Application Server.
Note : You must have the TM1_PATH environment variable specified before connecting to Cognos TM1
under a UNIX environment.

Configuring Cognos TM1 Applications to use Cognos Analytics Security

To configure IBM Cognos TM1 Applications to use IBM Cognos Analytics security, you work with files on
the computers hosting these two components, plus the computer where the Cognos TM1 Server is
running. This configuration also enables the IBM Cognos Connection portal to show links to Cognos TM1
Applications so that users can open the applications that they rights to from within the Cognos
Connection portal.

Before you begin

The Cognos TM1 server must be configured to use Cognos Analytics security.
To use Cognos TM1 Applications with Cognos Analytics security, the IntegratedSecurityMode
parameter in the Cognos TM1 [Link] configuration file must be set to 5 to support user groups from
both Cognos TM1 and Cognos Analytics.
For complete details and configuration steps, see “Cognos security” on page 261 and “Configuring the
TM1 Server to use Cognos security” on page 263.
Note : You must configure the TM1_PATH environment variable before you can connect to Cognos TM1
under a UNIX environment.

Procedure
1. Extract the content of the bi_interop.zip file into your existing Cognos Analytics installation.
Note : As of Cognos TM1 version 10.2.2, the bi_interop.zip replaces the
planning_gateway.zip file that was provided with previous versions of Cognos TM1.
a) Locate the bi_interop.zip file that is provided with the Cognos TM1 installation in the following
location.
Cognos TM1 location\bi_interop\
b) Extract and merge the content of the bi_interop.zip file into the root directory of your existing
Cognos Analytics installation.
For example: C:\Program Files\IBM\cognos\ca_64\
Note : The bi_interop.zip file contains a directory structure that merges files into the
\templates and \webcontent subdirectories.
c) To manually extract and copy the files to your Cognos Analytics installation, copy the files as
follows:
If you are using a distributed Cognos Analytics server environment, copy these files to the
computer that is running the TM1 Data Tier or TM1 Web Tier as follows.
[Link]
Copy [Link] to CA Install Dir\webcontent and to CA Install Dir
\webcontent\bi where the Cognos Analytics Gateway is installed.
icon_active_application.gif
Copy icon_active_application.gif to CA Install Dir\webcontent\ps\portal
\images where the Cognos Analytics Gateway is installed.

270 IBM Planning Analytics: Installation and Configuration

 variables_plan.xml
Copy variables_plan.xml to CA Install Dir\templates\ps\portal wherever the
presentation service (Application tier) is running in a Cognos Analytics server.
Note : These files are also installed with newer Cognos Analytics installations. If the files exist on
your Cognos Analytics server, then you only need to edit them as explained in these steps.
2. Edit the [Link] file.
Important : The values for the planningServices parameter in this file are required to ensure that
the Cognos Analytics server redirects users to only approved locations. The location of the Cognos
TM1 Application Server from where the user logs in must be validated to be one of the approved
locations in this file. Otherwise, the Cognos Analytics server will not redirect the user.
a) Open the [Link] file and locate the following lines:
// Update the following to point to the location of the planning
service(s)
var planningServices = ["[Link]
b) Set the planningServices parameter to the location and port number for the Cognos TM1
Application Server.
var planningServices = ["[Link]
Replace web_server_address with the fully qualified domain name (FQDN) for the computer where
the Cognos TM1 Application Server is running. For example, [Link]
• If you are running the Cognos TM1 Application Server with the WebSphere® Liberty server that is
provided with the Cognos TM1 installation:
var planningServices = ["[Link]
• If you are running the Cognos TM1 Application Server with your own web application server, use
the location and port number for that system.
Tip : If you are using the same Cognos Analytics server to authenticate different instances of
Cognos TM1 Applications that are running on multiple computers, use a comma-separated list with
the fully qualified domain name (FQDN) for each computer. For example:
var planningServices = ["[Link]
[Link]:port_number"];
Tip : If the Cognos TM1 Application Server is running on a web server that belongs to multiple
domains, use a comma-separated list to enter the fully qualified domain name for each domain. For
example:
var planningServices = ["[Link]
computer_A.domain_2:port_number","http://
computer_A.domain_3:port_number"];
c) Save and close the [Link] file.
3. Configure the session timeout parameters for Cognos TM1 Applications and Cognos Analytics security
to ensure the proper timeout detection.
For details, see “Configuring session timeout values for Cognos TM1 Applications and Cognos
Analytics Security” on page 272.
4. Restart the Cognos Analytics server.
5. Configure Cognos TM1 Applications with values for the IBM Cognos Gateway URI and IBM
Cognos Dispatcher URI .
a) Open Cognos TM1 Applications using the format of the following link:
[Link]
For example: [Link]
b) Log in and open the Cognos TM1 Applications Configuration page:

Chapter 15. Planning Analytics Local security 271

 • If you are running Cognos TM1 Applications for the first time, the Configuration page opens after
you log in.
• If you already configured Cognos TM1 Applications, open the Configuration page by clicking the
Administer IBM Cognos TM1 Applications icon on the toolbar of the TM1 Applications portal
page.
c) On the TM1 Applications Configuration page, enter values for the following Cognos TM1 and
Cognos Analytics parameters:
• Enter values in the TM1 Admin Host and Server Name fields and configure the options for the
data contribution clients that you want to use. For details, see “Configuring the server and client
environment for TM1 Application Web” on page 121.
• Set the IBM Cognos Gateway URI parameter. For example:
[Link]
• Set the IBM Cognos Dispatcher URI parameter. For example:
[Link]
Replace CognosServerName with the name of the system where the Cognos Analytics web
server is running.
6. To test the configuration, log in to Cognos TM1 Applications using a web browser on a remote
computer.
If you see the following error, review your settings for the planningServices parameter in the
[Link] file on the Cognos Analytics server.
The planning service parameter was not specified or is not
one of the configured locations

Configuring session timeout values for Cognos TM1 Applications and Cognos Analytics
Security
When using IBM Cognos TM1 Applications with IBM Cognos Analytics security, set the pmpsvc session
timeout to a value higher than the CAM session timeout to ensure the proper timeout detection. If the
Cognos TM1 Applications (pmpsvc) session timeout is set to a value lower than the Cognos Analytics
security (CAM) session timeout, then Cognos TM1 Applications will not properly detect a CAM session
termination and will not timeout.

About this task

To ensure that Cognos TM1 Applications can properly detect a CAM session termination, set the pmpsvc
session timeout to a value higher than the CAM session timeout.
• The pmpsvc session timeout is the number of minutes of inactivity after which Cognos TM1 Applications
terminates a user session. The default value is 60 minutes (1 hour).
• The CAM session timeout is the number of seconds of inactivity after which Cognos security terminates
a user session. The default value is 3600 seconds (1 hour).

Procedure
1. Configure the pmpsvc session timeout parameter.
a) Locate the fpmsvc_config.xml file in the WEB-INF/configuration directory.
• When Cognos TM1 Applications is deployed with the WebSphere® Liberty server that is provided
with the Cognos TM1 installation, the fpmsvc_config.xml file is here:

Cognos_TM1_install_location\webapps\pmpsvc\WEB-INF\configuration
b) Enter a value for the timeout attribute of the service / session element.
Use the format for the service / session / timeout attribute as defined in the XML schema
definition file fpmsvc_config.xsd located in the same directory.

272 IBM Planning Analytics: Installation and Configuration

 For example:
<session timeout="60"/>
2. On your Cognos Analytics system, configure the CAM session timeout using IBM Cognos Configuration.
Enter a value in the Inactivity timeout in seconds field in the Security/Authentication section of
Cognos Configuration.

Administrator considerations when using Cognos authentication

IBM Cognos TM1 administrators should be aware of the some issues when configuring the Cognos TM1
server to use IBM Cognos authentication.
The issues are as follows:
• Review the description of Cognos TM1 security modes 4 and 5 for the IntegratedSecurityMode
parameter. You should understand how these different modes control whether or not Cognos users can
belong to Cognos TM1 user groups. For details, see the description of the IntegratedSecurityMode
parameter in TM1 Operations.
• You cannot use Cognos TM1 to permanently assign a Cognos user to another Cognos group. Any user
assignment you make in Cognos TM1 to a Cognos group is not saved back to Cognos. When a Cognos
user logs in to Cognos TM1, the group assignments in Cognos override any Cognos group assignments
made in Cognos TM1.
• If you rename a Cognos user after importing that user to Cognos TM1, you must then delete the user in
Cognos TM1 in order to update Cognos TM1 with the new user name. After deleting the user in Cognos
TM1, the new name will appear the next time the user logs in.

User considerations when using Cognos authentication

IBM Cognos TM1 users should be aware of issues that may arise when accessing the Cognos TM1 server
configured to use IBM Cognos authentication.

Authentication behavior
Rules govern authentication behavior when logging on to the IBM Cognos TM1 server that uses IBM
Cognos authentication.
The rules are as follows:
• If common logon is enabled in IBM Cognos and you have previously logged in to an IBM Cognos
application and maintain an active session, you are not prompted for credentials when logging on to the
Cognos TM1 server.
• If common logon is enabled in IBM Cognos and you have not previously logged in to an IBM Cognos
application, you are prompted for credentials when logging on to the Cognos TM1 server.
• If common logon is not enabled in IBM Cognos, you are prompted for credentials when logging on to the
Cognos TM1 server, even if the server is configured to use IBM Cognos authentication.

Private Cognos Security sessions

When an IBM Cognos server is configured to use common logon, you will be challenged only once for
credentials.
Any subsequent connections to other IBM Cognos security-enabled applications (including Cognos TM1)
which are configured to reference the same IBM Cognos server will automatically occur, provided your
Cognos security passport is valid.
For example, if you have three available Cognos TM1 servers, all configured to use the same IBM Cognos
server, once you connect to the first server as user X in namespace Y, all connections to the other Cognos
TM1 servers will automatically occur using the passport of user X from namespace Y.
In some circumstances, you might want to log on to the Cognos TM1 server as a user other than the one
identified by your Cognos security passport. To accommodate this, the Logon As option lets you override
the automatic authentication that usually occurs with a passport, while maintaining the validity of the

Chapter 15. Planning Analytics Local security 273

 passport for later use. When you log on to the Cognos TM1 server using the Logon As option, a private
session is established. The credentials used to establish the private session are not stored in a passport
and are not shared with any other application. Any existing passport remains valid and can be used to
access other IBM Cognos security-enabled applications.

Procedure
1. From the Server Explorer, click Server, then Logon As.
2. In the Cognos Logon window, enter the User ID and Password you want to use to log on to the Cognos
TM1 server.
3. Click OK.

Establishing a replication with Cognos security

When establishing a replication connection to the IBM Cognos TM1 server that uses IBM Cognos
authentication, you must provide the IBM Cognos Namespace ID of the namespace.
Do not provide the descriptive name of the namespace.

ETLDAP utility
You can use the ETLDAP utility to add LDAP (Lightweight Directory Access Protocol) users to IBM TM1
Server when you use TM1 Server with Integrated Login and LDAP authentication.
Note : You can only use the ETLDAP utility to add new LDAP users to TM1 Server. ETLDAP does not
modify, update or delete existing users in TM1 Server.
ETLDAP, an LDAP load tool, provides the following functionality:
• Extracts user information from an LDAP or Active Directory server.
• Creates the element UniqueID in the }ClientProperties dimension.
• Adds users to the }ClientProperties cube.
• Populates the UniqueID field in the }ClientProperties cube with the domain-qualified user name of the
user you add to TM1 database. For example, ETLDAP writes the name robert@[Link] to
the }ClientProperties cube.
As the TM1 administrator, you can perform these tasks using ETLDAP:
• Add many user names from an LDAP server to the TM1 database quickly.
• Migrate information from a legacy LDAP database to TM1.
• Perform one or more queries to specify the users you want to create in TM1 Server, and then export the
users into the TM1 security cubes.
• Update TM1 with new users that have been added to the LDAP server since the initial load of user data
into TM1.
Note : The ETLDAP utility is not available when the IBM TM1 Server is configured to use one of the
following Integrated Security Modes:
• Integrated Security Mode 3 - Integrated Login
• Integrated Security Mode 5 - IBM Cognos Analytics authentication
However, you can use ETLDAP to prepare your user and security data for Integrated Security Mode 3
server operation. In this case, you must configure your server to use Integrated Security Mode 1 or 2
while using the ETLDAP utility. Then, after all user and security data has been prepared, you must
reconfigure your server to use Integrated Security Mode 3 during normal operation.
See “IntegratedSecurityMode” on page 352 for more information about Integrated Security Mode
options.

274 IBM Planning Analytics: Installation and Configuration

Modifying LDAP attributes
The value of an attribute you retrieve from an LDAP directory may not precisely match what you want to
enter in the TM1 security cube.
If so, you must modify certain LDAP attributes before you can run ETLDAP.
For example, you could combine all users from the R&D, Quality Assurance, and Documentation LDAP
groups into a single TM1 group named Engineering. To support these requirements, you can extend a Java
class with a single method you need to override.
The stringFilter class contains one method with the following signature:

String filterString(String attrName, String value)

At run time, this method is passed the name of each LDAP attribute that matches a mapping entry and its
value. The String it returns is added to the TM1 database.
The following code demonstrates the implementation of the stringFilter class, combining all users
from the R&D, Quality Assurance, and Documentation LDAP groups into a single TM1 group named
Engineering.
The stringFilter class looks for instances of the LDAP ou attribute, which is the TM1 Group names field. If
the value is R&D, Quality Assurance, or Documentation, it returns Engineering. The users from any of
the 3 LDAP groups are added to a single TM1 Engineering group. Any other group value remains
unchanged.

// The stringFilter class provides the ability to transform strings

// which are read from the LDAP database before they are inserted into
// TM1's datastore.
//
// To implement this feature, create a class which extends stringFilter
// and contains a method 'filterString' with the following signature:
//
// String filterString(String attrName, String value)
//
//
public class myStringFilter extends stringFilter
{
public String filterString(String attrName, String value)
{
if ([Link]("ou"))
{
if ( ([Link]("R&D")) ||
([Link]("Quality Assurance")) ||
([Link]("Documentation")) )
return "Engineering";
else
return value;
}
else
return value;
}
}

After you write and compile the Java code, put the class somewhere in your Classpath. Then click Edit >
Options and enter its name in the Class Name field.

Running ETLDAP
You can run ETLDAP from the Microsoft Windows operating system or the DOS command window with
command-line parameters.

Procedure
1. If you want to run ETLDAP from the Microsoft Windows operating system, complete the following
actions:
• Click Start > Programs > IBM Cognos > TM1 > Administration > ETLDAP.

Chapter 15. Planning Analytics Local security 275

 • Set the elements that you require.

Table 25. Elements in the LDAP Load Tool dialog box.

Field or Button Description

Search DN Displays the LDAP node at which the search originates. ETLDAP
does not search for entries above this level in the tree.

Filter Displays the query string that filters the entries in the directory and
generates the matching records.

Attributes Displays the attribute values for LDAP entries that assist in
validating the records returned by the search. When you export the
LDAP information to TM1, ETLDAP retrieve the attributes required
to create valid TM1 users.
Note: The attributes are for display purposes only.

Search Scope Specifies the starting point of the search, and the search level.
Select One level to specify all entries one level below the base
Search DN, but not the base DN itself. Select Sub-tree level to
search all entries beneath the base DN, including the base DN.

Results Table Displays the search results. Click the column headers to sort the
data, or right-click in a row and click View Entry to examine all
attributes for that entry.

Search Button Performs the search using the parameters you select.

Export Button Exports the displayed set of users to TM1 based on the settings in
the Options dialog box.

2. If you want to run ETLDAP from the DOS command window, complete the following actions:
• Click Start > Programs > Accessories >Command Prompt.
• Enter the following command line:
java etldap options
• Add the parameters that you require.

Table 26. Supported command-line parameters

Parameter Description

-f filename Passes the name of a saved session file to load all configuration
settings from a previous session.
When you run ETLDAP in unattended (batch) mode, you must
include a name for the session save file. If this file does not contain
the passwords necessary to connect to the LDAP and IBM TM1
Server, an error message is written to the log file and the session is
terminated.

-batch Runs ETLDAP in command-line mode with no user interface.

Requires the -f option.

276 IBM Planning Analytics: Installation and Configuration

 Table 26. Supported command-line parameters (continued)

Parameter Description

-secure When you run ETLDAP in batch mode, passing this flag removes all
passwords from the session file referenced by the -f flag after they
have been read.
This parameter reads the save file at the beginning of the session,
and then re-writes the file with the passwords removed. While in
use, you would run ETLDAP and specify the passwords with the
user interface. Then you would exit ETLDAP and run the command
line version specifying the '-secure' option. This would insure that
the passwords were only available for the short period of time it
takes for the utility to initialize.

-help Displays online Help for these command-line parameters.

Configuring the LDAP login parameters

You can configure the LDAP login parameters.

Procedure
1. In the LDAP Load Tool dialog box, click File > Connect.
2. Enter the following host and user information.

Panel Field Description

Host Info Host Enter the host name or IP address of the machine
where the LDAP server is running.

Port The port on which the LDAP server is running. If a

port is not specified, 636 is used. Cognos TM1
attempts to bind to an LDAP server on the specified
secure port. If you do not enter an LDAPPort value,
Cognos TM1 uses the default value of port 636.

Version ETLDAP will most likely ignore the version number.

Most LDAP servers support version 2 or version 3
type connections, ETLDAP does not use any
functionality specific to either version.

SSL option Determines whether the communication between

the LDAP server and ETLDAP happens over a secure
encrypted channel. Unless you are viewing secure
information over an insecure network, leave this
option turned off.

Anonymous option Most LDAP servers have some layer of security

configuration that requires you to authenticate as a
known user. In some systems, anonymous users
can browse the directory, but not retrieve the
schema. In other systems, an anonymous user
might have access to certain insecure areas of the
directory, but not others.

Chapter 15. Planning Analytics Local security 277

 Panel Field Description

User Info User DSN In many cases, your LDAP directory prevents
Anonymous users from accessing or modifying data.
In this case, you may need a Distinguished Name
(DN) and password to complete the extraction of
your LDAP security information.
For example, the name Norm Lodin might refer to a
person who works at Blodget, Inc. Inside LDAP, he
has a Distinguished Name that uniquely
distinguishes him from all other entities in the
network.
Norm might enter the following information in the
User Info field.
uid=nlodin, ou=People, o=[Link]

Password Enter a password that corresponds to the User DN.

3. To see if the connection is successful, click Test.

4. Click OK.
You have established a connection to your LDAP server with the parameters you specified.

Building an LDAP query

Use an LDAP query to add LDAP users and groups to IBM Cognos TM1.

Before you begin

An LDAP query consists of the following major elements:
• Search DN - An LDAP directory is organized as a tree structure, with a root node and a number of
branches off this root. The Search DN specifies at which node the search originates. Entries above this
level in the tree are searched. You must specify the correct base DN to obtain the results you want.
• Filter - A query string that filters the entries in the LDAP directory and generates the matching records.
You can create complex filters by using a combination of the following symbols:
& (AND)
| (OR)
! (NOT)
* wildcard character
( ) parentheses for nesting
For instructions on building LDAP filter strings, refer to LDAP books and online resources, including the
LDAP standard, RFC 2254, The String Representation of LDAP Search Filters.
• Scope - While the Search DN specifies the starting point of the search, the Scope attribute indicate the
level of depth to which the search occurs. There are two Scope levels:
One Level - Specifies that LDAP search all entries one level below the base DN, but does not include the
base DN itself.
Sub-Tree Level - Indicates that LDAP search all records at all levels including the base DN.
The following diagram illustrates the effect that the Scope setting has on a search.

278 IBM Planning Analytics: Installation and Configuration

• Attributes - Describe every LDAP entry and their values. Includes a comma-separated list of values to
return for the records that match the filter string. There are two LDAP attributes:
User attribute - You add this attribute to the LDAP directory. For example, cn or mail.
Operational attribute - The LDAP server creates and maintains this attribute. For example,
numSubordinates.
The attributes for an entry could include:
Present with no value
Present with one or more values
Not present. If an attribute is optional, the attribute may not exist for an entry.
Note : Be sure to request only the attributes you need. If you request all attributes, a large result set can
significantly increase processing time on the LDAP server and memory requirements on both the server
and the client.

Procedure
1. Specify the Search DN, Filter String, Attributes, and Scope for your query.
2. Click Search.
You see a list of entries in the table, unless there are syntax errors or if the filter string does not match
any records in the directory.
3. Examine the result set.
• Does it include names that you do not want to see?
• Are important entries missing?
• Do you need to build multiple queries to capture the list of records you are interested in?
4. Make your changes to the filter string.
5. Click Search.
6. Examine the result set.
7. Repeat steps 3 through 6 until you have a list of valuable records.
8. Click File, Save As to save your LDAP query as a text file.
Note : You can use the saved LDAP query at a later time. To do so, click File > Open in the LDAP Load
Tool dialog box. ETLDAP fills in the DN, Filter String, Attributes, and Scope for your LDAP query.

Connecting to the IBM TM1 Server

Follow these steps to connect to the IBM TM1 Server server.

Chapter 15. Planning Analytics Local security 279

 Procedure
1. Click Edit > Login > TM1.
2. Enter the following server information:

Field Description

Host The machine name of the server on which your TM1 Admin Server is
running.

SSL port Enter the port number configure which the admin server will use. The
default is 5498

Server The name of the TM1 server to which you want to connect.
Click Server and then the Browse button to select a server from the
Server list.

Username The name of a user with Admin privileges on the target TM1 server.

Password The password of the admin user.

3. To see if the connection is successful, click Test.

4. Click OK.

Mapping LDAP attributes to Cognos TM1 fields

LDAP directories contain many attributes, some of which you standardize, and others which you add or
customize for your environment. You must specify the relationship between the LDAP attributes and the
required IBM Cognos TM1 fields manually.

Before you begin

You should be familiar with your LDAP schema.

Procedure
1. Click Edit > Mapping > TM1.
2. For each required (red) Cognos TM1 field, select an LDAP schema attribute.
For each user, Cognos TM1 requires a unique name and group name. For example, you could map the
name attribute in your LDAP schema to the Cognos TM1 user, and map the department attribute to the
Cognos TM1 group.
3. Click OK.

Specifying the ETLDAP export options

You can specify the ETLDAP export options.

Procedure
1. Click Edit > Options.
2. Select Enable Integrated Login.
3. Enter the realm name that contains the users you want to transfer.
4. Clear Save Passwords.
When you clear Save Passwords, ETLDAP removes all passwords necessary to connect to the servers
before the session save file is written. The next time you run ETLDAP, you would have to enter the
passwords again.

280 IBM Planning Analytics: Installation and Configuration

5. Set Maximum Search Results and Search Time Limit to 0.
6. Click OK.

Exporting LDAP information to Cognos TM1

You can export LDAP information to IBM Cognos TM1.

Procedure
1. Click Export.
ETLDAP moves the records you retrieved from the LDAP directory into TM1, and logs the data export
activity in a log file.
Note : You can open the log before you export records to track the export progress.
2. Click View, Log to open the Session Log.
The Session Log shows a summary of the LDAP users that ETLDAP exported and created in Cognos
TM1. ETLDAP randomly generates the Cognos TM1 user passwords and adds them to the Cognos TM1
database.
Note : If you use Integrated Login, Cognos TM1 users do not use the Cognos TM1 passwords, and you
do not have to coordinate passwords between Cognos TM1 and Microsoft Windows. If you do not use
Integrated Login, Cognos TM1 users must change their password during their first login session. For
details, see “Integrated login” on page 247.

Running ETLDAP in Update mode to add new LDAP users

You can run ETLDAP in Update mode to update IBM Cognos TM1 with new LDAP users that do not already
exist in Cognos TM1. To do this, you specify a date in the Filter section of your LDAP query.

About this task

When you run ETLDAP the first time, you must retrieve all records from the LDAP server that meet your
organizational requirements. You define these requirements using the Filter parameter. After you retrieve
all user and group records, you load them into the IBM Cognos TM1 database.
After using ETLDAP to initially load LDAP users into Cognos TM1, you can then only use the tool to retrieve
and add new LDAP users that do not already exist in Cognos TM1. You cannot use the ETLDAP utility to
update or delete existing users in Cognos TM1 based on changes in the LDAP directory.
As new users are added to your LDAP server, you can add them to Cognos TM1 by specifying a date in the
Filter section of your LDAP query. Using a date in the Filter section runs ETLDAP in Update mode. You can
edit your LDAP Filter to select only new user records that meet your original search requirements since
the last time you ran ETLDAP.
Note : Running ETLDAP in Update mode only adds new LDAP users that do not already exist in Cognos
TM1. ETLDAP does not update user attributes or delete existing Cognos TM1 users.

Procedure
1. Determine the last modified record attribute to specify a date in the Filter section of your LDAP query.
All LDAP servers support a last modified record attribute, which includes these timestamp attributes:
• Standard LDAP - modifytimestamp
• Microsoft Active Directory - whenChanged
During an export session, ETLDAP examines all records as it processes them and stores the date of the
most recently changed record in the Session Log file, as shown in the following sample:

newest record modified: Thu Jan 23 07:00:42 EST 2003(20030123070042.0Z)

Chapter 15. Planning Analytics Local security 281

 2. Locate the newest record line in the LDAP Session Log.
3. Copy the timestamp portion of the string in parentheses from the LDAP Session Log into the Filter
section of your LDAP query.
Note : Be sure to adhere to the syntax supported by LDAP Filters. For more information, see the
Internet standards protocol document, RFC 2254, "The String Representation of LDAP Search Filters".
The following table shows a sample Filter string without any changes, and after modification for both
LDAP and Active Directory servers.
• A standard LDAP server uses the modifytimestamp attribute.
• An LDAP server with Microsoft Active Directory uses the whenChanged attribute.

Sample Filter String Filter String After Modification

Initial string (&(objectclass=person)(|(department=R&D)

(department=Documentation)))

Modified for standard LDAP (&(objectclass=person)(modifytimestamp>

=20030515162433Z)(|(department=R&D*)

(department=QA)))

Modified for Active Directory (&(objectclass=person)(whenChanged>

=20030515162433.0Z)(|(department=R&D*)

(department=QA)))

4. After you make the necessary changes to the Filter line, save the session data with a name that clearly
identifies it as an incremental update query.
5. Run ETLDAP using the new session data.

Data transmission security

You can configure IBM Planning Analytics Local to use secure data transmission between clients and
servers with the Transport Layer Security (TLS) protocol.
Planning Analytics provides a default configuration that services use to create a 2048-bit RSA key pair
and issue a certificate to the configured subject, which is signed using SHA-256 by a built-in certificate
authority (CA).
The server key and certificates are stored in a PKCS12 keystore named CAMKeystore in the configured
keystore location (<PA_install_directory>/configuration/certs/ ) of the Planning Analytics
data tier installation.

Overview
All IBM Planning Analytics Local components can communicate with the Cognos TM1 Admin Server by
using Transport Layer Security (TLS).
Note : Though a standard Planning Analytics Local installation is configured to use TLS by relying on the
certificates that are installed in the <PA_install_directory>\bin64\ssl directory, you should use
your own certificates to maximize security.

282 IBM Planning Analytics: Installation and Configuration

 The following diagram illustrates how IBM TM1 Server interacts with the components of the Data Tier,
Web Tier, Rich Tier, and other Planning Analytics clients.
To learn more, follow this legend.
1. The IBM TM1 Server is configured to use Transport Layer Security (TLS) by default. When the TM1
Server registers with the Admin Server, the TM1 Server specifies whether it is using TLS or not. To
replace the provided TLS certificates, see “Configure the TM1 Server to use custom TLS” on page
284.
2. The TM1 Admin Server is configured to use TLS by default. To replace the provided TLS certificates,
see “Configure the Cognos TM1 Admin Server to use custom TLS” on page 287.
3. “Configure the Web Tier to use custom TLS” on page 291. For TM1RunTI configuration to TM1 Server,
see Using TM1RunTI in TM1 TurboIntegrator.
4. If you are using custom TLS certificates, see “Configure Cognos TM1 Architect or Perspectives to use
custom certificates” on page 301.
5. If you are using custom TLS certificates, see “Configure Cognos TM1 Performance Modeler to use
custom certificates” on page 302.
6. If you are using custom TLS certificates, see “Configure Cognos Insight to use custom certificates” on
page 303.
7. If you are using custom TLS certificates, see “Configure the TM1 C API to use custom certificates” on
page 304.
8. This configuration depends on the REST API client. Assuming the REST API client is using a web
browser, there is no configuration required unless the default TLS certificates from the TM1 Server
are used. For more information, see Authentication and session security.
9. “Configure the TM1 Server and a Cognos Analytics dispatcher with SSL enabled” on page 289.
10. “Configure TLS for Planning Analytics Workspace Local” on page 166.
11. If you are using custom TLS certificates, see “Configure TLS between Planning Analytics Workspace
Local and other servers” on page 167.
12. For information about IBM Planning Analytics for Microsoft Excel connections, see “Set up
connections for TM1 REST APIs” on page 203.

Default configuration
When you install IBM Planning Analytics Local, all certificates and other files required to configure TLS are
placed in the <PA_install_directory>\bin64\ssl directory.
When you install Planning Analytics Local, the Admin Server, TM1 Server, and TM1 clients are all
configured to use TLS, relying on the certificates installed in the <PA_install_directory>
\bin64\ssl directory. Although these certificates allow you to configure a TLS implementation, you
should replace these certificates with your own certificates (as well as a certificate revocation list) if you
want to maximize security.
For TM1 Web, all root certificates must be installed in the certificate store on the machine that the servers
are using to run TM1 Web.
The <PA_install_directory>\bin64\ssl directory contains the following certificates and files. Files
with a .pem extension are Privacy Enhanced Mail format. Files with a .der extension are Distinguished
Encoding Rules.
[Link]
The original default certificate in DER format used for Java certificate stores.
[Link]
The original root authority certificate.
[Link]
The default certificate file.

Chapter 15. Planning Analytics Local security 283

 [Link]
The certificate revocation list.
[Link]
The key database file, which contains the server certificate and trusted certificate authorities.
[Link]
The requested key pair and the certificate request data.
[Link]
The key store, which contains passwords to the key database file.
tm1ca_v2.der
The updated default certificate.
tm1ca_v2.pem
The updated default root authority certificate.
tm1store
The Java certificate store containing the public root authority certificate.

Configure the Data Tier to use custom TLS

These steps provide an overview of the process to configure encrypted communication using Transport
Layer Security (TLS) for TM1 Admin Server and TM1 Server in IBM Planning Analytics Local.

Configure the TM1 Server to use custom TLS

To configure an IBM TM1 Server to use Transport Layer Security (TLS), you must set several parameters in
the [Link] file and configure the Data tier to use custom certificates.

Generate the custom SSL keystore and certificate

IBM Planning Analytics includes the gsk8capicmd_64.exe program in the <PA_install_directory>
\bin64\ directory. This tool can be used to create and populate a keystore database that is used by the
TM1 Admin Server and TM1 Server.
1. Create a keystore database file by using the following command.

gsk8capicmd_64 -keydb -create -populate

-db PA_install_directory\bin64\ssl\[Link]
-type cms -pw changeit -stash

2. Request a certificate from the keystore database that was created in step “1” on page 284.

gsk8capicmd_64 -certreq -create -db PA_install_directory\bin64\ssl\[Link]

-stashed -label tm1server -dn "CN=[Link],O=IBM"
-file PA_install_directory\bin64\ssl\cert_request.arm –size 2048

Note : The cn value must match the fully qualified domain name of the system that is running the
Planning Analytics Data tier.
3. Provide the certificate request (cert_request.arm file) to the Certificate Authority for signing.
The certificate authority provides both an issued certificate ([Link] in this example) and a
CA certificate ([Link] in this example). Multiple CA certificates are usually stored in a single file. It is
common for a certificate authority to provide both the issued certificate and CA certificates in a single
file.
4. Add the CA certificates into the keystore.

gsk8capicmd_64 -cert -add -db PA_install_directory\bin64\ssl\[Link]

-stashed -label tm1serverca -file PA_install_directory\bin64\ssl\[Link]
-format ascii -trust enable

5. Receive the issued certificate into the keystore.

284 IBM Planning Analytics: Installation and Configuration

 gsk8capicmd_64 -cert -receive -db PA_install_directory\bin64\ssl\[Link]
-stashed -file .\ssl\[Link] -default_cert yes

Complete the following steps for UNIX and Linux environments.

1. Add the <PA_install_directory>\bin64\ directory to the library path environment variable
(LD_LIBRARY_PATH) before you run gsk8capicmd_64.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ibm/cognos/bin64

Note : The gsk8capicmd_64 program fails with a missing library error if the library path variable is
not set correctly.
2. The gsk8capicmd_64 file in the <PA_install_directory>\bin64\ is missing the execute
permission by default. Add the missing execute permissions by running the following command from
the bin64 directory.

chmod +x gsk8capicmd_64

Configure the TM1 Admin Server to use the custom TLS certificate
1. Point the following TM1 Admin Server settings to the [Link] and [Link] files in Cognos
Configuration.

2. Restart the TM1 Admin Server service.

The Server certificate parameter in the settings might be incorrectly referenced in the
<PA_install_directory>\configuration\[Link] file. To correct this problem,
manually edit the [Link] file to change this line:

<crn:parameter name="tm1AdminKeyLabel">
<crn:value xsi:type="xsd:filePath">tm1server</crn:value>
</crn:parameter>

To the following line:

<crn:parameter name="tm1AdminKeyLabel">
<crn:value xsi:type="xsd:string">tm1server</crn:value>
</crn:parameter>

Note : Saving your changes in Cognos Configuration resets the above line to the incorrect value. You must
ensure that the certificate being used is the default certificate in the key database and leave the Server
certificate parameter empty in Cognos Configuration.

Configure the TM1 Server to use the custom TLS certificate

1. Edit the [Link] file to include the following lines.

keyfile=PA_install_directory\bin64\ssl\[Link]
keystashfile=PA_install_directory\bin64\ssl\[Link]

Chapter 15. Planning Analytics Local security 285

 2. Restart the TM1 Server service.

Configure TM1 Architect and TM1 Perspectives to use the custom TLS certificate
1. Create a file named [Link] in the <TM1 Client>\bin\ or <TM1 Client>\bin64\
directory of the TM1 client installation depending on your client installation.
2. Update the contents of the [Link] file with the following lines:

[tm1api]
keystorefile=PA_install_directory\bin64\ssl\[Link]
keystashfile=PA_install_directory\bin64\ssl\[Link]

You don't need to make any changes in the options for Cognos TM1 Architect or TM1 Perspectives.

Configure TM1Web to use the Custom TLS certificate

1. The CA certificates must be imported into the <PA_install_directory>\bin64\ssl\ttm1store
certificate store file in the TM1Web installation.
To import the CA certificates, use the Java keytool command found in the
<PA_install_directory>\jre\bin\ directory as follows.

[Link] -import -trustcacerts file "PA_install_directory\bin64\ssl\[Link]"

-keystore "PA_install_directory\bin64\ssl\tm1store" -alias tm1cacert
-storepass applix

Note : This command assumes that all CA certificates are in a file named [Link] that is already
copied into the <PA_install_directory>\bin64\ssl\ directory.
2. Restart the IBM Cognos TM1 service from the Windows services list or Cognos Configuration.

Configure TM1 Applications (pmpsvc) to use the custom TLS certificate

1. Make sure the [Link] and [Link] file are copied into the <PA_install_directory>
\bin64\ssl\ directory of the TM1 Server install that includes the pmpsvc web application.
2. Create a file named [Link] in the <PA_install_directory>\bin64\ directory of the
TM1 Server install containing the pmpsvc web applications.
3. Update the contents of the [Link] file:

[tm1api]
keystorefile=PA_install_directory\bin64\ssl\[Link]
keystashfile=PA_install_directory\bin64\ssl\[Link]

4. Update the <PA_install_directory>\wlp\usr\servers\tm1\[Link] file to include the

following line:

-[Link]=PA_install_directory\bin64

5. Restart the IBM Cognos TM1 service (WebSphere Liberty Profile).

Configuration parameters
The following table describes parameters that are related to secure connections, which can be set in the
[Link] configuration file. All [Link] parameters are described in “Parameters in the [Link] file”
on page 336.

286 IBM Planning Analytics: Installation and Configuration

Parameter Description

UseSSL Enables or disables secure connections on the TM1

Server.
This parameter is enabled by default.
Set UseSSL=F to disable secure connections. With
this setting, clients can connect to the server in
insecure mode.

SSLCertAuthority The name of the TM1 Server's certificate authority

file. This file must be on the computer where the
TM1 Server is installed.

SSLCertificate The full path of the certificate file that contains the
public/private key pair.

SSLCertificateID The name of the principal to whom the TM1

Server's certificate is issued.

SvrSSLExportKeyID The identity key that is used to export the TM1

Server's certificate from the Microsoft Windows
certificate store.
This parameter is required only if you choose to
use the certificate store by setting
ExportSvrSSLCert=T.

ClientExportSSLSvrCert Specifies whether the TM1 client must retrieve the

certificate authority certificate, which was
originally used to issue the TM1 Server's
certificate, from the Microsoft Windows certificate
store.
If ClientExportSSLSvrCert=T, the certificate
authority certificate is exported from the certificate
store on the client computer when requested by
the TM1 client.

ClientExportSSLSvrKeyID The identity key that is used by the TM1 client to

export the certificate authority certificate, which
was originally used to issue the TM1 Server's
certificate, from the Windows certificate store.

Configure the Cognos TM1 Admin Server to use custom TLS

To configure the IBM TM1 Admin Server to use Transport Layer Security (TLS), use IBM Cognos
Configuration.
The following table describes properties that are related to secure connections, which can be set in IBM
Cognos Configuration.

Chapter 15. Planning Analytics Local security 287

 Property Description

Support non-SSL clients? This property determines if the Admin Server supports non-SSL TM1
clients.
Set this property to True to configure the Admin Server to support
non-SSL clients and to listen for client connections on both secured
and unsecured ports.
Set this property to False to configure the Admin Server to support
only secure client connections on a single secured port.

Support pre-TLS v1.2 clients? As of TM1 10.2.2 Fix Pack 6 ([Link]), all secured communication
between clients and servers in TM1 uses Transport Layer Security
(TLS) 1.2. This property determines whether TM1 clients and TM1
servers prior to 10.2.2 Fix Pack 6 can connect to the [Link] or later
Admin Server.
Set this property to True to allow TM1 clients and TM1 servers prior
to [Link] to connect to the Admin Server. When such a connection
is established, TLS 1.0 is used instead of TLS 1.2.
Set this property to False to prevent TM1 clients and TM1 servers
prior to [Link] from connecting to the Admin Server.

TM1 Admin Server certificate The full path and name of the Cognos TM1 Admin Server's certificate
authority file location authority file.

Certificate file location The full path of the Cognos TM1 Admin Server's certificate file, which
contains the public/private key pair.

TM1 Admin Server private key The full path of the file that contains the encrypted password for the
password file location Cognos TM1 Admin Server's private key.

TM1 Admin Server password key The full path of the file that contains the key used to encrypt and
file location decrypt the password for the private key.

Certificate revocation file The full path of the Cognos TM1 Admin Server's certificate revocation
location file.
A certificate revocation file will only exist in the event that a
certificate has been revoked.

288 IBM Planning Analytics: Installation and Configuration

Property Description

TM1 Admin Server Certificate Specifies which version of the TM1 generated certificates to use.
Version
By default, the 1024-bit encryption version of the TM1 generated
certificates is used.
Change this property only if you want to use the new 2048-bit
encryption version of the default certificates. You can use the new
version with old and new TM1 clients, but you must configure the
clients to use the new certificate authority file.
Note : This property does not apply if you are using your own
certificates.
Valid values include:
• 1 - Enables certificate authority for 1024-bit encryption with sha-1
(default value)
• 2 - Enables certificate authority for 2048-bit encryption with
sha-256

Configure the TM1 Server and a Cognos Analytics dispatcher with SSL
enabled
You can configure TM1 Server for CAM Authentication when using a Cognos Analytics dispatcher with SSL
enabled.

Procedure
1. Add the following parameter to the [Link] file.
CAMUseSSL=T
2. Find the root and any intermediate CA (signing) certificates for the Cognos Analytics dispatcher.
By default this key database file is <PA_install_directory>\bin64\ssl\[Link].
a) Browse to the Cognos Analytics dispatcher URL.
For example, [Link]
b) Using Internet Explorer, click the lock icon to the right of the URL.
c) Click View certificates.
3. Export the certificates to a Base-64 encoded cer file.
4. Import the certificates into the key database used by the TM1 Server by running the following
command from the <PA_install_directory>\bin64\ directory.

gsk8capicmd_64 -cert -add -db .\ssl\[Link] -stashed -label cognosbi

-file .\ssl\[Link] -format ascii -trust enable

This command assumes that the certificates are in a file named [Link] that has already
been copied into the <PA_install_directory>\bin64\ssl\ directory.
5. Restart the TM1 Server.

Edit parameters in the [Link] file to use independent certificates

After adding your certificate to the Microsoft Windows Certificate Store, add the required parameters to
the [Link] file.

Chapter 15. Planning Analytics Local security 289

 Table 27. Parameters for the [Link] file
Parameter Value

AdminSvrSSLCertID Specifies the name of the principal to whom the IBM Cognos TM1
Admin Server's certificate is issued.

AdminSvrSSLExportKeyID Specifies the identity key used to export the Admin Server's
certificate from the Microsoft Windows Certificate Store.

ClientExportSSLSvrCert Specifies whether the TM1 client should retrieve the certificate
authority certificate, which was originally used to issue the TM1
Server's certificate, from the Microsoft Windows Certificate Store.
If ClientExportSSLSvrCert=T, the certificate authority
certificate is exported from the certificate store when requested by
the TM1 client.

ClientExportSSLSvrKeyID The identity key used by the TM1 client to export the certificate
authority certificate, which was originally used to issue the TM1
Server's certificate, from the Microsoft Windows Certificate Store.

ExportAdminSvrSSLCert Specifies whether the Cognos TM1 Admin Server's certificate should
be exported from the Microsoft Windows Certificate Store.
If ExportAdminSvrSSLCert=T, the Admin Server's certificate is
exported from the Microsoft Windows Certificate Store when the
certificate is requested by the TM1 Server.

ExportSvrSSLCert This parameter must be set to T to enable the TM1 Server to retrieve
the certificate from the Microsoft Windows Certificate Store.
ExportSvrSSLCert=T

SSLCertAuthority The name of the authority that issued your certificate.

You can determine this value by referring to the Microsoft
Management Console and clicking Certificates > Personal >
Certificates. The authority name is displayed in the Issued By
column of the Properties pane.

SSLCertificateID The name of the principal to whom the TM1 Server's certificate is
issued.
You can determine this value by referring to the Microsoft
Management Console and clicking Certificates > Personal >
Certificates. The principal name is displayed in the Issued To
column of the Properties pane.

290 IBM Planning Analytics: Installation and Configuration

 Table 27. Parameters for the [Link] file (continued)
Parameter Value

SSLPrivateKeyPwdFile The full path to the .dat file that contains the encrypted password for
the private key.
Note : The name of this file is specified by the -outfile parameter
when you run the TM1Crypt utility.
For example, if you run the TM1Crypt utility from the following
command:
[Link] -pwd abc123 -keyfile [Link] -
outfile [Link] -validate
the correct parameter value is
SSLPrivateKeyPwdFile=C:\Program Files\Cognos
\TM1\bin\[Link]

SSLPwdKeyFile The full path to the .dat file that contains the key used to encrypt and
decrypt the password for the private key.
Note : The name of this file is specified by the -keyfile parameter
when you run the TM1Crypt utility.
For example, if you run the TM1Crypt utility from the following
command:
[Link] -pwd abc123 -keyfile [Link] -
outfile [Link] -validate
the correct parameter value is SSLPwdKeyFile=C:\Program
Files\Cognos\TM1\bin\[Link]

SvrSSLExportKeyID Specifies the identity key used to export the TM1 Server's certificate
from the Microsoft Windows certificate store.
In most cases, the value for SvrSSLExportKeyID will be identical to
the value for SSLCertificateID.

Configure the Web Tier to use custom TLS

These steps provide an overview of the process to configure encrypted communication using Transport
Layer Security (TLS) for TM1 Web, TM1 Applications, and TM1 Application Gateway in IBM Planning
Analytics Local.
All secured communication between clients and servers in Planning Analytics Local uses Transport Layer
Security (TLS) 1.2.
When Planning Analytics is configured to use TLS, you access TM1Web, TM1 Applications, and TM1
Application Gateway by using HTTPS instead of HTTP. Planning Analytics provides a default configuration
that gets stored in the CAMKeystore file in the /configuration/certs/ directory of the Planning
Analytics installation.
You can configure encrypted communication with the default configuration for development and testing.
However, you should configure custom certificates for production systems.
Custom certificates need to be signed by a third-party certificate authority (CA). You can use the IBM Key
Management tool to create a certificate and import the certificate back into Planning Analytics after it is
signed by a third-party CA. You can also import an existing keystore that contains a server key and
matching certificates that are already signed by a CA that is external to Planning Analytics.

Chapter 15. Planning Analytics Local security 291

 Important : Before you follow these steps, stop the IBM Cognos TM1 service and back up the
CAMKeystore and [Link] files, or back up the configuration directory of your Planning
Analytics installation.

Use the default configuration

You can use the standard, default certificates that are included as part of your Planning Analytics Local
installation.

About this task

You must change the default settings for Planning Analytics and import the certificate to establish trust for
TM1 Web.
Because you are changing Planning Analytics Data Tier configuration for supporting encrypted
communication, the keystore that TM1 Web uses to establish trust with the Planning Analytics Web Tier
and Planning Analytics Data Tier has changed.
The keystore that is configured in Cognos Configuration is used to look up CA certificates whenever trust
needs to be established. Therefore, you must add the CA certificate that signed the server certificates of
the TM1 Servers in the Planning Analytics Data Tier to the configured keystore.

Procedure
1. In IBM Cognos Configuration, navigate to Local Configuration > Security > Cryptography > Cognos
and enter the following parameters:
• Server common name - Enter the fully qualified hostname of the server that hosts the Planning
Analytics Data Tier that is used in URLs by clients.
• Organization name - Enter your company or organization name.
• Country or region code - Enter the two-letter country region code.
• Optional: Certificate location - Enter the folder to store the CAMKeystore file.
• Optional: Keystore password - Enter a password for the keystore.
• Optional: Supported cipher suites - Configure the cipher suites supported by the Planning Analytics
Data Tier that are offered to clients connecting to the Data Tier.
Note : This setting does not affect ciphers that are used by the Planning Analytics Data Tier.
2. In IBM Cognos Configuration, navigate to Local Configuration > Environment > TM1 Applications and
change the URLs for the following parameters to use the HTTPS prefix:
• TM1 Application Server Gateway URI - For example, https://
system_name.[Link]/pmpsvc
• External server URI - For example, [Link]
• TM1 Application Server Dispatcher URI - For example, https://
system_name.[Link]/pmpsvc/dispatcher/servlet
• Business Viewpoint URI - For example, [Link]
Note : Enter the fully qualified system_name.[Link] and port numbers for your specific
configuration.
3. Open a command prompt and change to the bin folder of your Planning Analytics Local installation,

cd C:\\Program Files\ibm\cognos\tm1_64\bin

4. Run the following command to import the certificate into the keystore.

keytool -import -trustcacerts -file "<path to the certificate>\<CA_file>"

-keystore ..\lib\security\cacerts -storepass changeit -alias TM1ServerCert

292 IBM Planning Analytics: Installation and Configuration

 Where <CA_file> is the PEM encoded file that contains the CA (chain) used to sign the TM1 Server's
certificate.
By default, all TM1 Servers use the self-signed certificate that is stored in
<PA_install_directory>\bin64\ssl\[Link]. Enter this file name for <CA_file> unless the
TM1 Servers in Planning Analytics Data Tier are configured to use custom certificates.
And <Keystore_Password> is the password that specified in Local Configuration > Security >
Cryptography > Cognos Key store password in Cognos Configuration. The default keystore password
is NoPassWordSet.
5. Enter yes when prompted to trust or add the certificate. You can ignore messages about logging.
The following message displays: Certificate was added to keystore.
6. Add the TM1 Server CA certificate to the CAMKeystore keystore file.
Note : If this step is missed, TM1Web cannot connect to TM1 Server. This step must be completed
even if the TM1 Server is not using custom certificates.
a) Use IBM Key Management to open the CAMKeystore file, and switch to the Signer Certificates
section.
b) Click Add and select the ./tm1_64/bin64/ssl/[Link] file (the certificate that is provided
by IBM).
There is no requirement for a specific label for certificates that are added to the Signer Certificates
section of IBM Key Management.
7. Restart the IBM Cognos TM1 service from IBM Cognos Configuration.
Remember : Re-add certificates anytime you reinstall Cognos TM1.

What to do next
Log in to TM1 Web with the secure HTTPS URL to confirm that you can connect to TM1 with this
configuration.
For example, log in using [Link]
The browser might show a certificate warning because the CA certificate that signed the WebSphere
Liberty Profile server certificate is from the built-in CA service and is not trusted by the browser. You can
either import that certificate into the browser (refer to your browser documentation) or safely ignore the
warning and continue.
If the warning is because of a different reason, check that the hostname of the URL exactly matches the
hostname that is specified for Server Common Name in Cognos Configuration and verify you're using a
supported browser.

Use IBM Key Management to configure custom certificates

You can generate a certificate request and import a certificate with the IBM Key Management tool.

About this task

If a signed certificate is already available for the system that is running the Planning Analytics web tier,
start at step “3” on page 295. This signed certificate must be in the form of a pkcs12 or jks file. This file
is password-protected.

Procedure
1. Use the IBM Key Management tool ([Link]) to access the CAMKeystore file and generate a
certificate request.
The [Link] program is found in the <PA_install_directory>\jre\bin directory of the
Planning Analytics installation or in the IBM JRE installation if Linux used. The CAMKeystore file is
found in the \configuration\certs\ directory. The default certificate created by the built-in
services is issued to CN=CAMUSER and issued by CN=CA

Chapter 15. Planning Analytics Local security 293

 a) Click to open a key database file and select the file.
The key database file type must be PKCS12. The default password for the CAMKeystore file is
NoPassWordSet.
b) In the Personal Certificates section, select the certificate with the label encryption and click
Delete.

You must replace this certificate with your own certificate that will be issued to the name of the
server running TM1Web.

c) In the Personal Certificates section and click Create > New Certificate Request or click in the
IBM Key Management toolbar. Fill in the details as follows:

294 IBM Planning Analytics: Installation and Configuration

 The Key Label must be encryption, Key Size 2048, and Signature Algorithm SHA256WithRSA.
Setting a Subject Alternative Name: DNS Name is also strongly recommended because web
browsers might require a proper Subject Alternative Name (SAN) to validate the certificate.
d) Enter the location and name of the certificate request file and click OK.
2. Get the certificate request signed by a Certificate Authority (CA).
The certificate request file must be provided to the CA. The CA will provide one or more files that
contain a signed certificate and the CA certificates in the chain.
3. Import a server key and certificates from an external keystore or replace the encryption certificate
with one that was created with IBM Key Management.
a) Use IBM Key Management to open the CAMKeystore file. See step “1” on page 293.
b) In the Personal Certificates section, select the encryption certificate and click Delete if it has not
been removed yet.
c) In the Personal Certificates section, click Receive to import the new certificate and select the
certificate file that contains the certificate to be used.
This file should typically contain the signed certificate and the certificate authority chain certificate
(root and intermediate certificates). During the import, IBM Key Management prompts for a label
for the signed certificate. This label must be encryption. All certificates will be imported into
CAMKeystore during the import action. If the file being imported does not contain the full
certificate chain, the CA certificates must be added separately to the Signer Certificates section.
d) In the Signer Certificates section, click Add and select the file or files containing the CA
certificates.

Chapter 15. Planning Analytics Local security 295

 If a single file contains multiple CA certificates (for example, a root and multiple intermediate
certificates) then multiple certificates can be selected for import. IBM Key Management prompts
for a label for these certificate. A specific label is not required for the CA certificates.
e) After the CA certificates have been added to the Signer Certificates section, switch back to the
Personal Certificates section and click Receive to receive the signed encryption certificate.
When the signed encryption certificate has been received into the keystore, double-click the
encryption certificate to see the details and verify that the certificate is issued to the system running
TM1Web, and issued by one of the CA certs in the chain.
4. Enable TLS in IBM Cognos Configuration.
a) Add the StandaloneCertificateAuthority property under the Local Configuration > Advanced
Properties section and set it to True.

b) Update the TM1 Applications settings in Cognos Configuration to specify HTTPS.

c) Set Use third party CA? to True in the Security > Cryptography > Cognos section of Cognos
Configuration.

296 IBM Planning Analytics: Installation and Configuration

5. Add the TM1 Server CA certificate to the CAMKeystore keystore file.
Note : If this step is missed, TM1Web cannot connect to TM1 Server. This step must be completed
even if the TM1 Server is not using custom certificates.
a) Use IBM Key Management to open the CAMKeystore file, and switch to the Signer Certificates
section.
b) Click Add and select the ./tm1_64/bin64/ssl/[Link] file (assuming the TM1 Server uses
the certificate provided by IBM, otherwise select your own file containing your CA certificate).
There is no requirement for a specific label for certificates added to the Signer Certificates section
of IBM Key Management.
6. Restart the IBM Cognos TM1 service from either Cognos Configuration or the list of Windows services.

What to do next
Log in to Cognos TM1 Web using the secure HTTPS URL to confirm that you can connect to Cognos TM1
with this configuration. For example, log in using [Link] Verify that you
are not presented with any certificate warnings.

Use ThirdPartyCertificateTool to create custom certificates

Not supported in v2.0.6 You can use the ThirdPartyCertificateTool to configure custom
certificates.

About this task

Note : The ThirdPartyCertificateTool requires Java 7 and is not supported in Planning Analytics version
2.0.6 or later.
The following steps configure custom certificates for TM1 Applications that run in WebSphere Liberty
Profile for IBM Planning Analytics Local. These steps use a command-line tool named
ThirdPartyCertificateTool. This tool is located in <PA_install_directory>\bin\. For more
information about this tool, see “ThirdPartyCertificateTool command-line reference” on page 305.

Procedure
1. From the <PA_install_directory>\bin\ directory, run the following
ThirdPartyCertificateTool command to generate a new key pair and associated certificate
signing request (CSR) for the encryption entry in the CAMKeyStore store.

[Link] -java:local -c -e -d "cn=[Link]" -p

NoPassWordSet

Note : The cn value must match the fully qualified domain name of the system that is running the
Planning Analytics Data tier.

Chapter 15. Planning Analytics Local security 297

 2. Back up the <PA_install_directory>\configuration\certs\ directory and the
<PA_install_directory>\configuration\[Link] file.
3. Get the certificate request signed by a certificate authority.
The CA provides a signed certificate and any CA certificates. The certificate authority usually provides
both the issued certificate and CA certificates in a single file.
• The issued certificate must be copied into its own file ([Link]) and all CA certificates should
be placed in a single file ([Link]).
• If the provided certificates are in base64 format, you can use a text editor to split the certificates into
the files that are required by the ThirdPartyCertificateTool command.
• If the files provided by the CA are not in base64 format, the Windows certificate utility can be used to
convert to base64 format.
4. From the <PA_install_directory>\bin\ directory, run the following commands to import the
encryption and CA certificates:

[Link] -java:local -i -e
-r "<PA_install_directory>\bin64\ssl\[Link]"
-p NoPassWordSet -t "<PA_install_directory>\bin64\ssl\[Link]"

5. Set up Cognos Configuration to use the custom certificate.

a) Add the StandaloneCertificateAuthority property under the Local Configuration >
Advanced Properties section and set it to True.

b) Update the TM1 Applications settings in Cognos Configuration to specify HTTPS.

c) Set Use third party CA? to True in the Security > Cryptography > Cognos section of Cognos
Configuration.

298 IBM Planning Analytics: Installation and Configuration

6. Restart the IBM Cognos TM1 service from either Cognos Configuration or the list of Windows services.
7. Run the following command to import the certificate into the keystore.
Important : After you configure TLS for TM1Web, you must import the certificate for the TM1 Server
and TM1 Admin Server into the CAMKeystore. You must do this step in the Planning Analytics
installation directory on the system that runs TM1Web. If this step is missed, you can access TM1Web
using HTTPS, but TM1Web cannot connect to any TM1 Servers.
Windows:

[Link] -java:local -i -T -r <CA_file>

-p <Keystore_Password>

Linux:

./[Link] -java:local -i -T -r <CA_file>

-p <Keystore_Password>

Where <CA_file> is the PEM encoded file containing the CA (chain) used to sign the TM1 Server's
certificate.
And <Keystore_Password> is the password that specified in Local Configuration > Security >
Cryptography > Cognos Key store password in Cognos Configuration. The default key store password
is NoPassWordSet.
Windows:

[Link] -java:local -i -T -r ..\bin64\ssl\[Link]

-p NoPassWordSet

Linux:

./[Link] -java:local -i -T -r ../bin64/ssl/[Link]

-p NoPassWordSet

What to do next
Log in to Cognos TM1 Web using the secure HTTPS URL to confirm that you can connect to Cognos TM1
with this configuration. For example, log in using [Link] Verify that you
are not presented with any certificate warnings.

Edit parameters in Cognos Configuration to use independent certificates

After adding your certificate to the Microsoft Windows Certificate Store, use IBM Cognos Configuration to
update the parameters for the Cognos TM1 Admin Server.

Chapter 15. Planning Analytics Local security 299

 Table 28. TLS Parameters in Cognos Configuration that support independent certificates
Parameter Description
Export TM1 Admin Server This parameter must be set to True to enable the Admin Server to retrieve
certificate? the certificate from the Certificate Store.

TM1 Admin Server The full path and name of the certificate authority file that issued the TM1
certificate authority file Admin Server's certificate.
location
You can determine this value by referring to the Microsoft Management
Console and clicking Certificates > Personal > Certificates. The authority
name displays in the Issued By column of the Properties pane.

TM1 Admin Server The name of the principal to whom the IBM Cognos TM1 Admin Server's
certificate ID certificate is issued.
You can determine this value by referring to the Microsoft Management
Console and clicking Certificates > Personal > Certificates. The principal
name displays in the Issued To column of the Properties pane.

TM1 Admin Server private The full path to the .dat file that contains the encrypted password for the
key password file location private key.
Note : The name of this file is specified by the -outfile parameter when
you run the TM1Crypt utility.
For example, if you run the TM1Crypt utility from the following command:
[Link] -pwd abc123 -keyfile [Link] -outfile
[Link] -validate
the correct parameter value is:
C:\Program Files\Cognos\TM1\bin\[Link]

TM1 Admin Server The full path to the .dat file that contains the key used to encrypt and
password key file location decrypt the password for the private key.
Note : The name of this file is specified by the -keyfile parameter when
you run the TM1Crypt utility.
For example, if you run the TM1Crypt utility from the following command:
[Link] -pwd abc123 -keyfile [Link] -outfile
[Link] -validate
the correct parameter value is:
C:\Program Files\Cognos\TM1\bin\[Link]

TM1 Admin Server export Specifies the identity key used to export the Admin Server's certificate
key ID from the Windows certificate store.
In most cases, the value for TM1 Admin Server export key ID will be
identical to the value for TM1 Admin Server certificate ID.

Configure the Rich Tier to use TLS

To configure IBM Cognos TM1 Performance Modeler, IBM Cognos Insight, and other Rich Tier components
to use custom certificates, you must place the certificates in several locations.
TM1 clients connect to the Admin Server using a secured port. When a TM1 client contacts the Admin
Server, the Admin Server responds with a list of all TM1 Servers available on the network.

300 IBM Planning Analytics: Installation and Configuration

The TM1 client establishes a secure connection with the TM1 Server that is configured to use TLS and
establishes an insecure connection with TM1 Servers that are not configured to use TLS.

Configure Cognos TM1 Architect or Perspectives to use custom certificates

To configure IBM Cognos TM1 Architect or TM1 Perspectives clients to use custom certificates, you must
set several options on the Cognos TM1 Options dialog box.
TM1 Architect and TM1 Perspectives communicate with the Data Tier only.

The [Link] file

1. Open Cognos TM1 Architect or Cognos TM1 Perspectives, Server Explorer.
2. In Server Explorer, click File > Options.
3. Edit the following options in the Admin Server Secure Socket Layer (SSL) section.
The following table describes all options that can be set in the TM1 Options dialog box and lists the
corresponding [Link] parameters.

Option Name Corresponding [Link] Description

Parameter

Certificate Authority AdminSvrSSLCertAuthority The full path of the certificate authority file
that issued the Cognos TM1 Admin Server's
certificate.

Certificate AdminSvrSSLCertRevList The full path of the certificate revocation file

Revocation List issued by the certificate authority that
originally issued the Cognos TM1 Admin
Server's certificate. A certificate revocation
file will only exist in the event a certificate
had been revoked.

Certificate ID AdminSvrSSLCertID Note : The name of the principal to whom the

Cognos TM1 Admin Server's certificate is
issued.
The value of this parameter should be
identical to the SSLCertificateID parameter
for the IBM Cognos TM1 Admin Server as set
in IBM Cognos Configuration.

Use Certificate Store ExportAdminSvrSSLCert Select this option if you want the certificate
authority certificate that originally issued the
Cognos TM1 Admin Server's certificate to be
exported from the Microsoft Windows
certificate store at runtime.
Selecting this option in the Cognos TM1
Options dialog box is equivalent to setting
ExportAdminSvrSSLCert=T in the [Link]
file.
When this option is selected, you must also
set a value for Export Certificate ID in the
Cognos TM1 Options dialog box.

Chapter 15. Planning Analytics Local security 301

 Option Name Corresponding [Link] Description
Parameter

Export Certificate ID AdminSvrSSLExportKeyID The identity key used to export the certificate
authority certificate, which originally issued
the Cognos TM1 Admin Server's certificate,
from the certificate store.
This parameter is required only if you choose
to use the certificate store by setting
ExportAdminSvrSSLCert=T.

The [Link] file

Create a configuration file named [Link] with the following format:

[tm1api]
### Path to GSKit store
#keystorefile=

### Path to GSKit stash file

#keystashfile=

### Comma delimited string of TLS ciphers

#tlsCipherList=

### FIPS_MODE = 1 (default), FIPS_APPROVED = 2, FIPS_NONE = 3

#FIPSOperationMode=1

#NIST_SP800_131A_MODE=T

This configuration file allows TM1 Architect or Perspectives clients to configure the GSKit options. The file
contains a section named tm1api and supports comments using the # character. The file must reside
where the [Link] resides. For example, place [Link]fig under C:\Program Files\IBM
\cognos\tm1_64\webapps\pmpsvc\WEB-INF\bin64 then restart the Application Server.
The following is a sample configuration file.

[tm1api]
keystorefile=C:\TM1Install_Dir\x64\Debug\ssl\[Link]
keystashfile=C:TM1Install_Dir\x64\Debug\ssl\[Link]
tlsCipherList=TLS_RSA_WITH_AES_128_CBC_SHA,
TLS_RSA_WITH_RC4_128_MD5,
TLS_RSA_WITH_AES_128_CBC_SHA256
keylabel=ibmtm1_client
FIPSOperationMode=1
NIST_SP800_131A_MODE=T

Configure Cognos TM1 Performance Modeler to use custom certificates

If the Data Tier is configured to use custom certificates, you can enable custom certificates for IBM
Cognos TM1 Performance Modeler.

About this task

The following setup is assumed:
• TM1 Performance Modeler is installed in <pa_install_directory>/perfmodeler.
• <CMS_Keystore> is the name of the CMS keystore containing all CA certificates, intermediate and root,
which form the chain of trust for any certificate presented by TM1 Admin servers and TM1 Server
instances.
The keystore can be created using the gsk8capicmd tool, or copied from a Data Tier install. Typically
this keystore will consist of at least two files, <CMS_Keystore>.kdb and <CMS_Keystore>.sth. The
file <CMS_Keystore>.crl is optional and depends on how the keystore was created.

302 IBM Planning Analytics: Installation and Configuration

• The machine where TM1 Performance Modeler is installed can connect to the Application Tier URL and
the Data Tier.

Procedure
1. Close TM1 Performance Modeler if it is running.
2. Copy the CMS keytore file <CMS_Keystore>.* to a location on the PM computer.
A best practice is to use a custom name for the keystore and store it outside of
<pa_install_directory>/perfmodeler to prevent unintended overwriting. Create a separate
folder such as c:\pa_certs. <PA_CERTS> denotes the absolute path to this folder in the following
steps.
3. In <PA_CERTS>, create a text file named of [Link] and paste the following contents:

[tm1api]
keystorefile=<PA_CERTS>\<CMS_Keystore>.kdb
keystashfile=<PA_CERTS>\<CMS_Keystore>.sth

For example:

[tm1api]
keystorefile=c:\pa_certs\[Link]
keystashfile=c:\pa_certs\[Link]

Important : Ensure the local users group has read and execute permission on the file referenced in
keystashfile. By default, this file is readable only for the account that created it.
4. Copy the <PA_CERTS>\[Link] file to the following locations, where xxxx denotes a version
number.
• <pa_install_directory>\perfmodeler\bins\bin_xxxx\tm1\bin
• <pa_install_directory>\perfmodeler\bins\bin_xxxx\tm1\bin\tm1api101
• <pa_install_directory>\perfmodeler\bins\bin_xxxx\tm1\bin\tm1api102
• <pa_install_directory>\perfmodeler\plugins
\[Link].win32.x86_64_xxxx\extract_bin\tm1\bin
• <pa_install_directory>\perfmodeler\plugins
\[Link].win32.x86_64_xxxx\extract_bin\tm1\bin
\tm1api101
• <pa_install_directory>\perfmodeler\plugins
\[Link].win32.x86_64_xxxx\extract_bin\tm1\bin
\tm1api102
5. Start Cognos TM1 Performance Modeler.
6. Enter the URL for the IBM Cognos TM1 system and click Log on as.
7. When you are prompted for the security certificate, select Trust this certificate and click OK.
Connect to the TM1 Server.
For example, Planning Sample.

Configure Cognos Insight to use custom certificates

You can enable custom certificates for IBM Cognos Insight.

Procedure
1. Stop the IBM Cognos service.
2. Rename the custom certificate files from new_cert_name.* to ibmtm1.*.
3. Copy the files to the following locations:
• ci_install_directory\bins\bin_10.xxxx\tm1\bin\ssl

Chapter 15. Planning Analytics Local security 303

 • ci_install_directory\bins\bin_10.xxxx\tm1\bin\tm1api101\ssl
• ci_install_directory\bins\bin_10.xxxx\tm1\bin\tm1api102\ssl
• ci_install_directory\plugins
\[Link].win32.x86_64_xxxx\extract_bin\tm1\bin
\ssl
• ci_install_directory\plugins
\[Link].win32.x86_64_xxxx\extract_bin\tm1\bin
\tm1api101\ssl
• ci_install_directory\plugins
\[Link].win32.x86_64_xxxx\extract_bin\tm1\bin
\tm1api102\ssl
4. Restart the IBM Cognos service.
5. Start Cognos Insight and select Connect to IBM Cognos TM1.
6. Enter the URL for the IBM Cognos TM1 system and click Next.
7. When you are prompted for the security certificate, select Trust this certificate and click OK.
Connect to the TM1 Server.
For example, Planning Sample.

Configure the TM1 C API to use custom certificates

Several public routines are available as part of the TM1 C API. You can use these routines to configure a
client to communicate with the Admin Server using TLS.
TM1 C APIs communicate with the Data Tier only.
For more information, see Configuring the TM1 C API to Use SSL in the TM1 API documentation.

Configure the Cognos TM1 Java API to use TLS

The certificates used by a Java client to validate the server must reside in either the Java system cacerts
truststore file or be specified on the application command line.
The Java system cacerts truststore resides in the Java \lib\security directory.
The default password for cacerts is "changeit". Java provides an executable named [Link] to change
it. For example:

keytool -keystore ..\lib\security\cacerts -alias Company -import

-file [Link]

Optionally, if access is restricted to the system cacerts truststore, a truststore can be created. For
example:

keytool -keystore tm1store -alias Companyca -import -file [Link]

When starting the Java application this keystore must be specified. If a password is required it must be
provided as well. For example:

java -[Link]=bin\ssl\tm1store
-[Link]=<password>

Further information is provided in the API specification for the Java 2 Platform Standard Edition. The
minimum Java version supported is 1.4.2.

Configure the Cognos TM1 ETLDAP Utility to use TLS

Before you can connect to the LDAP server using TLS, you must run the following command to add your
certificate to the IBM Cognos TM1 keystore in the <PA_install_directory>bin64\jre\8.0\bin
directory:

304 IBM Planning Analytics: Installation and Configuration

 Example:

keytool -keystore "C:\Program Files\IBM\cognos\tm1_64\bin64\ssl\tm1store"

-alias Applixldapca -import -file c:\temp\certificate_name.cer

In this command, substitute the name of your certificate file for certificate_name.cer.
When prompted for the keystore password, enter 'applix'.
You will receive confirmation that the certificate was added to the Cognos TM1 keystore.
When connecting to the LDAP server, you must select the SSL option. If you do not select the SSL option,
the LDAP server will not be able to authenticate your user information.
When running the ETLDAP utility from a command line, you must use the following two parameters to
enable TLS.

Parameter Description

-[Link] Use this parameter to specify the full path to the

Java certificate store containing the public root
authority certificate.
For example, to use the Java certificate store
installed with TM1, use the parameter -
[Link]= C:\Program
Files\IBM\cognos\tm1_64\bin\ssl
\tm1store

-[Link] Use this parameter to specify the password used to

create the Java certificate store.
For example, to specify the password used to
create the Java certificate store installed withTM1,
use the parameter -
[Link]=appl
ix

ThirdPartyCertificateTool command-line reference

Not supported in v2.0.6 Some of the tasks to use a certificate from another certificate authority use a
command-line tool named ThirdPartyCertificateTool.
Note : The ThirdPartyCertificateTool requires Java 7 and is not supported in Planning Analytics version
2.0.6 or later.
This tool is located in the following <PA_install_directory>\bin location.
On UNIX or Linux operating systems, use the following format:
[Link] parameters
On Microsoft Windows operating systems, use the following format:
[Link] parameters
The following tables list the options for this command-line tool.

Table 29. Main operation modes

Command Description
-c Create a certificate signing request.
-i Import a certificate.

Chapter 15. Planning Analytics Local security 305

 Table 29. Main operation modes (continued)
Command Description
-E Export a certificate.

Table 30. Operation modifiers

Command Description
-s Work with the signing identity.
-e Work with the encryption identity.
-T Work with the trust store (only with -i and -E operation modes).

Table 31. Information flags

Command Description
-d DN to use for certificate.
-r CSR or certificate file location (depends on mode).
-t Certificate authority chain file (PEM or binary PKCS#7 certificate authority chain
or single DER-format certificate authority)
-p Key Store password. If missing, use the default password.
-a Key pair algorithm: Either RSA or DSA. RSA is the default value.
-P Create a certificate authority keystore including the certificate authorities trusted
by the current JRE.
-N Set the certificate authority trust store to NIST SP800-131a standard.
-R Restore non-Nist SP800-131a certificates back to trust store.

These parameters create a signing key pair and PKCS#10 CSR:

-c -s -d cn=Me,o=MyCompany,c=CA -r [Link] -a DSA -p password

These parameters import the third-party CA generated encryption certificate and PKCS#7 CA certificate
chain:

-i -e -r [Link] -p password -t cacert.p7b

These parameters import the third-party CA generated signing certificate and PEM CA certificate chain:

-i -s -r [Link] -p password -t [Link]

These parameters add [Link] as a trusted certificate:

-i -T -r [Link] -p password -t [Link]

These parameters export the signing certificate to [Link]:

-E -s -r [Link] -p password

These parameters export the IBM Cognos CA certificate to [Link] (when you are not using a third-party
certificate authority):

-E -T -r [Link] -p password

306 IBM Planning Analytics: Installation and Configuration

 These parameters remove all non-NIST SP800-131a CA certificates and set the CA trust store to NIST
SP800-131a standard:

-N -D ../configuration -p password

These parameters restore JRE non-NIST SP800-131a certificates back to the CA trust store:

-R -D ../configuration -p password

TM1 Server data encryption

You can configure the IBM TM1 Server to encrypt data when it is written to disk.
Note :
TM1 Server data encryption is only available for Planning Analytics Local [Link] Analytics on
Cloud and distributed TM1 Servers do not support TM1 Server data encryption.
Although TM1 Server data encryption is not supported in Planning Analytics on Cloud, the Planning
Analytics on Cloud offering does provide Encryption at Rest.
TM1 Server uses a two-tier key management system to encrypt/decrypt server data. The first tier includes
a data encryption key (DEK) to encrypt data. The DEK is stored on-disk in a directory (within the model)
called }key. The second tier uses a primary key (PK) to encrypt the DEK. The primary key is stored in an
IBM Global Security Kit (GSKit) store and can be rotated regularly for added security.
CAUTION : You must back up your primary key as part of your regular TM1 backup and restore
procedure. If you lose your primary key, you cannot restore the primary key. You will be unable to
access data on your TM1 server.
When a primary key is rotated, the DEK is decrypted by using the previous primary key and then
encrypted with the new primary key. During a rotation, the DEK is backed up in a }key_backup
subdirectory; located in the }key directory. Older primary keys are persisted in the keystore in case a
model restoration is required later.
Note : Encryption is not supported on a TM1 Server that is using replication and sync.
Key generation and rotation are performed by the TM1 server. Using the TM1 API, a TM1 Admin user can
enable and disable server encryption. An API method can also be used to perform an PK rotation.
Users have limited control over the keys that are generated by the TM1 Server. However, the user will still
have control over the GSKit store by using the command line utility that is provided by the GSKit. A user
must use care when they manage the keys in the GSKit store.
When the TM1 Server generates an PK and a DEK, the keys use the following format for identification and
allow the server to associate primary keys to their appropriate DEKs.
• ibm_tm1_mk_version_model_name_time_stamp (For example,
ibm_tm1_mk_v1_planning_sample_2016031510211514)
• ibm_tm1_dek_version_model_name_time_stamp (For example,
ibm_tm1_dek_v1_planning_sample_2016031510211514)
The TM1 Server includes a command line utility, which provides a (-K) option to perform a primary key
rotation. The order of operation is as follows:
1. New names (time stamps) are generated for the data encryption and primary keys.
2. A new primary key is generated in the GSKit store.
3. The existing DEK is encrypted with the new primary key and saved to disk with the new DEK name.
4. The existing DEK is moved to the }key_backup folder.
5. The TM1 Server is shut down.
Note : You cannot perform a key rotation on a model that is not configured for encryption.

Chapter 15. Planning Analytics Local security 307

 If another instance of the TM1 Server is running when a key rotation is performed, an error indicates that
the TM1 server log is locked by another server instance.
During startup, the server performs a model conversion based on the existence or absence of a DEK in the
model directory. The following table outlines the server actions based on these conditions.

Table 32. TM1 server data encryption behavior

DEK Presence TM1 Server Behavior
No TM1 Server operates without data encryption.
Yes TM1 Server uses the existing DEK to encrypt or decrypt the model files.
When the server decrypts a model, the DEK is moved to the backup
folder and the server completes the process of loading the model.

TM1 model conversion

The server converts only files that were generated by TM1 processes. The following table lists the files
that are converted.

Table 33. TM1 object file extensions

Extension Description
.dim Dimension
.hie Hierarchy
.sub Subsets can be located in a user's private folder
.cub Cubes
.tab Old cube format
.set Sets can be located in a user's private folder
.vue Views can be located in a user's private folder
.xbv Expression-based views can be located in a user's private folder
.pro Processes
.rux Rules
.cho Chores
.namemap Sandbox
.dr Data reservation
tm1s*.log Server transaction logs
tm1s*.rej Rejected server transaction logs
tm1rawstore.* Pending audit event entries
tm1auditstore*.log Process audit event entries
.cube located under the }Applications folder
.chore located under the }Applications folder
.dimension located under the }Applications folder
.process located under the }Applications folder
.extr located under the }Applications folder

308 IBM Planning Analytics: Installation and Configuration

Table 33. TM1 object file extensions (continued)
Extension Description
.view located under the }Applications folder
.subset located under the }Applications folder

Note : Binary large objects (BLOBs) used with data import, or Websheets stored as BLOBs under
the }Applications folder of any file with a .blb extension, are not encrypted when the TM1 Server is
enabled with encryption at rest. These files are out of the control of the TM1 Server, which makes it
difficult to track their location and content accurately. For data safety, binary large objects (BLOBs) are not
encrypted.

TM1 APIs
You can use TM1 APIs to enable and disable encryption, and rotate the server key. You must be a member
of the TM1 Admin group. You can also move data objects manually between two servers.
For example, a user might create a process that they would like to move into their production server. The
file can be decrypted by the development server, and encrypted by the production server. The file is then
ready to be loaded into the production server.
The following methods perform a server shutdown and then convert the model.

TM1V TM1API TM1EncryptDataModel( TM1P hPool, TM1V hServer, TM1V iMinutesBeforeShutDown );

TM1V TM1API TM1DecryptDataModel( TM1P hPool, TM1V hServer, TM1V iMinutesBeforeShutDown );

The following method performs a key PK rotation.

TM1V TM1API TM1RotateDataModelKey( TM1P hPool, TM1V hServer );

The following methods encrypt and then decrypt a file.

TM1V TM1API TM1EncryptDataFile( TM1P hPool,

TM1V hServer, TM1V sFileSrc, TM1V sDestPath, TM1V fileType );

TM1V TM1API TM1DecryptDataFile( TM1P hPool,

TM1V hServer, TM1V sFileSrc, TM1V sDestPath, TM1V fileType );

These methods convert a file. Optionally, you can provide a destination path. If omitted, the source file is
overwritten. The files must be accessible by the TM1 server and paths must be specified as relative to the
TM1 server.
The following file types are valid:
• TYPE_OBJECT_FILE (1)
• TYPE_TRANSACTION_LOG_FILE (2)
• TYPE_AUDIT_LOG_FILE (3)

TM1Crypt utility
The TM1Crypt utility allows users to manage the server for data encryption. The utility can also be used to
convert files.
This command demonstrates a key rotation example:

tm1crypt -i [Link] -action rotate

Chapter 15. Planning Analytics Local security 309

 This command demonstrates a decryption example:

tm1crypt -i [Link] -action decrypt

-filesrc C:\DataModel\[Link]
-filetype 2 -filedest C:\Temp\LogDir

Details:

tm1crypt -?
or tm1crypt -help
or tm1crypt [<cmd_parm>...]
where <cmd_parm> is one of:
-i <filespec>
-logpath <string>
-connect <string>
-action <string>
-keyfile <string>
-outfile <string>
-filesrc <string>
-filedest <string>
-filetype <string>
-minsbeforeshutdown <string>
-validate
-<connect_parm>...

where <connect_parm> is one of:

-adminhost <string>
-server <string>
-user <string>
-securitymode
-retryattempts
-retryinterval
<password_parm>
-keystorefile <filespec>
-keystashfile <filespec>
-FIPSOperationMode <1|2|3>
-CAMNamespace <string>

where <password_parm> is one of:

-pwd <string>
-passwordfile <filespec>
-passwordkeyfile <filespec>

For more information, see “Run the TM1Crypt utility” on page 310.

Run the TM1Crypt utility

The TM1Crypt utility ([Link]) is a command prompt that encrypts the password that the IBM TM1
Server needs to access the private key. The utility can be used to convert a model or a file.
The password is encrypted with Advanced Encryption Standard, 256 bit, Cipher Block Chaining (AES-256-
CBC).

Location
The TM1Crypt utility, [Link], is installed in the directory:
PA_install_directory\bin

Syntax
Run the TM1Crypt utility from a command prompt with the following syntax:
[Link] [<cmd_parm> <connect_parm> <password_parm>]
You can provide parameters with constant values in a configuration file when you run tm1crypt.

310 IBM Planning Analytics: Installation and Configuration

Command parameters
Parameter Value Description
i filespec Name of the file that contains default configuration
parameters. Parameters specified in this file are
used, unless overridden by parameters provided on
the command prompt. If no path is specified, the
TM1 Server directory is assumed. If -i is not
specified, then other parameters must be specified
to provide the process name, TM1 Server, and so
on.
connect string This parameter can be used to specify a section in
the configuration file that contains parameters
used to make server connections, such as user,
pwd, or CAMnamespace.
logpath string Enables logging and specifies location of log.
action string 1 [default] - Generate encrypted password and key
file
2 - Encrypt server model
3 - Decrypt server model
4 - Encrypt file using server key
5 - Decrypt file using server key
6 - Rotate server key

keyfile string Name of the file generated containing key. If no

keyfile is specified the default is [Link].
outfile string Name of file generated encrypted password. If no
outfile is specified the default is [Link].
filesrc string Source file to perform conversion. Source is
replaced with converted data unless file
destination is provided.
filedest string Source file to perform conversion. Source is
replaced with converted data unless file
destination is provided.
filetype string 1 [default] - TM1 object file
2 - Transaction log
3 - Audit log

minsbeforeshutdown Time before performing a shutdown when

encrypting or decrypting a server model.
validate Validate key file.

help Display help documentation including parameters

and descriptions.

? Display a synopsis of command line parameters.

Chapter 15. Planning Analytics Local security 311

 Connect Parameters
Connect parameters are common across TM1 components and can be defined in their own section of a
configuration file to reuse them.

Parameter Value Description

-adminhost string TM1 admin host
-server string TM1 Server name
-user string TM1 or Cognos Access Manager (CAM) username,
depending on the type of authentication that is
used by the TM1 Server.
-securitymode Security mode used to connect to the TM1 Server.
The mode must match the value in the TM1 Server
configuration file.
-retryattempts Number of attempts to connect to the TM1 Server.
-retryinterval Time in seconds to retry connection to the TM1
Server.
-keystorefile filespec The full path of the key database file that contains
the trusted certificate authorities.
-keystashfile filespec The full path of the file that contains the password
that is used to access the key database file.
-FIPSOperationMode 1|2|3 Indicates FIPS mode of operation.
FIPS_MODE = 1 (default)
FIPS_APPROVED = 2
FIPS_NONE = 3

CAMNamespace id The ID of the Cognos Access Manager (CAM)

namespace. This parameter is the namespace ID,
not the namespace name.

Password Parameters
Passwords are either prompted for on the command line or supplied by using an encrypted file provided
by the passwordfile parameter.

Parameter Value Description

pwd string Password for the username given in the -user
parameter, in clear text. For greater security, the
password can be specified in an encrypted file
using the -passwordfile parameter.
This parameter is ignored on the command line.
You are prompted for the password.

passwordfile filespec Filename of the file containing the encrypted

password for the user specified by -user. If no
path is specified, the TM1 Server directory will be
assumed. When this option is used, you cannot use
-pwd.

312 IBM Planning Analytics: Installation and Configuration

Parameter Value Description
-passwordkeyfile filespec If the passwordfile parameter is given, a key file
is also required to decrypt the password. The
password file and key file can be created using the
TM1Crypt tool.

Example
For example, the command

[Link] -keyfile [Link] -outfile [Link] -validate

Generates two files:

• [Link] contains the key that is used to encrypt/decrypt the password for the private key.
• [Link] contains the encrypted password for the private key.
The generated files are written to the PA_install_directory\bin directory.
Note : The use of the pwd parameter on the command line does not display an error but the pwd
parameter is ignored. You are prompted for the password and must verify it.

TM1Crypt configuration file

[tm1crypt]
#connect=ConnectParams
#retryattempts=3
#retryinterval=3

### Actions ###

##1 – OPERATION_CRYPT_PWD
##2 - OPERATION_ENCRYPT_MODEL
##3 - OPERATION_DECRYPT_MODEL
##4 - OPERATION_ENCRYPT_FILE
##5 - OPERATION_DECRYPT_FILE
##6 - OPERATION_ROTATE_KEY
###
#action=

### File Types

##1 - Object File //default
##2 - Transaction Log
##3 - Audit Log
###
#filetype=

### Valid path for logs files

#logpath=

### Path to file source and destination

#filesrc=
#filedest=

#adminhost=
#server=
#user=
#pwd=
#camnamespace=

[Connect - ConnectParams]
#adminhost=
#server=
#user=
#pwd=
#camnamespace=
#passwordfile=
#passwordkeyfile=

Chapter 15. Planning Analytics Local security 313

314 IBM Planning Analytics: Installation and Configuration
Chapter 16. Configuring and maintaining Planning
Analytics Local
The following topics describe advanced topics in setup, maintenance, and configuration.

Setting up unattended installations and configurations

You can set up an unattended installation and configuration to install an identical configuration across
several computers on your network. You can automate the installation and configuration process by
specifying options and settings for users.
Before you set up an unattended installation and configuration, ensure that all the system requirements
and prerequisites are met and that all third-party products are installed and configured.

Procedure
1. Configure a transfer specification file (.ats) to specify installation options.
2. Run the installation tool in silent mode.
3. Use a pre-configured configuration file from another computer.
4. Run the configuration tool in silent mode.

Set up an unattended installation for IBM Cognos components

Use a transfer specification file (.ats) to copy IBM Cognos components to your computer without being
prompted for information. Use the following TM1 product codes for an unattended installation.
By default, each time you install IBM Cognos components with the installation wizard, the options you
select are recorded in a transfer specification file. Therefore, if you already installed IBM Cognos
components on a sample computer, you can use the generated transfer specification file as a template for
unattended installations on different computers.
If you do not use the installation wizard to install components, you can use the default transfer
specification file named [Link] that is available on the disk. You must modify the
[Link] file for your environment before you can use it for an unattended installation.
You can check whether the unattended installation was successful by checking the return status. A value
of 0 indicates success and all other values indicate that an error occurred.

Procedure
1. Use the installation wizard to install IBM Planning Analytics components on one computer.
2. After the installation is complete, go to tm1_location/instlog to locate the transfer specification
file (.ats) that was generated during the installation. The file name format is ts-product_code-
version-yyyymmdd_hhmm.ats.
Where product_code is as listed in the following table:

Table 34. TM1 product codes for an unattended installation

Product Code Product
TM1APPTIER_APP=1 TM1 Data Tier
TM1SERVER_APP=1 TM1 Server
TM1ADMINSERVER_APP=1 TM1 Admin Server
TM1TOOLS_APP=1 TM1 Tools

© Copyright IBM Corp. 2007, 2021 315

 Table 34. TM1 product codes for an unattended installation (continued)
Product Code Product
TM1WEBAPPTIER_APP=1 TM1 Web Tier
TM1CONTRIBGATEWAY_APP=1 TM1 Applications Gateway
TM1CONTRIBSERVICE_APP=1 TM1 Application Server
TM1WEB_APP=1 TM1 Web
TM1OPERATIONSCONSOLE_APP=1 TM1 Operations Console
Deprecated in v2.0.9 Deprecated in v2.0.9

TM1CLIENTTIER_APP=1 TM1 Rich Tier

TM1PERSPECTIVES_APP=1 TM1 Perspectives
TM1COGNOSINSIGHT_APP=1 Cognos Insight
TM1APIS_APP=1 TM1 API
TM1DEVTIER_APP=1 TM1 Rich Tier
TM1ARCHITECT_APP=1 TM1 Architect
TM1PERFMOD_APP=1 TM1 Performance Modeler
TM1SAMPLETIER_APP=1 TM1 Samples
3. Copy the generated transfer specification file to the computer where you plan to install IBM Planning
Analytics.
4. On the computer where you plan to install the software, do one of the following:
• Insert the appropriate product installation disk, and copy the contents of the disk to your computer.
• Copy the product installation files you downloaded to your computer.
5. Open the transfer specification file in a text editor.
6. In the License Agreement dialogs, change the I Agree property to y. This action means that you are
accepting the license agreement. To read the terms of the license agreement, see the
LA_language_code and notices files in either of these locations:
• On the product disk in the root installation directory for the operating system
• On the computer from which you copied the transfer specification file in the tm1_location/
instlog directory
7. Save the transfer specification file in the directory where you copied the installation files.
8. In a command or terminal window, go to the operating system directory where you copied the
installation files.
9. Enter the following command:
• On Windows, type the following, where location is the directory where you copied the fi[Link]
file:

issetup -s location\[Link]

• On UNIX or Linux, type:

./issetup -s location/[Link]

• On UNIX or Linux where you do not have XWindows, type:

./issetupnx -s location/[Link]

316 IBM Planning Analytics: Installation and Configuration

 Results
If a return status other than 0 is returned, check the log files for error messages. Errors are recorded in
the tm1_location/instlog in a summary error log file. The file name format is tl-product_code-
version-yyyymmdd-hhmm_summary-[Link].
If errors occur before sufficient initialization occurs, log messages are sent to a log file in the Temp
directory. The file name format is tl-product_code-[Link].
After all errors are resolved, you can set up an unattended configuration.

Set up unattended installations for IBM Planning Analytics for Microsoft

Excel
Set up an unattended installation and configuration when you want to install an identical configuration
across several computers on your network or to automate the installation process by specifying options
and settings for users.
There are two ways to set up an unattended installation. Both methods use a transfer specification file
(.ats) to copy IBM Planning Analytics for Microsoft Excel to your computer without you being prompted for
information.
• “Set up the installation using a file generated from the Installation wizard” on page 317
• “Set up the installation using the [Link] file” on page 318
One method allows you to run the installation wizard on your computer. The selections that you make are
recorded in a transfer specification file (.ats). You can use the generated .ats file to perform an unattended
installation across other computers on your network. Alternatively, you can use the default [Link]
file to automate the installation. The installer uses the values in the response file rather than requiring you
to interact with it.
Before you set up an unattended installation and configuration, ensure that all the system requirements
and prerequisites are met and that all third-party products are installed and configured.
For more information, see “Installation overview” on page 200.

Set up the installation using a file generated from the Installation wizard
By default, each time you install IBM Planning Analytics for Microsoft Excel using the installation wizard,
the options that you select are recorded in a transfer specification file. Therefore, if you already installed
Planning Analytics for Microsoft Excel on a deployment computer, you can use the generated transfer
specification file as a template for unattended installations on different computers. You can do this by
starting the installer from the command line and passing the response file in as an argument.
You can check if the unattended installation was successful by checking the return status. A value of zero
(0) indicates success and all other values indicate that an error occurred.

Procedure
1. Use the installation wizard to install Planning Analytics for Microsoft Excel on your computer.
2. Go to [installation_location]/instlog.
3. Locate the transfer specification file (.ats) that was generated:
• If you installed Planning Analytics for Microsoft Excel, the file name is ts-COR-version-yyyymmdd
_hhmm.ats.
4. Copy the transfer specification file to the computer where you plan to install Planning Analytics for
Microsoft Excel.
5. On the computer where you plan to install the software, download and extract the installation
package.
6. In a text editor, open the transfer specification file (.ats) that you copied.

Chapter 16. Configuring and maintaining Planning Analytics Local 317

 7. In the section named License Agreement, change the I AGREE= property to y.
This action means that you are accepting the license agreement. To read the terms of the license
agreement, see the LA_language_code and notices files in either of these locations:
• in the installation package - in the root installation directory for the operating system
• on the computer from which you copied the [Link] file - in the c10_location\license
\product directory
8. Save the transfer specification file in the directory where you extracted the contents of the
installation package, and in the same folder that contains the installer executable file, [Link].
9. Open a Command Prompt window, and then change to the directory in which the installer,
[Link], is located.
10. Type the following command, where location is the file path location of the transfer specification file:
issetup -s location/[Link]
The progress of the installation appears in the Windows task bar.
A value of zero (0) indicates success and all other values indicate that an error occurred. Errors are
recorded in the installation directory in the tl-COR-version-yyyymmdd-hhmm_summary-[Link] log
file.
If errors occur before sufficient initialization occurs, log messages are sent to the tl-COR-version-
[Link] log file, in the Temp directory.

Set up the installation using the [Link] file

If you do not use the installation wizard to install components, you can use the default transfer
specification file named [Link] that is available in the installation package. Use the
[Link] file to copy IBM Planning Analytics for Microsoft Excel to several computers without
being prompted for information.
You must modify the [Link] file for your environment before you can use it for an unattended
installation.
You can check if the unattended installation was successful by checking the return status. A value of zero
(0) indicates success and all other values indicate that an error occurred.

Procedure
1. On the target computer, download and extract the contents of the installation package.
2. In a text editor, go to the operating system directory in the file structure that you extracted and open
the [Link] file.
Each section in the [Link] file corresponds to a dialog box in the installation wizard.
3. In the section named License Agreement, change the I AGREE= property to y.
This action means that you are accepting the license agreement. To read the terms of the license
agreement, see the LA_language_code and notices files in the root installation directory for the
operating system in the installation package.
4. In the APPDIR= location, type the path of the installation location folder.
Note : Ensure that there are no spaces on either side of the equal sign (=).
5. For the APPFOLDER= property, type the name of the Start menu folder that contains your program
shortcuts.
Note : To ensure that the shortcut folder is visible to all users, for the ALLUSERS_FLAG= property,
type 1.
6. In the section named [Component List], next to each component:
• To install the component, type 1.
• To not install the component, type 0.

318 IBM Planning Analytics: Installation and Configuration

 For example, COR_APP=0.
7. In the [Install Conditions] section:
• To specify that the condition is true, type 1.
• To specify that the condition is false, type 0.
8. After you make the necessary changes, save the [Link] file to a local directory.
9. Open a Command Prompt window, and then navigate to the directory in which the installer,
[Link], is located.
10. Type the following command, where location is the file path location of the transfer specification file:
issetup -s location/[Link]
The progress of the installation appears in the Windows task bar.
A value of zero (0) indicates success and all other values indicate that an error occurred. Errors are
recorded in the installation directory in the tl-COR-version-yyyymmdd-hhmm_summary-[Link] log
file.
11. If errors occur before sufficient initialization occurs, log messages are sent to the tl-COR-version-
[Link] log file, in the Temp directory.

Set up an unattended configuration for IBM Cognos components

Before you set up an unattended configuration, you must export a configuration from another computer
that has the same IBM Cognos TM1 components installed. You can then run IBM Cognos Configuration in
silent mode.
The exported configuration contains the properties of the Cognos TM1 components that you installed on
the source computer. If you made changes to the global configuration, you must also copy the global
configuration file from the source computer to the computer where you plan to run an unattended
configuration.

Before you begin

Ensure that the configuration settings on the local computer are appropriate to use to configure another
computer with the same installed components.

Procedure
1. In IBM Cognos Configuration, from the File menu, click Export as.
2. If you want to export the current configuration to a different folder, in the Look in box, locate and open
the folder.
3. In the File name box, type a name for the configuration file.
4. Click Save.
5. Copy the exported configuration file from the source computer or network location to the
install_location/configuration directory on the computer where you plan to do an
unattended configuration.
6. Rename the file to [Link].
7. If you changed the global configuration on the source computer, copy the [Link] file from
the source computer to the install_location/configuration directory on the computer where
you plan to do an unattended configuration.
8. Go to install_location/bin64 directory.
9. Type the configuration command:
[Link] -s
To view log messages that were generated during an unattended configuration, see the
cogconfig_response.csv file in the install_location/logs directory.

Chapter 16. Configuring and maintaining Planning Analytics Local 319

 Results
You can check if the unattended configuration was successful by checking the return status. A value of
zero (0) indicates success and all other values indicate that an error occurred.
Cognos Configuration applies the configuration settings specified in the local copy of [Link],
encrypts credentials, generates digital certificates, and if applicable, starts the IBM Cognos service or
process.

Set up an unattended uninstallation for IBM Cognos components

You can set up an unattended uninstallation to automate the removal of components on several
computers that have the same components or to remove components on a UNIX or Linux environment
that does not have Microsoft Windows.

Procedure
1. Go to tm1_locaton/instlog.
2. Open the transfer specification .ats file for the product in a text editor.
The filename format of the transfer specification .ats file is ts-product_code-version-
yyyymmdd_hhmm.ats
See “Set up an unattended installation for IBM Cognos components” on page 315 for a list of the TM1
product codes.
You need to edit only one .ats file per product.
3. In the section named [Component List], specify the components to remove.
• To remove the component, type 1
• To leave the component installed, type 0
By default, all installed components are set to be removed.
4. Save and close the file.
5. Repeat steps 2 to 4 for each installed product.
6. From the operating system command line, change to the tm1_location/uninstall directory.
7. At the command prompt, type the following command:
• On Windows,
uninst -u -s
• On UNIX or Linux,
./uninst -u -s
• On UNIX or Linux without XWindows,
./uninstnx -u -s

Maintaining your IBM Planning Analytics Local installation

After successfully installing IBM Planning Analytics Local, you can perform maintenance tasks such as
installing additional components, backing up and restoring your data and configuration files, and
uninstalling the current version.
Installing additional components
You can return to the Planning Analytics Wizard to install additional components that are not installed.
Backing up data and configuration files
You should regularly back up your data and configuration files, especially before you upgrade to a new
version of Planning Analytics.

320 IBM Planning Analytics: Installation and Configuration

 Uninstalling the current version
Depending on which Planning Analytics components you installed, you might have to perform
separate steps to remove them. For example, IBM Cognos Insight and IBM Cognos TM1 Performance
Modeler are uninstalled differently than the other Planning Analytics components.

Backing up data and configuration files for IBM Planning Analytics Local
This topic describes how to back up your data and configuration files for IBM Planning Analytics Local.

About this task

Each Planning Analytics component has its own set of related data and configuration files. Review and
follow the steps below to backup the data and configuration information for the components you are
using.
For example:
• For each IBM TM1 Server you are running, backup your TM1 data directory and configuration files.
• If you are using Cognos TM1 Web, you should back up the related data and configuration files for that
component.
• If you are using Cognos TM1 Applications, you should export your applications and backup any other
related files.

Procedure
1. Export configuration settings from IBM Cognos Configuration:
If you used the Cognos Configuration utility to run and manage your TM1 components, such as the
TM1 Admin Server, TM1 servers, or the TM1 Application Server, you can save an XML file of your
configuration information.
a) Open Cognos Configuration.
b) Click File > Export As.
c) Select a location and enter a file name for the XML file.
d) Click Save.
2. Back up TM1 Server databases:
Save a copy of the contents of your IBM TM1 database data directories and subdirectories to a secure
location. These directories contain both data and configuration files. For example, the TM1 sample
database directories and subdirectories are located here:
<TM1_Install>\samples\tm1
3. Back up additional TM1 configuration files:
Save a copy of any TM1 configuration files you may want to retain, such as the TM1 Admin Server
logging properties file, [Link], located in the <TM1_Install>\bin
\directory.
4. Back up TM1 Web:
If you use Cognos TM1 Web, backup the tm1web_config.xml file and any custom Cognos TM1 Web
server pages to a secure location. The default location for these files is:
<TM1_Install>\webapps\tm1web\
<TM1_Install>\webapps\tm1web\web-inf\configuration\
5. Back up Cognos TM1 Architect and Cognos TM1 Perspectives:
If you are using Cognos TM1 Architect or Cognos TM1 Perspectives, save the [Link] client
configuration file from:
• %ALLUSERSPROFILE%\Application Data\Applix\TM1\

Chapter 16. Configuring and maintaining Planning Analytics Local 321

 • %USERPROFILE%\Application Data\Applix\TM1\
In most cases, the full paths to these files are:
• C:\Documents and Settings\All Users\Application Data\Applix\TM1\[Link]
• C:\Documents and Settings\<username>\Application Data\Applix\TM1\[Link]

Modifying Cognos TM1 installed components

You can modify your current installation by reinstalling components or adding components that are not
already installed.

About this task

You can only install components using the install wizard, you cannot remove components using this
method.
Note : Program maintenance does not include changing the location of the Cognos TM1 installation
directory. To change the location of the installation directory, remove all Cognos TM1 files and reinstall
Cognos TM1 in another location.

Procedure
1. To start the installation:
• Go to the download location for the Cognos TM1 installation program.
• Or, insert the IBM Cognos TM1 product disk.
If the installation wizard does not open automatically, go to the operating system directory to locate
the [Link] file.
2. Right-click the [Link] command and click Run as Administrator.
3. Click Next to advance to the Component Selection screen.
If prompted, respond to the following questions:
• Confirm that you want to install to the same location as a previous installation.
• Confirm whether or not you want to create a backup of all files from the existing installation.
4. On the Component Selection screen, select the Cognos TM1 components you want to install and click
Next.
The Component Selection screen shows the current state of your Cognos TM1 installation.
• Items that are currently installed display with a red X icon next to the component name.
• Items that are not currently installed display with a green check mark next to the name. These items
are automatically selected for installation.

5. Click Next to start the modifications.

6. Click Finish when the modifications are completed.

Uninstalling IBM Planning Analytics

To remove and uninstall all components of IBM Planning Analytics, follow these steps.

Before you begin

Before you start to uninstall Planning Analytics, you must have completed the backup of all Planning
Analytics data.
For details, see:
• “Backing up data and configuration files for IBM Planning Analytics Local” on page 321.

322 IBM Planning Analytics: Installation and Configuration

 About this task
Depending on which components you installed, you might have to perform separate steps to remove
them. For example, IBM Cognos Insight and IBM Cognos TM1 Performance Modeler are uninstalled
differently than the other IBM Cognos TM1 components.

Procedure
1. Uninstall Cognos Insight:
a) From the Windows Control Panel, choose Add or Remove Programs.
b) In the list of currently installed programs, select IBM Cognos TM1 Insight.
c) Click Remove and follow the instructions to complete the process
d) Check program files directory to see if any files remain. If so delete them manually.
2. Uninstall Cognos TM1 Performance Modeler:
a) From the Windows Control Panel, choose Add or Remove Programs.
b) In the list of currently installed programs, select IBM Cognos Performance Modeler.
c) Click Remove and follow the instructions to complete the process
d) Check program files directory to see if any files remain. If so delete them manually.
3. Uninstall core TM1 components:
These steps uninstall all of the following components in a single procedure:
• IBM TM1 Server
• Cognos TM1 Admin Server
• Cognos Configuration
• Cognos TM1 Web
• Cognos TM1 Architect
• Cognos TM1 Perspectives
• Cognos TM1 Applications
• Cognos TM1 Operations Console (Deprecated in v2.0.9)
a) From the Microsoft Windows Start menu, click Programs > IBM Planning Analytics > Uninstall
IBM Planning Analytics > Uninstall IBM Planning Analytics.
b) Select the language for the uninstall wizard and click Next.
c) On the Select the packages you wish to uninstall screen, click the check box for the IBM Planning
Analytics option, then select Next.
The uninstall program removes the components and may take some time. When completed, you
will be prompted to restart your computer.
d) Choose to restart now or later, then click Finish.
e) Check the TM1 installation directory to see if any files or sub-directories remain. If so delete them
manually.
For example, check C:\Program Files\IBM\cognos\tm1.

Restoring data and configuration files in IBM Planning Analytics version

2.0.0
After installing the newer version of IBM Planning Analytics, complete these steps to restore your
previous Cognos TM1 configuration and data files.

Before you begin

Install the new version of the product.

Chapter 16. Configuring and maintaining Planning Analytics Local 323

 About this task
These steps apply only to restoring data and configuration files for IBM Cognos TM1 version 10.x.x.

Procedure
1. Restore TM1 Server data:
For each TM1 server that you want to restore, copy its data directory and subdirectories to the new
location for data: <TM1_Install>\samples\tm1.
2. Restore configuration information in IBM Cognos Configuration:
This includes configuration information for TM1 Admin Server, TM1 Application Server, and each TM1
Server you want to run.
a) Open IBM Cognos Configuration.
b) In the Cognos Configuration Explorer pane, expand Local Configuration > Environment .
c) Click TM1 Admin Server and update the parameters in the Properties pane.
d) Expand IBM Cognos TM1 services and click IBM Cognos TM1 and update the parameters in the
Properties pane.
e) Click Data Access > TM1 Server and add an entry for each TM1 server that you want to use.
For details, see “Adding an existing TM1 Server in Cognos Configuration” on page 99.
f) Click File > Save.
3. Restore Cognos TM1 Architect and Cognos TM1 Perspectives configuration files:
If you want to restore any settings from your previous installation of Cognos TM1 Architect or Cognos
TM1 Perspectives, copy the values from your old [Link] file into the new [Link] file.

Attention : If you leave your old [Link] files in place, you might need to update the
directory path in the file for the AdminSvrSSLCertAuthority parameter. For example, if you
are using the default Cognos TM1 SSL certificate, manually change the value for this parameter
to the new install path C:\Program Files\IBM\cognos\tm1\bin\ssl\[Link].
a) Update the new system default [Link] file located here:
%ALLUSERSPROFILE%\Application Data\Applix\TM1\[Link]
For example: C:\Documents and Settings\All Users\Application Data\Applix
\TM1\[Link]
b) Update the new user-specific [Link] file located here:
%APPDATA%\Applix\TM1\[Link]
For example: C:\Documents and Settings\user name\ApplicationData\Applix
\TM1\[Link]
4. Restore your TM1 Web files:
Note : As of IBM Cognos TM1 version 10.2.0, the default installation directory for TM1 Web is
<TM1_Install>\webapps\tm1web\.
• Restoring files from Cognos TM1 Web version 10.2.0 or newer:
Open your old tm1web_config.xml file and selectively merge the lines and parameters that you
want to use into the new tm1web_config.xml file located in <TM1_Install>\webapps
\tm1web\web-inf\configuration.
• Restoring files from a pre-10.2.0 version of Cognos TM1 Web:
Note : Cognos TM1 Web version 10.2.0 uses a new configuration file named tm1web_config.xml.
This file replaces the [Link] file from previous TM1 Web versions. For more information, see
“Modifying TM1 Web configuration parameters” on page 218.

324 IBM Planning Analytics: Installation and Configuration

 Open your old [Link] file and selectively merge the lines and parameters that you want to
use into the new tm1web_config.xml file located in <TM1_install>\webapps\tm1web\web-
inf\configuration.
5. Restore your application and configuration files in Cognos TM1 Applications:
For details, see:
• “Restoring application and configuration files in Cognos TM1 Applications” on page 325
• “Importing an application definition in Cognos TM1 Applications” on page 325

Restoring application and configuration files in Cognos TM1 Applications

You can manually restore backup copies of your application and configuration files into an existing version
of IBM Cognos TM1 Applications.

Before you begin

The Cognos TM1 server that your application depends on must be restored and running before you
restore the application files for Cognos TM1 Applications.

Procedure
1. Restore your applications for Cognos TM1 Applications:
Copy your application files here:
<TM1_Install>\webapps\pmpsvc\WEB-INF\applications
2. Restore your configuration files for Cognos TM1 Applications:
Copy your backup copies of the pmpsvc_config.xml and fpmsvc_config.xml configuration files
to here:
• <TM1_Install>\webapps\pmpsvc\WEB-INF\configuration\pmpsvc_config.xml
• <TM1_Install>\webapps\pmpsvc\WEB-INF\configuration\fpmsvc_config.xml
3. In Cognos Configuration:
a) Start the TM1 Application server.
b) Start the TM1 servers that are related to your application.
4. Log in to the Cognos TM1 Applications portal and add the related TM1 server to the configuration page
if it is not already listed.

a) Click the Administer IBM Cognos TM1 Applications icon on the toolbar of the Cognos TM1
Applications main page.
b) Under the Server Names section, click Add and enter the information for the related TM1 server.
c) Click OK.
The applications in the webapps/pmpsvc/WEB-INF/application folder will be upgraded and
added to Cognos TM1 Applications.
Note : The upgrade process may take some time depending on the amount of rights that need to be
applied in the application. For more information, see “How do I save security rights when importing
or restoring a Cognos TM1 10.2.x application?” on page 400.

Importing an application definition in Cognos TM1 Applications

You can import an application definition that was exported from IBM Cognos TM1 Applications back into
IBM Cognos TM1 Applications.

Procedure
1. Open the Cognos TM1 Applications portal.

Chapter 16. Configuring and maintaining Planning Analytics Local 325

 2. Click the Import Application button.
3. Select the Cognos TM1 server onto which you want to import the application.
4. Next to the Application file field, click Browse.
5. Navigate to the application (.zip) file, then click Open.
6. Select the Import application security option if you want to import security settings with the
application.
Note : If you import security settings, the rights-saving operation may take longer to process
depending on the amount of rights that need to be applied in the application. For more information,
see “How do I save security rights when importing or restoring a Cognos TM1 10.2.x application?” on
page 400.
7. Select the Import application properties option if you want to import property settings with the
application.
8. Click Import.

The [Link] configuration file

The [Link] file is an ASCII file that specifies environment information for an IBM TM1 Server.
A default [Link] file is created in the TM1 Server data directory when you install a copy of the TM1
Server. Most of the available parameters are documented in the configuration file. If a parameter is not
installed by default, the parameter is commented out in the configuration file. You can edit the [Link]
file to reflect the environment of the associated remote server by uncommenting the parameter that you
want to use and setting the correct value.
Note : IBM TM1 Server on IBM POWER8 little endian (LE) uses a subset of the TM1 Server configuration
parameters in the [Link] file. For more information, see “Sample [Link] file” on page
333.
For an alphabetical listing of all the parameters in the server configuration file, see “Parameters in the
[Link] file” on page 336.

Location of the [Link] file

The location of the [Link] file depends on the type of server you are using.
• If you are using the IBM Cognos Configuration tool to start and stop your IBM TM1 Server, you can view
the configuration path for a TM1 Server by clicking the server name in the Explorer tree of Cognos
Configuration.
• If you are running the TM1 Server remotely as a Microsoft Windows service ([Link]), and you used
the TM1 installation program to install the server, the system uses the [Link] file that is located in the
server data directory you specified during installation.
• If you are running the TM1 Server remotely as a Windows application ([Link]), you specify the
location of the [Link] file by using the -z parameter in the command line when you start the server,
either from a shortcut or from a command prompt.
For example, this command specifies that TM1 uses the [Link] file located in the c:\salesdata
directory:

c:\Program
Files\Cognos\TM1\bin\[Link]
-z c:\salesdata

If the -z parameter points to a directory containing spaces, you must enclose the directory in double
quotation marks. For example, -z "c:\sales data".
• If you are running a TM1 Server on UNIX, and you used the TM1 installation program to install the
server, the system uses the [Link] file that is located in the server data directory you specified during
installation.

326 IBM Planning Analytics: Installation and Configuration

 • If you are running a TM1 Server on IBM POWER8 LE, the system uses the [Link] file that is
located in the <install_location>/configuration directory, where <install_location> is the
server data directory you specified during the installation.

Sample [Link] file

This is a sample [Link] file.
Your [Link] file might also include comments that describe the parameters.

## Licensed Materials - Property of IBM

##
## IBM Cognos Products: TM1
##
## (C) Copyright IBM Corp. 2007, 2017
##
## US Government Users Restricted Rights - Use, duplication or
## disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

[TM1S]
# ServerLogging
# Generates a log with the security activity details on the TM1 server that are associated with
Integrated Login. The log file, named [Link], is saved to the TM1 server data directory.
The ServerLogging parameter is useful only if your TM1 server is configured to use Integrated
Login.
# Type: Optional, Static
#
# Set ServerLogging to T in [Link]. Note also that if ServerLogging=T is set, you must rename
the TM1 server message logfile [Link] by editing the corresponding parameter in the
logger configuration file [Link] file.
ServerLogging=F

# Security package name

# If you configure the TM1 server to use Integrated Login, the SecurityPackageName parameter
defines the security package that authenticates your user name and password in Windows.
# Type: Optional, Static
#
# Valid values are:
# * Kerberos (default) - Windows 2000 or later.
# * NTLM - Older Windows installations, such as Windows NT.
SecurityPackageName=Kerberos

# Security mode
# Type: optional, static
#
#
# If IntegratedSecurityMode is set to 1. All clients must provide a database
# username and password. This is traditionally done through a login screen.
#
# If IntegratedSecurityMode is set to 2. The clients will have the choice
# to connect provide a database username and password or use the single-login
# mechanism for authentication.
#
# If IntegratedSecurityMode is set to 3. All clients must use the single-login
# mechanism for authentication.
#
# If IntegratedSecurityMode is set to 4. The server uses IBM Cognos 8 security authentication.
#
# If IntegratedSecurityMode is set to 5. The server uses IBM Cognos 8 security authentication
and supports user groups from both TM1 and Cognos 8.
#
# If this is not set the parameter will be set to 1 by default.
IntegratedSecurityMode=1

# UseSSL
# Enables or disables SSL on the TM1 server.
# Type: Optional/Required to use SSL, Static
# Set UseSSL=T to enable SSL. With this setting, only TM1 9.1 and later clients will be able to
securely connect to the server.
# Set UseSSL=F to disable SSL. With this setting, all TM1 clients, including older clients that
do not support SSL, will be able to connect to the server in insecure mode.
# When UseSSL=T, you must set several other [Link] parameters that manage SSL implementation.
For details on these parameters, see Running TM1 in Secure Mode Using SSL.
# Default is UseSSL=T

Chapter 16. Configuring and maintaining Planning Analytics Local 327

 UseSSL=T

# Server name to register with the Admin Server. If you do not supply this parameter, TM1 names
the server Local and treats it as a local server.
# Type: Optional, Static
ServerName=SData

# Location of TM1 database

# Type: Required, static
# Specifies the data directory from which the server loads cubes, dimensions, and other
objects. You can list multiple data directories by separating them with semicolons.
#
# Example:
# DataBaseDirectory=C:\Program Files\Cognos\TM1\Custom\TM1Data\PlanSamp\
DataBaseDirectory=.

# AdminHost
# Specifies the computer name or IP address of the Admin Host on which an Admin Server is
running
# Type: Required, Static
# You can specify multiple Admin Hosts by separating each host name with a semicolon on a
Windows TM1 server, or a colon on a UNIX TM1 server. For example:
# * Use the format AdminHost=hostname1;hostname2 on a Windows TM1 server.
# * Use the format AdminHost=hostname1:hostname2 on a UNIX TM1 server.
#
# Some examples include:
# * AdminHost=boston;newyork
# * AdminHost=[Link];[Link]
# * AdminHost=boston;[Link];[Link];myserver;[Link]
#
#Note: The string specifying the admin host(s) is limited to 1020 characters or bytes.
# If set to empty than use localhost
AdminHost=

# TM1 Server Port

# Sets the server port number used to distinguish between multiple servers running on the same
computer. When multiple TM1 servers are installed on a single computer, each server must use a
unique port number.
# Type: Optional, Static
# When you install a TM1 server, the default port number is 12345. Valid port values are
between 5000 and 65535
#
# If the [Link] file does not contain the PortNumber parameter, the TM1 server uses port
5000. Local TM1 servers use port 5000. The port used for Client Messages must also be a unique
port number and is set to 5001 by default when the ClientMessagePortNumberparameter is used.
PortNumber=12346

# ClientMessagePortNumber
# Identifies a secondary port used to accept client messages concerning the progress and
ultimate cancellation of a lengthy operation without tying up thread reserves.
# Type: optional, dynamically set/Sstatic for changes
# This additional port ensures that other server requests can continue to process while waiting
for a cancellation from the user.
#
# By default, this port number is automatically and dynamically assigned when the TM1 server
starts. You do not have to set ClientMessagePortNumber to a specific number unless firewalls or
other network issues require the listener port to be a well-known number.
#
# Note: Be sure to assign unique port numbers for the server and client message ports. If you
have two servers running on the same machine with the same port number, the message activity
may cause a system failure.
ClientMessagePortNumber=

# Language
# Sets the language used in the TM1 interface for the IBM Cognos TM1 [Link] can use this to
override the current locale settings
# This parameter applies to messages generated by the server and is also used in the user
interface
# of the server dialog box when you run the server as an application instead of a Windows
service.
# Type: Optional, Static
#
# Valid values are:
# eng English
# bra Brazilian Portuguese
# hrv Croatian

328 IBM Planning Analytics: Installation and Configuration

# csy Czech
# sch Chinese (Simplified)
# tch Chinese (Traditional)
# dan Danish
# nld Dutch
# deu German
# fin Finnish
# fra French
# hun Hungarian
# ita Italian
# jpn Japanese
# kaz Kazakh
# kor Korean
# nor Norwegian
# pol Polish
# rom Romanian
# rus Russian
# esp Spanish
# sky Slovak
# slv Slovenian
# sve Swedish
# tha Thai
# trk Turkish
#Language=eng

# Savetime
# Sets the time of day to execute an automatic save of server data; saves the cubes every
succeeding day at the same time. As with a regular shutdown, SaveTime renames the log file,
opens a new log file, and continues to run after the save.
# The Savetime parameter is not available when running the TM1 server as a Windows service.
# The format of the SaveTime parameter is dd:hh:mm where:
# * dd is the number of days from today that the system will start automatically saving data.
For example, 00 is today, 01 is tomorrow.
# * hh:mm is the time of day in 24-hour format.
# Type: optional, dynamic
Savetime=

# Downtime
# Specifies a time when the server will come down automatically.
# The Downtime parameter is not available when running the TM1 server as a Windows service.
# The format of the Downtime parameter is dd:hh:mm where:
# * dd is the number of days from today that the system will start automatically saving data.
For example, 00 is today, 01 is tomorrow.
# * hh:mm is the time of day in 24-hour format.
# When you use the DownTime parameter on the UNIX TM1 server, you must set the
RunningInBackground parameter to T. If RunningInBackground=F, the server prompts for
confirmation before shutting down and cannot shut down without manual confirmation from an
administrator.
# Type: optional, dynamic
Downtime=

# LicenseMetricTime
# Sets the time of day the TM1 server will generate a License Metric Tag file.
# A License Metric Tag file is an XML file which contains information about license metrics
consumed by software product instances.
# In the case of TM1 server, the reported authorized user metrics are the number of Modelers,
Contributors and Explorers.
# The License Metric Tag files produced by various instances of TM1 servers are collected by
the IBM License Metric Tool (ILMT) agent and aggregated to produce final metrics based on the
TM1 product version.
#
# The format of the LicenseMetricTime parameter is dd:hh:mm where:
# * dd is the number of days from today that the system will start automatically producing
License Metric tag files. For example, 00 is today, 01 is tomorrow.
# * hh:mm is the time of day in 24-hour format.
# Type: optional, dynamic
LicenseMetricTime=

# ProgressMessage
# This parameter determines whether users have the option to cancel lengthy view calculations.
When a user opens a view that takes a significant amount of time to calculate (usually a view
with high levels of consolidation or complex rules), TM1 monitors the progress of the process.
When ProgressMessage=T a dialog box opens that allows the user to Stop Building View.
# Type: Optional, Static
#
# If the user clicks Stop Building View, the view is discarded on the client, but view
calculation continues on the server. In some instances, this can tie up the server.
# If ProgressMessage=F, the Stop Building View option is not offered and the user cannot cancel

Chapter 16. Configuring and maintaining Planning Analytics Local 329

 lengthy operations. This setting helps avoid potential server tie ups in versions 9.1 SP3
through 9.4.
# When ProgressMessage=T or is not present in the [Link] file, the Stop Building View option
opens during lengthy view calculations so the user can cancel the process if necessary. For
versions 9.4 or later, the user can assign a unique Port Number using ClientMessagePortNumber.
This additional port allows these progress messages to travel via a secondary port so that
server processing can continue without tying up thread reserves.
# Note: To avoid potentially tying up servers, TM1 9.1 SP3 through 9.4 have ProgressMessage=F
inserted into the [Link] file during server installation. As of TM1 9.4, progress messages
can travel via the secondary port assigned by ClientMessagePortNumber so TM1 9.4 and later have
ProgressMessage=T set by default. This parameter has been tested with Citrix when this feature
was redesigned.
ProgressMessage=True

# AuditLogOn
# Turns audit logging on (T) or off (F).
# Type: Optional, Static
AuditLogOn=F

# AuditLogMaxFileSize
# Indicates the maximum file size that an audit log file can grow to before it is closed and a
new file is created.
# Type: Optional, Dynamic
# This value must include units of KB (kilobytes), MB (megabytes), or GB (gigabytes).
# Default value: 100 MB
# Minimum value: 1 KB
# Maximum value: 2 GB
AuditLogMaxFileSize= 100 MB

# AuditLogUpdateInterval
# Indicates the maximum amount of time, in minutes, that TM1 waits before moving the events
from the temporary audit file into the final audit log.
# Type: Optional, Dynamic
# This value must include units of KB (kilobytes), MB (megabytes), or GB (gigabytes).
# Default value: 60 (sixty minutes)
# Minimum value: 1 (one minute)
AuditLogUpdateInterval=60

#PersistentFeeders
# Turn on Persistent Feeders to make TM1 models load faster
# Type: Optional, Static
PersistentFeeders=F

# ServerCAMURI
# Specifies the URI for the internal dispatcher that the TM1 server should use to connect to
CAM. The URI is specified in the form http[s]://host IP address:port/p2pd/servlet/dispatch.
# Type: Optional, Static
# No default
# For example,
#
# [Link]
# or
# [Link]
#ServerCAMURI=[Link]

# ClientCAMURI
# The URI for the IBM Cognos Server IBM Cognos Connection used to authenticate TM1 clients. The
URI is specified in the form http[s]://host/cognos8/cgi-bin/[Link].
# Type: Optional, Static
# No default
# Example: [Link]
#ClientCAMURI=[Link]

# ClientPingCAMPassport
# Indicates the interval, in seconds, that a client should ping the CAM server to keep their
passport alive.
# Type: Optional, Static
# If an error occurs or the passport expires the user will be disconnected from the TM1 server.
#ClientPingCAMPassport=900

## Optional CAM parameters

# CAMSSLCertificate
# Type: Optional/Required only when CAM server is configured with SSL, Static

330 IBM Planning Analytics: Installation and Configuration

# The full path and name of the SSL certificate to be used when connecting to the internal
dispatcher. For example, C:\AxTM1\Install_Dir\ssl\[Link].
#CAMSSLCertificate=

# CAMSSLCertRevList
# CAM SSL Certificate Rev List
#CAMSSLCertRevList=

# Skip SSL CAM Host Check

# Indicates whether the SSL certificate ID confirmation process can be skipped. The default is
FALSE.
# Type: Optional, Static
# Important: This parameter should be set to TRUE only if using a generic certificate for
demonstration purposes.
#SkipSSLCAMHostCheck=TRUE

## Optional LDAP Settings

# PasswordSource
# Determines the source of authentication
# Type: Optional, Static
# Two options:
# * TM1 (default) - Compares the user-entered password to the password in the TM1 database.
# * LDAP - Compares the user-entered password to the password stored in on the LDAP server.
#PasswordSource=LDAP

# LDAPPort
# TM1 attempts to bind to an LDAP server on the specified secure port. If you do not enter an
LDAPPort value, TM1 uses the default value, port 636
# Type: Optional, Static
# This must be a secure (SSL) port.
#LDAPPort=636

# LDAPHost
# Uses the domain name or dotted string representation of the IP address of the LDAP server
host. If you do enter a value for LDAPHost, TM1 uses the default value, localhost.
# Type: Optional, Static
#LDAPHost=localhost

# LDAPUseServerAccount
# Determines if a password is required to connect to the server when using LDAP authentication.
# Type: Optional
# To connect directly to the LDAP server using integrated authentication, set this parameter to
T. Set this parameter to T whenever the IBM Cognos TM1 server and LDAP server exist on the same
domain.
# To use a password before connecting, set this parameter to F. When LDAPUseServerAccount is
set to F, you must also set the LDAPPasswordFile and LDAPPasswordKeyFile to successfully
connect to the LDAP server using SSL.
#LDAPUseServerAccount=T

# LDAPSearchBase
# A base distinguished name (DN) in the LDAP directory. For example:
# ou=people,o=[Link]
# Specifies the node in the LDAP tree at which the search for the TM1 user being validated
begins. For example, if the distinguished names are of the form:
# uid-bjensen, ou-people, o=[Link]
#
# then the search base would be:
# ou-people, o=[Link]
# This is a required field if using LDAP Authentication.
#LDAPSearchBase=cn=users,dc=company,dc=com

# LDAPSearchField
# cn
# The name of the LDAP attribute that is expected to contain the name of the TM1 user being
validated. If you do not enter an LDAPSearchField value, the default value is cn, which is also
the default value for Microsoft Active Directory.
#LDAPSearchField=cn=user

# IPVersion
# Select IPv4 or IPv6
# Sets IP protocol.
# Type: Optional, Static

Chapter 16. Configuring and maintaining Planning Analytics Local 331

 #
# Three options:
# * ipv4 - use ipv4 (default)
# * ipv6 - use ipv6
# * dual - use ipv6 with support for ipv4
IPVersion=ipv4

# ServerCAMIPVersion
# Server CAM Internet Protocol Version
# Select IPv4 or IPv6
# Sets IP protocol.
# Type: Optional, Static
#
# Two options:
# * ipv4 - use ipv4 (default)
# * ipv6 - use ipv6
ServerCAMIPVersion=ipv4

# AllowSeparateNandCRules
# Specifies expressions for N: and C: levels on separate lines using identical AREA
definitions, maintaining the rules conventions of TM1.
# Type: Optional, Static
#
# For example,
#
# ['Budget','Argentina']=N:Expression;
#
# ['Budget','Argentina']=C:Expression;
#
# are both valid rules statements when you include the AllowSeparateNandCRules parameter in the
[Link] file and set to T.
#
# This parameter also effects how numeric and string rules are applied to cells. Without this
parameter, the first rule statement that is encountered for a given AREA definition is applied
to the cells within the scope of that definition. If any cell within the AREA definition is
numeric and the rule is a string rule, then the cell is considered not rule-derived because
there was a match that did not apply to the cell.
#
# For example, consider the statements:
#
# ['1 Quarter']=s:'str_value';Not following.
#
# ['1 Quarter']=n:77;
#
# If the AllowSeparateNandCRules parameter is not set (or is set to F), then the first rule
statement will match any cell that uses '1 Quarter' as one of its elements. If the cell is a
string cell, the value of the cell will be set to “str_value”. If the cell is a numeric cell,
the cell will not be considered rule derived, since a match was found (the first rule) but the
rule itself did not apply.
#
# If the AllowSeparateNandCRules parameter is set to T, then string cells which use '1 Quarter'
will be set to "str_value" and numeric cells which use '1 Quarter' will be set to 77.
AllowSeparateNandCRules=T

# DistributedPlanningOutputDir
# Type: Optional, Static
# Cognos Insight distributed clients need information called "tunits".
# This data is created when an application is deployed and is updated as the TM1 server runs.
# The location of the directory used for this purpose is set using this parameter.
# In order to deploy Cognos Insight distributed client applications using this database,
uncomment or add this parameter as DistributedPlanningOutputDir=<location of the tunit
directory>.
# The pathname specified can be absolute, or relative to the TM1 server data directory.
#
# Examples:
#
DistributedPlanningOutputDir=tunit
creates a directory "tunit" under the TM1 server data directory
#
DistributedPlanningOutputDir=..\tunit
creates a directory "tunit" as a sibling to the TM1 server data directory
# DistributedPlanningOutputDir=C:\Program Files\IBM\cognos\tm1\samples\tm1\GO_New_Stores
\tunit creates a directory "tunit" at the specified location.
#DistributedPlanningOutputDir=.\tunit

# ForceReevaluationOfFeedersForFedCellsOnDataChange
# Type: Optional, Static
# When this parameter is set, a feeder statement is forced to be re-evaluated when data changes.

332 IBM Planning Analytics: Installation and Configuration

 # When the IBM Cognos TM1 server computes feeders, the process can be a "chain" of feeders,
where cell A feeds cell B, and there is a feeder rule for cell B, so that rule runs and feeds
cell C, etc. Feeders for numeric cells are only evaluated when a cell goes from empty to some
non-zero value since any non-zero value in the cell would already have set any feeders.
# There is no need to re-evaluate the feeders when a cell changes from one non-zero value to
another.
# Normally, when evaluating feeders, if a feeder rule is evaluated and the target cell is
already fed, the feeding process stops.
# Feeder rules are not processed any further since the presence of the feeder in the target
cell indicates that the feeder rules for the target cell have already been run, and there is no
need to run them again.
# Consider the following feeder rules:
# ['A']=>['B'];
# The feeder rule for cell B depends on some cube data value:
# [B]=>DB(cube-name,!dim1,DB(cube2-name, ...),!dim2);['C']=>['D'];['X']=>['B'];
# When the feeder rule for B is initially evaluated, the DB(cube2-name, ...) is evaluated to
produce an element name, such as C. Therefore B feeds C and then C feeds D. When that cell X
goes from zero to non-zero. This change also feeds B. But B is already fed, so the feeding
process stops, and the feeder rule for B never evaluates, so any "change" in the output of the
rule, which may come about because of an underlying data change targeted by the DB(…) statement
will not be evaluated. If the config parameter
ForceReevaluationOfFeedersForFedCellsOnDataChange is set, then the presence of a feeder in cell
B will not terminate feeder processing. Rather, the feeder rule for B will run. Because the
feeder rule for B is data dependent, the target for the feeder may be the former C, or may be
some other cell, and that cell will be fed. Note that setting this parameter will force more
feeder evaluations, which may have a performance impact.
# To turn on this parameter set ForceReevaluationOfFeedersForFedCellsOnDataChange=T.
ForceReevaluationOfFeedersForFedCellsOnDataChange=T

#Specifies whether multiple hierarchy creation is enabled or disabled.

#Parameter type: optional (required for multiple hierarchies)
#By default, the EnableNewHierarchyCreation parameter is set to F (false). If you are working
with multiple hierarchies, change the parameter setting to T (true). TM1 Reference lists the
TurboIntegrator functions to manage dimensions and equivalent functions to manage specific
hierarchies within dimensions.
EnableNewHierarchyCreation=T

# TM1 Server HTTP Port

# Sets the server port number for HTTP access. Like PortNumber above, it is used to distinguish
between multiple servers running on the same computer. When multiple TM1 servers are installed
on a single computer, each server must use unique values for port number and HTTP port number.
# Type: Optional, Static
# When you install a TM1 server, the default HTTP port number is 12354. Valid port values are
between 5000 and 49151
#
# If the [Link] file does not contain the HTTPPortNumber parameter, then you can not use the
OData v4 Compliant REST API.
HTTPPortNumber=8010

#Specifies whether TurboIntegrator debugging capabilities are enabled or disabled.

#Parameter type: optional, dynamic
#By default, the EnableTIDebugging parameter is set to F (false).
#Setting the parameter to T (true) allows you to use any of the TurboIntegrator process
debugging capabilities of the TM1 REST API.
EnableTIDebugging=T

Sample [Link] file

This is a sample [Link] file for IBM POWER8 LE.

<crn:parameters
xmlns:xsi="[Link]
xmlns:xsd="[Link]
xmlns:cfg="[Link]
xmlns:crn="[Link]
xsi:schemaLocation="[Link] [Link]"
version="166.0">
<!--tm1AdminServer:Defines a group of properties for the TM1 Admin Server.-->
<crn:parameter
name="tm1AdminServer"
opaque="true">
<crn:value>
<!--tm1AdminNonSSLPortNumber:Specifies the TCP port number used by TM1 Admin Server for
unsecured communication.-->
<crn:parameter
name="tm1AdminNonSSLPortNumber">
<crn:value
xsi:type="xsd:unsignedShort">5495</crn:value>
</crn:parameter>

Chapter 16. Configuring and maintaining Planning Analytics Local 333

 <!--tm1AdminSSLPortNumber:Specifies the TCP port number used by TM1 Admin Server for
secured (SSL) communication.-->
<crn:parameter
name="tm1AdminSSLPortNumber">
<crn:value
xsi:type="xsd:unsignedShort">5498</crn:value>
</crn:parameter>
<!--tm1AdminHTTPPortNumber:Specifies the HTTP port number used by TM1 Admin Server for
unsecured communication.-->
<crn:parameter
name="tm1AdminHTTPPortNumber">
<crn:value
xsi:type="xsd:unsignedShort">5895</crn:value>
</crn:parameter>
<!--tm1AdminHTTPSPortNumber:Specifies the HTTPS port number used by TM1 Admin Server for
secured (SSL) communication.-->
<crn:parameter
name="tm1AdminHTTPSPortNumber">
<crn:value
xsi:type="xsd:unsignedShort">5898</crn:value>
</crn:parameter>
<!--tm1AdminSupportNonSSLClients:Specifies if the TM1 Admin Server supports non-SSL TM1
clients.-->
<!--Set the parameter to true to configure TM1 Admin Server to support non-SSL clients
and to listen for client connections on both secured (SSL) and unsecured ports. If set to false
TM1 Admin Server will support only SSL client connections on the secured port.-->
<crn:parameter
name="tm1AdminSupportNonSSLClients">
<crn:value
xsi:type="xsd:boolean">false</crn:value>
</crn:parameter>
<!--tm1AdminSupportPreTLSv12Clients:Specifies if the TM1 Admin Server will supports pre
TLS v1.2 SSL protocols from TM1 clients.-->
<!--Set the parameter to true to allow TM1 clients to connect with TM1 Admin Server using
SSL protocols earlier than TLS v1.2. If set to false (default), TM1 Admin Server will accept
only TLS v1.2 or later SSL protocols.-->
<crn:parameter
name="tm1AdminSupportPreTLSv12Clients">
<crn:value
xsi:type="xsd:boolean">false</crn:value>
</crn:parameter>
<!--tm1AdminKeyFile:Specifies the file path to the key database file.-->
<!--The key database file which contains the server certificate and trusted certificate
authorities.-->
<crn:parameter
name="tm1AdminKeyFile">
<crn:value
xsi:type="cfg:filePath">./ssl/[Link]</crn:value>
</crn:parameter>
<!--tm1AdminKeyStashFile:Specifies the file path to the key database password file.-->
<!--The key store containing passwords to the key database file.-->
<crn:parameter
name="tm1AdminKeyStashFile">
<crn:value
xsi:type="cfg:filePath">./ssl/[Link]</crn:value>
</crn:parameter>
<!--tm1AdminKeyLabel:Specifies label of the server certificate.-->
<!--The label of the server certificate in key database file. A certificate may be marked
as the default.-->
<crn:parameter
name="tm1AdminKeyLabel">
<crn:value
xsi:type="xsd:string">ibmtm1_server</crn:value>
</crn:parameter>
<!--tm1AdminFIPSOperationMode:Specifies the FIPS mode of operation.-->
<!--Controls the level of support for Federal Information Processing Standards (FIPS).
Default is 'enabled'. \n\tEnabled is basic, FIPS 140-2 level 1 support. \n\tApproved is FIPS
140-2 level 2 support. \n\tDisabled is no FIPS support at all.-->
<crn:parameter
name="tm1AdminFIPSOperationMode">
<crn:value
xsi:type="xsd:int">2</crn:value>
</crn:parameter>
<!--tm1AdminNIST_SP800_131A_MODE:Indicates server should operate in compliance of the SP
800-131A standard. Default is true.-->
<crn:parameter
name="tm1AdminNIST_SP800_131A_MODE">
<crn:value
xsi:type="xsd:boolean">true</crn:value>
</crn:parameter>
<!--tlsCipherList:Specifies a list of supported ciphersuites in priority sequence.-->
<!--Use this property to specify what ciphersuites are acceptable in this install. The

334 IBM Planning Analytics: Installation and Configuration

comma-delimited string values are defined by RFC 2246, 4346, 5246, 4492 and 5289. The named
ciphersuites are presented to the SSL negotiation in specified order for both client and server
sides of the negotiation. At least one of the selected ciphersuites between configured client
and server platforms must match.-->
<crn:parameter
name="tlsCipherList">
<crn:value
xsi:type="xsd:string"/>
</crn:parameter>
<!--tm1AdminIPVersion:Specifies the Internet Protocol(s) which the TM1 Admin Server will
support.-->
<crn:parameter
name="tm1AdminIPVersion">
<crn:value
xsi:type="xsd:string">IPv4</crn:value>
</crn:parameter>
<!--tm1AdminActivityInterval:Specifies the interval in seconds wherein the TM1 Server
will notify the TM1 Admin Server that it is active.-->
<crn:parameter
name="tm1AdminActivityInterval">
<crn:value
xsi:type="xsd:positiveInteger">10</crn:value>
</crn:parameter>
<!--tm1AdminInactivityTimeout:Specifies the interval in seconds that the TM1 Server is
allowed to be inactive before it is removed from the TM1 Admin Server.-->
<crn:parameter
name="tm1AdminInactivityTimeout">
<crn:value
xsi:type="xsd:positiveInteger">10</crn:value>
</crn:parameter>
<!--tm1AdminSvrCertificateVersion:Specifies which version of the TM1 generated SSL
certificates to use.-->
<!--By default, the 1024-bit encryption version of the TM1 generated certificates is
used. Change this parameter only if you want to use the new 2048-bit encryption version of the
default certificates. You can use the new version with old and new TM1 clients, but you must
configure the clients to use the new certificate authority file. This parameter does not apply
if you are using your own SSL certificates. Valid values include: 1 = certificate authority to
enable 1024-bit encryption with sha-1 (default value); 2 = certificate authority to enable 2048-
bit encryption with sha-256.-->
<crn:parameter
name="tm1AdminSvrCertificateVersion">
<crn:value
xsi:type="xsd:int">1</crn:value>
</crn:parameter>
</crn:value>
</crn:parameter>
<!--tm1Server:Defines a group of properties for the TM1 Server.-->
<crn:parameter
name="tm1Server"
opaque="true">
<crn:value>
<crn:instances
name="tm1ServerInstances">
<!--24 Retail:Defines a group of properties for a TM1 Server instance.-->
<crn:instance
name="24 Retail"
class="tm1ServerInstance">
<crn:parameter
name="tm1sConfigDirectory">
<crn:value
xsi:type="cfg:folderPath">../samples/tm1/24Retail</crn:value>
</crn:parameter>
</crn:instance>
<!--SData:Defines a group of properties for a TM1 Server instance.-->
<crn:instance
name="SData"
class="tm1ServerInstance">
<crn:parameter
name="tm1sConfigDirectory">
<crn:value
xsi:type="cfg:folderPath">../samples/tm1/SData</crn:value>
</crn:parameter>
</crn:instance>
<!--Planning Sample:Defines a group of properties for a TM1 Server instance.-->
<crn:instance
name="Planning Sample"
class="tm1ServerInstance">
<crn:parameter
name="tm1sConfigDirectory">
<crn:value
xsi:type="cfg:folderPath">../samples/tm1/PlanSamp</crn:value>
</crn:parameter>

Chapter 16. Configuring and maintaining Planning Analytics Local 335

 </crn:instance>
<!--GO_New_Stores:Defines a group of properties for a TM1 Server instance.-->
<crn:instance
name="GO_New_Stores"
class="tm1ServerInstance">
<crn:parameter
name="tm1sConfigDirectory">
<crn:value
xsi:type="cfg:folderPath">../samples/tm1/GO_New_Stores</crn:value>
</crn:parameter>
</crn:instance>
<!--GO_Scorecards:Defines a group of properties for a TM1 Server instance.-->
<crn:instance
name="GO_Scorecards"
class="tm1ServerInstance">
<crn:parameter
name="tm1sConfigDirectory">
<crn:value
xsi:type="cfg:folderPath">../samples/tm1/GO_scorecards</crn:value>
</crn:parameter>
</crn:instance>
<!--Proven_Techniques:Defines a group of properties for a TM1 Server instance.-->
<crn:instance
name="Proven_Techniques"
class="tm1ServerInstance">
<crn:parameter
name="tm1sConfigDirectory">
<crn:value
xsi:type="cfg:folderPath">../samples/tm1/Proven_Techniques</
crn:value>
</crn:parameter>
</crn:instance>
</crn:instances>
</crn:value>
</crn:parameter>
</crn:parameters>

Parameters in the [Link] file

The parameters in the [Link] file are described here.

Dynamic parameter
Dynamic parameter values can be edited while the IBM TM1 Server is running.
The TM1 Server continuously polls the [Link] file at 60 second intervals to determine if any dynamic
parameter values have changed. If the server detects a parameter value change, the new value is applied
immediately. Dynamic parameters are identified with a statement describing them as dynamic in this list.

Static parameter
Static parameter values are read from the [Link] file only when the TM1 Server starts. If you want to
change a static parameter value, you must shut down the TM1 Server, edit the value in the [Link] file,
and then restart the server.
Most parameters in the [Link] file are static.

Spaces in values
If a parameter value contains spaces, enclose the parameter values within double quotes.

AdminHost
Specifies the computer name or IP address of the Admin Host on which an Admin Server is running.
Parameter type: required, static
To specify multiple Admin Hosts, separate each host name with a semicolon when running on Microsoft
Windows or with a colon when running on a UNIX. For example:
• Use the format AdminHost=hostname1;hostname2 on a Windows IBM TM1 Server.

336 IBM Planning Analytics: Installation and Configuration

• Use the format AdminHost=hostname1:hostname2 on a UNIX IBM TM1 Server.
Some other examples include:
• AdminHost=boston;newyork
• AdminHost=[Link];[Link]
• AdminHost=boston;[Link];[Link];myserver;[Link]
Note : The string specifying the admin host or hosts is limited to 1020 characters or bytes.

AllowReadOnlyChoreReschedule
Provides users with READ access to a chore, and the ability to activate, deactivate, and reschedule chores.
Parameter type: optional, static
When the line AllowReadOnlyChoreReschedule=T is added to the [Link] file for a server, users with
READ access to a chore can right-click a chore in Server Explorer, and toggle the Activate Schedule option
or choose the Edit Chore option. The Edit Chore option is available only when a chore is not activated.
When a user with READ access to a chore selects the Edit Chore option, only the scheduling screen of the
Chore Setup Wizard opens.
The scheduling screen lets the user set scheduling parameters for the chore, but does not allow the user
to edit the list of processes that compose the chore.

AllowSeparateNandCRules
When enabled, this parameter lets you specify rule expressions for N: and C: levels on separate lines
using identical AREA definitions.
Parameter type: optional, static
For example,

['Budget','Argentina']=N:Expression;

['Budget','Argentina']=C:Expression;

are both valid rules statements when you include the AllowSeparateNandCRules parameter in the
[Link] file and set to T.
This parameter also effects how numeric and string rules are applied to cells. Without this parameter, the
first rule statement that is encountered for a given AREA definition is applied to the cells within the scope
of that definition. If any cell within the AREA definition is numeric and the rule is a string rule, then the cell
is considered not rule-derived because there was a match that did not apply to the cell.
For example, consider the statements:

['1 Quarter']=s:'str_value';Not following.

['1 Quarter']=n:77;

If the AllowSeparateNandCRules parameter is not set (or is set to F), then the first rule statement will
match any cell that uses '1 Quarter' as one of its elements. If the cell is a string cell, the value of the cell
will be set to 'str_value'. If the cell is a numeric cell, the cell will not be considered rule derived, since a
match was found (the first rule) but the rule itself did not apply.
If the AllowSeparateNandCRules parameter is set to T, then string cells which use '1 Quarter' will be set
to 'str_value' and numeric cells which use '1 Quarter' will be set to 77.
To set the parameter to T, add the following line to [Link]:

AllowSeparateNandCRules=T

Chapter 16. Configuring and maintaining Planning Analytics Local 337

 AllRuleCalcStargateOptimization
The AllRuleCalcStargateOptimization parameter can improve performance in calculating views that
contain only rule-calculated values.
Parameter type: optional, static
Typically, TM1 performs calculations for standard consolidations and then calculates values for rule-
based consolidations, which may end up overriding values in the standard consolidations. The
AllRuleCalcStargateOptimization parameter provides optimization that first checks if every value in the
view is rule-calculated and then proceeds as follows:
• If every value in the view is rule-calculated, then TM1 skips the unnecessary calculations for standard
consolidations and just performs the rule-calculated consolidations.
• If the view contains even a single value which is not rule-calculated, then this optimization parameter
will have no effect.
When this parameter is set to True, some additional processing will take place for every view that is
requested to first check if the view contains only rule-calculated values. For most views, this additional
processing is minimal since the optimization is stopped after the first value in the view is found to be not
rule-calculated.
To enable this parameter, set the parameter's value to T in the TM1 server configuration file, [Link], as
follows:

AllRuleCalcStargateOptimization=T

The default setting is disabled (F).

ApplyMaximumViewSizeToEntireTransaction
Applies MaximumViewSize to the entire transaction instead of to individual calculations.
Parameter type: optional, dynamic
By default MaximumViewSize checks individual view processing. For example, if 10 views are processed
in a single transaction, the threshold is crossed only if the processing of any single view crosses the
threshold. See “MaximumViewSize ” on page 364.
With this parameter set to True, the cumulative memory usage of all views processed in a single
transaction is compared against the threshold value. This allows the memory size threshold to catch more
transactions that consume large amounts of memory.
Note : TI process execution counts as a single transaction, including all child TI processes.

ApplyMaximumViewSizeToEntireTransaction=T

Default value is F.

AuditLogMaxFileSize
Indicates the maximum file size that an audit log file can grow to before it is closed and a new file is
created.
Parameter type: optional, dynamic
This value must include units of KB (kilobytes), MB (megabytes), or GB (gigabytes). For example, to limit
the log file size to 100 MB, enter the following:
AuditLogMaxFileSize=100 MB
The range of values include:
• Default value: 100 MB
• Minimum value: 1 KB

338 IBM Planning Analytics: Installation and Configuration

• Maximum value: 2 GB

AuditLogMaxQueryMemory
Indicates the maximum amount of memory that IBM TM1 Server can use when running an audit log query
and retrieving the set of results.
Parameter type: optional, dynamic
This value must include units of KB (kilobytes), MB (megabytes), or GB (gigabytes). For example:
AuditLogMaxQueryMemory=100 MB
The range of values include:
• Default value: 100 MB
• Minimum value: 1 KB
• Maximum value: 2 GB

AuditLogOn
Turns audit logging on (T) or off (F).
Parameter type: optional, dynamic
For example:
• To enable audit logging, set AuditLogOn=T
• To disable audit logging, set AuditLogOn=F
The default setting is F.

AuditLogUpdateInterval
Indicates the maximum amount of time, in minutes, that IBM TM1 Server waits before moving the events
from the temporary audit file into the final audit log.
Parameter type: optional, dynamic
For example:
AuditLogUpdateInterval=60
The default value is 60 (sixty minutes).
The minimum value is 1 (one minute).
Note : You can manually update the audit log with the latest events anytime you want by using the
Process Audit Log Events command in Server Explorer. For details, see "Updating the Audit Log with the
Latest Events" in TM1 Operations.

AutomaticallyAddCubeDependencies
Determines if cube dependencies are set automatically or if you must manually identify the cube
dependencies for each cube.
Parameter type: optional, static
The IBM Cognos TM1 server establishes dependencies so it can properly invalidate cube calculation
caches when data in cubes is changed. For more details, see "Understanding Cube Dependency" in TM1
Operations.
When set to true (the default), rule-based inter-cube DB(…) dependencies are detected and set
automatically at server startup time. Further, after a rule edit, save, or recompile, the dependencies
expressed in that rule, whether from DB(), ATTRS(), or ATTRN() functions, are automatically re-
established.

Chapter 16. Configuring and maintaining Planning Analytics Local 339

 When set to false, rule based inter-cube DB(…) dependencies are not detected and are set at server
startup time. Dependencies are established when a query is run. This can cause a query to block others
because of a new dependency.

AutomaticallyAddCubeDependencies=F

Default value: T

CacheFriendlyMalloc
Allows for memory alignment that is specific to the IBM Power Platform.
Parameter type: optional, static
Testing has shown that enabling this parameter provides the most benefit for high user count usage
scenarios. Single or low user count usage scenarios may see little to no benefit. By default,
CacheFriendlyMalloc=F.
To enable the option, add the following line to your [Link] file:

CacheFriendlyMalloc=T

CalculationThresholdForStorage
Defines a minimum number of rule calculations required for a single cell or Stargate view, beyond which
the IBM TM1 Server stores the calculations for use during the current server session.
Parameter type: optional, dynamic
For example, when a user requests rule-derived values from the IBM TM1 Server, either from a single cell
or a Stargate view, the server usually has to perform multiple rule calculations to arrive at the requested
rule-derived values.
CalculationThresholdForStorage has a direct effect on memory consumption and performance. A high
parameter value results in decreased memory consumption and slower performance. A low parameter
value results in increased memory consumption and faster performance.
If you do not include CalculationThresholdForStorage in [Link], the default calculation threshold is 50.

CAMPortalVariableFile
The path to the variables_TM1.xml file in your IBM Cognos installation.
Parameter type: Required for IBM Cognos interoperability, static.
The CAMPortalVariableField parameter is required only when using IBM Cognos Analytics with Cognos
TM1 Web and the Cognos TM1 Server.
Set this parameter with a relative path as follows:
CAMPortalVariableFile=portal\variables_TM1.xml
Note : The exact file location on the IBM Cognos Analytics server is: Cognos_location\templates\ps
\portal\variables_TM1.xml.

CAMUseSSL
Specifies that all communications between TM1 and the IBM Cognos Analytics server must use SSL.
Parameter type: optional, static
Default value: False

CheckFeedersMaximumCells
Limits the number of cells checked by the Check Feeders option in the Cube Viewer.

340 IBM Planning Analytics: Installation and Configuration

The CheckFeedersMaximumCells is an optional parameter that you can add to [Link]. If you do not
include this parameter in [Link], Check Feeders checks 3,000,000 cells, by default.
Parameter type: optional, dynamic
When TM1 Server checks feeders from a highly consolidated cell, it must check all intersections that
apply to the cell. In large applications, the TM1 Server will be unavailable for a significant amount of time
while TM1 Server is checking all intersections.
To limit the number of cells checked when using Check Feeders (which in turn limits the amount of time
the TM1 Server is unavailable), add CheckFeedersMaximumCells to [Link] and set the parameter to
the number of cells you want to check.
For example, to limit Check Feeders to 1,000,000 cells, enter the following line:
CheckFeedersMaximumCells=1,000,000

ClientCAMURI
The URI for the IBM Cognos Server IBM Cognos Connection used to authenticate TM1 clients.
Parameter type: optional, dynamic
The URI is specified in the form http[s]://<host>/<cognos_location>/cgi-bin/[Link].
For example, [Link]

ClientExportSSLSvrCert
Specifies whether an IBM Cognos TM1 client should retrieve the certificate authority certificate, which
was originally used to issue the TM1 server's certificate, from the Microsoft Windows certificate store.
Parameter type: optional (required for SSL), static
If ClientExportSSLSvrCert=T, the certificate authority certificate is exported from the certificate
store on the client computer when requested by the TM1 client.
Default value: F

ClientExportSSLSvrKeyID
Specifies the identity key used by an IBM Cognos TM1 client to export the certificate authority certificate,
which was originally used to issue the TM1 server's certificate, from the Microsoft Windows certificate
store.
Parameter type: optional (required for SSL), static

ClientMessagePortNumber
Identifies a secondary port used to accept client messages concerning the progress and ultimate
cancellation of a lengthy operation without tying up thread reserves.
Parameter type: optional, static for changes, dynamically set
If no port number is specified in the configuration file, the port number is dynamically chosen and set at
server startup. However, it cannot be changed while the server is running.
This additional port ensures that other server requests can continue to process while waiting for a
cancellation from the user.
By default, this port number is automatically and dynamically assigned when the IBM TM1 Server starts.
You do not have to set ClientMessagePortNumber to a specific number unless firewalls or other network
issues require the listener port to be a well-known number.
CAUTION : If you choose to set a specific value for the ClientMessagePortNumber parameter,
instead of having it dynamically assigned, be sure to assign unique port numbers for all the TM1

Chapter 16. Configuring and maintaining Planning Analytics Local 341

 Server and client message ports you are using. If you have two servers running on the same
machine using the same port number, the message activity may cause a system conflict or hang.
See also, “PortNumber” on page 373 and “ProgressMessage” on page 374.

ClientPingCAMPassport
Indicates the interval, in seconds, that a client should ping the Cognos Authentication Management server
to keep their passport alive.
Parameter type: optional, dynamic
If an error occurs or the passport expires the user will be disconnected from the IBM TM1 Server.
Default value: 900

ClientPropertiesSyncInterval
Specifies the frequency (in seconds) at which client properties are updated in the }ClientProperties
control cube. Set to 1800 seconds to update cube every 30 minutes.
Frequent updating can cause unnecessary consumption of CPU time and may cause users from
connecting/disconnecting until operation completes.
Parameter type: optional, dynamic

ClientVersionMaximum
Specifies the maximum client version that can connect to the IBM TM1 Server.
Parameter type: optional, dynamic
The ClientVersionMaximum parameter value is expressed as a version string using the following format:
[Link]
m = major release number,
n = minor release number
t = maintenance release number
ff = fix pack number
hh = hot fix number
Using this format, setting ClientVersionMaximum = 9.4.10305 specifies that the maximum client
version that can connect to the server is 9.4.1.
If your [Link] file does not include a ClientVersionPrecision parameter value, only the major release
number, minor release number, and maintenance release number are used to enforce compatability
between client and server. Using the above example,
If ClientVersionMaximum is not explicitly set, the default value is equal to the currently installed server
version.
Valid parameter values fall within the range x00 up to the currently installed server version, where x is the
major release number of the currently installed TM1 Server. For example, valid parameter values for TM1
Server 9.0 SP3 fall within the range 900 - 903.
You cannot set ClientVersionMaximum to a value greater than the currently installed server version. You
cannot connect newer client versions to older server versions.

ClientVersionMinimum
Specifies the minimum client version that can connect to the IBM TM1 Server.
Parameter type: optional, dynamic

342 IBM Planning Analytics: Installation and Configuration

The ClientVersionMinimum parameter value is expressed as a version string using the following format:
[Link]
m = major release number,
n = minor release number
t = maintenance release number
ff = fix pack number
hh = hot fix number
Using this format, setting ClientVersionMinimum = 9.4.10305 specifies that the minimum client
version that can connect to the server is 9.4.1.
If your [Link] file does not include a ClientVersionPrecision parameter value, only the major release
number, minor release number, and maintenance release number are used to enforce compatability
between client and server.
If the ClientVersionMinimum parameter is not explicitly set, the default value is 8.4.00000, which
corresponds to version 8.4.
You should not set ClientVersionMinimum to a value lower than the major release number of the currently
installed TM1 Server. There is no upper limit for ClientVersionMinimum. However, if
ClientVersionMinimum is larger than ClientVersionMaximum, only clients with a version number equal to
ClientVersionMaximum can connect to the server.

ClientVersionPrecision
This parameter lets you more precisely identify the minimum and maximum versions of clients that can
connect to the IBM TM1 Server.
Parameter type: optional, dynamic
The ClientVersionMinimum and ClientVersionMaximum parameter values are expressed as a version
string using the following format:
[Link]
m = major release number,
n = minor release number
t = maintenance release number
ff = fix pack number
hh = hot fix number
Using this format, the version string 9.4.10305 indicates major release 9, minor release 4, maintenance
release 1, fix pack 3, and hot fix 5.
If ClientVersionPrecision is not set in [Link] or if it is set to 0, only the major release number, minor
release number, and maintenance release number are used to enforce compatability between client and
server. In this case, any client from major release 9, minor release 4, maintenance release 1 and more
recent can connect to the server.
You can enforce more precise server and client version compatability by adding ClientVersionPrecision to
the [Link] file and setting the parameter to one of the following values.
• 1 - Indicates that the fix pack number will be enforced, but not the hot fix number.
• 2 - Indicates that both the fix pack number and hot fix number will be enforced.

Chapter 16. Configuring and maintaining Planning Analytics Local 343

 Examples
If ClientVersionMinumum = 9.4.10305 and ClientVersionPrecision = 1, only clients from major release 9,
minor release 4, maintenance pack 1, fix pack 3 or later can connect to the server. In this case, the hot fix
number is not enforced when determining server/client compatability.
If ClientVersionMinumum = 9.4.10305 and ClientVersionPrecision = 2, only clients from major release 9,
minor release 4, maintenance pack 1, fix pack 3, hot fix 5 or later can connect to the server. In this case,
both the fix pack and hot fix numbers are enforced when determining server/client compatability.

[Link]
When possible, replaces aggregation over a member set with a reference to an ancestor, if the aggregated
member set comprises a complete set of descendants and all members have the weight 1.
For example, the aggregation aggregate(children(<Member>)) might be replaced with a reference
to <Member>.
Parameter type: optional, static
This parameter is applicable only when using TM1 with IBM Cognos Analytics.
To enable [Link], add the following line to the [Link] file:

[Link]=true

Default value: false

[Link]
Allows the IBM Cognos MDX engine to modify TM1 consolidation and calculation cell cache strategies.
Parameter type: optional, static
This parameter is applicable only when using TM1 with Cognos Analytics.
Default value: true

[Link]
Expands the data source provider cross join approach to nested filtered sets.
Parameter type: optional, static
This parameter is applicable only when using TM1 with IBM Cognos Analytics.
This parameter is active only in the following cases: ·
• [Link] has a value greater than 0 in the [Link] file
• UseProviderCrossJoinThreshold has a value greater than 0 in the Cognos Analytics
qfs_config.xml configuration file.
To enable [Link], add the following line to [Link] file:

[Link]=true

Default value: false

[Link]
Applies IBM Cognos MDX engine consolidation and calculation cell cache strategies to all cells in query
results.
Parameter type: optional, static
This parameter is applicable only when using TM1 with Cognos Analytics.

344 IBM Planning Analytics: Installation and Configuration

When [Link] is not enabled, consolidation and calculation cell cache
strategies are applied only to query result cells associated with calculated members.
Default value: true

[Link]
Applies the data source provider cross join strategy, even if it is not explicitly enabled in IBM Cognos
Analytics.
Parameter type: optional, static
This parameter is applicable only when using TM1 with Cognos Analytics.
When you enable [Link], this has the same effect as
enabling the UseProviderCrossJoinThreshold parameter in the qfs_config.xml file of Cognos
Analytics.
UseProviderCrossJoinThreshold controls whether combinations of members on an edge, which
have no measure values, are retrieved from the TM1 server. UseProviderCrossJoinThreshold is
enabled when it has a value greater than 0.
Note : If UseProviderCrossJoinThreshold is enabled in the Cognos Analytics qfs_config.xml, it
takes precedence over the [Link] parameter in the
[Link] file.
To enable [Link], add it to the [Link] file and specify a
value greater than 0, for example:

[Link]=1000

Default value: 0

CognosTM1InterfacePath
Specifies the location of the IBM Cognos Analytics server to use when importing data from a Cognos
Package to Cognos TM1 using the Cognos TM1 Package Connector.
See the TM1 TurboIntegrator guide for more information.
Parameter type: optional except when using the Cognos TM1 Package Connector, static

CreateNewCAMClients
The CreateNewCAMClients server configuration parameter determines how the TM1 server handles an
attempt to log on to the server with CAM credentials in the absence of a corresponding TM1 client.
Parameter type: optional, dynamic
When CreateNewCAMClients=T and a logon is attempted with a valid set of CAM credentials, but a
corresponding TM1 client does not exist, the TM1 client is created during the logon. This is the default
behavior when CreateNewCAMClients is not set in the [Link] file.
When CreateNewCAMClients=F and a logon is attempted with a valid set of CAM credentials, but a
corresponding TM1 client does not exist, the TM1 client is not created and the logon is rejected.
Through the C API, the error code is SystemServerClientNotFound. Through the HTTP endpoint, a 401
Unauthorized error is returned, with authentication information dependent on server configuration
settings. Additionally, when the logon is rejected a log message is printed to the
[Link] logger at the WARN level, if this level of logging is enabled. The log message
includes the text "CAM Client not found, and not created due to CreateNewCAMClients config setting."

DataBaseDirectory
Specifies the data directory from which the server loads cubes, dimensions, and other objects.

Chapter 16. Configuring and maintaining Planning Analytics Local 345

 You can list multiple data directories by separating them with semicolons.
Parameter type: required, static
For details, see “Data directory overview” on page 66.

DefaultMeasuresDimension
Identifies if a measures dimension is created. IBM TM1 Server does not require that a measures
dimension be defined for a cube. You can optionally define a measures dimension by modifying the cube
properties.
For more information, see the topic, "}CubeProperties", in TM1 Operations.
Parameter type: optional but some OLAP applications may require this parameter (see description below
for details),static
Some OLAP applications do require that a measures dimension be present in all cubes, and may fail if
such a dimension is not present. To accommodate these applications, set
DefaultMeasureDimension=T to instruct the TM1 Server to automatically define the last dimension in
a cube as the measures dimension when a new cube is created on the TM1 Server.
If DefaultMeasureDimension is set to F or is omitted from [Link], a measures dimension is not defined
for when a cube is created.

DisableMemoryCache
Disables the memory cache used by IBM Cognos TM1 memory manager.
Parameter type: optional, static
Enable this parameter only to debug memory leaks. When you enable this parameter, there might be a
decrease in server performance.
For example, when DisableMemoryCache=T is set it disables the memory cache used by IBM Cognos
TM1 memory manager. The default setting is DisableMemoryCache=F.

DisableSandboxing
Determines if users have the ability to use sandboxes across the server.
Parameter type: optional, dynamic
By default, this parameter is not present in the configuration file which enables the sandbox capability for
all users.

DisableSandboxing=F

When sandboxing is turned on in this way, administrators can Deny or Grant the use of Personal
Workspaces or multiple sandboxes on a per usergroup basis using Capability Assignments. For more
details, see "Capability Assignments" in TM1 Operations.
To put all usergroups into Direct Writeback mode, add the following line to [Link]:

DisableSandboxing=T

When DisableSandboxing=T, the Capability Assignments are ignored.

Important : Do not use DisableSandboxing=T in the TM1 Server configuration file for any TM1 Server
that deploys and supports TM1 Applications. TM1 Servers that deploy and support TM1 Applications
require that the sandbox feature is enabled in the TM1 Server configuration file.

Display_Info_DBType_R8
Display_Info_DBType_R8 instructs the IBM TM1 Server to store DISPLAY_INFO column data as
DBTYPE_R8.

346 IBM Planning Analytics: Installation and Configuration

Parameter type: optional, static
Important : Contact customer support to determine if this parameter is applicable to your TM1 Server.
By default, TM1 Server stores the DISPLAY_INFO as DBTYPE_UI4. When the TM1 Server OLE DB provider
processes a request from ADO 2.7 for the DISPLAY_INFO column data, the provider has to convert
column data from DBTYPE_UI4 to a DBTYPE_R8. The TM1 Server OLE DB provider then returns the
converted column data to the OLE DB client (ADO in this case).
ADO 2.7 expects IRowset::GetData to return an integer, and uses only the first 4 bytes of the converted
column data. However, the returned data is an 8-byte real number, and as a result, all information in the
last 4 bytes is lost. This causes ADO 2.7 to return zeroes for all the items of the DISPLAY_INFO column.
When you include the Display_Info_DBType_R8 parameter in the [Link] file and set the parameter to T,
the TM1 Server stores DISPLAY_INFO column data as DBTYPE_R8 with the relevant 4 bytes of
information in the first 4 bytes. The Display_Info_DBType_R8 parameter ensures that the information is
not lost when ADO converts the data back to an integer of 4 bytes. The parameter also ensures that ADO
2.7 returns the correct values for the properties of an axis rowset member. Additionally, the parameter
ensures that any OLE DB client (such as ADO 2.6) requesting the DISPLAY_INFO property as a 4 byte
value, gets the correct values.

DownTime
Specifies a time when the server will come down automatically.
Parameter type: optional, dynamic
The format of the DownTime parameter is dd:hh:mm where:
• dd is the number of days from today. (For example, 00 is today, and 01 is tomorrow.)
• hhmm is the time of day in 24-hour format.
For example, DownTime = 01:03:30 specifies that you want to bring the server down on the following
day at 3:30 in the morning.
The DownTime parameter is not available when you run the IBM TM1 Server as a Windows service.
When you use the DownTime parameter on a TM1 Server on UNIX, you must set the
RunningInBackground parameter to T. If RunningInBackground=F, the server prompts for confirmation
before shutting down and cannot shut down without manual confirmation from an administrator.

EnableNewHierarchyCreation
Specifies whether multiple hierarchy creation is enabled or disabled.
Parameter type: optional (required for multiple hierarchies), static
By default, the EnableNewHierarchyCreation parameter is set to F (false). If you are working with
multiple hierarchies, change the parameter setting to T (true). TM1 Reference lists the TurboIntegrator
functions to manage dimensions and equivalent functions to manage specific hierarchies within
dimensions.

EnableSandboxDimension
Specifies whether the virtual sandbox dimension feature is enabled.
Parameter type: optional, dynamic
By default, the EnableSandboxDimension parameter is set to False.
A sandbox property (IncludeInSandboxDimension) was introduced to specify whether a sandbox is
included in the virtual sandbox dimension. For older sandboxes, the value of the
IncludeInSandboxDimension property is false. Including sandboxes in the virtual sandbox dimension
allows users to compare multiple sandbox scenarios in a single view. For more information, see
IncludeInSandboxDimension in the Sandbox entity in the TM1 REST API documentation on IBM
Knowledge Center.

Chapter 16. Configuring and maintaining Planning Analytics Local 347

 EnableTIDebugging
Specifies whether TurboIntegrator debugging capabilities are enabled or disabled.
Parameter type: optional, dynamic
By default, the EnableTIDebugging parameter is set to F (false).
If you want to use any of the TurboIntegrator process debugging capabilities of the TM1 REST API, you
must change the parameter setting to T (true). Similarly, you must set the parameter to T if you want to
use the TurboIntegrator Debugger utility, which is currently available in preview release on IBM
developerWorks.
Important : Debugging TurboIntegrator processes can consume significant system resources. It is
recommended that you set EnableTIDebugging=T only while debugging processes in a development
environment and that the parameter not be enabled in a production environment.

EventLogging
Indicates whether the event logger is turned on.
Critical events are logged in the event log file. The file is expected to be consumed by third-party tools.
Parameter type: optional, dynamic
Default: T
If the EventLogging parameter is set to F, then the event log file is not written to.
To set the parameter to T, add the following line to [Link]:

EventLogging=T

EventScanFrequency
Specifies the period to check the collection of threads, where 1 is the minimum number and 0 disables
the scan.
Parameter type: optional, dynamic
Default: 1(s)
To disable event scanning, add the following line to [Link]:

EventScanFrequency=0

[Link]
Specifies the threshold for which a message is printed for the event that the server's pooled memory
exceeds a certain value.
Parameter type: optional, dynamic
The memory footprint of every model is different. This parameter is set to 0 (disabled) by default and
must be adjusted by the administrator of the TM1 server.
Default: 0
To enable the threshold, add the following line to [Link]:

[Link]=0

[Link]
Indicates that a warning is printed when a thread blocks at least the specified number of threads.
Parameter type: optional, dynamic

348 IBM Planning Analytics: Installation and Configuration

Default: 5
To set the number of threads, add the following line to [Link]:

[Link]=5

[Link]
Indicates that a warning is printed when a thread has been running for the specified length of time.
Parameter type: optional, dynamic
Default: 600 (s)
To set the number of threads, add the following line to [Link]:

[Link]=600

[Link]
Indicates that a warning is printed when a thread has been blocked by another thread for the specified
length of time.
Parameter type: optional, dynamic
Default: 20 (s)
To set the waiting time, add the following line to [Link]:

[Link]=20

ExcelWebPublishEnabled
Enables the publication of Microsoft Excel files to IBM Cognos TM1 Web, as well as the export of Microsoft
Excel files from TM1 Web, when Microsoft Excel is not installed on the web server. Enable the
ExcelWebPublishEnabled parameter when you have TM1 10.1 clients that connect to TM1 10.2.2 servers.
Parameter type: optional, dynamic
If ExcelWebPublishEnabled=T, Microsoft Excel files in Cognos TM1 Applications can be published to
TM1 Web without using Microsoft Excel on the web server. Similarly, Websheets and Cube View can be
exported from TM1 Web without using Microsoft Excel on the web server.
When Microsoft Excel is not available on the web server, Microsoft Excel files in TM1 Applications must be
explicitly published to TM1 Web.
For details about the procedure required to publish Microsoft Excel files, see TM1 Developer.
For details about limitations exporting from TM1 Web without using Microsoft Excel on the web server,
see TM1 Perspectives, TM1 Architect, and TM1 Web.
Restriction : You cannot publish Microsoft Excel 2007 .xlsx files to TM1 Web when Microsoft Excel is not
available on the web server. These files must be saved in Microsoft Excel 2003 .xls format if you want to
publish them to TM1 Web.
Default value: F

[Link]
Specifies the number of retry attempts.
Parameter type: optional, dynamic
By default, TM1 server will shutdown when transaction log updates fail. Specifying
[Link] defers the server shutdown while the server attempts to reestablish a

Chapter 16. Configuring and maintaining Planning Analytics Local 349

 connection. [Link] defines the number of retry attempts as an integer value. If the network
failure persists after the specified number of retries, TM1 server will self-terminate.
Default value: 5

[Link]
Specifies the time delay between retry attempts.
Parameter type: optional, dynamic
By default, TM1 server will shutdown when transaction log updates fail. Specifying
[Link] defers the server shutdown while the server attempts to reestablish a
connection. [Link] defines the delay (in milliseconds) between retry attempts. If the
network failure persists after the specified number of retries, TM1 server will self-terminate.
Default value: 2000

[Link]
Network issues can cause transaction log updates to fail, which might force a TM1 server shutdown. This
configuration parameter specifies the directory paths of the affected log files.
Parameter type: optional, dynamic
By default, TM1 server shuts down when transaction log updates fail. Specifying [Link]
defers the server shutdown while the server attempts to reestablish a connection.
The number of retry attempts and delay between attempts is determined by [Link] and
[Link], respectively. If the network failure persists after the specified number of retries,
TM1 server will self-terminate.
As of IBM Planning Analytics Local version 2.0.3, if this setting is not specified in the [Link] file
(default), the retry logic is applied to all files in the logs directory only.
To turn off the retry logic, specify one of the following options in the [Link] file:
• [Link]="" (explicitly setting the value to the empty value)
• [Link]=0
Use a semi-colon delimiter to specify multiple paths. For example,
1. [Link]=c:\production\model\Logs
On a write failure, the retry logic is applied to all files in the "c:\production\model\Logs" directory and
below.
2. [Link]=c:\production\model\Logs;\\[Link]\production\Logs
On a write failure, the retry logic is applied to all files in the "c:\production\model\Logs" directory and
the network share of \\[Link]\production\Logs and below.
Note : Messages are written to the server log at the WARN level when this logic is enabled.
• "Error writing to <FILENAME>, retry in progress." is written when a write operation fails and a retry
attempt is in progress.
• "Error writing to <FILENAME>, retry attempt failed." is written when the retry attempt fails.

FIPSOperationMode
Controls the level of support for Federal Information Processing Standards (FIPS).
Parameter type: optional, static
Allowed values:
• 1: FIPS 140-2 level 1 approved ciphers and operation
• 2: FIPS 140-2 level 1 approved ciphers

350 IBM Planning Analytics: Installation and Configuration

• 3: Disabled
Default value: 2
To change the level of support for FIPS to level 1 approved ciphers and operations, for example, add the
following line to the [Link] file:

FIPSOperationMode=1

ForceReevaluationOfFeedersForFedCellsOnDataChange
When this parameter is set, a feeder statement is forced to be re-evaluated when data changes.
Parameter type: optional, static
When the IBM Cognos TM1 server computes feeders, the process can be a "chain" of feeders, where cell
A feeds cell B, and there is a feeder rule for cell B, so that rule runs and feeds cell C, etc. Feeders for
numeric cells are evaluated only when a cell goes from empty to some non-zero value since any non-zero
value in the cell would already have set any feeders.
There is no need to re-evaluate the feeders when a cell changes from one non-zero value to another.
Normally, when evaluating feeders, if a feeder rule is evaluated and the target cell is already fed, the
feeding process stops.
Feeder rules are not processed any further since the presence of the feeder in the target cell indicates
that the feeder rules for the target cell have already been run, and there is no need to run them again.
Consider the following feeder rules:

['A']=>['B'];

The feeder rule for cell B depends on some cube data value:

[B]=>DB(cube-name,!dim1,DB(cube2-name,…),!dim2);['C']=>['D'];['X']=>['B'];

When the feeder rule for B is initially evaluated, the DB(cube2-name,…) is evaluated to produce an
element name, such as C. Therefore B feeds C and then C feeds D. When that cell X goes from zero to non-
zero, this change also feeds B. But B is already fed, so the feeding process stops, and the feeder rule for B
never evaluates, so any "change" in the output of the rule, which may come about because of an
underlying data change targeted by the DB(…) statement will not be evaluated. If the parameter
ForceReevaluationOfFeedersForFedCellsOnDataChange is set, then the presence of a feeder in
cell B will not terminate feeder processing. Rather, the feeder rule for B will run. Because the feeder rule
for B is data dependent, the target for the feeder may be the former C, or may be some other cell, and that
cell will be fed. Note that setting this parameter will force more feeder evaluations, which may have a
performance impact.
To turn on this parameter set ForceReevaluationOfFeedersForFedCellsOnDataChange=T.

HTTPPortNumber
Sets the port number on which the TM1 Server listens for incoming HTTP(S) requests.
Parameter type: required, static
The IBM Planning Analytics TM1 Server services the REST API using this HTTP(S) channel. The server
accepts either standard HTTP or SSL secured HTTPS connections depending on the UseSSL parameter
(see “UseSSL” on page 387). If UseSSL is set to T, switching the use of SSL on, then the server will accept
only HTTPS connections. If UseSSL is set to F, the server will accept unsecured, HTTP connections.
If HTTPPortNumber is not defined in your [Link] file, then port number "5001" will be assigned
automatically.
Note : Port numbers must be unique across all services running on a computer, not just across TM1
servers and not just across the HTTP ports of TM1 servers.

Chapter 16. Configuring and maintaining Planning Analytics Local 351

 HTTPSessionTimeoutMinutes
Sets the timeout value for authentication sessions for the TM1 REST API.
Parameter type: optional, dynamic
When you use the TM1 REST API, your application needs to authenticate with the TM1 Server. This
parameter sets the timeout, in minutes, for this authentication. If a session times out, requests made with
the old session ID return 401 Unauthorized.
The default value is 20.

IdleConnectionTimeOutSeconds
Specifies a timeout limit for idle client connections, in seconds.
Parameter type: optional, dynamic
For example, if you include the following line in [Link], the server disconnects idle client connections
after 900 seconds.

IdleConnectionTimeOutSeconds=900

IndexStoreDirectory
Added in v2.0.5 Designates a folder to store index files, including bookmark files.
Parameter type: optional, static
By default, this parameter is undefined and bookmark (*.bm) files will appear in the same folder as its
corresponding main file.

IntegratedSecurityMode
This parameter sets the user authentication mode to be used by the IBM TM1 Server.
Parameter type: optional, dynamic
Although the parameter name focuses on Integrated Security Mode, the security modes are used to set
other kinds of security.
Note : If you change the security mode without restarting the TM1 Server, the change applies only to new
client connections. If you want to ensure that all clients are authenticated with the new security mode, all
clients must be logged off by the administrator.
Use the following format to set this parameter:
IntegratedSecurityMode=x
where x can be a value for one of the following security modes.

Security Mode Description

1 The server uses secure mode (standard TM1 security).

With this authentication, the TM1 Server checks the user name and password
against the user names and passwords in the TM1 database.

2 This mode allows you to switch back and forth between integrated login and
native TM1 security.

352 IBM Planning Analytics: Installation and Configuration

Security Mode Description

3 The server uses Integrated Login.

Integrated Login uses Microsoft Windows network authentication to control
access to TM1 data.
If you use this security mode, you must also set the “SecurityPackageName” on
page 378 parameter.
For more details, see “Integrated login” on page 247.

4 The server uses IBM Cognos Analytics security authentication.

Considerations when using this mode:
In TM1 Server, Cognos Analytics users can belong only to Cognos Analytics
groups and any of these predefined TM1 administrator groups (ADMIN,
DataAdmin, SecurityAdmin, and OperationsAdmin). Membership in TM1 user
(non-administrator) groups is not supported for Cognos Analytics users when
they log in to TM1 Server.
You can not use TM1 Server to permanently assign a Cognos Analytics user to
another Cognos Analytics group. Any user assignment you make in TM1 Server
to a Cognos Analytics group is not saved back to Cognos Analytics. When a
Cognos Analytics user logs in to TM1 Server, the group assignments in Cognos
Analytics override any Cognos Analytics group assignments made in TM1
Server.

5 The server uses Cognos Analytics security authentication and supports user
groups from both TM1 Server and Cognos Analytics.
Use security mode 5 when you are running IBM Cognos TM1 Applications with
Cognos Analytics security.
Considerations when using this mode:
• In TM1 Server, Cognos Analytics users can belong to both Cognos Analytics
and TM1 groups.
• You can not use TM1 Server to permanently assign a Cognos Analytics user to
another Cognos Analytics group. Any user assignment you make in TM1 Server
to a Cognos Analytics group is not saved back to Cognos Analytics. When a
Cognos Analytics user logs in to TM1 Server, the group assignments in Cognos
Analytics override any Cognos Analytics group assignments made in TM1
Server.
• If IntegratedSecurityMode=5 is used for the TM1 Server and IBM Cognos TM1
Applications, it is not possible to assign rights to native TM1 groups within the
Manage rights dialog. Only Cognos Groups, imported into the TM1 Server, are
available.

IPAddressV4
This parameter lets you specify the IPv4 address for an individual IBM TM1 Server.
Parameter type: optional, static
A physical server/host can have one internal IP address for clients within a firewall and a different
external IP address for clients outside the firewall. By default, all TM1 client requests are routed through
the external (public) adapter, which would require updates to firewall profiles. By assigning the internal IP
address of TM1 Server to the IPAddressV4 parameter, traffic is routed through the private adapter and
firewall profiles do not require updates.

Chapter 16. Configuring and maintaining Planning Analytics Local 353

 For example:

IPAddressV4="[Link]"

Note : This parameter replaces the old IPAddress parameters, which is now obsolete.

IPAddressV6
This parameter lets you specify the IPv6 address for an individual IBM TM1 Server.
Parameter type: optional, static
A physical server/host can have one internal IP address for clients within a firewall and a different
external IP address for clients outside the firewall. By default, all TM1 client requests are routed through
the external (public) adapter, which would require updates to firewall profiles. By assigning the internal IP
address of TM1 Server to the IPAddressV6 parameter, traffic is routed through the private adapter and
firewall profiles do not require updates.
For example:

IPAddressV6="0ff1:aa00:4125:2:a05:f7b1:61c2:a341"

Note : This parameter replaces the old IPAddress parameters, which is now obsolete.

IPVersion
This parameter indicates the Internet protocol used by the IBM TM1 Server to identify IP addresses on
the network.
For example, to specify that your network uses the IPV6 protocol, add the parameter IPVersion=ipv6
to the [Link] file.
Parameter type: optional, static
Valid settings are:
• ipv4
Default setting. Used for IPv4 networks.
• dual
Used to transition from IPv4 to IPv6. Both protocols are supported.
• ipv6
Used for IPv6 networks.

Configuration notes
If you set this parameter to ipv6 or dual, use the Cognos Configuration tool to change the TM1 Admin
Server IP support option to reflect the change.
To allow clients to recognize this change, add and set the TM1_IPVersion environment variable in the
operating system to ipv6 or dual.
Setting this parameter to dual or IPV6 without having the appropriate network running can result in
performance degradation.
Note : In some cases, depending on your network environment and DNS configuration, you may need to
also add the IPv6 address to the /etc/hosts operating system file on UNIX and Microsoft Windows to
successfully run the Cognos TM1 Admin Server and Cognos TM1 Server in IPv6 mode.
For complete details on configuring all Cognos TM1 components to use IPv6, see “Configuring TM1 Server
to use IPv6” on page 101.

354 IBM Planning Analytics: Installation and Configuration

JavaClassPath
Use this parameter to make third-party Java libraries available to the IBM Cognos TM1 Server.
Parameter type: optional, static
For example, to allow a Java extension to use classes inside a file called [Link] file (a Db2 JDBC
driver), use the following:

JavaClassPath=C:\Development\Java\DB2JDBC\[Link]

You can specify multiple references by separating them with semicolons.

JavaJVMArgs
Specifies a list of arguments to pass to the Java Virtual Machine (JVM). Arguments are separated by a
space and the dash character. For example, JavaJVMArgs=-argument1=xxx -argument2=yyy.
Parameter type: optional, static
If you want to debug a process, you might specify these arguments:

JavaJVMArgs=-Xrunjdwp:transport=dt_socket -server=y -suspend=n -address=1044

The arguments you can use depend on the specific JVM you are using.

JavaJVMPath
This parameter sets the path to the Java Virtual Machine .dll file ([Link]), which is required to run Java
from IBM Cognos TM1 TurboIntegrator.
Parameter type: optional, static
By default, this parameter is not present in the [Link] file.
To enable Java integration with TurboIntegrator, add the following line to your [Link] file:
JavaJVMPath=<full_path_to_jvm.dll>

keyfile
Specifies the file path to the key database file. The key database file contains the server certificate and
trusted certificate authorities. The server certificate is used by the TM1 server and the TM1 Admin server.
Parameter type: optional, static
The key database file that is provided with TM1 is [installation_location]/ssl/[Link]
To specify a different key database file, add the keyfile parameter to the [Link] file and specify the
relative or absolute path to the .kdb file.
For example:

keyfile=./ssl/[Link]

keylabel
Specifies the label of the server certificate in the key database file.
Parameter type: optional, static
For example:

keylabel=TM1_Certificate

Chapter 16. Configuring and maintaining Planning Analytics Local 355

 keystashfile
Specifies the file path to the key database password file. The key database password file is the key store
that contains the password to the key database file.
Parameter type: optional, static
The key database password file that is provided with TM1 is [installation_location]/ssl/
[Link]
To specify a different key database password file, add the keystashfile parameter to the [Link] file
and specify the relative or absolute path to the .sth file.
For example:

keystashfile=./ssl/[Link]

Language
Sets the language used for the IBM TM1 Server. This parameter applies to messages generated by the
server and is also used in the user interface of the server dialog box when you run the server as an
application instead of a Windows service.
Parameter type: optional, static
Valid values currently are:

Language Code
Brazilian Portuguese bra
Croatian hrv
Czech csy
Chinese (Simplified) sch
Chinese (Traditional) tch
Danish dan
Dutch nld
German deu
Finnish fin
French fra
Hungarian hun
Italian ita
Japanese jpn
Kazakh kaz
Korean kor
Norwegian nor
Polish pol
Romanian rom
Russian rus
Spanish esp

356 IBM Planning Analytics: Installation and Configuration

Language Code
Slovenian slv
Swedish sve
Thai tha
Turkish trk

LDAPHost
Specifies the domain name or dotted string representation of the IP address of the LDAP server host.
Parameter type: optional, static
If you do not enter a value for LDAPHost, TM1 Server uses the default value, localhost.

LDAPPasswordFile
Defines the password file used when LDAPUseServerAccount is not used. This is the full path of the .dat
file that contains the encrypted password for the IBM TM1 Server Admin Server's private key.
Parameter type: optional unless “LDAPUseServerAccount” on page 358=F, static
This parameter uses the full path to a .dat file.

LDAPPasswordKeyFile
Defines the password key used when LDAPUseServerAccount is not used.
Parameter type: optional unless “LDAPUseServerAccount” on page 358=F, static
This parameter uses the full path of the .dat file that contains the key used to encrypt and decrypt the
password for the private key.
This file must be generated using the tm1crypt utility, as described in “Run the TM1Crypt utility” on page
310.

LDAPPort
Specifies the port IBM TM1 Server uses to bind to an LDAP server.
Parameter type: optional, static
Specify a secure (SSL) port, for example, 636.
Default value: 389 (an unsecured port)

LDAPSearchBase
Specifies the node in the LDAP tree where TM1 Server begins searching for valid users.
Parameter type: optional, static
A base distinguished name (DN) in the LDAP directory. For example:

ou=people,o=[Link]

For example, if the distinguished names are of the form:

uid-bjensen, ou-people, o=[Link]

Then the search base would be:

ou-people, o=[Link]

Chapter 16. Configuring and maintaining Planning Analytics Local 357

 LDAPSearchField
The name of the LDAP attribute that is expected to contain the name of the TM1 user being validated.
Parameter type: optional, static
If you do not enter an LDAPSearchField value, the default value is cn, which is also the default value for
Microsoft Active Directory.

LDAPSkipSSLCertVerification
Skips the certificate trust verification step for the SSL certificate used to authenticate to an LDAP server.
This parameter is applicable only when LDAPVerifyServerSSLCert=T.
Parameter type: optional, static
If trust verification does not work, you can skip the trust verification step by specifying
LDAPSkipSSLCertVerification=T. In this case, TM1 does not verify the server certificate at all but
simply accepts it.
Note : Before working with this parameter, you should be familiar with SSL and LDAP.
Default value: F

LDAPSkipSSLCRLVerification
Skips CRL checking for the SSL certificate used to authenticate to an LDAP server. This parameter is
applicable only when LDAPVerifyServerSSLCert=T.
Parameter type: optional, static
This parameter is not required if LDAPVerifyServerSSLCert=F. The Microsoft Windows API can tolerate an
empty or non-existent CRL certificate.
Note : Before working with this parameter, you should be familiar with SSL and LDAP.
Default value: F

LDAPUseServerAccount
Determines if a password is required to connect to the server when using LDAP authentication.
Parameter type: optional, static
• To connect directly to the LDAP server using integrated authentication, set this parameter to T. Set this
parameter to T whenever the IBM TM1 Server and LDAP server exist on the same domain.
• To use a password before connecting, set this parameter to F. When LDAPUseServerAccount is set to F,
you must also set the “LDAPPasswordFile” on page 357 and “LDAPPasswordKeyFile” on page 357 to
successfully connect to the LDAP server using SSL.

LDAPVerifyCertServerName
Specifies a server to use during the SSL certificate verification process for LDAP server authentication.
This parameter is applicable only when LDAPVerifyServerSSLCert=T.
Parameter type: optional, static
Note : Before working with this parameter, you should be familiar with SSL and LDAP.
Use this parameter to specify the servers TM1 should use to verify the received SSL certificate.
All of the server names you want to use for certificate verification must be listed in separate
LDAPVerifyCertServerName entries. The entries must exactly match the name (subject) of the certificate
presented to TM1 in the SSL handshake by the server on the other end.

358 IBM Planning Analytics: Installation and Configuration

Specify LDAPVerifyCertServerName in the [Link] file of each TM1 server that is using LDAP.

LDAPVerifyCertServerName=<server_cert_subject>

Replace server_cert_subject with a server name or IP addresses. Create an entry for each server
you want to use For example:

LDAPVerifyCertServerName=[Link]
LDAPVerifyCertServerName=[Link]

Default value: F

LDAPVerifyServerSSLCert
Delegates the verification of the SSL certificate to TM1. This parameter is useful, for example, when you
are using LDAP with a proxy server.
Parameter type: optional, static
Note : Before working with this parameter, you should be familiar with SSL and LDAP.
Typically, TM1 leverages the Microsoft Windows API to verify SSL certificates. For this process to succeed,
the certificate name and the LDAP server host name must match. If you are using a proxy, however, these
names may not match, causing the verification to fail. In this case, you can set
LDAPVerifyServerSSLCert=T to have TM1 perform the certificate verification.
When LDAPVerifyServerSSLCert=T, TM1 performs the two steps of verification (verifying the trust
relationship to the certificate and checking the CRL) like the Windows API would have done, but with a
slightly different approach.
1. Instead of verifying the received certificate against the configured host name, TM1 looks at the list of
server names specified by LDAPVerifyCertServerName.
2. If the certificate name matches one of the servers specified by LDAPVerifyCertServerName, TM1 calls
the Microsoft Windows API and requests it to verify this single certificate only.
Note : The correct trusted root certificate authority (CA) must already have been imported to the
Microsoft Windows Certificate Store.
You can skip the trust verification step by specifying LDAPSkipSSLCertVerification=T. In this case, TM1
does not verify the server certificate at all but simply accepts it.
3. Once the trust verification is confirmed (or skipped), TM1 calls the Microsoft Windows API to check the
CRL.
Note : The CRL certificate for the trusted root must already have been imported to the Microsoft
Windows Certificate Store.
If the CRL certificate does not exist in the Microsoft Windows Certificate Store, the process will fail.
You can skip the CRL step by specifying LDAPSkipSSLCRLVerification=T.
4. If all the previous steps finish successfully, the SSL handshake is complete. TM1 now attempts to
authenticate to the LDAP server.
For troubleshooting information, see “Troubleshooting LDAP authentication” on page 261.

LDAPWellKnownUserName
Specifies the user name used by the IBM TM1 Server to log in to LDAP and look up the name submitted by
the user.
Parameter type: optional unless “LDAPUseServerAccount” on page 358=F,, static
The value of this parameter can be any LDAP distinguished name.

Chapter 16. Configuring and maintaining Planning Analytics Local 359

 For example:

uid=bjensen,ou=people,o=[Link]

LoadPrivateSubsetsOnStartup
This configuration parameter determines if private subsets are loaded when the TM1 server starts.
Parameter type: optional, static
Lock contention issues can occur when private subsets are loaded on-demand (when a user requests the
subset). You can avoid lock contention by loading all private subsets from all users into memory upon
server startup, by adding

LoadPrivateSubsetsOnStartup=T

to the [Link] file for your server.

If LoadPrivateSubsetsOnStartup=F, or is not present in [Link], private subsets are loaded on-
demand.

LoadPublicViewsAndSubsetsAtStartup
Added in v2.0.8 This configuration parameter enables whether public subsets and views are loaded when
the TM1 Server starts and keeps them loaded to avoid lock contention during the first use.
Parameter type: optional, static
Default: LoadPublicViewsAndSubsetsAtStartup=T
If LoadPublicViewsAndSubsetsAtStartup=F, public views subsets are loaded on-demand for your
TM1 Server.
Lock contention issues can occur when public views and subsets are loaded on-demand (when a user
requests the subset). You can avoid lock contention on server startup by loading all public views and
subsets from all users into memory and keeping them loaded to avoid lock contention during the first use.
Add the following setting to the [Link] file for your TM1 Server.

LoadPublicViewsAndSubsetsAtStartup=T

LockPagesInMemory
When this parameter is enabled, memory pages used by the IBM TM1 Server process are held in memory
(locked) and do not page out to disk under any circumstances. This retains the pages in memory over an
idle period, making access to TM1 data faster after the idle period.
This parameter is applicable only to TM1® Servers running on a Microsoft® Windows 64-bit operating
system.
Parameter type: optional, static
If a TM1 Server running on a Windows 64-bit operating system is idle for a long period of time, physical
memory taken up by the TM1 Server will page out to disk. This is a function of the Windows 64-bit
operating system and not TM1 Server. This can cause performance degradation in large TM1 Server
databases when trying to access data after an idle period.
To maximize performance when running a largeTM1 Server database on 64-bit Windows, set
LockPagesInMemory=T in the [Link] file. If you change this parameter value, restart the TM1 Server
to apply the new value.
Note : This parameter has no effect on performance for an actively running TM1 system, in which TM1
data is regularly accessed.

360 IBM Planning Analytics: Installation and Configuration

When this parameter is enabled, Windows still trims pages from the TM1 Server process space, but does
not page them to disk. This benefits TM1 Server performance because objects are no longer placed in
virtual memory, but instead remain in physical RAM.
When LockPagesInMemory is not present in [Link], or if the parameter is set to F, the following
behavior is expected:
When a TM1 Server running on a Windows 64-bit operating system is idle for a period of time, physical
memory taken up by the TM1 Server is paged out to disk. This paging to disk happens even if there are no
other processes contending for the memory pages. Essentially, Windows leaves the memory pages vacant
and available. This is a function of the Windows 64-bit operating system and not TM1 Server.
This background paging by the Windows operating system can cause initial performance degradation in
large TM1 databases when trying to access TM1 data after an idle period. For example, when the TM1
system has been inactive overnight the first access in the morning will take longer, as the required
memory pages containing TM1 data are read from disk back into memory. Also, if the TM1 model is such
that there are large cube data areas that are accessed infrequently, the memory holding that cube
information may page out to disk. When a request is made for that cube data the request will take longer,
as these infrequently used pages must be read back into memory.
When LockPagesInMemory=T in [Link], the memory pages containing TM1 data are locked into
memory and are not available for use at any time by any other process. This can make the system overall
perform poorly if there are other tasks that need to run on the TM1 machine. For example, if the machine
has 48 GB of physical memory, and the TM1 server takes 38 GB to fully load, then there are only 10 GB of
physical memory to run any and all other processes, including system processes. These other processes
may perform poorly because they may force extensive paging activity as the system tries to run them all in
what would then essentially be a 10 GB machine. If a second TM1 server is started with the same
LockPagesInMemory=T configuration setting, and that second TM1 instance would normally take 12 GB
to load, the load will fail since that TM1 server can not lock 12 GB of memory, as there is only 10 GB
available.

LoggingDirectory
Specifies the directory to which the server saves its log files.
If you do not supply this parameter, the log files are saved to the first data directory specified by the
DataBaseDirectory parameter.
Parameter type: optional,static.
Note : The value of parameter LoggingDirectory must be encapsulated by quotes if it uses spaces, for
example LoggingDirectory=C:/Data Files/Logfiles. The IBM TM1 Server startup will fail if
quotes are not used in that case. Note also that other parameters, such as DataBaseDirectory, do not
necessarily require quotes when a value contains spaces.

LogReleaseLineCount
Sets the number of lines that a search of the Transaction Log will accumulate in a locked state before
releasing temporarily so that other Transaction Log activity can proceed.

Parameter type: optional, dynamic

Default value: 5000 lines

MagnitudeDifferenceToBeZero
Sets the order of magnitude of the numerator relative to the denominator, above which the denominator
equals zero when using a safe division operator.

Parameter type: optional, static

In rules and TurboIntegrator, there is a safe division operator (the backslash). With this, if you try to divide
by zero, the result is zero, not undefined. If the denominator to the division is a calculated quantity, the

Chapter 16. Configuring and maintaining Planning Analytics Local 361

 result can be very close to zero, but not exactly zero, for example, .0000000000000004. By setting the
MagnitudeDifferenceToBeZero parameter, you can specify how close a number can be to zero,
relative to the magnitude of the numerator, to be considered as zero for the safe division operator.
Consider this example:
• In the file [Link], set MagnitudeDifferenceToBeZero=14
• The operation is A \ B
Note : Backslash (\) is the safe division operator in TurboIntegrator.
• A = 1000 B = 1.5e-15
• B is 18 orders of magnitude less than A
• 18 > 14, therefore the save division operator returns B=0

MaskUserNameInServerTools
Determines whether usernames in server administration tools are masked until a user is explicitly verified
as having administrator access.
Parameter type: optional, static
When MaskUserNameInServerTools is set to TRUE, usernames are masked in server administration tools
until the user who is working in the administration tool is explicitly verified as an administrator. For
example, when MaskUserNameInServerTools is set to TRUE, usernames are masked in TM1Top.
When MaskUserNameInServerTools is set to FALSE, usernames are displayed in server administration
tools to all users regardless of administrator status.
Default value: true

MaximumCubeLoadThreads
Specifies whether the cube load and feeder calculation phases of server loading are multi-threaded, so
multiple processor cores can be used in parallel.
This results in decreased server load times.
Parameter type: optional, static
To run in multi-threaded mode, you must set MaximumCubeLoadThreads to the number of processor
cores on the Cognos TM1 server that you want to dedicate to cube loading and feeder processing.
Generally, the best performance is achieved when the parameter is set to a value equal to (number of
available processor cores) - 1. For example, if the Cognos TM1 server is running on a computer with four
processor cores, MaximumCubeLoadThreads must be set to 3. This ensures that one processor core is
available to run other applications while the Cognos TM1 server is loading.
Note :
The maximum value for MaximumCubeLoadThreads is 32.
When MaximumCubeLoadThreads is set to 0, cube loading and feeder processing are not multi-threaded.
This is the default behavior when MaximumCubeLoadThreads is not explicitly set in the [Link] file.

Conditional feeders
When MaximumCubeLoadThreads is enabled, Cognos TM1 cannot manage the order in which feeders
are calculated. There might be cases where processing order has an adverse effect on your application
due to some order-of-evaluation dependencies in the multi-threaded environment.
If your Cognos TM1 model uses conditional feeders where the condition clause contains a fed value, you
must disable the use of multiple threads at load time. Set MaximumCubeLoadThreads=0 or exclude the
parameter from the [Link] file.

362 IBM Planning Analytics: Installation and Configuration

MaximumLoginAttempts
Sets the maximum number of failed user login attempts permissible on the server.
If you do not include MaximumLoginAttempts in [Link], by default, the server allows three login
attempts.
Parameter type: optional, dynamic
For example, if you add the line MaximumLoginAttempts=5 to [Link], the server enforces a limit of five
failed login attempts per user. If a user does not successfully log in to the TM1 Server within the specified
number of attempts, the server issues an error.
After a user has exceeded the specified maximum number of failed login attempts, the TM1 Server rejects
any subsequent login attempts by the user.
The MaximumLoginAttempts parameter is enforced per server session. If a user exceeds the maximum
number of attempts, he cannot log in to the current TM1 Server session, unless the administrator changes
his password. However, after the TM1 Server recycles, the user can log in with his existing password.

MaximumMemoryForSubsetUndo
Sets the maximum amount of memory, in kilobytes, to be dedicated to storing the Undo/Redo stack for
the Subset Editor.
For example, adding the line MaximumMemoryForSubsetUndo=20480 to the configuration file instructs
the server to allot 20480 kilobytes (20 MB) of memory for the Undo/Redo stack.
Parameter type: optional, dynamic
Generally, larger subsets require greater amounts of memory to store a usable Undo/Redo stack. If you
find that the TM1 Server is not storing a sufficient number of Undo/Redo steps for your subsets, increase
the value of MaximumMemoryForSubsetUndo.
If this parameter is not explicitly set in the [Link] file, the maximum amount of memory dedicated to
the Undo/Redo feature of the Subset Editor is 10240 kilobytes (10 MB).

MaximumSynchAttempts
Sets the maximum number of times a synchronization process on a planet server will attempt to
reconnect to a network before the process fails.
Parameter type: optional, static
You can use the MaximumSynchAttempts parameter to improve the stability of a synchronization process
that is running over an unstable network connection such as a long distance wide area network (WAN)
with high latency, poor bandwidth and poor transmission quality.
To specify the maximum number of times a synchronization process should attempt to make a network
connection, add the following line to [Link] for the planet server:
MaximumSynchAttempts=n
where n represents the number of network connection attempts that the synchronization process should
make a before the process fails.
The default value is 1 which means the synchronization process will only attempt to connect once and will
not attempt to reconnect if the connection is lost.
A value of 0 means unlimited network connection attempts.
You can configure this parameter to work with the SyncUnitSize parameter. For more information, see
“SyncUnitSize” on page 383.

Chapter 16. Configuring and maintaining Planning Analytics Local 363

 The following example shows how to use the MaximumSynchAttempts parameter with the SyncUnitSize
parameter:

SyncUnitSize=2000

MaximumSynchAttempts=100

MaximumTILockObjects
A server configuration parameter that sets the maximum lock objects for a TurboIntegrator process. Used
by the synchronized() TurboIntegrator function.
The server maintains a list of created TurboIntegrator lock objects. Every time the user calls the
synchronized() function on a lock object, the server first checks to see if the lock object is already in the
list. If not, the server creates a new lock object and inserts it into the list.
For more details, see the topic "Serializing TurboIntegrator processes using synchronized()" in IBM
Cognos TM1 TurboIntegrator.
Even after all the TurboIntegrator processes that have referenced a lock object have exited, the lock
object may not be removed from the list to free the memory immediately. This is because it is likely that
sometime later, either the same process or some other process may call the synchronized() function on
that same lock object.
The server configuration parameter MaximumTILockObjects in [Link] controls the growth of the list
of created TurboIntegrator lock objects. When the number of lock objects in the list has reached
MaximumTILockObjects, the server starts a cleanup operation. It removes some lock objects from the list
if they are not used by any TurboIntegrator process at that moment.
If the MaximumTILockObjects parameter is not explicitly set in [Link], a default value of 2000 is
assumed.
Parameter type: optional, static

MaximumUserSandboxSize
Sets the maximum amount of RAM memory (in MB) to be allocated per user for personal workspaces or
sandboxes.
If you do not set the MaximumUserSandboxSize parameter, the default maximum size is 500 MB on a 64-
bit system.
Parameter type: optional, dynamic
To specify a maximum amount of memory allocation for personal workspaces or sandboxes, add the
following line to [Link]:

MaximumUserSandboxSize=n

where n represents the amount of memory in MB to be allocated.

MaximumViewSize
Sets the maximum amount of memory (in MB) to be allocated when a user accesses a view.
If you do not set the MaximumViewSize parameter, the default maximum view size is 500 MB on a 64-bit
system.
Parameter type: optional, dynamic
To specify a maximum amount of memory allocation for views, add the following line to [Link]:

MaximumViewSize=n

where n represents the amount of memory in MB to be allocated.

364 IBM Planning Analytics: Installation and Configuration

See also “ApplyMaximumViewSizeToEntireTransaction” on page 338.

MDXSelectCalculatedMemberInputs
Changes the way in which calculated members in MDX expressions are handled when zero suppression is
enabled.
Parameter type: required, dynamic
MDXSelectCalculatedMemberInputs addresses an issue with calculated members in an MDX expression
when zero suppression is enabled. When zero suppression is enabled on a query axis, calculated
members might be dropped from the query or might cause zero suppression to be turned off.
The issue arises because zero suppression is based on the actual data in a cube. Calculated members do
not have an actual member in the cube—calculated members are derived from other members.
For example, suppose a cube has a calculated member, C, that is a sum of the members A and B.

C (A+B)
A B

The members A and B are actual members in the cube, while C is derived. When you run a query with A, B,
and C in the columns, {A,B,C}, you see A, B, and C in the columns and you see that C is the sum of A and B.
When you turn on zero suppression, only non-null rows of data are displayed for A, B, and C, as expected.
Now, suppose you restrict the columns to C only, {C}. When zero suppression is turned off, C is displayed
in the columns. But if you turn on zero suppression, C might be dropped from the columns because C does
not reference any actual member in the cube.
MDXSelectCalculatedMemberInputs addresses this issue. When MDXSelectCalculatedMemberInputs is
enabled, TM1 assumes that if the inputs to the calculated member have data (the A and B in the
example), then the calculated member (C) also has data and must be retained when zero suppression is
turned on.
The processing occurs as follows:
1. Do a fast check of the calculated member to detect what specific actual members it references.
2. Consider these actual members as inputs to the calculated member.
3. Make sure that these inputs are included in the stargate data underlying the view.
With the inputs included in the Stargate data, the suppression algorithm sees Stargate data at A and B,
notices that A and B are inputs to C, and keeps C when zero suppression is enabled.
MDXSelectCalculatedMemberInputs works well for simple formulas, like C=A+B. If you use complex
formulas, such as data-dependent formulas that contain conditional expression like IIF, enabling
MDXSelectCalculatedMemberInputs might not resolve issues with zero suppression.
Note : Enabling MDXSelectCalculatedMemberInputs can increase the size of Stargate views. This can
provide faster access times for cube data but can consume more system resources.
To enable MDXSelectCalculatedMemberInputs, add the following to the [Link] file.

MDXSelectCalculatedMemberInputs=True

To disable MDXSelectCalculatedMemberInputs, add the following to the [Link] file.

MDXSelectCalculatedMemberInputs=False

Default value: True

It is recommended to set the MaximumViewSize to be higher than the default 500MB.

Chapter 16. Configuring and maintaining Planning Analytics Local 365

 [Link]
Switches global garbage collection to use lock free structures.
Parameter type: optional, dynamic
Default value: False

MessageCompression
Enables message compression for large messages that significantly reduces network traffic.
The parameter is enabled by default.
Parameter type: optional, static
To disable message compression, add the following line to [Link]:

MessageCompression=F

MTCubeLoad
Enables multi-threaded loading of individual cubes.
Note : To enable multi-threaded loading of individual cubes, you must have IBM Planning Analytics
version 2.0.5 or later installed.
Parameter type: optional, dynamic
Default value: F (disabled)
MTCubeLoad uses the MTQ multi-threaded framework to achieve improved speeds when compared to
the previous approach using MaximumCubeLoadThreads. Configuration settings
[Link], [Link], [Link], and
IndexStoreDirectory are used to optimize performance.
MTCubeLoad also eliminates the risk of changing feeder generation sequences. When MTCubeLoad is
enabled, the MaximumCubeLoadThreads configuration option is ignored. Since MTCubeLoad leverages
the MTQ framework, it still relies on the MTQ configuration to set the number of concurrent threads.
Note : Setting MTCubeLoad=T does not work in all cases. When issues are detected, you must disable the
multi-threaded loading of individual cubes.
TM1 server administrators can use the [Link],
[Link], and [Link] settings to
configure preallocation memory and optimize scale-up and performance results. Allocating memory for a
TM1 server can help avoid contention effects related to varying operating system memory allocation. For
best results, consider the amount of RAM consumed by TM1 server to configure the preallocation memory
settings.
CAUTION : Setting MTCubeLoad=T increases memory usage significantly.

Example
The following [Link] file illustrates the configuration of multi-threaded cube loading:

MTCubeLoad=T
MTQ=All
[Link]=T
IndexStoreDirectory=c:\Cubes\CubeFolder\indexStore

# 30GB of RAM to preallocate

[Link]=30000
# Run preallocation in parallel to cube cell/feeder loading
[Link]=F
# Window 2012 patches as of Dec 2016 worked most efficiently with a single thread
[Link]=1

366 IBM Planning Analytics: Installation and Configuration

 # Disable TM1 performance counters to speed up MTQ.
PerfMonIsActive=F

Logging
To enable logging for multi-threaded loading of individual cubes, enter the following lines in the tm1s-
[Link] file located in the same location as your [Link] file:
[Link]=DEBUG
Captures individual timing of TM1 Server loading stages: DeSerializeDimensions,
DeSerializeAttributeCubes, DeSerializeRegularCubes, GenerateServerSecurity.
[Link]=DEBUG
Captures cube loading time, separately for .cub and .feeder files.

[Link]
Sets the minimum size for cube files to be loaded on multiple threads.
Parameter type: optional, dynamic
The value must be specified in units of KB (kilobytes). Specifying a value of "0" will apply MTCubeLoad to
files of any size.
Default value: 10KB

[Link]
Enables the persisting of bookmarks on disk.
Parameter type: optional, dynamic
Bookmarks store information that allow cube loading to start reading cells/feeders from the middle
of .cub and .feeder files. Bookmarks can be read from the files where they persist. If a bookmark file is
not present, or is out-of-sync with the main file it corresponds to, bookmarks are generated on-the-fly in
parallel for the rest of the cube loading logic. Bookmark files are stored in the folder specified by the
IndexStoreDirectory configuration option. For example:

<IndexStoreDirectory>\<path-to-main-file-relative-to-data-folder>\<main-filename>.bm

Bookmark files incorporate the timestamp of their corresponding main file. When it does not match the
actual timestamp of the main file, bookmark files are ignored and bookmarks are regenerated on-the-fly.
When bookmark synchronization is in doubt, the bookmark folder contents should be cleaned. The
content is regenerated after restarting the server. Bookmark files are also updated during SaveDataAll and
CubeSaveData calls when the main files that the bookmarks are associated with are updated.
Default value: F (disabled)

[Link]
Defines the number of atomic operations needed to load a single cell.
Parameter type: optional, dynamic
The "atomic operation" is the unit used in the [Link]
configuration option. [Link] provides a relative heuristics of how much slower cell loading
is when compared to visiting a cell during a read operation.
Default value: 10

Chapter 16. Configuring and maintaining Planning Analytics Local 367

 MTFeeders
Applies multi-threaded query parallelization techniques to the following processes: the
CubeProcessFeeders TurboIntegrator function, cube rule updates, and construction of multi-threaded
(MT) feeders at start-up.
Parameter type: optional, dynamic
The default setting is disabled (F). Enable this parameter to improve the processing of feeders. Set
MTFeeders=T to obtain the following benefits:
• Process optimization when you use the CubeProcessFeeders( <cube_name>) TurboIntegrator
function.
• When a rule update involves updating feeder cubes, the process is optimized by running in parallel.
Rules are updated manually or by using the RuleLoadFromFile (Cube, TextFile)
TurboIntegrator function.
• When used MTFeeders=T and [Link]=T in [Link], multi-threaded (MT) feeders
are constructed at start-up. See “[Link]” on page 368 for details on using the
[Link] configuration parameter.
CAUTION : Setting MTFeeders=T increases memory usage significantly.

Conditional feeders
When MTFeeders is enabled, TM1® cannot manage the order in which feeders are calculated. There
might be cases where processing order has an adverse effect on your application due to some order-of-
evaluation dependencies in the multi-threaded environment.
Enabling MTFeeders to apply feeder construction during server startup is not supported when your TM1
model uses conditional feeders. Set MTFeeders=F or exclude the parameter from the [Link] file.

[Link]
If the MTFEEDERS configuration option is enabled, enabling [Link] applies multi-
threaded (MT) feeder construction during server start-up.
Parameter type: optional dynamic
The default setting is disabled (F).
When this configuration option is enabled, it prevents the load threads (set with the
MaximumCubeLoadThreads configuration parameter) from taking over parallel feeder construction.
However, [Link] will not disable MaximumCubeLoadThreads impact on other model
load phases.

Conditional feeders
When [Link] is enabled, TM1 cannot manage the order in which feeders are
calculated. There might be cases where processing order has an adverse effect on your application due to
some order-of-evaluation dependencies in the multi-threaded environment.
Enabling [Link] to apply multi-threaded feeder construction during server startup is
not supported when your model uses conditional feeders. Set [Link]=F or exclude the
parameter from the [Link] file.

[Link]
Defines the number of required atomic operations to process feeders of a single cell.
Parameter type: optional, dynamic

368 IBM Planning Analytics: Installation and Configuration

The "atomic operation" is the unit used in the [Link]
configuration option. Essentially, [Link] provides a relative heuristics of how much
slower a feeder construction is when compared to visiting a cell during a read operation. The ratio
[Link]/ [Link] approximates the
number of cells triggering parallel execution when processing feeder updates.
The default value is 10.

MTQ
Sets the maximum number of threads per single-user connection, when multi-threaded optimization is
applied. Used when processing queries, and in batch feeder and cube load operations.
Parameter type: optional, dynamic
Default value: -1
To specify a maximum number of threads for the multi-threaded optimization, add the following line to
[Link]:

MTQ=n

where n represents the number of threads to be used for a single operation.

If you set MTQ equal to a negative number, that is, MTQ=-N, the number of threads that will be used is
defined by the following equation: T=M-N+1, where T= the number of threads to be used by the system
and M= the number of threads on the server.
For example, if your server has 64 cores and you set MTQ=-10, the system will use 55 threads.

T=64-(10)+1

By default, MTQ=-1, which sets the value to the maximum number of threads available to a server. The
result is a dynamic system setting that consumes all threads.
If you set MTQ=1 or MTQ=0, multi-threaded optimization is turned off.
For more information, see "Improving processing performance with Multi-threaded Queries" in TM1
Operations.
Note : Multi-threaded optimizations can improve performance on numeric cubes, where consolidation is
optimized. Since TM1 does not consolidate string values, the MTQ parameter has no impact on the
performance of string cubes.

[Link]
Use this parameter to fine-tune multi-threaded query processing.
Parameter type: optional, dynamic
This parameter specifies the number of cells to be processed before checking whether multi-threaded
splits are needed.
Default value is 10000.

[Link]
Use this parameter to fine-tune multi-threaded query processing.
Parameter type: optional, dynamic
Set this parameter to False to disallow multi-threaded query processing for single cell consolidations. This
is applicable, for example, if your model contains complex rules (rules that have cross-cube references
with a recursive depth greater than two).

Chapter 16. Configuring and maintaining Planning Analytics Local 369

 Single cell consolidation is often invoked for the computation of rules that reference consolidated values
as arguments. Single cell consolidation is also used to compute title only views.
Default value is True.

MTQQuery
Use this parameter to enable multi-threaded query processing when calculating a view to be used as a TI
datasource.
Parameter type: optional, dynamic
If the value of the MTQ parameter is 1 (or OFF), this functionality is turned off entirely and cannot be
overridden.
The value of MTQQuery can be overridden on a per-TI basis by calling the EnableMTQViewConstruct
and DisableMTQViewConstruct TI functions.
If MTQQuery=F, EnableMTQViewConstruct() can be called to override this value on a per-TI basis.
If MTQQuery=T (the default), DisableMTQViewConstruct() can be called to disable the functionality
for individual TIs.
Default value is True.

NetRecvBlockingWaitLimitSeconds
Use this parameter to have the server perform the wait period for a client to send the next request as a
series of shorter wait periods. This parameter changes the wait from one long wait period to shorter wait
periods, so that a thread can be canceled if needed.
Parameter type: optional, static
The parameter is enabled by default.
By default the server can wait for a long time for input, which can result in long-held threads and other
problems.
This parameter instructs the Cognos TM1 server to perform the wait as a series of repeated shorter waits
and gives the server the opportunity to cancel or pause the thread. When set to zero (the default) the
legacy behavior of one long wait is used.
Default value: 0

NetRecvMaxClientIOWaitWithinAPIsSeconds
Specifies the maximum time for a client to do I/O within the time interval between the arrival of the first
packet of data for a set of APIs through processing until a response has been sent.
Parameter type: optional, static
This parameter requires the client to handle I/O in a reasonably timely fashion after initiating API
requests. This parameter is designed to protect against connections that go dead but do not raise a socket
error or create other possibilities such as a hung client.
Default value is 0, which means no time limit.

NIST_SP800_131A_MODE
Indicates that the server must operate in compliance with the SP800-131A encryption standard.
Parameter type: optional, static
When SP800-131 encryption is enforced, the signed certificate must comply with the standard as defined
by the National Institute of Standards and Technology (NIST) Special Publication SP800-131. This
standard requires a minimum key size of 2048 bits and a signature algorithm of RSA with SHA-224 or
higher.

370 IBM Planning Analytics: Installation and Configuration

To turn off SP800-131 compliance, add the following line to the [Link] file:

NIST_SP800_131A_MODE=False

Default value: True

ODBCLibraryPath
Specifies the name and location of the ODBC interface library (.so file) on UNIX.
Parameter type: optional (required to support ODBC on UNIX), static
This parameter is applicable only to TM1 running on UNIX or Linux.
In the [Link] file, add the following line:

ODBCLibraryPath= location/file

Replace location/file with the absolute path and filename of the library.
For example:

ODBCLibraryPath=/usr/local/lib/unixODBC/lib/[Link]

ODBCTimeoutInSeconds
Specifies the timeout value that is sent to the ODBC driver using the SQL_ATTR_QUERY_TIMEOUT and
SQL_ATTR_CONNECTION_TIMEOUT connection attributes.
Parameter type: optional, dynamic
Note : The ODBC driver must respect the request and implement the timeout.
This parameter defaults to zero. A zero value indicates legacy behavior of no timeout.
For example, in the [Link] file, add the following line:

ODBCTimeoutInSeconds= 10

OptimizeClient
Added in v2.0.7 This parameter determines whether private objects are loaded when the user
authenticates during TM1 Server startup.
Parameter type: optional, dynamic
Note : A new user that was dynamically added, who logs in with CAM authentication, is still subject to lock
contention because a new element must be added to the }clients dimension.
Organizations with many users can set this parameter to improve startup times for particular users. Users
with many private objects can set this parameter to improve startup times. Currently, private objects
include a user's private directory, private sandboxes, private subsets, and private views. Loading these
private objects affects the server load and potentially the amount of memory that is consumed at startup.
Depending on the number of users, the private objects, and the memory that each consumes, setting this
parameter can improve server startup times.
OptimizeClient can be set as follows:
• None = 0
• OperationsAdmin = 1
• Admin = 2
• All = 3

Chapter 16. Configuring and maintaining Planning Analytics Local 371

 For example, to load all private objects for all users when TM1 Server starts up, you can set
OptimizeClient to All:

OptimizeClient=3

The default setting is 0 (None).

OracleErrorForceRowStatus
Use this parameter to ensure the correct interaction between IBM Cognos TM1 TurboIntegrator
processes and Oracle ODBC data sources.
Parameter type: optional, static
The format of the parameter is as follows:

OracleErrorForceRowStatus=x

Replace x with one of the following values:

0
Planning Analytics auto-detects the version of Oracle you are connecting to.
1
Planning Analytics handles the connection to Oracle the same way as other drivers.
2
Planning Analytics connects to Oracle and uses SQLULEN instead of SQLUSMALLINT.
The default is 0.

PasswordMinimumLength
Specifies a minimum password length for clients accessing the server.
Parameter type: optional, dynamic
For example, set PasswordMinimumLength=8 to enforce a minimum password length of 8 characters.
Note : This parameter only affects passwords set or changed after the parameter had been set. It has no
effect on old, unchanged passwords having less characters as enforced by PasswordMinimumLength

PasswordSource
Compares user-entered password to the stored password.
Parameter type: optional, static
Cognos TM1 (Default): Compares the user-entered password to the password in the TM1 database.
LDAP: Compares the user-entered password to the password stored in on the LDAP server.

PerfMonIsActive
Use this parameter to turn updates to TM1 performance counters on or off.
Parameter type: optional, dynamic
You can view performance counters using the TM1 PerfMon utility or the Microsoft Windows Performance
Monitor. For more details, see "Using TM1 Performance Counters" in TM1 Operations.
Capturing performance counters in TM1 can impact performance under a heavy multi-user workload (with
100 or more active users). Use this parameter to turn off updates to performance counters if performance
is an issue.

PerfMonIsActive=F

372 IBM Planning Analytics: Installation and Configuration

Default value is T.

PerformanceMonitorOn
Automatically starts populating the }Stats control cubes when a server starts.
The control cubes contain statistics that you can review to monitor the system performance. For details
on control cubes, see "Control Cubes" in IBM Cognos TM1 Operations.
Parameter type: optional, dynamic
For example, to enable Performance Monitor set PerformanceMonitorOn=T. To disable the
Performance Monitor set PerformanceMonitorOn=F

PersistentFeeders
To improve reload time of cubes with feeders, set the PersistentFeeders configuration parameter to true
(T) to store the calculated feeders to a .feeders file.
Any installation with server load times of over 5 minutes can probably improve their performance using
this parameter.
Parameter type: optional, static
When this parameter is set to T and the server encounters a persistent feeder file, it loads the saved
feeders which reduces the time normally taken to recalculate those feeders. Feeders are saved when the
data is saved or rules are edited. You do not explicitly save the feeders
For installations with many complex feeder calculations persisting feeders and then re-loading them at
server startup will improve performance. For simple feeders, the time taken to read feeders from disk may
exceed the time to re-calculate the feeders but most installations will benefit.
Using the Persistent Feeders feature will increase your system size on disk only. Memory size is not
affected by the use of this parameter.

PersistentFeeders=T

For more information, see "Using Persistent Feeders" in IBM Cognos TM1 Operations.

PortNumber
Sets the server port number used to distinguish between multiple servers running on the same computer.
When multiple IBM TM1 Servers are installed on a single computer, each server must use a unique port
number.
Parameter type: optional, static
When you install a TM1 Server, the default port number is 12345. Valid port numbers are between 5001
and 65535.
If the [Link] file does not contain the PortNumber parameter, the TM1 Server uses port 5000. Local
TM1 Servers use port 5000. The port used for Client Messages must also be a unique port number and is
set to 5001 by default when the ClientMessagePortNumberparameter is used.

[Link]
Added in v2.0.5 Specifies whether the preallocation of memory occurs before server loading or in parallel.
Parameter type: optional, dynamic
Default value: F (disabled)
When [Link]=T (enabled), preallocation of memory is performed before
server loading. With this setting is disabled, preallocation occurs in parallel to a server loading process.
Overall server load time improvements vary by operating system allocation speeds and the memory

Chapter 16. Configuring and maintaining Planning Analytics Local 373

 consumption speeds of the server loading logic. TM1 server administrators can modify the preallocation
memory settings to obtain optimal results for their environment.

[Link]
Added in v2.0.5 Triggers the preallocation of pooled TM1 server memory.
Parameter type: optional, dynamic
Default value: 0
Allocated memory is specified in units of MB (megabytes).

[Link]
Added in v2.0.5 Specifies the number of threads used for preallocation memory in multi-threaded cube
loading.
Parameter type: optional, dynamic
Default value: 4

PrivilegeGenerationOptimization
When the IBM TM1 Server generates security privileges from a security control cube, it reads every cell
from that cube.
If the security control cube is sparsely populated, this results in unnecessary processing and a longer
loading time. An example of a sparsely populated security cube would be one that has a greater ratio of
default security settings compared to defined security settings.
Parameter type: optional, static
To address this issue, the PrivilegeGenerationOptimization parameter can be added to the [Link] file as
follows:

PrivilegeGenerationOptimization=T

When this parameter is set to T, the TM1 Server will read only the populated cells in security cubes. In the
case of a sparsely populated security cube, this will dramatically shorten the load time of the TM1 Server.
Note : If you populate the security settings via rules and want to use this parameter, you must write
feeders for the rules that populate your security cubes. Because security settings are stored as strings,
the rules that populate your security cubes must include the FeedStrings function.

ProgressMessage
This parameter determines whether users have the option to cancel lengthy view calculations.
When a user opens a view that takes a significant amount of time to calculate (usually a view with high
levels of consolidation or complex rules), IBM TM1 Server monitors the progress of the process. When
ProgressMessage=T a dialog box opens that allows the user to Stop Building View.
Parameter type: optional, static
If the user clicks Stop Building View, the view is discarded on the client, but view calculation continues on
the server. In some instances, this can tie up the server.
• If ProgressMessage=F, the Stop Building View option is not offered and the user cannot cancel lengthy
operations.
• When ProgressMessage=T or is not present in the [Link] file, the Stop Building View option opens
during lengthy view calculations so the user can cancel the process if necessary. You can assign a
unique Port Number using ClientMessagePortNumber. This additional port allows these progress
messages to travel via a secondary port so that server processing can continue without tying up thread
reserves.

374 IBM Planning Analytics: Installation and Configuration

Note : As of Cognos TM1 10.1, progress messages can travel via the secondary port assigned by
ClientMessagePortNumber so Cognos TM1 10.1 and later have ProgressMessage=T set by default.

ProportionSpreadToZeroCells
Allows you to perform a proportional spread from a consolidation without generating an error when all the
leaf cells contain zero values.
In this case, Cognos TM1 applies an equal spread to the empty cells when the
ProportionSpreadToZeroCells parameter is enabled. This functionality is enabled by default.
Parameter type: optional, static

Behavior when ProportionSpreadToZeroCells is enabled

This parameter and functionality are enabled by default, allowing you to complete a spread operation
without an error when you perform a proportional spread on a consolidation where all the leaf cells are
zero. In this scenario, Cognos TM1 converts the typed entry of "P###" to "LS*###" and applies the
spread as an equal spread.
When this parameter is enabled and data exists in any of the leaf cells, the behavior is the same as
previous versions of Cognos TM1 when performing a proportional spread.
This parameter is on by default and it is not necessary to enable it. However, if you want to explicitly
configure it, set the ProportionSpreadToZeroCells parameter to T (True) in the [Link] configuration file
as follows.
ProportionSpreadToZeroCells=T

Behavior when ProportionSpreadToZeroCells is disabled

Setting this parameter to F (False) disables this feature. An error displays when you try to perform one of
the following proportional spreading operations:
• In TM1 Contributor - Enter a number in a consolidated cell where all of the leaf cells for that
consolidation contain zeros.
• In TM1 Contributor and other TM1 clients - Perform a proportional spread operation by either entering a
spreading code and number such as "P###" in a cell, or access a proportional spread from the right-
click menu or TM1 menu (TM1 Perspectives only) when the leaf cells for that consolidation all contain
zeros.
These operations make the TM1 server perform a proportional spread, but the operation fails because all
of the leaf cells contain zeros.
To disable this functionality, set the ProportionSpreadToZeroCells parameter to F (False) in the [Link]
configuration file as follows.
ProportionSpreadToZeroCells=F

PullInvalidationSubsets
Reduces metadata locking by not requiring an R-lock (read lock) on the dimension during subset creation,
deletion, or loading from disk.
Parameter type: optional, dynamic
Default value: T (enabled)
When a user logs in, the system loads the user's unregistered subsets from disk. At the same time, a
TurboIntegrator process that edits a dimension will hold an IX (intent-to-write) lock on the dimension for
the process duration. In previous releases, or when this parameter is set to F (disabled), logging in could
be blocked for the entire duration of a long-running TurboIntegrator process. TM1 lock types are
incompatible with each other.

Chapter 16. Configuring and maintaining Planning Analytics Local 375

 RawStoreDirectory
Indicates the location of the temporary, unprocessed log file for audit logging if logging takes place in a
directory other than the data directory.
Parameter type: optional, dynamic
If this parameter is not entered, by default the unprocessed audit log file is saved in the directory listed in
the DataBaseDirectory parameter.
For details on other audit logging parameters, see “AuditLogMaxFileSize” on page 338,
“AuditLogMaxQueryMemory ” on page 339, “AuditLogOn” on page 339, and “AuditLogUpdateInterval” on
page 339.

ReceiveProgressResponseTimeoutSecs
The ReceiveProgressResponseTimeoutSecs parameter configures the server to sever the client
connection and release resources during a long wait for a Cancel action.
Parameter type: optional, dynamic
When the IBM TM1 Server is performing lengthy operations for a client, periodic "progress" messages are
sent to the TM1 client application. The client responds to these messages with an indication of whether
the user has pressed the Cancel button, in which case the lengthy operation is terminated. These
responses are generated automatically by the network code in the client application; there is no user
interaction involved. After sending the progress message the server waits for a response from the client
application. As the server is waiting, the client's thread will continue to hold resource locks on the TM1
Server, preventing other users from making other server requests which require the same resource locks.
In some particular situations, most notably running TM1 clients under a Citrix environment, the response
from the client application never arrives back at theTM1 Server, causing the server to wait for an infinite
amount of time. This results in a system lockup, because the client's thread holds resource locks that are
never released.
The ReceiveProgressResponseTimeoutSecs parameter lets you configure your server to detect this
situation and to sever the client connection, releasing the resources. When the parameter is set to a valid
interval (in seconds), the server process will terminate the client connection, releasing any resource locks,
if the server does not detect the client application's response within the specified interval.
For example, if ReceiveProgressResponseTimeoutSecs=20 and the client application does not respond to
the progress message sent from the server within 20 seconds, the client connection is terminated. Again,
no user action is required to generate this response. The response is automatically generated by the client
application, so that if the response does not arrive within 20 seconds, it is an indication that there is
something seriously wrong with the client or the underlying network.
ReceiveProgressResponseTimeoutSecs is an optional [Link] parameter. If the parameter is not present
in the [Link] file, processes are not terminated when a client does not respond to a progress message
from the TM1 Server.
For some TM1 Server installations, the ClientMessagePortNumber defines a separate thread to use for
cancellation messages without tying up reserves. When ClientMessagePortNumber is available,
ReceiveProgressResponseTimeoutSecs is not used.

ReduceCubeLockingOnDimensionUpdate
Reduces the occurrence of cube locking during dimension updates.
Parameter type: optional, static
Default value: F (disabled)
You can use this parameter to reduce cube locking during dimension updates.
Previously, whenever a dimension was updated, all cubes that used this dimension had to be locked IX so
that their rules could be recompiled and checked. This approach meant that if two dimensions used the

376 IBM Planning Analytics: Installation and Configuration

same cube, they could not be modified simultaneously. Often, updating a dimension does not change the
existing rules. For example, adding an element that is not yet referenced by the rules.
Now, you can use this parameter to maintain dimension to cube consistency and coherency. When
ReduceCubeLockingOnDimensionUpdate=T, the same coherency is maintained by using only a RO
lock, which is less prone to causing contention.
Instead of IX locking the cube, the server first makes a copy of the rule to recompile it to the side to see
whether an IX lock is necessary; often it is not.
To enable this functionality, add the following line to the [Link] file:

ReduceCubeLockingOnDimensionUpdate=T

RulesOverwriteCellsOnLoad
Prevents cells from being overwritten on server load in rule-derived data.
Parameter type: optional, static
During the processing of feeders for a cube, a cube's value can be wiped out if there is a rule for that cell.
When the cube that had a cell wiped out is saved, the value is gone so the action has no effect on the
cube. However, if the rule is edited but the cube is not modified later, the cube is not saved to disk. In that
case, real cell values might be wiped out when the rules run.
The RulesOverwriteCellsOnLoad parameter can be used to prevent the zeroing out action after a rule is
edited.
If you are changing rules and the rules might cause some cells that have data to become rule-derived
because of edits, set RulesOverwriteCellsOnLoad=F in the configuration file.
If this parameter is set to T, rule-derived cells are wiped to zero whenever the server loads. The data
value in those cells is lost even if the rule is changed later so that the cell is no longer rule-derived.

RulesOverwriteCellsOnLoad=F

Important :
In IBM Planning Analytics version 2.0.7 or later, if this parameter is not present in the configuration file
then it is assumed to be False by default.
In IBM Planning Analytics version 2.0.6 or earlier, if this parameter is not present in the configuration file
then it is assumed to be True by default.

RunningInBackground
When you add the line RunningInBackground=T to [Link], the IBM TM1 Server on UNIX runs in
background mode.
Parameter type: optional, static
If you use the startup_tm1s.sh and shutdown_tm1s.sh scripts to start and stop your TM1 Server, set
RunningInBackground=T.

SaveFeedersOnRuleAttach
When set to False, postpones writing to feeder files until SaveDataAll and CubeDataSave are called,
instead of updating the files right after rules are changed and feeders are generated at the server start
time.
Parameter type: optional, dynamic
Default value: True

Chapter 16. Configuring and maintaining Planning Analytics Local 377

 SaveTime
Sets the time of day to execute an automatic save of server data; saves the cubes every succeeding day at
the same time. As with a regular shutdown, SaveTime renames the log file, opens a new log file, and
continues to run after the save.
Parameter type: optional, dynamic
The SaveTime parameter is not available when running the TM1 Server as a Windows service.
The format of the SaveTime parameter is dd:hh:mm where:
• dd is the number of days from today that the system will start automatically saving data. For example,
00 is today, 01 is tomorrow.
• hh:mm is the time of day in 24-hour format.

SecurityPackageName
If you configure the IBM TM1 Server to use Integrated Login, the SecurityPackageName parameter
defines the security package that authenticates your user name and password in Microsoft Windows.
Parameter type: optional, static
Valid values are:
• Kerberos
• NTLM
• Negotiate
Use Kerberos unless you are running TM1 locally. If you are running locally, use Negotiate or NTLM.
Negotiate selects Kerberos unless it cannot be used by one of the systems involved in the
authentication.
For complete descriptions of all login security modes, including Integrated Login, see “Integrated login”
on page 247.

ServerCAMURI
Specifies the URI for the internal dispatcher that the IBM TM1 Server should use to connect to Cognos
Authentication Manager (CAM).
The URI is specified in the form

http[s]://fully-qualified host IP address:port/p2pd/servlet/dispatch

Note : In Planning Analytics version 2.0.9 or later, you can configure your TM1 Server CAM URI with a
Server Name Indication (SNI). The SNI can be set using the existing ServerCAMURI parameter in the
format of SNI;URI.
Parameter type: optional, dynamic
For example,

[Link]

For CAM authentication this setting must include the fully-qualified name for the server that the Cognos
Analytics certificate was created for.
To determine the server that the certificate was issued for:
1. Enter the SSL URI to the Cognos Analytics dispatcher in a browser.
2. Update the ServerCAMURI setting in the [Link] with the fully-qualified name of that server.
For example:

378 IBM Planning Analytics: Installation and Configuration

 ServerCAMURI=[Link]

To configure the Cognos TM1 Applications Server to work with CAM SSL,
1. Ensure the following settings are made in Cognos Configuration:
• Force Qualified Paths set to False.
• Use Mutual Authentication set to True
2. Accept the certificate when saving.

ServerCAMURIRetryAttempts
Specifies the number of attempts made before moving on to the next ServerCAMURI entry in the [Link]
file.
Parameter type: optional, static
This parameter is applicable if you are using IBM TM1 Server with Cognos Analytics security and you have
defined multiple dispatchers in the [Link] file. Dispatchers are defined using the ServerCAMURI
parameter.
For example, suppose you have three ServerCAMURI parameters specified in the [Link] file and
ServerCAMURIRetryAttempts=7.

ServerCAMURI=[Link]
ServerCAMURI=[Link]
ServerCAMURI=[Link]
ServerCAMURIRetryAttempts=7

The first dispatcher ([Link] is used and tried seven times. If it does
not respond, the second one is then used and tried seven times. If it does not respond, the third
dispatcher is then tried seven times. If the third one does not respond, the login fails.
Default value: 3

ServerLogging
Generates a log with the security activity details on the IBM TM1 Server that are associated with
Integrated Login.
Parameter type: optional, dynamic
The log file, named [Link], is saved to the TM1 Server data directory. The ServerLogging
parameter is useful only if your TM1 Server is configured to use Integrated Login.
Set ServerLogging to T in [Link]. Note also that if ServerLogging=T is set, you must rename the TM1
Server message logfile [Link] by editing the corresponding parameter in the logger configuration
file [Link].
Note : If you change this parameter dynamically (without restarting the TM1 Server), logging occurs only
for new client sessions.

ServerName
Sets the name of the IBM TM1 Server. If you do not supply this parameter, TM1 Server names the server
Local and treats it as a local server.
Parameter type: optional, static

ServicePrincipalName
Specifies the service principal name (SPN) when using Integrated Login with TM1 Web and constrained
delegation.
Parameter type: optional, static

Chapter 16. Configuring and maintaining Planning Analytics Local 379

 Use the following format to add the parameter to the [Link] file:
ServicePrincipalName=SPN
The value you set here must match the service name that has also been mapped to a domain account on
the Active Directory domain controller using the Microsoft command-line tool, [Link].
For example, if you use [Link] to add an SPN as follows:
setspn -a FPM/TM1 WbSvr_Account
then you need to set the ServicePrincipalName parameter like this:
ServicePrincipalName=FPM/TM1
For more information about constrained delegation and SPN configuration, search the Microsoft website
for the topic "Kerberos Technical Supplement for Windows".

SkipLoadingAliases
Use SkipLoadingAliases to speed up the loading of the server and updating of views by skipping the
loading of aliases.
Parameter type: optional, static
Important : Contact customer support to determine if this parameter is applicable to your IBM TM1
Server.
Valid values are:
• T - Aliases skipped
• F - Aliases loaded

SpreadErrorInTIDiscardsAllChanges
If SpreadErrorInTIDiscardsAllChanges is enabled and a spreading error occurs as part of a running
TurboIntegrator script, all changes that were made by that TurboIntegrator script are discarded.
Parameter type: optional, static
To enable SpreadErrorInTIDiscardsAllChanges, add the following line to the [Link] file:

SpreadErrorInTIDiscardsAllChanges=T

Default value: F

SpreadingPrecision
Use the SpreadingPrecision parameter to increase or decrease the margin of error for spreading
calculations. The SpreadingPrecision parameter value is specified with scientific (exponential) notation.
Parameter type: optional, dynamic
Floating point arithmetic on computers is not 100% precise. When a computer calculates very small
numbers, a margin of error is applied to the calculation. If the computer adds a set of numbers, and the
resulting sum is close to the target value within the margin of error, the sum is considered accurate.
The margin of error for certain TM1 Server calculations is controlled through the SpreadingPrecision
parameter. The default value is SpreadingPrecision=1e-8. This value is used in the following spreading
scenarios:
• Spreading from a consolidated cell.
• Spreading in leaf cells whose consolidated value has a hold applied.

380 IBM Planning Analytics: Installation and Configuration

Spreading from a Consolidation
When you execute a proportional data spread from a consolidated cell, TM1 Server writes the numbers to
each cell in the range, and rolls up the total to recalculate the consolidation. The total of all cells in the
consolidation is then compared to the original value you provided for the spread function. The total might
be different from the target value because of the rules applied to the n-level elements or the consolidated
cell itself.
If the rules are such that the resultant value does not match the spread desired value, an error will be
generated and the spread operation will not be done.
If SpreadingPrecision=1e-8, the total calculated by TM1 Server for the consolidation must be within
0.000001% of the target value (99.999999% accurate), or TM1 Server displays an error. An error of more
than US$0.01 on a consolidated spread of US$1,000,000 results in an error.
You can increase or decrease the margin of error for these types of calculations using the
SpreadingPrecision parameter.
The following examples include valid values for the SpreadingPrecision parameter:
• SpreadingPrecision=1e-4
• SpreadingPrecision=1e-8
• SpreadingPrecision=1e-99
The exponent value in the notation must be two digits or less. For example,
SpreadingPrecision=1e-123 is not a valid parameter value, as the exponent contains three digits.

Spreading and Consolidation Holds

The SpreadingPrecision parameter also has an effect under these conditions:
• When you spread values to some leaf cells that roll up into a consolidation
• A consolidation with a hold applied to it
For example, suppose you have the consolidation Q1 with values Jan, Feb, and Mar.
If Q1- has a consolidated hold applied, and you spread values to Jan and Feb, TM1 Server does the
following:
• Applies the spreading to Jan and Feb.
• Adjusts Mar.
• Adds the three n-level elements together.
• Compares the sum of the n-level elements to the value of Q1.
If the sum is accurate to within the margin of error specified by the SpreadingPrecision parameter, the
spread succeeds. If the sum falls outside the margin of error specified by the SpreadingPrecision
parameter,TM1 Server generates an error.

SQLRowsetSize
Added in v2.0.3 Specifies the maximum number of rows to retrieve per ODBC request.
This parameter can be used to improve execution time for long-running processes that are caused by slow
Microsoft SQL queries. It can benefit any users that use an ODBC driver that does not have a fetch setting,
such as MS SQL and Db2. It does not affect Oracle database users.
Parameter type: optional, dynamic
Note : This parameter applies to all data sources even if you are pulling data from multiple different data
sources.

Chapter 16. Configuring and maintaining Planning Analytics Local 381

 To set this parameter, add the following line to the [Link] file for the server:

SQLRowsetSize=nn

Where nn is any positive integer that represents the maximum number of ODBC requests to make.
The minimum value is 50 (default).
For cloud only customers, the default value is 500. The entry SQLRowsetSize=500 is added to the
[Link] file for any new provision in IBM Planning Analytics on Cloud. If the setting exists in the
[Link] file, it is not changed.
The recommended value depends on the long-running process that you are trying to improve processing
for. You can double the values (100, 200, and so on) to test for the best results. Increasing the value of
SQLRowsetSize fetches more results per ODBC request and incurs network latency fewer times.
A larger value means that more memory is used per fetch. You need to look at memory consumption to
see whether the increase in memory usage is acceptable (it might be noticeable if you have lots of data
per row).

SSLCertAuthority
Specifies the name of the IBM Cognos TM1 server's certificate authority file. This file must reside on the
computer where the TM1 server is installed.
Parameter type: optional (required for SSL), static
If you are using your own SSL certificates with TM1, you can determine this value by referring to the
Microsoft Management Console. Click Certificates > Personal > Certificates. The principal name is
displayed in the Issued By column of the Properties pane.

SSLCertificate
Specifies the full path of the IBM Cognos TM1 server's certificate file, which contains the public/private
key pair.
Parameter type: optional (required for SSL), static

SSLCertificateID
Specifies the name of the principal to whom the IBM Cognos TM1 server's certificate is issued.
Parameter type: optional (required for SSL), static
If you are using your own SSL certificates with TM1, you can determine this value by referring to the
Microsoft Management Console. Click Certificates > Personal > Certificates. The principal name is
displayed in the Issued To column of the Properties pane.

StartupChores
StartupChores is a configuration parameter that identifies a list of chores that run at server startup.
Parameter type: optional, static
To run a chore at startup before users login or other scheduled chores run, add this parameter with the
names of the chores to run separated by a colon, for example:

StartupChores=ChoreName1:ChoreName2:ChoreName3:ChoreNameN

If this parameter is not specified, then no Chores will be run. If the name specified does not match an
existing Chore then an error is written to the server log and execution continues to the next Chore.
The value of the configuration parameter can be retrieved by a client application as a Server property
called StartupChores using the existing TM1ObjectPropertyGet call.

382 IBM Planning Analytics: Installation and Configuration

This is a read-only property and set operations are rejected. The value of the property can be changed
only by editing the configuration file and restarting the server.

SubsetElementBreatherCount
This parameter manages the wayIBM TM1 Server handles locking behavior for subsets.
Parameter type: optional, dynamic
When

SubsetElementBreatherCount=-1

The TM1 Server never releases the lock on subsets when other requests for the subset are pending. This
setting is the default. It can optimize view performance for a single user, but at the cost of multi-user
concurreny.
When SubsetElementBreatherCount is set to any value greater than zero (0), the TM1 server releases
the lock on subsets when other requests for the subset are pending, then reacquires the lock after
pending requests are processed. This setting improves performance when multiple users attempt to
access the same subset, particularly when the subset contain more than 100 elements.

SupportPreTLSv12Clients
As of TM1 10.2.2 Fix Pack 6 ([Link]), all SSL-secured communication between clients and servers in
TM1 uses Transport Layer Security (TLS) 1.2. This parameter determines whether clients prior to [Link]
can connect to the [Link] or later TM1 server.
Parameter type: optional, static
Default is F (False).
To allow clients prior to [Link] to connect to the [Link] (or later) TM1 server, add the following line to
[Link]:

SupportPreTLSv12Clients=T

When the TM1 server is configured to allow connections from pre-TLS v1.2 clients, the connection with
such clients is established using TLS 1.0.
If SupportPreTLSv12Clients is not present in the [Link] file, or if
SupportPreTLSv12Clients=F, clients prior to [Link] cannot connect to a [Link] or later TM1
Server.

SvrSSLExportKeyID
Specifies the identity key used to export the IBM Cognos TM1 server's certificate from the Microsoft
Windows certificate store.
Parameter type: optional, static
In most cases, the value for SvrSSLExportKeyID will be identical to the value for SSLCertificate.

SyncUnitSize
Sets the frequency of saving a check point during a synchronization process in case there is a network
connection failure.
Parameter type: optional, static
Note : When you use SyncUnitSize, you must also configure the MaximumSynchAttempts parameter. For
more information, see “MaximumSynchAttempts” on page 363.

Chapter 16. Configuring and maintaining Planning Analytics Local 383

 If you configure both the SyncUnitSize and MaximumSynchAttempts parameters and a synchronization
process is interrupted by a network connection failure, the process will attempt to reconnect and
complete the synchronization starting from the last check point.
To set this parameter, add the following line to the [Link] file for the planet server:

SyncUnitSize=n

where n represents the number of synchronization records written to the transaction log file, [Link],
after which a check point will be saved.
The default value is 1000.
The minimum recommended value is 500.

tlsCipherList
Specifies a comma-separated list of supported cipher suites in priority sequence.
Parameter type: optional, static
Use tlsCipherList to specify what cipher suites are acceptable for your TM1 system. The listed cipher
suites are presented to the SSL negotiation in the order in which they are listed, for both the client and
server sides of the negotiation. At least one of the listed cipher suites for the client and server must
match.
The following cipher suites are supported:
• RFC 2246: "The TLS Protocol Version 1.0 " ([Link]
• RFC 4346: "The Transport Layer Security (TLS) Protocol Version 1.1" ([Link]
[Link])
• RFC 5246: "The Transport Layer Security (TLS) Protocol Version 1.2" ([Link]
[Link])
• RFC 4492: "Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)" (http://
[Link]/rfc/[Link])
• RFC 5289, TLS Elliptic Curve Cipher Suites with SHA-256/384 and AES Galois Counter Mode (GCM)
([Link]
For example:

tlsCipherList=TLS_RSA_WITH_AES_128_CBC_SHA,
TLS_RSA_WITH_RC4_128_MD5, TLS_RSA_WITH_AES_128_CBC_SHA256

TopLogging
Added in v2.0.7 Enables dynamic logging of the threads that are running in an instance of the TM1 Server.
Parameter type: Boolean, optional, dynamic
By default, the TopLogging parameter is set to False.
Note : You must add TopLogging=T to the [Link] file before you start your TM1 Server to enable
logging.

TopScanFrequency
Added in v2.0.7 Specifies the logging frequency (interval) in seconds for the TopLogging logger, which
enables dynamic logging of the threads that are running in an instance of the TM1 Server.
Parameter type: Integer, optional, dynamic
By default, the TopScanFrequency parameter is set to 5 seconds. Setting this parameter to 0 disables
the logger.

384 IBM Planning Analytics: Installation and Configuration

See also TopLogging.

[Link]
Added in v2.0.7 Enables logging of the active sandboxes for the current server, the total memory that is
consumed for all sandboxes by a user, and the number of sandboxes for this user.
Parameter type: optional, dynamic
By default, the [Link] parameter is set to F (False).
See also TopLogging.

[Link]
Added in v2.0.7 Enables logging of sandbox queue metrics. The name of the node for the sandbox, the
status of the sandbox in the queue, and the length of time the sandbox was in the queue before it was
processed is logged for each sandbox in the queue.
Parameter type: optional, dynamic
By default, the [Link] parameter is set to F (False).
See also TopLogging.

[Link]
Added in v2.0.7 Enables logging of the current processing state of each thread. This information includes
the name of the user or process that started the thread, the API function that the thread is executing, the
lock status of the last object that was locked, the number of objects that are used by the thread, and the
total time, in seconds, that the current API function or chore process has been processing.
Parameter type: optional, dynamic
By default, the [Link] parameter is set to T (True).
See also TopLogging.

UnicodeUpperLowerCase
This configuration parameter instructs the TM1 server to identify and handle Unicode object names,
preventing the creation of identical Unicode object names that vary only in case.
Parameter type:
• Optional
• Static
If you change this parameter value, restart the TM1 server to apply the new value.
TM1 treats ASCII object names as case-insensitive; the element name SALES is equivalent to sales. A
reference to either SALES, sales, or even SaLeS is considered to be a reference to a single element.
Similarly, the cube name Projections is equivalent to PROJECTIONS.
However, Unicode object names are not treated as case-insensitive. Consequently, a server can contain
two identically named objects that varied only in case. For example, the elements NEMÈIJA and nemèija
can exist in a single dimension, and each is considered a unique element.
Include the parameter UnicodeUpperLowerCase=T in your [Link] file to prevent the creation of
identically named Unicode object names that vary only in case. When UnicodeUpperLowerCase=T,
Unicode object names are handled just as ASCII object names, and are case-insensitive.
If you have developed applications that rely on Unicode object names that vary only in case, and want to
maintain such functionality, you should not add the UnicodeUpperLowerCase configuration parameter to
your [Link] file. If this parameter is not present in [Link] (or is set to F) TM1 will continue to treat
Unicode object names as case-sensitive.

Chapter 16. Configuring and maintaining Planning Analytics Local 385

 UseExcelSerialDate
Enables the use of Microsoft Excel serial dates instead of TM1 serial dates.
Parameter type: optional, static
When UseExcelSerialDate is enabled, TM1 rule functions and TurboIntegrator functions use Jan 1, 1900
as a base date for serial dates instead of Jan 1, 1960.
In the past, TM1 rule functions used serial dates that represent the number of days elapsed since Jan 1,
1960. This conflicts with Microsoft Excel serial dates, which represent the number of days elapsed since
Jan 1, 1900. The number formatting features in TM1 expect cube data to use Microsoft Excel serial dates
rather than TM1 serial dates.
To avoid the need to convert dates, enable UseExcelSerialDate to have rule functions use Microsoft Excel
dates rather than legacy TM1 dates.

UseExcelSerialDate=T

Default value: F

Example
You can see the serial date issue in this example.
The following rule returns May 26, 2015 as a serial date.

[]= N:(DAYNO('2015-05-26'));

The unformatted result is 20234, which indicates that 20234 days have elapsed since Jan 1, 1960. The
rule function is using legacy TM1 serial dates.
When you set the display format in TM1 to a date format, such as mmmm dd, yyyy, the result is May 25,
1955, because May 25, 1955 is 20234 days away from Jan 1, 1900. The value is being interpreted as a
Microsoft Excel serial date.
After you add UseExcelSerialDate=T to the [Link] file and restart the TM1 server, you see the
expected result, May 26, 2015, in TM1. The rule function is now using Jan 1, 1900 as the base date for
serial dates.

UseLocalCopiesforPublicDynamicSubsets
Allows public dynamic subsets to improve performance and reduce locking by using local copies of the
subset when possible.
Parameter type: optional, dynamic
By default, or if the parameter is not present in the [Link] file,
UseLocalCopiesforPublicDynamicSubsets is enabled. To restore the earlier method of saving
dynamic subsets, set this parameter to F.

UserDefinedCalculations
Enables the Rollup and Insert Subset options to create user-defined consolidations in the Subset Editor
in IBM Cognos TM1(r) Perspectives and Architect, and enables the Create Custom Consolidation button
in TM1(r)Web clients.
Parameter type: optional, dynamic
By default, UserDefinedCalculations is enabled.
To disable user-defined consolidations TM1 Perspectives, Architect, and TM1 Web clients, add the
following line to [Link]:

UserDefinedCalculations=F

386 IBM Planning Analytics: Installation and Configuration

Note : When set to F, users will see the following:
• In Architect and Perspectives, when users click the Rollup or Insert Subset option, they will get an
error message stating that user defined calculations are not enabled.
• In TM1 Web, the Create Custom Consolidation button will be grayed-out.

UseSQLFetch UseSQLFetchScroll UseSQLExtendedFetch

These parameters instruct IBM TM1 Server to use a particular fetch call.
Parameter type: optional, dynamic
When you run TurboIntegrator process that extracts information from an ODBC data source, TM1 Server
tries to use the most efficient SQL fetch call possible.TM1 Server queries the ODBC driver to determine
which of the following SQL Fetch calls to use to extract the data:
SQLFetch(), an ODBC 1 function
SQLExtendedFetch(), an ODBC 2function
SQLFetchScroll(), an ODBC 3 function
These parameters are all dynamic.
If TM1 Server receives no response when it queries the ODBC driver, your TM1 Server process will result
in an error unless one of the following parameters is set to T in your [Link] file:
UseSQLFetch
UseSQLFetchScroll
UseSQLExtendedFetch
These parameters instruct TM1 Server to use a particular fetch call. You must ensure that the call
specified in [Link] is appropriate for the ODBC driver being accessed, and you can specify only one of
these parameters in [Link].
For example, to instruct the TM1 Server to use the SQLExtendedFetch() call to extract data from an ODBC
source, add the following line to [Link]:

UseSQLExtendedFetch=T

UseSSL
Enables or disables SSL on the IBM TM1 Server.
Parameter type: optional (required for SSL), static
This parameter is enabled by default.
To disable SSL, set UseSSL=F.
Default value: T
When UseSSL=T, you must set several other [Link] parameters that manage SSL implementation. For
details on these parameters, see “Data transmission security ” on page 282.

UseStargateForRules
Indicates if a rule uses the Stargate view.
Parameter type: optional, static
By default, any time a rule references a calculated value, the value is retrieved from a Stargate view stored
in memory (if available). Using the Stargate view for rules, in most cases, results in a significant
improvement in performance. It is more efficient to retrieve a calculated value from memory than to
request and retrieve a calculation from the server.

Chapter 16. Configuring and maintaining Planning Analytics Local 387

 In some unique instances that are difficult, if not impossible, to determine in advance and can only be
determined through trial and error, retrieving a calculated value from a Stargate view is actually slower
than requesting and retrieving the value from the server. In these instances, add the following line to
[Link] to instruct the TM1 rules to always retrieve the calculated values from the server and improve
performance.

UseStargateForRules=F

Contact customer support before adding the UseStargateForRules parameter.

VersionedListControlDimensions
Removes contention on control dimensions such as }Cubes, }Dimensions, }Groups, }Clients. Allows
creation of new objects without IX locking the dimension.
Parameter type: optional, static
Default value: T (enabled)
Set to F (False) to disable versioned list control dimensions.

ViewConsolidationOptimization
Enables or disables view consolidation optimization on the IBM TM1 Server.
Parameter type: optional, static
Using this parameter improves the performance of calculating consolidated elements. By default,
ViewConsolidationOptimization is enabled on the TM1 Server.
View consolidation optimization stores the consolidated values that use leaf element components on
either the row or column axis. For example, consider the dimension structure Year, 1Quarter with values
Jan, Feb, and Mar.
When either a row or column subset uses the Jan element, both the 1 Quarter and Year consolidations are
calculated and stored for future reference. This improves performance but increases the amount of
memory required for a given view.
To disable view consolidation optimization, add the following line to [Link]:
ViewConsolidationOptimization=F

ViewConsolidationOptimizationMethod
This parameter defines the method used to achieve view consolidation optimization when the
ViewConsolidationOptimization parameter is enabled on the IBM TM1 Server.
Parameter type: optional, static
There are two methods that ViewConsolidationOptimization can use to calculate and store consolidations:
ARRAY or TREE. The ARRAY method stores consolidations in a temporary array. The TREE method stores
consolidations in a tree.
ViewConsolidationOptimizationMethod should be set to TREE in most circumstances. This setting
provides the best performance in normal operations.
In rare instances, using the TREE method can result in a degradation of performance. In such an instance,
try setting the parameter to ARRAY. For example, in the uncommon circumstance when dimensions have
just a few leaf elements rolling up to many consolidations, ViewConsolidationOptimizationMethod should
be set to ARRAY.
To set this parameter, add the appropriate line to your configuration file:

ViewConsolidationOptimizationMethod=TREE

388 IBM Planning Analytics: Installation and Configuration

 or

ViewConsolidationOptimizationMethod=ARRAY

If ViewConsolidationOptimizationMethod is not explicitly set in the [Link] file, the TREE method is
used by default.

ZeroWeightOptimization
Determines whether consolidated members with a weight of 0 are factored into the computation of
consolidated cell values or consolidation functions. Consolidation functions include ConsolidatedCount,
ConsolidatedMax, ConsolidatedMin, ConsolidatedAvg, ConsolidatedCount, and ConsolidatedCountUnique.
Parameter type: optional, static
When set to true, members for which the weighting is zero are eliminated from the consolidation list, and
are therefore not processed when calculating values for consolidated cells or consolidation functions.
This is the default behavior.
When set to false, members for which the weighting is zero are included in the consolidation list, and
are therefore factored into the calculations.
Default value: true

The [Link] client configuration file

The [Link] file specifies the environment information for the IBM Cognos TM1 clients (Cognos TM1
Perspectives, Cognos TM1 Architect, and Cognos TM1 Clients).

Location of the [Link] File

IBM Cognos TM1 installs a system default version of the [Link] file and also creates a user-specific
version of the file.
The two versions of the [Link] file are stored in different locations.

System default [Link] file

The system default version of [Link] allows multiple users to use Cognos TM1 on a given computer.
The [Link] file must be present the first time a user starts Cognos TM1 on the computer, as the
parameters in the system default version govern the behavior of the initial startup of the Cognos TM1
client for each user.
The installation location of the system default version of the [Link] file is determined by the
%ProgramData% setting.
%ProgramData%\Applix\TM1\
For example:
C:\ProgramData\Applix\TM1\[Link]
Tip : Run echo %ProgramData% from a command line to see the exact location.

User-specific [Link] file

After a user starts Cognos TM1 on the computer, a user-specific copy of the [Link] file is created in
their %USERPROFILE% location.
The user-specific copy of [Link] accepts all parameters settings and changes for the user and
governs the behavior of the Cognos TM1 client for all subsequent user sessions of the Cognos TM1 client.

Chapter 16. Configuring and maintaining Planning Analytics Local 389

 The Cognos TM1 Options dialog box also stores many of these settings. You can change these settings
using either the TM1 Options dialog box or by editing the [Link] file. The [Link] parameters and
TM1 Options are described here.
The exact location for %USERPROFILE% is located here:
%USERPROFILE%\user name\AppData\Roaming\Applix\TM1\
For example:
C:\Users\ADMIN\AppData\Roaming\Applix\TM1\[Link]
Tip : Run echo %USERPROFILE% from a command line to see the exact location.

Parameters in the [Link] file

The following parameters can be used in the [Link] file.

AdminHost
Displays the Admin Host name on which an Admin Server is running. On IBM Cognos TM1 Options, use
Login Parameters Admin Host.

AdminSvrSSLCertAuthority
The full path of the certificate authority file that issued the certificate for IBM TM1 Server.
On Cognos TM1 Options, use Certificate Authority.

AdminSvrSSLCertID
The name of the principal to whom the IBM Cognos TM1 Admin Server's certificate is issued.
Note : The value of this parameter should be identical to the SSLCertificateIDparameter for the
Cognos TM1 Admin Server as set in IBM Cognos Configuration.
This parameter can also be set for clients in the Cognos TM1 Options window > Certificate ID field.

AdminSvrSSLCertRevList
The full path of the certificate revocation file issued by the certificate authority that issued the IBM
Cognos TM1 Admin Server's certificate.
A certificate revocation file will only exist in the event a certificate had been revoked. On Cognos TM1
Options, use Certificate Revocation List.

AdminSvrSSLExportKeyID
The identity key used to export the certificate authority certificate, which originally issued the IBM Cognos
TM1 Admin Server's certificate, from the certificate store.
This parameter is required only if you choose to use the certificate store by setting
ExportAdminSvrSSLCert=T.
On Cognos TM1 Options, use Export Certificate ID.

AdvancedRulesEditor
Deprecated in v2.0.7 Indicates the type of rules editor used.
Note : As of Planning Analytics version 2.0.7, the AdvancedRulesEditor parameter in the [Link]
file is ignored. The advanced rules editor does not launch in TM1 Architect and TM1 Perspectives, only the
basic rule editor launches.
The advanced rules editor has an enhanced interface.

390 IBM Planning Analytics: Installation and Configuration

• T - The advanced rules editor is used.
• F (Default)- The basic rules editor is used.

AllowImportCamClients
This parameter is required only when configuring IBM TM1 Server to use CAM authentication.
It must be set to T when importing an administrative user from CAM into TM1 Server.
If your TM1 Server is not configured to use CAM authentication, this parameter should be set to F or
omitted from the [Link] file.
For details, see “Configuring the TM1 Server to use Cognos security” on page 263.

BrowseDisplayReadsRightToLeft
Indicates how data is oriented in the Cube Viewer.
Data can display right to left or left to right.
• T - Data is oriented right to left.
• F (Default) - Data is oriented left to right.

ClassicSliceMode
Indicates whether the Slice option in the Cube Viewer generates classic slices or dynamic slices.
• T - Slice option generates classic slices.
• F - Slice option generates dynamic slices.

CognosGatewayURI
This parameter is required only when configuring IBM TM1 Server to use IBM Cognos security (CAM)
authentication.
It must be set to the URI of your IBM Cognos gateway. The URI is specified in the form http[s]:/
<host>/cognosx/cgi-bin/[Link] or http[s]:/<host>/ibmcognos/cgi-bin/
[Link].
For example, [Link]
If your TM1 Server is not configured to use CAM authentication, this parameter should be omitted from
the [Link] file.
For details, see “Configuring the TM1 Server to use Cognos security” on page 263.

ConnectLocalAtStartup
Indicates whether IBM Cognos TM1 Architect or IBM Cognos TM1 Perspectives automatically connects to
the local server at startup.
• T (Default) - TM1 Server connects to the local server at startup.
• F - TM1 Server does not connect to the local server at startup.

DataBaseDirectory
Uses the full path to the local server data directory.
You can specify multiple data directories by separating the directory names with semicolons.

DimensionDownloadMaxSize
A threshold value of the number of elements in a dimension, beyond which the dimension is downloaded
and cached on the IBM TM1 client.

Chapter 16. Configuring and maintaining Planning Analytics Local 391

 The DimensionDownloadMaxSize parameter is applicable to older version of TM1. The parameter is not
applicable to 10.2.2.
To improve performance when you work with large dimensions, add DimensionDownloadMaxSize so that
large dimensions will cache on the client.

DisableAdminHostEntry
When enabled in the [Link] file, the DisableAdminHostEntry parameter prevents users from
modifying the Admin Host setting on the TM1 Options dialog box.
When DisableAdminHostEntry=T, the Admin Host option on the TM1 Options dialog box is disabled.
This prevents a user from modifying the Admin Host setting and seeing other TM1 servers in your
environment. If DisableAdminHostEntry=F, or if the parameter is not present in the [Link] file,
the Admin Host setting can be edited.
DisableAdminHostEntry must be present in the user-specific version of the [Link] file. When the
DisableAdminHostEntry parameter is added in the system default [Link] file, the parameter and
setting is copied to the user-specific version of [Link] the first time a user starts Architect or
Perspectives.
If a user starts Architect or Perspectives and the DisableAdminHostEntry parameter is not present in
the system default version of [Link], DisableAdminHostEntry=F is added to the user-specific
version of [Link].

DisableWritebackOnDisconnect
When DisableWritebackOnDisconnect is enabled in the [Link] file, worksheet cells containing
TM1 formulas that write to the TM1 server remain active and write to the server as long as an active
server connection is available.
However, when this parameter is enabled and the TM1 Perspectives client is not connected to a TM1
server, cells containing TM1 formulas that write to the server are no longer protected. In this case,
entering a value in any worksheet cell containing a TM1 formula that writes to the TM1 server results in
the TM1 formula being overwritten.
TM1 formulas that write to the server include DBR, DBRW, DBRA, DBS, DBSA, DBSS, and DBSW.
Setting DisableWritebackOnDisconnect=T also restores multiple level undo/redo and multiple copy/
paste operations in a worksheet containing TM1 formulas when there is no active server connection.
DisableWritebackOnDisconnect has a similar effect as DisableWritebackOnTM1Formulas. The
important distinction between these two parameters is that DisableWritebackOnDisconnect applies
only when there is no active server connection, while DisableWritebackOnTM1Formulas applies at all
times.

DisableWritebackOnTM1Formulas
When enabled in the [Link] file, the DisableWritebackOnTM1Formula parameter prevents
writeback to the TM1 server when you enter a value in a cell containing a TM1 worksheet formula.
When you set DisableWritebackOnTM1Formula=T in the [Link] file, entering a value in any
worksheet cell containing a TM1 formula that writes to the TM1 server results in the TM1 formula being
overwritten.
TM1 formulas that write to the server include DBR, DBRW, DBRA, DBS, DBSA, DBSS, and DBSW.
Setting DisableWritebackOnTM1Formula=T also restores multiple level undo/redo and multiple copy/
paste operations in a worksheet containing TM1 formulas.

DisplayApplications
Indicates whether the Applications group is visible in Server Explorer on startup.
• T - Applications group is visible in Server Explorer.

392 IBM Planning Analytics: Installation and Configuration

• F - Applications group does not appear in Server Explorer.

DisplayChores
Indicates whether the Chores group is visible in Server Explorer on startup.
• T - Chores group is visible in Server Explorer.
• F - Chores group does not appear in Server Explorer.

DisplayControlCubes
Indicates whether the Control Cube group is visible in Server Explorer on startup.
• T - ControlCube group is visible in Server Explorer.
• F - ControlCube group does not appear in Server Explorer.

DisplayCubes
Indicates whether the Cubes group is visible in Server Explorer on startup.
• T - Cubes group is visible in Server Explorer.
• F - Cubes group does not appear in Server Explorer.

DisplayDimensions
Indicates whether the Dimensions group is visible in Server Explorer on startup.
• T - Dimensions group is visible in Server Explorer.
• F - Dimensions group does not appear in Server Explorer.

DisplayExplorerPropertiesWindow
Indicates whether the Properties pane is visible in Server Explorer on startup.
• T - Properties pane is visible.
• F (Default) - Properties pane does not appear.

DisplayProcesses
Indicates whether the Processes group is visible in Server Explorer at startup.
• T - Processes group is visible in Server Explorer.
• F - Processes group does not appear in Server Explorer.

DisplayReplications
Indicates whether the Replications group is visible in Server Explorer at startup.
• T - Replications group is visible in Server Explorer.
• F - Replications group does not appear in Server Explorer.

ExpandRowHeaderWidth
Indicates if the Row Headers will automatically expand to accommodate the width of the longest entry in
the column.
• T(Default) - Row headers auto-expand.
• F - Row header must be manually expanded when necessary.

Chapter 16. Configuring and maintaining Planning Analytics Local 393

 ExportAdminSvrSSLCert
Select this option if you want the certificate authority certificate which originally issued the IBM Cognos
TM1 Admin Server's certificate to be exported from the Microsoft Windows certificate store at runtime.
• T (Default) - Original certificate is exported from the Windows certificate store.
• F - Original certificate is not exported.
In Cognos TM1 Options, select Use Certificate Store.
When this option is selected, you must also set a value for Export Certificate ID in the Cognos TM1
Options dialog box or AdminSvrSSLExportKeyID.

InSpreadsheetBrowser
Indicates if the In-Spreadsheet Browser or the Cube Viewer is the default browser.
• T - In-Spreadsheet Browser is the default browser. When you double-click a cube or view, it opens in an
Excel document.
• F (Default) - Cube Viewer is the default browser. When you double-click a cube or view, it opens in the
Cube Viewer.

IntegratedLogin
Indicates if your TM1 client uses Integrated Login or the standard TM1 security to log in to the IBM TM1
Server and other TM1 components.
• T - Client uses Integrated login, where your Microsoft Windows login username and password are used
to access the TM1 Server and other components.
• F (Default) - Client uses standard TM1 Server security, where a username and password must be
explicitly provided, when logging in to the TM1 Server and other components.
Before you enable this parameter, consult with your TM1 administrator to determine if Integrated Login is
implemented on your TM1 Server.
On Cognos TM1 Options, use Integrated Login.

Language
Indicates the language used in the IBM TM1 Server client interface.
Clients will try to read from the locale and use that to set the language. That language will be used if it
matches one of the supported languages. If the language entered does not match a supported language,
English is used.
To override the default you can set the Language explicitly in the [Link] using the following codes:

Language Code
Brazilian Portuguese bra
Croatian hrv
Czech csy
Chinese (Simplified) sch
Chinese (Traditional) tch
Danish dan
Dutch nld
German deu
Finnish fin

394 IBM Planning Analytics: Installation and Configuration

Language Code
French fra
Hungarian hun
Italian ita
Japanese jpn
Kazakh kaz
Korean kor
Norwegian nor
Polish pol
Romanian rom
Russian rus
Spanish esp
Slovenian slv
Swedish sve
Thai tha
Turkish trk

LocalServerNetworkProtocol
Determines the protocol that the local IBM TM1 Server uses to communicate with clients. Currently, the
only valid setting is TCP.

MainWindowLayoutInfo
Generates dimension and position coordinates for the Server Explorer window; allows Server Explorer
dimensions and position to be maintained between sessions.
The coordinates are automatically generated when you move or resize the Server Explorer window.

PreviousAdminHosts
Lists up to six of the most recently accessed Admin Hosts from the IBM Cognos TM1 Options Admin Host
list.

PreviousDataDirectories
Lists up to six of the most recently accessed data directories in the Local Server Data Directory list from
the IBM Cognos TM1 Options window.
The directories accessed within a single session are separated by semicolons. The directories accessed in
different sessions are separated by commas.

SecurityAssignmentWindowLayoutInfo
Generates dimension and position coordinates for the Clients/Groups window; allows Clients/Groups
dimensions and position to be maintained between sessions.
The coordinates are automatically generated when you move or resize the Clients/Groups window.

Chapter 16. Configuring and maintaining Planning Analytics Local 395

 SentMsgsToServerCountWarning
The SentMsgsToServerCountWarning parameter is for development use only. The parameter is set to F by
default.
Be sure not to change the default setting.

ShowAdminHostChangeWarning
Between session storage of whether to display or suppress a warning when the AdminHost is changed.
• T (Default)- When an AdminHost is changed, a warning message displays.
• F - No message is displayed when the AdminHost is changed.

ShowAliasAttributeWarning
Between session storage of whether to display or suppress a warning when the Alias Attribute is changed.
• T (Default)- When an Alias Attribute is changed, a warning message displays.
• F - No message is displayed when the Alias Attribute is changed.

ShowChoresSchedulingWarning
Between session storage of whether to display or suppress a warning when a chore schedule is changed.
• T (Default)- When a chore schedule is changed, a warning message displays.
• F - No message is displayed when a chore schedule is changed.

ShowCubeReplicationWarning
Between session storage of whether to display or suppress a warning when a cube is replicated.
• T (Default)- When a cube is replicated, a warning message displays.
• F - No message is displayed when a cube is replicated.

ShowDimDeleteElementWarning
Between session storage of whether to display or suppress a warning when a dimension element is
deleted.
• T (Default)- When a dimension element is deleted, a warning message displays.
• F - No message is displayed when a dimension element is deleted.

ShowDimensionAccessWarning
Between session storage of whether to display or suppress a warning when a dimension is accessed.
• T (Default)- When a dimension is accessed, a warning message displays.
• F - No message is displayed when a dimension is accessed.

ShowDynamicSubsetWarning
Between session storage of whether to display or suppress a warning when a Dynamic Subset is changed.
• T (Default)- When a Dynamic Subset is changed, a warning message displays.
• F - No message is displayed when a Dynamic Subset is changed.

ShowPickOperationWarning
Between session storage of whether to display or suppress a warning when data is copied using the Pick
Elements option.

396 IBM Planning Analytics: Installation and Configuration

• T (Default)- A warning message displays any time data is copied using the Pick Elements option.
• F - No message displays when data is copied using the Pick Elements option.

ShowProcessUNASCIIWarning
Between session storage of whether to display or suppress a warning when an ASCII datasource is
processed.
• T (Default)- When an ASCII datasource is processed, a warning message displays.
• F - No message is displayed when an ASCII datasource is processed.

ShowProcessUNODBCWarning
Between session storage of whether to display or suppress a warning when an ODBC datasource is
processed.
• T (Default)- Any time an ODBC datasource is processed, a warning message displays.
• F - No message displays when an ODBC datasource is processed.

SliceNewWorkbook
Determines how slices are generated from the Cube Viewer.
• T - Inserts slices in a new workbook.
• F (Default) - Inserts slices in a new sheet of the current workbook.

SubsetWindowLayoutInfo
Generates dimension and position coordinates for the Subset Editor window; allows Subset Editor
dimensions and position to be maintained between sessions.
The coordinates are automatically generated when you move or resize the Subset Editor window.

TM1RebuildDefault
Determines if worksheets recalculate on opening by default
By default, when you slice a view into Microsoft Excel from IBM Cognos TM1, the workbook contains a
workbook level named variable, TM1RebuildOption, that is set to 1 by default. This causes the worksheets
in the book to be rebuilt on opening (which forces a recalculation to happen on each sheet in the book).
This action is necessary if the sheets contain Active Forms. If you are not working with Active Forms, you
may not want all workbooks to use this default behavior.
All worksheets recalculate when a Cognos TM1 workbook is opened. The workbook was created by slicing
from Cognos TM1 Perspectives and contains the workbook level named variable TM1RebuildOption =
1.
By default, all new books created by slicing have a workbook level named variable
TM1RebuildOption=1 in them. This makes the workbook rebuild on open, causing a recalculation of all
sheets, which is important for Active Forms but may not be the desired behavior if you are primarily
working with non-Active Form worksheets.
To prevent sheets from using the default to always rebuild when slicing, change TM1RebuildDefault from
T to F (or add TM1RebuildDefault=F if it doesn't already exist) in your [Link] file. When
TM1RebuildDefault=F the books get the workbook level named variable set to TM1RebuildOption=0
on slicing. This is equivalent to how Cognos TM1 worked prior to the introduction of Active Forms.
If this option is set to T or doesn't exist, slicing from a view in Cognos TM1 Perspectives sets the
TM1RebuildOption workbook level named variable to 1 which forces a rebuild on open. If this option is F,
the name variable TM1RebuildOption is set to 0, which does not rebuild. For a particular report, for
example, an Active Form, you can set the name variable to 1 instead of the default 0.

Chapter 16. Configuring and maintaining Planning Analytics Local 397

 By default, a new install does not have the TM1RebuildDefault parameter at all which provides the default
behavior of slicing with TM1RebuildOption=1.

398 IBM Planning Analytics: Installation and Configuration

Chapter 17. Troubleshooting Planning Analytics Local
Troubleshooting is a systematic approach to solving a problem. The goal of troubleshooting is to
determine why something does not work as expected and how to resolve the problem.

Gathering information
Before contacting IBM Support, collect diagnostic data, such as system information, symptoms, log files,
and traces, that are required to resolve a problem. Gathering this information saves time.

IBM Support
You can access IBM support resources from the IBM Support community. Sign in to get help or to open a
case.

Fix Central
Fix Central provides fixes and updates for your software, hardware, and operating system.

IBM Planning Analytics community

Visit the IBM Planning Analytics community to share ideas and solutions with your peers.

What if my TM1 Application Server deployment fails with a Java

heap space error?
If the TM1 Application Server ([Link]) deployment fails with a Java heap space error message, try
adjusting the Java parameters in the WebSphere administrative console.
Note : You may have to reapply this change if you upgrade or modify your installation of WebSphere at a
later date.

Procedure
1. Open the WebSphere administrative console.
• In Windows, click Start > All Programs > IBM WebSphere Application Server > Profiles > [Profile
Name] > Administrative console. Or, go to [Link]
• In UNIX, click Applications > IBM WebSphere > IBM WebSphere Application Server > Profiles >
[Profile Name] > Admin Console. Or, go to [Link]
2. Log in using the WebSphere profile that you used to deploy TM1 Application Server.
The administrative console opens.
3. Click Servers > Server Types > WebSphere application servers.
4. Click the server where you deployed TM1 Application Server.
5. Under Server Infrastructure, click Java and Process Management > Process Definition.
6. Under Additional Properties, click Java Virtual Machine.
7. In the Initial heap size field, type 1024.
8. In the Maximum heap size field, type 2048.
9. Click Apply, and then click OK. Click Save.
10. Restart WebSphere.

© Copyright IBM Corp. 2007, 2021 399

What if I use Microsoft Excel 2007 or earlier .xls worksheets?
IBM TM1 Web versions 10.2.0 and later use the Open XML file formats for Microsoft Excel worksheets
created using Excel 2007 or later.
If you are using existing Microsoft Excel files in the older .xls format, use the TM1 conversion tool to
convert the files. If your original file contained macros, the TM1 conversion tool converts the original file
into a macro-enabled .xlsm file, otherwise it is converted into a standard .xslx file.
The Convert Excel files to OpenXML Excel format option in Cognos TM1 Architect Server Explorer
converts a single .xls worksheet or all worksheets in a folder. Only administrative users have this option
available. The conversion renames the files to preserve as many links as possible after the conversion.
Some links and action buttons need to be updated depending on permissions that may have changed as a
result of the move to cell-based security that occurred in version 10.2.0.
In some cases, the Named Ranges from the original file could be renamed in the converted file during the
conversion process.
By default a backup of the pre-converted worksheets is saved. By default a log file is also generated.

How do I save security rights when importing or restoring a Cognos

TM1 10.2.x application?
In IBM Cognos TM1 Applications 10.2, the operation to save security rights in a Cognos TM1 Application
for the very first time may be significantly slower than in previous releases. You may experience this delay
when performing an upgrade and either manually restoring application files or importing an application
and the related security rights.
This is a known effect of a new security design for TM1 Applications that provides greater application
design flexibility. Specifically, the ability to share an Approval Hierarchy dimension across more than one
application has been added to Cognos TM1 Applications 10.2. Cognos TM1 Applications now also allows
you to deploy multiple applications, independently secured, for different cycles of your business process.
For example, to operate a Budgeting application and a Forecasting application at the same time, based on
the same underlying cube, permitting real-time Budget versus Forecast variances.
It is important to note that the significant performance delay is only seen the very first time that rights are
saved for an application. The rights-saving operation is also performed when manually restoring
application files or when an application is imported in the Cognos TM1 Applications portal and you select
the option to include security rights during the import process.
On subsequent saving of the rights, a differential analysis is performed to ensure that the time taken to
process the rights is a function of the degree of change being made. For example, a small change to the
rights will be processed quickly. This is the key factor in the day-to-day operation of a TM1 Application,
where you are likely to routinely update rights to reflect incremental changes to your business. Large-
scale changes are unusual after an application is in production, so you will see routine changes to the
rights processed quickly.
Note : You previously had to change these rights manually from the Cognos TM1 Performance Modeler or
Cognos TM1 Applications portal user interface. However, the Cognos TM1 10.2 release gives you the
ability to automate these changes from the command line for the first time.

400 IBM Planning Analytics: Installation and Configuration

How do I configure client computers to export TM1 data in PDF
format?
To export IBM TM1 data to Adobe PDF format from IBM Planning Analytics client applications running in
Microsoft Windows, set PDFCamp as your default printer. These steps apply to IBM Cognos TM1
Perspectives, IBM Cognos TM1 Architect, and IBM Cognos TM1 Web.

Before you begin

Verify that PDFCamp is installed correctly by confirming that PDFCamp Printer Driver exists in the
Windows Printers and Faxes configuration.

Procedure
1. In Windows, open the Printers and Faxes configuration window.
2. Right-click PDFCamp Printer Driver and select Set as Default Printer.

What timeout settings can I set?

The following list shows timeout settings that you can set in IBM Planning Analytics. Timeout settings
allow the server to clean up inactive sessions, which frees up resources and memory from services that
are used by active users. Timeouts that are set too high might have a negative impact on your
environment.
TM1 SERVER IDLE
Default: 900 seconds (15 minutes)
Location: [Link]
Setting: IdleConnectionTimeOutSeconds=900
“IdleConnectionTimeOutSeconds” on page 352
TM1 SERVER REST/HTTP
Default: 20 minutes
Location: [Link]
Setting: HTTPSessionTimeoutMinutes=20
“HTTPSessionTimeoutMinutes” on page 352
CAM SECURITY
Default: 3600 seconds (60 minutes)
Location: Cognos Configuration > Security > Authentication
Setting: Inactivity timeout in seconds
“Configuring session timeout values for Cognos TM1 Applications and Cognos Analytics Security” on
page 272
TM1 WEB (2.0.5 or earlier):
Default: 20 minutes
Location: \tm1_64\webapps\tm1web\WEB-INF\[Link]
Setting <session-timeout>20</session-timeout>
Setting the TM1 Web session timeout
TM1 WEB (2.0.6 or later):
Default: 20 minutes
Location: \tm1_64\webapps\tm1web\WEB-INF\configuration\tm1web_config.xml
Setting <add key="HttpSessionTimeout" value="60" />
Setting the TM1 Web session timeout

Chapter 17. Troubleshooting Planning Analytics Local 401

 PMPSVC
Default: 60 minutes
Location: Cognos Configuration > TM1 Applications
Setting: Session timeout (min)
This setting updates the \tm1_64\webapps\pmpsvc\WEB-INF\configuration
\fpmsvc_config.xml session-timeout.
“Configuring session timeout values for Cognos TM1 Applications and Cognos Analytics Security” on
page 272
PLANNING ANALYTICS WORKSPACE PROXY TIMEOUT
Default: 120 seconds (2 minutes)
Location: <paw install>/config/[Link]
Setting: ProxyTimeoutSeconds
“Configure parameters” on page 161
PLANNING ANALYTICS WORKSPACE IDLE TIMEOUT
Default: 60m (60 minutes)
Location: <paw install>/config/[Link]
Setting: SessionTimeout
“Configure parameters” on page 161

How do I fix my Planning Analytics Workspace Local installation?

This section lists the most common errors that you might encounter when you install IBM Planning
Analytics Workspace Local.

Why can't I open Planning Analytics Workspace in a browser?

If you can't access Planning Analytics Workspace in a browser or your Planning Analytics Workspace
services aren't starting up, check your browser for one of the following messages.

Symptoms
One of the following messages appears in your web browser:
• "Planning Analytics Workspace is unavailable. Try again in a few minutes"
• "This site can't be reached"

What to do
Note : All PowerShell commands must be run from an elevated PowerShell session.
1. Make sure that Docker is up and running. Type the following command in a PowerShell window:

- start-service docker

2. Check your Windows Services to make sure "Docker Engine" is running.

3. In a PowerShell window, navigate to the Planning Analytics Workspace installation directory, and type
in the following command.

./scripts/paw.ps1

What to do next
If the issue persists or if the script returns an error, see “How do I handle errors when I run the start
script?” on page 403.

402 IBM Planning Analytics: Installation and Configuration

Why doesn't the Planning Analytics Workspace administration tool start?
If you can't launch the Planning Analytics Workspace administration tool or the administration tool exits
unexpectedly, check the /log/admintool/[Link] for one of the following messages.

Symptoms
One of the following messages appears when the ./scripts/paw.ps1 script runs.
• "Something went wrong at step 'Starting IBM Planning Analytics Administration
Tool' Execution failed with exit code 1"
• "Cannot start service admintool: failed to create endpoint admintool on
network nat: HNS failed with error : Element not found. Encountered errors
while bringing up the project."

What to do
Note : All PowerShell commands must be run from an elevated PowerShell session.
1. Navigate to the Planning Analytics Workspace installation directory, and open the /log/admintool/
[Link] file.
2. If the error message mentions HNS, see “How do I handle errors with the Host Network Service
(HNS)?” on page 404.
3. If the error message doesn't mention HNS, run the following command from a PowerShell window:

./scripts/paw.ps1

What to do next
If the issue persists, see “How do I handle errors when I run the start script?” on page 403.

How do I handle errors when I run the start script?

If running the ./scripts/paw.ps1 script doesn't restart services or returns Host Network Service
(HNS) errors, Windows filter errors, or pa-gateway errors, you can try the following solutions.

Symptoms
One of the following messages appears when the ./scripts/paw.ps1 script runs.
• "C:\Program Files\Docker\[Link]: failed to register layer: re-exec error:
exit status 1: output: ProcessUtilityVMImage C:\ProgramData\docker
\windowsfilter\<id>\UtilityVM: The process cannot access the file because it
is being used by another process"
• "Recreating 32bf8925a845_32bf8925a845_32bf8925a845_admintool Error: for
<service-Name> Cannot start <service-Name>: hcsshim: PrepareLayer failed in
Win32: The handle is invalid. (0x6) layerId=<ID> flavour=1"
• "For pa-gateway Cannot start service pa-gateway: failed to create endpoint
pa-gateway on network nat: HNS failed"
• "HNS failed with error: The file cannot be opened because it is in the
process of being deleted.".
• "Cannot start service <service-Name>: failed to create endpoint <service-
name> on network nat: HNS failed with error: The object already exists." .
• "Cannot Start service <service-name>: Container is marked for removal and
cannot be started"

Chapter 17. Troubleshooting Planning Analytics Local 403

 What to do
Note : All PowerShell commands must be run from an elevated PowerShell session.
1. If you see a windowsfilter error, it is possible that anti-virus software is preventing your Windows
containers from starting. For more information, see Docker for Windows Server fails to pull image or
start container. It is also recommended that you get confirmation from your anti-virus vendor that the
anti-virus software does support Windows containers. If you need to add exclusions to your anti-virus
scanning protocols, the following locations are recommended:
• C:\ProgramData\docker (Or the docker-root location in the [Link] file)
• C:\ProgramData\Microsoft\Windows\HNS
• <Planning Analytics Workspace install location>
2. If the pa-gateway is not starting, make sure that nothing is running on port 80. If port 80 is free and
the issue persists or other containers don't start, try the following commands in a PowerShell window:

• docker container rm <container-name>

• ./scripts/paw.ps1

3. If you see HNS errors, see “How do I handle errors with the Host Network Service (HNS)?” on page
404.

How do I handle errors with the Host Network Service (HNS)?

Sometimes the Docker network gets corrupted and the Host Network Service is affected. You must use
the Microsoft Network cleanup script to resolve your issues.

What to do
Note : All PowerShell commands must be run from an elevated PowerShell session.
1. Get the Microsoft Network Cleanup Script from the MicrosoftDocs Virtualization documentation.
2. Run the cleanup script with the following syntax:

.\WindowsContainerNetworking-LoggingAndCleanupAide.ps1 -Cleanup -ForceDeleteAllSwitches

3. If the cleanup script runs successfully, restart your computer and then run the ./scripts/paw.ps1
script.
4. If the cleanup script fails, run the following commands from PowerShell window:

• docker container run hello-world:nanoserver

• docker run -p 80:80 hello-world:nanoserver

5. If neither of the previous steps resolve the issue, contact Microsoft support for Docker issues. For
more information, see How to get help with your Windows container issues.

What to do next
In some cases, you might need to re-image the server because of a Docker network corruption at the
registry level. Contact IBM Support to discuss available options or any further troubleshooting.

404 IBM Planning Analytics: Installation and Configuration

Why can't I access Planning Analytics Workspace on Windows Server 2016?
If Planning Analytics Workspace is installed on a Microsoft Windows Server 2016 OS, then you must
access it from a different computer. This issue is a limitation of the Microsoft NAT network driver.

Procedure
1. Start a PowerShell Window when Planning Analytics Workspace is running and type the following
command:

docker inspect pa-gateway -f' {{.[Link]}}'

This gives you the internal IP address of your PA-gateway container. For example:

[Link]

2. Access Planning Analytics Workspace from your browser.

This is a dynamic IP address and a new IP address is assigned every time Planning Analytics
Workspace is restarted.
3. To assign a static IP to the PA-gateway container, open a command window and run the following:

scripts/launch.ps1

What do I do if Docker for Planning Analytics Workspace hangs?

The virus protection software that you use must fully support Windows Server 2016 and Docker.
Apply the latest updates to your virus protection software. For more information, see Antivirus software
and Docker ([Link]

Chapter 17. Troubleshooting Planning Analytics Local 405

How do I resolve Planning Analytics Workspace connection issues on
Windows Server 2016?
You might need to resolve issues that can prevent connections from Planning Analytics databases to
Planning Analytics Workspace Local.
Here's a short video that shows you how to resolve issues connecting to Planning Analytics Workspace.
[Link]

How do I change default port numbers for Planning Analytics Workspace on

Windows Server 2016?
You can change default HTTP (80) and HTTPS (443) ports that Planning Analytics Workspace uses on
Windows Server 2016 if you're using them for other services.
Here's a video that shows how to change default HTTP (80) and HTTPS (443) ports for Planning Analytics
Workspace on Windows Server 2016.
[Link]

Procedure
1. Open the config/paw.ps1 file in a text editor.
2. Add the following lines, substituting your preferred ports:

$env:PAGatewayHTTPPort="80"
$env:PAGatewayHTTPSPort="443"

3. Restart Planning Analytics Workspace.

For more information, see “Configure parameters” on page 161.

How do I change the IP configuration of Planning Analytics Workspace

Local?
If you can't access Planning Analytics Workspace Local over a VPN connection, it might be because they
are using the same IP address. You can change the Planning Analytics Workspace Local IP address for the
paw_net network to avoid conflicts.

What to do
To change the subnet for the paw_net network, run the following docker commands:

On Windows 2016
1. stop-service docker
2. get-containernetwork | remove-containernetwork
3. Create the file: C:\ProgramData\docker\config\[Link] with the following contents:

{
"fixed-cidr": "[Link]/24"
}

Where you substitute the desired subnet for paw_net.

4. start-service docker
For more information, see Customize the docker0 bridge.

406 IBM Planning Analytics: Installation and Configuration

 On Linux
1. docker network rm paw_net
2. docker network create -d bridge --subnet [Link]/16 paw_net
Where you substitute the desired subnet for paw_net.
The script scripts/create_network.sh creates the initial paw_net network.
For more information, see Use bridge networks.

What are some common errors when installing Planning Analytics

for Microsoft Excel?
This section lists the most common errors that you might encounter.

Configuration Issues
These issues are related to configuration and setup.

Convert to Formulas does not show value

You can create an Exploration View without experiencing an error, but when you convert that exploration
sheet to formulas, cells no longer display values properly. In one of the cells that has no value, you click
the cell and it shows the COGVAL formula, such as =COGVAL($C$1, $C$2, $B10, C$8, $B$8). Attempting
to do this on another workstation you find that values are displayed correctly. If a user with administrative
rights to the workstation attempts to convert to formulas, the values are displayed correctly in the cells of
the worksheet.
The user did not use Microsoft Excel before IBM Planning Analytics for Microsoft Excel was installed and
did not get registered properly. There are two ways to resolve this problem. You can give the affected user
local administration rights to the workstation or you can run the file Register Cognos [Link], which will
add the proper registry entries for the new user.
For the Register Cognos [Link] file process to work (both during the installation of the software or when
run separately to add a new user) the Microsoft Excel registry entries must have been created by
Microsoft Excel itself. You must ensure that the user run Microsoft Excel first, before attempting to add
registry entries for IBM Planning Analytics for Microsoft Excel. You can examine the [Link] that the
script writes to check whether the user has been properly added.

Update server and package designations to make a server available

After changing the gateway alias or switching from a test to a production environment you receive the
following error message advising you that the server is not available and that the Cognos gateway is
unable to connect to the IBM Cognos Analytics server.
SERVER_NOT_AVAILABLE: The Cognos gateway is unable to connect to the Cognos Analytics server. The
server may be unavailable or the gateway may not be correctly configured.
This is probably caused by a change in the gateway URI.
Update the server and package designation in a workbook to switch from a test to a production
environment or to access information from a different set of financial data, such as a submission.

Procedure
1. Optionally, you can update information in cell references.
• From the worksheet you want to update, open the new server and package.
• From the Information folder, drag the updated server and package metadata to the server or
package cell.

Chapter 17. Troubleshooting Planning Analytics Local 407

 2. Optionally, you can update information in embedded text.
• Use the Microsoft Excel search and replace function to update embedded references in the text of
cell formulas.

The Cognos Office interface fails to initialize in Microsoft Office

IBM Cognos Office may not initialize when the Microsoft .NET Framework is not installed or the version is
not correct. The required Microsoft .NET Framework version is 4.6.1 or later. Another possible reason for
this condition is that the add-in is either not installed or not registered.

If you are running the wrong version of Microsoft .NET Framework, uninstall it and then reinstall
Microsoft .NET Framework.
To install the IBM Cognos add-in, run the installation program.
Before you attempt to install Microsoft .NET Programmability Support, you must have installed
Microsoft .NET Framework.

Cognos for Microsoft Office Fails to Initialize

If you use Internet Explorer to browse IBM Cognos Analytics and open a workbook, document, or
presentation published by IBM Cognos for Microsoft Office, the document launches in Microsoft Office,
but without full functionality.
To configure Internet Explorer to open Microsoft Office files in Microsoft Office instead of in Internet
Explorer, you must use the Folder Options tool to update browse options. It is also possible to do this in
Windows Registry.

Procedure
1. Open My Computer.
2. From the Tools menu, click Folder Options.
3. On the File Types tab, under Registered file types, click Microsoft Excel Worksheet, and then click
Advanced.
The Edit File Type dialog box appears.
4. Clear the Browse in same window check box and click OK.
5. Complete the same steps for Microsoft Office PowerPoint presentations and Microsoft Office Word
documents.

Microsoft Office does not open a Microsoft Office document published from
Cognos Office
If you observe Microsoft Office trying to open a published document twice when you double-click the
workbook, document, or presentation from Microsoft Windows Explorer, the file association is either
corrupted or not installed properly.
There are two options to resolve this issue. You can start the Microsoft Office application first, and then
open the document using the Open command from the File menu, or you can reregister the file type.

Re-register file types with a Microsoft Office program

When you are not able to open a Microsoft Office document even though it is associated with the correct
file type, you must re-register the file type with the appropriate Microsoft Office program, such as Excel,
Word, or PowerPoint.

About this task

In these steps, [Link] is a placeholder for the executable file for the Microsoft Office program that
you want to re-register. If you installed Microsoft Office to another location, use the path that is correct for
that location.

408 IBM Planning Analytics: Installation and Configuration

Note : If you are using the command line on version 7 of Microsoft Windows operating system, you must
elevate the rights of the command line to perform certain tasks, such as re-registering file types. To open
an elevated command prompt, or a command prompt in Administrator mode, right-click the command
prompt shortcut, and select Run as Administrator.

Procedure
1. From the Start menu, click Run.
2. To disassociate the program version, in the Open box, type the following command, and then click OK:
[Link]/regserver
3. To specify the default version, from the Start menu, click Run.
4. In the Open box, type the following command, and then click OK:
[Link]/regserver

Unable to Open Published Microsoft Office Documents from Cognos

Connection
If the browser does not prompt you to open or save the workbook, document, or presentation, it may
mean that the option to prompt before opening was cleared. Reset this option.
You must enable the File Download and Automatic prompting for file downloads in Internet Explorer.

Confirm opening of documents

The procedure to confirm opening of documents is as follows.

Procedure
1. Start the Windows Control Panel.
2. Double-click Folder Options.
3. From the File Types tab, in the Registered file types list, click Microsoft Excel Worksheet, and then
click Advanced.
4. Ensure that the Confirm open after download check box is selected and click OK.
5. Repeat steps 3 and 4 for other Microsoft Office documents that are supported in IBM Cognos Office,
such as Microsoft Office Excel Template, Microsoft PowerPoint Presentation, Microsoft Office
PowerPoint Template, Microsoft Word Document, and Microsoft Office Word Template.
6. Click Close.

Reset internet security options

The procedure to reset internet security options is as follows.

Procedure
1. Start Internet Explorer.
2. From the Tools menu, click Internet Options.
3. From the Security tab, click the Web content zone for which you are updating these options, and then
click Custom Level.
4. Scroll down to the Downloads section and click Enable for the File download and Automatic
prompting for file downloads options.
5. Click OK twice.

.NET Messages are not in the installed .NET Framework language

When you install a non-English version of .NET Framework in a non-English operating system, you will
notice that the error messages, .NET shortcut, and .NET Console are in English.

Chapter 17. Troubleshooting Planning Analytics Local 409

 To solve this issue, you must apply the .NET Framework Language Pack for your language.
The subkey numbers relate to the language. For example, English, French, German, and Japanese are
listed here: 1033=en-en, 1036=fr-fr, 1031=de-de, and 1041=ja. Refer to the Microsoft Support Site to
obtain subkey numbers for other languages.
If you are missing the language pack subkeys, you must install the .NET language pack, which is available
from the Microsoft support Web site.

Workbook closes unexpectedly

If you install the COM add-in and your Microsoft Excel workbook name contains a square bracket, Excel
stops responding or closes unexpectedly after opening.

To resolve this problem, rename the workbook so that it does not contain square brackets.

Reports unavailable in Cognos Connection jobs after using Save As command

in Cognos Report Studio
After opening a report in IBM Cognos Report Studio and saving a copy using the Save As command, you
may find that if the report is included in a job, it is not available in the IBM Cognos Connection portal.
Do not use the Save As command in IBM Cognos Report Studio to save changes when a report is included
in a job. Instead, make a copy of the report, make changes to the copy, and then copy the updated report
to the IBM Cognos Connection portal. Use this method to overwrite the report in the job without breaking
the report links.

The content of the Custom Report shows #NAME?

When building a Custom Report, the content of the cells shows #NAME?

When you drag items from the source tree directly to a cell of a worksheet, you are creating a COGNAME
or COGVAL formula that references the item in the database. This functionality is available only when the
CognosOffi[Link] automation add-in is loaded.
If #NAME? appears in the contents of the cell, it means that the add-in was not loaded and the
[Link] check box in the Add-in dialog box (Tools, Add-Ins) is not selected.
To resolve this issue and ensure that the add-in is always properly loaded, you must verify that the value
of the OPEN registry key is set to /A "[Link]". If you use version 7 of Microsoft
Windows operating system, you must use Run in XP from the command prompt to reregister file types.

Procedure
1. From the Windows Start menu, click Run.
2. In the Open box, type Regedit, and then click OK.
3. In the Registry Editor, go to the Registry branch:
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\version\Excel\Options
4. In the topic area, right-click the OPEN entry, and then click Modify.
5. In the Value Data box, type
/A "[Link]"
6. Click OK, and then close the Registry Editor.

410 IBM Planning Analytics: Installation and Configuration

Processing issues
The following issues are related to processing and rendering reports.

Improve performance for TM1 data

If you experience unacceptable performance when you work with TM1 data, the administrator of the TM1
system might be able to change cube or system settings to improve performance. To help the TM1
administrator evaluate the performance issue, provide the administrator with the details of the data you
are using and a description of actions that result in unacceptable performance.
The following are examples of TM1 settings that affect performance.
VMM (}CubeProperties)
For each cube, this property determines the amount of RAM reserved on the server for the storage of
stargate views. The more memory made available for stargate views, the better performance will be.
Sufficient memory must be available for the TM1 server to load all cubes.
VMT (}CubeProperties)
If the time required to calculate a cube view surpasses the specified threshold, TM1 attempts to store
a stargate view. If there is not enough memory available to store the stargate view, TM1 purges the
oldest stargate view that is not currently in use, and continues to purge views in this manner until
sufficient memory is made available.
The IBM Cognos TM1 Operation documentation includes more information about the CubeProperties and
other tuning options.

DPR-ERR-2079 Firewall Security Rejection

If you run a report after your session has expired and then try to navigate away from the first page of the
report, you encounter an error.
DPR-ERR-2079 Firewall Security Rejection. Your request was rejected by the security firewall. CAF
rejection details are available in the log. Please contact your administrator.
When the DPR-ERR-2079 error occurs after an expired session, you must log on again to resolve the
problem.

Procedure
1. In the report list, right-click the node item, which appears before other items.
2. Click Log On.
3. Provide your authentication credentials as prompted and click OK.

Item cannot be expanded

Microsoft Excel has reached the maximum number of rows or columns for this worksheet. The number of
rows and columns is limited in Microsoft Excel. Expanding the current item is not possible because it
would shift rows or columns beyond this worksheet limit. Microsoft Excel cannot shift nonblank cells off
the worksheet.

Manually move items so that the row or column item can expand without reaching the limit, or move your
Exploration View, list, or report to another worksheet. Or, you can move the data to a new location and try
again.

Results have exceeded the Excel row or column limit

Microsoft Excel has reached the maximum number of rows or columns for this worksheet. The number of
rows and columns is limited in Microsoft Excel. Items are truncated.

Chapter 17. Troubleshooting Planning Analytics Local 411

 Filter items so that the row or column items can be displayed without reaching the limit. Consider creating
additional Exploration Views, lists, or reports to spread the data over more than one worksheet. Consider
using a new version of Microsoft Excel that has larger limits for rows and columns.

Error: Exception from HRESULT:<location>

If you import a data item where the path to the data item exceeds 256 characters it results in the error:
Exception from HRESULT.
You must create names and unique data identifiers that keep to the 256-character limit inside Microsoft
Excel.

Error refreshing exploration saved in earlier version of Microsoft Excel

This workbook may have been created with an older version of Microsoft Excel that has a set maximum
number of rows or columns. Rows or columns that go beyond the maximum limits are truncated.

Although you are no longer using that version, the application is working within the limits of the older
version of Excel. You might encounter this situation when you are expanding items or when you are
refreshing items that have grown in size since the workbook was created.
To correct the problem, you must save the workbook with the .xlsx extension. Opening the workbook that
contains the exploration in a more recent version of Excel does not convert it to the new format. Saving
the workbook with the .xlsx extension converts the workbook to the new format.

Microsoft Excel limits

There are specifications and limits in Microsoft Excel 2013-2016 that may affect the performance of
Planning Analytics for Microsoft Excel.
The following tables group the specifications and limits into categories:
• Worksheet and workbook
• Calculation

Table 35. Specifications and limits that apply to worksheets and workbooks
Specification Maximum limit / restrictions Notes
Column width 255 characters If the data that you enter or receive
exceeds the column limits of
Microsoft Excel, the result is
truncated.
Row height 409 points If the data that you enter or receive
exceeds the row limits of Microsoft
Excel, the result is truncated.
Total number of characters that a 32,767 characters If the data that you enter or receive
cell can contain exceeds the cell character limits of
Microsoft Excel, the result is
truncated.

412 IBM Planning Analytics: Installation and Configuration

Table 35. Specifications and limits that apply to worksheets and workbooks (continued)
Specification Maximum limit / restrictions Notes
Maximum limits of memory storage 32-bit environment is subject to 2 Due to the limitations with add-ins,
and file size for Data Model gigabytes (GB) of virtual address users can only copy and paste once
workbooks space, shared by Excel, the on top of a DBRW formula.
workbook, and add-ins that run in
Adding tables to the Data Model
the same process. A data model’s
increases the file size. If you don’t
share of the address space might
plan to create complex Data Model
run up to 500 – 700 megabytes
relationships using many data
(MB), but could be less if other data
sources and data types in your
models and add-ins are loaded.
workbook, uncheck the Add this
64-bit environment imposes no data to the Data Model box when
hard limits on file size. Workbook you import or create tables, pivot
size is limited only by available tables, or data connections.
memory and system resources.

Table 36. Specifications and limits that apply to calculations

Specification Maximum limit / restrictions Notes
Length of formula contents 8,192 characters If the formula that you enter
exceeds the formula content limit
of Microsoft Excel, the result is
truncated.
Internal length of formula 16,384 bytes If the formula that you enter
exceeds the internal length of
formula limit of Microsoft Excel, the
result is truncated.

Security Issues
The following issues are related to security setup.

Cognos Office Unable to Create Trust Relationship

If you are using HTTPS to Report Data Service and you receive an error in IBM Cognos Office about being
unable to trust the relationship, the Certificate Authority (CA) certificate that was issued by the Web
server is not trusted on the client workstation.
To resolve this problem, you must ensure that the Certificate Authority (CA) that issued the Web server
certificate is also trusted on the client workstation. If the certificate is not from an authority that is already
trusted on the client, such as Verisign, you must install the CA certificate in the trust store on the client.

Procedure
1. Retrieve the CA certificate from the issuing authority.
The file has a .cer extension. This is not the same certificate as the one used by the Web server. It is
the certificate for the issuing authority itself.
2. Double-click the .cer file, click Install Certificate, and then click Next.
3. Click Place all certificates in the following store.
4. Click Browse, click Trusted Root Certification Authorities, and then click Next.
5. Click Finish.

Chapter 17. Troubleshooting Planning Analytics Local 413

 Unable to View Reports After Clicking View Report
IBM Cognos for Microsoft Office is functioning normally, but you cannot use the View Report option to
view reports. The client machine, running IBM Cognos for Microsoft Office, cannot connect to the gateway
URL as configured in IBM Cognos Analytics. This may be because it is behind a firewall, the
hostname/DNS is not known to this client machine, or the client machine has proxy issues.
To resolve the connectivity issues, work with your system administrator.

Cognos Office Numbered Error Messages

The following error messages may appear in a dialog box and are recorded in the IBM Cognos Office log.

COI-ERR-2002 Block type is not valid

An internal processing error occurred. The block object was not able to be processed.
Contact IBM Cognos Resource Center. Be ready to supply all relevant logs and details related to this error.

COI-ERR-2003 Unexpected type: stacked block

An internal processing error occurred. The data object was not of the expected type and could not be
processed.
Contact IBM Cognos Resource Center. Be ready to supply all relevant logs and details related to this error.

COI-ERR-2005 This version of Microsoft Office is not supported

IBM Cognos Office supports only specific versions of Microsoft Office applications.
Load the report content into one of the supported applications and environments.
To review an up-to-date list of environments supported by IBM Cognos Office products, including
operating systems, patches, browsers, web servers, directory servers, database servers, and application
servers, go to the IBM Support Portal for IBM Cognos Analysis for Microsoft Excel or the IBM Support
Portal for IBM Cognos for Microsoft Office.

COI-ERR-2006 This Microsoft Office product is not supported

IBM Cognos Office supports only specific Microsoft Office applications, such as Microsoft Excel, Microsoft
Word, and Microsoft PowerPoint. You cannot load IBM Cognos Office content to another Microsoft Office
application, such as Microsoft Access even when there is an add-in that enables these applications to
interoperate.
Load the report content into one of the supported applications and environments.
To review an up-to-date list of environments supported by IBM Cognos Office products, including
operating systems, patches, browsers, web servers, directory servers, database servers, and application
servers, go to the IBM Support Portal for IBM Cognos Analysis for Microsoft Excel or the IBM Support
Portal for IBM Cognos for Microsoft Office.

COI-ERR-2008 Unable to Retrieve from Resources. Tried '{0}'

An internal processing error occurred.
Contact IBM Cognos Resource Center. Be ready to supply all relevant logs and details related to this error.

COI-ERR-2009 Unable to Perform This Operation Because Microsoft Excel is

in Edit Mode
Report content cannot be refreshed while one of the cells of the workbook is being edited.
Click outside the active cell to return it to a non-edit mode and try again.

414 IBM Planning Analytics: Installation and Configuration

COI-ERR-2010 The name {0} is not valid. A name must not contain both a
quote (") character and an apostrophe (') character
When you create a folder, rename a folder, or publish a document, the name can contain an apostrophe or
a quote, but not both.
To resolve this problem, rename the folder or document. Exclude the apostrophe or quote character from
the name.

COI-ERR-2011 The server did not return the expected response. Check that
the gateway is valid.
This error message is displayed if the value entered in the System Gateway URI box of the Options dialog
box is not a valid IBM Cognos Analytics server.

To resolve this problem, reenter the System Gateway URI with the gateway address for a valid IBM
Cognos Analytics server.

COI-ERR-2013 Unable to load metadata

You may be unable to load metadata because you do not have security rights to all of the items in the
worksheet or because the items were removed or changed on the server.
Ensure that you have security rights to all of the items that you are trying to view. If this does not fix the
problem, ensure that the server and package information are correct and that any items that have been
removed from the source database are also removed from the worksheet.

COI-ERR-2015 There was a problem parsing the MIME encoded server

response. Tried to find the boundary [{0}] but found the boundary [{1}]
instead
While using GZip compression, an option for compressing data that is retrieved from the server, an error
occurred. The codes to decompress the data are missing or unrecognized by IBM Cognos Office.
Turn compression off. Although compression is turned on by default, it can be turned off by setting the
UseGzipCompression property to false in the [Link] file, which, by default, is located
in the Office Connection directory, such as C:\Documents and Settings\user name\Local Settings
\Application Data\Cognos\Office Connection or C:\Users\user name\AppData\Local\Cognos\Office
Connection.
Turn compression off if you need to run tests or perform troubleshooting.
To turn gzip compression off set the following attribute:
<setting name="UseGzipCompression">False</setting>

COI-ERR-2016 Worksheet protected, IBM Cognos styles cannot be populated

If the worksheet is protected, the IBM Cognos styles cannot be applied.
You must unprotect the worksheet for the styles to be applied during a refresh of the data.

COI-ERR-2019 Connection failed

In Planning Analytics for Microsoft Excel, when you try to connect to a IBM Planning Analytics server, the
following error message appears:
COI-ERR-2019 Connection failed. Connection returned an error. Verify that the connection string,
including the server name and port number, is correct.
To resolve this issue, you must configure your antivirus software to allow connections from both
Microsoft .NET Runtime and Microsoft Excel.

Chapter 17. Troubleshooting Planning Analytics Local 415

 COI-ERR-2305 Unable to perform this operation because Microsoft Excel is in
edit mode
Report content cannot be refreshed while one of the cells of the workbook is being edited.
Click outside the active cell to return it to a non-edit mode and try again.

COI-ERR-2307 Login failed

Your user name and password are not correct.
Ensure that you typed a valid user name and password.

IBM Planning Analytics for Microsoft Excel numbered error messages

The following error messages may appear in a dialog box and are recorded in the IBM Cognos Office log.

COR-ERR-2004 Axis specification is not valid

The workbook specification is not capable of being generated because of an anomaly.
To fix the problem, you may attempt to do any of the following:
• Click Undo.
• Click Clear All Data.
• Close the workbook and open it again.
The workbook should now accept data from the source tree.

COR-ERR-2007 Error retrieving from resources. Tried '{0}'

The exploration sheet experienced a bad state.
Contact IBM Cognos Resource Center.

COR-ERR-2009 Name formula is not valid

The COGNAME formula did not parse correctly. It may have been altered manually and may have a
missing argument.
Check the COGNAME formula in the active cell and ensure that it is in the correct format, or optionally,
insert the member from the source tree.

COR-ERR-2010 Formula is not valid

If an argument to a COGNAME or COGVAL formula references a cell and that cell does not contain the
expected string formula you receive this error.
Check the cell and its dependents. Look for #REF or #VALUE in the cell. The contents of the cell may have
accidentally been deleted.

COR-ERR-2011 Invalid range: Please enter a valid range for crosstab or list
The range is not valid or is outside of the range of the data type.
To avoid this limitation, limit your data selections.

COR-ERR-2013 Exploration cannot be converted to formula based because at

least one context item contains a selection
With more than one item in the Context drop zone there is no way for the multiple items to be rendered
into the cells of the worksheet.

416 IBM Planning Analytics: Installation and Configuration

Remove one dimension from the Context drop zone. You must have one item per dimension to convert to
a formula-based analysis.

COR-ERR-2014 Due to Excel worksheet limitations the results may be

truncated
If the data that you receive back exceeds the row or column limits of Microsoft Excel, the result is
truncated. You receive this message to make you aware of the truncation.
To avoid this limitation, limit your data selections.

COR-ERR-2015 The current exploration cannot be rendered at this location on

the worksheet
The exploration cannot write data outside the limits of the current worksheet. Either the exploration is too
large for Microsoft Excel or you have designated a starting location too close to the limit.
Try to move your start location. If that fails to fix the problem, try creating an Exploration View with fewer
rows or columns.

COR-ERR-2016 Unable to retrieve package <Name>

After you selected a package using the Open Package dialog box, an error occurred when trying to
download the package from the server.
This is an internal error.
Contact IBM Cognos Resource Center.

ValueNotInPickList (243)
The value you are trying to commit is not an available option in the picklist.
When entering a value into a report cell, ensure that the value is an available option in the picklist.

Chapter 17. Troubleshooting Planning Analytics Local 417

418 IBM Planning Analytics: Installation and Configuration
Notices
This information was developed for products and services offered worldwide.
This material may be available from IBM in other languages. However, you may be required to own a copy
of the product or product version in that language in order to access it.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that only
that IBM product, program, or service may be used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual property right may be used instead. However, it is the
user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
This document may describe products, services, or features that are not included in the Program or
license entitlement that you have purchased.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can send
license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in
any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of
the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this
one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Software Group

Attention: Licensing

© Copyright IBM Corp. 2007, 2021 419

 3755 Riverside Dr.
Ottawa, ON
K1V 1B7
Canada

Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any
equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have
been made on development-level systems and there is no guarantee that these measurements will be the
same on generally available systems. Furthermore, some measurements may have been estimated
through extrapolation. Actual results may vary. Users of this document should verify the applicable data
for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without
notice, and represent goals and objectives only.
This information is for planning purposes only. The information here is subject to change before the
products described become available.
This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform for
which the sample programs are written. These examples have not been thoroughly tested under all
conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must include a copyright
notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. ©
Copyright IBM Corp. _enter the year or years_.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.
This Software Offering does not use cookies or other technologies to collect personally identifiable
information.

420 Notices
©

Product Information
This document applies to IBM Planning Analytics version 2.0.0 and may also apply to subsequent
releases.

Copyright
Licensed Materials - Property of IBM
© Copyright IBM Corp. 2007, 2020.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule
Contract with IBM Corp.
IBM, the IBM logo, and [Link] are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be
trademarks of IBM or other companies. A current list of IBM trademarks is available on the web in "
Copyright and trademark information " at [Link]/legal/[Link].
The following terms are trademarks or registered trademarks of other companies:
• Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
• Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or
trademarks of Adobe Systems Incorporated in the United States, and/or other countries.
• The registered trademark Linux is used pursuant to a sublicense from the Linux Foundation, the
exclusive licensee of Linus Torvalds, owner of the mark on a worldwide basis.
• UNIX is a registered trademark of The Open Group in the United States and other countries.
• Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle
and/or its affiliates.
• Red Hat®, JBoss®, OpenShift®, Fedora®, Hibernate®, Ansible®, CloudForms®, RHCA®, RHCE®, RHCSA®,
Ceph®, and Gluster® are trademarks or registered trademarks of Red Hat, Inc. or its subsidiaries in the
United States and other countries.
Microsoft product screen shot(s) used with permission from Microsoft.

Notices 421
422 IBM Planning Analytics: Installation and Configuration
Index

Special Characters AdvancedRulesEditor 390

Allow provisioned installs 123
.ats file 317 Allow provisioned updates 123
.ats file type 317 AllowImportCamClients 391
.blb file extension 66 AllowImportCAMClients 267
.cfg file 67, 326 AllowReadOnlyChoreReschedule 337
.cho file extension 66 AllowSeparateNandCRules 84, 337
.cub file extension 66 AllRuleCalcStargateOptimization 338
.dim file extension 66 ApplyMaximumViewSizeToEntireTransaction 338
.dit file extension 66 Architect 66
.exe file type 317 architecture 63, 155
.ini file 67, 389 ASCII characters in directory names 82
.NET Framework AuditLogMaxFileSize 338
troubleshooting 409 AuditLogMaxQueryMemory 339
version 408 AuditLogOn 339
.NET programmability support 408 AuditLogUpdateInterval 339
.pro file extension 66 authentication
.rej file 64 importing groups into TM1 266
.rux file extension 66 integrated login 246
.sub file extension 66 authentication modes 155
.tbu file extension 66 authentication, LDAP 246
.tqu file extension 66 authentication, LDAP diagram 259
.tru file extension 66 authentication, OpenID 246
.vue file extension 66 AutomaticallyAddCubeDependencies 339
.xdi file extension 66
.xlsx worksheet 400
.xru file extension 66
B
#NAME? 410 backing up data 320
backup
Numerics TM1 Applications 321
BrowseDisplayReadsRightToLeft 391
64-bit 73 business analysts
64-bit Windows installation 45 role 199

A C
access CacheFriendlyMalloc 340
privileges, data directory 67 CalculationThresholdFor Storage 340
requirements to install Planning Analytics for Microsoft CAM authentication 156
Excel 204 CAMID 261
requirements to use Planning Analytics for Microsoft CAMPortalVariableFile 340
Excel 205 CAMUseSSL 340
accessibility features 60 certificate
adding a server 98 authority 287
addins, registering 206 revocation 287
additional components 320 store 287
Admin Server 64, 74 Certificate Authority (CA)
AdminHost 336, 390 unable to create trust relationship 413
AdminHost parameter certificates 283
TLS 284 character encoding 94
administration CheckFeedersMaximumCells 340
tm1web_confi[Link] 218 Chrome 257
administrator privileges 82 cipher suites 384
AdminSvrSSLCertAuthority 390 ClassicSliceMode 391
AdminSvrSSLCertID 390 client components 47
AdminSvrSSLCertRevList 390 client installation 45, 141
AdminSvrSSLExportKeyID 390 client software

Index 423
client software (continued) connecting to a server 279
installing 204 connections
upgrading 79 adding 203
ClientCAMURI 341 ConnectLocalAtStartup 391
ClientExportSSLSvrCert 284, 341 convert to formulas
ClientExportSSLSvrKeyID 284, 341 errors 407, 412
ClientMessagePortNumber 341 converting .xls 400
ClientPingCAMPassport 342 CreateNewCAMClients 345
ClientPropertiesSyncInterval 342 cross-frame scripting attacks 129
clients 64, 66 Cube Viewer
ClientVersionMaximum 342 page size 233
ClientVersionMinimum 342 CubeviewerStringWrap 234
ClientVersionPrecision 343 Custom Report
Cognos Analytics security #NAME? errors 410
with TM1 Applications 269
Cognos authentication
defining an administrator 265
D
Cognos Configuration 82, 90, 123 data directory
Cognos Connection 82 access privileges 67
Cognos Connection Folder Name 123 definition 66
Cognos Connection portal 244 local server 67
Cognos Insight multiples 67
installing 85, 148 path 66
logging 152 remote server 67
running 85 required network access 67
Cognos Insight ping frequency (seconds) 123 security 67
Cognos Query Studio 240 data encryption 307
Cognos Report Studio 240 data modelers
Cognos security role 199
administrator considerations 273 Data Tier 70
user considerations 273 Data tier component 47
with TM1 Applications session timeout 272 data tier installation 89
Cognos security passport 261 DataBaseDirectory 345, 391
Cognos TM1 Performance Modeler decrypt 287
installing 143 default printer 401
logging 145 default settings 54
CognosGatewayURI 267, 391 DefaultMeasuresDimension 346
[Link] 344 [Link] 161
[Link] 344 defaults.ps1 161
[Link]filterWithPXJ 344 deploy 70
[Link] 344 deploying
[Link] 345 TM1 Application Server 126
CognosOffi[Link] 206 TM1 Operations Console 135–139
CognosOffi[Link] 206 deployment options 73
CognosTM1InterfacePath 345 DimensionDownloadMaxSize 391
CognosTM1InterfacePath configuration parameter 242 DisableAdminHostEntry parameter 392
[Link] file DisableMemoryCache 346
location 326 DisableSandboxing 346
sample 333 DisableWritebackOnDisconnect parameter 392
Com Add-in DisableWritebackOnTM1Formulas parameter 392
Excel workbook closes unexpectedly 410 Dispatch URI 241
command line 169 Display_Info_DBType_R8 346
components 81 DisplayApplications 392
components modify 322 DisplayChores 393
configuration 57, 161, 406 DisplayControlCubes 393
Configuration DisplayCubes 393
TM1 165 DisplayDimensions 393
Configuration files 58 DisplayExplorerPropertiesWindow 393
configuration parameters DisplayProcesses 393
TM1 Web 219 DisplayReplications 393
configure 82, 90 distributed installation 74
configure login page 225 DistributedPlanningOutputDir 84
configuring components 93 domains
configuring validation 260 account 74

424 IBM Planning Analytics: Installation and Configuration

domains (continued) error messages (continued)
installing without 59 Results have exceeded the Excel row or column limit
DOS command window 275 411
dot as local domain 59 server not available 407
DownTime 347 This item cannot be expanded 411, 412
DPR-ERR-2079 error 411 unable to open published Microsoft Office documents
from IBM Cognos Analytics 409
unable to view reports after clicking view report 414
E ValueNotInPickList (243) 417
editing tm1web_confi[Link] 218 ETLDAP
Enable Business Viewpoint 123 Attributes field 275
Enable macros 83 building LDAP query 278
Enable publish from Cognos Insight 123 configuring LDAP login parameters 277
EnableNewHierarchyCreation 347 connecting to a server 279
EnableSandboxDimension 347 Export button 275
EnableTIDebugging 348 export options 280
encrypt 287 exporting LDAP users to TM1 281
error messages Filter field 275
COI-ERR-2002 Block type is not valid 414 LDAP modified record attribute 281
COI-ERR-2005 this version of Microsoft Office is not LDAP query elements 278
supported 414 mapping LDAP attributes to TM1 fields 280
COI-ERR-2006 This Microsoft Office product is not modifying LDAP attributes 275
supported 414 Results table 275
COI-ERR-2008 Unable to retrieve from resources 414 running from DOS 275
COI-ERR-2009 Unable to perform this operation running in update mode 281
because Microsoft Excel is in Edit mode 414 Search button 275
COI-ERR-2010 The name {0} is not valid. A name must Search DN field 275
not contain both a quote (") character and an Search Scope option 275
apostrophe () character 415 updating TM1 with new LDAP users 281
COI-ERR-2011 The server did not return the expected ETLDAP utility 274
response 415 ETLDAP, LDAP authentication 260
COI-ERR-2016 Worksheet protected, IBM Cognos styles EventLogging 348
cannot be populated 415 EventScanFrequency 348
COI-ERR-2305 Unable to perform this operation [Link] 348
because Microsoft Excel is in Edit mode 416 [Link] 348
COI-ERR-2307 Login Failed 416 [Link] 349
Convert to Formulas does not show value 407 [Link] 349
COR-ERR-2004 Axis specification is not valid 416 ExcelWebPublishEnabled 349, 386
COR-ERR-2007 error retrieving from resources 416 ExpandRowHeaderWidth 393
COR-ERR-2009 Name formula is not valid 416 expired sessions 411
COR-ERR-2010 Formula is not valid 416 export
COR-ERR-2011 Invalid range: Please enter a valid range maximum sheets 233
for crosstab or list 416 ExportAdminSvrSSLCert 394
COR-ERR-2013 exploration cannot be converted to exporting PDF data 401
formula based 416
COR-ERR-2014 Due to Excel Worksheet Limitations the F
Results May Be Truncated 417
COR-ERR-2015 The current exploration cannot be Federal Information Processing Standards (FIPS) 350
rendered at this location on the worksheet 417 file extensions 66
COR-ERR-2016 Unable to retrieve package 417 file types
Error: Exception from HRESULT:<location> 412 registering 408
Excel workbook closes unexpectedly 410 reregistering 408
IBM Cognos Office fails to initialize in Microsoft Internet [Link] 349
Explorer 408 [Link] 350
IBM Cognos Office Fails to Initialize in Microsoft Office [Link] 350
408 financial analysts
IBM Cognos Office unable to create trust relationship role 199
413 finding information xi
Microsoft Office Excel does not open a workbook FIPSOperationMode 350
published from IBM Cognos Office 408 Firefox 257
reports unavailable in IBM Cognos Connection jobs after firewall security rejection 411
using Save As command in IBM Cognos Report Studio Force qualified paths 123
410 fpmsvc_confi[Link] 129

Index 425
G integrated login
}ClientProperties cube 247
Gateway URI 241 access rights 258
GO_Contributor 106 overview 247
GO_New_Stores setting up 248
starting 82, 90 setting up manually 249
GOSALES sample database 106 TM1 Architect 257
group assignments 260 TM1 Perspectives 258
UniqueID field 247
IntegratedLogin 394
H IntegratedSecurityMode 352
heartbeat interval 64 Internet Explorer 257, 408
HTTPPortNumber 351 interoperability 340
HTTPSessionTimeoutMinutes 352 introduction xi
IP address 354
IPAddressV4 353
I IPAddressV6 354
[Link] (installer) 317
IBM Cognos BI gateway addresses 415
iWidgets 340
IBM Cognos Connection
troubleshooting unavailable reports 410
unable to open published Microsoft Office documents J
409
IBM Cognos for Microsoft Office Java
firewall security rejection 411 TLS 304
unable to view reports 414 Java certificate chaining error 167
IBM Cognos Office JavaClassPath 355
failure to initialize in Microsoft Office 408 JavaJVMArgs 355
numbered error messages 414 JavaJVMPath 355
security issues 413
supported Microsoft Office applications 414 K
troubleshooting opening published documents 408
IBM Cognos Office Reporting TM1 Addin 206 Kerberos 378
IBM Planning Analytics for Microsoft Excel keyboard shortcuts
numbered error messages 416 Cognos Configuration 61
identity key 287 keyfile 355
IdleConnectionTimeOutSeconds 352 keylabel 355
iframe injections 129 keystashfile 356
IndexStoreDirectory 352
initialization file 67, 389
Insight
L
TurboIntegrator function restrictions 151 language 74
InSpreadsheetBrowser 394 Language 356
install scenario 81 language codes 95, 96
install TM1 Operations Console on separate machine 136 language configuration 95, 97
installation 54 language for clients 394
installation wizard 204 Language parameter for clients 97
installations Language parameter for server 97
COM add-in 408 languages
unattended 317 troubleshooting pack subkeys 409
installed sample database 105 LDAP
installer program 317 authentication 246, 259
installing building a query 278
IBM Cognos Analytics 315 configuring login parameters 277
IBM Planning Analytics for Microsoft Excel for Microsoft exporting users to TM1 281
Excel 200 mapping attributes to TM1 fields 280
Microsoft .NET Framework 201 modified record attribute 281
Planning Analytics Workspace 158, 160 modifying attributes 275
unattended install 315 running ETLDAP in update mode 281
using transfer specification file (.ats) 315 updating TM1 with new users 281
without user interaction 317 LDAP authentication
installing TM1 clients 141 configuring validation 260
installing TM1 data tier 89 ETLDAP 260
installing TM1 web tier 119 modifying group assignments 260

426 IBM Planning Analytics: Installation and Configuration

LDAP authentication (continued) Microsoft Excel
parameters 259 #NAME? errors 410
[Link] 260 refreshing content, troubleshooting 414, 416
validating users 259 row and column restrictions, resolving 411, 412
LDAP Authentication 258 workbook closes unexpectedly 410
LDAP Load Tool dialog box 275 Microsoft Internet Explorer
LDAPHost 259, 357 cannot initialize IBM Cognos Office 408
LDAPPasswordFile 259, 357 setting security options 409
LDAPPasswordKeyFile 259, 357 Microsoft Windows Server 2016 158
LDAPPort 259, 357 model encryption 307
LDAPSearchBase 259, 357 modify installation 322
LDAPSearchField 259, 358 modifying
LDAPSkipSSLCertVerification 259, 358 group assignments 260
LDAPSkipSSLCRLVerification 259, 261, 358 MTCubeLoad 366
LDAPUseServerAccount 259, 358 [Link] 367
LDAPVerifyCertServerName 259, 261, 358 [Link] 367
LDAPVerifyServerSSLCert 259, 261, 359 [Link] 367
LDAPWellKnownUserName 259, 359 MTFeeders 368
limiting 69 [Link] 368
Linux [Link] 368
installation 92 MTQ 369
start TM1 server 94 [Link] 369
TM1 server installation 91 [Link] 369
Linux installation 45 MTQQuery 370
LoadPrivateSubsetsOnStartup 360 multiple Admin Hosts 64
LoadPublicViewsAndSubsetsAtStartup 360 multiple computer install 89
local machine syntax 59 multiple computer web install 132, 210
local server 67 multiple servers 69
locale setting 74
LocalServerNetworkProtocol 395
locations 54
N
LockPagesInMemory 360 navigation tree
log views node 232
file 64 Negotiate 378
log files 168 NetRecvBlockingWaitLimitSeconds 370
Logging in 140 NetRecvMaxClientIOWaitWithinAPIsSeconds 370
LoggingDirectory 361 new clients 267
login credentials 84 NIST_SP800_131A_MODE 370
login page configuring 225 non-ascii characters and moving 94
login, integrated 247 non-ascii names and locale 94
Logon As 273 non-English operating system
logon rules 273 troubleshooting .NET Framework 409
LogReleaseLineCount 361 non-SSL clients 287
Notifications provider 123
M NTLM 378

MagnitudeDifferenceToBeZero 361
maintain installation 320
O
MainWindowLayoutInfo 395 ODBCLibraryPath 371
MaskUserNameInServerTools 362 ODBCTimeoutInSeconds 371
MaximumCubeLoadThreads 362 OLE DB 73
MaximumLoginAttempts 363 Operations Console
MaximumMemoryForSubsetUndo 363 Cognos security 268
MaximumSynchAttempts parameter 363 OptimizeClient 371
MaximumTILockObject 364 optional [Link] parameter
MaximumUserSandboxSize 364 [Link] 366
MaximumViewSize 364 SaveFeedersOnRuleAttach 377
MDXSelectCalculatedMemberInputs 365 Optional [Link] parameter
[Link] 366 AllowReadOnlyChoreReschedule 337
MessageCompression 366 AllowSeparateNandCRules 337
metadata 64 AllRuleCalcStargateOptimization 338
Microsoft .NET 81 ApplyMaximumViewSizeToEntireTransaction 338
Microsoft .NET Framework AuditLogMaxFileSize 338
installing 201

Index 427
Optional [Link] parameter (continued) Optional [Link] parameter (continued)
AuditLogMaxQueryMemory 339 LDAPWellKnownUserName 359
AuditLogOn 339 LoadPrivateSubsetsOnStartup 360
AuditLogUpdateInterval 339 LoadPublicViewsAndSubsetsAtStartup 360
AutomaticallyAddCubeDependencies 339 LockPagesInMemory 360
CacheFriendlyMalloc 340 LoggingDirectory 361
CalculationThresholdForStorage 340 LogReleaseLineCount 361
CAMUseSSL 340 MagnitudeDifferenceToBeZero 361
CheckFeedersMaximumCells 340 MaskUserNameInServerTools 362
ClientCAMURI 341 MaximumCubeLoadThreads 362
ClientExportSSLSvrCert 341 MaximumLoginAttempts 363
ClientExportSSLSvrKeyID 341 MaximumMemoryForSubsetUndo 363
ClientMessagePortNumber 341 MaximumSynchAttempts 363
ClientPingCAMPassport 342 MaximumTILockObject 364
ClientPropertiesSyncInterval 342 MaximumUserSandboxSize 364
ClientVersionMaximum 342 MaximumViewSize 364
ClientVersionMinimum 342 MessageCompression 366
ClientVersionPrecision 343 MTCubeLoad 366
[Link] 344 [Link] 367
[Link] 344 [Link] 367
[Link]filterWithPXJ 344 [Link] 367
[Link] 344 MTFeeders 368
[Link] 345 [Link] 368
CognosTM1InterfacePath 345 [Link] 368
CreateNewCAMClients 345 MTQ 369
DefaultMeasuresDimension (OLAP may require) 346 [Link] 369
DisableMemoryCache 346 [Link] 369
DisableSandboxing 346 MTQQuery 370
Display_Info_DBType_R8 346 NetRecvBlockingWaitLimitSeconds 370
DownTime 347 NetRecvMaxClientIOWaitWithinAPIsSeconds 370
EnableSandboxDimension 347 NIST_SP800_131A_MODE 370
EventLogging 348 ODBCLibraryPath 371
EventScanFrequency 348 ODBCTimeoutInSeconds 371
[Link] 348 OptimizeClient 371
[Link] 348 OracleErrorForceRowStatus 372
[Link] 349 PasswordMinimumLength 372
ExcelWebPublishEnabled 349 PasswordSource 372
FIPSOperationMode 350 PerfMonIsActive 372
ForceReevaluationOfFeedersForFedCellsOnDataChange PerformanceMonitorOn 373
351 PersistentFeeders 373
HTTPSessionTimeoutMinutes 352 PortNumber 373
IdleConnectionTimeOutSeconds 352 [Link] 373
IndexStoreDirectory 352 [Link] 374
IntegratedSecurityMode 352 [Link] 374
IPAddressV4 353 PrivilegeGenerationOptimization 374
IPAddressV6 354 ProgressMessage 374
IPV6 354 ProportionSpreadToZeroCells 375
JavaClassPath 355 PullInvalidationSubsets 375
JavaJVMArgs 355 RawStoreDirectory 376
JavaJVMPath 355 ReceiveProgressResponseTimeoutSecs 376
keyfile 355 ReduceCubeLockingOnDimensionUpdate 376
keylabel 355 RunningInBackground 377
keystashfile 356 SaveTime 378
Language 356 SecurityPackageName 378
LDAPHost 357 ServerCAMURI 378
LDAPPasswordKeyFile 357 ServerCAMURIRetryAttempts 379
LDAPPort 357 ServerLogging 379
LDAPSearchBase 357 ServerName 379
LDAPSearchField 358 ServicePrincipalName 379
LDAPSkipSSLCertVerification 358 SkipLoadingAliases 380
LDAPSkipSSLCRLVerification 358 SpreadErrorInTIDiscardsAllChanges 380
LDAPUseServerAccount 358 SpreadingPrecision 380
LDAPVerifyCertServerName 358 SSLCertAuthority 382
LDAPVerifyServerSSLCert 359 SSLCertificate 382

428 IBM Planning Analytics: Installation and Configuration

Optional [Link] parameter (continued) Planning Analytics Workspace (continued)
SSLCertificateID 382 configuring 406
StartupChores 382 installing 158, 160
SubsetElementBreatherCount 383 Planning Analytics Workspace administration tool
SupportPreTLSv12Clients 383 command line 169
SvrSSLExportKeyID 383 Planning Analytics Workspace Local
SyncUnitSize 383 configuring 161
[Link] Planning Sample
e 349 starting 82, 90
tlsCipherList 384 [Link] 137
TopLogging 384 [Link] 126, 127
TopScanFrequency 384 port number 203
[Link] 385 port numbers 54
[Link] 385 PortNumber 373
[Link] 385 POWER8 LE
UnicodeUpperLowerCase 385 server 326
UseExcelSerialDate 386 start TM1 server 94
UseExtendedFetch 387 TM1 server installation 91
UseLocalCopiesforPublicDynamicSubsets 386 POWER8 LE installation 45
UserDefinedCalculations 386 [Link] 373
UseSQLFetch 387 [Link] 374
UseSQLFetchScroll 387 [Link] 374
UseSSL 387 prerequisite software 81
UseStargateForRules 387 prerequisites 156
VersionedListControlDimensions 388 PreviousAdminHosts 395
ViewConsolidationOptimization 388 PreviousDataDirectories 395
ViewConsolidationOptimizationMethod 388 Primary Interop Assemblies, See PIAs
ZeroWeightOptimization 389 Primary Interop Assemblies (PIAs)
Optional [Link] parameter SQLRowsetSize 381 installing 201
OracleErrorForceRowStatus 372 Primary Interop Assemblies (PIAs) redistributable package
Outdoors Company 106 installing 202
private key 287
PrivilegeGenerationOptimization 374
P privileges
parameters, tm1web_confi[Link] 218 required to install Planning Analytics for Microsoft Excel
passport 261 204
password required to use Planning Analytics for Microsoft Excel
default for samples 54 205
PasswordMinimumLength 372 privileges in Service Account 59
PasswordSource 259, 372 product codes 315
path data directory 66 ProgressMessage 374
[Link] 161 ProportionSpreadToZeroCells 375
paw.ps1 161 Provisioning URI 123
pdata 66 published documents
PerfMonIsActive 372 opening in Microsoft Office 408
performance unable to open from IBM Cognos Connection 409
TM1 data sources 411 PullInvalidationSubsets 375
Performance Modeler
installing 85 Q
PerformanceMonitorOn 373
PersistentFeeders 373 query elements
PIAs (Primary Interop Assemblies) LDAP 278
installing 201 quotation marks 336
installing subkeys 408
Planning 45
Planning Analytics
R
Cognos security 243 RawStoreDirectory 376
Planning Analytics Administration agent 114–116 ReceiveProgressResponseTimeoutSecs 376
Planning Analytics for Microsoft Excel Red Hat Enterprise Linux 7 160
testing the installation of client components 205 ReduceCubeLockingOnDimensionUpdate 376
uninstalling 205 regional setting 74
user roles and responsibilities 199 Register Cognos [Link] 206
Planning Analytics Workspace remote access 170
accessing 165

Index 429
remote server servers
data directory 67 adding 98
operations 64 Service Account TM1 59
replication connection 274 ServicePrincipalName 379
Report Studio services
saving changes in a job 410 restarting 168
reports starting 168
cell-based with #NAME? errors 410 stopping 168
running IBM Cognos for Microsoft Office reports after Session timeout (min) 123
expired session 411 shortcut keys
unable to view reports in IBM Cognos for Microsoft IBM Cognos Configuration 61
Office 414 ShowAdminHostChangeWarning 396
required [Link] parameter ShowAliasAttributeWarning 396
HTTPPortNumber 351 ShowChoresSchedulingWarning 396
MDXSelectCalculatedMemberInputs 365 ShowCubeReplicationWarning 396
Required [Link] parameter ShowDimDeleteElementWarning 396
AdminHost 336 ShowDimensionAccessWarning 396
CAMPortalVariableFile 340 ShowDynamicSubsetWarning 396
DataBaseDirectory 345 ShowPickOperationWarning 396
requirements ShowProcessUNASCIIWarning 397
to install Planning Analytics for Microsoft Excel 202, ShowProcessUNODBCWarning 397
204, 205 silent installation 315, 317
to upgrade Planning Analytics for Microsoft Excel 79 SkipLoadingAliases 380
to use IBM Cognos Analysis for Microsoft Excel 205 SliceNewWorkbook 397
[Link] 317, 318 software and hardware 45
[Link] file 315 Solaris 59
restore backup files for Oracle 109 SP800-131A encryption standard 370
restore sample database on Db2 107 SpreadErrorInTIDiscardsAllChanges 380
restoring backup sample files for Microsoft SQL 112 SpreadingPrecision 380
restoring data after upgrading 323 SQLRowsetSize 381
revocation 287 SSL parameters
Rich Tier 50, 71 ClientExportSSLSvrCert 341
Rollup 386 ClientExportSSLSvrKeyID 341
Run as Administrator 82 SSLCertAuthority 382
RunningInBackground 377 SSLCertificate 382
SSLCertificateID 382
SvrSSLExportKeyID 383
S UseSSL 387
sample data 204 SSLCertAuthority 284, 382
samples SSLCertificate 284, 382
upgrading 113 SSLCertificateID 284, 382
SaveFeedersOnRuleAttach 377 SSO 165
SaveTime 378 Stargate views 365
saving data 64 start IBM Cognos Configuration 93
sdata 66 starting
SData services 82, 90
starting 82, 90 TM1 Application server 120
security 129, 155, 246 StartupChores 382
security authentication mode SubsetElementBreatherCount 383
TM1 Application Web 121 SubsetWindowLayoutInfo 397
TM1 Applications 246 SupportPreTLSv12Clients 383
security certificates 167 SvrSSLExportKeyID 284, 383
security issues 413 SyncUnitSize parameter 383
SecurityAssignmentWindowLayoutInfo 395
SecurityPackageName 378 T
SentMsgsToServerCountWarning 396
server TEMP system variable 82
multiple 69 testing
server components 47 installation of IBM Cognos Analysis for Microsoft Excel
server not available errror message 407 205
ServerCAMURI 378 ThirdPartyCertificateTool 305
ServerCAMURIRetryAttempts 379 TLS
ServerLogging 379 Cognos Insight 303
ServerName 379 Cognos TM1 Performance Modeler 302

430 IBM Planning Analytics: Installation and Configuration

TLS (continued) TM1 server install on Linux 91
TM1 Admin Server 284 TM1 server install on Unix 91
TM1 Server 284 TM1 server installation on Windows 89
TM1 Web 291 TM1 servers
TLS port 54 connecting 203
tlsCipherList 384 REST APIs 203
TM1 Admin Server TM1 Service Account 59
starting 82, 90 TM1 Web
TLS 284 Cognos security 268
TM1 Admin Server Certificate Version 287 configuration parameters 219
TM1 APIs homepage 227
installing 153 running 84
TM1 Application startup parameters 230
installing on separate computers 75 TLS 291
TM1 Application server UNIX 133
starting 120 web browser configuration 235
TM1 Application Server TM1 Web Tier components 48
deploying on IBM WebSphere 127 TM1_Package_Connector environment variable 242
logging 129 TM1Crypt 310
TM1 Application Service Dispatcher URI 123 [Link] 151
TM1 Application Web [Link]
running 84, 86 location 389
security authentication mode 121 parameters 389
server configuration 121 [Link] file 67, 389
URL 124 TM1RebuildDefault 397
using with multiple TM1 servers 128 [Link] 260
TM1 Applications [Link] file
architecture overview 69 location 326
Cognos Connection portal 244 parameters 336
data tier 70 sample 327
installing on a single computer 74 tm1web_confi[Link]
restoring applications files 325 defined 218
restoring configuration files 325 editing 225
saving security rights 400 startup parameters 230
security authentication mode 246 [Link] 268
using with Cognos Analytics security 270 tm1xfer 94
with IBM Cognos Analytics security 269 Tools 103
with IBM Cognos security session timeout 272 TopLogging 384
TM1 Applications install 70 TopScanFrequency 384
TM1 Architect [Link] 385
running 84 [Link] 385
TM1 components 47 [Link] 385
TM1 data sources transaction log file 64
improve performance 411 transfer specification file (.ats) 317, 318
TM1 integration 239 troubleshooting
TM1 interoperability 239 TLS 167
TM1 iWidgets 340 Troubleshooting 399
TM1 object names 94 TurboIntegrator
TM1 OLE DB 51 restricting function execution 151
TM1 Operations Console TurboIntegrator functions
installing 135 restricting execution of 151
starting 135 types of installations 45
TM1 Package Connector 86, 240
TM1 Package Connector requirements 240
TM1 Perspectives
U
running 83 unattended installation 315, 317, 320
TM1 server UnicodeUpperLowerCase 385
starting on Linux 94 uninstall 172, 320, 322
starting on POWER8 LE 94 uninstalling
starting on UNIX 94 IBM Cognos Analysis for Microsoft Excel 202
TM1 Server Planning Analytics for Microsoft Excel 205
Cognos security 263 UNIX
starting 82, 90 installation 92
TLS 284 server 326

Index 431
UNIX (continued)
start TM1 server 94
TM1 server installation 91
UNIX installation 45
UNIX-related [Link] parameter
ODBCLibraryPath 371
RunningInBackground 377
upgrade 171
upgrade overview 77
upgrade prerequisites 77
upgrading
samples 113
User ID and Password 123
user name
default for samples 54
UserDefinedCalculations 386
username 59
users
adding with ETLDAP 274
UseSQLExtendedFetch 387
UseSQLFetch 387
UseSQLFetchScroll 387
UseSSL 284, 387
UseStargateForRules 387
using Cognos security 267

V
validation 260
variables_TM1.xml 268
VersionedListControlDimensions 388
ViewConsolidationOptimization 388
ViewConsolidationOptimizationMethod 388

W
web application 70
web architecture 68
web client 71
web server 69
Web Tier 70
web tier installation 119
[Link]fig 225
websheet, export sheets 233
websheets 86
WebSphere 126, 127, 136–139
Windows
installation 89
Windows Server 82
wrapping in cells 234

X
x-frame-options 129

Z
zero suppression 365
ZeroWeightOptimization 389

432 IBM Planning Analytics: Installation and Configuration

IBM®