325
IBM Cognos TM1 Version 9.5.2 Operation Guide

IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

  • Upload
    vungoc

  • View
    245

  • Download
    14

Embed Size (px)

Citation preview

Page 1: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

IBM Cognos TM1

Version 9.5.2

Operation Guide

Page 2: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Product InformationThis document applies to IBM Cognos TM1 Version 9.5.2 and may also apply to subsequent releases. To check for newer versions of this document,visit the IBM Cognos Information Centers (http://publib.boulder.ibm.com/infocenter/cogic/v1r0m0/index.jsp).

CopyrightLicensed Materials - Property of IBM© Copyright IBM Corp. 2007, 2011.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.IBM, the IBM logo, ibm.com, TM1, and Cognos are trademarks or registered trademarks of International Business Machines Corp., in manyjurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks isavailable on the Web at www.ibm.com/legal/copytrade.shtml.Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentiumare trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.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 of Sun Microsystems, Inc. in the United States, other countries, or both.Microsoft product screen shot(s) used with permission from Microsoft.

Page 3: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Table of Contents

Introduction 15

Chapter 1: TM1 System Architecture 17TM1 Architecture 17TM1 Admin Server 17

Running the Windows Admin Server 19Running the UNIX Admin Server 20

Specifying the Location of the Admin Host 20Specifying Multiple Admin Hosts 21

TM1 Files 21Data Directory 22

Specifying the Location of the Data Directory 22Specifying Multiple Data Directories 23Required Network Access 23

Chapter 2: TM1 System Configuration 25System Configuration Overview 25The Tm1s.cfg Server Configuration File 26

Location of the Tm1s.cfg File 26Sample Tm1s.cfg File 27

Capability Assignments 28TM1 Contributor Capabilities 29Setting Capabilities 30Understanding the Effect of Blanks in the Capability Assignments 30

Using Persistent Feeders 31Saving data with persistent feeders 31Modifying rules for cubes with feeders 32Handling corrupted or invalidated feeder files 32

Parameters in the Tm1s.cfg File 33AdminHost 33AllowMultiModes 34AllowReadOnlyChore Reschedule 34AllowSeparateNandCRules 34AllRuleCalcStargateOptimization 35AuditLogMaxFileSize 36AuditLogMaxQueryMemory 36AuditLogMaxTempFileSize 37AuditLogOn 37AuditLogUpdateInterval 37CalculationThresholdForStorage 38CAMSSLCertificate 38CheckFeedersMaximumCells 38ClientCAMURI 39ClientPingCAMPassport 39

Licensed Materials – Property of IBM3© Copyright IBM Corp. 2007, 2011.

Page 4: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

CAMPortalVariableFile 39ClientMessagePortNumber 40ClientPropertiesSyncInterval 40ClientVersionMaximum 41ClientVersionMinimum 41ClientVersionPrecision 42CognosInterfacePath 43DataBaseDirectory 43DefaultMeasuresDimension 43DisableMemoryCache 44DisableSandboxing 44DisableWorksheetView 45Display_Info_DBType_R8 45DownTime 46ExcelWebPublishEnabled 46GroupsCreationLimit 47IdleConnectionTimeOutSeconds 47IntegratedSecurityMode 47IPAddress 49JobQueuing 50JobQueueMaxWaitTime 50JobQueueThreadSleepTime 50Language 51LDAPUseServerAccount 51LDAPPasswordFile 51LDAPPasswordKeyFile 51LockPagesInMemory 51LoggingDirectory 52LogReleaseLineCount 52MaximumCubeLoadThreads 52MaximumLoginAttempts 53MaximumMemoryForSubsetUndo 53MaximumSynchAttempts 54MaximumUserSandboxSize 55MaximumViewSize 55MaxUndoHoldLineCount 55MessageCompression 56PasswordMinimumLength 56PasswordSource 56PerformanceMonitorOn 57PersistentFeeders 57PortNumber 57PrivilegeGenerationOptimization 58ProgressMessage 58RawStoreDirectory 59ReceiveProgressResponseTimeoutSecs 59RunningInBackground 60SAPLoggingEnabled 60SAPLogFilePath 61

4 IBM Cognos TM1

Table of Contents

Page 5: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

SaveTime 61SecurityPackageName 61ServerCAMURI 62ServerLogging 62ServerName 62SkipLoadingAliases 63SkipSSLCAMHostCheck 63SpreadingPrecision 63SpreadingPrecision (Consolidated Holds) 64SubsetElementBreatherCount 65SyncUnitSize 65UserDefinedCalculations 66UseSQLFetch UseSQLFetchScroll UseSQLExtenedFetch 66UseSSL 67UseStargateForRules 67ViewConsolidationOptimization 68ViewConsolidationOptimizationMethod 68

The Tm1p.ini Client Configuration File 69Location of the TM1p.ini File 69AdminHost 69AdminSvrSSLCertAuthority 69AdminSvrSSLCertID 69AdminSvrSSLCertRevList 70AdminSvrSSLExportKeyID 70AdvancedRulesEditor 70AllowImportCamClients 70BrowseDisplayReadsRightToLeft 70ClassicSliceMode 70CognosGatewayURI 71ConnectLocalAtStartup 71DataBaseDirectory 71DimensionDownloadMaxSize 71DisplayApplications 71DisplayChores 71DisplayControlCubes 71DisplayCubes 72DisplayDimensions 72DisplayExplorerPropertiesWindow 72DisplayProcesses 72DisplayReplications 72ExpandRowHeaderWidth 72ExportAdminSvrSSLCert 72InSpreadsheetBrowser 73IntegratedLogin 73Language 73LocalServerNetworkProtocol 73MainWindowLayoutInfo 74PreviousAdminHosts 74PreviousDataDirectories 74

Operation Guide 5

Table of Contents

Page 6: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

SecurityAssignmentWindowLayoutInfo 74SentMsgsToServerCountWarning 74ShowAdminHostChangeWarning 74ShowAliasAttributeWarning 74ShowChoresSchedulingWarning 74ShowCubeReplicationWarning 75ShowDimDeleteElementWarning 75ShowDimensionAccessWarning 75ShowDynamicSubsetWarning 75ShowPickOperationWarning 75ShowProcessUNASCIIWarning 75ShowProcessUNODBCWarning 76SliceNewWorkbook 76SubsetWindowLayoutInfo 76

Configuring and Managing Sandboxes in your TM1 Environment 76Memory Usage Considerations for Sandboxes and Personal Workspaces 76Managing Files and Folders for Sandboxes 77TM1 Server Configuration Parameters for Sandboxes 77Understanding Sandbox Differences Among Different TM1 Clients 77

Using Cube Versioning 78Overview 78Enabling Cube Versioning 78

Configuring and Administering Data Reservations 79

Chapter 3: Understanding Cube Dependency 81Changes in Dependency Mapping 81Clearing Cube Dependencies 83Creating Cube Dependencies 83Using AddCubeDependency to Establish Dependencies 83

Debugging and Identifying Cube Dependencies 84

Chapter 4: Remote Server Operations 85Overview of Remote Server Operations 85Setting Up a Remote TM1 Server to Run as an Application 86Setting Up a Remote TM1 Server to Run as a Windows Service 87

Installing a TM1 Server to Run as a Windows Service 87Removing a TM1 Server from Running as a Windows Service 88

Starting a Remote TM1 Server 88Starting a TM1 Server Set Up as a Windows Application 88Starting a TM1 Server Installed as a Windows Service 88Starting a UNIX TM1 Server 89

Connecting to a Remote Server 90Refreshing the List of Remote Servers 90Re-Setting the Admin Host 91Re-Setting Local Server Options 91

Disconnecting from a Remote Server 91Shutting Down a Windows TM1 Server 91

Shutting Down a Windows TM1 Server Running as a Service 92Shutting Down a UNIX TM1 Server 92

Shutting Down a UNIX TM1 Server Running in Background Mode 92

6 IBM Cognos TM1

Table of Contents

Page 7: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Logging Transactions 93Data Backup and Recovery 94Enabling and Disabling Logging 95Viewing the Transaction Log 95Setting Search Lock Limit 96Backing Out Records from the Transaction Log 97Removing Log Files from the Disk 97

Monitoring Server Performance 97Managing Client Connections 98

Broadcasting Messages to Clients 98Disconnecting Clients from the Server 99Shutting Down a Server Remotely 99

Remote Server Memory Management 100About Stargate Views 101

Using TM1 in Bulk Load Mode 101Considerations for Using Bulk Load Mode 101TM1 C API 102TurboIntegrator Process Commands 102

Chapter 5: Replicating Cubes 105Replication Overview 105

Relationships Created by Replication 106Required Access Privileges 109Admin Server Considerations 109Configuring the Tm1s.cfg File to Support Replication 110

Maintaining Replication Connections 110Creating a Replication Connection 110Modifying a Replication Connection 111Deleting a Replication Connection 112

Replication Process 112Replicating a Cube 112Specifying Information about the Replicated Cube 113What Happens when TM1 Replicates a Cube 115

Synchronization Process 115Synchronizing on Demand 116Scheduling Synchronization 116Synchronizing over Unstable or Wide Area Network Connections 117

Chapter 6: System and Performance Monitoring 119Overview of TM1 System and Performance Monitoring 119Using the Admin Server Log 120

Message Severity Levels for Admin Server Logging 120Configuring Admin Server Logging 120Enabling Admin Server Logging 122Viewing the Admin Server Log File 122

Logging Transactions 122Data Backup and Recovery 123Enabling and Disabling Transaction Logging 124Viewing the Transaction Log 124Backing Out Records from the Transaction Log 125

Operation Guide 7

Table of Contents

Page 8: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Removing Transaction Log Files from the Disk 126Troubleshooting: Recovering from a Corrupt Transaction Log File 126

Using the TM1 Server Message Log 127Message Severity Levels 127TM1 Loggers 128Logging Properties File 128Configuring and Enabling Server Message Logging 129Viewing the TM1 Server Message Log 132

Client Logging 134Using the Audit Log 135

Understanding Audit Log Events 135Configuring Audit Logging 137Updating the Audit Log with the Latest Events 137Using the Audit Log Window to View Log Messages 138

Monitoring Server Performance Using Control Cubes 142Enabling Performance Monitoring 142Disabling Performance Monitoring 142Viewing Performance Statistics for Clients, Cubes, and Servers 143

Using the TM1 Top Utility 143Installing TM1 Top 144Configuring the Tm1top.ini File 144Running TM1 Top 146Viewing and Understanding the TM1 Top Display 147TM1 Top Commands 152Canceling a Thread's Processing 153

Using TM1 Performance Counters 154Important Notes about Running TM1 Performance Counter Tools 155Available TM1 Performance Counters 155Viewing TM1 Performance Counters with the TM1 PerfMon Utility 155Viewing TM1 Performance Counters with the Microsoft Windows Performance Monitor 157

Capturing Core Dumps for TM1 Server Crash Analysis 158Debugging Tools for Windows 158

Installing and Running ADPlus 159Running Dr. Watson 163Collecting Files for Analysis Following A TM1 Server Crash 164Transmitting Files to Cognos 164

Chapter 7: Administering IBM Cognos TM1 Web 167IBM Cognos TM1 Web Overview 167IBM Cognos TM1 Web Architecture 167

Accessing Multiple TM1 Servers from IBM Cognos TM1 Web 168Limiting Access to a Single TM1 Server from IBM Cognos TM1 Web 168

Installing and Running IBM Cognos TM1 Web 169Software Requirements 169Installing the IBM Cognos TM1 Web Software 169Configuring Language Settings in Microsoft Internet Explorer 170Displaying and Entering Numbers Based on Regional Settings 170Configuring Microsoft Internet Explorer for IBM Cognos TM1 Web 171Running IBM Cognos TM1 Web in Mozilla Firefox Web Browser 171

8 IBM Cognos TM1

Table of Contents

Page 9: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Running the 64-bit version of IBM Cognos TM1 Web on Windows x64 173Running IBM Cognos TM1 Web on a WAN Server and Exporting Excel and PDF Files 173Using ClearType on TM1 Web Server to Enhance Display and Rendering of Websheets 174Configuring TM1 Web to Run in Windows Vista 175

Administering the TM1 Server from IBM Cognos TM1 Web 176Administering Processes 177Administering Chores 178Setting Client Properties 180Setting Cube Properties 180Setting Dimension Properties 181

Changing Your Password 181Configuring a Custom Homepage for IBM Cognos TM1 Web 181

Configuring Different Homepages for Individual Users 182Configuring a Global Homepage for All Users 184

Modifying IBM Cognos TM1 Web Configuration Parameters 186Editing the Web.Config File 187Configuring TM1 Workflow Parameters 188Displaying the Custom Toolbar 190Displaying the Content of the Custom Toolbar 190Changing the Height of the Custom Toolbar 190Displaying or Hiding the Views Node in the Navigation Pane 191Displaying or Hiding the Administration Node in the Navigation Pane 191Changing the IBM Cognos TM1 Web Session Timeout 192Changing the Cube Viewer Page Size 193Setting the Maximum Number of Sheets to Export from a Cube Viewer 194Adjusting the HttpRuntime ExecutionTimeout Parameter 194Setting the TM1ExcelServicePortNumber Parameter 195Configuring the Login Page using the AdminHostName and TM1ServerName Parame-

ters 195Configuring IBM Cognos TM1 Web Startup and Appearance Settings 196Using the CustomLink Parameter to Open Other URLs and Web Pages 198Configuring the IBM Cognos TM1 Web Virtual Cache Directory 199Controlling Chart Scaling and Increments with the SmartAxisEnabled Parameter 200Enabling the Websheet Paging Toolbar 200

Setting Web Permissions 201Modifying the IBM Cognos TM1 Web Virtual Directory to Allow Anonymous Access 201Setting Security for IBM Cognos TM1 Web Folders 202

Performing Web Folder Maintenance 203Using IBM Cognos TM1 Web Logging 203

Message Severity Levels for IBM Cognos TM1 Web Logging 203IBM Cognos TM1 Web Log 204TM1 Excel Services Log 206

Multiple Skin Support in IBM Cognos TM1 Web 208Overview 208Configuration 209Creating Your Own Custom Skins for TM1 Web 211

Chapter 8: TM1 Security Overview 213Authentication 213

Operation Guide 9

Table of Contents

Page 10: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

TM1 Authentication 213Integrated Login 214LDAP Authentication 214

TM1 Object Security 215

Chapter 9: ETLDAP Utility 217ETLDAP Utility Overview 217Using ETLDAP 217

Modifying LDAP Attributes 218Running ETLDAP 219Configuring the LDAP Login Parameters 221Understanding the Elements of an LDAP Query 222Building an LDAP Query 224Connecting to the TM1 Server 224Mapping LDAP Attributes to TM1 Fields 225Specifying the ETLDAP Export Options 225Exporting LDAP Information to TM1 226

Updating TM1 with New LDAP Users 226Determining Last Modified Record Attribute 227Running ETLDAP in Update Mode to Add New LDAP Users 227

Chapter 10: Integrated Login 229What Is Integrated Login? 229Setting Up Integrated Login During Installation 229

Select Integrated Login Option During TM1 Installation 230Run the ETLDAP Utility 231Set Access Rights for TM1 Users 231

Manually Configuring Integrated Login for the TM1 Server 232Manually Configuring Integrated Login for TM1 Web 232

Editing the Web.config File for Integrated Login with TM1 Web 233Configuring IIS for Integrated Login with TM1 Web 233Configuring Folder Security for Integrated Login with TM1 Web 234Configuring Integrated Login for TM1 Web Using NTLM 234Configuring Integrated Login for TM1 Web Using Kerberos 235Configuring Web Browsers for Integrated Login and TM1 Web 241Additional Resources for Configuring TM1 Web for Integrated Login 242

Configuring and Logging into TM1 Clients with Integrated Login 242Configuring TM1 Architect to use Integrated Login 243Configuring TM1 Perspectives to use Integrated Login 243Logging into TM1 Web with Integrated Login 243

Chapter 11: LDAP Authentication 245Validating Users with an LDAP Server 245LDAP Authentication Parameters 245

PasswordSource 245LDAPPort 245LDAPHost 245LDAPWellKnownUserName 246LDAPSearchBase 246LDAPSearchField 246

10 IBM Cognos TM1

Table of Contents

Page 11: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

LDAPUseServerAccount 246LDAPPasswordFile 246LDAPPasswordKeyFile 247

Configuring LDAP Validation 247Run the TM1 Installation Wizard and Select LDAP Authentication 247Change the Parameter in TM1s.cfg to TM1 247Run the ETLDAP Utility 248Modify Group Assignments for New Users 248Change the PasswordSource Parameter in TM1S.cfg to LDAP 248

Chapter 12: Using IBM Cognos 8 Security with TM1 251IBM Cognos 8 Security Overview 251Setting Up the TM1 Server to Use IBM Cognos 8 Security 252

Configuring the TM1 Server 252Configuring the TM1 Client 254Defining a Cognos User to Function as a TM1 Administrator 255Importing Cognos Groups into TM1 256Creating Users 257Administering TM1 Object Security 257Configuring TM1 Web to Use IBM Cognos 8 Security 257Logging in to TM1 Top 257Administrator Considerations When Using IBM Cognos 8 Authentication 257User Considerations When Using IBM Cognos 8 Authentication 258

Chapter 13: Running TM1 in Secure Mode Using SSL 261Overview of Running TM1 in Secure Mode Using SSL 261TM1-Generated Certificates 262Configuring the TM1 Admin Server to Use SSL 262Configuring the TM1 Server to Use SSL 264Configuring TM1 Clients to Use SSL 267Configuring the TM1 Top Utility to Use SSL 268Configuring TM1 Web to Use SSL 269Configuring the TM1 C API to Use SSL 270Configuring the TM1 Java API to Use SSL 270Configuring the TM1 ETLDAP Utility to Use SSL 270Using Independent Certificates 271

Using the Windows Certificate Store 271Using the File System 276

Chapter 14: Managing Users and Groups 277TM1 Users and Groups Security Overview 277

Implementing a TM1 Security Scheme 277TM1 User and Group Security Examples 278

Understanding Administrative Groups and Authority 278ADMIN Group 279SecurityAdmin Group 279DataAdmin Group 280

Adding and Deleting Users and Groups 281Adding a User 281Adding a Group 282

Operation Guide 11

Table of Contents

Page 12: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Deleting a User 282Deleting a Group 283

Assigning Users to Groups 283Membership in Multiple Groups 283

Securing TM1 Data 283Restricting Access to the Data Directory 284Assigning Passwords 284Using Standard Security for Passwords 284

Setting and Clearing Passwords 284Setting a Password 284Clearing a Password 285Changing a Password 285

Setting an Expiration for a User 286

Appendix A: Control Cubes 287Security Control Cubes 287

}CellSecurity_CubeName 287}ChoreSecurity 288}ClientSecurity 288}CubeSecurity 289}DimensionSecurity 289}ElementSecurity_DimensionName 290}ProcessSecurity 291

Client and Group Administration Control Cubes 291}ClientsGroups 291}ClientProperties 292

Object Attribute and Property Control Cubes 293}ConnectionProperties 293}CubeProperties 293}DimensionProperties 294}DimensionAttributes 295}ElementAttributes_DimensionName 295}HierarchyProperties 296

Performance Monitoring Control Cubes 296}StatsByClient 297}StatsByCube 297}StatsByCubeByClient 298}StatsForServer 299

Other Control Cubes 299}Hold_UserName_CubeName 300

Appendix B: Control Dimensions 301}Chores 301}ClientProperties 301}Clients 302}ConnectionProperties 302}Connections 303}CubeFunctions 303}CubeProperties 303}Cubes 305

12 IBM Cognos TM1

Table of Contents

Page 13: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

}DimensionAttributes 305}DimensionProperties 305}Dimensions 306}ElementAttributes_DimensionName 306}Groups 306}Hierarchies 306}HierarchyProperties 306}Hold 307}PerfClients 307}PerfCubes 308}Processes 308}StatsStatsByClient 308}StatsStatsByCube 309}StatsStatsByCubeByClient 309}StatsStatsForServer 310}TimeIntervals 310

Appendix C: Excel Events Handled by TM1 313

Index 315

Operation Guide 13

Table of Contents

Page 14: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

14 IBM Cognos TM1

Table of Contents

Page 15: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Introduction

This document is intended for use with IBM® Cognos® TM1®.

This document describes TM1 architecture, server operations, authentication, and component

security.

Business Performance Management is the continuous management and monitoring of Financial,

Operational, Customer and Organizational performance across the enterprise. Business Performance

Management solutions have the following capabilities to facilitate the proactive steering of business

direction:

● Wide deployment

● Collaborative decision making

● Continuous and real-time review and refinement

● Monitoring of Key Performance Indicators

IBM Cognos TM1 integrates business planning, performance measurement and operational data

to enable companies to optimize business effectiveness and customer interaction regardless of

geography or structure. TM1 provides immediate visibility into data, accountability within a col-

laborative process and a consistent view of information, allowing managers to quickly stabilize

operational fluctuations and take advantage of new opportunities.

Audience

The TM1 Operations Guide is written for TM1 system administrators who want to gain a basic

understanding of TM1 architecture, server operations, authentication, and component security. To

use this guide, you should have a system administration background.

Finding information

To find IBM® Cognos® product documentation on the web, including all translated documentation,

access one of the IBM Cognos Information Centers at http://publib.boulder.ibm.com/infocenter/

cogic/v1r0m0/index.jsp. Updates to Release Notes are published directly to Information Centers.

You can also read PDF versions of the product release notes and installation guides directly from

IBM Cognos product disks.

Samples disclaimer

The Great Outdoors Company, GO Sales, any variation of the Great Outdoors name, 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 appli-

Licensed Materials – Property of IBM15© Copyright IBM Corp. 2007, 2011.

Page 16: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

cations. Product names referenced may be the trademarks of their respective owners. Unauthorized

duplication is prohibited.

Accessibility features

This product does not currently support accessibility features that help users with a physical disability,

such as restricted mobility or limited vision, to use this product.

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.

16 IBM Cognos TM1

Introduction

Page 17: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 1: TM1 System Architecture

This section describes the basic data structures that define IBM® Cognos® TM1®.

TM1 ArchitectureIBM® Cognos® TM1® employs a distributed, client-server architecture that consists of the IBM

Cognos TM1 server to which a combination of the following clients can connect:

● TM1 Perspectives

● TM1 Architect

● TM1 Client (limited version of TM1 Perspectives)

● TM1 Web client

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 servers to obtain

different kinds of data. TM1 clients are described in detail in the IBM® Cognos® TM1® Users Guide.

TM1 Perspectives and TM1 Architect can connect to a local IBM Cognos TM1 server, which acts

as a repository for private TM1 data. If you have the proper authority, 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 Clientare standard TM1 clients. In a normal LAN/WAN

environment, these clients all communicate with a remote server using the TCP/IP network protocol.

TM1 Admin ServerThe 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 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 following diagram shows how clients and servers use the Admin Server.

Licensed Materials – Property of IBM17© Copyright IBM Corp. 2007, 2011.

Page 18: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

TM1 Clients

3 2 3

1 1

TM1 Admin ServerTM1 Server TM1 Server

1. TM1 Servers register with the Admin Server.

2. TM1 clients contact the Admin Server and receive information about the TM1 Servers that are available.

3. After determining which servers are available, TM1 clients establish connections with TM1 Servers.

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 Tm1s.cfg 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 TM1 servers on the network by listening for notification from

the servers. 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 the TM1

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.

18 IBM Cognos TM1

Chapter 1: TM1 System Architecture

Page 19: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

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.

Running the Windows Admin ServerBy default, the TM1® Installation Wizard installs the Admin Server as a Microsoft® Windows®

service. The service is configured to start automatically when your operating system starts, and to

use the logon account and password you supplied during installation.

To remove the TM1 Admin Server Windows service, run Tm1admsd -remove from a command

prompt. Tm1admsd is located in the install_dir\bin directory.

Running the Windows Admin Server as an Application

All that is required to run an Admin Server as an application is the Tm1admsrv.exe executable file.

This file is placed in the install_dir\bin directory when you install TM1®. You can run the Admin

Server by double-clicking the Tm1admsrv.exe file, but we recommend that you create a shortcut

to the executable file in the Startup directory on the Admin Host. That way, the Admin Server is

launched whenever the Admin Host starts.

Steps to Add Tm1admsrv.exe to an Admin Host Startup Directory

1. Click the Start button on the Windows taskbar.

2. Choose Settings, Taskbar.

3. Click the Start Menu Programs tab.

4. Click Add.

The Create Shortcut dialog box opens.

5. Enter the full path to Tm1admsrv.exe in the Command line field, or click Browse to navigate

to the file.

6. If necessary, specify a command line parameter to set the heartbeat interval for the Admin

Server.

DescriptionParameter

Sets the heartbeat interval, in seconds, for TM1 servers registered

with the Admin Server.

- h

The default heartbeat interval is 60 seconds.

7. Click Next.

The Select Program Folder dialog box opens.

8. Select Startup.

Operation Guide 19

Chapter 1: TM1 System Architecture

Page 20: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

9. Click Next.

The Select a Title dialog box opens.

10. Type a name for the shortcut and click Finish.

Viewing Admin Server Status

When an Admin Server is running as an application on an Admin Host, an icon is appended to the

Windows system tray.

To view the current status of the Admin Server, double-click the icon.

The IBM® Cognos® TM1® Admin Server window shows the following information:

● Time at which the Admin Server was started

● Machine on which it is running

● Port being used

● Details of each TM1 server currently registered with the Admin Server

To shut down an Admin Server running as an application, click Stop Admin Server.

You cannot view the status of an Admin Server running as a Windows service.

Running the UNIX Admin ServerTo start the UNIX® version of the TM1® Admin Server, run tm1admsrv.exe from the install_dir/bin

directory.

Viewing Admin Server Status Report

To view an Admin Server status report, run tm1admstat.exe from the install_dir/bin directory.

The Admin Server report contains the following information:

● Time at which the Admin Server was started

● Machine on which it is running

● Port being used

● Details of each TM1® server currently registered with the Admin Server

Specifying the Location of the Admin HostYou specify the location of the Admin Host differently for clients and remote servers.

● Specify the Admin Host referenced by clients in the AdminHost parameter of the Tm1p.ini file.

You can change the Tm1p.ini file by using the TM1® Options menu in Server Explorer.

For more information on the Tm1p.ini file, see "The Tm1p.ini Client Configuration File" (p. 69).

20 IBM Cognos TM1

Chapter 1: TM1 System Architecture

Page 21: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Specify the Admin Host with which remote servers register by using either the AdminHost

parameter in the Tm1s.cfg file or the -v command-line parameter when you bring up the Win-

dows® TM1® server.

For information on server parameters, see "The Tm1s.cfg Server Configuration File" (p. 26).

Specifying Multiple Admin HostsYou can set a TM1® client to reference multiple Admin Hosts by separating host names with

semicolons.

A client that specifies multiple Admin Hosts can access any TM1 servers that are registered with

the Admin Servers on the specified hosts.

TM1 FilesTM1® requires numerous object and system files, most of which are stored in the TM1 server's

data directory. Some of these are installed with the product, while others are generated for each

dimension and cube you create. Yet other files are generated by TM1to 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 section.

DescriptionFile Extension

Cube formatting file.blb

Chore definition file.cho

Cube database file.cub

Compiled dimension.dim

ASCII dimension source file.dit

TurboIntegrator process definition file.pro

Compiled rule.rux

Dimension subset.sub

ASCII source for view file.tbu

Saved query.tqu

ASCII source for a rule file.tru

Operation Guide 21

Chapter 1: TM1 System Architecture

Page 22: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionFile Extension

Saved view.vue

Excel dimension worksheet.xdi

Excel rule worksheet.xru

Data DirectoryThe data directory contains the cubes, dimensions, and system information that are loaded into

memory when a 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 (Tm1s.log). 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 choose Save Data from the

pop-up menu. This directs TM1 to save the changes to the selected server.

● An administrator chooses File, Save Data All in Server Explorer. This directs TM1 to save 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.

Default PathData Directory

install_dir\custom\tm1data\pdataTM1 local server

install_dir\custom\tm1data\sdataWindows® TM1 remote

server for sample data

install_dir/custom/tm1data/sdataUNIX® TM1 server

Specifying the Location of the Data DirectoryYou 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 Tm1p.ini file.

You can change the.ini file by using the TM1® Options menu in Server Explorer.

For more information, see "The Tm1p.ini Client Configuration File" (p. 69).

22 IBM Cognos TM1

Chapter 1: TM1 System Architecture

Page 23: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● For a remote server, specify the location of the data directory by using either the DatabaseDi-

rectory parameter in the Tm1s.cfg file or the -d command-line parameter when you bring up

the server.

For information on server parameters, see "The Tm1s.cfg Server Configuration File" (p. 26).

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.

Note: 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 TM1 server will not be able to start and

the following error displays.

"Data Directory not specified. Aborting server startup."

Specifying Multiple Data DirectoriesYou can specify that you want TM1 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 Tm1s.cfg 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.

Required Network AccessA client's ability to save data is determined by the TM1® security scheme, as described in the IBM®

Cognos® TM1® Developers Guide.

We strongly recommend that you make this directory visible only to administrators and to the login

that is used by the server.

Operation Guide 23

Chapter 1: TM1 System Architecture

Page 24: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

24 IBM Cognos TM1

Chapter 1: TM1 System Architecture

Page 25: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 2: TM1 System Configuration

This section describes how to configure the IBM® Cognos® TM1® server and clients.

System Configuration OverviewUse the following components and features to configure the IBM® Cognos® TM1® server and clients.

DescriptionConfiguration

A configuration file that specifies environment information for

the TM1® server.

Tm1s.cfg file

You can edit the Tm1s.cfg file to reflect the environment of the

associated server.

For details about the file, see "The Tm1s.cfg Server Configuration

File" (p. 26)

For an alphabetical listing of all the parameters in the server

configuration file, see "Parameters in the Tm1s.cfg File" (p. 33).

A set of capabilities that administrators can enable or disable by

user group.

Capability Assignments

Capabilities allow you to manage options such as Personal

Workspace Writeback Mode, Sandboxes, Data Reservation, and

access to Server Explorer.

For details, see "Capability Assignments" (p. 28)

A parameter that can improve reload time of cubes with feeders,

especially those with many complex feeder calculations, by saving

feeders and then re-loading them at server startup without recal-

culating those feeders.

Persistent Feeders

For details, see "Using Persistent Feeders" (p. 31)

A configuration file that specifies the environment information

for the TM1® clients (TM1 Perspectives, TM1 Architect, and

Client).

Tm1p.ini file

For details, see "The Tm1p.ini Client Configuration File" (p. 69)

Licensed Materials – Property of IBM25© Copyright IBM Corp. 2007, 2011.

Page 26: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionConfiguration

A feature that allows users to create and work in their own data

areas separate from base data.

Sandboxes

Administrator tasks for this feature include understanding the

feature and its memory usage, enabling the necessary configura-

tion parameters and managing related files and folders.

For details, see "Configuring and Managing Sandboxes in your

TM1 Environment" (p. 76)

A server-related feature that allows for greater concurrency of

read and write operations on the same cube object. Cube Version-

ing helps to keep writers to a cube from being blocked waiting

for readers of the same cube to finish their read operation.

Cube Versioning

For details, see "Using Cube Versioning" (p. 78)

A server-related feature that allows you to configure exclusive

write-access to regions of a cube for individual users. Once

reserved, the data in that region can only be modified by that

specific user until the reservation is released.

Data Reservation

For details, see "Configuring and Administering Data Reserva-

tions" (p. 79)

The Tm1s.cfg Server Configuration FileThe Tm1s.cfg file is an ASCII file that specifies environment information for a TM1® server. A

default Tm1s.cfg file is created in the TM1 server data directory when you install a copy of the

TM1 server. You can edit the Tm1s.cfg file to reflect the environment of the associated remote

server.

For an alphabetical listing of all the parameters in the server configuration file, see "Parameters in

the Tm1s.cfg File" (p. 33).

Location of the Tm1s.cfg FileThe location of the Tm1s.cfg file depends on the type of server you are using.

● If you are running the TM1® remote server as a Microsoft® Windows® service (Tm1sd.exe),

and you used the TM1 installation program to install the server, the system uses the Tm1s.cfg

file that is located in the server data directory you specified during installation.

● If you are running the TM1 remote server as a Windows application (Tm1s.exe), you specify

the location of the Tm1s.cfg file by using the -z parameter in the command line when you start

the server, either from a shortcut or from a command prompt.

26 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 27: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

For example, this command specifies that TM1 will use the Tm1s.cfg file located in the

c:\salesdata directory:

c:\ProgramFiles\Cognos\TM1\bin\tm1s.exe-z c:\salesdata

If the -z parameter points to a directory containing spaces, you must enclose the directory in

double quotes. 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 Tm1s.cfg file that is located in the server data directory

you specified during installation.

Sample Tm1s.cfg FileThis is a sample Tm1s.cfg file.

#Security mode

#(there are typically some information comments here.)

[TM1S]

ServerLogging=F

SecurityPackageName=Kerberos

IntegratedSecurityMode=1

UseSSL=T

ServerName=Planning Sample

DataBaseDirectory=C:\Program Files\Cognos\TM1\Custom\TM1Data\PlanSamp\

AdminHost=xxxxxxxx

PortNumber=12345

ClientMessagePortNumber= 5433

Language=ENG

SaveTime=

DownTime=

ProgressMessage=True

AuditLogOn=F

AuditLogMaxFileSize= 100 MB

AuditLogUpdateInterval=60

#ServerCAMURI=http://L3L0833-6457A26:9300/p2pd/servlet/dispatch

#ClientCAMURI=http://L3L0833-6457A26/cognos8/cgi-bin/cognos.cgi

#ClientPingCAMPassport=900

#Optional CAM parameters

#CAMSSLCertificate=

#CAMSSLCertRevList=

#SkipSSLCAMHostCheck=TRUE

#SkipSSLCAMHostCheck=TRUE

Operation Guide 27

Chapter 2: TM1 System Configuration

Page 28: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Capability AssignmentsAdministrators can set certain capabilitites by usergroup using the Capability Assignment menu

found in the Server Explorer, Server Menu. With the Server Explorer open, select a server to display

the Server Menu and select Capability Assignments.

By default all assignments are blank. The blank settings have different implications for each capa-

bility. Changes made to these assignments take effect after you log out of TM1® then log back in.

Be sure to save the settings to the server to have changes take effect.

The following capabilities can be set per usergroup:

● Block Access to Server Explorer

To prevent this usergroup from using the Server Explorer, click the interesection of this capa-

bility and the usergroup and select Grant. The choice to grant this capability blocks access to

the Server Explorer.

By default this capability is set to Deny. When this capability is blank or when Deny is explicitly

set, this usergroup launches the Server Explorer.

● Personal Workspace Writeback Mode

This capability defines how data changes are handled in this usergroup.

When this capability is granted, users have the ability to hold data changes in a private workspace

before manually deciding when to commit the changes to the base data. Users can further be

granted the ability to name and manage multiple private scenarios called sandboxes (see the

Sandbox Capability).

When Personal Workspace Writeback Mode is granted:

● Users operate in a non-direct writeback situation so they can privately adjust data values

before making them available to the rest of the community. The special sandbox used when

Personal Workspace Writeback Mode is granted makes it easy to try out different data

changes without the complexity of named sandboxes.

● Data that is changed displays in a different color to remind the user that this change has

not yet been merged to the base data. Once the data change in a Personal Workspace is

committed, the cell coloring reverts to black to identify it as part of the base data.

● Users must manually commit their data changes to make them available to other users. If

users are not used to working in a sandbox, for example, if they were used to the classic

direct writeback mode of earlier versions of TM1, they may find it challenging to remember

to commit their changes manually by pressing the Commit button.

● Often working in Personal Workspace mode improves performance over working in direct

writeback since changes to the base data occur less frequently than when every data change

must be merged to the base.

When this capability is set to Deny, the users do not have a Personal Workspace writeback so

they work directly in the base. This is the default behavior for this capability. The advantage

to this capability setting is that data changes happen immediately, but many users want the

flexibility to control when to commit their changes and make them available to other users.

28 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 29: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

By default, usergroups do not have the Personal Workspace Writeback mode capability granted.

By default this capability is blank which acts like a Deny.

To enable a usergroup to use a Personal Workspace, click the interesection of the usergroup

and this capability and select Grant.

Note also that usergroups may Deny the Personal Workspace Writeback Mode capability but

still use the Sandbox capability. In that case, users work directly in the base but have the option

to save changes to a named sandbox. When they create a named sandbox, then the Commit

and reset Data buttons become available. If they move back to the Base, they return to direct

writeback. See Setting Capabilities for the possible option combinations of Personal Workspace

Writeback Mode and Sandbox capabilitites.

If the system-wide ability to have sandboxes is turned off using the DisableSandboxing=T in

the server configuration file, the Personal Workspace Writeback Mode and Sandbox capabilitites

are ignored. By default DisableSandboxing is not present or is set to F.

● Sandbox

This capability enables the usergroup to create named sandboxes that can be used to build

what-if scenarios. With this capability granted, users can create and name more than one set

of data changes which are overlaid on top of the base data. Users can keep their sandboxes

private and decide when to commit the data changes to make them public. Sandboxing is a

powerful feature, but some users will find the complexity of managing multible scenarios against

a common base challenging.

By default all users have this capability. The blank setting acts like a Grant.

To prevent this usergroup from using named sandboxes, set this capability to Deny.

If the ability to have sandboxes is turned off using the DisableSandboxing in the server's con-

figuration file, the Personal Workspace Writeback Mode and Sandbox capabilitites are ignored.

By default this parameter is not present or is set to F.

● Data Reservation capabilities

Data Reservation (DR) is a server-related feature that allows you to configure exclusive write-

access to regions of a cube for individual users. Once reserved, the data in that region can only

be modified by that specific user until the reservation is released.

DR uses the ManageDataReservation and DataReservationOverride capabilities to allow

members of a user group to acquire, release, and override DRs for themselves and other users.

For details, see the "Using Data Reservations" and "Enabling user groups to manage Data

Reservations" sections in the IBM® Cognos® TM1® Developer Guide.

TM1 Contributor CapabilitiesThe Writeback Mode and Sandbox capabilities are ignored by TM1® Contributor. In TM1 Con-

tributor, the capabilities are set by application. All users associated with a particular application,

work in the way set for that application.

If you are working with multiple sandboxes, you must submit from TM1 Contributor, you cannot

submit from the Workflow page.

Operation Guide 29

Chapter 2: TM1 System Configuration

Page 30: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Setting CapabilitiesYou determine the writeback mode using a combination of Grant or Deny settings to the Personal

Workspace Writeback Mode and the Sandbox Capabilities as described here:

SandboxingPersonal WorkspaceWriteback Mode

To let the usergroup

GrantDenyWork directly in the base with the ability to create

multiple sandboxes. This is the default case.

DenyGrantWork in a single, private work area without named

sandboxes.

GrantGrantWork with both a "default" private work area and

named sandboxes.

DenyDenyWork in Direct writeback with no sandbox. This is the

classic TM1® mode. This setting is similar to the addi-

tion of DisableSandboxing=T to the configuration file

which prevents the use of sandboxes and puts all users

into direct writeback.

Understanding the Effect of Blanks in the Capability AssignmentsBy default all Capability Assignments are set to blank. Blank can mean either Deny or Grant

depending on the default setting of each Capability.

For example, Blank in the Personal Workspace Writeback Mode Capability means Deny. Blank in

the Sandbox Capability means Grant.

When a user is a member of more than one group, the blank setting allows conflicts that might

occur to be resolved based on any explicitly set assignment.

When a user is a member of more than one usergroup, any explicitly set Grant or Deny overrides

a blank.

In the case of conflicting explicitly set assignments, a Deny capability overrides a Grant.

See the "Using Personal Workspaces and Sandboxes" in the IBM® Cognos® TM1® User Guide for

more information about the implications of Personal Workspaces and Sandboxing on users.

Understanding Recalc and Commit in a Personal Workspace

The following table shows the different effects of Commit and Recalc in a Personal Workspace

with and without queuing:

Sends DataActionWriteback

From the Base TM1 Model.Read--> RecalcDirect

30 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 31: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Sends DataActionWriteback

To the Base TM1 Model.Write--> Recalc

From the Base TM1 Model.Read--> RecalcPersonal Workspace

To the Personal Workspace.Write--> Recalc

Sends the Personal Workspace data to the

TM1 Base Model.

CommitPersonal Workspace

Sends the Personal Workspace to the Queue.CommitPersonal Workspace with

Queuing

When all resources are available, the Personal

Workspace data is processed and sent to the

Base TM1 Model.

Using Persistent FeedersTo 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.

For more details about the associated parameter for this feature, see "PersistentFeeders" (p. 57).

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.

Saving data with persistent feedersWhen PersistentFeeders=T, and a cube with rules is saved, the feeders are stored along side the

cube data in a .feeders file. The cube files are called cube-name.cub and cube-name.feeders.

When a cube is loaded, if a .feeders file exists, it is read to re-load the feeders and normal feeder

evaluation is skipped. If the feeders file does not exist normal feeder calculation occurs and the

.feeders file is written after all the feeders have been calculated. This will be the behavior the first

time the TM1® server is brought up on a data directory with the PersistentFeeders=T. As part

of the server startup the .feeders files for all the relevant cubes will be written. A new persistent

feeders files is written for any cube for which the persistent feeders file is not found at server startup.

This means that the .feeders files may be deleted from the data directory to force a complete re-

Operation Guide 31

Chapter 2: TM1 System Configuration

Page 32: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

calculation of feeders when the server next starts. In a TI process, use the DeleteAllPersistentFeeders

() TI function to delete all persistent feeders.

The modified time of the .feeders file is compared to that of the base cube file at load time. If the

cube file is newer than the feeders file, the .feeders file is regarded as invalid and is deleted. The

.feeders file is always written after the cube file so it should always be newer than the cube file.

Modifying rules for cubes with feedersWhen rules for a cube are modified the feeders for the rules associated with that cube are re-run to

pick up any changes in the feeder statements in the rules file. The TM1® server never deletes feeders

themselves in memory so this recalculation will only add new feeders, it will not delete feeders

which may no longer be valid due to the rule file edits.

After the feeders are recalculated, the persistent feeder files for the cube whose rule was edited, and

all dependent cubes ( due to DB(…) statements in the rules) are rewritten. Because feeders in

memory are never deleted, this means that rule file edits may leave some feeders set which are no

longer valid (no rules actually apply). These unused feeders will be saved with the persistent feeders.

Because of the possibility of unused feeders, the administrator may want to periodically (during

some time when there is little demand on the server) re-calculate all the feeders. This is done by

calling the DeleteAllPersistentFeeders() TurboIntegrator function, shutting down the server, and

then bringing the server back up. When the server is brought back up, because there is no persistent

feeder information, all the feeders will be re-calculated and new persistent feeder information will

be written to disk. See the TurboIntegrator Functions chapter of the Reference Guide for more

information.

Handling corrupted or invalidated feeder filesIf a corrupted or invalid feeder file is detected, all the saved feeders will be deleted and the server

will exit with appropriate messages in the log file. In that case, you must restart the server to reload

and re-compute all of the feeders. The messages in the log will be of the form:

27660 ERROR 2010-05-14 19:10:26.455 TM1.Server All persistent feeder files will be deleted and

server will shut down

27660 ERROR 2010-05-14 19:10:26.455 TM1.Server Restart server to re-load database.

Feeder files are deemed "invalid" if there is a format error in the file, or if the date-time of the feeder

file is older than the corresponding cube (.CUB) file which may happen if one tries to manually

copy feeder or cube files from one data directory to another. When a feeder file is deemed to be

invalid, a message is written to the system log file explaining the exact reason that the feeder file is

deemed to be invalid. The message has the form:

ERROR 2010-05-14 19:00:22.987 TM1.Server Invalid feeder file detected for cube "xxxx" reason:

...

This message will typically (in the case of a multi-threaded load or an error with an cube which

loads early in the startup process) not be near the end of the file, but rather will be in the middle

of the load sequence. Searching the message log for "ERROR" will show the error.

32 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 33: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Parameters in the Tm1s.cfg FileThe parameters in the Tm1s.cfg file are described here.

Static or Dynamic Parameters

Some parameters in the Tm1s.cfg file are dynamic, meaning that the parameter value can be edited

while the TM1® server is running. The TM1 server continuously polls the Tm1s.cfg 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.

Most parameters in the Tm1s.cfg file are static. These parameter values are read from the Tm1s.cfg

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 Tm1s.cfg file, and then restart the server. Static

parameters are also identified as such in this list.

Note: The TM1 local server never polls for changes in the Tm1s.cfg file, so all parameters in a local

server's .cfg file must be considered static. If you change any Tm1s.cfg parameter values for a local

server, you must restart the server to apply the new parameter values.

Spaces in Values

If a parameter value contains spaces, you must enclose the parameter values within double quotes.

AdminHostSpecifies the computer name or IP address of the Admin Host on which an Admin Server is running.

Parameter type:

● Required

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

You can specify multiple Admin Hosts by separating each host name with a semicolon when running

on Microsoft® Windows® or using a colon when running on a UNIX®. 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=192.168.1.17;192.168.1.22

● AdminHost=boston;192.168.1.17;192.168.1.22;myserver;192.168.1.40

Note: The string specifying the admin host(s) is limited to 1020 characters or bytes.

Operation Guide 33

Chapter 2: TM1 System Configuration

Page 34: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

AllowMultiModesPermits TM1 Top to replace the normal display for a display of sandboxes or the queue. When this

parameter is set to T, and TM1 Top is running, pressing

● n displays the normal screen.

● s displays the sandbox status screen.

● q displays the sandbox queue screen.

If this parameter is set to F or is not present, only the normal mode of TM1 Top displays.

You must also have sandboxing turned on or job queuing.

AllowReadOnlyChore RescheduleProvides users with READ access to a chore, and the ability to activate, deactivate, and reschedule

chores.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

When the line AllowReadOnlyChoreReschedule=T is added to the Tm1s.cfg 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.

AllowSeparateNandCRulesSpecifies expressions for N: and C: levels on separate lines using identical AREA definitions,

maintaining the rules conventions of TM1®.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

Specifies expressions for N: and C: levels on separate lines using identical AREA definitions,

maintaining the rules conventions of TM1 7.x.

For example,

['Budget','Argentina']=N:Expression;

34 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 35: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

['Budget','Argentina']=C:Expression;

are both valid rules statements when you include the AllowSeparateNandCRules parameter in the

Tm1s.cfg 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 Tm1s.cfg:

AllowSeparateNandCRules=T

AllRuleCalcStargateOptimizationThe AllRuleCalcStargateOptimization parameter can improve performance in calculating views

that contain only rule-calculated values.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

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.

Operation Guide 35

Chapter 2: TM1 System Configuration

Page 36: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

To enable this parameter, set the parameter's value to T in the TM1 server configuration file,

Tm1s.cfg, as follows:

AllRuleCalcStargateOptimization=T

The default setting is disabled (F).

AuditLogMaxFileSizeIndicates 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

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

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

● Maximum value: 2 GB

AuditLogMaxQueryMemoryIndicates the maximum amount of memory that TM1® can use when running an audit log query

and retrieving the set of results.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

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

36 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 37: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

AuditLogMaxTempFileSizeIndicates the maximum file size that the temporary audit log file can grow to before TM1® moves

the file's data into the final audit log.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

This value must include units of KB (kilobytes), MB (megabytes), or GB (gigabytes). For example:

AuditLogMaxTempFileSize=100MB

The range of values include:

● Default value: 100 MB

● Minimum value: 1 KB

● Maximum value: 2 GB

AuditLogOnTurns audit logging on (T) or off (F).

Parameter type:

● Optional

● Static

If you change this parameter value, restart the IBM® Cognos® TM1® server to apply the new

value.

For example:

● To enable audit logging, set AuditLogOn=T

● To disable audit logging, set AuditLogOn=F

The default setting is F.

AuditLogUpdateIntervalIndicates the maximum amount of time, in minutes, that TM1® waits before moving the events

from the temporary audit file into the final audit log.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

Operation Guide 37

Chapter 2: TM1 System Configuration

Page 38: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

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".

CalculationThresholdForStorageDefines a minimum number of rule calculations required for a single cell or Stargate view, beyond

which the TM1® server stores the calculations for use during the current server session.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

For example, when a user requests rule-derived values from the 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 Tm1s.cfg, the default calculation threshold

is 50.

CAMSSLCertificateParameter type:

● Optional/Required

Required only when CAM server is configured to use SSL.

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

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\CognosCert.cer.

CheckFeedersMaximumCellsLimits the number of cells checked by the Check Feeders option in the Cube Viewer. The Check-

FeedersMaximumCells is an optional parameter that you can add to Tm1s.cfg. If you do not include

this parameter in Tm1s.cfg, Check Feeders checks 3,000,000 cells, by default.

38 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 39: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

When TM1® 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 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 Tm1s.cfg 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

ClientCAMURIParameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

The URI for the IBM® Cognos® 8 Server IBM Cognos Connection used to authenticate TM1 clients.

The URI is specified in the form http[s]://host/cognos8/cgi-bin/cognos.cgi.

For example, http://10.121.25.121/cognos8/cgi-bin/cognos.cgi

ClientPingCAMPassportIndicates the interval, in seconds, that a client should ping the CAM server to keep their passport

alive.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

If an error occurs or the passport expires the user will be disconnected from the TM1 server.

CAMPortalVariableFileThe path to the variables_TM1.xml in your C8 installation. In most cases, the path will be c8_

location\templates\ps\portal\variables_TM1.xml..

Parameter type:

Operation Guide 39

Chapter 2: TM1 System Configuration

Page 40: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Required for TM1® Web

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

The variables_TM1.xml file is included as part of the TM1 Viewer Portlets installation. For details

on installing and configuring Viewer Portlets, see the IBM® Cognos® TM1® Installation Guide.

The CAMPortalVariableField parameter is required only when running TM1 Web.

ClientMessagePortNumberIdentifies 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

● Dynamically set/Static for changes

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 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.

See also, "PortNumber" (p. 57) and "ProgressMessage" (p. 58).

ClientPropertiesSyncIntervalSpecifies 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

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

40 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 41: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ClientVersionMaximumSpecifies the maximum client version that can connect to the TM1® server.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

The ClientVersionMaximum parameter value is expressed as a version string using the following

format:

m.n.tffhh

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 Tm1s.cfg file does not include a ClientVersionPrecision parameter value, only the major

release number, minor release number, and maintenance release number are used to enforce com-

patability 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 - currently installed server version, where x is the

base version 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.

ClientVersionMinimumSpecifies the minimum client version that can connect to the TM1® server.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

The ClientVersionMinimum parameter value is expressed as a version string using the following

format:

Operation Guide 41

Chapter 2: TM1 System Configuration

Page 42: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

m.n.tffhh

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 Tm1s.cfg file does not include a ClientVersionPrecision parameter value, only the major

release number, minor release number, and maintenance release number are used to enforce com-

patability 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 base version of the currently

installed TM1 server. There is no upper limit for ClientVersionMinimum. However, if ClientVer-

sionMinimum is larger than ClientVersionMaximum, only clients with a version number equal to

ClientVersionMaximum can connect to the server.

ClientVersionPrecisionThis parameter lets you more precisely identify the minimum and maximum versions of clients that

can connect to the TM1® server.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

The ClientVersionMinimum and ClientVersionMaximum parameter values are expressed as a version

string using the following format:

m.n.tffhh

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, mainte-

nance release 1, fix pack 3, and hot fix 5.

42 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 43: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

If ClientVersionPrecision is not set in Tm1s.cfg 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 ClientVersionPreci-

sion to the Tm1s.cfg 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.

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.

CognosInterfacePathSpecifies the location of the BI server to use when importing data from a Cognos Package to TM1®

using the IBM Cognos TM1 Package Connector. See the IBM® Cognos® TM1® TurboIntegrator

Guide for more information.

Parameter type:

● Optional; required when using the TM1 Package Connector.

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

DataBaseDirectorySpecifies the data directory from which the server loads cubes, dimensions, and other objects. You

can list multiple data directories by separating them with semicolons.

Parameter type:

● Required

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

For details, see "Data Directory".

DefaultMeasuresDimensionParameter type:

Operation Guide 43

Chapter 2: TM1 System Configuration

Page 44: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Optional: but some OLAP applications may require this parameter. See description below for

details.

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

TM1 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 "}CubeProper-

ties" (p. 293).

However, 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 Tm1s.cfg, a measures dimension is not

defined for when a cube is created.

DisableMemoryCacheDisables the memory cache used by TM1 memory manager. 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 TM1

memory manager. The default setting is DisableMemoryCache=F.

DisableSandboxingDetermines if users have the ability to use sandboxes across the server.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

By default, this parameter is not present in the configuration file which enables the sandbox capa-

bility 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.

To put all usergroups into Direct Writeback mode, add the following line to Tm1s.cfg:

DisableSandboxing=T

When DisableSandboxing=T, the Capability Assignments are ignored.

44 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 45: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DisableWorksheetViewDisableWorksheetView disables any VIEW functions contained in slice worksheets. Any slice

worksheets containing a VIEW function remain functional, but the function does not generate a

Stargate view.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

Please contact customer support to determine if this parameter is applicable to your TM1 system.

Generally, you should disable the worksheet VIEW functions when you work with extremely large

row or column dimensions in slice worksheets. The VIEW function generates a Stargate view that

contains all row and column dimension elements, and not just those elements contained in the

current row and column subsets. With the Stargate view, you might experience decreased performance

when, for example, a row dimension contains 9,000 elements but only 20 elements are actually

used in the row subset.

To disable the slice worksheet VIEW functions, add the following line to Tm1s.cfg:

DisableWorksheetView=T

Display_Info_DBType_R8Display_Info_DBType_R8 instructs the TM1® server to store DISPLAY_INFO column data as

DBTYPE_R8.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

Please contact customer support to determine if this parameter is applicable to your TM1 system.

By default, TM1 stores the DISPLAY_INFO as DBTYPE_UI4. When the TM1 OLE DB provider

processes a request from ADO 2.7 for the DISPLAY_INFO column data, the provider has to convert

TM1 column data from DBTYPE_UI4 to a DBTYPE_R8. The TM1 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 con-

verted 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 Tm1s.cfg file and set the

parameter to T, the TM1 server stores DISPLAY_INFO column data as DBTYPE_R8 with the rel-

evant 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

Operation Guide 45

Chapter 2: TM1 System Configuration

Page 46: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

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.

DownTimeSpecifies a time when the server will come down automatically.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

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 fol-

lowing day at 3:30 in the morning.

The DownTime parameter is not available when you run the TM1® server as a Windows® service.

When you use the DownTime parameter on the UNIX® TM1 server, you must set the RunningIn-

Background parameter to T. If RunningInBackground=F, the server prompts for confirmation

before shutting down and cannot shut down without manual confirmation from an administrator.

ExcelWebPublishEnabledEnables the publication of Excel files to TM1® Web, as well as the export of Excel files from TM1

Web, when Excel is not installed on the Web Server.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

If ExcelWebPublishEnabled=T, Excel files in TM1 Applications can be published to TM1 Web

without using Excel on the Web server. Similarly, Websheets and Cubeviewers can be exported

from TM1 Web without using Excel on the Web server.

When Excel is not available on the Web server, Excel files in TM1 Applications must be explicitly

published to TM1 Web.

For details about the procedure required to publish Excel files, see the IBM® Cognos® TM1®

Developers Guide.

For details about limitations exporting from TM1 Web without using Excel on the Web server, see

the IBM® Cognos® TM1® User Guide.

46 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 47: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Note: You cannot publish Excel 2007 .xlsx files to TM1 Web when Excel is not available on the

Web server. These files must be saved in Excel 2003 .xls format if you want to publish them to

TM1 Web.

GroupsCreationLimitSets the maximum number of groups that can be created in one TM1® server session.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

The GroupsCreationLimit parameter accepts a value of any positive integer. The maximum number

of groups for GroupsCreationLimit is 65535. The maximum number of groups that can exist on

a server is 65535. If you do not use the parameter, the default number of groups is 20.

For example, to create 50 groups per server session, enter the following line:

GroupsCreationLimit=50

Note: When TM1 allocates memory to store security information, the server calculates the amount

of memory required based in part on the value of GroupsCreationLimit. In some circumstances

when your TM1model is large and the GroupsCreationLimit parameter is set to an exceptionally

high value, the server will attempt to allocate memory beyond the available capacity on the server.

The TM1 server will fail to load and will issue a Server Out of Memory message. To avoid this

situation, set GroupsCreationLimit to a value that accurately reflects the maximum number of user

groups you may need to create during a server session.

The GroupsCreationLimit value is not enforced when you create groups with the AddGroup function

in TurboIntegrator.

IdleConnectionTimeOutSecondsSpecifies a timeout limit for idle client connections, in seconds.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

For example, if you include the following line in Tm1s.cfg, the server disconnects idle client connec-

tions after 900 seconds.

IdleConnectionTimeOutSeconds=900

IntegratedSecurityModeThis parameter sets the user authentication mode to be used by the TM1® server.

Operation Guide 47

Chapter 2: TM1 System Configuration

Page 48: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

Use the following format to set this parameter:

IntegratedSecurityMode=x

where x can be a value for one of the following security modes.

DescriptionSecurityMode

The server uses secure mode (standard TM1 security).1

With this authentication, the TM1 server checks the user name and password

against the user names and passwords in the TM1 database.

The server uses mixed mode.2

This mode allows you to log in to TM1 using either standard TM1 security or

Integrated Login. This is useful because it is often necessary to log in to TM1using

standard TM1 security when you are setting up Integrated Login.

The server uses Integrated Login.3

Integrated Login allows you to use Microsoft® Windows® network authentication

to control access to TM1 data.

If you use this security mode, you must also set the SecurityPackageName

parameter.

For more details, see "Integrated Login" (p. 229).

The server uses IBM® Cognos® 8 security authentication.4

Considerations when using this mode:

In TM1, Cognos 8 users can belong only to Cognos 8 groups and any of the

three internal TM1 administrator groups (ADMIN, DataAdmin and SecurityAd-

min). Membership in TM1user (non-administrator) groups is not supported for

Cognos 8 users when they log in to TM1.

You can not use TM1to permanently assign a Cognos 8 user to another Cognos

8 group. Any user assignment you make in TM1to a Cognos 8 group is not

saved back to Cognos 8. When a Cognos 8 user logs in to TM1, the group

assignments in Cognos 8 override any Cognos 8 group assignments made in

TM1.

48 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 49: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionSecurityMode

The server uses IBM Cognos 8 security authentication and supports user groups

from both TM1and Cognos 8.

5

Use security mode 5 when you are running IBM® Cognos® TM1® Contributor

with IBM Cognos 8 security.

Considerations when using this mode:

● In TM1, Cognos 8 users can belong to both Cognos 8 and TM1groups.

● You can not use TM1 to permanently assign a Cognos 8 user to another

Cognos 8 group. Any user assignment you make in TM1 to a Cognos 8

group is not saved back to Cognos 8. When a Cognos 8 user logs in to TM1,

the group assignments in Cognos 8 override any Cognos 8 group assignments

made in TM1.

IPAddressThis parameter lets you specify multiple IP addresses for an individual TM1® server. For example,

a server can use one IP address for clients within a firewall and a different IP address for clients

outside the firewall.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

Note: When this parameter is used in the Tm1s.cfg file, both the TM1 Server and Admin Server

must run on the same computer. If this parameter is used in the Tm1s.cfg file, but the TM1 Server

and Admin Server reside on different computers, TM1 clients will receive an error when they attempt

to log in to the TM1 Server.

If the TM1 Server and Admin Server reside on different computers, you can configure the Admin

Server to use multiple IP addresses for an individual TM1 Server by adding an initialization file

named Tm1admsrv.ini to the directory where the Admin Server executable resides. For details, see

"TM1 Admin Server" (p. 17).

The syntax for Microsoft® Windows® uses as element separator a semicolon, for example the fol-

lowing setting specifies two IP addresses for the TM1 server:

IPAddress="130.5.32.0; 130.5.64.0"

Note: The addresses must be enclosed in a single set of quotation marks and separated by a semi-

colon.

When you specify multiple IP addresses for a server, the associated Admin Server recognizes all

addresses but displays only the first IP address in the Admin Server window.

Operation Guide 49

Chapter 2: TM1 System Configuration

Page 50: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The syntax for UNIX® uses as element separator a colon. For example IPAddress=130.5.32.0:130.5.64.0

JobQueuingTurns on queuing for Personal Workspace or Sandbox submissions.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

Set this parameter to JobQueuing=T to have all sandbox submissions to process using the Job

Queue. When this parameter is set to F or not in the configuration file, sandbox submissions do

not process in a queue.

When this parameter is turned on, the submission icon displays on the toolbar.

See the Job Queuing description in the Sandbox and Writeback chapter of the IBM® Cognos® TM1®

User Guide for details.

JobQueueMaxWaitTimeWhen the queue thread runs, it blocks all incoming requests to ensure it can get the locks necessary

to process a job on the queue. New requests are blocked for the amount of time set in the

JobQueueMaxWaitTime parameter.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

Defaults to 100ms.

If the currently executing requests have not completed in this time, the queue thread goes back to

sleep for JobQueueThreadSleepTime and incoming requests are allowed to proceed.

To give the queue thread higher priority, set the JobQueueMaxWaitTime to a larger number.

If the JobQueueMaxWaitTime parameter is set to zero in the configuration file and Job Queuing is

turned on, the queue will keep trying until it can process, effectively locking out any other activity

until it is complete.

See Job Queuing in the IBM® Cognos® TM1® User Guide for more details.

JobQueueThreadSleepTimeJobQueueThreadSleepTime determines the frequency with which the thread processing the queue

runs when there are queued jobs.

Parameter type:

50 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 51: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

Defaults to 10 seconds.

LanguageSets the language used in the TM1® interface.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

Valid values are:

● ENG - English

● FRA - French

● DEU - German

● JPN - Japanese

● SCH - Simplified Chinese

● ITA - Italian

● ESP - Spanish

LDAPUseServerAccountSee "LDAP Authentication" (p. 245).

LDAPPasswordFileSee "LDAP Authentication" (p. 245).

LDAPPasswordKeyFileSee "LDAP Authentication" (p. 245).

LockPagesInMemoryWhen this parameter is enabled, Windows® trims pages from the TM1 process space, but does not

page them to disk.

Parameter type:

● Optional

● Static

Operation Guide 51

Chapter 2: TM1 System Configuration

Page 52: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

If you change this parameter value, restart the TM1® server to apply the new value.

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. This can cause performance degradation in large TM1

databases when trying to access data after an idle period.

To maximize performance when running a large TM1 database on 64-bit Windows, set

LockPagesInMemory=T in the Tm1s.cfg file.

When this parameter is enabled, Windows still trims pages from the TM1 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

LoggingDirectorySpecifies 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

If you change this parameter value, restart the TM1® server to apply the new value.

Note: The value of parameter LoggingDirectory must be encapsulated by quotes if it uses spaces,

for example LoggingDirectory=C:/Data Files/Logfiles. The 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.

LogReleaseLineCountSets 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. By default this

value is set at 5000 lines.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

MaximumCubeLoadThreadsSpecifies 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

52 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 53: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

If you change this parameter value, restart the TM1® server to apply the new value.

To run in multi-threaded mode, you should set MaximumCubeLoadThreads to the number of

processor cores on the 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

off available processor cores) - 1. For example, if the TM1 server is running on a computer with

four processor cores, MaximumCubeLoadThreads should be set to 3. This ensures that one processor

core is available to run other applications while the TM1 server is loading.

When MaximumCubeLoadThreads is set to 0, cube loading and feeder processing is NOT multi-

threaded. This is the default behavior when MaximumCubeLoadThreads is not explicitly set in the

Tm1s.cfg file.

Note: When MaximumCubeLoadThreads is enabled, TM1 cannot manage the order in which

feeders are calculated. There may 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 TM1® model uses conditional feeders where the condition clause contains a fed value, you

should set MaximumCubeLoadThreads=0 or exclude the parameter from the Tm1s.cfg file to disable

the use of multiple threads at load time.

MaximumLoginAttemptsSets the maximum number of failed user login attempts permissible on the server. If you do not

include MaximumLoginAttempts in Tm1s.cfg, by default, the server allows three login attempts.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

For example, if you add the line MaximumLoginAttempts=5 to Tm1s.cfg, 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 TM1 adminis-

trator changes his password. However, after the TM1 server recycles, the user can log in with his

existing password.

MaximumMemoryForSubsetUndoSets 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.

Operation Guide 53

Chapter 2: TM1 System Configuration

Page 54: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

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 Tm1s.cfg file, the maximum amount of memory dedicated

to the Undo/Redo feature of the Subset Editor is 10240 kilobytes (10 MB).

MaximumSynchAttemptsSets 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

If you change this parameter value, restart the TM1® server to apply the new value.

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 Tm1s.cfg 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. This default behavior is the same

behavior as TM1 versions prior to 9.5.1 where a synchronization process would fail if the network

connection was 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" (p. 65).

The following example shows how to use the MaximumSynchAttempts parameter with the SyncU-

nitSize parameter:

SyncUnitSize=2000

MaximumSynchAttempts=100

54 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 55: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

MaximumUserSandboxSizeSets 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 100 MB on a 32-bit system, and 500 MB on a 64-bit system.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

To specify a maximum amount of memory allocation for personal workspaces or sandboxes, add

the following line to Tm1s.cfg:

MaximumUserSandboxSize=n

where n represents the amount of memory in MB to be allocated.

MaximumViewSizeSets 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 100MB on a 32-

bit system, and 500 MB on a 64-bit system.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

To specify a maximum amount of memory allocation for views, add the following line to Tm1s.cfg:

MaximumViewSize=n

where n represents the amount of memory in MB to be allocated.

MaxUndoHoldLineCountMaxUndoHoldLineCount determines how long an Undo or Redo operation locks the Tm1s.log

file.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

When the Tm1s.log file grows to sizes of 1 GB or larger, an Undo or Redo operation can lock the

Tm1s.log file for an unacceptably long period, preventing other threads from accessing the log file.

Operation Guide 55

Chapter 2: TM1 System Configuration

Page 56: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

MaxUndoHoldLineCount lets you specify the interval, expressed as the number of records to be

processed between lock releases, at which an Undo or Redo operation allows other threads to access

the Tm1s.log file.

To specify the interval at which the TM1 server should release the lock on the Tm1s.log file, add

the following line to Tm1s.cfg:

MaxUndoHoldLineCount=n

where n represents the number of records to be processed before an Unor/Redo operation relinquishes

and reacquires the lock on Tm1s.log. When MaxUndoHoldLineCount is set, an Undo/Redo operation

processes the number of records specified by the parameter value, then releases the lock, alows

other threads to access the log file, and reacquires the lock.

If MaxUndoHoldLineCount is not explicitly set, the default value is 5000.

MessageCompressionEnables message compression for large messages that significantly reduces network traffic. The

parameter is enabled by default.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

To disable message compression, add the following line to Tm1s.cfg:

MessageCompression=F

PasswordMinimumLengthSpecifies a minimum password length for clients accessing the server.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

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 PasswordMini-

mumLengt.h

PasswordSourceSee "LDAP Authentication" (p. 245).

56 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 57: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

PerformanceMonitorOnAutomatically 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" (p. 287).

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

For example, to enable Performance Monitor set PerformanceMonitorOn=T. To disable the Per-

formance Monitor set PerformanceMonitorOn=F

PersistentFeedersTo 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

If you change this parameter value, restart the TM1 server to apply the new value.

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 details about using Persistent Feeders, see "Using Persistent Feeders" (p. 31)

PortNumberSets 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.

Parameter type:

● Optional

● Static

Operation Guide 57

Chapter 2: TM1 System Configuration

Page 58: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

If you change this parameter value, restart the TM1 server to apply the new value.

When you install a TM1 server, the default port number is 12345. Valid port numbers are between

5001 and 49151.

If the Tm1s.cfg 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.

PrivilegeGenerationOptimizationWhen the 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 process-

ing 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

If you change this parameter value, restart the TM1 server to apply the new value.

To address this issue, the PrivilegeGenerationOptimization parameter can be added to the Tm1s.cfg

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 TM1 server's

load time.

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.

ProgressMessageThis 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 Pro-

gressMessage=T a dialog box opens that allows the user to Stop Building View.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

If the user clicks Stop Building View, the view is discarded on the client, but view calculation con-

tinues on the server. In some instances, this can tie up the server.

58 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 59: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● If ProgressMessage=F, the Stop Building View option is not offered and the user cannot cancel

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 Tm1s.cfg file, the Stop Building View option

opens during lengthy view calculations so the user can cancel the process if necessary. For ver-

sions 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 Tm1s.cfg 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.

RawStoreDirectoryIndicates 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

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

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, AuditLogMaxQueryMemory

, AuditLogMaxTempFileSize , AuditLogOn, and AuditLogUpdateInterval.

ReceiveProgressResponseTimeoutSecsThe ReceiveProgressResponseTimeoutSecs parameter configures the server to sever the client con-

nection and release resources during a long wait for a Cancel action.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

When the 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

Operation Guide 59

Chapter 2: TM1 System Configuration

Page 60: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

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 the TM1 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 Tm1s.cfg parameter. If the parameter is not

present in the Tm1s.cfg file, processes are not terminated when a client does not respond to a

progress message from the TM1 server.

For some TM1 installations (version 9.4 or later), the ClientMessagePortNumber defines a separate

thread to use for cancellation messages without tying up reserves. When ClientMessagePortNumber

is available, ReceiveProgressResponseTimeoutSecs is not used.

RunningInBackgroundWhen you add the line RunningInBackground=T to Tm1s.cfg, the UNIX® TM1® server runs in

background mode.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

SAPLoggingEnabledWhen a TurboIntegrator process imports objects and/or data from SAP RFC, you can configure

your TM1® server to log all activity between TM1 and SAP.

Parameter type:

● Optional: used only in 9.0 software. 9.1 and higher versions use a property to set this value.

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

60 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 61: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

When a TurboIntegrator process imports objects and/or data from SAP RFC, you can configure

your TM1 server to log all activity between TM1 and SAP.

Add the line SapLoggingEnabled=T to your Tm1s.cfg file to enable SAP logging. If this parameter

is not present in the Tm1s.cfg file, or if the parameter is set to F, SAP activity is not logged.

If SapLoggingEnabled=T you must also set the SapLogFilePath parameter.

SAPLogFilePathThis parameter sets the log file to receive SAP logging information.

Parameter type:

● Optional: used only in 9.0 software. 9.1 and higher versions use a property to set this value.

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

You should specify the full path to the log file, for example, SapLogFilePath=c:\SAPdata\tm1_

sap.log.

SaveTimeSets 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

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

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.

SecurityPackageNameIf 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®.

Parameter type:

● Optional

● Static

Operation Guide 61

Chapter 2: TM1 System Configuration

Page 62: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

If you change this parameter value, restart the TM1 server to apply the new value.

Valid values are:

● Kerberos (default) - Windows 2000 or later.

● NTLM - Older Windows installations, such as Windows NT.

For complete descriptions of all login security modes, including Integrated Login, see "Integrated

Login" (p. 229).

ServerCAMURISpecifies 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.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

For example,

http://10.121.25.121:9300/p2pd/servlet/dispatch

or

https://10.121.25.121:9300/p2pd/servlet/dispatch

ServerLoggingGenerates a log with the security activity details on the TM1® server that are associated with Inte-

grated Login. The log file, named Tm1server.log, is saved to the TM1 server data directory. The

ServerLogging parameter is useful only if your TM1 server is configured to use Integrated Login.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

Set ServerLogging to T in Tm1s.cfg. Note also that if ServerLogging=T is set, you must rename

the TM1 server message logfile tm1server.log by editing the corresponding parameter in the logger

configuration file tm1s-log.properties file.

ServerNameSets the name of the TM1® server. If you do not supply this parameter, TM1 names the server Local

and treats it as a local server.

Parameter type:

● Optional

62 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 63: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

SkipLoadingAliasesUse SkipLoadingAliases to speed up the loading of the server and updating of views by skipping

the loading of aliases.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

Please contact customer support to determine if this parameter is applicable to your TM1 system.

Valid values are:

● T - Aliases skipped

● F - Aliases loaded

SkipSSLCAMHostCheckIndicates whether the SSL certificate ID confirmation process can be skipped. The default is FALSE.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

Important: This parameter should be set to TRUE only if using a generic certificate for demonstration

purposes.

SpreadingPrecisionUse the SpreadingPrecision parameter to increase or decrease the margin of error for spreading

calculations.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

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.

Operation Guide 63

Chapter 2: TM1 System Configuration

Page 64: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The margin of error for certain TM1® 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.

Spreading from a Consolidation

When you execute a proportional data spread from a consolidated cell, TM1 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 for the consolidation must be within

0.000001% of the target value (99.999999% accurate), or TM1 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 Spreading-

Precisionparameter.

The following examples include valid values for the SpreadingPrecision parameter:

● SpreadingPrecision=1e-4

● SpreadingPrecision=1e-8

● SpreadingPrecision=1e-10

● SpreadingPrecision=1e-12

SpreadingPrecision (Consolidated Holds)Specifies the the margin of error for spreading consolidated hold calculations.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

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.

64 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 65: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

If Q1- has a consolidated hold applied, and you spread values to Jan and Feb, TM1® does the fol-

lowing:

● 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® generates an error.

SubsetElementBreatherCountThis parameter manages the way TM1® handles locking behavior for subsets.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

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=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.

SyncUnitSizeSets the frequency of saving a check point during a synchronization process in case there is a network

connection failure.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

Operation Guide 65

Chapter 2: TM1 System Configuration

Page 66: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Note:When you use SyncUnitSize, you must also configure the MaximumSynchAttempts parameter.

For more information, see "MaximumSynchAttempts" (p. 54).

If you configure both the SyncUnitSize and MaximumSynchAttempts parameters and a synchroniza-

tion 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 Tm1s.cfg file for the planet server:

SyncUnitSize=n

where n represents the number of synchronization records written to the transaction log file,

Tm1s.log, after which a check point will be saved.

The default value is 1000.

The minimum recommended value is 500.

UserDefinedCalculationsEnables user-defined consolidations on a TM1® server.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

By default, UserDefinedCalculations is enabled.

To disable user-defined consolidations on a server, add the following line to Tm1s.cfg:

UserDefinedCalculations=F

UseSQLFetch UseSQLFetchScroll UseSQLExtenedFetchThese parameters instruct TM1® to use a particular fetch call.

Parameter type:

● Optional

● Dynamic

Modified parameter values are applied to the server when you save the Tm1s.cfg file. There is

no need to restart the server.

When you run TurboIntegrator process that extracts information from an ODBC data source, TM1

tries to use the most efficient SQL fetch call possible. TM1 queries the ODBC driver to determine

which of the following SQL Fetch calls to use to extract the data:

SQLFetch(), an ODBC 1 function

SQLFetchScroll(), an ODBC 2 function

SQLExtendedFetch(), an ODBC 3 function

These parameters are all dynamic.

66 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 67: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

If TM1 receives no response when it queries the ODBC driver, your TM1 process will result in an

error unless one of the following parameters is set to T in your Tm1s.cfg file:

UseSQLFetch

UseSQLFetchScroll

UseSQLExtendedFetch

These parameters instruct TM1 to use a particular fetch call. You must ensure that the call specified

in Tm1s.cfg is appropriate for the ODBC driver being accessed, and you can specify only one of

these parameters in Tm1s.cfg.

For example, to instruct the TM1 server to use the SQLExtendedFetch() call to extract data from

an ODBC source, add the following line to Tm1s.cfg:

UseSQLExtendedFetch=T

UseSSLEnables or disables SSL on the TM1® server.

Parameter type:

● Optional/Required to use SSL.

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

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 Tm1s.cfg parameters that manage SSL implementation.

For details on these parameters, see "Running TM1 in Secure Mode Using SSL" (p. 261).

UseStargateForRulesIndicates if a rule uses the Stargate view.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1® server to apply the new value.

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.

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

Operation Guide 67

Chapter 2: TM1 System Configuration

Page 68: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

line to Tm1s.cfg to instruct the TM1 rules to always retrieve the calculated values from the server

and improve performance.

UseStargateForRules=F

Please contact customer support before adding the UseStargateForRules parameter.

ViewConsolidationOptimizationEnables or disables view consolidation optimization on the TM1® server.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

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 Tm1s.cfg:

ViewConsolidationOptimization=F

ViewConsolidationOptimizationMethodThis parameter defines the method used to achieve view consolidation optimization when the

ViewConsolidationOptimization parameter is enabled on the TM1® server.

Parameter type:

● Optional

● Static

If you change this parameter value, restart the TM1 server to apply the new value.

There are two methods that ViewConsolidationOptimization can use to calculate and store consol-

idations: 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 and when data is sparse along the view axes.

In the uncommon circumstance when axes 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

68 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 69: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ViewConsolidationOptimizationMethod=ARRAY

If ViewConsolidationOptimizationMethod is not explicitly set in the Tm1s.cfg file, the ARRAY

method is used by default.

The Tm1p.ini Client Configuration FileThe Tm1p.ini file specifies the environment information for the TM1® clients (TM1 Perspectives,

TM1 Architect, and Client).

Location of the TM1p.ini FileWhen you install TM1, the installation location for the system default version of the Tm1p.ini file

is

%ALLUSERSPROFILES%\Application Data\Applix\TM1\Tm1p.ini.

In most cases, the full path to the Tm1p.ini file is

C:\Documents and Settings\All Users\Application Data\Applix\TM1\Tm1p.ini.

The system default version of Tm1p.ini allows multiple users to use TM1 on a given computer.

Tm1p.ini must be present the first time a user starts TM1 on the computer, as the parameters in

the system default version govern the behavior of the initial startup of the TM1 client for each user.

After a user starts TM1 on the computer, a user-specific copy of Tm1p.ini is created in %APPDATA

%\Applix\TM1\Tm1p.ini. In most cases, the full path to the Tm1p.ini file is

C:\Documents and Settings\user name\ApplicationData\Applix\TM1\Tm1p.ini.

The user-specific copy of Tm1p.ini accepts all parameters settings and changes for the user and

governs the behavior of the TM1 client for all subsequent user sessions of the TM1 client.

The 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 Tm1p.ini file. The Tm1p.ini parameters

and TM1 Options are described here.

AdminHostDisplays the Admin Host name on which an Admin Server is running. On TM1 Options, use Login

Parameters Admin Host.

AdminSvrSSLCertAuthorityThe full path of the certificate authority file that issued the TM1® Admin Server's certificate. On

TM1 Options, use Certificate Authority.

AdminSvrSSLCertIDThe name of the principal to whom the TM1® Admin Server's certificate is issued.

Note: The value of this parameter should be identical to the SSLCertificateIDparameter in the

Tm1admsrv.ini file.

On TM1 Options, use Certificate ID.

Operation Guide 69

Chapter 2: TM1 System Configuration

Page 70: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

AdminSvrSSLCertRevListThe full path of the certificate revocation file issued by the certificate authority that issued the TM1®

Admin Server's certificate.

A certificate revocation file will only exist in the event a certificate had been revoked. On TM1

Options, use Certificate Revocation List.

AdminSvrSSLExportKeyIDThe identity key used to export the certificate authority certificate, which originally issued the TM1®

Admin Server's certificate, from the certificate store.

This parameter is required only if you choose to use the certificate store by setting ExportAd-

minSvrSSLCert=T.

On TM1 Options, use Export Certificate ID.

AdvancedRulesEditorIndicates the type of Rules Editor used. The Advanced Rules Editor has an enhanced interface.

● T - The Enhanced Rules Editor is used.

● F (Default)- The Basic Rules Editor is used.

AllowImportCamClientsThis parameter is required only when configuring TM1® to use CAM authentication. It must be

set to T when importing an administrative user from CAM into TM1.

If your TM1 server is not configured to use CAM authentication, this parameter should be set to

F or omitted from the Tm1p.ini file.

For details, see "Setting Up the TM1 Server to Use IBM Cognos 8 Security" (p. 252).

BrowseDisplayReadsRightToLeftIndicates 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.

ClassicSliceModeIndicates 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.

70 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 71: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

CognosGatewayURIThis parameter is required only when configuring TM1® to use CAM authentication. It must be

set to the URI of your IBM Cognos 8 gateway. The URI is specified in the form http[s]://host/

cognos8/cgi-bin/cognos.cgi. For example, http://win2003test/cognos8/cgi-bin/cognos.cgi.

If your TM1 server is not configured to use CAM authentication, this parameter should be omitted

from the Tm1p.ini file.

For details, see "Setting Up the TM1 Server to Use IBM Cognos 8 Security" (p. 252).

ConnectLocalAtStartupIndicates whether TM1® Architect or TM1 Perspectives automatically connects to the local server

at startup.

● T (Default) - TM1 connects to the local server at startup.

● F - TM1 does not connect to the local server at startup.

DataBaseDirectoryUses the full path to the local server data directory. You can specify multiple data directories by

separating the directory names with semicolons.

DimensionDownloadMaxSizeA threshold value of the number of elements in a dimension, beyond which the dimension is

downloaded and cached on the TM1® client. To improve performance when you work with large

dimensions, add DimensionDownloadMaxSize so that large dimensions will cache on the client.

DisplayApplicationsIndicates whether the Applications group is visible in Server Explorer on startup.

● T - Applications group is visible in Server Explorer.

● F - Applications group does not appear in Server Explorer.

DisplayChoresIndicates 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.

DisplayControlCubesIndicates 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.

Operation Guide 71

Chapter 2: TM1 System Configuration

Page 72: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DisplayCubesIndicates 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.

DisplayDimensionsIndicates 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.

DisplayExplorerPropertiesWindowIndicates whether the Properties pane is visible in Server Explorer on startup.

● T - Properties pane is visible.

● F (Default) - Properties pane does not appear.

DisplayProcessesIndicates 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.

DisplayReplicationsIndicates 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.

ExpandRowHeaderWidthIndicates 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.

ExportAdminSvrSSLCertSelect this option if you want the certificate authority certificate which originally issued the TM1®

Admin Server's certificate to be exported from the Windows® certificate store at runtime.

● T (Default) - Original certificate is exported from the Windows certificate store.

72 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 73: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● F - Original certificate is not exported.

In TM1 Options, use Use Certificate Store.

When this option is selected, you must also set a value for Export Certificate ID in the TM1 Options

dialog box or AdminSvrSSLExportKeyID.

InSpreadsheetBrowserIndicates 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.

IntegratedLoginIndicates if your TM1 client uses Integrated Login or the standard TM1 security to log in to the

TM1 server and other TM1 components.

● T - Client uses Integrated login, where your Windows® login username and password are used

to access the TM1 server and other components.

● F (Default) - Client uses standard TM1 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 TM1 Options, use Integrated Login.

LanguageIndicates the language used in the TM1® interface.

● ENG - English

● FRA - French

● DEU - German

● JPN - Japanese

● SCH - Simplified Chinese

● ITA - Italian

● ESP - Spanish

LocalServerNetworkProtocolDetermines the protocol that the local TM1® server uses to communicate with clients. Currently,

the only valid setting is TCP.

Operation Guide 73

Chapter 2: TM1 System Configuration

Page 74: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

MainWindowLayoutInfoGenerates 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.

PreviousAdminHostsLists up to six of the most recently accessed Admin Hosts from the TM1® OptionsAdmin Host list.

PreviousDataDirectoriesLists up to six of the most recently accessed data directories in the Local Server Data Directory list

from the TM1® Options window.

The directories accessed within a single session are separated by semicolons. The directories accessed

in different sessions are separated by commas.

SecurityAssignmentWindowLayoutInfoGenerates 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.

SentMsgsToServerCountWarningThe SentMsgsToServerCountWarning parameter is for development use only. The parameter is set

to F by default. Be sure not to change the default setting.

ShowAdminHostChangeWarningBetween 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.

ShowAliasAttributeWarningBetween 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.

ShowChoresSchedulingWarningBetween session storage of whether to display or suppress a warning when a chore schedule is

changed.

74 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 75: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● T (Default)- When a chore schedule is changed, a warning message displays.

● F - No message is displayed when a chore schedule is changed.

ShowCubeReplicationWarningBetween 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.

ShowDimDeleteElementWarningBetween 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.

ShowDimensionAccessWarningBetween 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.

ShowDynamicSubsetWarningBetween 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.

ShowPickOperationWarningBetween session storage of whether to display or suppress a warning when data is copied using the

Pick Elements option.

● 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.

ShowProcessUNASCIIWarningBetween 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.

Operation Guide 75

Chapter 2: TM1 System Configuration

Page 76: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ShowProcessUNODBCWarningBetween 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.

SliceNewWorkbookDetermines 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.

SubsetWindowLayoutInfoGenerates 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.

Configuring andManaging Sandboxes in your TM1 EnvironmentAs the TM1® administrator, you should understand the following technical items when using

Sandboxes and Personal Workspaces in your TM1 environment:

● Memory usage for Sandboxes and Personal Workspaces

● Managing the files and folders that support Sandboxes and Personal Workspaces

● TM1 server configuration parameters for Sandboxes and Personal Workspaces

The sandbox feature lets you create your own Personal Workspaces or Sandboxes separate from

your base data. A sandbox is not a copy of the base data, but is a separate overlay or layer of your

own data values that you have entered on top of the base data.

The new data values that you enter in a Sandbox or Personal Workspace are not saved to the base

data until you explicitly commit the changed data in the sandbox to the base data. This behavior

is different than working directly in base data where any new data values that you enter are written

directly back to the TM1 server.

For more details on using the Sandbox or Personal Workspace feature, see the information on

Sandboxs and Personal Workspaces in the IBM® Cognos® TM1® User Guide and the IBM Cognos

TM1 TurboIntegrator Guide.

Memory Usage Considerations for Sandboxes and Personal WorkspacesIf you are using the sandbox feature, you should be aware that sandboxes require usage of some

additional amount of RAM memory and hard disk space. Error messages display when users

approach their sandbox memory limit.You can control the amount of memory used for sandboxes

76 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 77: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

per user by adjusting the MaximumUserSandboxSize parameter in the TM1® server configuration

file, Tm1s.cfg. For details, see The Tm1s.cfg Server Configuration File.

Managing Files and Folders for SandboxesEach TM1® server stores the support files for sandboxes in the sub-folders of the TM1 server data

directory. If you are backing up this data, you may want to consider these files and the implications

of backing up and restoring sandbox files.

TM1 Server Configuration Parameters for SandboxesThe TM1® server configuration file, Tm1s.cfg, uses the following parameters for enabling and

managing the sandbox feature:

● DisableSandboxing parameter

● MaxUserSandboxSize parameter

● Capability Assignments

The use of Personal Workspaces or Sandboxes is controlled using the Capability Assingments

option available on the Server Explorer, Server menu. See the System Configuration chapter of

the IBM® Cognos® TM1® Operation Guide for more information.

For more details about the Tm1s.cfg file and these parameters, see the TM1 System Configuration

section in this guide.

Understanding Sandbox Differences Among Different TM1 ClientsThe sandbox feature works slightly differently in TM1® Contributor compared to the legacy clients

of TM1 Perspectives, Server Explorer, and TM1 Web. This information is targeted to those users

or administrators who use a combination of these clients.

Default Sandbox and Base Data

Regardless of other configuration settings, in the TM1® Contributor client, the default sandbox is

called default. This option operates in the same way as the Sandbox feature in other clients. You

cannot turn on a Personal Workspace in the TM1 Contributor client. TM1 Contributor also does

not permit direct writeback so you cannot work directly with the base data when using TM1

Contributor.

TM1 Contributor users can submit their sandbox data to base data only as part of the TM1 Con-

tributor workflow process.

Visibility of Sandboxes in Different TM1 Clients

By design, TM1® Contributor does not display any sandboxes created in TM1 Perspectives, Server

Explorer or TM1 Web. For example, a sandbox created in TM1 Web does not display in the TM1

Contributor client sandbox drop-down list.

Operation Guide 77

Chapter 2: TM1 System Configuration

Page 78: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Using Cube VersioningThis section describes the new Cube Versioning feature available in IBM® Cognos® TM1®.

OverviewCube Versioning (CV) is a new server-related feature in TM1® 9.5.2 that allows for greater concur-

rency of read and write operations on the same cube object. Using CV, writers to a cube will not

be blocked waiting for readers of the same cube to finish their read operation. For example, without

the CV feature, a user that is writing data to a cube can be blocked and forced to wait if another

user is performing an intensive read operation on that same cube, such as recalculating a large

complex view.

When to Use Cube Versioning

Cube Versioning is most useful for cubes that typically experience a large combination of both read

and write activity. In this case, CV provides an improvement over the TM1 legacy concurrency

mode by allowing read and write operations to execute at essentially the same time. In some cases,

read operations might take a little longer when using CV.

Memory usage considerations

TM1 might possibly use more memory when Cube Versioning is enabled as compared to using

TM1 in legacy mode without this feature. Exact memory usage varies depending on the specific

cubes in your TM1 server and the amount of read/write activity on those cubes.

How to use Cube Versioning

Cube Versioning is enabled using a global parameter in the Tm1s.cfg file that enables the feature

for all of the cubes in a TM1 server.

Enabling Cube VersioningBy default, Cube Versioning is disabled. To enable Cube Versioning for a TM1® server, use the

UseCubeVersioning configuration parameter in the Tm1s.cfg file.

UseCubeVersioning parameter

Turns Cube Versioning on or off for all of the user-created and control cubes in a TM1® server.

Parameter Type

● Optional

● Static - If you change this parameter value, you must restart the TM1 server to apply the new

value.

Values

● Default value is F (false)

● F - Disables Cube Versioning for all cubes in the TM1 server.

78 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 79: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● T - Enables Cube Versioning for all cubes in the TM1 server.

Example

The following line enables the Cube Versioning feature.

UseCubeVersioning=T

Configuring and Administering Data ReservationsData Reservation (DR) is a server-related feature that allows you to configure exclusive write-access

to regions of a cube for individual users. Once reserved, the data in that region can only be modified

by that specific user until the reservation is released.

Administrator tasks for DR include configuring related properties in the }CubeProperties control

cube and the Capability Assignments window.

To actually apply and manage Data Reservations, you must use the related TurboIntegrator (TI)

and API functions that allow you to programmatically obtain, release and manage reservations.

For complete details, see the "Using Data Reservations" and "Enabling Data Reservation" sections

in the IBM® Cognos® TM1® Developer Guide.

Operation Guide 79

Chapter 2: TM1 System Configuration

Page 80: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

80 IBM Cognos TM1

Chapter 2: TM1 System Configuration

Page 81: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 3: Understanding Cube Dependency

IBM® Cognos® TM1® server establishes dependencies so it can properly invalidate cube caches.

Dependencies are established generally when a user executes a query on a cube and when that query

includes a rule-calculated value from another cube. A dependency can be established to one or many

cubes based on the scope of the rule within the Base cube.

Here is a simple example of a dependency within TM1:

This cube hasvalues fromCube A or

depends on it.

This cube has valuesthat the Base cube

is using.

Dependent CubeBase Cube

In this simple case, the caches in Base cube are invalided when:

● there is a change in the Base cube itself

or

● there is a change in the dependent cube

Since a dependency is established, when there is a change in the dependent cube, the Base cube must

also change.

Without this dependency map, the Base cube data could become inconsistent with the Dependent

cube. The Base data is dependent upon the data in the dependent cube so any change in the

Dependent cube requires the Base cache to change also.

Changes in Dependency MappingTM1 9.4.1 FP3 introduced a change to the dependency mapping to make TM1 more stable and to

perform better. There is an artifact of this change that users upgrading to TM1 9.4.1 FP3 and above

should understand. In previous releases, this dependency map between cubes was established when

rules were executed that referenced other cubes. However, these dependencies were cleared when

there was any invalidation between the cubes and these dependencies would again be re-established

once the rule was run to establish the dependency.

Dependency behavior now follows these rules:

● Dependencies once established are NOT cleared based on data invalidation.

● Cube dependencies can be established ahead of time using the AddCubeDependency TM1

function.

When dependencies are created, the dependency lists are protected by an object lock between the

cubes affected.

Licensed Materials – Property of IBM81© Copyright IBM Corp. 2007, 2011.

Page 82: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The fact that dependency lists are protected by an object lock and "hangs" off a cube has an

important effect on application upgrade. The dependency blocks writers as well as readers from a

cube object when a reader queries a cube and and when there is a need to add or write to the

dependency list object for that cube. This lock persists for the duration of the read query. For fast

queries, this impact is minimal and a one time "cost" for each cube-to-cube dependency. For slower

queries, however, other users may be blocked for usually long periods. In complex applications,

the dependency object may be locked many times initially as users execute only certain rules. Here

is an example:

A B D

EC F

In this example, the arrows show data flow based on rule connections. Cube B has a two rules: one

that pulls from Cube C and the other pulls from Cube D. Cube D has a single rule that pulls from

Cubes E and F.

A B D

E FC

When User 1 reads from Cube B, a rule calculated there requires data pulled from Cube C. So Cube

B, C and related cube objects are blocked until User 1's query is completed.

A B D

E FCC

When User 2 reads from Cube B, a rule calculated there requires data pulled from Cube D. Cube

B, D, and related cube objects are now blocked until User 2's query is completed.

To address this situation, the TurboIntegrator function AddCubeDependency was created to

establish dependencies. This function allows users to establish dependencies after events such as a

re-start of the server. In the 9.5 series, other enhancements are available to better establish depen-

dencies without any manual intervention.

82 IBM Cognos TM1

Chapter 3: Understanding Cube Dependency

Page 83: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Clearing Cube DependenciesThe following table describes the TM1 events or actions that destroy a cube's dependency:

Dependency ActionEvent

Cube dependency lists are destroyed.Server Shutdown

Eliminates only those cubes where rules have been

deleted or modified.

Rule Compile (Note: any dimensiuon

update casues a rule compile.

When cube dependencies are cleared, depending on the application and the level of user activity,

you may want to establish those cube dependencies manually.

Creating Cube DependenciesThe following table describes the TM1 events or actions that add a cube dependency:

Dependency ActionEvent

Calculated Feeders will create dependencies.Server Startup (not available for TM1

9.4.1 FP3 HS7)

Persistent Feeders also store dependency maps for each

cube.

Server Startup + Persistent Feeders (not

available for TM1 9.4.1 FP3 HS7)

Calculated Feeders for the particular cube rule will cre-

ate dependencies.

Rule Compile

Create dependencies based which rule is executed by

the query.

Rule Calculation

TI Function can create dependencies between cubes.TI Function

Using AddCubeDependency to Establish DependenciesThe AddCubeDependency function is used to create a manual dependency between two cubes.

AddCubeDependency is a TM1® TurboIntegrator function, valid only in TurboIntegrator processes.

This function creates a manual dependency between Cube A and Cube B.

Syntax: AddCubeDependency('CubeA','CubeB');

DescriptionArgument

The name of the base cube.CubeA

Operation Guide 83

Chapter 3: Understanding Cube Dependency

Page 84: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionArgument

The name of the dependent cube.CubeB

Cube B relies on a rule that is dependent on Cube A.

This function can be set in anywhere in the TurboIntegrator Advanced tab.

Debugging and Identifying Cube DependenciesUsing TurboIntegrator to preset dependencies may be necessary. To identify existing cube depen-

dencies requires an in-depth understanding of an application so that you can analyze all of the rules

for each cube including control cubes. Even when you have that level of knowledge about an

application, it is important to turn on the following logging capability to identify cube dependencies

as they are established.

For example, when the following command is added to the the tm1s-log.properties file:

log4j.logger.TM1.Cube.Dependency=DEBUG

the following information is returned that identifies dependencies:

INFO 2010-06-09 18:09:23.728 TM1.Cube.DependencyAdding cube dependency: cube

"}ElementSecurity_}Cubes" depends on cube "}CubeSecurity"

The TurboIntegrator command for this would be:

AddCubeDependency('}CubeSecurity','}ElementSecurity_}Cubes');

84 IBM Cognos TM1

Chapter 3: Understanding Cube Dependency

Page 85: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 4: Remote Server Operations

This section describes how IBM® Cognos® TM1® remote servers work, and how you can manage

their operations.

Overview of Remote Server OperationsThe following figure illustrates the operations of a remote TM1® server. These operations are

explained in the text that follows.

When the TM1 server isstarted, all TM1 data isloaded from the TM1 datadirectory into RAM on theserver machine.

When the TM1 server is shutdown, or when an explicit SaveData command is issued, anychanges to cube values arewritten from the transactional logfile to the data directory.

While the TM1 serveris running, all cubedata resides in RAM.All edits receivedfrom TM1 clients arestored in atransaction log filenamed Tm1s.log.

TM1 Server

TM1 Clients

TM1 clients retrievecube values from theserver. Clients alsosend edits to cubevalues to the TM1server.

❑ On startup, the remote server loads dimensions and cubes from the data directory into the

server machine RAM. At the same time, the server opens a new transactional log file called

Tm1s.log 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.

❑ Clients edit the cube data, sending the values back to the TM1 server.

❑ As new values are received from clients, the TM1 server writes the records to the Tm1s.log 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.

❑ 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.

Licensed Materials – Property of IBM85© Copyright IBM Corp. 2007, 2011.

Page 86: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

❑ When the server shuts down, all records in the Tm1s.log file are saved to disk, and the

transaction log file is renamed by appending a date/time stamp to it. The Tm1s.log file is saved

in the server's data directory to back out data transactions, as described in "Backing Out

Records from the Transaction Log" (p. 97).

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 Tm1syyyymmddhh-

mmss.rej 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 Tm1s.log file are

immediately written to disk, the transaction log file is renamed by appending a date/time stamp

to it, and a new Tm1s.log 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.

Setting Up a Remote TM1 Server to Run as an ApplicationWhen you run the TM1® Installation Wizard, the TM1 server is installed as a Microsoft® Windows®

service by default. However, you can set up the TM1 server to run as an application.

Steps

1. Open the install_dir\bin directory in Windows Internet Explorer.

2. Right-click Tm1s.exe.

3. Select Create Shortcut.

Windows creates Shortcut to Tm1s.exe in the install_dir\bin directory.

4. Right-click Shortcut to Tm1s.exe.

5. Select Properties.

The Properties window opens.

6. Click the Shortcut tab.

The Target field on this tab contains the full path to Tm1s.exe.

7. In the Target field, add the -z flag and specify the full path to the directory containing the

Tm1s.cfg file for the server.

For example, -z C:\TM1\salesdata indicates that the Tm1s.cfg file for the server resides in the

C:\TM1\salesdata directory.

Note: If the path to the directory contains any blank spaces, enclose the entire path with double

quotes.

The contents of the Target field should resemble the following:

"C:\Program Files\Cognos\TM1\\bin\tm1s.exe" -z C:\TM1\salesdata

8. Click OK to save the shortcut.

86 IBM Cognos TM1

Chapter 4: Remote Server Operations

Page 87: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

You might want to move the shortcut to the desktop for easy access.

Setting Up a Remote TM1 Server to Run as a Windows ServiceYou can manually install a TM1® server to run as a Windows service, or remove an existing one,

using the command line options of the tm1sd.exe file. The tm1sd.exe file is installed in the TM1

install\bin directory.

The following sections describe how to configure a TM1 server to run as a Windows service.

● Installing a TM1 Server to Run as a Windows Service

● Removing a TM1 Server from Running as a Windows Service

Installing a TM1 Server to Run as a Windows ServiceTo install a TM1® server to run as a Windows service, use the following command line format:

tm1sd.exe -install parameters

The following table lists the available parameters.

Required/Optional

Description

Parameter

Required-n

Name of the TM1 Server. This will become the Windows service name as

shown when you display the properties of an installed service.

Required-z

Data directory that contains the tm1.cfg file for the TM1 database.

Optional-u

Valid user name for the computer on which you are working. Use one of the

following formats:

● Domain and user name in the format Domain\username. For example,

entp\jsmith.

● User name for a local user account.

If you do not provide a user name, the current user account is used by default.

Optional-w

Password for the above account.

For example, the following command line installs the sdata TM1 server as a Windows service for

the current user.

tm1sd.exe -install -n sdata -z C:\Program Files\Cognos\TM1\Custom\TM1Data\SData

Operation Guide 87

Chapter 4: Remote Server Operations

Page 88: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Removing a TM1 Server from Running as a Windows ServiceTo remove a TM1® server that is running as a service, use the following command line format:

tm1sd.exe -remove -n ServerName

where ServerName is the Microsoft® Windows® service name of the TM1® server you want to

remove.

For example, the following command line removes an existing service for the sdata TM1 server.

tm1sd.exe -remove -n sdata

Starting a Remote TM1 ServerThe following sections describe how to start all versions of the TM1® server.

● Starting a TM1 Server Set Up as a Windows® Application

● Starting a TM1 Server Installed as a Windows Service

● Starting a UNIX® TM1 Server

Starting a TM1 Server Set Up as a Windows ApplicationYou can start a remote server that has been set up as a Windows application.

Step

● Double-click the TM1 Sales Data icon.

A server window opens. The server window lists the cubes and dimensions loaded into the server

RAM.

Starting a TM1 Server Installed as a Windows ServiceTo start a remote server that has been installed as a service, complete the following steps.

Steps

1. Open Windows Control Panel.

2. Double-click the Services icon. (On Windows 2000 and XP, open the Administrative Tools

folder, and double-click the Services icon.)

A list of installed services opens.

3. Select the entry for the TM1® server you want to start, for example Planning Sample, and click

the Start button.

An Admin Server must be running before a TM1 server can start. If you have specified an

Admin Host in the Tm1s.cfg file, 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 an Admin Server

for any reason.

88 IBM Cognos TM1

Chapter 4: Remote Server Operations

Page 89: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

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,

either as a service or an application, the TM1 server starts a new Admin Server application and

connects to it.

Setting up a Service to Start Automatically

To set up an installed service to start automatically when Windows reboots, complete the following

steps.

Steps

1. Open Windows Control Panel.

2. Double-click the Services icon.(On Windows 2000 and XP, open the Administrative Tools

folder, and double-click the Services icon.)

A list of installed services opens.

3. Double-click the TM1Server entry.

The Service Properties dialog box opens.

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

When you install TM1 , the TM1® server is installed as a service by default, which starts

automatically.

Starting a UNIX TM1 ServerTo assist you in starting a UNIX® TM1® server, a sample script named tm1s_start_example is

installed in the TM1_install_dir/bin directory. With a few minor modifications, you can use this

sample script to start your UNIX TM1 server. When you use the script to start a server, TM1 uses

the Tm1s.cfg file in the specified data directory to govern the behavior of the server.

Modifying the tm1s_start_example Script

You modify the tm1s_start_example.

Steps

1. Open the file in a text editor.

2. Set the tm1_path parameter to the directory containing the tm1s.exe server executable file. In

most circumstances, this directory is TM1_install_dir/bin.

3. Set the tm1_data_path parameter to your server data directory.

4. Set the TM1_PATH parameter to directory containing the tm1s.exe server executable file. In

most circumstances, this directory is TM1_install_dir/bin.

Note: You must set both tm1_path and TM1_PATH to the same directory.

5. Save the script.

Operation Guide 89

Chapter 4: Remote Server Operations

Page 90: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

You can save to a new file name if desired. If you have installed multiple TM1® servers, you

should create server-specific scripts with unique file names for each server.

6. Run ./tm1s_start_example (or the new file name) to start your TM1 server.

Running the UNIX TM1 Server in Background Mode

You can run the TM1® server in background mode by adding the parameter RunningInBackground

to the tm1s.cfg file and setting the parameter to T.

RunningInBackground=T

You must manually add the RunningInBackground parameter to Tm1s.cfg. This parameter is not

part of the standard tm1s.cfg file created when you install the TM1 server.

When you run the TM1 server in background mode, you must use Tm1srvstop.exe to shut down

the server. For details, see "Shutting Down a Windows TM1 Server" (p. 91).

Connecting to a Remote ServerTo connect to a remote TM1® server, a client must point to an Admin Host on which an Admin

Server is running. The Admin Server maintains information about remote TM1 servers available

on the network, including name, protocol, address, and port number. The Admin Host used by the

client is specified in the Tm1p.ini file.

Steps

1. Access Server Explorer.

2. Double-click the icon for the server to which you want to connect.

The Server Login dialog box opens.

3. Enter the correct user name and password, and click OK.

If the connection to the server is successful, TM1 displays the Cubes, Dimensions, Replications,

Processes, and Chores icons for that server. (The Replications icon displays only if you logged

in as a member of the ADMIN group.)

Note: The TM1 remote server comes with a predefined administrator ID of ADMIN, and a

password of apple.

Refreshing the List of Remote ServersIf you do not see the remote server to which you want to connect in the list of available servers,

you can refresh this list.

Step

● Click File, Refresh Available Servers. TM1® displays all running servers that are registered on

the Admin Host to which the client is pointing.

90 IBM Cognos TM1

Chapter 4: Remote Server Operations

Page 91: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Re-Setting the Admin HostYou can set or change the Admin Host.

Steps

1. From Server Explorer, click File, Options.

The TM1® Options dialog box opens.

2. Enter the name of the Admin Host in the Admin Host field. You can concatenate two or more

hosts by separating the host names with a semicolon.

You can also click the drop-down menu to select from previously accessed Admin Hosts.

3. Click OK.

When you change the Admin Host, TM1 disconnects you from the remote servers to which

you are connected and restarts your TM1 client. If a local server is running, that server is shut

down and restarted.

Re-Setting Local Server OptionsThe following table describes the Local Server options that you can change through the TM1®

Options dialog box.

DescriptionLocal Server Option

Directory for the local server data files.Data Directory

Select or clear the Connect to Local Server on Startup check box

to control whether the TM1 client automatically connects to the

local server at startup.

Connect to Local Server on

Startup

Disconnecting from a Remote ServerYou can disconnect from a remote server.

Steps

1. In Server Explorer, select the icon for the server from which you want to disconnect.

2. Click Server, Log Out.

Shutting Down a Windows TM1 ServerYou can shut down a remote server that has been set up to run as a Windows application.

Step

● Click the Close button in the server window.

Operation Guide 91

Chapter 4: Remote Server Operations

Page 92: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Shutting Down a Windows TM1 Server Running as a ServiceYou can shut down a remote server that has been installed as a Windows service.

Steps

1. Open Windows Control Panel.

2. Double-click the Services icon. (On Windows 2000, open the Administrative Tools folder, and

double-click the Services icon.)

A list of services opens.

3. Right-click Server and select Stop.

For details on shutting down a server from a remote location when logged in as an ADMIN

user, see "Managing Client Connections" (p. 98).

The TM1® server running as a Windows service automatically shuts down during system shutdown.

In some instances, a server running a large or complex model, might not properly shut down during

system shutdown, power failure, or manual service shutdown. An improper shutdown is defined

as a shutdown in which the TM1 server is summarily terminated before it has completed all shutdown

procedures. This can happen during normal system shutdown because Windows allots a limited

time (approximately 20 seconds) for service shutdown. After the allotted time expires, the system

shutdown proceeds regardless of whether the service shutdown is complete.

When the TM1 server is running as a service, it automatically recovers any data changes from the

previous sessions in which an improper shutdown occurs. The changes are recovered from records

in the server's Tm1s.log file.

For details on Microsoft's approach to service shutdown or on increasing the amount of time

allotted by Windows for service shutdown, see the Microsoft support website.

Shutting Down a UNIX TM1 ServerYou can shut down a server running in the foreground.

Steps

1. Press CTRL+C in the window from which you started the server.

2. Before you exit, the server prompts you to save all data to disk. Press ENTER (or RETURN)

to save all data. Type No and press ENTER to shut down the server without saving the data.

Shutting Down a UNIX TM1 Server Running in Background ModeTo shut down the TM1® server running in background mode, run tm1srvstop.exe, located in the

install_dir/bin directory.

The tm1srvstop.exe file accepts the following parameters:

92 IBM Cognos TM1

Chapter 4: Remote Server Operations

Page 93: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Required/Optional

Description

Parameter

Required-n

The name of the TM1 server you want to shut down. Note that this server

must have been started in background mode.

Required-v

IP address of the Admin Server on which the TM1 server is registered.

Required-user

User name of the person bringing down the server. This person must have

the necessary access and privileges to shut down the server.

Required-pwd

Password for the person bringing down the server.

Optional-time

Delay, in seconds, at which the server will be shut down after running

tm1srvstop.exe.

Optional-cancel

Cancels any previously issued Tm1srvstop.exe commands.Valid values are

T and F.

Optional-unsave

By default, TM1 saves the data before a TM1 server is shut down with the

Tm1srvstop.exe command. The -unsave parameter shuts down a server

without saving the data. Valid values are T and F.

For example, the following command line allows a user named Admin with a password of Admin-

istrator to shut down a TM1 server named TM1SERV registered on an Admin Host located at

207.110.100.206. The command line indicates a 30-second interval between the time the command

is issued and the time the server shuts down. The server is shut down without saving the data.

tm1srvstop.exe -n TM1SERV -v 207.110.100.206 -user ADMIN-pwd Administrator -time 30 -unsave T

Logging TransactionsEach TM1® server tracks the data transactions made by its clients. When a client changes a cube

value, TM1 records the change in a transaction log file named Tm1s.log, which is located in the

TM1 server data directory.

The information recorded in the log file includes:

Operation Guide 93

Chapter 4: Remote Server Operations

Page 94: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Date and time the change was made.

● Name of the client who made the change.

● Whether the new data is simple data (N) or string data (S).

● Value before the change.

● Value after the change.

● Name of the cube in which the change was made.

● Elements that identify the cell that changed.

● Optional user-provided string that is attached to each transaction. You create the string with

the TM1ServerLogSetFlagString API function.

The log file is a comma-delimited ASCII file, as shown in the following sample:

"19980602212741","19980602212741","Admin","N","380.","250.","salescube","Budget","Belgium","LSeries 1.6 L Sedan","Units","Jun","""19980602212744","19980602212744","Admin","N","430.","600.","salescube","Budget","Belgium","LSeries 1.6 L Sedan","Units","Sep","""19980602212749","19980602212749","Admin","N","610.","800.","salescube","Budget","Belgium","LSeries 1.6 L Sedan","Units","Oct",""

Data Backup and RecoveryThe Tm1s.log file remains open while the TM1® server is running. When you bring down the server

normally, TM1 renames the log file by appending a time stamp to it, and with the following naming

convention:

Tm1syyyymmddhhmmss.log

The time stamp, yyyymmddhhmmss, represents the current Greenwich Mean Time at the time the

server was brought down. For example, if the server came down on January 2, 2002, at 2:30 PM,

the name of the log file is Tm1s20020102143000.log.

TM1 recovers the data automatically in the event that a server comes down abnormally, and leaves

the Tm1s.log file on the disk. The next time you bring up the server, TM1 recovers the changes in

either of two ways:

● Automatically recovers the changes -- when you are running the TM1 server as a Windows

service

● Prompts you to recover the changes -- when you are running the TM1 server as an application

If you intentionally shut down a TM1 server without saving the data, TM1 saves the transaction

log with a time stamp and changes the file extension to .rej. For example, Tm1s20020102143000.

rej. The .rej log file ensures that you always have a record of the data transactions, even if you shut

down the server without saving the data. If you accidentally shut down the server without saving

the changes, you can process the .rej file through TurboIntegrator to recover the data.

94 IBM Cognos TM1

Chapter 4: Remote Server Operations

Page 95: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Enabling and Disabling LoggingBy default, TM1® logs transactions to all cubes loaded on the server. As the system administrator,

you have the option to turn off logging for particular cubes.

When you disable logging, TM1 accelerates updating the data but you cannot recover the updates

in the event of a system failure.

You can enable logging for individual cubes.

Steps

1. Open Server Explorer.

2. Select the Cubes icon for the server you are working with.

3. Select Cubes, Security Assignments.

The TM1 Security Assignments dialog box opens.

4. Click the cell at the intersection of the Logging column and the cube name.

TM1 enables logging when a check box contains an X, and disables logging when the check

box is empty.

5. Click OK.

Viewing the Transaction LogYou can query the transaction log (Tm1s.log) to view the records of all the logs currently in the

TM1® server data directory. When you query the transaction log, TM1 combines all the log files

into one logical file that satisfies the query parameters. For example, if you query for all the records

starting on Jan. 2, 2002 at 2:30 PM GMT, TM1 returns all the records in all the transaction logs

with a time stamp of 20020102143000 or later.

Note: You must use a 9. 5 or newer TM1client to view log files on a 9.5.x server. The transaction

log does not display correctly when you use a pre-9.5 client to view log files on a 9.5.x server.

Steps

1. Select the server in Server Explorer.

2. Click Server, View Transaction Log.

The Transaction Log Query dialog box opens.

3. Click the right arrow in a parameter field to set the parameters for the query.

There are four parameters you can set:

Operation Guide 95

Chapter 4: Remote Server Operations

Page 96: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

Queries all the records written to the transaction log on or after

the starting time.

Starting Time

Start date and time for the query. The date and time format is

MM/DD/YYYY HH:MM:SS GMT. The default start date and

time is 00:01:00 GMT on the date you launch the query.

End date and time for the query. The date and time format is

MM/DD/YYYY HH:MM:SS

End Time

The default is __/__/____ __:__:__, which is an open end date

and time. If you accept the default, TM1 queries all the records

up to the time you launch the query.

The client(s) against which you apply the query.Clients

You can query against either a single client or all the clients. The

default is all clients (*).

The cube(s) against which you apply the query.Cubes

You can query against either a single cube or all the cubes. The

default is all cubes (*)

4. Click OK.

The query returns a table with all the transaction records that satisfy the parameters you set.

The table displays in the Transaction Log Query Results dialog box.

By default, records are sorted in ascending order by LOGTIME.

At any time after you start the query, you can click Cancel to stop the search. When you choose

Cancel, nothing is returned for your search.

5. To sort on a different column, click the column heading. To change the order of a column sort,

click the column heading a second time.

6. Click Edit, Find to search the records in the query results table.

Setting Search Lock LimitWhen the Transaction Log is searching, other users are locked out of performing activity on the

log. By default the log searches 5000 lines before it temporarily releases the lock so that other users

can access the log. You can change the number of lines searched before the lock is temporarily

released using the LogReleaseLineCount parameter set in the TM1s.cfg file. See The TM1s.cfg File

for more information about the TM1s.cfg file.

96 IBM Cognos TM1

Chapter 4: Remote Server Operations

Page 97: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Backing Out Records from the Transaction LogAfter you query the transaction log, you can use the Transaction Log Query Results dialog box to

back out the transactions. When you back out a transaction, the value in the OLDVALUE column

replaces the value in the NEWVALUE column.

Steps

1. Highlight the record(s) you want to back out.

To highlight an individual record, click the record.

To highlight multiple adjacent records, click the first record and SHIFT+click the last record.

To highlight multiple non-adjacent records, CTRL+click each record.

2. Click Edit, Select.

All the highlighted records now display a check mark in the box adjacent to the first column.

The check marks indicate that the record is selected to be backed out.

To select all the records without first highlighting them, click Edit, Select All.

3. Click Edit, Back Out.

TM1® backs out the records in reverse chronological order as identified by the LOGTIME

column.

Removing Log Files from the DiskThe TM1® log files can take up a substantial amount of disk space after the server has been running

for some time. You should remove the old log files from your disk every so often, depending on

the volume of the changes you make and the size of your disk. You can back up these files before

you erase them.

Do not remove the log files when the TM1 server is running. First shut down the server, and then

delete the log files from your disk.

Monitoring Server PerformanceTM1® includes a performance monitoring feature that lets you record the performance statistics

for clients, cubes, and servers. When you enable performance monitoring, TM1 populates several

control cubes on a minute-by-minute basis. You can then browse these cubes to analyze the server

performance.

The following control cubes are populated during performance monitoring. For details, see "Control

Cubes" (p. 287).

DescriptionCube

Tracks the message count, average message size, total elapsed time,

and other measures for each client on the server.

}StatsByClient

Operation Guide 97

Chapter 4: Remote Server Operations

Page 98: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionCube

Tracks the memory used for each cube on the server.}StatsByCube

Tracks the number and elapsed time of cell updates, cell retrievals,

view calculations, and view retrievals for each client and cube on the

server.

}StatsByCubeByClient

Tracks the connected clients, active threads, and memory used by the

server.

}StatsForServer

Steps

1. Select the server in Server Explorer.

2. Click Server, Start Performance Monitor.

You have enabled performance monitoring on a per-session basis.

If you want to enable performance monitoring at the start of every server session, you can set

the PerformanceMonitorOn parameter in the Tm1s.cfg file to automatically begin performance

monitoring when a server starts.

To end performance monitoring during a server session:

3. Select the server in Server Explorer.

4. Click Server, Stop Performance Monitor.

Managing Client ConnectionsAs a TM1® server administrator, you can use the Clients Messaging Center to perform the following

tasks.

● Broadcasting Messages to Clients

● Disconnecting Clients from the Server

● Shutting Down a Server Remotely

Broadcasting Messages to ClientsIf you are a member of the ADMIN group for a TM1 server, you can broadcast messages to any

clients that are connected to the server. For example, you can inform clients that they are going to

be disconnected from the server or that the server is going to be shut down.

Steps

1. In the left pane of Server Explorer, select the server on which you want to broadcast a message.

2. Click Server, Server Manager.

The Clients Messaging Center dialog box opens.

98 IBM Cognos TM1

Chapter 4: Remote Server Operations

Page 99: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

3. Select Do nothing to broadcast the message without shutting down the TM1 server.

4. Select Broadcast a Message.

5. Enter the message you want to broadcast in the Broadcast Message box.

6. Click Select Clients.

The Subset Editor opens with a subset of all the clients that are currently connected to the TM1

server. You cannot send messages to clients that are not currently connected to the server.

7. Select the clients you want to receive the message and click OK.

8. Click OK in the Clients Messaging Center to broadcast the message.

Disconnecting Clients from the ServerYou can disconnect clients from a TM1® server.

Steps

1. In the left pane of Server Explorer, select the server from which you want to disconnect clients.

2. Click Server, Server Manager.

The Clients Messaging Center dialog box opens.

3. Select Disconnect Clients.

4. Specify a Minutes interval to determine when the clients will be disconnected.

5. Click Select Clients.

The Subset Editor opens with a subset of all clients that exist on the server. The subset is not

a subset of all clients currently connected.

6. Select the clients you want to disconnect and click OK.

A message is sent to all selected clients with a warning that they will be disconnected at the

interval you specified in Step 4.

7. If you want to broadcast a more detailed message to the selected clients, you can select the

Broadcast Message to Selected Clients option and enter a message in the Broadcast Message

box.

8. Click OK in the Clients Messaging Center.

Shutting Down a Server RemotelyYou can shut down a server remotely from a TM1® client.

Steps

1. In the left pane of Server Explorer, select the server you want to shut down.

2. Click Server, Server Manager.

Operation Guide 99

Chapter 4: Remote Server Operations

Page 100: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The Clients Messaging Center dialog box opens.

3. Select Shutdown Server.

4. Specify a Minutes interval to determine when the server will be shut down.

5. Click OK.

Any clients currently connected to the server receive a message that the server will be shut down

in the number of minutes you specified in Step 4.

Remote Server Memory ManagementThe TM1® server uses a sparse memory management scheme, which allows the server to hold very

large cubes in much less space than the same data would occupy in a relational database. Therefore,

the memory management scheme allows the server to accommodate very large databases in RAM

without the need to use disk space.

The RAM that is used by the server is not static. When the remote server calculates the consolidations,

the server stores the results for later reference. The second time a consolidated value is requested,

TM1 can deliver the value without calculation, which provides a great improvement in speed.

The remote server memory management approach means that the longer the server runs, the faster

it becomes, as an ever-increasing number of consolidations are stored and do not need to be recal-

culated. The amount of memory the server uses increases incrementally. The server does not take

memory byte-by-byte, but rather takes a larger piece every so often.

TM1 does not release the memory back to the operating system until the TM1 server is terminated.

Instead, TM1 puts memory it no longer needs into a garbage list, to be reused as required.

Accordingly, the memory consumption for the TM1 server, as reported by the operating system, is

the total of the actual current memory usage and the garbage memory. You can view an accurate

report of the actual memory usage and garbage memory by viewing the }StatsForServer control

cube, which is described in "Control Cubes" (p. 287).

All the remote server platforms support virtual memory, where disk space is used as if it were RAM.

The server runs in virtual memory, but it slows down the performance significantly. The best

practice is for you to keep all the cubes in real RAM at all times.

You should keep an eye on the memory consumption by using the system-monitoring utilities. If

the system runs slowly, you might need to add more RAM to your server.

Some operating systems maintain a configurable limit on the memory they will allocate to any one

process. If your system appears unable to take all the memory that should be available to it, you

might want to look at the operating system parameters.

You can limit the amount of memory allocated to any individual view by adding the MaximumView-

Size parameter to the Tm1s.cfg file. The MaximumViewSize parameter is documented in "TM1

System Architecture" (p. 17).

100 IBM Cognos TM1

Chapter 4: Remote Server Operations

Page 101: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

About Stargate ViewsA Stargate view is a calculated and stored subsection of a TM1® cube that TM1 creates when you

browse a cube with the Cube Viewer or In-Spreadsheet Browser. The purpose of a Stargate view is

to allow quicker access to the cube data.

A Stargate view is different from a TM1 view object. The Stargate view contains only the data for

a defined section of a cube, and does not contain the formatting information and browser settings

that are in a view object.

A Stargate view that TM1 creates when you browse a cube in the Cube Viewer or In-Spreadsheet

Browser contains only the data defined by the current title elements and row and column subsets.

TM1 stores a Stargate view when you access a view that takes longer to retrieve than the threshold

defined by the VMT property in the }CubeProperties control cube. (If a VMT value is not explicitly

defined, a Stargate view is generated when a view takes longer than five seconds. This is the default

threshold when VMT is not specified in the }CubeProperties control cube.)

A Stargate view persists in memory only as long as the browser view from which it originates

remains unchanged. When you recalculate the browser view, TM1 creates a new Stargate view

based on the recalculated view and replaces the existing Stargate view in memory. When you close

the browser view, TM1 removes the Stargate view from memory.

Using TM1 in Bulk Load ModeBulk Load Mode enables TM1 to run in a special optimized single-user or single chore/process

mode. This mode can maximize TM1 performance for dedicated tasks during times when little or

no other activity is expected.

Some examples of using Bulk Load Mode include:

● A TM1 administrator that needs to manually perform maintenance operations.

● A night-time window to load large amounts of data.

TM1 typically runs in a multi-user mode where multiple users, chores and processes can all run

concurrently accessing TM1 data. In Bulk Load Mode, the TM1 server prevents concurrent activity

by temporarily suspending other users, chores and processes and eliminates the overhead required

by a multi-user environment.

Bulk Load Mode doesn't actually log out users, but only suspends their interaction with TM1. As

soon as Bulk Load Mode is done, any users that were previously logged in are reactivated and user-

interaction with TM1 resumes.

You can enable Bulk Load Mode directly within a TI process or with the TM1 API. In either case,

you use commands to enter and leave Bulk Load Mode.

Considerations for Using Bulk Load ModeYou should consider the following when using Bulk Load Mode:

● Bulk Load Mode does not display a message to end-users to alert them. You will need to plan

and coordinate your usage of Bulk Load Mode accordingly.

Operation Guide 101

Chapter 4: Remote Server Operations

Page 102: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Only a single user or process may be active during Bulk Load Mode. No new connections can

be established to the server while it is operating in Bulk Load Mode.

● A TI process can not use the ExecuteCommand to launch a command line program that attempts

to log back into the same TM1 server. The login attempt will fail.

● Any scheduled chores that are scheduled to execute during the time Bulk Load Mode is enabled

are deactivated and not run.

Starting Bulk Load Mode

When the server enters Bulk Load Mode, all processing by other threads is paused. Any existing

user threads and running chores will be suspended. Only the thread that initiated Bulk Load Mode

will remain active. All scheduled chores will be deactivated, except the chore that initiates Bulk

Load Mode. All system-specific threads and TM1Top connections will also be suspended.

Ending Bulk Load Mode

When Bulk Load Mode is disabled, all system and user threads will be resumed and user logins will

be allowed.

Custom applications that use the TM1 API to enable Bulk Load Mode should also call the necessary

TM1 API function to exit Bulk Load Mode. However, if the client connection is severed (the network

fails or the client logs out, crashes or disconnects), the server will automatically exit Bulk Load

Mode.

Similarly, if a TI process/chore is running in Bulk Load Mode and the process exits, whether

successfully or with errors, the server will automatically exit Bulk Load Mode.

When the server returns to normal multi-user mode, any chores that were deactivated get reactivated

and return to their normal schedule. If the chores were scheduled to run, but were prevented by

Bulk Load Mode, they will not get executed immediately, but will execute according to the schedule.

You may have to adjust the launch time of your scheduled chores to prevent them from getting

locked out during the times you enable Bulk Load Mode.

TM1 C APIUse the following TM1 API functions to enable and disable Bulk Load Mode.

TM1V TM1ServerEnableBulkLoadMode(TM1P hPool, TM1Server hServer)

TM1V TM1ServerDisableBulkLoadMode(TM1P hPool, TM1Server hServer)

where:

● TM1P is a pool handle obtained with TM1ValPoolCreate.

● TM1Server is a handle to the current server.

TurboIntegrator Process CommandsYou can enable Bulk Load Mode in either the Prolog or Epilog section of a TI process. For efficiency,

we recommend enabling Bulk Load Mode in the first, or very close to the first, statement in the

Prolog section of your process.

102 IBM Cognos TM1

Chapter 4: Remote Server Operations

Page 103: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

After enabling Bulk Load Mode in a process, it can only be disabled on the last line in the Epilog

section. If you attempt to disable Bulk Load Mode anywhere else in the process, the process will

not compile.

If the mode is enabled in one TI process, it remains enabled until explicitly disabled or until the

chore completes. This means you can enable the mode in a process within a chore and then run a

series of TI processes before disabling it. You can also enter and exit Bulk Load Mode repeatedly,

using the mode only for certain critical parts of a chore.

Use the following TI commands to enable and disable Bulk Load Mode in a TI process.

EnableBulkLoadMode()

DisableBulkLoadMode() - This function can only be used on the last line in the Epilog section of

your TI process when using Bulk Load Mode.

Operation Guide 103

Chapter 4: Remote Server Operations

Page 104: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

104 IBM Cognos TM1

Chapter 4: Remote Server Operations

Page 105: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 5: Replicating Cubes

This section describes how you can replicate cubes from one IBM® Cognos® TM1® server to another,

and synchronize the updates across the copied cubes.

Replication OverviewDepending on your access privileges, you can copy cubes (and their associated dimensions, rules,

subsets, and views) from one server to another, and synchronize the updates among the copied

cubes either at specified time intervals or on demand. The process of copying cubes from one server

to another is called replication.

Note:Replication and synchronization operations in IBM® Cognos® TM1® should only be performed

by members of the ADMIN group. Members of the DataAdmin and SecurityAdmin groups do not

have all the required access privileges to perform these operations.

Advantages of Using Replication

Replication offers the following advantages.

● Enhances response time because users can update a cube locally without having to communicate

across a network.

● Lets users access and update a copy of a cube, even when they are not connected to the remote

server on which the original cube resides.

● Greatly enhances the scalability of TM1.

TM1 provides bi-directional synchronization for replicated cubes. During the synchronization

process, TM1 copies the data updates and metadata from the original cube to its replicated versions,

and copies the data updates from the replicated versions back to the original cube.

Considerations When Using Replication

The following considerations apply to replication:

● TM1 versions - All TM1® servers in a replication process must be the identical version.

● Remote servers - You can replicate cubes that reside on remote servers only. You cannot

replicate cubes that reside on local servers.

● Local servers - TM1 clients can replicate cubes to their local server only if they are running that

server as an independent process. The machine must have a network card. To run a local server

as an independent process, clients need to select the Local Server Execution Mode: Independent

Process option in the TM1 Options dialog box.

● Access privileges - When you replicate a source cube on a remote server to a local server, any

elements to which the local client has NONE access on the remote server, will have a value of

zero. If the client has READ (or higher) access to a consolidation that includes elements to

Licensed Materials – Property of IBM105© Copyright IBM Corp. 2007, 2011.

Page 106: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

which the client has NONE access, the consolidation will appear to be the sum of only those

elements to which the client has READ (or higher) access. The consolidation, as reported to

the client, will not be the sum of all elements, as in the source cube.

Note: When you set security levels and establish replication to the local servers, you must know

the implications of replicating data to which a client does not have at least READ access.

● Tm1s.cfg file - The Tm1s.cfg file must be configured to register the target and source servers

with the same TM1 Admin Server. For details, see "Configuring the Tm1s.cfg File to Support

Replication" (p. 110).

● Length of directory path and cube name - The total length of the pathname for the target TM1

server's data directory and the name of the cube you are replicating can not exceed the Windows

pathname limit of approximately 256 characters. If this limit is exceeded, due to a long pathname

or cube name, TM1 displays the following error message: Could not register the cube.

● Transaction Logging - If you are performing a synchronization process, transaction logging

must be enabled for the mirror cubes on the target server that are part of the replication and

synchronization process. If you are performing a bi-directional synchronization, transaction

logging must be enabled for all the related cubes on both the source and target servers.

TM1 uses these log files to keep track of the changes made to the source and mirror cubes. To

verify that transaction logging is enabled, see "Enabling and Disabling Transaction Log-

ging" (p. 124) in the IBM® Cognos® TM1® Operation Guide.

● CubeProperties Control Cube - The values stored in the CubeProperties control cube are specific

to a TM1 server and are not copied from the master to the target server during a replication

process. For example, if you wanted the Measures dimension for a replicated cube to be set on

the target server, you would have to manually set the value in the CubeProperties control cube

on the target server.

Relationships Created by ReplicationA replication creates a relationship between two cubes and between two servers. There are two

types of relationships: cube and server. A replication creates server configurations.

Cube Relationships

When you replicate a cube, the original cube is called the source cube, and a copy of that cube is

called the mirror cube. You can replicate a single cube on many different servers, and you can

replicate a replicated cube.

Server Relationships

To replicate a cube, you must log on to a remote server and create a replication connection. This

connection establishes the remote server that you just logged on to as a source server and the server

you logged in from as the target server.

After you establish a replication connection, you can replicate as many cubes as you want to through

this connection. TM1® uses the logon ID for the replication connection to determine your access

rights to the source data.

106 IBM Cognos TM1

Chapter 5: Replicating Cubes

Page 107: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The same TM1 server can be both a target server for some cubes, and a source server for other

cubes. In this situation, there would be two replication connections between the target and source

servers, as illustrated in the following diagram.

Region 1 Region 2

Cube A

Cube B

Target server

Source server

Source server

Target server

The synchronization process occurs at the server level, rather than at the cube level. When you

synchronize the replication connection, TM1 updates all the mirror cubes that are part of the same

replication connection. For example, if you replicate Cubes A and B from a central server to the

Region 4 server, both of these cubes are updated when you initiate the synchronization process for

the replication connection between these two servers.

Typical Server Configurations

The typical server configurations that TM1® create when you replicate cubes are shown in the fol-

lowing diagram.

Note: As the TM1 administrator, you must ensure that no loops are created through a replication.

When you replicate a single cube on many different servers, you create a star configuration of

servers. For example, you can replicate Cube A from a central server to four regional servers.

Operation Guide 107

Chapter 5: Replicating Cubes

Page 108: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Central server

Region 1

Cube A1(Mirror of cube A)

Region 2

Cube A1(Mirror of cube A)

Cube A

Region 4

Cube A1(Mirror of cube A)

Region 3

Cube A1(Mirror of cube A)

When you replicate a replicated cube, you create a chain configuration of servers. For example,

using the star configuration of servers, Cube A can be replicated from Region 3 to a local server.

Region 3

Central server

Cube A(Mirror of cube A)

Cube A1(Mirror of cube A)

Local server

Cube A2(Mirror of cube A)

You can combine the star and chain configurations, as shown below.

108 IBM Cognos TM1

Chapter 5: Replicating Cubes

Page 109: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Central server

Region 1

Cube A1(Mirror of cube A)

Region 2

Cube A1(Mirror of cube A)

Region 4

Cube A1(Mirror of cube A)

Region 3

Cube A1(Mirror of cube A)

Cube A2(Mirror of cube A1)

Local server

Cube A2(Mirror of cube A1)

Local server

Cube A(Mirror of cube A)

Required Access PrivilegesTo replicate a cube, you need the following access privileges:

● Read access or higher to the cube you want to replicate.

If you have access privileges for only certain elements in a cube, TM1® copies the values for

those elements, but does not populate the rest of the cube.

● Admin access to the server where you are creating the replicated cube. You must be in the

ADMIN group on that server. Members of the DataAdmin and SecurityAdmin groups do not

have all the required access privileges to perform replication and synchronization operations.

Users have Admin access to their local servers and can replicate any cube for which they have Read

access to the local server.

As the TM1 administrator, you are responsible for replicating cubes on the remote servers.

Note: Although you can replicate a cube if you have Read access to it, you need Reserve access to

the cube to write updates back to cube during the synchronization process. See "Synchronization

Process" (p. 115).

Admin Server ConsiderationsWhen you establish a replication connection, both the source server and the target server must be

registered on the same Admin Server. If the two servers do not share the same Admin Server, the

replication and synchronization results are unpredictable.

For details on verifying that the source and target servers register with the same Admin Server, see

"Configuring the Tm1s.cfg File to Support Replication" (p. 110).

For details on the Admin Server, see "TM1 Admin Server" (p. 17).

Operation Guide 109

Chapter 5: Replicating Cubes

Page 110: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Setting up Replication

There are three stages you must follow to set up a replication for a TM1® system.

❑ Create a replication connection between the target and source servers. See "Replication Pro-

cess" (p. 112).

❑ Replicate one or more cubes from the target server to the source server.

❑ After you make updates to the cubes, initiate the synchronization process, if synchronization

is done on demand. See "Synchronization Process" (p. 115).

Configuring the Tm1s.cfg File to Support ReplicationThe target and source TM1® servers must be registered with the same TM1 Admin Server. Each

server can be registered with other Admin servers, but the target and source servers must share at

least one common Admin Server.

Edit the AdminHost parameter in the Tm1s.cfg file for the target TM1 server so it registers with

the same Admin Server as the source.

AdminHost=hostname1;hostname2

where:

● hostname1 is the computer name or IP address of the TM1 Admin Host where the target TM1

server is registered.

● hostname2 is the computer name or IP address of the TM1 Admin Host where the source TM1

server is registered.

You can use a mix of computer names and IP addresses and you can also list multiple Admin hosts:

For example:

AdminHost=boston;newyork

or

AdminHost=192.168.1.17;192.168.1.22

or

AdminHost=boston;192.168.1.17;192.168.1.22;myserver;192.168.1.40

Maintaining Replication ConnectionsIn order to replicate cubes, you must first create a replication connection between two servers.

Creating a Replication ConnectionTo create a replication connection between two servers, complete the following steps.

Steps

1. Open the Server Explorer.

2. Make sure that the target server is visible.

110 IBM Cognos TM1

Chapter 5: Replicating Cubes

Page 111: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

3. Double-click the Replications icon for the target server.

For example, to replicate a cube from the sdata server to the financiareporting1 server, double-

click the Replications icon under the financiareporting1 server.

The Create Server Replication Object dialog box opens.

Note: If the server already has a replication connection, you must select the Replications icon,

right-click the icon, and click Insert New Replication to open the Create Server Replication

dialog box.

4. Fill in the dialog box as follows:

● Select the source server in the From Server box.

● Specify the username and password with which you want to connect to the source server.

● If the source server uses Cognos 8® security (CAM authentication), enter the Cognos 8

Namespace ID of the source server in the with Namespace box.

Note that you must provide the Namespace ID of the namespace, not the descriptive name

of the namespace.

5. Click OK.

The system connects you to the specified server, and adds the server name under the Replications

icon for the target server.

Replication

Sdata

After you create a replication connection, you can manually synchronize data between the

target and source servers or create a chore to automate synchronization. For details, see "Syn-

chronization Process" (p. 115).

Modifying a Replication ConnectionYou can change the user name and password properties of a replication connection. If you change

these properties, you are logged in to the replication server as a different user. The existing replication

relationships between the source cube and the mirror cube may no longer be valid. The privileges

of the new client may not be equivalent to those of the old client. In this case, the synchronization

process does not work.

Steps

1. Open the Server Explorer.

2. Access the server that contains the replication connection you want to modify.

3. Double-click the Replications icon to expand it.

Operation Guide 111

Chapter 5: Replicating Cubes

Page 112: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

4. Right-click the server whose connection you want to modify, and click Modify Replication

Parameters.

The Modify Server Replication Object dialog box opens.

5. Make the appropriate changes, and click OK.

Deleting a Replication ConnectionYou can sever the relationship between the source and target servers by deleting a replication con-

nection. When you do this, you delete the relationship between the source and mirror cubes. You

can still update your local copy of the cube, but you can no longer synchronize the updates with

the source cube.

Steps

1. Open the Server Explorer.

2. Access the server that contains the replication connection you want to delete.

3. Double-click the Replications icon to expand it.

4. Right-click the server whose connection you want to delete and click Delete Replication.

Note: If you created a chore to automate synchronization, you must delete the chore before

deleting the replication. For details on automating synchronization, see "Synchronization Pro-

cess" (p. 115).

Replication ProcessAfter you create a replication connection between two servers, you can replicate the cubes from the

source server to the target server.

TM1® allows the replication of control cubes, including these cubes:

}DimensionProperties

}CubeProperties

}ConnectionProperties

In most circumstances, you should not replicate these cubes. If you do, be aware that the cubes on

the target server overwrite the cubes on the source server when synchronization occurs, thereby

removing all the replication and synchronization settings that were made through the UI.

Replicating a CubeWhen replicating a cube, the total length of the pathname for the target TM1® server's data directory

and cube name can not exceed the Microsoft® Windows® pathname limit of approximately 256

characters. If this limit is exceeded, due to a long pathname or cube name, TM1 displays the follow-

ing error message: Could not register the cube.

Steps

1. Double-click the Replications icon for the target server.

112 IBM Cognos TM1

Chapter 5: Replicating Cubes

Page 113: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The tree expands to list existing replication connections.

2. Double-click the replication connection you want to use.

The tree expands to list the cubes that you can replicate.

3. Right-click the cube you want to replicate and click Replicate.

The Replicate Cube dialog box opens.

4. Fill in the Replicate Cube dialog box as described in "Specifying Information about the Repli-

cated Cube" (p. 113).

5. Click OK.

TM1 replicates the cube, as described in "What Happens when TM1 Replicates a Cube" (p. 115).

Note: After you click OK to replicate a cube, you cannot change the specifications for this

particular replication. However, you can create another replicated version of the source cube

with different specifications.

Specifying Information about the Replicated CubeThe Replicate Cube dialog box lets you specify the following information about the mirror cube

you are creating:

● Name of the mirror cube.

● Name of each dimension in the mirror cube.

● Whether the mirror cube uses dimensions that are replicated from the source server or local

dimensions.

● Whether the dimensions replicated from the source server are synchronized when the cubes are

synchronized.

● Whether the mirror cube uses rules that are replicated from the source cube.

● Whether the rules replicated from the source server will be synchronized when the cubes are

synchronized.

The Replicated Cube dialog box that displays when you replicate the depletion cube from the

inventory server is shown in the following figure. The replication status might be different,

depending on whether you have already replicated the dimensions in the cube.

Note: The sections that follow describe how to change the TM1® default settings. We recommend

that you do not change any default settings unless you fully understand the implications of doing

so.

Specifying Cube Information

By default, TM1® names the mirror cube with the source cube name.

Steps

1. To specify another name for the mirror cube, enter the name in the Name field.

Operation Guide 113

Chapter 5: Replicating Cubes

Page 114: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Note: Do not rename a cube if you are replicating rules in that cube.

2. To replicate the cube and allow later synchronization, select Copy Data and Set to Synchronize.

3. To replicate the cube but disable later synchronization, select Copy Data but Do Not Set to

Synchronize.

Specifying Dimension Information

By default, TM1® specifies that each dimension in the mirror cube will be copied from the source

server, and then synchronized when the mirror cube is synchronized with its source.

TM1 does not change the dimension names when it copies them.

You can override the default settings for a dimension when you replicate a cube.

Steps

1. To rename a dimension, slowly click the dimension twice (do not double-click), and type the

new name.

Warning: Do not rename a dimension if you are replicating rules in the associated cube.

2. To direct TM1 to copy a dimension but not synchronize it, select the dimension, and clear the

Set Dimension to Synchronize option.

3. To direct TM1 to use a local dimension instead of a replicated dimension:

● Double-click the dimension to open the Select Dimension for use in Replicated Cube dialog

box.

● Select the dimension you want to use and click OK.

Warning: By default, TM1 overwrites the local dimension with the source dimension. If you

do not want TM1 to overwrite the dimension, select the Don't Overwrite Dimension option.

This automatically directs TM1 to treat the local dimension as a stand-alone dimension.

Specifying Rule Information

By default, TM1® specifies that each rule in the mirror cube is copied from the source cube, and

then synchronized when the mirror cube is synchronized with its source.

Steps

1. To specify that you want TM1 to copy the rules but not synchronize them, clear the Set Rule

to Synchronize option.

2. To specify that you do not want TM1 to copy rules for the mirror cube, select the Do Not

Copy Rule option.

114 IBM Cognos TM1

Chapter 5: Replicating Cubes

Page 115: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Specifying View Information

By default, TM1® specifies that each public view in the mirror cube is copied from the source cube,

and then synchronized when the mirror cube is synchronized with its source.

Step

● To specify that you do not want TM1 to copy views for the mirror cube, clear the Replicate

Views option.

Specifying Subset Information

By default, TM1® specifies that each public subset in the mirror cube is copied from the source

cube, and then synchronized when the mirror cube is synchronized with its source.

Step

● To specify that you do not want TM1 to copy subsets for the mirror cube, clear the Replicate

Subsets option.

What Happens when TM1 Replicates a CubeWhen TM1® replicates a cube, the following action occurs:

● Optionally, TM1 replicates the cube dimensions. When you initiate the replication process,

you decide which dimensions you want to replicate, and of those, which dimensions you want

to synchronize when you synchronize the cubes. You can also choose to use one or more local

dimensions with a replicated cube.

● Optionally, TM1 replicates the cube rules. When you initiate the replication process, you decide

which rules you want to replicate, and of those, which rules you want to synchronize when

you synchronize the cubes.

● Represents the cube as an icon under the Cubes icon on the target server.

● Names the source server in the Replication Server field on the attributes bar for each replicated

cube.

● Names the source server in the Replication Server field on the attributes bar for each replicated

dimension.

Synchronization ProcessYou always initiate the synchronization process from the target server, which is the server that

contains the mirror cubes. You must have administrator authority for this server to initiate the

synchronization process.

You can synchronize on demand or schedule the synchronization process to be automatic.

❑ TM1® updates the data in all the mirror cubes that are part of the same replication connection.

You cannot specify individual cubes to update.

❑ TM1 also updates the replicated dimensions if you made changes to their definitions and rules.

Operation Guide 115

Chapter 5: Replicating Cubes

Page 116: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

❑ TM1 always writes updates from the source cubes to the mirror cubes.

❑ TM1 does the following with updates you make to the mirror cube:

● Writes the updates back to the source cube, if the updates were made by users with Reserve

access to the source cube.

● Does not write the updates back to the source cube, if the updates were made by users with

Read or Write access to the source cube.

❑ TM1 uses the transaction log files to keep track of the changes made to the source and mirror

cubes. During the synchronization process, TM1 uses the log files to determine which updates

to make.

● If you are performing a synchronization process, transaction logging must be enabled for

the mirror cubes on the target server that are part of the replication and synchronization

process.

● If you are performing a bi-directional synchronization, transaction logging must be enabled

for all the related cubes on both the source and target servers.

To verify that transaction logging is enabled, see "Enabling and Disabling Transaction Log-

ging" (p. 124) in the IBM® Cognos® TM1® Operation Guide.

If there is an update conflict for a particular cell, TM1 uses the most recent update, no matter

where this update was made (that is, in the source cube or the mirror cube).

Synchronizing on DemandTo synchronize updates on demand, complete the following steps.

Steps

1. In the Server Explorer, access the server that contains the mirror cubes.

2. Double-click the Replications icon.

3. Right-click the icon for the replication connection for whose cubes you want to synchronize,

and click Synchronize Data.

Scheduling SynchronizationYou can create a chore to automatically synchronize data at a regular interval using TurboIntegrator.

For details on TurboIntegrator, see the IBM® Cognos® TM1® TurboIntegrator Guide.

Steps

1. In the Server Explorer, select the Chores icon beneath the target server for which you want to

automate synchronization.

2. Right-click the Chores icon and click Create New Chore.

The Chore Setup Wizard opens.

3. Select the replication for which you want to automate synchronization.

116 IBM Cognos TM1

Chapter 5: Replicating Cubes

Page 117: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

4. Click the arrow button to move the replication from the Available list to the Selected List.

5. Click Next.

The second screen of the Chore Setup Wizard displays.

6. Use the calendar and Time field to set a start date and time for the initial synchronization.

7. Use the fields in the Chore Execution Frequency box to set the interval at which the synchro-

nization should be executed.

8. Click Finish to complete the scheduling.

Synchronizing over Unstable or Wide Area Network ConnectionsYou can use the MaximumSynchAttempts and SyncUnitSize parameters 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.

For more details, see "MaximumSynchAttempts" (p. 54) and "SyncUnitSize" (p. 65) in the "TM1

System Configuration" section in this guide.

Operation Guide 117

Chapter 5: Replicating Cubes

Page 118: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

118 IBM Cognos TM1

Chapter 5: Replicating Cubes

Page 119: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 6: System and Performance Monitoring

This section describes the available log files, tools, and utilities for monitoring the system performance

of an IBM® Cognos® TM1® server.

Overview of TM1 System and Performance MonitoringTM1® includes a collection of tools that provide logging and real-time performance monitoring of

the TM1 servers in your organization. You can monitor TM1 performance and activity using the

following tools.

● Message Logging

● Admin Server log

A log file containing messages about communication between TM1 clients, the Admin

Server and individual TM1 servers.

● Transactions Log

A log file that tracks the data transactions made by the clients logged into one TM1 server.

Recorded information includes the date and time the change was made, name of the client

who made the change, before and after value, name of the cube in which the change was

made, and the elements that identify the cell that changed.

● Server Message Log

A log file containing details on the activity of the TM1 server, such as an executed processes,

chores, loaded cubes and dimensions, and a synchronized replication.

● Audit Log

A log file that monitors changes to TM1 objects and system-wide events, such as

modifications to dimensions, views and subsets and successful/ unsuccessful login activity.

● Monitoring Server Performance Using Control Cubes

Minute-by-minute performance statistics for clients, cubes, and servers. This performance data

is tracked and stored in the following TM1 control cubes; }StatsByClient, }StatsByCube,

}StatsByCubeByClient, and }StatsForServer.

● TM1 Top

A utility that dynamically monitors the threads and processes running in an instance of a single

TM1 server. TM1 Top is a stand-alone utility that runs within a console (command) window

on a Microsoft® Windows® computer.

● Performance Counters

A collection of continuously updated values that provide real-time monitoring of specific TM1

server properties and activities such as usage of cubes, views, subsets, dimensions, and read/write

Licensed Materials – Property of IBM119© Copyright IBM Corp. 2007, 2011.

Page 120: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

activity. Performance counters are viewable in graphical format using the Microsoft Windows

Performance Monitor, or in a text-only display using the TM1 PerfMon utility.

Using the Admin Server LogThe TM1® Admin Server log contains messages about the communication between TM1 clients,

the TM1 Admin Server, and individual TM1 servers. This log is useful for troubleshooting connection

issues when using the TM1 Secure Socket Layer (SSL) with custom certificates or certificates from

the Microsoft® Windows® certificate store.

Most of the messages in this log are created during the startup process for clients and servers.

Messages are logged when:

● TM1 servers start up and register with the TM1 Admin Server.

● TM1 clients contact the TM1 Admin Server for a list of available TM1 servers.

● SSL security is established between TM1 clients, the TM1 Admin Server, and individual TM1

servers. For more details on SSL, see "Running TM1 in Secure Mode Using SSL" (p. 261).

For details about the TM1 Admin Server, see the "TM1 Admin Server" (p. 17).

Message Severity Levels for Admin Server LoggingThe Admin Server log categorizes messages into the following three severity levels. These levels are

also used in the logging properties file to configure logging to a specific level.

DescriptionParameter

Detailed, technical messages that are useful when customer support or develop-

ment engineering need to debug the application.

DEBUG

When logging is configured to this level, DEBUG, INFO, and ERROR messages

are logged.

Informational messages that highlight the progress of the application and report

normal transitions within the application.

INFO

When logging is configured to this level, INFO and ERROR messages are

logged.

An error condition of which you should be aware. Action should be taken to

fix or report the issue to customer support.

ERROR

When logging is configured to this level, only ERROR messages are logged.

Configuring Admin Server LoggingConfiguration for TM1® Admin Server logging is contained in the tm1admsrv-log.properties file.

This file is located in the TM1_install_dir\bin directory.

120 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 121: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

A sample tm1admsrv-log.properties file is shown in the following figure.

The sections of the properties file are:

● Logger section

Configures the TM1 sub-components and message severity level that you want to log.

Example:

log4j.rootLogger=INFO*, R1

log4j.logger.TM1=INFO

*INFO is the message level.

● Appender section

Example:

Controls the output destination of the logging. The default configuration uses the RollingFileAp-

pender option to write messages to the tm1admsrv.log file.

# R1 is set to be a RollingFileAppender

log4j.appender.R1=org.apache.log4j.RollingFileAppender

log4j.appender.R1.File=tm1admsrv.log*

log4j.appender.R1.MaxFileSize-10 MB

log4j.appender.R1.MaxBackupIndex=2

*tm1admsrv.log is the log file name.

● Pattern Layout section

Controls the output fields and formatting of the messages that are written to the log file. The

default settings use a time reference of GMT.

Example:

# R1 uses PatternLayout

log4j.appender.R1.layout=org.apache.log4j.PatternLayout

log4j.appender.R1.layout.ConversionPattern=%t %p %d(%Y-%m-%d %H:%M:%S,%Q)

%c %m%n

log4j.appender.R1.layout.TimeZone=GMT

The default logging configuration logs all INFO level messages. You can adjust the logging message

level by editing the following two statements in the logging properties file:

log4j.rootLogger=INFO, R1

log4j.logger.TM1=INFO

For example, replace INFO with the DEBUG logging level:

log4j.rootLogger=DEBUG, R1

log4j.logger.TM1=DEBUG

Note: The default logging configuration is intended for every-day use and does not typically require

adjustment. Contact customer support for assistance if you need to configure the logging properties

file for troubleshooting purposes.

Operation Guide 121

Chapter 6: System and Performance Monitoring

Page 122: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Enabling Admin Server LoggingLogging for the TM1® Admin Server is enabled by default when you install TM1. The installation

places the tm1admsrv-log.properties file and the TM1 Admin Server program file, tm1admsrv.exe,

into the TM1_install_dir\bin directory.

Logging is activated when the TM1 Admin Server starts up and detects the tm1admsrv-log.properties

file in the same directory.

Viewing the Admin Server Log FileThe default logging configuration writes log messages to the tm1admsrv.log file. The log file is an

ASCII text file that you can open in any text editor, such as Microsoft® Windows® Notepad.

Steps

1. Locate the tm1admsrv.log file in the TM1_install_dir\bin directory.

2. Open and view the log file with a text editor, such as Microsoft Windows Notepad.

Each line in the log file represents one unique message, arranged in the following format:

Message TextTM1Subcompo-nent Name

Date and TimeMessageLevel

ThreadID

Error connecting to remote

machine

TM1.Comm.SSL2007-01-19 19:10:22,

128

INFO3948

Logger initializedTM1.Server2007-01-19 19:14:04,

396

DEBUG1260

Timwed wait for event

0043B858 succeeded

TM1 .Event2007-01-19 19:14:04,

396

DEBUG3328

Destroy event 0043B858

succeeded

TM1.Event2007-01-19 19:14:04,

396

DEBUG3328

Signal event 0043B858 suc-

ceeded

TM1. Event2007-01-19 19:14:04,

396

DEBUG1260

Logging TransactionsEach TM1® server tracks the data transactions made by its clients. When a client changes a cube

value, TM1 records the change in a transaction log file named Tm1s.log, which is located in the

TM1 server data directory.

The information recorded in the log file includes:

● Date and time the change was made.

122 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 123: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Name of the client who made the change.

● Whether the new data is simple data (N) or string data (S).

● Value before the change.

● Value after the change.

● Name of the cube in which the change was made.

● Elements that identify the cell that changed.

● Optional user-provided string that is attached to each transaction. You create the string with

the TM1ServerLogSetFlagString API function.

The log file is a comma-delimited ASCII file, as shown in the following sample:

"19980602212741","19980602212741","Admin","N","380.","250.","salescube","Budget","Belgium","LSeries 1.6 L Sedan","Units","Jun",""

"19980602212744","19980602212744","Admin","N","430.","600.","salescube","Budget","Belgium","LSeries 1.6 L Sedan","Units","Sep",""

"19980602212749","19980602212749","Admin","N","610.","800.","salescube","Budget","Belgium","LSeries 1.6 L Sedan","Units","Oct",""

Data Backup and RecoveryThe Tm1s.log file remains open while a TM1® server is running. When you bring down the server

normally, TM1 renames the log file by appending a time stamp to it, and with the following naming

convention:

Tm1syyyymmddhhmmss.log

The time stamp, yyyymmddhhmmss, represents the current Greenwich Mean Time at the time the

server was brought down. For example, if the server came down on January 2, 2002, at 2:30 PM,

the name of the log file is Tm1s20020102143000.log.

TM1 recovers the data automatically in the event that a server comes down abnormally, and leaves

the Tm1s.log file on the disk. The next time you bring up the server, TM1 recovers the changes in

either of two ways:

● Automatically recovers the changes -- when you are running the TM1 server as a Microsoft®

Windows® service.

● Prompts you to recover the changes -- when you are running the TM1 server as an application

If you intentionally shut down a TM1 server without saving the data, TM1 saves the transaction

log with a time stamp and changes the file extension to .rej. For example, Tm1s20020102143000.

rej. The .rej log file ensures that you always have a record of the data transactions, even if you shut

down the server without saving the data. If you accidentally shut down the server without saving

the changes, you can process the .rej file through TurboIntegrator to recover the data.

Operation Guide 123

Chapter 6: System and Performance Monitoring

Page 124: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Enabling and Disabling Transaction LoggingBy default, TM1® logs transactions to all cubes loaded on the server. As the system administrator,

you have the option to turn off logging for particular cubes.

When you disable logging, TM1 accelerates updating the data but you cannot recover the updates

in the event of a system failure.

Steps to enable logging for individual cubes

1. Open Server Explorer.

2. Select the Cubes icon for the server you are working with.

3. Select Cubes, Security Assignments.

The TM1 Security Assignments dialog box opens.

4. Click the cell at the intersection of the Logging column and the cube name.

TM1 enables logging when a check box contains an X, and disables logging when the check

box is empty.

5. Click OK.

Viewing the Transaction LogYou can query the transaction log (Tm1s.log) to view the records of all the logs currently in the

TM1® server data directory. When you query the transaction log, TM1 combines all the log files

into one logical file that satisfies the query parameters. For example, if you query for all the records

starting on Jan. 2, 2002 at 2:30 PM GMT, TM1 returns all the records in all the transaction logs

with a time stamp of 20020102143000 or later.

Steps

1. Select the server in Server Explorer.

2. Click Server, View Transaction Log.

The Transaction Log Query dialog box opens.

3. Click the right arrow in a parameter field to set the parameters for the query.

There are four parameters you can set:

DescriptionParameter

Queries all the records written to the transaction log on or after

the starting time.

Starting Time

Start date and time for the query. The date and time format is

MM/DD/YYYY HH:MM:SS GMT. The default start date and

time is 00:01:00 GMT on the date you launch the query.

124 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 125: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

End date and time for the query. The date and time format is

MM/DD/YYYY HH:MM:SS

End Time

The default is __/__/____ __:__:__, which is an open end date

and time. If you accept the default, TM1 queries all the records

up to the time you launch the query.

The client(s) against which you apply the query.Clients

You can query against either a single client or all the clients. The

default is all clients (*).

The cube(s) against which you apply the query.Cubes

You can query against either a single cube or all the cubes. The

default is all cubes (*)

4. Click OK.

The query returns a table with all the transaction records that satisfy the parameters you set.

The table displays in the Transaction Log Query Results dialog box.

By default, records are sorted in ascending order by LOGTIME.

5. To sort on a different column, click the column heading. To change the order of a column sort,

click the column heading a second time.

6. Click Edit, Find to search the records in the query results table.

Backing Out Records from the Transaction LogAfter you query the transaction log, you can use the Transaction Log Query Results dialog box to

back out the transactions. When you back out a transaction, the value in the OLDVALUE column

replaces the value in the NEWVALUE column.

Steps

1. Highlight the record(s) you want to back out.

● To highlight an individual record, click the record.

● To highlight multiple adjacent records, click the first record and SHIFT+click the last

record.

● To highlight multiple non-adjacent records, CTRL+click each record.

2. Click Edit, Select.

All the highlighted records now display a check mark in the box adjacent to the first column.

The check marks indicate that the record is selected to be backed out.

To select all the records without first highlighting them, click Edit, Select All.

Operation Guide 125

Chapter 6: System and Performance Monitoring

Page 126: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

3. Click Edit, Back Out.

TM1® backs out the records in reverse chronological order as identified by the LOGTIME

column.

Removing Transaction Log Files from the DiskThe TM1® log files can take up a substantial amount of disk space after the server has been running

for some time. You should remove the old log files from your disk every so often, depending on

the volume of the changes you make and the size of your disk. You can back up these files before

you erase them.

Do not remove the log files when the TM1 server is running. First shut down the server, and then

delete the log files from your disk.

Troubleshooting: Recovering from a Corrupt Transaction Log FileIn some cases, an unexpected or incomplete shutdown of the TM1® server, due to a server crash

or power outage, can cause the transaction log file to become corrupt. If this happens, the server

will not be able to restart.

In this case, you will need to troubleshoot the cause of the shutdown, verify that the transaction

log file is corrupt, remove the log file and contact Customer Support for assistance.

Determining if the Transaction Log File is Corrupt

When the TM1® server restarts after an unexpected shutdown, it attempts to recover data from the

transaction log file, Tm1s.log. If TM1 detects that the log file is corrupt, the server will not start

and informs you of the situation via visual prompts and/or logged messages. The exact type of

message depends on how you are running the TM1 server:

● On a UNIX® system or as a Microsoft® Windows® service.

● As a Microsoft Windows application.

TM1 Server Running on a UNIX System or as a Microsoft Windows Service

If you are running the TM1® server on a UNIX system or as a Microsoft Windows service, TM1

cancels the automatic recovery when trying to restart the server and writes a warning message to

the TM1 server message log, tm1server.log. This message indicates that the transaction log is corrupt.

An example messages in the TM1 Server Message log indicating a corrupt transaction file and the

warning messages are shown in the following table.

Message TextTM1Subcompo-nent Name

Date and TimeMessageLevel

ThreadID

Bad transaction log record:

828.7...

TM1.Server2007-10-30 18:20:10,

203

FATAL4076

Server terminatedTM1.Server2007-10-30 18:20:14,

921

FATAL4076

126 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 127: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

TM1 Server Running as a Microsoft Windows Application

If you are running the TM1® server as a Windows application, TM1 first prompts you to recover

the changes when the server restarts.

If you select No, the server will continue running, but the problem that caused the unexpected

shutdown may still exist.

If you select Yes, TM1 displays the following warning message and also writes a message to the

TM1 server message log as described above.

Select OK to shutdown the TM1 server.

Resolving a Corrupt Transaction Log File

To resolve this condition, move the transaction log file, tm1s.log, from the TM1® server data

directory to a temporary location on your system. At this point, you should be able to successfully

restart the server, but you should also contact Customer Support for assistance in resolving the

cause of the unexpected shutdown.

Using the TM1 Server Message LogThe TM1® server records status messages on the activity of the server in a log file. These messages

contain details on activity such as executed processes, chores, loaded cubes and dimensions, and

synchronized replication.

The TM1 server message logging system is designed to minimize the impact on performance while

allowing greater control over the quantity and focus of data produced by logging.

The logging system includes the following components:

● Message severity levels - Categories for classifying and reporting messages by severity; DEBUG,

INFO, WARN, ERROR, and FATAL.

● TM1 loggers - Parameters that provide enhanced control for selectively logging specific areas

or sub-components of TM1.

● Logging properties file - A text-based file that enables you to configure and enable logging for

a specific TM1 server.

● Message log viewer - A tool for viewing the message log in Server Explorer and TM1 Architect.

Note: Log messages are displayed in English only.

Message Severity LevelsThe logging system categorizes messages into the following severity levels.

Operation Guide 127

Chapter 6: System and Performance Monitoring

Page 128: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

Detailed, technical messages that are useful when customer support or

engineering need to debug the application.

DEBUG

Examples: "SSL Connection opened", "Removing SQL Connection from

memory"

Informational messages that highlight the progress of the application and

report normal transitions within the application.

INFO

Examples: "Server is ready", "Loading dimension..."

A potentially harmful situation or condition of which you should be aware.

Action may be required, but operation of the server is not interrupted.

WARN

Example: "Attempt to add a new group exceeded the limit on group cre-

ation"

An error condition of which you should be aware. Action should be taken

to fix or report the issue to customer support. The error may be so severe

that the server shuts down or it may result in the current client request being

canceled.

ERROR

Examples: "Error connecting to remote machine", "Failed to create a cube"

A very severe error event that will possibly cause the server to shut down

or result in the current client request being canceled. You should immediately

take action to fix the issue and report the event to customer support.

FATAL

TM1 LoggersTM1® loggers represent the different areas or sub-components of TM1 that produce log messages.

For example, dimensions and cubes produce messages when loading and the server reports messages

when starting and stopping.

You can control the quantity and focus of the logging by selectively turning on or off individual

TM1 loggers in the logging properties file.

The default logging configuration is INFO level messages for all areas of TM1.

Note: Customer support can provide you with guidance and assistance to enable individual TM1

loggers.

Logging Properties FileThe logging properties file, tm1s-log.properties, is a text file that contains the parameters for con-

figuring logging for a specific TM1® server. This file enables you to control which message levels

are logged for the different sub-components of TM1.

128 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 129: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Each TM1 server uses its own logging properties file and checks for the file whenever the server is

started. After startup, the server checks for updates to the properties file and adjusts the logging as

needed. You can make changes to a properties file in real-time and the TM1 server will dynamically

read the changes and adjust the logging.

Note: The TM1 local server only checks the logging properties file, tm1s-log.properties, when the

local server starts up. For details, see "Enabling and Disabling Transaction Logging" (p. 124).

A sample logging properties file is provided in the directory of each sample TM1 database that you

install. Sample TM1 databases are installed in the following locations:

● Windows® system:TM1_install_dir\custom\tm1data\TM1_sample_dir

● UNIX® system: TM1_install_dir/custom/tm1data/TM1_sample_dir

Where TM1_sample_dir is the directory for a sample TM1 database. For example:

● Planning Sample Data:TM1_install_dir\custom\tm1data\PlanSamp

● Sample Data: TM1_install_dir\custom\tm1data\SData

Here is an example of the logging properties file:

Log4j.rootLogger=INFO, S1

Log4j.logger.TM1=INFO

# S1 is set to be a SharedMemoryAppender log4j.appender.S1=org.apache.log4j.SharedmemoryAppender

#Specify the size of the shared memory segment log4j.appender.S1.MemorySize=5MB

#Specify the max filesize log4j.appender.S1.MaxFileSize=10MB

Specify the max backup index log4j.appender.S1.MaxBackupIndex=3

Configuring and Enabling Server Message LoggingUse a copy of the logging properties file, tm1s-log.properties, to configure and enable message

logging for a specific TM1® server.

Enabling and Disabling Logging

Logging is enabled when a TM1® server detects a logging properties file in the same directory where

the server's configuration file, Tm1s.cfg, is located.

1. Edit a copy of the sample logging properties file, tm1s-log.properties, to configure logging

message level and output settings, as described in "Configuring Logging Message Level" (p. 130)

and "Configuring Logging Output" (p. 131).

2. Place the logging properties file, tm1s-log.properties, into the same directory where the config-

uration file, Tm1s.cfg, is located for the TM1 server you want to monitor.

The location of the Tm1s.cfg file is typically the data directory of the TM1 server, but could

be a different location depending on your specific TM1 configuration. For example, if your

Tm1s.cfg file is located in the C:\salesdata directory on a Microsoft® Windows® system, then

copy the logging properties file into this directory.

Operation Guide 129

Chapter 6: System and Performance Monitoring

Page 130: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

After the tm1s-log.properties file is placed in the same directory as the Tm1s.cfg file, the server

will start logging based on the settings configured in the logging properties file. It is not necessary

to restart the TM1 server to initialize logging, unless you are running a local server.

Note: The TM1 local server only checks the logging properties file, tm1s-log.properties, when

the local server starts up. After startup, a local server never checks for changes in the logging

properties file, so all settings in a local server's logging properties file must be considered static.

If you change any logging properties for a local server, you must restart the server to apply the

new logging settings.

3. To temporarily turn off logging, set the TM1 logger values to either INFO or OFF. Using a

value of INFO is recommended.

● Setting a logger value to INFO will continue some logging, but at a much decreased amount

compared to a setting of DEBUG. Using a setting of INFO, instead of OFF, is useful because

TM1 will still log important messages for WARN, ERROR and FATAL messages.

● Setting a logger value to OFF will stop all logging for that logger, and you could miss any

potential WARN, ERROR and FATAL messages.

Configuring Logging Message Level

Use the following two statements in the logging properties file as the standard configuration to log

all INFO level messages for all areas of TM1®.

log4j.rootLogger=INFO, S1

log4j.logger.TM1=INFO

Use the following format to configure logging at a specific message level:

TM1 logger=Message level, Appender

Where:

● TM1 logger is the name of the TM1 sub-component that you want to log. Contact customer

support for assistance using TM1 loggers.

● Message level is the message severity level that you want to log. Valid values include: DEBUG,

INFO, WARN, ERROR, FATAL, or OFF, as described in the section "Message Severity Levels."

Message levels are logged as follows:

● Setting logging to DEBUG will report all severity levels messages.

● Setting logging to WARN will report WARN, ERROR, and FATAL messages.

● Setting logging to OFF disables all logging for the specific TM1 logger.

● Appender is the output destination. Use a value of S1 for the TM1 shared memory appender

which transfers messages to memory before saving them to a file.

For example, to turn on logging at the DEBUG level for all TM1 sub-components, you would use

the following statements:

log4j.rootLogger=DEBUG, S1

log4j.logger.TM1=DEBUG

130 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 131: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Configuring Logging Output

Logging output is configured in the appender section of the logging properties file with the following

parameters.

● MemorySize

● MaxFileSize

● MaxBackupIndex

● TimeZone

Each parameter is described in the following table.

DescriptionParameter

Specifies the size of the shared memory segment. This memory represents

the area of system memory where log messages are sent before being

written to the log file.

MemorySize

Default value is 5 MB.

Use the following format:

log4j.appender.S1.MemorySize=Size Units

where:

● Size is the numeric value for the memory size.

● Units can be KB, or MB.

For example, to set the MemorySize to 5 MB, enter the following:

log4j.appender.S1.MemorySize=5 MB

Specifies the maximum file size that the log file is allowed to take up on

disk.

MaxFileSize

Default size is 100 MB.

Uses the following format:

log4j.appender.S1.MaxFileSize=SizeUnits

where:

● Size is the numeric value for the file size.

● Units can be KB, MB, or GB.

For example, to limit the log file size to 10 MB, enter the following:

log4j.appender.S1.MaxFileSize=10 MB

If the MaxBackupIndex parameter is set to 1 or greater, then the logging

process automatically creates a backup file when the log file reaches the

MaxFileSize. The total number of backup files is determined by

MaxBackupIndex option.

Operation Guide 131

Chapter 6: System and Performance Monitoring

Page 132: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

A numeric value that specifies how many backup files are kept before the

oldest log file is erased.

MaxBackupIndex

Default value is 20.

● If set to 0 - no backup log files will be saved and the current log file

will be overwritten and restarted each time it reaches MaxFileSize.

● If set to 1 or higher - A total of x backup files will be maintained,

where x is equal to the MaxBackupIndex value.

The backup process repeats each time the MaxFileSize is reached, overwrit-

ing the oldest backup file so that only the newest backup files remains.

Specifies the timezone for the message timestamps in the log file. Uses the

following format:

TimeZone

log4j.appender.S1.TimeZone=Zone

where Zone can be set to either GMT or Local.

● If set to Local, the log messages will have timestamps based on the

local time of the machine where the TM1® server is running.

● If set to GMT, the log messages will have timestamps based on

Greenwich Mean Time.

● If the parameter is set to something other than GMT or Local, or if

the parameter is not set at all, it defaults to GMT.

Viewing the TM1 Server Message LogTo view a list of the messages that the TM1® server has recorded, complete the following steps.

Steps

1. Select the server in the Server Explorer.

2. Click Server, View Message Log.

The Message Log window opens.

The message log fields are defined in the following table.

DescriptionMessage Field

ID number of the thread in the TM1 server that generated

the logging event.

Thread ID

Example: 2488

132 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 133: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionMessage Field

Severity level of the message being reported: DEBUG,

INFO, WARN, ERROR, or FATAL.

Message Level

Date and time the message was logged, based on the

TimeZone parameter setting in the logging properties file.

Data and time can be recorded as either GMT or Local.

For more details, see "Configuring Logging Out-

put" (p. 131).

Date and Time

Reported in the format: yyyy-mm-dd hh:mm.ss,milliseconds

Example: 2006-10-02 16:49.01,925

Name of the TM1 sub-component that generated the

message or activity.

TM1 Logger Name

Example:

Start time: Tue Dec 05 2006 11:02:47

Pre-defined text message that describes the error or activity

being reported.

Message Text

Viewing Details for Error Messages

If a message in the log shows an error condition for an executed process or replication, you can

double-click the message to view the details of why the activity generated the error.

Searching for Text in the Message Log

You can search for text in the message log.

Steps

1. Click Edit, Find or press CTRL+F.

The Find dialog box opens.

2. Enter the text you to find and then click Find Next.

If the text is found, the line containing the matched text is highlighted and shown in the Message

Log window.

Copying Text from the Message Log

You can copy text from the message log.

Steps

1. Select the line of text you want to copy.

2. Select Edit, Copy or press CTRL+C to copy.

Operation Guide 133

Chapter 6: System and Performance Monitoring

Page 134: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The currently selected line is copied to the Microsoft® Windows® clipboard and can then be

pasted into other applications.

Client LoggingAs of 9.5.1, a client side logging tool is available that can collect data about client activity. Due to

the large amounts of data that can be collected, this tool should only be used under the direction

of customer support.

Here is a sample Client Log:

log4j.rootLogger=DEBUG, R1#Server Explorelog4j.logger.COrionMainApp=DEBUGlog4j.logger.CCubeView=DEBUGlog4j.logger.CubeViewGrid=DEBUGlog4j.logger.COrionTreeView=DEBUGlog4j.logger.COrionApp=DEBUGlog4j.logger.CMultiSelect=DEBUGlog4j.logger.CCreateSandbox=DEBUGlog4j.logger.loggerViewDimension=DEBUG#Subset Editorlog4j.logger.CSubsetWnd=DEBUGlog4j.logger.CSubsetEntry=DEBUGlog4j.logger.CSubsetListProp=DEBUGlog4j.logger.CSubsetListBox2=DEBUGlog4j.logger.CSubsetListView1=DEBUGlog4j.logger.CSubsetRegExp=DEBUGlog4j.logger.CSubsetSelByAttr=DEBUGlog4j.logger.CSingleSelect=DEBUG#ISBlog4j.logger.CXLCtrlsApp=DEBUGlog4j.logger.CConnectServerDlg=DEBUGlog4j.logger.CViewCtrl=DEBUGlog4j.logger.CGetViewDlg=DEBUGlog4j.logger.CubeViewerISB=DEBUGlog4j.logger.ExcelReportPrintDPage=DEBUGlog4j.logger.CTM1Connector=DEBUGlog4j.logger.ExcelReportPrintIncludedSheetsPage=DEBUGlog4j.logger.CAutoExcel=DEBUGlog4j.logger.SubsetEditorIntLog=DEBUG#Perspectiveslog4j.logger.TM1Perspectives=DEBUGlog4j.logger.TM1AF=DEBUGlog4j.logger.TM1ExcelAPI=DEBUGlog4j.appender.R1=org.apache.log4j.RollingFileAppenderlog4j.appender.R1.File=c:\\ClientDebugLog.loglog4j.appender.R1.MaxFileSize=10 MBlog4j.appender.R1.MaxBackupIndex=50log4j.appender.R1.layout=org.apache.log4j.PatternLayoutlog4j.appender.R1.layout.ConversionPattern=%X{pid}%t %p %d{%Y-%m-%d %H:%M:%S,%Q} %c %m%nlog4j.appender.R1.layout.TimeZone=GMT

To turn on Client Side logging, create a file called tm1p-log.properties in the C:\Documents

and Settings\Administrator\Application Data\Applix\TM location on the client’s system

machine. TM1p.ini must be in the same folder.

Be sure that location is also set in the log4j.appender.R1.File=c:\\ClientDebugLog.log line

of the log file.

134 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 135: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

If you put the log files directly on the c:drive as in the example , log4j.appender.R1.File=c:\\ClientLog.log

Be sure to use \\ slashes.

If you want to use a temp directory, specify the location using the other slash:

log4j.appender.R1.File=c:/temp/ClientLog.log

Be sure to update the file parameter with the new location if you change the tm1p-log.properties

file, for example:

location.log4j.appender.R1.File=c:\<new location>\ClientDebugLog.log

If the presence of this file and at least one component within it is set to DEBUG, client side logging

is collected. log4j.rootLogger=DEBUG can only be set to OFF or DEBUG (which turns client

logging ON).

To turn off logging, remove or rename this file. You can turn off logging for an individual component

by changing the value from DEBUG to OFF.

To customize the log file, you can change:

● Location of the log file is set in log4j.appender.R1.File=c:\\ClientDebugLog.log

● Log file max size is set in log4j.appender.R1.MaxFileSize=10 MB. When this size is met a

new log file is created.

● Backup index is set in log4j.appender.R1.MaxBackupIndex=50.

Using the Audit LogThe TM1® audit log monitors changes to metadata, such as modifications to dimensions, views

and subsets. This log can be used for accountability purposes where laws or regulations, such as

Sarbanes-Oxley, require auditing of certain activities in mission critical software.

Each TM1 server maintains its own separate audit log. Administrators can use a server's audit log

to answer these questions:

● What object was changed?

● How was the object modified?

● Who made the change?

● When was the change made?

You can query and view the audit log using the Audit Log window, available in TM1 Server Explorer.

Note: By default, audit logging is disabled and must be manually enabled for each server you want

to monitor. For details, see "Configuring Audit Logging" (p. 137).

Understanding Audit Log EventsThe audit log contains records of changes to major TM1® objects and system-wide activity. These

records are called events.

Operation Guide 135

Chapter 6: System and Performance Monitoring

Page 136: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

TM1 Object Events

The audit log monitors activity for the following TM1® objects:

● Applications

● Chores

● Clients

● Cubes

● Dimensions

● Elements

● Groups

● Processes

● Rules

● Subsets

● Views.

A common set of events, such as object created or deleted, are logged for all these objects. Addition-

ally, events are logged that are specific to each object. For example, the execution of a process is

an event that is logged only for process objects.

System-wide Events

System-wide events include operations related directly to the TM1® server such as:

● Successful and failed login attempts

● Server startup and shutdown

● Changes to server parameters

Audit Log Messages for Dimension Sorting Events

When you sort or change the order of elements in a dimension, the exact message recorded in the

Audit log depends on the sort method that was used; automatic or manual.

Automatic Dimension Sorting

When you set an automatic type sort for a dimension, the audit log records a specific descriptive

message about the action. An automatic sort is performed using the Dimension Element Ordering

dialog box available when you right-click on a dimension and select Set Elements Order.

For example, the following message would be reported in the audit log for an automatic sort change

to the “account” dimension:

"136","account","DESCENDING","DimensionSortElementsSenseproperty set for Dimension 'account': DESCENDING"

The Audit Log window would display the following message:

136 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 137: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Property SortElementsSense was set to 'DESCENDING' for dimension 'account'.

Manual Dimension Sorting

When you edit the order of a dimension in “manual” mode using the Dimension Editor, the audit

log records only a generic message. Manual mode includes changing the element order by hand, or

selecting Sort from the Edit menu in the Dimension Editor, and clicking the Set Dimension order

button followed by saving the dimension.

For example, the following generic message would be reported in the audit log for a manual sort

change to the “account” dimension:

21,account,Dimension updated: account

The Audit Log window would display the following message:

Dimension 'account' was updated.

Configuring Audit LoggingBy default, audit logging is disabled. You must manually configure audit logging using the audit

log parameters in the TM1® server's configuration file (tm1s.cfg).

To enable audit logging for a specific TM1 server, complete the following steps.

Steps

1. Open the tm1s.cfg file for that server.

2. Set the following parameters in the tm1s.cfg file:

AuditLogOn=T

AuditLogUpdateInterval=60

3. Restart the server.

Note: After changing the value for the AuditLogOn parameter, you must restart the TM1 server

for the new value to be applied.

For detailed information about all of the audit log parameters, see "The Tm1s.cfg Server

Configuration File" (p. 26).

Updating the Audit Log with the Latest EventsWhen audit logging is enabled, TM1® runs the logging in the background and automatically updates

the audit log at a set interval. This interval is determined by the AuditLogUpdateInterval parameter

in the tm1s.cfg file.

You can manually update the audit log whenever you want by using the Process Audit Log Events

command in TM1 Server Explorer. This action updates the audit log to include the latest events

and is especially useful to do just before you open the Audit Log window to run queries.

Steps

1. Select a TM1 server in Server Explorer.

2. Click Server, Process Audit Log Events.

Operation Guide 137

Chapter 6: System and Performance Monitoring

Page 138: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

3. Click Yes to confirm the update process.

The audit log now contains the latest audit event records.

Using the Audit Log Window to View Log MessagesThe content of the audit log is accessible through the Audit Log window, available in TM1® Server

Explorer. You use the Audit Log window to query the audit log and to view the audit log event

messages retrieved by the query.

The Audit Log window contains two main panels:

● Query panel - Use the Query panel to build queries that search the audit log for a specific time

period or type of event.

● Results panel - Use the Results panel to view and navigate the records retrieved by your query.

Opening the Audit Log Window

You can open the Audit Log window.

Steps

1. Select a TM1 server in Server Explorer.

2. Click Server, View Audit Log.

The Audit Log window opens.

You can then select the query parameters that you want and click the Run Query button to

retrieve the records for the query.

Creating and Running Queries

Use the following search parameters in the Query panel of the Audit Log window to narrow your

search.

● Date and Time

● Event Owner

● Event Type

Steps

1. Set the Date and Time option.

This option includes pre-defined time periods including today, and the last 10, 30, 60 and 90

days.

If you are looking for events from a specific time period, select Custom Time Period from the

Time Period drop-down box. Enter a start and end time.

2. Set the Event Owner option.

This option asks the question "Who caused this event?". This can be an actual TM1® user or

a scheduled chore.

138 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 139: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Click All to search for events caused by any user or any scheduled chore.

● Click Client to search for events caused only by a user.

● Click Scheduled Chore to search for events caused only by a scheduled chore.

To select a specific user or scheduled chore, click the Select button next to the related

field.

The Select Client or Select Chore dialog box opens.

● To select an individual user or chore name, click the item.

● To select an adjacent range of user or chore names, click the first item in the range, hold

down SHIFT, and click the last item in the range.

● To select multiple non-adjacent user or chore names, hold down CTRL and click each item.

3. Set the Event Type option.

Use this option to select the exact type of event for which you want to search. For example,

"find unsuccessful login attempts" or "find events where a dimension was deleted".

● Click All to search for both types of audit events; system-wide and object related events.

● Click System-wide to search for only system-wide audit events.

To search for a specific system-wide event, select the event from the Event list.

The default setting, *, searches for all system-wide events.

● Click Object to search for events related to only TM1 objects.

The Object option has the following sub-options:

● Set the Object Type option to limit the query to only a specific type of TM1 object. For

example, events related only to dimensions.

● Set the Object Name option to find events for a specific object name.

● Set the Event option to search for a specific object event.

The list of events changes depending on which type of object you select in the Object Typedrop-down box.

Click the Select Object Name button next to the Object Name field to display a dialog

box where you can select objects by name.

● To select an individual object name, click the item.

● To select an adjacent range of object names, click the first item in the range, hold down

SHIFT, and click the last item in the range.

● To select multiple non-adjacent object names, hold down CTRL and click each item.

Note: When you set Object Type to Element, the Select Object Name button becomes

disabled because the element list could be too large to display. If you want to search for events

Operation Guide 139

Chapter 6: System and Performance Monitoring

Page 140: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

related to a specific element, you must manually enter an element name using the following

format:

DimensionName:ElementName

For example: region:italy

4. Click the Run Query button .

The records retrieved by the query appear in the Results panel grid.

Viewing Results

The Results panel grid organizes the audit log records from the query into the following columns.

DescriptionMessage Field

Date and time of the event.Date

TM1® client (user) or scheduled chore that was responsible for

causing the event.

User

Brief description of the event.Event Type/Description

Type of TM1 object associated with the event.Object Type

Name of the TM1 object associated with the event.Object Name

Displays an icon to indicate that detailed information exists for the

specific event.

Details

If an event has details, you can view the details by clicking on the

Details for that record.

You can sort the results in the grid in ascending or descending order for any column by clicking on

the column title.

Viewing Event Details

Some events have additional information stored as event details. If an event has details, a Details

icon is displayed in the Details column for that event.

To view the details for an event, click the Detail icon for that event.

Event details display in the Audit Log Details window, separate from the main Audit Log window.

You can open multiple Audit Log Details windows at a time to compare them side-by-side.

140 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 141: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Copying Data to the Windows Clipboard

You can copy event data from the grid to the Windows clipboard. The copy feature is available in

both the Audit Log and Audit Log Details windows.

Step

● To copy event data, highlight an individual cell in the Results grid and then click the Copybutton on the Results toolbar.

Using the Find Feature

The Results panel includes a Find tool that searches for specified text in the Results grid. The Find

tool is available in both the Audit Log and Audit Log Details windows.

Steps

1. Click Find in the Results toolbar.

The Find dialog box appears.

2. Enter the text you want to find

3. Click Find Next.

If the text is found, the cell containing the matching text is highlighted in the Results grid.

Exporting Results

The Results panel also includes an export option for exporting results in XML, comma delimited,

and tab delimited file formats. The export feature is available in both the Audit Log and Audit Log

Details windows.

To export audit log data, complete the following steps.

Steps

1. Click Export in the Results toolbar.

The Save As dialog box appears.

2. Enter a filename and location for the file.

3. Select the file format using the Save as type option.

● XML (*.xml)

● CSV (Comma delimited) (*.csv)

● Text (Tab delimited) (*.txt)

4. Click Save.

Operation Guide 141

Chapter 6: System and Performance Monitoring

Page 142: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Monitoring Server Performance Using Control CubesTM1® includes a performance monitoring feature that lets you record the performance statistics

for clients, cubes, and servers. When you enable performance monitoring, TM1 populates several

control cubes on a minute-by-minute basis. You can then browse these cubes to analyze the server

performance.

The following control cubes are populated during performance monitoring. For details, see "Control

Cubes" (p. 287).

DescriptionControl Cube Name

Tracks the message count, average message size, total elapsed

time, and other measures for each client on the server.

}StatsByClient

Tracks the memory used for each cube on the server.}StatsByCube

Tracks the number and elapsed time of cell updates, cell

retrievals, view calculations, and view retrievals for each client

and cube on the server.

}StatsByCubeByClient

Tracks the connected clients, active threads, and memory used

by the server.

}StatsForServer

Enabling Performance MonitoringTo enable performance monitoring during a server session, complete the following steps.

Steps

1. Select the server in the Server Explorer.

2. Click Server, Start Performance Monitor.

You have enabled performance monitoring on a per-session basis.

If you want to enable performance monitoring at the start of every server session, you can set the

PerformanceMonitorOn parameter in the Tm1s.cfg file to automatically begin performance moni-

toring when a server starts.

Disabling Performance MonitoringTo end performance monitoring during a server session, complete the following steps.

Steps

1. Select the server in the Server Explorer.

2. Click Server, Stop Performance Monitor.

142 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 143: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Viewing Performance Statistics for Clients, Cubes, and ServersAfter enabling performance monitoring, you can view the status with the following steps:

Steps

1. In the Server Explorer, click View, Display Control Objects.

All of the Control Cubes will now be displayed, including the Performance Monitoring Control

Cubes.

2. Open any of the Performance Monitoring Control Cubes to view the cube.

The available control cubes include:

● StatsByClient

● StatsByCube

● StatsByCubeByClient

● StatsForServer

For details, see "Control Cubes" (p. 287) and "Control Dimensions" (p. 301).

Note that the performance monitor does not update to reflect any new cubes createdor new

users added while the performance monitor is running. Restart the performance monitor to

update it with items that were added.

Using the TM1 Top UtilityThe TM1 Top utility enables you to dynamically monitor the threads running in an instance of the

TM1® server. This utility is similar to the UNIX® "top" utility which allows dynamic monitoring

of the processes running on a given system.

TM1 Top is a stand-alone utility that runs within a console (command) window on a Microsoft®

Windows® system. It is designed to make minimal demands on the TM1 server and the supporting

network and system.

With the exception of a user-initiated login process, TM1 Top does not use any cube or dimension

resources in the TM1 server, and does not use or interact with the data or locks on the TM1 server.

The server-side processing that supports TM1 Top runs in a separate light thread to allow TM1

Top to report server state even if the server is unresponsive to users.

When Allowmultimodes=T is set in the TM1top.ini file, TM1 Top can also display information

about sandboxes and the queue.

Note: The TM1 Top user interface and help text are not translated and will appear in English in

non-English versions of TM1.

Operation Guide 143

Chapter 6: System and Performance Monitoring

Page 144: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Installing TM1 TopTM1 Top is installed by default when you install the TM1® server. When you perform a custom

TM1 installation with the TM1 Installation Wizard, TM1 Top is listed under Servers on the Com-

ponent Selection screen.

If TM1 Top is not currently installed on your system, run theTM1 Installation Wizard to install

the utility as follows.

Steps

1. Run the TM1 Installation Wizard.

● If your system has a previous installation of TM1, click Next to advance to the Program

Maintenance screen. On the Program Maintenance screen, select the Modify option. Click

Next to advance to the Installation Options screen.

● If your system does not have a previous installation of TM1, follow the Installation Wizard

steps until the Installation Options screen opens.

2. On the Installation Options screen, select the Custom option for the Installation Type.

3. Click Next.

The Component Selection screen opens.

4. On the Component Selection screen, expand the Servers component category and select the

TM1 Top sub-category.

5. Select the This feature will be installed on local hard drive option for TM1 Top.

6. Follow the steps in the TM1 Installation Wizard to complete the installation.

Configuring the Tm1top.ini FileBefore running TM1 Top, edit the initialization file Tm1top.ini. The Tm1top.ini file is an ASCII

file that specifies environment information for the TM1 Top utility.

By default, a sample Tm1top.ini file is installed to the TM1_install_dir\bin directory. When you

run TM1 Top, the Tm1top.ini file should be located in the same directory as the TM1 Top executable

file.

A sample of a configured Tm1top.ini file is shown below.

adminhost=

allowmultimodes=T

servername=planning sample

logfile=c:\temp\tm1top.log

logperiod=50

logappend=T

refresh=10

adminsvrsslcertid=

adminsvrsslcertauthority=

adminsvrsslcertrevlist=

144 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 145: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

exportadminsvrsslcert=

adminsvrsslexportkeyid=

If you configure TM1® to use SSL for secure data transmission, then you must configure the SSL

parameters in the Tm1top.ini file. For details about configuring TM1 Top to work with SSL, see

"Configuring the Tm1top.ini File" (p. 144).

Do not include any spaces between the parameter name and the parameter value when editing the

Tm1top.ini file.

The parameters in the Tm1top.ini file are described in the following table.

DescriptionParameter

Machine name or IP address of the computer running the Admin

Server. Default value is localhost.

AdminHost

Permits TM1 Top to replace the normal display for a display of

sandboxes or the queue. When this parameter is set to T, and TM1

Top is running, pressing

Allowmultimodes

● n displays the normal screen.

● s displays the sandbox status screen.

● q displays the sandbox queue screen.

If this parameter is set to F or is not present, only the normal mode

of TM1 Top displays.

You must also have sandboxing turned on or job queuing.

Specifies the path and file to which the log information is written.

As TM1 Top is running, the status lines can be continuously written

to this ASCII file so that the activity over time can be monitored.

LogFile

Format is: logfile=path-to-log-file

where path-to-log-file must specify the complete path, filename, and

file extension. A default filename and file extension is not provided.

Specifies the time interval between updates being written to the log

file. This value should be a multiple of the Refresh time parameter.

LogPeriod

The format for this parameter is: logperiod=nn

where nn is the number of elapsed seconds between updates to the

log file. Setting this to zero disables logging.

For example, if the screen Refresh is set to 2 seconds, LogPeriod

could be set to 10 seconds so that every fifth screen display will be

output to decrease the amount of data written to the file.

The default value is 2 seconds.

Operation Guide 145

Chapter 6: System and Performance Monitoring

Page 146: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

Specifies if log data is appended to the log file that is set with the

LogFile parameter, or if the file is overwritten when a new session

is started. If the LogAppend parameter is not set, the existing log file

will be over-written.

LogAppend

Valid values are T and F as shown in the following examples:

If you set LogAppend=T, log data is appended to the log file specified

by the LogFile parameter.

If you set LogAppend=F, the existing log file will be over-written.

The default value is F, which overwrites the existing log file.

Time interval between refreshing of the TM1 Top display. Format

is:

Refresh

refresh=nn

where nn is the time interval in seconds.

Default value is 2 seconds.

TM1 server name. This is the ServerName from the server configu-

ration file, Tm1s.cfg.

ServerName

Note: You can also enter these values at the command prompt when starting TM1 Top, over-riding

the values in the Tm1top.ini file. For details, see "Running TM1 Top with Command-line

Options" (p. 147).

Running TM1 TopYou can run TM1 Top.

Steps

1. Edit the initialization file, Tm1top.ini, as described in "Configuring the Tm1top.ini File" (p. 144).

2. Place the Tm1top.exe and Tm1top.ini files in the TM1_install_dir\bin directory.

Note: By default, the Tm1top.exe file and a sample Tm1top.ini file are installed in the

TM1_install_dir\bin directory when you install the TM1® server.

3. Run the Tm1top.exe file from a command prompt to start TM1 Top.

tm1top.exe

By default, the Tm1top.ini file is read from the same directory that contains the TM1 Top

executable. To specify a different location for the Tm1top.ini file, use the -i command-line

parameter as follows.

tm1top.exe -i path-to-initialization-file

146 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 147: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Running TM1 Top with Command-line Options

You can over-ride the basic parameter values in the Tm1top.ini file by entering them on the command

line when starting TM1 Top.

Note: SSL security parameters can not be entered at the command line and must be specified in the

Tm1top.ini file if TM1® is configured to use SSL. For details, see "Configuring the TM1 Top Utility

to Use SSL."

Use the following format to run TM1 Top with command-line options:

tm1top.exe -OptionName1 OptionValue1 -OptionName2OptionValue2 ..

Where OptionName and OptionValue can be any of the following parameter and value combinations:

● -adminhost admin-host-name

● -servername server-host-name

● -refresh refresh-period

● -logfile file-path

● -logperiod nnn

● -logappend T or F

For example, to run TM1 Top with the ServerName parameter set to sdata and the refresh

parameter set to 5 seconds, enter the following:

tm1top.exe -servername sdata -refresh 5

Note: Use quotes for parameter values that include spaces, as follows:

tm1top.exe -servername "planning sample"

To show a list of available parameters, use the /? option as follows:

tm1top.exe /?

For more details on TM1 Top parameters, see "Configuring the Tm1top.ini File" (p. 144).

Viewing and Understanding the TM1 Top DisplayWhen TM1 Top is running, it displays a set of fields and status information.

Each row in the display represents one unique thread running in the TM1® server that you are

monitoring. The title bar of the console window displays the current values for the AdminHost,

ServerName, and Refresh parameters.

Note: To see more lines or a wider display, you can re-size the console window or use a smaller

font size. If the display fills the entire height of the console window, you can use the up and down

arrow keys on your keyboard to go to the next or previous page within the console window.

TM1 Top can run in the following different display modes:

● Normal

● Sandbox

● Queue

Operation Guide 147

Chapter 6: System and Performance Monitoring

Page 148: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Normal display mode

The following table describes the status fields displayed by TM1 Top.

DescriptionField Name

The thread ID of the underlying system thread in the TM1 server.ID

The name of the user or process that started the thread. This can be

one of three possible thread types.

User Name

● User Thread - Name of an actual user that is logged into TM1. A

value of ??? means the user is currently in the login stage.

● Chore Thread - A chore running on the TM1 server. The name of

the chore thread is displayed in the following format:

C:chore-name

The name of the process running under the chore is displayed in the

Function field.

● SystemThread - A TM1 system process running on the TM1 server.

Displayed in the following format:

Th:name of system thread

● Th:Pseudo - The Pseudo thread is used to clean up user-defined

consolidation (UDC) objects.

● Th:Stats - The Stats thread represents the thread for the perfor-

mance monitor feature that is started when a user selects the Start

Performance Monitor option in TM1 Architect and Server Explorer.

● Th:DynamicConf - This thread dynamically reads and updates

parameters in the TM1 server configuration file, tm1s.cfg.

The current processing state of a specific thread. This value can be one

of the following values:

State

● Idle

● Run

● Commit

● Rollback

● Wait

● Login

For more information, see "Understanding TM1 Thread Processing

States" (p. 151).

148 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 149: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionField Name

The current API function that the thread is executing.Function

If the thread is running a chore, as opposed to a function for an inter-

active user, the Function field will display the name of the process that

is currently executing under that chore.

Lock status of the last object that was locked.Obj Lock Status

Displayed in the format: R# IX# W#

Where:

● R, IX, and W represent the different lock modes on the object. For

more information, see "Understanding TM1 Lock Modes" (p. 150).

● # is the number of locks for each specific lock mode.

Note: The name of the object is displayed in the State field.

Total lock status and count for all objects being used by a thread.User Lock Status

Displayed in the format: R# IX# W#

Where:

● R, IX, and W represent the different lock modes on the objects.

For more information, see "Understanding TM1 Lock

Modes" (p. 150).

● # is the total number of locks, across all objects, for each specific

lock mode.

The total time, in seconds, that the current API function or chore pro-

cess has been processing.

Time

The name of the API function or chore process is displayed in the

Function field.

Sandbox display mode

Pressing the s key while TM1 Top is running switches to sandbox mode. Press n to return to the

normal TM1 Top display. In addition to the ID and Username fields, the following fields become

available in sandbox mode:

DescriptionFields

Name of the currently active sandbox.Active Sandbox

The Total Sandbox Memory being consumed for all sandboxes

by user.

Total Sandbox Memory

Operation Guide 149

Chapter 6: System and Performance Monitoring

Page 150: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionFields

Number of sandboxes for this user.Number of Sandboxes

Queue display mode

Pressing the q key while TM1 Top is running switches to queue mode. Press n to return to the

normal TM1 Top display. In addition to the ID and Username fields, the following fields become

available in queue mode:

DescriptionFields

Name of the sandbox in the queue.Name

Name of the node for the sandbox in the queue.Node Name

Date, time, and state when the status was taken for the sandbox

in the queue.

Status

Length of time sandbox has been in the queue before it was

processed.

Time in Queue

Understanding TM1 Lock Modes

TM1® uses a set of three lock modes to control access to TM1 data. When the TM1 server is running,

these locks are applied to individual objects, such as cubes, views, and dimensions, as these objects

are accessed.

TM1 Top displays the status of these locks for the objects being used by the current threads running

in a TM1 server. Lock status is displayed by TM1 Top under the State, Obj Lock Status, and Total

Lock Status fields.

The lock modes for TM1 objects are described in the following table.

DescriptionLock Mode

R-lock (read lock) - A shared lock that allows many threads to read

from an object at the same time, but does not allow another thread to

modify or write to this object until all R-locks have been released.

R

IX-lock (intent-to-write-lock) - A lock that reserves the right for a

thread to obtain a W-lock on an object when all R-locks have been

released. Only one thread at a time is allowed to have an IX-lock on

an object.

IX

150 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 151: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionLock Mode

W-lock (write lock) - An exclusive lock that allows only one thread at

a time to access and write changes to an object. No other thread can

read or modify this object until the W-lock has been released.

W

Understanding TM1 Thread Processing States

TM1 Top displays the current processing state of each thread in the State field. A thread can be in

one of the following processing states.

DescriptionState

Thread is currently not processing.Idle

Indicates the thread is actively running. Also displays the lock mode and

object being accessed by the thread in the following format:

Run

Run: Lock Mode-(Object Name)-Object Type

Where:

● Lock Mode is one of the possible object lock modes; R, IX, or W. For

more information, see "Understanding TM1 Lock Modes" (p. 150).

● Object Name is the name of the last TM1® object that was being acted

on by the API function displayed in the Function field.

● Object Type is a numeric value representing the type of TM1 object.

Thread is currently committing changes to the objects it was accessing.Commit

Indicates the thread encountered a conflict while committing and could not

proceed. The thread will automatically re-try until the conflict is resolved.

Rollback

Operation Guide 151

Chapter 6: System and Performance Monitoring

Page 152: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionState

Thread is currently waiting for a specific condition to complete. Displayed

in the format:

Wait

Wait: Wait Status - (Object Name) - Object Type

Where:

● Wait Status can be one of the following conditions:

● WR - (WaitForWriterEvent) Thread is waiting for R-locks to be

released so it can obtain a W-lock on the object.

● IXR - (WaitForIXReaderEvent) Thread is waiting for a W-lock to

finish so it can get either an R-lock or an IX-lock on an object.

● IXC - (WaitForIXConflictEvent) Thread is requesting an IX-lock,

but is waiting for another thread with an IX-lock on the same object

to finish and release the lock.

● IXCur - (WaitForIXCurrentEvent) Thread is requesting an IX-lock

for an object, but is waiting for a thread with a R-lock on the same

object to release its lock.

● WC - (WaitForCompletionEvent) Thread is waiting for another

thread to complete and release its locks.

● DRR - (Data Reservation Release) Thread is waiting for a Data

Reservation to be released.

● Object Name is the name of the last TM1 object that was being acted

on by the API function displayed in the Function field.

● Object Type is a numeric value representing the type of TM1 object.

A user is currently logging into the TM1 server.Login

TM1 Top CommandsTM1 Top provides a command prompt to interact with the utility.

You can enter the following commands at the TM1 Top command prompt identified by Cmd:_ in

the top left corner:

DescriptionCommand

Writes the current display to a file.W

Exits the TM1 Top utility.X

152 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 153: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionCommand

Displays help text.H

Displays a user name and password prompt so the TM1®

administrator can log into the current session of TM1 Top and

enter commands to cancel processing in other threads.

V

Cancels processing in another thread.C

Note: Before using the Cancel command, an administrator

must first log into the current session of TM1 Top by using

the V (Verify) command./>.

Use the up and down arrow keys to scroll the status display if

there are more lines in the status than the height of the console

window.

Up, Down arrow keys

Canceling a Thread's ProcessingA system administrator can use TM1 Top to request the cancellation of certain thread operations

or functions that are processing-intensive. TM1 Top can cancel only the following types of threads,

determined by the current state of the thread and the function the thread is currently processing:

● Threads in a Run state - TM1® can cancel only threads with a state of Run that are running

functions involving either TI processing, constructing a view, or calculating a view.

● Threads in a Wait state - Any thread that in a Wait state can be cancelled.

The state of a thread is indicated under the State field in the TM1 Top display.

This functionality provides a way to cancel an action that is negatively impacting other threads by

consuming too much of the server's processing time. For example, a TI process that gets stuck in

a loop, or when a user tries to compute a very large and demanding view.

To cancel a thread, you must use the Cancel and Verify commands together, as described below.

Understanding the Cancel Process

The Cancel process cancels a running or waiting thread as follows:

● If a thread has a Run state, and the process involves TI processing, constructing a view, or

calculating a view, then the thread can be cancelled. While running, the thread will check to

see if its "exit indicator" has been set, and if set, the thread will exit out of the current operation.

● If a thread is in the Wait state, the thread is cancelled in two steps. First, the cancel command

releases the thread's lock request, and then the cancel command cancels the thread's processing.

Understanding the Verify Process

TM1 Top was designed to run without requiring a user to log on to the server. This allows TM1

Top to run against a server which might be resource deadlocked. If a login procedure was required,

Operation Guide 153

Chapter 6: System and Performance Monitoring

Page 154: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

then the login process would also become deadlocked because it requires access to cubes and other

data that are manipulated under the resource locks.

However, it is not desirable to allow just any user running TM1 Top to cancel user threads. As a

compromise between a full login procedure and no security at all, TM1 Top requires that the TM1

Top user must first be "verified" as having administrator access before the Cancel command can

be used. This verification process is initiated using the V (verify) command. The process can be

done in advance and is maintained for the life of the TM1 Top connection.

Using the Verify and Cancel Commands

To verify a TM1 Top session and cancel a thread, complete the following steps.

Steps

1. Enter V to display the following prompt to verify a TM1 Top session:

Verify Admin Access

Admin User Name:

2. Enter the login name of an admin user.

The following prompt displays:

Verify Admin Access

Admin Password:

3. Enter the password for the admin user.

If you entered a valid admin user name and password, then the following confirmation displays:

Admin access verified

Press any key to continue:

4. After the session has been verified, enter C to initiate the Cancel process.

The following prompt displays:

Cancel processing of a thread

Thread-id:

5. Enter the ID of the thread to be canceled. You can find the thread ID displayed in the first

column of the TM1 Top display.

Using TM1 Performance CountersTM1® performance counters are a collection of values that are continuously updated to provide

real-time monitoring of TM1 server performance. These values are incremented and decremented

in real-time to track specific TM1 properties and activities for cubes, views, subsets, dimensions,

and read/write activity.

You can view TM1 performance counters with the following tools:

● TM1 PerfMon utility - A text-only display of TM1 performance counters that runs in a console

window on Microsoft® Windows® and UNIX® systems. The TM1 PerfMon utility can monitor

local TM1 servers only.

154 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 155: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Microsoft Windows Performance Monitor - A Microsoft Windows tool that provides an

interactive, graphical display of TM1 performance counters to monitor local and remote Win-

dows TM1 servers.

Important Notes about Running TM1 Performance Counter ToolsYou need the same administrator rights and privileges to run TM1® PerfMon on a Microsoft®

Windows® system as you do to run the Microsoft Windows Performance Monitor:

● The user must be a member of the local Administrators group to run either TM1 PerfMon or

the Microsoft Windows Performance Monitor.

● The user must be a member of the Administrators group, on both the local and remote systems,

to monitor a remote TM1 server using the Microsoft Windows Performance Monitor.

Viewing TM1 performance counters with the Microsoft Windows Performance Monitor is not

supported on 64-bit Intel Itanium II systems. When running TM1 with this configuration, use the

TM1PerfMon console utility to view TM1 performance counters.

Available TM1 Performance CountersTM1® provides a set of more than 30 performance counters, organized into groups, such as Cubes,

Dimensions, Subsets, Memory, Threads, and Views.

Examples of TM1 performance counters include:

● Threads created

● Views and Dimensions created and destroyed

● Subsets created, duplicated, destroyed, and deleted

● Read lock requests and waits

Note: To see a complete, updated list of available TM1 performance counters, with descriptions,

use the Microsoft Windows Performance Monitor as described in "Adding and Viewing TM1 Per-

formance Counters in the Microsoft Windows Performance Monitor" (p. 157) .

Viewing TM1 Performance Counters with the TM1 PerfMon UtilityTM1® PerfMon is a console utility for Microsoft Windows and UNIX systems that provides a text

display of TM1 performance counters.

Running TM1PerfMon

Run the tm1perfmon.exe file from a command line on either a Microsoft Windows or UNIX system.

Use the following format and parameters:

tm1perfmon -servername Name-loopLoopCount-sleepSleepTime

Where:

● Name is the name of the TM1® server to monitor. Use quotes when the server name includes

spaces. For example:

Operation Guide 155

Chapter 6: System and Performance Monitoring

Page 156: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

-servername "planning sample"

● LoopCount is the number of times to repeat, or refresh, the display of counter values. Default

value is 1, no loop. This value is optional.

A value of 0 causes TM1 PerfMon to loop indefinitely.

To cancel TM1 PerfMon while looping, press the CTRL+Break keys to return to the command

prompt.

● SleepTime is the time, in seconds, between loops. Default value is 5 seconds. This value is

optional.

For example, the following command line would run TM1 PerfMon continuously to monitor a

TM1 server named planning sample. The display would continue to refresh every 5 seconds, using

the default value for the sleep option, until you exit by pressing the CTRL+Break keys.

tm1perfmon -servername "planning sample" -loop 0

The following command line would run TM1 PerfMon to monitor the salesdata TM1 server,

looping a total of 10 times with a 5 second refresh rate between display updates.

tm1perfmon -servername salesdata -loop 10 -sleep 5

Note: If you do not include values for the loop and sleep options, as shown in the following

example, TM1 PerfMon will run and display the TM1 performance counters once only.

tm1perfmon -servername salesdata

Viewing the TM1 PerfMon Display Output

The display output from TM1® PerfMon looks similar to the following:

C:\>tm1perfmon -server cdata

TM1 Version: 9.0.3.226

Output data and time Tue Dec 05 17:36:42 2006

Counter Name/ Value

Threads: Threads created 6

Threads: Threads Creation Retry Attemtps 0

Threads: Thread Creations Failures 0

Views: Views Created 23

Views: Empty Views Created 0

Views: Views Destroyed 0

Dimensions: Dimensions Created 0

Dimensions: Dimensions Destroyed 119

Cubes: Cubes Invalidated 0

Cubes: Dependent Cubes Invalidated 1

Subsets: Subset Create Empty 0

Subsets: Subset Calculated by Expression 0

Subsest: Subset Calculated with Empty Expression 0

Subsets: Subset Calculated by Expression 0

Subsets: Subset Created by Expression 0

Subsets: Subset Created by MDX Expression 0

Subsets: Subset Duplicated 0

156 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 157: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Subsets: Subsets destroyed 0

Subsets: Subsets Deleted 0

The title fields in the display include:

DescriptionField

Group name and counter name for each TM1 performance counter.Counter Name

Displayed in the format: GroupName:CounterName

For example: Threads:Threads Created

Numeric value for the TM1 performance counter at the specific

output date and time.

Value

Exiting TM1 PerfMon

To exit the TM1® PerfMon while the utility is still looping press CTRL+Break at anytime.

Viewing TM1 Performance Counters with the Microsoft Windows PerformanceMonitor

Use the Microsoft® Windows® Performance Monitor to view TM1® performance counters in a

graphical-type display for Windows TM1 servers only. The Microsoft Windows Performance

Monitor is supplied with current versions of Microsoft Windows and runs as an add-in to the

Microsoft Management Console.

Opening the Microsoft Windows Performance Monitor

To open the Microsoft® Windows® Performance Monitor, complete the following steps.

Step

● Click Start, Settings, Control Panel, Administrative Tools, Performance.

The Microsoft Windows Performance Monitor opens.

Adding and Viewing TM1 Performance Counters in the Microsoft Windows Performance Monitor

You can view TM1® performance counters by adding them with the Add Counters dialog box in

the Microsoft® Windows® Performance Monitor. This dialog also lets you view a brief explanation

of each counter.

Steps

1. Click Add in the Performance Monitor toolbar.

The Add Counters dialog box displays.

Note: Microsoft Windows can sometimes display the following message when you open or

close the Add Counters dialog.

Operation Guide 157

Chapter 6: System and Performance Monitoring

Page 158: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

"At least one data sample is missing. Data collection is taking longer than expected.You might

avoid this message by increasing the sample interval. This message will not be shown again

during this session."

This message is informational only and typical if the system becomes too busy when adding

new counters. Click OK to clear the message.

2. Select IBM Cognos TM1 from the Performance object list.

The available performance counters display in the performance counter list.

3. Select a performance counter from the list of available counters.

You can also click Explain to see a text description of the currently selected counter.

4. Select the instance of the server you want to monitor.

5. Click Add to add the selected counter to the performance display.

6. Click Close to close the Add Counters dialog and return to the Performance Monitor.

The Performance Monitor will add the TM1 performance counters to the monitoring process

and update the display as shown in the following figure.

TM1 performancecounters

Capturing Core Dumps for TM1 Server Crash AnalysisIf you ever experience a TM1®server crash, it is imperative that the appropriate debugging tools

are configured correctly and the correct files are collected and sent to IBM® Cognos® support and/or

engineering for analysis.

Debugging Tools for WindowsYou can use either ADPlus or Dr. Watson as a debugging tool to collect server crash information

on a Windows system.

158 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 159: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Installing and Running ADPlusADPlus is part of the Microsoft® Debugging Tools for Windows® package. You can download the

most recent package at http://www.microsoft.com/whdc/devtools/debugging/default.mspx.

Both a 32-bit version and a 64-bit version of Debugging Tools for Windows is available, be sure

to download the version that is appropriate for your operating system.

For complete details on ADPlus, including system requirements, see http://support.microsoft.com/

kb/286350.

Running ADPlus Directly on the TM1 Server

Follow these steps to run ADPlus directly on the computer where the TM1® server is installed:

Steps

1. Start the TM1 server.

2. Open a command prompt window and cd to the Debugging Tools for Windows directory. The

default directory on a 32-bit system is C:\Program Files\Debugging Tools for Windows (x86).

3. Open the Windows® Task Manager and note the process ID (PID) for Tm1s.exe (if running

the server as an application) or Tm1sd.exe (if running the server as a service).

4. At the command prompt, enter adplus –crash –p [PID]

For example, adplus –crash –p 492

If you cannot determine the process ID for the server you want to monitor, you can also use

one of the following commands to start ADPlus:

● adplus -crash -pn tm1sd.exe if running the TM1 server as a service

● adplus -crash -pn tm1s.exe if running the TM1 server as an application

5. A warning message appears indicating that an environment variable is not set. You do not have

to take any action based on this warning. Click OK to dismiss the warning.

Another message appears indicating that a new subdirectory will be created in the Debugging

Tools for Windows directory. The new subdirectory, which is named Crash_Mode_DateS-

tamp_TimeStamp, receives the dump files that are generated when the TM1 server crashes.

6. Click OK to dismiss the message.

Note that a new command prompt window is now open on your desktop. The Microsoft

Console Debugger (cdb.exe) runs in this window, as shown in the following image.

Operation Guide 159

Chapter 6: System and Performance Monitoring

Page 160: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Monitoring the TM1 Server

If you are monitoring the server, just continue your daily activity. When the server crashes, three

dump files (.dmp) are created in the Crash_Mode_DateStamp_TimeStampsubdirectory. The only

one IBM needs to debug the server crash is the ...2nd chance_AccessViolation…file.

Using CTRL-C to Force a TM1 Server Crash

To force a server crash, enter CTRL-C in the cdb.exe command prompt window.

The name of the resulting dump (.dmp) file will include the string ...1st_chance_CONTROL_C_OR

Debug_Break.... This is the file IBM needs to debug the TM1 server.

Taking a Snapshot of Current Server State

Follow these steps to take a snapshot of the current server state, but leave the TM1 server running:

Steps

1. Start the TM1 server.

2. Open the Windows Task Manager and note the process ID (PID) for Tm1s.exe (if running the

TM1 server as an application) or Tm1sd.exe (if running the TM1 server as a service).

3. Open a command prompt window and cd to the Debugging Tools for Windows directory

4. At the command prompt, enter adplus –hang –p <PID>.

For example, adplus –hang –p 492

Note: You can run a -hang command even when adplus is already running in -crash mode.

A warning message appears indicating that an environment variable is not set. You do not have

to take any action based on this warning.

5. Click OK to dismiss the warning.

160 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 161: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Another message appears indicating that ADplus is running in HANG mode. The message also

indicates that a subdirectory will be created in the Debugging Tools for Windows directory.

The new subdirectory, which is named Hang_Mode_DateStamp_TimeStamp, receives the dump

files that record the current server state.

6. Click OK to dismiss the message.

A new dump file is immediately generated, recording the current server state.

7. Open the new subdirectory in the Debugging Tools for Windows directory and note the presence

of a single dump (.dmp) file. This is the file IBM needs to debug your server.

Running ADPlus Remotely from a TM1 Client

In some environments, you might want to manage and run ADPlus from the computer on which a

TM1 client is running, rather than directly from the TM1 server.

Installing and Running ADPlus on the TM1 Server

Follow these steps to install and run ADPlus on the computer where the TM1 server is running.

Steps

1. Install the Microsoft® Debugging Tools for Windows package.

2. Create a batch file named Remoteshell.cmd in the debugging tools installation directory

(C:\Program Files\Debugging Tools for Windows (x86) if you accepted the default installation

directory on a 32-bit system.) This batch file should contain the following single line:

C:\Program Files\Debugging Tools for Windows (x86)\remote.exe /s "cmd.exe"

remoteshell

3. From a command prompt, enter the following line:

at 2 minutes past current time, 24 hour format C:\Program Files\Debugging Tools for Windows

(x86)\remoteshell.cmd

For example, if your system clock shows 4:45 PM, enter the following line at the command

prompt:

at 16:47 C:\Program Files\Debugging Tools for Windows (x86)\remoteshell.cmd

This command. will run the remoteshell.cmd batch file at 4:47 PM

4. After the specified time, run the at command from a command prompt. Do not include any

parameters to the command, type only at.

If the remoteshell.cmd batch file ran successfully, you should see a report that lists the Status,

Day, Time and Command Line listing such as "c:\Program Files\Debugging Tools for Windows\

remoteshell.cmd."

For more details on the at command, see http://technet2.microsoft.com/windowsserver/en/

library/40b9beb1-3578-48f9-93e1-7ca6760c1c151033.mspx.

Operation Guide 161

Chapter 6: System and Performance Monitoring

Page 162: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

5. Open the Windows Task Manager and note the process ID (PID) for Tm1s.exe (if running the

TM1 server as an application) or Tm1sd.exe (if running the TM1 server as a service). You will

need to know the PID when running ADPlus from the TM1 client.

Running ADPlus from a TM1 Client

Follow these steps to run ADPlus from a computer on which a TM1 client is installed.

Steps

1. Copy the remote.exe and breakin.exe files from the debugging tools installation directory on

the TM1 server computer. (C:\Program Files\Debugging Tools for Windows (x86) if you accepted

the default installation directory on a 32-bit system.)

2. Save remote.exe and breakin.exe to an easily identified directory on the computer running

theTM1 client. These instructions assume that remote.exe is saved in C:\debuggers.

3. Open a command prompt and cd to the C:\debuggers folder.

4. Enter the following command:

remote.exe /c remote server name remoteshell

remote server name is the name of the computer on which the TM1 server is installed; it is not

the name of the TM1 server. For example, if smithers is the name of the computer where the

server is installed, you would enter the command

remote.exe /c smithers remoteshell

5. You are now running commands on the server computer from the command prompt on the

client computer. To confirm that you are properly connected to the server, enter dir C:\ at

the command prompt. You should see the contents of the C drive on the server.

6. From the command prompt, cd to the debugging tools installation directory on the TM1 server

computer. Again, this is C:\Program Files\Debugging Tools for Windows (x86) if you accepted

the default installation directory on a 32-bit system.

7. Enter the following at the command prompt:

Adplus -crash -quiet -p <PID>

PID is the process ID of the TM1 server. For example, if the process ID for the server is 1588,

enter Adplus -crash -quiet -p 1588 at the command prompt.

You should receive confirmation that the debugger is attached to the TM1 server.

ADPlus is now ready to collect debugging information and will continue to monitor the server

until it crashes.

Stopping ADPlus

Usually, you will want to let ADPlus run until a server crash occurs. However, if you need to stop

ADPlus, enter the following line at the command prompt on the client computer:

breakin.exe <PID>

162 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 163: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

PID is the process ID of the TM1 server. For example, if the process ID for the TM1 server is 1588,

enter breakin.exe 1588 at the command prompt to stop the debugging process.

Running Dr. WatsonDr. Watson is part of the Windows® operating system, so you do not need to install the tool.

Steps

1. From the Windows taskbar, click Start, then click Run

2. In the Run dialog box, enter drwtsn32, then click OK.

3. In the Dr. Watson dialog box, the Log File Path can be set to any path and Crash Dump can

be set to any path/filename you want. Take note of the path/filename you set for the Crash

Dump, as this file must be sent to IBM for analysis.

4. Set and enable only the following options:

● Number of Instructions: 10

● Number of Errors to Save: 10

● Crash Dump Type: Full

● Dump Symbol Table

● Dump All Thread Contents

● Create Crash Dump File

5. Click OK to begin running Dr. Watson.

Setting Dr. Watson as the Default Debugging Tool

If you have ADPlus or another debugging tool installed on your system, you may need to set Dr.

Watson as the default debugger.

Steps

1. From the Windows® taskbar, click Start, then click Run.

2. In the Run dialog box, enter drwtsn32 -i, then click OK.

You can now confirm that Dr. Watson is running as the default debugger.

3. From the Windows taskbar, click Start, then click Run.

4. In the Run dialog box, enter regedit, then click OK.

5. From the Registry Editor, click Edit, then click Find.

6. Search for AeDebug in the registry.

The settings for the AeDebug key should show drwatsn32 set as your Debugger.

Operation Guide 163

Chapter 6: System and Performance Monitoring

Page 164: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Collecting Files for Analysis Following A TM1 Server CrashIf the TM1®server crashes, you must collect the following files for IBM® support and engineering

to analyze:

● The dump file generated by your debugging tool.

If you are running ADPlus, the dump file is named ProcessID_ProcessName_2nd_chance_

AccessViolation_TimeStamp.dmp. For example, PID-492_TM1SD.EXE_2nd_chance_

AccessViolation_full_ODB8_2008-03-08_10-17-59-052_01EC.dmp

If you are running Dr. Watson, the dump file name and location was set with the Crash Dump

option when you started Dr. Watson.

● The Tm1server.log file. This file is located in the TM1 server data directory.

● All TM1ProcessError.log files generated during the server session that crashed.

When a process error log file is generated, TM1 assigns a unique name that lets you readily

identify which TurboIntegrator process generated the error file and the time at which the file

was created. File names are assigned using the convention TM1ProcessError_time stamp_process

name.log. In this convention, time stamp is the time (expressed as yyyymmddhhmmss GMT)

at which the file was generated and process name is the name of the TurboIntegrator process

that caused the errors.

There may be multiple TM1ProcessError.log files associated with the server session that crashed.

All TM1ProcessError.log files are stored in the server data directory.

● If you are running TM1 Top, collect the TM1 Top log file. The location and name of the log

file are determined by the logfile parameter to the Tm1top.ini configuration file.

The Tm1top.ini configuration file is located in the same directory as the TM1 Top executable

file (Tm1top.exe), which is usually install dir\ bin. If you accepted the default TM1 installation

directory, the full path is C:\Program Files\Cognos\TM1\bin.

● DO NOT collect the TM1 transaction log (Tm1s.log) unless specifically requested by IBM

support.

Transmitting Files to CognosOnce all required files are collected, you must deliver the files to Cognos support for analysis. There

are several options for delivering the files.

FTP

The quickest way to deliver files to IBM is to upload them to the IBM FTP server. You can access

the IBM FTP server from a command prompt or from a Web browser.

Uploading from a Command Prompt

Follow these steps to upload files to the IBM® FTP server from a command prompt.

Steps

1. cd to the directory where the file you want to upload resides.

164 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 165: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

2. At the command prompt, enter ftp testcase.boulder.ibm.com.

3. When prompted for a username, enter anonymous.

4. When prompted for a password, enter your email address.

The Virtual user anonymous logged in message confirms that you are connected to the FTP

server.

5. cd to the /toibm/im directory.

6. At the command prompt, enter bin to set the upload mode to binary.

7. At the command prompt, enter put followed by the name of the file you want to upload. For

example, to upload a file named MyDumpFiles.zip, enter put MyDumpFiles.zip.

Uploading from a Web Browser

Follow these steps to upload files to the IBM FTP server from a Web browser.

Steps

1. Go to https://testcase.boulder.ibm.com.

2. Log in with user name anonymous. No password is required for an anonymous login.

3. Click the toibm folder.

4. Click the im folder.

5. Click Browse and navigate to the file you want to upload.

6. Click Upload file (binary).

Uploading to Your FTP Server

Alternatively, you can upload the files to your own FTP server and contact IBM support with

instructions for retrieving the files. You should use your own FTP server only if you cannot establish

a connection to the IBM FTP server.

Operation Guide 165

Chapter 6: System and Performance Monitoring

Page 166: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

166 IBM Cognos TM1

Chapter 6: System and Performance Monitoring

Page 167: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 7: Administering IBM Cognos TM1 Web

This chapter describes how to configure IBM® Cognos® TM1® to work over the Web.

IBM Cognos TM1 Web OverviewIBM® Cognos® TM1® Web extends the analytical power of TM1 by allowing you to complete the

following tasks in a Web browser:

● Analyze cube data

● Manipulate formatted Excel reports

● Drill, pivot, select, and filter data

● Build charts

● Perform some server administration tasks

IBM Cognos TM1 Web ArchitectureThe IBM® Cognos® TM1® Web multi-tiered architecture uses the following components:

● Microsoft® Internet Information Services (IIS) Web server

The IIS Web Server has a virtual directory that stores TM1 Web ASP scripts.

The IIS Web server must have Microsoft Excel 2002 (or later) installed. This software is required

to generate TM1 Websheets.

The IIS Web server must have Microsoft .NET Framework version 3.0 installed.

● Microsoft® Excel Web service for displaying Websheets

TM1 Web installs a Windows service, the TM1 Excel Service (TM1ExcelService.exe), on your

Web server. This service converts Excel worksheets to TM1 Websheets. It also exports Web-

sheets back to Excel or to PDF.

● IBM Cognos 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.

Note: 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.

● IBM Cognos TM1 Admin server

Licensed Materials – Property of IBM167© Copyright IBM Corp. 2007, 2011.

Page 168: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

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.

Note: IBM Cognos TM1 Web requires the Microsoft .NET Framework. For more information

about the exact requirements and configuration, see the ".NET Framework Requirements" section

in the IBM Cognos TM1 installation documentation.

Accessing Multiple TM1 Servers from IBM Cognos TM1 WebIBM® 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, IBM Cognos 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 IBM Cognos TM1 Web will

automatically log you in to these other servers on an as-needed basis. This behavior is different

from TM1 Architect and 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, IBM Cognos 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 IBM Cognos TM1 WebIf you want to prevent IBM® Cognos® 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 TM1 server. For example, with this configuration, if you log into IBM Cognos 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.

Note: If you configure your TM1 servers to run under separate Admin Servers, but still want to

access them from IBM Cognos TM1 Web, TM1 Architect, or 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 IBM Cognos TM1 Web to access multiple Admin Servers,

see "Configuring the Login Page using the AdminHostName and TM1ServerName Parame-

ters" (p. 195).

● For information about configuring TM1 Architect and TM1 Perspectives to access multiple

Admin Servers, see "The Tm1p.ini File" in the "System Configuration" section of the IBM®

Cognos® TM1® Operation Guide.

168 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 169: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Installing and Running IBM Cognos TM1 WebBefore you install the IBM® Cognos® TM1® Web software, you need to understand about the

software requirements:

● "Software Requirements" (p. 169).

● "Installing the IBM Cognos TM1 Web Software" (p. 169).

● "Configuring Language Settings in Microsoft Internet Explorer" (p. 170).

● "Running IBM Cognos TM1 Web in Mozilla Firefox Web Browser" (p. 171).

● "Running the 64-bit version of IBM Cognos TM1 Web on Windows x64" (p. 173).

● "Running IBM Cognos TM1 Web on a WAN Server and Exporting Excel and PDF Files" (p. 173).

● "Using ClearType on TM1 Web Server to Enhance Display and Rendering of Websheets" (p. 174).

Software RequirementsFor a comprehensive and updated list of supported operating systems, Web servers, and versions,

see the IBM® Cognos® Information Center link to the Hardware and Software Requirements.

RequirementSoftware

Microsoft® Windows®Operating System

Microsoft IISWeb server

Microsoft Excel 2002 or laterMicrosoft Excel

Microsoft Internet ExplorerWeb browser

Windows services run under a network user name and password.

Establish a user account and password in your network exclusively

for the IBM Cognos TM1 Web services. The account can have any

name.

Windows Service

Account

Installing the IBM Cognos TM1 Web SoftwareFollow these steps to install IBM® Cognos® TM1® Web.

Steps

1. Insert the TM1 distribution CD in the CD-ROM drive.

The Installation Wizard runs.

2. Click IBM Cognos TM1 Web, and click Install.

3. Select a language: English, French or German. Click OK.

Operation Guide 169

Chapter 7: Administering IBM Cognos TM1 Web

Page 170: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The Installation Wizard Welcome screen opens.

4. Follow the wizard instructions to install IBM Cognos TM1 Web.

Note: For detailed explanations of the installation procedure, click

Help in the TM1 Installation Wizard or see the IBM® Cognos® TM1® Installation Guide.

Configuring Language Settings in Microsoft Internet ExplorerThe language settings in Microsoft® Internet Explorer determine which language is used in the IBM®

Cognos® TM1® Web interface. Follow these steps to configure Internet Explorer to display IBM

Cognos TM1 Web with your primary language.

Steps

1. Open Microsoft Internet Explorer.

2. Click Tools, Internet Options from the Internet Explorer menu bar.

The Internet Options dialog box opens.

3. Click the General tab.

4. Click the Languages button located near the bottom of the General tab.

The Language Preference dialog box opens.

5. Verify that the primary language that you want IBM Cognos TM1 Web to use is displayed at

the top of the Language list.

If the desired language is not in the Language list, you must add it by clicking the Add button

to display the Add Language dialog box. Select the language that you want to use and then

click OK.

After you add the language, you must move it to the top of the Language list on the Language

Preference dialog by selecting it and then clicking the Move up button.

6. Click OK to close the Language Preference dialog box.

7. Click OK to close the Internet Options dialog box.

Displaying and Entering Numbers Based on Regional SettingsIf 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 Windows regional

setting are set to the same value. This will enable you to display and enter numbers in IBM Cognos

TM1 Web based on a specific regional setting.

For example, if you have an English OS, but want to run IBM 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.

170 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 171: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

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 Language Settings

in Microsoft Internet Explorer" (p. 170).

Configuring Microsoft Internet Explorer for IBM Cognos TM1 WebIf you are using IBM® Cognos® TM1® Web with Microsoft® Internet Explorer, make sure you have

the following security setting enabled to allow IBM Cognos TM1 Web dialog windows to display

correctly. If Microsoft Internet Explorer is not configured correctly, some IBM Cognos TM1 Web

dialogs can appear truncated.

The following steps are applicable to Internet Explorer versions 7 and 8.

Steps

1. In Microsoft Internet Explorer, select Tools, Internet Options.

The Internet Options dialog opens.

2. Click the Security tab.

3. Select Local Intranet zone.

If the web server is outside the intranet zone, you may need to select Internet Zone instead.

4. Click Custom Level.

The Security Settings dialog opens.

5. Locate the Allow websites to open windows without address or status bars option and click

Enable. This is the default setting for this option.

6. Also in the Miscellaneous setting section, locate the Allow script-initiated windows without

size or position constraints option and click Enable.

7. Click OK to close the Security Settings dialog.

8. Click OK to close the Internet Options dialog.

Running IBM Cognos TM1 Web in Mozilla Firefox Web BrowserThis section describes configuration and limitations when running IBM® Cognos® TM1® Web with

the Mozilla Firefox 2.0 web browser on Microsoft Windows and Apple Mac OS X systems.

Operation Guide 171

Chapter 7: Administering IBM Cognos TM1 Web

Page 172: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Enabling the JavaScript Raise or Lower Windows Option

By default, Firefox 2.0 disables the JavaScript™ option for raising and lowering pop-up windows.

IBM® Cognos® TM1® Web requires this option to be enabled to correctly control the display of

TM1 pop-up windows, dialog boxes, and messages.

Steps

1. Open the Firefox Options dialog box, depending on the type of system you are using:

If you are running Firefox on a Microsoft Windows system:

Click Tools, Options, Content

If you are running Firefox on an Apple Mac OS X system:

Click Firefox, Preferences, Content

The Options dialog box opens.

2. Click the Advanced button for the Enable JavaScript option.

The Advanced JavaScript Settings dialog box opens.

3. To enable the required JavaScript setting, select the Raise or lower windows option.

4. Click OK to close the Advanced JavaScript Settings dialog box.

5. Click OK to close the Options dialog box.

After making this change, Firefox will correctly handle pop-up windows for IBM Cognos TM1

Web.

Zoom Functionality Not Available in Websheets

The zoom feature in TM1® Websheets is not supported in Firefox on both Microsoft Windows

and Apple Mac OS X systems. When viewing Websheets in Firefox, the Zoom In, Zoom Out, and

Normal View icons do not display.

Enabling the Display of Symbol and Wingdings Fonts

If you use Symbol or Wingdings fonts, you must complete the following steps to configure Firefox

to display these fonts.

Steps

1. Open the Firefox fontEncoding.properties file in a text editor.

If you accepted the default installation directory when you installed Firefox, the full path to

this file is C:\Program Files\Mozilla Firefox\res\fonts\fontEncoding.properties.

2. Locate the following lines:

# Symbol font

encoding.symbol.ttf = Adobe-Symbol-Encoding

3. Replace the above lines with the following:

# Symbol font

#-- Enabling Symbol and other fonts for Mozilla on Windows

172 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 173: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

encoding.symbol.ttf = windows-1252

encoding.wingdings.ttf = windows-1252

encoding.wingdings2.ttf = windows-1252

encoding.wingdings3.ttf = windows-1252

encoding.webdings.ttf = windows-1252

4. Save the fontEncoding.properties file.

Running the 64-bit version of IBM Cognos TM1 Web on Windows x64To run the 64-bit version of IBM® Cognos® TM1® Web on a Microsoft Windows x64 system, you

must:

● Configure Microsoft® Internet Information Services (IIS) to run in 64-bit mode.

● Register the 64-bit version of Microsoft® .NET Framework 3.5 SP1.

Steps to switch IIS to 64-bit mode

1. Open a command prompt.

2. Enter and run the following command:

cscript %SYSTEMDRIVE%\inetpub\adminscripts\adsutil.vbsSET W3SVC/AppPools/Enable32bitAppOnWin64 0

Steps to register the 64-bit version of .NET Framework

1. Make sure that the 64-bit version of Microsoft .NET Framework 3.5 SP1 is installed on the

Web server.

2. Open a command prompt.

3. Change to the following directory:

C:\WINDOWS\Microsoft.NET\Framework64\v2.0.50727)

Note: IBM Cognos TM1 Web requires the Microsoft .NET Framework 3.5 SP1, however,

.NET 2.0 remains on your system after upgrading .NET and is required for this step.

4. Enter and run the following command:

aspnet_regiis.exe -i

Your system is now configured to run the 64-bit version of IBM Cognos TM1 Web.

For more information about running the 64-bit version of ASP.NET, see the following Microsoft

technical article:

http://support.microsoft.com/?id=894435

Running IBM Cognos TM1 Web on a WAN Server and Exporting Excel and PDFFiles

If you are running IBM® Cognos® TM1 Web on a WAN (Wide Area Network) server and want to

allow users to export Excel and PDF® files from IBM Cognos TM1 Web, you need to configure

specific security settings in Internet Explorer.

Operation Guide 173

Chapter 7: Administering IBM Cognos TM1 Web

Page 174: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

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 IBM

Cognos TM1 Web in a WAN environment, you must add the IBM Cognos TM1 Web server as a

trusted site in the security settings for Internet Explorer.

Depending on which version of Internet Explorer you are using, perform the steps in the following

sections.

Configuring Internet Explorer 6

If you are using Internet Explorer 6 and running IBM® Cognos® TM1® Web on a WAN server, you

must add the IBM Cognos TM1 Web server as a trusted site.

Steps

1. Click Tools, Internet Options.

The Internet Options dialog opens.

2. Click the Security tab.

3. Click Trusted Sites and then click the Sites button.

4. Enter the URL of the IBM Cognos TM1 Web server in the Add this Web site to the zone box.

5. Click Add.

6. Click Close.

Configuring Internet Explorer 7

If you are using Internet Explorer 7 and running IBM® Cognos® TM1® Web on a WAN server, you

must add the IBM Cognos TM1 Web server as a trusted site and then customize the security settings

for trusted sites.

Steps

1. Perform the steps to add the IBM Cognos TM1 Web server as a trusted site, as described in

"Configuring Internet Explorer 6" (p. 174)

2. 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.

3. Locate the settings for Downloads and click Enable for the Automatic prompting for file

downloads option.

4. Click OK.

Using ClearType on TM1 Web Server to Enhance Display and Rendering ofWebsheets

To enhance the display of TM1® Websheets, especially ones that include a combination of frozen

and unfrozen panes with wrapped text within cells, install the Microsoft® ClearType Tuner on the

174 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 175: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

TM1 Web server. This tool helps TM1 Web maintain the same row height between frozen and

unfrozen panes in Websheets. Installation on client systems is optional.

Installing and Activating Microsoft ClearType Tuner

Steps

1. Download and install Microsoft ClearType Tuner from the Microsoft web site.

2. After installation, open ClearType Tuning from the Microsoft Windows Control Panel.

3. Click the Introduction tab and make sure the Turn On ClearType option is selected.

4. Click the Advanced tab and then click the Set Sample Font button. Choose a font for the text

sample and then click OK.

5. On the Advanced tab, click to enable the Apply all settings to defaults for new users and systemoption.

6. Click OK.

7. Restart your computer.

Configuring TM1 Web to Run in Windows VistaRunning TM1® Web on a Microsoft® Windows® Vista system is not a supported environment for

development or live applications of TM1. However, if you want to run TM1 Web and view Web-

sheets on a Windows Vista system for demonstration or personal use only, this section describes

how to configure your system.

If you do not configure Windows Vista as explained in the following steps, TM1 Web displays an

error when you view Websheets or try to export data to an Excel spreadsheet.

This configuration is for users that want to log on to a computer running Windows Vista and work

directly with TM1 Web on that system. It is not intended for remotely accessing TM1 Web from

a Web browser on another computer.

Steps

1. Click Start, All Programs, Accessories, Run.

The Run dialog box opens

2. In the Run dialog box, type dcomcnfg and then click OK.

The Windows Component Services tool opens.

3. Expand the tree to the following node:

Console Root, Component Services, Computers, My Computer, DCOM Config.

4. Under the DCOM Config node, scroll down and select the Microsoft Excel Application item.

5. Right-click on the Microsoft Excel Application item and then click Properties.

The Properties dialog box opens.

Operation Guide 175

Chapter 7: Administering IBM Cognos TM1 Web

Page 176: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

6. Click the Identity tab and then click to enable the option, The interactive user.

7. Click OK to close the Properties dialog box and then close the Component Services window.

Administering the TM1 Server from IBM Cognos TM1 WebThe options available in the Administration node in the Navigation pane of IBM® Cognos® TM1®

Web vary according to the TM1 group to which you belong.

If you are a member of the ADMIN group on a TM1 server, the Administration node displays the

following options.

Optionicon

Administration

Processes

Review and execute processes on the TM1 server.

Chores

Review and execute chores on the TM1 server.

Client Properties

Review and set properties for the client machines.

Cube Properties

Review and set properties of cubes.

Dimension Properties

Review and set properties for dimensions.

Change Password

Change your TM1 admin password.

If you are a member of any other user group, the Administration node displays the Change Password

option. The Processes and Chores options might be available as well, depending on your security

privileges for processes and chores on the server. If you have Read privilege to any processes on the

server, the Processes option is available. Similarly, if you have Read privilege to any chores on the

server, the Chores option is available.

Steps

1. Log in to IBM Cognos TM1 Web as a TM1 administrator.

2. Click Administration in the left Navigation pane.

176 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 177: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

3. Click the option relevant to the administrative task you want to perform.

Each administrative task is described below.

Administering ProcessesYou can administer processes on the TM1® server.

Steps

1. In the Administration pane, click Processes.

IBM Cognos TM1 Web displays a list of processes you established on your TM1 server.

2. To display the control processes, select the Display Control Processes check box. To hide the

control processes, clear the Display Control Processes check box.

3. Click a process to select it.

IBM Cognos TM1 Web displays two boxes next to the process list. All values in these boxes

are read-only; they allow you to review your process but not to change attributes or parameters.

● Process Attributes - At the top right of the Processes page, TM1 displays the process

attributes for the selected process.

Sample Process Attributes:

Plan_load_budget_odbc

ODBCDatasource Type

Security Owner

AVAILABLESecurity Status

TrueReadable

FalseWriteable

FalseEncrypted

● Process Parameters - At the bottom right of the Processes page, TM1 displays the default

process parameters you established on the Parameters tab of the TurboIntegrator process.

Sample Process Attributes:

TypeProcess Parameters

StringFY 2003 BudgetPVersion

StringJan-2003PStartDate

Operation Guide 177

Chapter 7: Administering IBM Cognos TM1 Web

Page 178: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

TypeProcess Parameters

StringDec-2003PEndDate

Note: If your process does not use parameters, the Process Parameters box does not appear.

4. To change the process attributes, use the TM1 Server Explorer. For details, see the IBM® Cognos®

TM1® User Guide.

5. To run a process, click a process in the list and click Execute Process .

Administering ChoresYou can administer chores on the TM1® server.

Steps

1. In the Administration pane, click Chores.

IBM® Cognos® TM1 Web displays a list of chores you established on your TM1 server.

2. To display the control chores, select the Display Control Chores check box. To hide the control

chores, clear the Display Control Chores check box.

3. Click a chore to select it.

IBM Cognos TM1 Web displays the following information about the chore:

● Process list - Lists TM1 processes that run when you execute the chore. The processes run

in the order they appear in the list.

● Basic Chore Parameters - Indicates whether the schedule of the chore is active, the number

of processes in the chore, the last start time, and how often the chore runs.

● Chore schedule - Shows the days on which the chore is scheduled to run, and how often

the chore runs.

● Last execution time - Shows the last time the chore was run.

178 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 179: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Process List

Basic Chore Parameters

Chore Frequency

Chore Schedule

Last execution time

TM1 also displays the Chore Administration toolbar at the top of the page.

The Chore Administration toolbar contains the following buttons.

DescriptionButton NameButton

Saves the changes you make to the chore.Save Chore

Runs the chore. IBM Cognos TM1 Web prompts

you for any parameters the chore requires.

Execute Chore

Activates the chore to run on the assigned sched-

ule.

Activate ChoreActivate

Deactivates the chore so that it no longer runs on

a schedule. Deactivated chores can still be run

manually by clicking the Execute Chore button.

Deactivate ChoreDeactivate

Displays the Chore Process List Editor dialog box.Edit Chore

Use this dialog box to modify and arrange the list

of processes that run when you execute the chore.

Click Apply to save your process list.

Closes the Chore Process List Editor dialog box.Close

4. To activate a chore to run on the set schedule, select a chore, and click Activate.

5. To deactivate a chore so that it no longer runs on schedule, select the chore, and click Deactivate.

Operation Guide 179

Chapter 7: Administering IBM Cognos TM1 Web

Page 180: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

6. To edit a chore, select a chore, and click Edit Chore .

IBM Cognos TM1 Web displays the Chore Process List Editor dialog box.

● Use the arrows to build and arrange a list of processes that run when you execute the chore.

● Click Apply to save your process list.

● Click Save to save your changes.

7. To run a chore, select a chore, and click Execute Chore .

Setting Client PropertiesTo review and set client properties:

Steps

1. In the Administration pane, click Client Properties.

IBM® Cognos® TM1® Web displays a list of clients you established on your TM1 server.

2. To display the properties for a client, click a client in the list.

IBM Cognos TM1 Web displays the property values for that client.

All but the Maximum # of Connections and Password Expiration properties are read-only.

3. To set the maximum number of connections that can be established on the TM1 server by the

selected client, highlight the Maximum # of Connections value and enter a new number.

4. To set the number of days that the clients password remains valid, highlight the Password

Expiration value and enter a new number.

A Password Expiration value of 0 means that the password does not expire.

5. Click Save to save the client property changes.

Setting Cube PropertiesYou can review and set cube properties.

Steps

1. In the Administration pane, click Cube Properties.

IBM® Cognos® TM1® Web displays a list of cubes available on your TM1 server.

2. To include control cubes in the list, select the Display Control Cubes check box. To exclude

control cubes from the list, clear the Display Control Cubes check box.

3. To view the properties for a cube, click a cube in the list.

IBM Cognos TM1 Web displays a box containing properties and corresponding values for the

selected cube. You can change the Load on Demand and Logging properties.

180 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 181: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

4. To change the value of a cube property, click the down arrow next to a property and select a

value.

5. Click Save to save your changes.

Setting Dimension PropertiesYou can review and set dimension properties.

Steps

1. In the Administration pane, click Dimension Properties.

IBM® Cognos® TM1® Web displays a list of dimensions on your TM1 server.

2. To display the control dimensions, select the Display Control Dimensions check box. To hide

the control dimensions, clear the Display Control Dimensions check box.

3. To view properties for a dimension, click a dimension in the list.

IBM Cognos TM1 Web displays the properties and associated values for the dimension. You

can change several dimension property values.

4. To change a property value for a dimension, click the down arrow next to a property and select

a new value.

5. Click Save to save your changes.

Changing Your PasswordAny user can change his own IBM® Cognos® TM1® Web password.

Steps

1. Click the Administration node in the left Navigation pane.

2. Click Change Password.

The Change User Password page opens.

3. Enter your current password in the Enter Current Password box.

4. Enter your new password in the Enter New Password box.

5. Enter your new password a second time in the Verify New Password box.

6. Click Save Changes to save your new password.

Configuring a Custom Homepage for IBM Cognos TM1 WebYou can configure a custom homepage for IBM® Cognos® TM1® Web to display a Websheet, cube

view, or a URL after users have successfully logged into IBM Cognos TM1 Web. This homepage

can provide users with a starting point for accessing and working with TM1 data. A homepage can

Operation Guide 181

Chapter 7: Administering IBM Cognos TM1 Web

Page 182: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

be configured globally for all IBM Cognos 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 Cognos TM1 Web and cannot be

closed by users. When configured, a Home link is displayed in the header area of IBM Cognos TM1

Web that allows users to easily return to the homepage.

An IBM Cognos TM1 Web homepage can be configured in one of the following two ways:

● Different homepage for different IBM Cognos 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 Cognos TM1 Web.

● Global homepage for all IBM Cognos TM1 Web users - Use the HomePageObject parameter

in the web.config file to configure a homepage that applies globally to all IBM Cognos TM1

Web users.

Note: Any homepage assignment you make with the Client Settings dialog can over-ride the global

setting in the web.config if you set AllowOverwrite=true in the HomePageObject parameter of the

web.config file.

Configuring Different Homepages for Individual UsersThe Client Settings dialog, in Architect and Server Explorer, configures a startup homepage for

different IBM Cognos TM1 Web clients (users). For example, you can assign one homepage for

IBM Cognos TM1 Web users in the Sales department and another homepage for users in the Finance

department.

Note: You can use the Client Settings dialog to assign homepages for specific users, over-riding the

global homepage setting for the HomePageObject parameter in the web.config file.

Steps

1. In Architect or Server Explorer, right click on the server and select Security, Clients/Groups.

The Clients/Groups dialog opens.

2. Click Settings.

The Client Settings dialog 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 IBM

Cognos TM1 Web Homepage dialog opens where you can select a reference to a Websheet

or cube view from the Application tree.

182 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 183: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

After selecting a Websheet or cube view reference, click OK to return to the Client Settings

dialog.

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 web.config file is set to AllowOverwrite=true. For details, see "Configuring IBM Cognos

TM1 Web Startup and Appearance Settings" (p. 196).

The available settings for controlling the appearance of the Navigation pane include:

● Include the Navigation Pane - Determines if the Navigation pane is displayed or not dis-

played when the selected client logs in to IBM Cognos TM1 Web.

● Open pane on Login - Sets the Navigation pane to display in the expanded mode when the

selected client logs in to IBM Cognos TM1 Web.

● Close pane on Login - Sets the Navigation pane to display in its minimized mode when the

selected client logs in to IBM Cognos TM1 Web.

● Save Client's Navigation Pane Settings - Determines if the personal settings for the Naviga-

tion pane are saved when the client logs out of IBM Cognos 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.

● 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.

● All Clients - Applies the same homepage setting to all TM1 clients.

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. The number of clients selected in the Subset Editor is summarized in the Client

Settings dialog.

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.

You have now configured a homepage for IBM Cognos TM1 Web. The selected IBM Cognos

TM1 Web clients will see the assigned homepage the next time they successfully log in to IBM

Cognos TM1 Web.

Operation Guide 183

Chapter 7: Administering IBM Cognos TM1 Web

Page 184: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Configuring a Global Homepage for All UsersThe HomePageObject parameter, in the web.config file, enables a global homepage that displays

for all IBM® Cognos® TM1®Web users.

Note: You can over-ride the global HomePageObject parameter by using the Client Settings dialog

to assign different homepages for individual TM1 clients. For details, see "Configuring Different

Homepages for Individual Users" (p. 182)

The HomePageObject parameter works for three types of objects:

● Cubeviewer

● Websheet

● URL

The homepage object displays after the user successfully logs in to IBM Cognos TM1 Web.

Using the HomePageObject Parameter

The HomePageObject parameter uses the following format:

<add key="HomePageObject" value="ObjectPath;Type=ObjectType;Description=ObjectTi-

tle;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 IBM Cognos TM1 Web Homepage to a Cube View

Use the following format to set a cube view as the homepage for IBM® Cognos® 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.

184 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 185: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● ViewName is the name of the cube view to display.

● Status is the public or private status of the cube view.

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:

<add key="HomePageObject" value="SalesCube$$Price$$Public;Type=cubeviewer;Description=MyStartCube;AllowOverwrite=true"/>

Setting a Global IBM Cognos TM1 Web Homepage to a Websheet

You can assign a Websheet as the IBM® Cognos® TM1® Web homepage, depending on how the

Excel file was added to TM1:

● Referenced Excel file - A Websheet that was added to TM1 as a referenced Excel file, outside

of TM1, and can be accessed with a UNC network path.

● Uploaded Excel file - A Websheet that was added to TM1 as an uploaded Excel file and copied

to the TM1 server.

Step to open a Websheet that references an Excel file outside of TM1

● 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

The complete HomePageObject parameter looks like this:

<add key="HomePageObject" value="//MySystem/Samples/classic_slice.xls;Type=websheet;Description=MyWebsheet;AllowOverwrite=true"/>

Steps to open a Websheet object that was uploaded to the TM1 server:

1. In Server Explorer, use the Properties pane to find the TM1 assigned name for the uploaded

Excel file.

Operation Guide 185

Chapter 7: Administering IBM Cognos TM1 Web

Page 186: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

User assigned name for an uploaded Excel file TM1 assigned name of an uploaded Excel file

2. Set the value parameter using the following format:

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=MyUploaded Websheet;AllowOverwrite=true" />

Setting a Global IBM Cognos TM1 Web Homepage to a URL

Use the following format to set the HomePageObject parameter to a URL:

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="homepage.html;Type=URL;Description=MyStartPage;AllowOverwrite=true"/>

● To set the homepage to a URL that points to a web site:

<addkey="HomePageObject" value="http://www.yahoo.com;Type=URL;Description=Yahoo;AllowOverwrite=true"/>

Modifying IBM Cognos TM1 Web Configuration ParametersThe Web.config administration file is an XML file that resides in the IBM® Cognos® TM1® Web

virtual directory. The parameters in this file control the following IBM Cognos TM1 Web features.

186 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 187: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● View node

● Administration node

● Web session timeout

● Cube Viewer page size

● Number of sheets to export from a Cube Viewer

● IBM Cognos TM1 Web startup and appearance settings

Here are the most common IBM Cognos TM1 Web parameters in the Web.config file that you can

change.

● MainTitleHeight - Sets the height of the main title bar.

● DisplayCustomToolbar - Set to Y or N to display or hide the TM1 Workflow toolbar.

● CustomToolbarURL - Establishes a target aspx file in the IBM Cognos TM1 Web virtual

directory. The aspx file defines a custom toolbar. For example, the file TM1WebPlanManTool-

bar.aspx defines the TM1 Workflow toolbar.

Note: In IBM Cognos TM1 Web 9.x, TM1WebPlanManToolbar.aspx is the only custom toolbar

TM1 supports.

● CustomToolbarHeight - Sets the height of the TM1 Workflow toolbar.

● NavTreeDisplayServerView - Hides or displays the Server View node in the Navigation tree.

● NavTreeDisplayAdministration - Hides or displays the Administration node in the Navigation

tree.

● SmartAxisEnabled - Set to true by default. This parameter, set to false, disables our newer

smartaxis automatic scale (and interval) calculator, and reverts back to the legacy mode.

Editing the Web.Config FileYou can edit the Web.config file.

Note: The web.cofig 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.

Steps

1. Log out of IBM® Cognos® TM1® Web.

2. Open the Windows Control Panel.

3. Click Administrative Tools, Internet Information Services.

The Internet Information Services window opens.

4. In the left Navigation pane, expand your local computer folders. Locate and select the IBM

Cognos TM1 Web virtual directory.

Operation Guide 187

Chapter 7: Administering IBM Cognos TM1 Web

Page 188: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

5. Locate the Web.config file in the Content pane, right-click the file, and click Open.

6. Edit the parameters and save your changes.

Note: If Web.config is set to read-only on your hard disk, IBM Cognos TM1 Web prompts

you to overwrite the file. Click Yes to confirm overwriting the file.

7. Log in to IBM Cognos TM1 Web to see the result of your edits.

Configuring TM1 Workflow ParametersThe following parameters in Web.config allow you to modify the appearance of the TM1® Workflow

toolbar in IBM Cognos TM1 Web.

Default Setting/

Description

Parameter

NDisplayCustomToolbar

Displays or hides the TM1 Workflow toolbar. The default is N.

Set this value to Y to display the TM1 Workflow toolbar.

TM1WebPlanManToolbar.aspxCustomToolbarUrl

Name of the custom toolbar executable. The only supported

toolbar is the default value shown here.

28CustomToolbarHeight

Height in pixels, of the TM1 Workflow toolbar.

TM1 WorkflowPM_ToolbarCaption

String caption on the TM1 Workflow toolbar.

120PM_ToolbarCaptionWidth

Width of the string caption on the TM1 Workflow toolbar cap-

tion.

ProcessPM_VersionCaption

Caption for the Process list in TM1 Workflow.

70PM_VersionCaptionWidth

Width of the Caption for the Version list in the TM1 Workflow

toolbar.

150PM_VersionListWidth

Width of the Version list in TM1 Workflow.

188 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 189: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Default Setting/

Description

Parameter

TaskPM_TaskCaption

Caption for the Task list in the TM1 Workflow toolbar.

50PM_TaskCaptionWidth

Width of the Task list caption in the TM1 Workflow toolbar.

200PM_TaskListWidth

Width of the Task list in the TM1 Workflow toolbar.

ActionPM_ActionCaption

Caption for the Action list.

55PM_ActionCaptionWidth

Width of the Action list caption.

120PM_ActionListWidth

Width of the Action list.

The default is an empty string.PM_AllTasksCaption

Caption for the All Tasks list.

30PM_AllTasksCaptionWidth

Width of the All Tasks list caption.

The default is an empty string.PM_StatusCaption

Caption for the Version Status button.

30PM_StatusCaptionWidth

Width of the Version status button caption.

The default is an empty string.PM_CustomizeCaption

Caption for the Customize button.

30PM_CustomizeCaptionWidth

Width for the Customize button caption.

The default is an empty string.PM_LoadCaption

Caption for the Load button.

Operation Guide 189

Chapter 7: Administering IBM Cognos TM1 Web

Page 190: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Default Setting/

Description

Parameter

30PM_LoadCaptionWidth

Width of the Load button caption.

Displaying the Custom ToolbarYou can display or hide a custom toolbar in IBM® Cognos® TM1® Web by modifying the parameter

DisplayCustomToolbar in Web.config.

Note: In TM1 9.x, TM1WebPlanManToolbar.aspx is the only custom toolbar supported.

Steps

1. Edit the Web.config file in the IBM Cognos TM1 Web virtual directory.

2. Locate the DisplayCustomToolbar parameter, which contains a value of N. The default value

of N hides the custom toolbar, as shown below:

<!--DisplayCustomToolbar: Y/N - Whether to displaycustom toolbar -->

<add key="DisplayCustomToolbar" value='N' />

3. To display the custom toolbar, change the DisplayCustomToolbar value to Y. Be sure to use

uppercase.

4. Save the Web.config file.

5. Click the Refresh button in your browser.

The custom toolbar displays in the banner at the top of the IBM Cognos TM1 Web page.

Displaying the Content of the Custom ToolbarIf you set the Web.config parameter DisplayCustomToolbar to Y, IBM® Cognos® TM1® Web exe-

cutes the code in the module indicated by the parameter CustomToolbarURL.

Note: The only supported setting for the CustomToolbarURL parameter is TM1WebPlanManTool-

bar.aspx. Do not change this setting.

<!-- CustomToolbarURL: URL to display contentfor custom toolbar -->

<add key="CustomToolbarUrl" value="TM1WebPlanManToolbar.aspx"/>

Changing the Height of the Custom ToolbarYou can change the height of a custom toolbar.

Steps

1. Edit Web.config in the IBM® Cognos® TM1® Web virtual directory.

190 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 191: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

2. Locate the CustomToolbarHeight parameter, which controls the display of the Server View

node. Note the value of 28 (in pixels).

<!-- CustomToolbarHeight: Height of custom toolbarsi n pixels -->

<add key="CustomToolbarHeight value="28" />

3. Change the number of pixels to change the height of the custom toolbar.

4. Save the Web.config file.

Displaying or Hiding the Views Node in the Navigation PaneYou can display or hide the Views node in the Navigation pane.

Steps

1. Edit Web.config in the IBM® Cognos® TM1® Web virtual directory.

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 Web.config.

5. Log in to IBM Cognos TM1 Web.

Now the Navigation pane displays without the View node.

Displaying or Hiding the Administration Node in the Navigation PaneYou can display or hide the Administration node in the Navigation pane.

Steps

1. Edit Web.config in the IBM® Cognos® TM1® Web virtual directory.

2. Locate the NavTreeDisplayAdministration parameter, which controls the display of the

Administration node. The default value of this parameter is Y, which displays the Administration

node in the Navigation pane.

<!--NavTreeDisplayAdministration: Y/N - Whether todisplay "Administration" node in navigation tree -->

<add key="NavTreeDisplayAdministration" value="Y"/>

3. To hide the Administration node, change the NavTreeDisplayAdministration value to N.

4. Save Web.config.

5. Log in to IBM Cognos TM1 Web.

The Navigation tree now displays without the Administration node:

Operation Guide 191

Chapter 7: Administering IBM Cognos TM1 Web

Page 192: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Changing the IBM Cognos TM1 Web Session TimeoutBy default, IBM® Cognos® TM1® Web applies a 120-minute session idle timeout. If you log in to

IBM Cognos TM1 Web, and IBM Cognos TM1 Web remains idle for 120 minutes, you are auto-

matically logged out.

Steps

1. Edit Web.config.

2. Locate the following code:

<!-- SESSION STATE SETTINGS

By default ASP.NET uses cookies to identify which requestsbelong to a particular session.

If cookies are not available, a session can be trackedby adding a session identifier to the URL.

To disable cookies, set sessionState cookieless="true".

-->

<sessionState

mode="InProc"

stateConnectionString="tcpip=127.0.0.1:42424"

sqlConnectionString="data source=127.0.0.1;Trusted_Connection=yes

cookieless="false"

timeout="120"

/>

3. Change the timeout value (in minutes).

4. Save Web.config.

5. Log in to IBM Cognos TM1 Web.

Unexpected timeouts

The default timeout parameter in web.config and Microsoft® IIS worker process is set at Web Session

Timeout=20 min, IdleConnectionTimeOutSeconds=120 sec, and IdleTimeout=20 min.

Timeouts can be configured at three different “levels” :

● TM1Web timeout settings: web.config, tm1web web app

● TM1® server timeout settings: tm1s.cfg

● Microsoft IIS settings for timeout of worker processes: IIS w3wp.exe + DefaultAppPool +

machine.cfg

The setting in the tm1s.cfg file applies at the server level, while the web.config applies to accessing

the virtual directory for TM1Web.

The IdleConnectionTimeOutSeconds will disconnect a user's TM1 session, while the timeout

parameter in the web.config only applies to a user's connection to the TM1Web website.

Unexpected timeouts may occur when the Default Parameter is changed or when the precedence

of settings results in unexpected behavior. The setting in the web.config file takes precedence over

192 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 193: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

idle timeout in IIS and machine.config. When timeout is missing in web.config then the setting from

machine.config takes precedence.

For best results, do not change the default settings. To prevent a TM1Web session from timing

out, if you do change the default setting, take into account your business requirements and the

precedence of timeout settings.

To diagnose a timeout problem, be sure a setting has been made in the tm1s.cfg. No timeout setting

means you never time out.

IdleConnectionTimeOut Seconds specifies a timeout limit for idle client connections in seconds.

For example, if you include the line IdleConnectionTimeOutSeconds=900 in tm1s.cfg, the server

disconnects idle client connections after 900 seconds.

You can use these techniques to adjust the timeout parameter in TM1, Microsoft IIS, and TM1Web:

1. Increase timeout IdleConnectionTimeOutSeconds (tm1s.cfg) from 900 sec to 7200 sec (= 120

min).

2. Increase timeout of IIS worker process from sec (=20 min) to 7200 sec (= 120 min) cscript

%SystemDrive%\Inetpub\AdminScripts\adsutil.vbs set W3SVC/AppPools/ApplicationPoolName

n

3. Increase timeout DefaultAppPool from default 20 min to 120 min.

4. Increase timeout TM1® Web Session (web.config) from default 20 min to 120 min.

5. httpRuntime executionTimeout="7200" (web.config)

6. Restart IIS after changing timeout settings.

Session timeouts immediately after logon or a short time later may also be caused by the default

setting in Microsoft IIS Version 6 webserver of Microsoft Windows® Server 2003.

To adjust this setting:

1. Change the default Maximum number of worker processes from 4 to 1. Select Start, Control

Panel, Administrative Tools, Internet Information Serves (IIS) Manager, Application Pool,

Default Application Pool (DefaultAppPool).

2. Right-click and select Properties, tab Performance, Web Garden:Maximum number of worker

processes .

Changing the Cube Viewer Page SizeBy default, the IBM® Cognos® TM1® Web Cube Viewer displays pages of TM1 data with 20 columns

and 100 rows, and includes the dimensions list in the row count.

Steps

1. Edit Web.config.

2. Locate the following code:

CubeViewerRowPageSize

Operation Guide 193

Chapter 7: Administering IBM Cognos TM1 Web

Page 194: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

CubeViewerColumnPageSize

3. Change the value for the row and/or column page size.

4. Save Web.config.

5. Log in to IBM Cognos 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 Cube ViewerBy default, the maximum number of sheets you can export from a Cube Viewer to a printer is 100.

You can configure IBM® Cognos® TM1® Web to export more sheets.

To set the maximum number of sheets to export from a Cube Viewer:

Steps

1. Edit Web.config.

2. Locate the following code:

MaximumSheetsForExport

3. Change the value for the maximum number of sheets to export.

4. Save Web.config.

5. Log in to IBM Cognos TM1 Web.

Adjusting the HttpRuntime ExecutionTimeout ParameterYou can adjust the IBM® Cognos® TM1® Web httpRuntimeexecutionTimeout parameter if IBM

Cognos TM1 Web displays the following error message when opening a large or complex Websheet:

Server Error in '/TM1Web' Application. Request timedout.

The executionTimeout parameter specifies the maximum number of seconds that a request, such

as opening a Websheet, is allowed to execute before being automatically shut down by Microsoft®

Internet Information Services (IIS).

Steps

1. Edit Web.config.

2. Locate the system.web section.

3. Add or edit the httpRuntime executionTimeout parameter as follows:

<httpRuntime executionTimeout="value"/>

where the format of value can be either seconds or HH:MM:SS.

194 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 195: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

If a value is not specified in Web.config, then the value in the Microsoft® .NET Framework

configuration file, Machine.config, is used. If no value is specified in either file, then the default

value for this parameter is 90.

4. Save Web.config.

5. Log in to IBM Cognos TM1 Web.

Setting the TM1ExcelServicePortNumber ParameterThe TM1ExcelServicePortNumber parameter specifies the port number at which the TM1® Excel

Service is listening. The TM1 Excel Service is an application that runs in the background to handle

IBM Cognos TM1 Web requests for converting Excel files into XML format.

You can edit the TM1ExcelServicePortNumber parameter in the Web.config file using the following

format:

<add key="TM1ExcelServicePortNumber" value="PortNumber"/>

where PortNumber must be set to a valid port number, as shown in the following example:

<add key="TM1ExcelServicePortNumber" value="4785"/>

Configuring the Login Page using the AdminHostName and TM1ServerNameParameters

The AdminHostName and TM1ServerName parameters control whether or not the IBM® Cognos®

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 Web.config 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 Web.config 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.

● If HostName is set to the name of a valid TM1 Admin Host, then IBM Cognos 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

Web.config file using the following format:

<add key="TM1ServerName" value="ServerName"/>

where ServerName can be one of the following values:

Operation Guide 195

Chapter 7: Administering IBM Cognos TM1 Web

Page 196: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● If ServerName is blank (default value), then the TM1 server prompt is displayed on the IBM

Cognos TM1 Web login page, as shown below.

● 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 TM1Web.config file. See "Running TM1 in

Secure Mode using SSL" in the IBM® Cognos® TM1® Operation Guide for more information.

After the user enters a valid User Name and Password, IBM Cognos TM1 Web will login to the

TM1 server specified by the TM1ServerName parameter in the Web.config 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 IBM Cognos TM1 Web Startup and Appearance SettingsThe following parameters in the web.config file control the appearance of the Navigation pane, tab

bar, and Websheet and Cubeviewer toolbars when users log in to IBM® Cognos® TM1® Web.

● NavTreeHidden

● NavTreeCollapsedOnStart

● HideTabBar

● HideWebsheetToolBar

● HideCubeviewerToolBar

These parameters are located in the appSettings section of the web.config file for IBM Cognos TM1

Web and apply globally to all users of IBM Cognos TM1 Web.

Note: For details on using the HomePageObject parameter to set a custom homepage, see "Config-

uring a Custom Homepage for IBM Cognos TM1 Web" (p. 181).

NavTreeHidden Parameter

The NavTreeHidden parameter determines if the Navigation pane displays when users log in to

IBM® Cognos® TM1® Web. This can be helpful if you are displaying a custom homepage for users

and you want to completely hide the Navigation pane.

The NavTreeHidden parameter uses the following format in the web.config 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 IBM Cognos TM1

Web.

196 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 197: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● If set to true, the Navigation pane will not be displayed when user's log in to IBM Cognos 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 web.config 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 IBM® Cognos® TM1® Web.

● If value is set to true, the Navigation pane will be collapsed when user's log in to IBM Cognos

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.

Example of HideTabBar parameter set to false

Operation Guide 197

Chapter 7: Administering IBM Cognos TM1 Web

Page 198: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

HideTabBar Parameter

The HideTabBar parameter determines if IBM® Cognos® TM1® Web can display multiple tabs

when a user opens multiple IBM Cognos 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.

The HideTabBar parameter uses the following format in the web.config 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 IBM

Cognos 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 web.config 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 IBM® Cognos® TM1® Web.

● If value is set to true, the Websheet toolbar will not display in IBM Cognos 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 web.config 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 IBM® Cognos® TM1® Web.

● If value is set to true, the Websheet toolbar will not display in IBM Cognos TM1 Web.

The AllowOverwrite option is not currently used for this parameter.

Using the CustomLink Parameter to Open Other URLs and Web PagesThe CustomLink parameter displays a link in the IBM® Cognos® TM1® Web toolbar that can open

a URL address or web page. You can configure this parameter with your own custom text and URL

198 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 199: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

for the link. When you click the link, the target of the URL opens in a new window using your

system's default web browser.

The default setting for this parameter is disabled - all the values for the parameter are set to blank.

This prevents the link from displaying on the toolbar.

<add key="CustomLink" value=";Description=;Url=;"/>

To configure the CustomLink parameter, edit the web.config file using the following format.

<add key="CustomLink" value="LinkTitle;Description=LinkTooltip;Url=LinkURL;"/>

where

● LinkTitle is the text that displays for the link in the toolbar.

● LinkTooltip is the help text that displays when you hover the mouse over the link.

● LinkURL is the URL that you want to open when you click the link.

For example:

<add key="CustomLink" value="IBM Web Site;Description=Openthe IBM Web Site;Url=http://www.ibm.com"/>

Note: You must follow standard character escape rules for XML when adding a URL to the XML-

based web.config file. For example, replace the & character with the &amp; escape sequence.

Configuring the IBM Cognos TM1 Web Virtual Cache DirectoryIBM® Cognos® TM1® Web requires a virtual directory, outside of the IBM Cognos TM1 Web

application directory, as a location for temporary files. The ExcelSheet and UserTempDir directories

are located under this directory and are used during the viewing of Websheets and the exporting

of Websheets and Cube Views from IBM Cognos TM1 Web.

By default, the IBM Cognos TM1 Web installation configures this virtual directory in the following

location:

C:\Inetpub\wwwroot\TM1WebEx

Note: This configuration does not typically require any changes, however, if necessary, you can

configure this setting using the UseSeparateVirtualCache parameter in the web.config file as follows:

<add key="UseSeparateVirtualCache" value="Y;Url=;AbsolutePath="/>

where the Url and AbsolutePath parameters must resolve to the same location.

● Url is the URL path to the virtual directory that you want IBM Cognos TM1 Web to use as

the cache directory.

The default is Url=http://<WebServerName>/TM1WebEx.

● AbsolutePath is the path to the physical directory that you want IBM Cognos TM1 Web to use

as the cache directory.

The default is AbsolutePath=C:\Inetpub\wwwroot\TM1WebEx.

Operation Guide 199

Chapter 7: Administering IBM Cognos TM1 Web

Page 200: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Important: The UseSeparateVirtualCache parameter must be set to either Y or not used at all. If

this parameter is excluded from the web.config file, IBM Cognos TM1 Web uses TM1WebEx as

the default location for the virtual cache directory.

Warning: IBM Cognos TM1 Web will not work if the UseSeparateVirtualCache parameter is set

to N.

Controlling Chart Scaling and Increments with the SmartAxisEnabled ParameterThe SmartAxisEnabled parameter controls the automatic scale and increment settings of the X and

Y-axis in IBM® Cognos® TM1® Web charts.

When this parameter is enabled (default), IBM Cognos TM1 Web uses a new enhanced display

process that automatically adjusts the axis scale and increment settings for charts. If disabled, IBM

Cognos TM1 Web displays charts using the legacy automatic scaling that was available in the 9.0

version of IBM Cognos TM1 Web.

To enable this parameter and use the new enhanced IBM Cognos TM1 Web 9.1.x charting, edit

the web.config file as follows:

<add key="SmartAxisEnabled" value="true" />

To disable this parameter and use the IBM Cognos TM1 Web 9.0 charting, edit the web.config file

as follows:

<add key="SmartAxisEnabled" value="false" />

Enabling the Websheet Paging ToolbarThe Websheet paging feature includes a toolbar in IBM® Cognos® TM1® Web that provides easier

navigation in Websheets that contain a large number of rows. This toolbar allows you to move

page by page through a range of rows in the Websheet or jump to a range of rows that you specify.

The Websheet paging toolbar is disabled by default. Use the WebsheetPaging parameter in the

web.config file to enable and configure the Websheet paging toolbar.

Steps

1. Open the web.config file and locate the <!-- Websheet Paging Settings --> line.

2. To enable the Websheet paging feature, set the value of the WebsheetPaging parameter to

Enabled=true as follows:

<!-- Websheet Paging Settings -->

<add key="WebsheetPaging" value="Enabled=true;PageSize=100"/>

3. Set the approxiamte number of Websheet rows that you want viewable in IBM Cognos TM1

Web by configuring the PageSize parameter. For example:

<add key="WebsheetPaging" value="Enabled=true;PageSize=50"/>

4. To disable the Websheet paging feature, set the value of the WebsheetPaging parameter to

Enabled=false as follows:

200 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 201: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

<!-- Websheet Paging Settings -->

<add key="WebsheetPaging" value="Enabled=false;PageSize=100"/>

5. Save and close the web.config file.

Setting Web PermissionsWhen you install IBM® Cognos® TM1® Web, the installation automatically configures the required

anonymous access and permission settings for the IBM Cognos TM1 Web directories. These per-

mission settings allow users to open Websheets and Cube Viewer charts, or export data to Excel

from the IBM Cognos TM1 Web Cube Viewer without being prompted for a user name and pass-

word or limited by other permission restrictions.

If you need to verify or reset the anonymous access settings on your IBM Cognos TM1 Web server,

perform these tasks:

● Modify the IBM Cognos TM1 Web virtual directory properties to allow anonymous access.

● Set security for IBM Cognos TM1 Web folders.

If you use a directory other than the default directory, be sure the Administrator; Authenticated

Users; IIS_WPG; and System have full control and that Internet Guest Account and Users have

read/execute permissions. If the Windows permissions on this directory are restricted, the TM1

Web client may not be accessible to all users.

Modifying the IBM Cognos TM1 Web Virtual Directory to Allow AnonymousAccess

The IBM® Cognos® TM1® Web installation automatically configures the IBM Cognos TM1 Web

virtual directory to allow anonymous access.

To verify or reset anonymous access for the IBM Cognos TM1 Web virtual directory, follow these

steps:

Steps

1. Open the Windows Control Panel.

2. Click Administrative Tools, Internet Information Services.

The Internet Information Services window opens.

3. Right-click TM1Web and select Properties.

The Properties dialog box opens.

4. Click the Directory Security tab.

5. Click Edit in the Anonymous Access and Authentication Control section.

The Authentication Methods dialog box opens.

6. Write down the user name of the anonymous access account; you will need this name in a later

step.

Operation Guide 201

Chapter 7: Administering IBM Cognos TM1 Web

Page 202: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

7. Click OK to close the Authentication Methods dialog box.

8. Click OK to close the Properties dialog box.

Setting Security for IBM Cognos TM1 Web FoldersIBM® Cognos® TM1® Web requires that user access is set up for the following IBM Cognos TM1

Web folders:

● ExcelSheet

● UserTempDir

● TempCharts

The required security settings are automatically configured for these folders during the IBM Cognos

TM1 Web installation.

To verify or reset the security for these IBM Cognos TM1 Web folders:

Steps

1. In Windows® Explorer, navigate to the TM1WebEx directory on your Web server.

Note: If you accepted the default location during installation, the directory for ExcelSheet and

UserTempDir is C:\Inetpub\wwwroot\TM1WebEx. TempCharts is put in the TM1Web folder.

2. Right-click the ExcelSheet folder and select Properties.

The ExcelSheet Properties dialog box opens.

3. Click the Security tab.

4. Click the Add button.

The Select Users or Groups dialog box opens.

5. Select a location:

● Click Locations.

● Select the location where the TM1 Excel Service is running.

● Click OK.

6. In the Enter the object names to select box, enter the anonymous user name that you noted in

the Authentication Methods dialog box, see "Modifying the IBM Cognos TM1 Web Virtual

Directory to Allow Anonymous Access" (p. 201).

7. Click Check Names to verify that the user name is valid, and click OK to close the Select Users

or Groups dialog box.

8. Click the Advanced button in the ExcelSheet Properties dialog box.

The Advanced Security Setting for ExcelSheet dialog box opens.

9. Click the Permissions tab.

202 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 203: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

10. Select the anonymous Internet Guest Account and click Edit.

The Permission Entry for ExcelSheet dialog box opens.

11. Set all permissions from List Folder/Read Data through Read Permissions to Allow.

12. Click OK.

13. Repeat steps 2 through 12 to set up security for the UserTempDir and TempCharts folders.

Performing Web Folder MaintenanceIBM® Cognos® TM1® Web uses the following two Web folders for temporary files:

● Excelsheet - When you view an Excel sheet, IBM Cognos TM1 Web writes several temporary

files to this folder.

● Tempcharts - When you generate a chart from a Cube Viewer, IBM Cognos TM1 Web writes

a temporary file to this folder.

These folders are located under the IBM Cognos TM1 Web directory. If you accepted the default

location during installation, the default IBM Cognos TM1 Web directory is C:\Inetpub\wwwroot\

TM1Web.

For best practice, monitor the Excelsheet and Tempcharts folders, and delete their contents period-

ically when the folders become full.

Using IBM Cognos TM1 Web LoggingIBM® Cognos® TM1® Web administrators can use the following two log files for status and trou-

bleshooting of IBM Cognos TM1 Web. Severity Levels help organize messages:

● Message Severity Levels for IBM Cognos TM1 Web Logging

● IBM Cognos TM1 Web Log

● TM1 Excel Services Log

Message Severity Levels for IBM Cognos TM1 Web LoggingThe logging process for IBM® Cognos® TM1® Web and TM1 Excel Services categorizes log messages

into the following three severity levels. These levels are also used in the logging properties file to

configure logging to a specific level.

DescriptionParameter

Detailed, technical messages that are useful when TM1 customer support

or development engineering need to debug the application.

DEBUG

When logging is configured to this level, DEBUG, INFO, and ERROR

messages are logged.

Operation Guide 203

Chapter 7: Administering IBM Cognos TM1 Web

Page 204: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

Informational messages that highlight the progress of the application and

report normal transitions within the application.

INFO

When logging is configured to this level, INFO and ERROR messages are

logged.

An error condition of which you should be aware. Action should be taken

to fix or report the issue to TM1 customer support.

ERROR

When logging is configured to this level, only ERROR messages are logged.

IBM Cognos TM1 Web LogThe IBM® Cognos® TM1® Web log records messages for IBM Cognos TM1 Web activity and errors.

The log file is an ASCII text file that you can open in any text editor, such as Microsoft® Windows®

Notepad.

Configuring and Enabling IBM Cognos TM1 Web Logging

The configuration for IBM® Cognos® TM1® Web logging is stored in a logging properties section

of the TM1 Web.config file. You can edit the properties in this file to adjust the logging message

level.

Logging is enabled when the logging properties in the web.config file are correctly configured to

turn on logging. Logging for IBM Cognos TM1 Web is configured by default when IBM Cognos

TM1 Web is installed.

The web.config file is installed in the TM1 Web install_directory. If you installed IBM Cognos TM1

Web to the default installation location, the web.config file is located in the directory C:\Inetpub\

wwwroot\TM1Web.

Note: The default web logging configuration is intended for every-day use and does not typically

require adjustment. For assistance if you need to configure the logging properties for troubleshooting

purposes, see the IBM CognosResource Center (http://www.ibm.com/software/data/support/cognos_

crc.html).

The following is a sample of the logging properties section in the web.config file.

<log4net>

<root>

<level value="ERROR" />

<appender-ref ref="LogFileAppender" />

</root>

<appender name="LogFileAppender" type="log4net.Appender.RollingFileAppender">

<file value="log\tm1web_err.log" />

<appendToFile value="true" />

<datePattern value="yyyyMMdd" />

<rollingStyle value="Date" />

<filter type="log4net.Filter.LevelRangeFilter">

204 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 205: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

<acceptOnMatch value="true" />

<levelMin value="INFO" />

<levelMax value="FATAL" />

</filter>

<layout type="log4net.Layout.PatternLayout">

<conversionPattern value="%date [%thread] %-5level%logger - %message%newline" />

</layout>

</appender>

</log4net>

Where:

The message level is indicated by: <level value="ERROR" />

The log file name is indicated by: <file value="log\tm1web_err.log" />

the minimum and maximum message level ranges are indicated by:

<levelMin value="INFO" />

<levelMax value="FATAL" />

Steps to change the logging message level:

1. Open the web.config file in a text editor, such as Microsoft Windows Notepad.

2. Locate the following section of code:

<level value="ERROR" />

3. Change the level to one of the valid values; DEBUG, INFO, or ERROR.

For example, to change the message level to DEBUG, edit this line as follows:

<level value="DEBUG" />

4. Locate the settings for the levelMin and levelMax parameters.

<levelMin value="INFO" />

<levelMax value="FATAL" />

Adjust the values for the levelMin and levelMax parameters to a range that includes the level

you want to log.

For example, to log DEBUG level messages, change the levelMin parameter to DEBUG.

<levelMin value="DEBUG" />

<levelMax value="FATAL" />

5. Save and close the file.

Viewing the IBM Cognos TM1 Web Log File

The IBM® Cognos® TM1® Web installation configures IBM Cognos TM1 Web logging to write

messages to the tm1web_err.log file in the following location:

<TM1Web_install_directory>\log

If you installed IBM Cognos TM1 Web to the default installation location, then the tm1web_err.log

file is located in the following directory:

Operation Guide 205

Chapter 7: Administering IBM Cognos TM1 Web

Page 206: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

C:\Inetpub\wwwroot\TM1Web\log

For backup purposes, a copy of the tm1web_err.log file is renamed and saved on a daily basis using

the following naming convention:

tm1web_err.log<year><mm><dd>

For example, tm1web_err.log20070116.

Steps

1. Locate the tm1web_err.log file in the TM1Web install directory\log\ directory.

2. Open and view the file with a text editor, such as Microsoft Windows Notepad.

Each line in the log file represents one unique message, arranged in the following format:

2007-01-17 11:13:36,916 [2600] ERROR Cognos.TM1.Web.PageTM1WebpageUtils- <Chores> not localized

Where:

2007-01-17 11:13:36,916 is the date and time

[2600] is the thread ID

ERROR is the message level

Cognos.TM1.Web.PageTM1WebpageUtils is the sub-component name

<Chores> not localized is the message text.

TM1 Excel Services LogThe TM1® Excel Services log records messages for the TM1 Excel Service - an application that runs

in the background to handle IBM Cognos TM1 Web requests for converting Excel files into XML

format.

The TM1 Excel Services log file is an ASCII text file that you can open in any text editor, such as

Microsoft® Windows® Notepad.

Configuring TM1 Excel Services Logging

The configuration for TM1® Excel Services logging is stored in the TM1ExcelService.exe.config

file. You can edit this file to adjust the logging message level.

The TM1ExcelService.exe.config file is located in the TM1install_dir\bin directory. If you installed

TM1 to the default installation location, then this file is located in C:\Program Files\Cognos\TM1\

bin.

Note: The default logging configuration is intended for every-day use and does not typically require

adjustment. Contact TM1 customer support for assistance if you need to configure the

TM1ExcelService.exe.config file for troubleshooting purposes.

A sample of the TM1ExcelService.exe.config file is shown:

<log4net>

<root>

<level value="ERROR" />

<appender-ref ref="LogFileAppender" />

206 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 207: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

</root>

<appender name="LogFileAppender" type="log4net.Appender.RollingFileAppender">

<file value="tm1excelservice_err.log" />

<appendToFile value="true" />

<datePattern value="yyyyMMdd" />

<rollingStyle value="Date" />

<filter type="log4net.Filter.LevelRangeFilter">

<acceptOnMatch value="true" />

<levelMin value="INFO" />

<levelMax value="FATAL" />

</filter>

<layout type="log4net.Layout.PatternLayout">

<conversionPattern value="%date [%thread] %-5level%logger - %message%newline" />

</layout>

</appender>

</log4net>

Where:

The message level is indicated by: <level value="ERROR" />

The log file name is indicated by: <file value="tm1excelservice_err.log" />

the minimum and maximum message level ranges are indicated by:

<levelMin value="INFO" />

<levelMax value="FATAL" />

Steps to change the logging message level

1. Open the web.config file in a text editor, such as Microsoft® Windows® Notepad.

2. Locate the following section of code

<level value="ERROR" />

3. Change the level to one of the valid values; DEBUG, INFO, or ERROR.

For example, to change the message level to DEBUG, edit this line as follows:

<level value="DEBUG" />

4. Locate the settings for the levelMin and levelMax parameters.

<levelMin value="INFO" />

<levelMax value="FATAL" />

Adjust the values for the levelMin and levelMax parameters to a range that includes the level

you want to log.

For example, to log DEBUG level messages, change the levelMin parameter to DEBUG.

<levelMin value="DEBUG" />

<levelMax value="FATAL" />

5. Save and close the file.

Operation Guide 207

Chapter 7: Administering IBM Cognos TM1 Web

Page 208: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Enabling TM1 Excel Services Logging

Logging for TM1® Excel Services is configured by default when you install IBM® Cognos® TM1®

Web. The installation places the TM1ExcelService.exe.config file and the TM1 Excel Services file,

TM1ExcelService.exe, into the TM1install_dir\bin directory.

Logging is started when TM1 Excel Services starts up and detects the TM1ExcelService.exe.config

file in the same directory.

Viewing the TM1 Excel Services Log File

The IBM® Cognos® TM1® Web installation configures TM1 Excel Services logging to write messages

to a file called tm1excelservice_err.log. On a daily basis, this file is renamed and archived using the

following naming convention:

tm1excelservice_err.log<year><mm><dd>

For example, tm1excelservice_err.log20070116.

Steps

1. Locate the tm1excelservice_err.log file in the TM1install_dir\bin directory.

2. Open and view the file with a text editor, such as Microsoft® Windows® Notepad.

Each line in the file represents one unique message, arranged in the following format:

2007-01-16 10:59:40,846 [3156] ERROR Cognos.TM1.ExcelServices.TM1ExcelService- 'PDFcamp Printer' printer

Where:

2007-01-16 10:59:40,846 is the date and time

[3156] is the thread ID

ERROR is the message level

Cognos.TM1.ExcelServices.TM1ExcelService is the TM1 sub-component name

'PDFcamp Printer' printer is the message text.

Multiple Skin Support in IBM Cognos TM1 WebIBM® Cognos® TM1® Web includes a feature for changing the appearance or skin of the TM1 Web

user interface. This section describes how to configure TM1 Web to use one of the pre-defined IBM

Cognos 8 skins and provides instructions on how to create and use a custom skin.

OverviewIBM® Cognos® TM1® 9.4 updated TM1 Web to use the Cognos 8 corporate-style skin similar to

other IBM Cognos 8 applications. However, TM1 Web did not support an easy way to switch to

the other pre-defined IBM Cognos 8 skins or provide a way to use custom skins.

TM1 Web administrators and application developers can now use the IBM Cognos 8 skins and

related features with TM1 Web as follows:

208 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 209: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Easily configure TM1 Web to use any of the six built-in IBM Cognos 8 skins.

● Create and use custom skins for TM1 Web.

● Use the TM1 Web URL API to dynamically set the skin for applications that use the TM1 Web

URL API.

ConfigurationEach skin for IBM® Cognos® TM1® Web is defined by a Cascading Style Sheet (css) file and a set

of supporting images. These files are installed when you install IBM Cognos TM1 Web. TM1 Web

is configured to use the corporate style skin as the default skin.

The css file for each skin is given a unique name and installed to the location:

<TM1 Web installation>\css

The supporting images for a skin are installed to a folder using the same name as the skin in the

following location:

<TM1 Web installation>images\skins\skin name

When a skin is set, TM1 Web first checks to see if the corresponding css file exists in the /css sub-

directory. If the file does not exist, the specified skin will not be used. TM1 also verifies whether

there is a corresponding sub-directory under the /images/skins directory that contains the images

for the specified skin. If this directory does not exist, the images of the default skin will be used

instead.

You can select which skin to use by configuring the Web.config file or with the TM1 Web URL

API, depending on how you are using TM1 Web.

Using the Web.config File to Set the TM1 Web Skin

To set the skin for the entire IBM® Cognos® TM1® Web application, set the skin name using the

CustomStyle parameter in the Web.config file.

Steps

1. Open the Web.config file in a text editor.

2. Locate the line containing the CustomStyle parameter.

3. Enter a skin name for the value of the parameter. For example:

<add key="CustomStyle" value="classic;AllowOverwrite=true"/>

For backward compatibility, this value can also include a .css extension and the css directory

name. For example:

<add key="CustomStyle" value="classic.css;AllowOverwrite=true"/>

<add key="CustomStyle" value="css/classic.css;AllowOverwrite=true"/>

You can use one of the following predefined skin names.

● corporate

Operation Guide 209

Chapter 7: Administering IBM Cognos TM1 Web

Page 210: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Classic

● Business

● Contemporary

● Modern

● Presentation

4. Save and close the Web.config file.

Note: If the file contains multi-byte characters, you must save the file in UTF-8 format.

5. Log in to TM1 Web.

TM1 Web opens using the selected skin.

Using the TM1 Web URL API to Set a TM1 Web Skin

If you are using the IBM® Cognos® TM1® Web URL API to show TM1 Web objects, such as the

Cubeviewer, Websheet or navigation tree, you can change the skin by using the UserStyle

parameter in the URL query string. Using this parameter, each user can overwrite the default skin

for their session and each TM1 Web object in that session will use that same skin.

Note: The TM1 Web URL API can change the skin only if the AllowOverwirte property is set to

true, in the Web.config file.

Steps

1. In the Web.config file, edit the CustomStyle parameter to set AllowOverwrite to true. This

setting allows users of the TM1 Web URL API to change the skin for their session.

<add key="CustomStyle" value="classic;AllowOverwrite=true"/>

2. Save and close the Web.config file.

3. Add the UserStyle parameter to your TM1 Web URL API query string using the following

format:

&UserStyle=SkinName

Replace SkinName with one of the following predefined values.

● Corporate

● Classic

● Business

● Contemporary

● Modern

● Presentation

For example, the following URL string opens a TM1 Web cube view using the business skin.

210 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 211: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

http://WebServerName/TM1Web/TM1WebMain.aspx?action=OpenObject&type=Cubeviewer&value=plan_BudgetPlan$$plan_budget_input&UserStyle=business

Creating Your Own Custom Skins for TM1 WebYou can create and use your own custom skin with IBM® Cognos® TM1® Web by creating your

own Cascading Style Sheet (css) file and related image files.

Steps

1. In the <TM1 Web installation>\css directory, copy and rename an existing css file to your

own file name.

For example, copy business.css to newskin.css.

2. In the <TM1 Web installation>\images\skins\ directory, copy one of the existing skin folders,

including all of its sub-folders, to your own folder using the same name as the css file that you

created.

For example, copy the ...\images\skins\business folder to ...\images\skins\newskin.

3. Edit the content of your custom css file. Make sure that any references to image files point to

the custom skin folder that you created under ...\images\skins\.

4. Add or edit the image files in your custom skin folder.

5. Open the Web.config file and edit the value for the CustomStyle parameter value so it includes

the name of your custom skin. For example:

<add key="CustomStyle" value="newskin;AllowOverwrite=true"/>

6. Save and close the Web.config.

7. Log in to TM1 Web.

TM1 Web opens using the custom skin you created.

Operation Guide 211

Chapter 7: Administering IBM Cognos TM1 Web

Page 212: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

212 IBM Cognos TM1

Chapter 7: Administering IBM Cognos TM1 Web

Page 213: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 8: TM1 Security Overview

IBM® Cognos® TM1® security features enable you to control who logs in to your IBM Cognos

TM1® server, and what objects those users are allowed to access.

AuthenticationWhen you install the TM1® server, you can select one of these authentication methods.

● TM1 Authentication - TM1 server asks you for a user name and password, and validates the

login information against the security cube login information.

● Integrated Login - Microsoft® Windows® performs the TM1 authentication.

● LDAP Authentication - TM1 server asks you for a user name and password, and validates the

login information against an external LDAP server.

After you install the TM1 server, you can change the authentication method by changing the

parameters in the TM1 configuration files.

TM1 AuthenticationWith TM1® authentication, the TM1 server checks the user name and password against the user

names and passwords in the TM1 database.

Standard TM1 Security

Clients TM1 Server

Attempt to Establish a Connection

Ask for a User Name and Password

Supply a User Name and Password

Establish Connection

TM1 ArchitectTM1 PerspectivesTM1 Web Client

Check Nameand Password

Licensed Materials – Property of IBM213© Copyright IBM Corp. 2007, 2011.

Page 214: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Integrated LoginWith Integrated Login, TM1® uses the Microsoft® Windows® network authentication to access

your TM1 data. After you log in to your Windows workstation, you can access TM1 without

entering a user name and password again.

Integrated Login is supported on Windows only. You cannot use Integrated Login to access a UNIX®

TM1 server.

Integrated Login

Clients TM1 Server

(2) Attempt to Establish a TM1 Connection

(3) Return Windows Network Identity

(4) Supply Windows Identity as a Log In request

(5) Establish Connection

TM1 ArchitectTM1 PerspectivesTM1 Web Client

Check Name

Windows

User supplies auser name,

password, and

Authentication

Windows domainname whilelogging into aWindowsworkstation

(1) Windows Login Completed

WindowsDomain

Controller

LDAP AuthenticationWith LDAP authentication, an LDAP security service that is external to TM1® authenticates a login

(as of TM1 version 8.2.2). You can add, modify, and delete user security information from one

location - the LDAP server or Windows Active Directory.

Authentication using LDAP

TM1

(2) TM1 logs into LDAP with a

User Interface

(1) User Supplies nameand password

(8) TM1 logs in the userand gives the user accessto objects on the server.

Server

well-known name and password.

(3) LDAP acknowledges asuccessful login using the

(4) Lookup - TM1 passes thename to LDAP

(5) LDAP returns a distinguishedname from its database that

(6) TM1 passes the distinguishedname and the user's password

(7) LDAP acknowledges asuccessful login using the

LDAPServer(ActiveDirectory,Netscape,etc.)

well-known name and password.

corresponds to the user'srequested name.

to LDAP.

user-supplied name and password.

214 IBM Cognos TM1

Chapter 8: TM1 Security Overview

Page 215: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

TM1 Object SecurityAs the TM1® administrator, you can control access to TM1 objects by assigning specific levels of

object security to TM1 groups.

Suppose you have a group named Executives in your TM1 database. You want these executives to

review the company budget summary data, which is stored in the BudSummary cube in your TM1

database. You can use TM1 to assign the Executives group Read privileges to the BudSummary

cube.

You set TM1 access control the same way for any of the products in the TM1 suite. For example,

if users in the Executives group have Read access to the BudSummary cube when they run TM1

Perspectives, they also have Read access to that cube when they run the TM1 Web client.

For more information about the procedures required to set security for TM1 objects, see the IBM®

Cognos® TM1® Developer Guide.

Operation Guide 215

Chapter 8: TM1 Security Overview

Page 216: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

216 IBM Cognos TM1

Chapter 8: TM1 Security Overview

Page 217: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 9: ETLDAP Utility

The ETLDAP utility allows you to move information from your LDAP (Lightweight Directory

Access Protocol) directory to IBM® Cognos® TM1®. You can use ETLDAP to add LDAP users to

TM1 when using TM1 with Integrated Login and LDAP authentication.

Note: You can only use the ETLDAP utility to add new LDAP users to TM1. ETLDAP does not

modify, update or delete existing users in TM1.

ETLDAP Utility OverviewETLDAP, 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@com-

pany.com 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, 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® Cognos® TM1® server is configured to

use IBM® Cognos® Access Manager (CAM) authentication.

Using ETLDAPHere are the major steps involved in using ETLDAP.

❑ Modify LDAP Attributes

❑ Run ETLDAP

❑ Configure the LDAP Login Parameters

❑ Build an LDAP Query

Licensed Materials – Property of IBM217© Copyright IBM Corp. 2007, 2011.

Page 218: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

❑ Connect to the IBM® Cognos® TM1® server.

❑ Map LDAP Attributes to TM1 Fields

❑ Export LDAP Information to TM1

❑ Update TM1 with new LDAP users

Modifying LDAP AttributesIn some cases, the value of an attribute you retrieve from an LDAP directory does 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 is added to a single TM1 'Engineering' group. Any other

group value remains unchanged.

// The stringFilter class provides the abilityto transformstrings

// which are read from the LDAP database before theyare inserted into // TM1's datastore.

// To implement this feature, create a class which extendsstringFilter

// and contains a method 'filterString' with the followingsignature:

//

// String filterString(String attrName, String value)

//

//

public class myStringFilter extends stringFilter

{

public String filterString(String attrName, String value)

{

if (attrName.equals("ou"))

{

if ( (attrName.equals("R&D")) ||

218 IBM Cognos TM1

Chapter 9: ETLDAP Utility

Page 219: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

(attrName.equals("Quality Assurance")) ||

(attrName.equals("Documentation")) )

return "Engineering";

else

return value;

}

else

return value;

}

}

After you write and compile the Java™ code, put the class somewhere in your Classpath, and enter

its name in the Class Name field of the Options dialog on the Edit menu.

Running ETLDAPYou can run ETLDAP from Windows or the DOS command prompt.

Running ETLDAP from Windows

Click Start, Programs, IBM Cognos, TM1, Administration, ETLDAP.

The LDAP Load Tool dialog box opens.

The following table describes the elements in the LDAP Load Tool dialog box.

DescriptionField or Button

Displays the LDAP node at which the search originates. ETLDAP

does not search for entries above this level in the tree.Search DN

Displays the query string that filters the entries in the directory and

generates the matching records.Filter

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.

Attributes

Note: The attributes are for display purposes only.

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.

Search Scope

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.

Results Table

Operation Guide 219

Chapter 9: ETLDAP Utility

Page 220: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionField or Button

Performs the search using the parameters you select.Search Button

Exports the displayed set of users to TM1 based on the settings in the

Options dialog box.

Export Button

Running ETLDAP from DOS

You can run ETLDAP from a DOS command window, with command-line parameters.

Steps

1. Click Start, Programs, Accessories, Command Prompt.

2. Enter the following command line:

java etldap options

TM1® supports these command-line parameters.

DescriptionParameter

Passes the name of a saved session file to load all configuration settings

from a previous session.

-f filename

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® Cognos® TM1® server, an

error message is written to the log file and the session is terminated.

Runs ETLDAP in command-line mode with no user interface. Requires

the -f option.

-batch

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.

-secure

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 speci-

fying the '-secure' option. This would insure that the passwords were

only available for the short period of time it takes for the utility to initial-

ize.

Displays online Help for these command-line parameters.-help

220 IBM Cognos TM1

Chapter 9: ETLDAP Utility

Page 221: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Configuring the LDAP Login ParametersYou can configure the LDAP login parameters.

Steps

1. In the LDAP Load Tool dialog box, click File, Connect.

2. Enter the following host and user information.

DescriptionFieldPanel

Enter the host name or IP address of the

machine where the LDAP server is running.HostHost Info

The port on which the LDAP server is running.

If a port is not specified, 636 is used. 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

of port 636

Port

ETLDAP will most likely ignore the version

number. Most LDAP servers support version

2 or version 3 type connections, ETLDAP does

use any functionality specific to either version.

Version

Determines whether the communication

between the LDAP server and ETLDAP hap-

pens over a secure encrypted channel. Unless

you are viewing secure information over an

insecure network, leave this option turned off.

SSL 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.

Anonymous option

Operation Guide 221

Chapter 9: ETLDAP Utility

Page 222: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionFieldPanel

In many cases, your LDAP directory prevents

Anonymous users from accessing or modifying

data. In this case, you may need a Distin-

guished Name (DN) and password to complete

the extraction of your LDAP security informa-

tion.

User DSNUser Info

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=Blodget.com

Enter a password that corresponds to the User

DN.Password

3. Click Test.

If you successfully connect to the LDAP server, the status bar displays the Connection Succeeded

message in green.

If you do not connect to the LDAP server, the status bar displays an error message in red.

4. Click OK.

You have established a connection to your LDAP server with the parameters you specified.

Understanding the Elements of an LDAP QueryAn LDAP query consists of four major elements: Search DN, Filter, Scope, and Attributes.

● 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

222 IBM Cognos TM1

Chapter 9: ETLDAP Utility

Page 223: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● ( ) 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.

Search base: o=Applix.com

o: Applix.com

ou: People ou: Groups

cn: Rob Smithuid: rsmith cn: Jill Benson

uid: jbenson

Scope: One

Scope: Sub

● 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.

Operation Guide 223

Chapter 9: ETLDAP Utility

Page 224: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Building an LDAP QueryYou must specify the following steps when building an LDAP Query.

Steps

1. Specify the Search DN, Filter String, Attributes, and Scope for your query.

2. Click Search.

If you did not make any syntax errors or create a filter string that does not match any records

in the directory, you should see a list of entries in the table. A status message indicates how

many records match your search requirements.

3. Examine the result set.

● Does it include names 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 TM1 ServerFollow these steps if you want to connect to the IBM® Cognos® TM1® server.

Steps

1. Click Edit, Login, TM1.

2. Enter the following server information:

DescriptionField

The machine name of the server on which your TM1 Admin Server

is running.Host

Enter the port number configure which the admin server will use.

The default is 5498SSL port

224 IBM Cognos TM1

Chapter 9: ETLDAP Utility

Page 225: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionField

The name of the TM1 server to which you want to connect.Server

Click Server and then the Browse button to select a server from the

Server list.

The name of a user with Admin privileges on the target TM1 server.Username

The password of the admin user.Password

3. Click Test.

If the connection is successful, the status bar displays the Connection Succeeded message in

green.

If the connection fails, the status bar displays an error message in red.

4. Click OK.

Mapping LDAP Attributes to TM1 FieldsLDAP 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 TM1® fields manually. You should be familiar with the LDAP schema.

Steps

1. Click Edit, Mapping, TM1.

The TM1 Mapping dialog box opens.

2. For each required (red) TM1 field, select an LDAP schema attribute.

For each user, TM1 requires a unique name and group name. For example, you could map the

name attribute in your LDAP schema to the TM1 user, and map the department attribute to

the TM1® group.

3. Click OK.

Specifying the ETLDAP Export OptionsYou can specify the ETLDAP export options.

Steps

1. Click Edit, Options.

The Options dialog box opens.

2. Select Enable Integrated Login.

3. Enter the realm name that contains the users you want to transfer.

Operation Guide 225

Chapter 9: ETLDAP Utility

Page 226: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

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.

5. Set Maximum Search Results and Search Time Limit to 0.

6. Click OK.

Exporting LDAP Information to TM1You can export LDAP information to TM1®.

Steps

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

TM1. ETLDAP randomly generates the TM1 user passwords and adds them to the TM1

database.

Note: If you use Integrated Login, TM1 users do not use the TM1 passwords, and you do not

have to coordinate passwords between TM1 and Windows. If you do not use Integrated Login,

TM1 users must change their password during their first login session. For details, see Integrated

Login.

Updating TM1 with New LDAP UsersWhen 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 TM1® database.

After using ETLDAP to initially load LDAP users into TM1, you can then only use the tool to

retrieve and add new LDAP users that do not already exist in TM1. You cannot use the ETLDAP

utility to update or delete existing users in TM1 based on changes in the LDAP directory.

As new users are added to your LDAP server, you can add them to 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

TM1. ETLDAP does not update user attributes or delete existing TM1 users.

226 IBM Cognos TM1

Chapter 9: ETLDAP Utility

Page 227: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Determining Last Modified Record AttributeYou can use the last modified record attribute to specify a date in the Filter section of your LDAP

query when you want to update TM1® with new users from your LDAP server.

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)

You can use this date when running ETLDAP in Update mode. For details, see "Running ETLDAP

in Update Mode to Add New LDAP Users" (p. 227).

Running ETLDAP in Update Mode to Add New LDAP UsersYou can run ETLDAP in Update mode to update TM1® with new LDAP users that do not already

exist in TM1. To do this, you specify a date in the Filter section of your LDAP query.

Steps

1. Locate the newest record line in the LDAP Session Log.

2. Copy the timestamp portion of the string in parentheses from the LDAP Session Log into the

Filter section of your LDAP query.

Important: 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 LDAPSearch Filters.

The following table shows a sample Filter string without any changes, and after modification

for both LDAP and Active Directory servers.

Note:

● A standard LDAP server uses the modifytimestamp attribute.

● An LDAP server with Microsoft Active Directory uses the whenChanged attribute.

Filter String After ModificationSample Filter String

(&(objectclass=person)(|(department=R&D)(department=Documentation)))

Initial string

(&(objectclass=person)(modifytimestamp>=20030515162433Z)(|(department=R&D*)(department=QA)))

Modified for standard

LDAP

(&(objectclass=person)(whenChanged>=20030515162433.0Z)(|(department=R&D*)(department=QA)))

Modified for Active Direc-

tory

Operation Guide 227

Chapter 9: ETLDAP Utility

Page 228: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

3. 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.

4. Run ETLDAP using the new session data.

228 IBM Cognos TM1

Chapter 9: ETLDAP Utility

Page 229: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 10: Integrated Login

This section describes the IBM® Cognos® TM1® Integrated Login feature.

What Is Integrated Login?Integrated Login allows you to use Microsoft® Windows® network authentication to control access

to TM1® data. In this security model, you can use the ETLDAP utility (see "Using ETLDAP" (p. 217))

or other steps to move user and group Windows login information into the TM1 database. Users

who want to access TM1 data through TM1 clients must log in to Windows first. After they suc-

cessfully log in to Windows, TM1 does not ask for log in information.

Integrated Login matches the domain-qualified name you use to log in to Windows with a name

in the UniqueID field of the }ClientProperties cube. If there is a match, TM1 allows you to log in.

As an example, suppose you log in with the user name Robert into the domain company.com. When

you double-click a server in Server Explorer, TM1 looks in the }ClientProperties cube and examines

the UniqueID field of that cube. Robert has a domain-qualified name of robert@company. As long

as Robert logs in to the COMPANY domain with the name Robert, Integrated Login should work

for this user.

If Integrated Login cannot match the domain-qualified name you use to log in to Windows with a

name in the UniqueID field of the }ClientProperties cube, TM1 displays an error message saying

that the client name does not exist on the server.

Integrated Login is supported on Windows only. You cannot use Integrated Login to access a UNIX®

version of the IBM® Cognos® TM1®server.

Setting Up Integrated Login During InstallationIf you perform a custom TM1® installation and choose the Integrated Login options for the server

and clients, the installation process automatically configures the following TM1 components to use

Integrated Login.

ConfigurationComponent

Enables the Use Integrated Login option for TM1 Architect

and TM1 Perspectives.

TM1 Clients

For details on verifying or manually configuring these settings,

see "Configuring and Logging into TM1 Clients with Integrated

Login" (p. 242)

Licensed Materials – Property of IBM229© Copyright IBM Corp. 2007, 2011.

Page 230: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ConfigurationComponent

Configures the Integrated Login parameters in the Tm1s.cfg

file for any sample database that you choose to install.

TM1 Server

Note: You must manually set these parameters for any of your

own TM1 server databases. For details, see "Manually Config-

uring Integrated Login for the TM1 Server" (p. 232)

Configures the following settings for TM1 Server Web:TM1 Server Web

● Web.config file: Configures parameters in the Web.config

file that enable Integrated Login for TM1 Server Web.

● Folder Security: Configures user security for the TM1

Server Web folders on the web server.

● Microsoft IIS: Configures Microsoft Internet Information

Services (IIS) to use Integrated Windows authentication.

Note: You may also need to manually verify and/or configure

your NTLM or Kerberos security settings.

For details on verifying or manually configuring any of these

settings, see "Manually Configuring Integrated Login for TM1

Web" (p. 232)

To set up Integrated Login during the installation process for TM1 clients, complete the following

procedures:

Steps

1. "Select Integrated Login Option During TM1 Installation" (p. 230).

2. "Run the ETLDAP Utility" (p. 231).

3. "Set Access Rights for TM1 Users" (p. 231).

Select Integrated Login Option During TM1 InstallationComplete the following procedures.

Steps

1. Run the TM1® Installation Wizard and choose a Custom installation type.

2. Select the Integrated Login options on the Security and Client configuration screens.

3. Complete the installation.

230 IBM Cognos TM1

Chapter 10: Integrated Login

Page 231: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Run the ETLDAP UtilityRun ETLDAP to extract the user and group login data from your LDAP directory and load that

data into the TM1® security cube. For details, see "Using ETLDAP" (p. 217). 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.

Set Access Rights for TM1 UsersFor a TM1® user to access any data, you might have to assign that user to other TM1 groups. For

example, for a user to publish public objects to the Web through TM1 Web, the user must be a

member of the TM1 Admin group.

To add a user to the Admin group, complete the following steps.

Steps

1. Start TM1 Architect.

2. Click File, Options.

The TM1 Options dialog box opens.

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.

The Clients/Groups dialog box opens.

9. Select a user to add to the admin group.

Note: Use the scroll bar to scroll to the left, where the list of groups displays.

10. Click the check box for a user in the ADMIN column to add the user to the Admin group.

11. Click OK.

Operation Guide 231

Chapter 10: Integrated Login

Page 232: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Manually Configuring Integrated Login for the TM1 ServerYou can modify a TM1® installation to use Integrated Login without re-installing TM1. To do so,

you can run ETLDAP and modify several TM1 configuration files.

Steps

1. Run ETLDAP and import the user and group information from your LDAP server, as described

in "Using ETLDAP" (p. 217).

2. Shut down the IBM® Cognos® TM1®server.

3. Edit the following parameters in the Tm1s.cfg file located in your TM1 server data directory:

● Set the IntegratedSecurityMode parameter to 2.

● Set the SecurityPackageName parameter to the security protocol you use for Integrated

Login, such as Kerberos (default) or NTLM.

In the following example, the server is configured to use Kerberos.

[TM1S]

SecurityLogging=F

SecurityPackagename=Kerberos

IntegratedSecurityMode=2

Servername=myserver

DatabaseDirectory=C:\Program Files\

4. Save and exit Tm1s.cfg.

5. Restart your TM1 server.

6. Configure the different TM1 clients to use Integrated Login by setting the Use Integrated Loginoption in the associated user interface.

● "Configuring TM1 Architect to use Integrated Login" (p. 243).

● "Configuring TM1 Perspectives to use Integrated Login" (p. 243).

You should now be able to log in to your TM1 server using Integrated Login through TM1 Architect

or TM1 Perspectives .

For information on configuring Integrated Login for TM1 Web, see "Manually Configuring Inte-

grated Login for TM1 Web" (p. 232).

Manually Configuring Integrated Login for TM1 WebYou can manually configure TM1® Web to use Integrated Login without re-installing the application.

To do so, perform the following steps:

● Edit the Web.config.

● Configure Microsoft Internet Information Services (IIS).

● Configure folder security for TM1 Web.

232 IBM Cognos TM1

Chapter 10: Integrated Login

Page 233: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Configure your NTLM or Kerebos security package.

● Configure Web browsers on client systems.

● View and research additional resources.

Editing the Web.config File for Integrated Login with TM1 WebIf you did not choose the Integrated Login option when installing TM1® Web, you can manually

edit the Web.config file to include the necessary parameters.

Steps

1. Open the Web.config file for TM1.

This file is typically located in \Inetpub\wwwroot\TM1Web.

2. Locate the <appSettings> section and edit the following parameter as follows:

<add key="IntegratedLogin" value="true" />

3. Locate the authentication settings under the <system.web> section and edit the following

parameters as follows:

<authentication mode="Windows"/>

<identity impersonate="true"/>

4. Save and close the Web.config file.

Configuring IIS for Integrated Login with TM1 WebYou must configure Microsoft Internet Information Services (IIS) for it to work with Integrated

Login.

Note: Depending on your version of IIS, the following steps may vary. Refer to Microsoft's IIS

documentation for the exact steps to configure Integrated Windows authentication for your specific

version of IIS.

Steps

1. In IIS, right-click your TM1® Web directory and then click Properties.

2. Click the Directory Security tab, locate the Anonymous access and Authentication control

section, and then click Edit.

The Authentication Methods dialog box opens.

3. Configure the following options:

● Clear the check box for the Enable anonymous access option.

● Select the check box for the Integrated Windows authentication option.

4. Close the Authentication Methods dialog box.

5. Restart IIS.

Operation Guide 233

Chapter 10: Integrated Login

Page 234: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Configuring Folder Security for Integrated Login with TM1 WebYou must configure security for the Microsoft Internet Information Services (IIS) folders for TM1®

Web.

Steps

1. On the Web server running TM1 Web, use Windows Explorer to locate the IIS folders for TM1

Web.

C:\Inetpub\wwwroot\TM1Web

2. For each of the following folders under this location:

Right-click on the folder and click Properties to open the Properties dialog box.

Click the Security tab and make sure that the group, Authenticated Users, has permission set

to Full Control.

● TM1Web\css

● TM1Web\images

● TM1Web\scripts

● TM1Web\TempCharts

● TM1WebEx\ExcelSheet

● TM1WebEx\UserTempDir

3. Restart IIS.

Configuring Integrated Login for TM1 Web Using NTLMYou can configure Integrated Login for TM1® Web using NTLM with the following steps:

● Verify the TM1 Web configuration

● Verify IIS authentication

● Verify that the NTLM Windows service is running

● Configure the SecurityPackageName parameter in the Tm1s.cfg file

Note: If you use the NTLM protocol, both the Web server and the IBM® Cognos® TM1®server

server must reside on a single computer. The NTLM protocol does not support system delegation.

In a scenario where the Web server and the TM1 server reside on different computers you should

use the Kerberos security protocol, as described in the next section.

Verifying TM1 Web Configuration

To verify that TM1 Web is correctly configured to use Integrated Login, make sure the system.web

section of the TM1 Web Web.config file includes the following line for the authentication

parameter.

<authentication mode="Windows" />

234 IBM Cognos TM1

Chapter 10: Integrated Login

Page 235: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Verifying IIS Authentication

Make sure that Microsoft Internet Information Services (IIS) is configured to use Integrated Windows

authentication. This option is enabled by default in IIS. For complete details on authentication with

IIS, search the Microsoft web site for "IIS Authentication".

Verifying that the NTLM Windows Service is Running

Make sure the NT LM Security Support Provider service is available and running as a Windows

service.

To set the SecurityPackageName parameter, complete the following steps.

Steps to configure the Tm1s.cfg file

1. Shut down your IBM® Cognos® TM1® server.

2. Open Tm1s.cfg in a text editor.

3. Set the SecurityPackageName parameter to NTLM.

SecurityPackageName=NTLM

4. Save Tm1s.cfg.

5. Restart your TM1 server.

Configuring Integrated Login for TM1 Web Using KerberosThis section describes how to set up TM1® Web to use Integrated Login with the Kerberos security

protocol. If you use the Kerberos security protocol, you can configure your Web server to use either

a system account or domain user account, according to your preference.

In all cases, you must verify that TM1 Web is correctly configured to use Integrated Login. To

verify this, make sure the system.web section of the TM1 Web Web.config file includes the following

line for the authentication parameter.

<authentication mode="Windows" />

Determining if Your Web Server is Running in IIS 5.0 Isolation Mode

If you install TM1® Web on IIS 6, but your web server is running in IIS 5.0 Isolation Mode, you

should follow the instructions for Configuring TM1 Web with Integrated Login on IIS 5 Using

Kerberos.

To determine if your web server is running in IIS 5.0 Isolation Mode, complete the following steps.

Steps

1. Run Computer Management.

2. Right-click Web Sites and choose Properties.

3. Click Services.

If the Run WWW service in IIS 5.0 isolation mode check box is selected, you are running your

web server in IIS 5 isolation mode.

Operation Guide 235

Chapter 10: Integrated Login

Page 236: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Configuring TM1 Web with Integrated Login on IIS 5 Using Kerberos

To configure TM1® Web with Integrated Login on IIS 5, you must complete the following procedures.

Steps

1. "Set the Security Protocol on the Web Server to Kerberos" (p. 236)

2. "Grant the Web Server Machine Account Delegation Rights" (p. 236)

3. "Modify the .Net Configuration Files" (p. 237)

Set the Security Protocol on the Web Server to Kerberos

You must be sure that your web server is running the Kerberos security protocol.

Steps

1. Open a command prompt.

2. Migrate to the inetpub/AdminScripts directory.

3. Run the following command to set the security protocol to Kerberos:

cscript adsutil.vbs set w3svc/1/NTAuthenticationProviders"Negotiate,NTLM"

The Negotiate,NTLM parameter forces the Web server to try to use Kerberos first. If Kerberos

fails, the web server will use NTLM. Be careful not to leave a blank before NTLM.

Grant the Web Server Machine Account Delegation Rights

From the network's domain controller, run the Active Directory Users and Computers control

panel. Assign delegation rights to the TM1 service account. To do this from a Windows 2000

domain controller, complete the following steps.

Steps

1. Run the Active Directory Users and Computers control panel.

2. Click the Computers folder.

3. Right-click a computer and choose Properties.

4. On the General tab, select Trust computer for delegation.

5. Click OK.

This procedure will vary somewhat with other versions of Windows. For example, in Windows

2003:

1. Select the Delegation tab.

2. Select the Trust this computer for delegation to any service (Kerberps only).

The Microsoft Windows Server 2003 operating system also provides a secure form of delegation

called Constrained Delegation. With Constrained Delegation, you can configure the Microsoft

Active Directory service to restrict the services and servers that your ASP.NET application can

236 IBM Cognos TM1

Chapter 10: Integrated Login

Page 237: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

access with the impersonated identity. Constrained Delegation in Microsoft Windows Server

2003 requires Kerberos authentication.

TM1 allows a system or a specific user to delegate.

To set TM1 to use Constrained Delegation:

1. Go to the Delegation tab of the Properties window for your Web server computer.

The Do not trust the computer for delegation option is selected by default.

2. Click Trust this user for delegation to specified services only.

3. Click Use Kerberos only.

4. Click Add and specify the service which can be delegated.

Refer to your Windows documentation for more information.

Modify the .Net Configuration Files

Add the TM1 service account to the machine.config file on your web server. To do this, complete

the following steps.

Steps

1. Edit machine.config on your web server. The machine.config file is located in the following

location:

C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\CONFIG

2. Locate the processModel Attributes section.

password="AutoGenerate"

3. Change the userName and password fields to the domain-qualified name and password of the

TM1 service account.

4. Save the file and exit the editor.

5. Restart the IIS admin service.

Configuring TM1 Web with Integrated Login for a System Account on IIS 6 Using Kerberos

To configure TM1 Web with Integrated Login on IIS 6 using Kerberos, you must complete the

following procedures:

Steps

1. "Select Integrated Login Option During TM1 Installation" (p. 230)

2. "Grant the Web Server Machine Account Delegation Rights" (p. 236)

Operation Guide 237

Chapter 10: Integrated Login

Page 238: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Set Your Security Protocol to Kerberos

To configure your Web server to use the Kerberos security protocol, complete the following steps.

Steps

1. Open a command prompt.

2. Migrate to the inetpub/AdminScripts directory.

3. Run the following command to set the security protocol to Kerberos:

cscript adsutil.vbs set w3svc/1/root/TM1Web/NTAuthenticationProviders"Negotiate, NTLM"

The Negotiate, NTLM setting forces the Web server to try to use Kerberos first. If Kerberos

fails, the web server will use NTLM.

Grant the Web Server System Delegation Rights

From the network's domain controller, run the Active Directory Users and Computers control

panel. Assign delegation rights to the Web server system. To do this from a Windows 2000 domain

controller, complete the following steps.

Steps

1. Run the Active Directory Users and Computers control panel.

2. Click the Computers folder.

3. Right-click the Web Server system and choose Properties.

4. Select the Trust Computer for Delegation check box.

5. Click OK.

Configuring TM1 Web with Integrated Login for a Domain User on IIS 6 Using Kerberos

To configure TM1® Web with Integrated Login on IIS 6 using Kerberos, you must complete the

following procedures.

Steps

1. "Set Your Security Protocol to Kerberos" (p. 238)

2. "Create a New Application Pool for TM1 Web" (p. 239)

3. "Set the TM1 Web Application Pool to Run Under the TM1 Network User ID" (p. 239)

4. "Add the TM1 Domain User to the IIS_WPG group" (p. 240)

5. "Set the Application Pool for Your TM1 Web Virtual Directory" (p. 240)

6. "Grant the TM1 Service Account Delegation Rights" (p. 240)

7. "Set the Service Principal Name (SPN)" (p. 241)

238 IBM Cognos TM1

Chapter 10: Integrated Login

Page 239: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Set Your Security Protocol to Kerberos

To configure your Web server to use the Kerberos security protocol, complete the following steps.

Steps

1. Open a command prompt.

2. Migrate to the inetpub/AdminScripts directory.

3. Run the following command to set the security protocol to Kerberos:

cscript adsutil.vbs set w3svc/1/root/TM1Web/NTAuthenticationProviders"Negotiate, NTLM"

The Negotiate, NTLM setting forces the Web server to try to use Kerberos first. If Kerberos

fails, the web server will use NTLM.

Create a New Application Pool for TM1 Web

To create a new application pool for your TM1 Web virtual directory, complete the following steps.

Steps

1. Right-click Application Pools and choose New, Application Pool. The Add New Application

Pool dialog box opens.

2. Enter TM1 Web for the Application Pool ID.

3. Choose Use Default settings for new application pool, and click OK.

Note: If you create an application pool for TM1 Web, then perform an uninstall, that application

pool is not deleted. If you later re-install and select integrated login during the custom install,

the TM1 Web virtual directory is re-set to the default application pool, not to TM1 Web.

Set the TM1 Web Application Pool to Run Under the TM1 Network User ID

The TM1 Web application pool should run using the network identity under which you run the

TM1 services.

Steps

1. Right-click the TM1 Web application pool and choose Properties.

2. Click the Identity tab.

3. Click Configurable.

4. Enter a valid domain user and password in the fields provided. This should be the same user

name and password as your TM1 services are running.

5. Click OK.

Operation Guide 239

Chapter 10: Integrated Login

Page 240: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Add the TM1 Domain User to the IIS_WPG group

The TM1 domain user must belong to the IIS_WPG group on the web server. To add the TM1

domain user to this group, complete the following steps.

Steps

1. Run the Computer Management administration tool.

2. Navigate to the Groups folder under System Tools, Local Users and Groups, Groups.

3. Right-click the group IIS_WPG and choose Add to Group. The IIS_WPG properties dialog box

opens.

4. Click Add and add the domain-qualified name to the IIS_WPG group. This should be the same

name used by your TM1 services.

Set the Application Pool for Your TM1 Web Virtual Directory

This procedure describes how to configure the TM1 Web virtual directory to run in the TM1 Web

application pool.

Steps

1. Run the IIS Manager.

2. Right-click the TM1 Web virtual directory and choose Properties.

3. Set the Application Pool option to TM1 Web.

Grant the TM1 Service Account Delegation Rights

From the network's domain controller, run the Active Directory Users and Computers control

panel. Assign delegation rights to the account used to run your TM1 services. To do this from a

Windows 2000 domain controller, complete the following steps.

Steps

1. Run the Active Directory Users and Computers control panel.

2. Click the Users folder.

3. Right-click a user and choose Properties.

4. Click the Account tab.

5. Scroll down the Account Options list and enable the Account is Trusted for Delegation option.

This procedure will vary somewhat with other versions of Windows. Refer to your Windows

documentation for more information.

240 IBM Cognos TM1

Chapter 10: Integrated Login

Page 241: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Set the Service Principal Name (SPN)

To set the SPN, complete the following steps.

Steps

1. Download the SetSPN.exe utility from the Microsoft support for Windows 2000 website.

2. As a domain administrator, execute the following commands:

setspn -A HTTP/web_server_name domain_name\user_acct_for_TM1_services

setspn -A HTTP/webservername.domain_name domain_name\user_acct_for_TM1_services

Configuring Web Browsers for Integrated Login and TM1 WebAfter configuring TM1® Web with Integrated Login, you must then configure the Web browsers

on client systems that will access TM1 Web.

Configuring Internet Explorer for Integrated Login

To log in to TM1® Web using Integrated Login through Microsoft® Internet Explorer, you must

set the following security and advanced options, regardless of your security protocol.

Steps for Configuring Security Options

1. In Internet Explorer, clickTools, Internet Options

2. Click the Security tab, then click Trusted Sites.

3. Click Sites and add the URL that you use to connect to TM1 Web. For example, TM1Web-

ServerName.domain.com.

4. After adding the site, click the Custom level button to open the Security Settings dialog box.

5. In the Settings list, locate the User Authentication section and the Logon sub-section.

6. Click to enable the Automatic logon with current username and password option.

Steps for Configuring Advanced Options

1. On the Internet Options dialog box, click the Advanced tab.

2. In the Settings list, locate the Security section

3. Click to enable the Enable Integrated Windows Authentication option.

Restart your Internet Explorer for all of the new options to take effect.

Configuring Firefox for Integrated Login

You must edit the Mozilla Firefox configuration to use Firefox with TM1® Web and Integrated

Login. Otherwise, Firefox will continue to prompt you to log in.

Operation Guide 241

Chapter 10: Integrated Login

Page 242: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

For more details about configuring Firefox for integrated authentication, search Firefox documen-

tation on the Mozilla web site for the topics, "integrated authentication" and "about:config".

Steps

1. Open Firefox.

2. Navigate to the url about:config.

The Firefox configuration page opens.

3. 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.

network.automatic-ntlm-auth.trusted-uris

network.negotiate-auth.delegation-uris

network.negotiate-auth.trusted-uris

For example, 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.

4. Close and restart Firefox.

Additional Resources for Configuring TM1 Web for Integrated LoginSee the Microsoft support website for more information about setting up ASP applications on IIS

with Windows authentication, such as:

● To troubleshoot Kerberos-related issues in IIS.

● To configure IIS to support both Kerberos and NTLM authentication.

● To configure an ASP.NET application for a delegation scenario

● For Integrated Windows Authentication (IIS 6.0), see the Microsoft Windows website.

Configuring and Logging into TM1 Clients with IntegratedLogin

After you set up Integrated Login for the IBM® Cognos® TM1®server, you can use it to access your

TM1 data through the following clients:

● TM1 Architect

● TM1 Perspectives

● TM1 Web

242 IBM Cognos TM1

Chapter 10: Integrated Login

Page 243: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Configuring TM1 Architect to use Integrated LoginYou can access your data through TM1® Architect using Integrated Login as follows.

Steps

1. Run TM1 Architect.

2. Click File, Options.

The TM1 Options dialog box opens.

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.

TM1 Architect should automatically log you in to TM1 without asking for a user name or

password.

Configuring TM1 Perspectives to use Integrated LoginYou can access your data through TM1® Perspectives using Integrated Login as follows.

Steps

1. Run Microsoft® Excel.

2. Click TM1, Server Explorer.

The TM1 Server Explorer displays.

3. Click File, Options.

The TM1 Options dialog box opens.

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.

TM1 Perspectives should automatically log you in to TM1 without asking for a user name or

password.

Logging into TM1 Web with Integrated LoginAfter you configure a IBM® Cognos® TM1®server and TM1 Web to use Integrated Login, you can

use this authentication mode to log in and access your data through TM1 Web.

Operation Guide 243

Chapter 10: Integrated Login

Page 244: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

For information on configuring Integrated Login for TM1 Web, see "Manually Configuring Inte-

grated Login for TM1 Web" (p. 232).

Steps

1. Run Microsoft® Internet Explorer.

2. Enter the following URL in the browser Address box:

http://Web Server Name/Virtual Directory Name/TM1WebLogin.aspx

The login page displays.

3. Enter the TM1 server Admin Server host name in the Admin Host field.

4. Click Server drop-down arrow.

5. Click Login.

244 IBM Cognos TM1

Chapter 10: Integrated Login

Page 245: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 11: LDAP Authentication

This section describes how to set up IBM® Cognos® TM1® authentication using an LDAP server.

Validating Users with an LDAP ServerAs 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® to use LDAP authentica-

tion.

Note: Your LDAP server must be configured to use SSL to successfully communicate with TM1.

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.

LDAP Authentication ParametersWhen you select the LDAP Authentication option during a TM1® installation, the following

parameters are added to Tm1s.cfg to support LDAP authentication.

PasswordSourceTM1 (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.

LDAPPort636 (Default LDAP port for SSL)

This must be a secure (SSL) port.

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.

LDAPHosthost

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.

Licensed Materials – Property of IBM245© Copyright IBM Corp. 2007, 2011.

Page 246: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

LDAPWellKnownUserNameAn LDAP distinguished name. For example:

uid=bjensen,ou=people,o=company.com

The IBM® Cognos® TM1® server uses the well-known user name to log in to LDAP and look up

the name submitted by the user.

This is a required parameter when the LDAPUseServerAccount parameter is set to False.

LDAPSearchBaseA base distinguished name (DN) in the LDAP directory. For example:

ou=people,o=company.com

Specifies the node in the LDAP tree where the TM1® begins searching for valid users. For example,

if the distinguished names are of the form:

uid-bjensen, ou-people, o=company.com

then the search base would be:

ou-people, o=company.com

This is a required field.

LDAPSearchFieldcn

The name of the LDAP attribute that is expected to contain the name of the TM1® user being vali-

dated. If you do not enter an LDAPSearchField value, the default value is cn, which is also the

default value for Microsoft® Active Directory.

LDAPUseServerAccountT or F

Determines if a password is required to connect to the server when using LDAP authentication.

● 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.

LDAPPasswordFileA full path to a .dat file

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 TM1® server Admin Server's private key.

This parameter is required only when LDAPUseServerAccount=F.

246 IBM Cognos TM1

Chapter 11: LDAP Authentication

Page 247: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

LDAPPasswordKeyFileA full path to a .dat file.

Defines the password key used when LDAPUseServerAccount is not used. This is 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 Util-

ity" (p. 272).

This parameter is required only when LDAPUseServerAccount=F.

Configuring LDAP ValidationTo configure LDAP validation, you need the following information:

● A well-known name that the IBM® Cognos® 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.

You can configure a TM1 component to use LDAP validation by completing the following proce-

dures:

❑ "Run the TM1 Installation Wizard and Select LDAP Authentication" (p. 247).

❑ "Change the Parameter in TM1s.cfg to TM1" (p. 247).

❑ "Run the ETLDAP Utility" (p. 248).

❑ "Modify Group Assignments for New Users" (p. 248).

❑ "Change the PasswordSource Parameter in TM1S.cfg to LDAP" (p. 248).

Run the TM1 Installation Wizard and Select LDAP AuthenticationTo run the TM1® Installation Wizard, and select LDAP Authentication, follow these steps.

Steps

1. Run the TM1 Installation Wizard.

2. Select the LDAP authentication options, as described in the IBM Cognos TM1 Installation

Guide.

3. Complete the installation.

Change the Parameter in TM1s.cfg to TM1To change the parameter in TM1s.cfg, follow these steps.

Steps

1. Edit TM1s.cfg in your IBM® Cognos® TM1® server data directory.

Operation Guide 247

Chapter 11: LDAP Authentication

Page 248: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

2. Modify the following line:

PasswordSource=LDAP

3. Change the line to read as follows:

PasswordSource=TM1

4. Save and exit TM1s.cfg.

5. Recycle your TM1 server.

Run the ETLDAP UtilityRun ETLDAP and import names from your LDAP directory into TM1®, as described in "ETLDAP

Utility" (p. 217).

Use the following TM1 login information:

● Admin user (default) - Admin

● Admin password (default) - apple

Use the well known user you specified during the installation to log in to LDAP.

Modify Group Assignments for New UsersYou can modify group assignments for new users.

Steps

1. Log in to TM1® as an administrator.

2. Right-click the server name in Server Explorer and click Security, Clients and Groups.

3. 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.

Change the PasswordSource Parameter in TM1S.cfg to LDAPYou can change the PasswordSource parameter in TM1s.cfg to LDAP.

Steps

1. Edit TM1s.cfg in your IBM® Cognos® TM1® server data directory.

2. Modify the following line:

PasswordSource=TM1

3. Change this line to read as follows:

PasswordSource=LDAP

248 IBM Cognos TM1

Chapter 11: LDAP Authentication

Page 249: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

4. Define the connection status:

● To directly connect to the server add the following line:

LDAPUseServerAccount=T

● To use a password before connecting to the server, add the following lines:

LDAPPasswordFile=file

LDAPPasswordKey=key

To configure LDAP validation, you need the following information:

● A well-known 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.

5. Save and exit TM1s.cfg file.

6. Recycle your TM1 server.

You should now be able to log in to TM1 with a name that you added from your LDAP

directory

Operation Guide 249

Chapter 11: LDAP Authentication

Page 250: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

250 IBM Cognos TM1

Chapter 11: LDAP Authentication

Page 251: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 12: Using IBM Cognos 8 Security withTM1

This section describes how to use IBM® Cognos® 8 security with IBM Cognos TM1®.

For complete details on IBM Cognos 8 security concepts, terminology, and implementation, see the

IBM Cognos 8 Administration and Security Guide.

Note: Integrating TM1 security with IBM Cognos security requires at least TM1 9.4 and IBM

Cognos 8.4.

IBM Cognos 8 Security OverviewThe IBM® Cognos® TM1 server can authenticate users using IBM Cognos 8 security. IBM Cognos

8 security is a component of the IBM Cognos 8 framework that manages user access to data. IBM

Cognos 8 security manages authorization and authentication through third-party security providers,

such as LDAP or Active Directory. When a user is authenticated through IBM Cognos 8 security,

they are provided with a Cognos security "passport." This passport is then used by IBM Cognos/TM1

applications to determine the user's permissions (role and group membership) and identity.

When using IBM Cognos 8 security, a Cognos passport is required to connect to TM1. A user is

presented with a logon screen requiring a namespace, a user name, and a password when first logging

in to TM1 or any other IBM Cognos 8 security-enabled components. Once authenticated by IBM

Cognos 8 security, a passport is issued to the user. This passport automatically provides the user's

credentials when accessing any other IBM Cognos 8 security-enabled application (including TM1).

Once a user connects to the TM1 server via a specific IBM Cognos 8 server that has been configured

for common logon, no direct user input is required to access additional TM1 servers (or other IBM

Cognos 8 applications) that are configured to reference the same IBM Cognos 8 server.

When a user attempts to access the TM1 server, the server validates the passport to authenticate

the user. This is done by querying an IBM Cognos 8 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, as well as

the account (user name) associated with the passport. If the user name already exists in TM1, their

existing membership will be validated against the existing TM1 groups. If the user does not exist,

they are added and assigned to the appropriate user groups on the TM1 server.

After connecting to CAM two new folders are created in the installdir directory:configuration

directory has epC8ITK.ini file and the Logs directory has multiple epC8ITK_2008-03-13.log.

● the configuration directory has epC8ITK.ini

● Logs directory has multiple epC8ITK_<datestamp>.log.

Licensed Materials – Property of IBM251© Copyright IBM Corp. 2007, 2011.

Page 252: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Setting Up the TM1 Server to Use IBM Cognos 8 SecurityThe following sections describe the configuration settings and procedures required to enable IBM®

Cognos® 8 security authentication on the TM1 server.

Note: To successfully complete these procedures, your IBM Cognos 8 server must not be configured

to allow anonymous access. If anonymous access is enabled on the IBM Cognos 8 server, you cannot

logon to a namespace from TM1 when importing Cognos groups into TM1.

Configuring the TM1 ServerIf you are re-configuring the TM1® server to use IBM® Cognos® 8 security for authentication with

another instance of IBM Cognos 8 (C8), you must remove any existing C8 users and groups that

were imported from the first C8 instance and then re-import users and groups from the new C8

instance.

Before enabling IBM Cognos 8 security on the TM1 server, you must add or modify several config-

uration parameters to the server's Tm1s.cfg file

Steps

1. Open the Tm1s.cfg configuration file in a text editor. Tm1s.cfg is located in the TM1 server

data directory.

2. Add the following parameters to the configuration file.

DescriptionParameter Name

The URI for the internal dispatcher that the TM1 server

should use to connect to IBM Cognos 8 security. The

URI is specified in the form

ServerCAMURI

http[s]://host IP address:port/p2pd/servlet/dispatch

For example, http://10.121.25.121:9300/p2pd/

servlet/dispatch or https://10.121.25.121:9300/p2pd/servlet/dispatch

Note: To find the URI, ask your IBM Cognos 8 admin-

istrator to perform the following steps.

1. Open the IBM Cognos Configuration.

2. Click Environment.

3. In the Gateway section, go to Dispatcher URI to

locate the URI.

252 IBM Cognos TM1

Chapter 12: Using IBM Cognos 8 Security with TM1

Page 253: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter Name

The URI for the IBM Cognos 8 Server IBM Cognos

Connection used to authenticate TM1 clients. The URI

is specified in the form:

ClientCAMURI

http[s]://host/cognos8/cgi-bin/cognos.cgi.

Note: Both cognos8 and cognos.cgi are variables and

depend on the exact settings that have been used. Con-

tact your IBM Cognos 8 administrator for more infor-

mation about these settings.

For example:

http://10.121.25.121/cognos8/cgi-bin/cognos.cgi.

If you are using Microsoft® Internet Information Services

(IIS):

http://10.121.25.121/cognos8/cgi-bin/cognosisapi.dll

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\CognosCert.cer.

CAMSSLCertificate

This parameter is required only if the IBM Cognos 8

server is configured to use SSL.

Indicates whether the SSL certificate ID confirmation

process can be skipped. The default is FALSE.

SkipSSLCAMHostCheck

Important: This parameter should be set to TRUE only

if using a generic certificate for demonstration purposes.

Indicates the interval, in seconds, that a client should

ping the IBM Cognos 8 server to keep their passport

alive.

ClientPingCAMPassport

If an error occurs or the passport expires the user will

be disconnected from the TM1 server.

Operation Guide 253

Chapter 12: Using IBM Cognos 8 Security with TM1

Page 254: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter Name

The path to the variables_TM1.xml file in your C8

installation. In most cases, the path will be:

CAMPortalVariableFile

CAMPortalVariableFile= portal\variables_TM1.xml

The variables_TM1.xml file is included as part of the

TM1 Viewer Portlets installation. For details on

installing and configuring Viewer Portlets, see the IBM®

Cognos® TM1® Installation Guide.

The CAMPortalVariableFile parameter is required only

when running TM1 Web.

The Tm1s.cfg file should contain parameters similar to the following:

ServerCAMURI=http://10.111.25.121:9300/p2pd/servlet/dispatch

ClientCAMURI=http://10.111.25.121/cognos8/cgi-bin/cognos.cgi

ClientPingCAMPassport=900

CAMPortalVariableFile=templates\ps\portal\variables_TM1.xml

3. Set the IntegratedSecurityMode parameter to 2.

IntegratedSecurityMode=2

4. Save and close Tm1s.cfg.

5. Restart the TM1 server.

Configuring the TM1 ClientYou must add two parameters to your Tm1p.ini file to allow you to perform IBM Cognos 8 security-

related administrative tasks from your TM1® client.

Steps

1. Open the Tm1p.ini configuration file in a text editor. Tm1p.ini is located in the C:\Documents

and Settings\user name\Application Data\Applix\TM1 directory.

2. Add the following parameters to the Tm1p.ini file.

DescriptionParameter Name

The URI for the IBM® Cognos® 8 Server IBM Cognos Connection

used to authenticate TM1 clients. The URI is specified in the

form

CognosGatewayURI

http[s]://host/cognos8/cgi-bin/cognos.cgi

For example: http://10.121.25.121/cognos8/cgi-bin/cognos.cgi

254 IBM Cognos TM1

Chapter 12: Using IBM Cognos 8 Security with TM1

Page 255: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter Name

Determines if Cognos clients can be imported into TM1. This

parameter must be set to T when setting up IBM Cognos 8

security in TM1.

AllowImportCAM-

Clients

Your Tm1p.ini file should include parameters similar to the following:

AllowImportCAMClients = T

CognosGatewayURI = http://10.111.25.121/cognos8/cgi-bin/cognos.cgi

3. Save and close Tm1p.ini.

4. Restart your TM1 client.

Defining a Cognos User to Function as a TM1 AdministratorTo successfully administer TM1® while using IBM Cognos 8 authentication, an existing Cognos

user must be added to the TM1 ADMIN group. This Cognos user will be used to import Cognos

groups into TM1.

Steps

1. Log in to TM1 as an administrator.

2. From the Server Explorer, click Server, then Security, then Clients/Groups.

3. From the Clients/Groups dialog box, click Clients, then Add New Client.

The Cognos logon dialog box appears.

4. Enter your Cognos user ID and password, then click OK.

The Select Entries dialog box appears.

5. In the Name box, click the namespace to which you are currently logged in.

Note: Only users from the namespace to which you are logged in can be imported into 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 TM1 administrator.

In most circumstances, you will define your own Cognos user as a 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 TM1.

Operation Guide 255

Chapter 12: Using IBM Cognos 8 Security with TM1

Page 256: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The user appears as a new client in the Client/Groups window, but is not assigned to any TM1

groups.

11. Assign the new user to the ADMIN group and click OK.

12. Shut down the TM1 server.

13. Open the Tm1s.cfg configuration file in a text editor.

14. Set the IntegratedSecurityMode parameter to indicate that the server should use IBM Cognos

8 authentication. The exact parameter value depends on the specific TM1 components you are

using:

● If you are not using the IBM® Cognos® TM1® Contributor component, set the parameter

to 4.

IntegratedSecurityMode=4

● If you are using IBM Cognos TM1 Contributor with IBM Cognos 8 security, set the

parameter to 5 to support user groups from both TM1 and Cognos 8.

IntegratedSecurityMode=5

15. Save and close Tm1s.cfg.

16. Restart the TM1 server.

Importing Cognos Groups into TM1Once a Cognos user is defined as the TM1® administrator, that user can import Cognos groups

into TM1. You should import only the Cognos groups that you want to allow to access the TM1

server.

Steps

1. In the Server Explorer, double-click your TM1 server.

The Cognos logon dialog box appears.

2. Log on as the Cognos user that you have defined as the 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.

The Select Entries dialog box appears.

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 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

TM1.

7. Click the green arrow icon to move the selected user to the Selected Entries list.

256 IBM Cognos TM1

Chapter 12: Using IBM Cognos 8 Security with TM1

Page 257: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

8. Click OK to import the Cognos groups into TM1.

If you review the User Group Assignment section of the Clients/Groups window, you should

see the Cognos groups added to your server.

Creating UsersWhen the TM1® server is configured to use IBM Cognos 8 authentication, you cannot create new

clients directly on the TM1® server. Instead, all client administration is performed in IBM Cognos

8.

When a Cognos user accesses TM1, the user is validated and automatically assigned to the appro-

priate TM1 groups. There is no need to manually assign users to groups in TM1.

Administering TM1 Object SecurityWhile IBM Cognos 8 authentication automatically manages users on the TM1® server, the TM1

administrator must still manage object security to allow Cognos users to view and use TM1 objects.

For details on administering TM1 object security, see the IBM® Cognos® 8 security with IBM

CognosTM1 Developer Guide.

Configuring TM1 Web to Use IBM Cognos 8 SecurityTo allow users to successfully log in to TM1® Web when the TM1 server uses IBM® Cognos® 8

authentication, a variables_TM1.xml file must be present in the c8_location\templates\ps\portal

directory. The variables_TM1.xml file must be configured to include the URL of the web server

used to deliver TM1 Web.

The variables_TM1.xml file is included as part of the TM1 Viewer Portlets installation. For details

on installing and configuring Viewer Portlets, see the IBM® Cognos® 8 security with IBM Cognos

TM1 Installation Guide.

Logging in to TM1 TopThe TM1® Top utility allows you to log into the current TM1 Top session by executing the TM1

Top command V. To successfully log in to TM1 Top, you must provide the IBM® Cognos® 8

Namespace ID of the namespace (not the descriptive name), along with a valid Cognos user name

and password.

Administrator Considerations When Using IBM Cognos 8 AuthenticationTM1® administrators should be aware of the following issues when configuring the TM1 server to

use IBM® Cognos® 8 authentication.

● Review the description of TM1 security modes 4 and 5 for the IntegratedSecurityMode

parameter. You should understand how these different modes control whether or not Cognos

8 users can belong to TM1 user groups. For details, see the description of the

IntegratedSecurityMode parameter in the IBM® Cognos® 8 security with IBM Cognos TM1

Operation Guide.

Operation Guide 257

Chapter 12: Using IBM Cognos 8 Security with TM1

Page 258: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● You can not use TM1 to permanently assign a Cognos 8 user to another Cognos 8 group. Any

user assignment you make in TM1 to a Cognos 8 group is not saved back to Cognos 8. When

a Cognos 8 user logs in to TM1, the group assignments in Cognos 8 override any Cognos 8

group assignments made in TM1.

● If you rename a Cognos 8 user after importing that user to TM1, you must then delete the user

in TM1 in order to update TM1 with the new user name. After deleting the user in TM1, the

new name will appear the next time the user logs in.

User Considerations When Using IBM Cognos 8 AuthenticationTM1® users should be aware of the following issues when accessing the TM1 server configured to

use IBM® Cognos® 8 authentication.

Authentication Behavior

The following rules govern authentication behavior when logging on to the TM1 server that uses

IBM Cognos 8 authentication.

● If common logon is enabled in IBM Cognos 8 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 TM1 server.

● If common logon is enabled in IBM Cognos 8 and you have not previously logged in to an IBM

Cognos application, you are prompted for credentials when logging on to the TM1 server.

● If common logon is not enabled in IBM Cognos 8, you are prompted for credentials when

logging on to the TM1 server, even if the server is configured to use IBM Cognos 8 authentica-

tion.

Private IBM Cognos 8 Security Sessions

When an IBM Cognos 8 server is configured to use common logon, you will only be challenged

once for credentials. Any subsequent connections to other IBM Cognos 8 security-enabled applica-

tions (including TM1®) which are configured to reference the same IBM Cognos 8 server will

automatically occur, provided your Cognos security passport is valid.

For example, if you have three available TM1 servers, all configured to use the same IBM Cognos

8 server, once you connect to the first server as user X in namespace Y, all connections to the other

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 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 passport for later use. When you log on to the 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 8 security-enabled applications.

Steps

1. From the Server Explorer, click Server, then Logon As.

258 IBM Cognos TM1

Chapter 12: Using IBM Cognos 8 Security with TM1

Page 259: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

2. In the Cognos Logon window, enter the User ID and Password you want to use to log on to

the TM1 server.

3. Click OK.

Establishing a Replication with IBM Cognos 8 Security

When establishing a replication connection to the TM1® server that uses IBM Cognos 8 authenti-

cation, you must provide the IBM Cognos 8 Namespace ID of the namespace, not the descriptive

name of the namespace.

Operation Guide 259

Chapter 12: Using IBM Cognos 8 Security with TM1

Page 260: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

260 IBM Cognos TM1

Chapter 12: Using IBM Cognos 8 Security with TM1

Page 261: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 13: Running TM1 in Secure Mode UsingSSL

This section describes how to configure IBM® Cognos® TM1® to use SSL for secure data transmission.

Overview of Running TM1 in Secure Mode Using SSLAll TM1® components communicate with the IBM® Cognos® TM1® Admin Server using SSL. The

Admin Server supports older TM1 clients that cannot use SSL by listening on two ports; one secured,

the other unsecured. TM1 clients that can use SSL connect to the Admin Server via the secured

port, while older clients that are incapable of using SSL connect to the Admin Server via the unsecured

port.

When the TM1 server registers with the Admin Server, the TM1 server specifies whether it is using

SSL or not. When a TM1 client contacts the Admin Server, the list of available TM1 servers will

vary according to which port the client uses to connect to the Admin Server. If the client uses the

secured port, the Admin Server responds with a list of all TM1 servers available on the network.

If the client uses the unsecured port, the Admin Server responds with a list of only those TM1

servers that do not use SSL.

TM1 Admin Server configuredto listen for client connections onboth secured and unsecured ports

Older TM1 Client (Pre-9.1)Not Configured to Use SSL.This client will contact the Admin Serveron the unsecured port and receive a list ofonly the TM1 servers that are not configuredto use SSL. These are the only servers withwhich the client will be able to establishinsecure connections; any TM1 serversconfigured to use SSL will not be visibleto this client.

TM1 (9.1 or Later) ClientConfigured to Use SSLThis client will contact the Admin Serveron the secured port and receive a list ofall TM1 servers available on the network.The client will establish secureconnections with TM1 servers configuredto use SSL, and will establish insecureconnections with TM1 servers that arenot configured to use SSL.

TM1 Serversnot configured to use SSL

TM1 Serversconfigured to use SSL

Licensed Materials – Property of IBM261© Copyright IBM Corp. 2007, 2011.

Page 262: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

TM1-Generated CertificatesWhen you install TM1®, all certificates and other files required to implement SSL are placed in the

TM1_install_dir\bin\SSL directory. The certificates contained in this directory are issued by the

Applix, Inc. certificate authority, which was created using OpenSSL. The password used was

"applix".

When you install TM1, the Admin Server, TM1 server, and TM1 client are all configured to use

SSL, relying on the certificates installed in the TM1_install_dir\bin\SSL directory. While the TM1

certificates allow an out-of-the-box SSL 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 TM1_install_dir\bin\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.

● Applixca.pem - the public root authority certificate

● Applixcacrl.pem - the certificate revocation list

● Applixca.der - the public root authority certificate in DER format used for Java™ certificate

stores

● tm1admsvrcert.pem - the Admin Server certificate containing the public/private key pair

● tm1svrcert.pem - the TM1 server certificate containing the public/private key pair

● dh512.pem - the file that contains the pre-generated Diffie-Hellman 512 bit key

● dh1024.pem - the file that contains the pre-generated Diffie-Hellman 1024 bit key

● tm1store - the Java certificate store containing the public root authority certificate

● tm1cipher.dat - the encrypted file containing the password used to access the server's private

key

● tm1key.dat - the key used to encrypt and decrypt tm1cipher.dat

Configuring the TM1 Admin Server to Use SSLTo configure the TM1® Admin Server to use SSL, you must set several parameters in Tm1admsrv.ini,

the TM1 Admin Server configuration file. The Tm1admsrv.ini file resides in the TM1_install_dir\bin

directory.

The following table describes all SSL-related parameters that can be set in the configuration file.

262 IBM Cognos TM1

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 263: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

This parameter determines if the Admin Server supports non-SSL

TM1 clients.

SupportNonSSLClients

Set SupportNonSSLClients = T to configure the Admin Server to

support non-SSL clients and to listen for client connections on both

secured (SSL) and unsecured ports.

Set SupportNonSSLClients = F to configure the Admin Server to

support only SSL client connections on a single secured port.

The full path of the TM1 Admin Server's certificate authority file.SSLCertAuthority

The full path of the TM1 Admin Server's certificate file, which

contains the public/private key pair.

SSLCertificate

The full path name of the file that contains a pre-generated Diffie-

Hellman 512 bit key.

DHFile-512

The generation of Diffie-Hellman parameters can be computationally

expensive. To minimize the consumption of resources and to reduce

the amount of time required to load the TM1 server, the Diffie-

Hellman 512 bit key should be pre-generated and stored in a file

that is called when the Admin Server starts.

The full path of the file that contains a pre-generated Diffie-Hellman

1024 bit key.

DHFile-1024

The generation of Diffie-Hellman parameters can be computationally

expensive. To minimize the consumption of resources and to reduce

the amount of time required to load the TM1 server, the Diffie-

Hellman 1024 bit key should be pre-generated and stored in a file

that is called when the Admin Server starts.

The full path of the file that contains the encrypted password for the

TM1 Admin Server's private key.

SSLPrivateKeyPwdFile

The full path of the file that contains the key used to encrypt and

decrypt the password for the private key.

SSLPwdKeyFile

Operation Guide 263

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 264: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

Specifies whether the TM1 Admin Server's certificate should be

exported from the Windows® certificate store.

ExportSvrSSLCert

If ExportSvrSSLCert=T, the Admin Server's certificate is exported

from the Windows certificate store when the certificate is requested

by the Admin Server.

If ExportSvrSSLCert=T, you must also set the following Tm1adm-

srv.ini parameters:

SvrSSLExportKeyID

SSLCertificateID

SSLPrivateKeyPwdFile

SSLPwdKeyFile

SSLCertAuthority

SvrSSLExportKeyID

ExportSvrSSLCert

ClientExportSSLSvrKeyID

For details on using your own security certificates and exporting

certificates from the Windows certificate store, see "Using Indepen-

dent Certificates" (p. 271).

Specifies the name of the principal to whom the TM1 Admin Server's

certificate is issued to.

SSLCertificateID

The full path of the TM1 Admin Server's certificate revocation file.SSLCertRevocationFile

A certificate revocation file will only exist in the event a certificate

had been revoked.

Specifies the identity key used to export the Admin Server's certificate

from the Windows certificate store.

SvrSSLExportKeyID

This parameter is required only if you choose to use the certificate

store.

Configuring the TM1 Server to Use SSLTo configure a TM1® server to use SSL, you must set several parameters in Tm1s.cfg, a TM1 server's

configuration file.

The following table describes all SSL-related parameters that can be set in the Tm1s.cfg configuration

file. Note that this table describes only the Tm1s.cfg parameters that are related to SSL; all other

Tm1s.cfg parameters are described in "Parameters in the Tm1s.cfg File" (p. 33).

264 IBM Cognos TM1

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 265: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

Enables or disables SSL on the TM1 server.UseSSL

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.

Specifies the name of the principal to whom the TM1 Admin

Server's certificate is issued.

AdminSvrSSLCertID

If the AdminSvrSSLCertID is incorrectly configured, the server pull-

down menu in TM1 Web displays as empty and an error is logged

to the TM1web.log file.

The full path of the certificate authority file that issued the TM1

Admin Server's certificate.

AdminSvrSSLCertAuthority

The full path of the certificate revocation file issued by the certificate

authority that originally issued the TM1 Admin Server's certificate.

A certificate revocation file will only exist in the event a certificate

had been revoked

AdminSvrSSLCertRevList

Specifies whether the TM1 Admin Server's certificate should be

exported from the Windows certificate store.

ExportAdminSvrSSLCert

If ExportAdminSvrSSLCert=T, the Admin Server's certificate is

exported from the Windows certificate store when the certificate is

requested by the TM1 server.

Specifies the identity key used to export the Admin Server's certifi-

cate from the Windows certificate store.

AdminSvrSSLExportKeyID

The full path of the certificate file that contains the public/private

key pair.

SSLCertificate

The name of the TM1 server's certificate authority file. This file

must reside on the computer where the TM1 server is installed.

SSLCertAuthority

The name the TM1 server's certificate revocation file. A certificate

revocation file will only exist in the event a certificate had been

revoked. This file must reside on the computer where the TM1

server is installed.

SSLCertRevocationFile

Operation Guide 265

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 266: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

The name of the principal to whom the TM1 server's certificate is

issued.

SSLCertificateID

Specifies whether the TM1 server's certificate should be exported

from the Windows certificate store.

ExportSvrSSLCert

If ExportSvrSSLCert=T, the TM1 server's certificate is exported

from the Windows certificate store when the certificate is requested

by the TM1 server.

If ExportAdminSvrSSLCert=T, you must also set the following

Tm1s.cfg parameters:

AdminSvrSSLCertID

AdminSvrSSLExportKey

ExportSvrSSLCert

SvrSSLExportKeyID

SSLCertificateID

SSLPwdKeyFile

SSLPrivateKeyPwdFile

SSLCertAuthority

ClientExportSSLSvrCert

For details on using your own security certificates and exporting

certificates from the Windows certificate store, see "Using Indepen-

dent Certificates."

The identity key used to export the TM1 server's certificate from

the Windows certificate store.

SvrSSLExportKeyID

This parameter is required only if you choose to use the certificate

store by setting ExportSvrSSLCert=T.

The full path of the file that contains the encrypted password for

the private key.

SSLPrivateKeyPwdFile

The full path of the file that contains the key used to encrypt and

decrypt the password for the private key.

SSLPwdKeyFile

266 IBM Cognos TM1

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 267: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

Specifies whether the TM1 client should retrieve the certificate

authority certificate, which was originally used to issue the TM1

server's certificate, from the Windows certificate store.

ClientExportSSLSvrCert

If ClientExportSSLSvrCert=T, the certificate authority certificate is

exported from the certificate store on the client computer when

requested by the TM1 client.

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 Windows certificate store.

ClientExportSSLSvrKeyID

The full path of the file that contains the pre-generated Diffie-

Hellman 512 bit key.

DHFile-512

The generation of Diffie-Hellman parameters can be computation-

ally very expensive. To minimize this cost, the Diffie-Hellman 512

bit key can be pre-generated and stored in a file that is called when

the TM1 server starts.

The full path name of the file that contains the pre-generated Diffie-

Hellman 1024 bit key.

DHFile-1024

The generation of Diffie-Hellman parameters can be computation-

ally very expensive. To minimize this cost, the Diffie-Hellman 1024

bit key can be pre-generated and stored in a file that is called when

the TM1 server starts.

Configuring TM1 Clients to Use SSLTo configure TM1® clients to use SSL, you must set several options on the TM1 Options dialog

box. To open the Options dialog box, choose File, Options from the Server Explorer. The SSL-

specific options appear halfway down the dialog box in the Admin Server Secure Socket Layer

grouping.

The following table describes all SSL-related options that can be set in the TM1 Options dialog

box and lists the corresponding Tm1p.ini parameters.

DescriptionCorrespondingTm1p.ini Parame-ter

Option Name

The full path of the certificate authority file that

issued the TM1 Admin Server's certificate.

AdminSvrSSLCertAu-

thority

Certificate Authority

Operation Guide 267

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 268: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionCorrespondingTm1p.ini Parame-ter

Option Name

The full path of the certificate revocation file

issued by the certificate authority that originally

issued the TM1 Admin Server's certificate. A cer-

tificate revocation file will only exist in the event

a certificate had been revoked.

AdminSvrSSLCertRevListCertificate Revocation

List

Note: The name of the principal to whom the

TM1 Admin Server's certificate is issued.

AdminSvrSSLCertIDCertificate ID

The value of this parameter should be identical to

the SSLCertificateID parameter in the Tm1adm-

srv.ini file.

Select this option if you want the certificate

authority certificate which originally issued the

TM1 Admin Server's certificate to be exported

from the Windows® certificate store at runtime.

ExportAd-

minSvrSSLCert

Use Certificate Store

Selecting this option in the TM1 Options dialog

box is equivalent to setting ExportAd-

minSvrSSLCert=T in the Tm1p.ini file.

When this option is selected, you must also set a

value for Export Certificate ID in the TM1

Options dialog box.

The identity key used to export the certificate

authority certificate, which originally issued the

TM1 Admin Server's certificate, from the certifi-

cate store.

AdminSvrSSLEx-

portKeyID

Export Certificate ID

This parameter is required only if you choose to

use the certificate store by setting ExportAd-

minSvrSSLCert=T.

Configuring the TM1 Top Utility to Use SSLThe TM1® Top utility can be configured to use SSL when communicating with the TM1 Admin

Server by adding five SSL-specific parameters to the Tm1top.ini file, as described in the following

table.

268 IBM Cognos TM1

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 269: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionParameter

The full path of the certificate authority file that issued the TM1

Admin Server's certificate.

AdminSvrSSLCertAuthority

The name of the principal to whom the TM1 Admin Server's certifi-

cate is issued.

AdminSvrSSLCertID

The full path of the certificate revocation file issued by the certificate

authority that issued the TM1 Admin Server's certificate.

AdminSvrSSLCertRevList

A certificate revocation file will only exist in the event a certificate

had been revoked.

Indicates whether the certificate authority certificate which issued

the TM1 Admin Server's certificate should be exported from the

Windows® certificate store at runtime.

ExportAdminSvrSSLCert

To export the certificate authority certificate at runtime, set Expor-

tAdminSvrSSLCert=T.

The identity key used to export the certificate authority certificate

which issued the TM1 Admin server's certificate from the Windows

certificate store.

AdminSvrSSLExportKeyID

This parameter is required only if you choose to use the certificate

store by setting ExportAdminSvrSSLCert=T.

Configuring TM1 Web to Use SSLTo enable SSL in TM1® Web, you must modify the value for the AdminSvrSSLCertID key in the

TM1 Web configuration file, Web.config.

The Web.config file is located in the TM1Web directory on your Web server. The default location

of this directory is C:\Inetpub\TM1Web.

The AdminSvrSSLCertID key displays in the appSetting section located at the top of the configuration

file. You must set the AdminSvrSSLCertID key value to the name of the principal to whom the

TM1 Admin server's certificate is issued.

The default AdminSvrSSLCertID entry in the Web.config file is:

<!-AdminSvrSSLCertID: Admin Server SSL CertificateID -->

<add key="AdminSvrSSLCertID" value="tm1adminserver"/>

This default entry configures TM1 Web to use SSL, relying on the TM1-generated certificates that

are included as part of your TM1 installation.

Operation Guide 269

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 270: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Configuring the TM1 C API to Use SSLSeveral 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 SSL.

For further details, see "Configuring the TM1 C API to Use SSL" in the IBM® Cognos® TM1® API

Guide.

Configuring the TM1 Java API to Use SSLThe 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. For example:

C:\Program Files\Java\JDK1.5.0_04\lib\security

The default password for cacerts is "changeit". Java provides an executable named keytool.exe for

this very purpose. For example:

keytool -keystore ..\lib\security\cacerts -alias Company-import -file Companyca.der

Optionally, if access is restricted to the system cacerts truststore, a truststore can be created. For

example:

keytool -keystore tm1store -alias Companyca -import -fileACompanyca.der

When starting the Java application this keystore must be specified. If a password is required it must

be provided as well. For example:

java -Djavax.net.ssl.trustStore=bin\ssl\tm1store -Djavax.net.ssl.trustStorePassword=Companycom.mycompany.MyApp

Further information is provided in the API specification for the Java 2 Platform Standard Edition.

The minimum Java version supported is 1.4.2.

Configuring the TM1 ETLDAP Utility to Use SSLBefore you can connect to the LDAP server using SSL, you must run the following command to

add your certificate to the TM1® store in the TM1_install_dir\axajre\bin directory:

Example:

C:\Program Files\Cognos\Tm1\axajre\bin >keytool -keystore"C:\Program Files\Cognos\Tm1\axajre\bin\tm1store" -alias Applixldapca-import -file c:\temp\certificate_name.cer

In the above 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 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.

270 IBM Cognos TM1

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 271: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

When running the ETLDAP utility from a command line, you must use the following two parameters

to enable SSL.

DescriptionParameter

Use this parameter to specify the full path to the Java™ certificate

store containing the public root authority certificate.

-Djavax.net.sll.truststore

For example, to use the Java certificate store installed with TM1,

use the parameter -Djavax.net.sll.truststore= C:\Program Files\

Cognos\TM1\bin\ssl\tm1store

Use this parameter to specify the password used to create the Java

certificate store.

-Djavax.net.ssl.trust-

StorePassword

For example, to specify the password used to create the Java certifi-

cate store installed with TM1, use the parameter -Djavax.net.ssl.

trustStorePassword=applix

Using Independent CertificatesThough a standard TM1® installation is configured to use SSL by relying on the certificates installed

in the TM1_install_dir\bin\SSL directory, you should use your own certificates to maximize security.

The following sections describe how to use non-TM1 certificates to implement SSL.

Using the Windows Certificate StoreTo add an independent certificate to the Microsoft® Windows® certificate store and configure TM1®

to use the certificate in the store, complete the following procedures.

Add Your Certificate to the Certificate Store

To add a certificate to the Windows certificate store, complete the following steps.

Steps

1. From the Windows Start menu, click Start, Run and enter mmc to open the Microsoft Manage-

ment Console.

2. Click File, Add/Remove Snap-in from the Microsoft Management Console.

The Add/Remove Snap-in dialog box opens.

3. Click Add.

The Add Standalone Snap-in dialog box opens.

4. Select Certificates and click Add.

5. Select My User Account and click Finish.

6. Click OK on the Add/Remove Snap-in dialog box.

Operation Guide 271

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 272: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The Microsoft Management Console displays the Certificate snap-in.

7. Right-click Personal under Certificates - Current User and select All Tasks, Import.

The Certificate Import Wizard opens.

8. Click Next.

The File to Import screen opens.

9. Click Browse and select the .pfx file that contains your certificate information.

10. Click Next.

The Password screen opens.

11. Enter a password for the private key and select the Mark this key as exportable option.

12. Click Next.

The Certificate Store screen opens.

13. Configure the screen as shown above and click Next.

14. Click Finish on the final screen of the Certificate Import Wizard.

Run the TM1Crypt Utility

The TM1Crypt utility (TM1Crypt.exe) encrypts the password that is needed by the TM1® server

to access the private key. The password is encrypted using Advanced Encryption Standard, 256 bit,

Cipher Block Chaining (AES-256-CBC).

The TM1Crypt utility is installed in the TM1_install_dir\bin directory. If you accepted the default

installation directory, the full path to the utility is C:\Program Files\Cognos\TM1\bin\tm1crypt.exe.

Run the TM1Crypt utility from a command prompt using the following syntax:

tm1crypt.exe -pwd [password] -keyfile [filename] -outfile[filename] -validate

DescriptionOption

The password for the private key. This should be the same password you

used to encrypt your certificate in Step 11 above.

-pwd

The name of the .dat file that will be generated to contain the key used

to encrypt and decrypt the password for the private key.

-keyfile

If this parameter is not specified, TM1Crypt generates a file named

tm1key.dat.

The name of the .dat file that will be generated to contain the encrypted

password for the private key.

-outfile

If this parameter is not specified, TM1Crypt generates a file named

tm1cipher.dat.

272 IBM Cognos TM1

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 273: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionOption

If you include the -validate parameter, the utility will decrypt the encrypted

password and display the results as clear text.

-validate

The displayed text should correspond to the password you specified with

the -pwd parameter.

This parameter does not allow validation of exiting files.

For example, the command

tm1crypt.exe -pwd abc123 -keyfile btkey.dat -outfilebtprk.dat -validate

generates two files:

● btkey.dat, which contains the key used to encrypt/decrypt the password for the private key

● btprk.dat, which contains the encrypted password for the private key.

The generated files are written to the TM1_install_dir\bin directory.

Edit the Tm1adminsvr.ini File

After adding your certificate to the Windows Certificate Store, the Tm1adminsvr.ini file must include

the following parameters:

ValueParameter

This parameter must be set to T to enable the Admin Server to

retrieve the certificate from the Certificate Store.

ExportSvrSSLCert

ExportSvrSSLCert=T

The name of the authority that issued your certificate.SSLCertAuthority

You can determine this value by referring to the Microsoft Manage-

ment Console and clicking Certificates→Personal→ Certificates. The

authority name displays in the Issued By column of the Properties

pane.

The name of the principal to whom the TM1® Admin Server's certifi-

cate is issued.

SSLCertificateID

You can determine this value by referring to the Microsoft Manage-

ment Console and clicking Certificates→Personal→Certificates. The

principal name displays in the Issued To column of the Properties

pane.

Operation Guide 273

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 274: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ValueParameter

The full path to the .dat file that contains the encrypted password

for the private key.private key.

SSLPrivateKeyPwdFile

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:

tm1crypt.exe -pwd abc123 -keyfile btkey.dat -outfile btprk.dat -

validate

the correct parameter value isSSLPrivateKeyPwdFile=C:\Program

Files\Cognos\TM1\bin\btprk.dat

The full path to the .dat file that contains the key used to encrypt

and decrypt the password for the private key.

SSLPwdKeyFile

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:

tm1crypt.exe -pwd abc123 -keyfile btkey.dat -outfile btprk.dat -

validate

the correct parameter value isSSLPwdKeyFile=C:\Program Files\

Cognos\TM1\bin\btkey.dat

Specifies the identity key used to export the Admin Server's certificate

from the Windows certificate store.

SvrSSLExportKeyID

In most cases, the value for SvrSSLExportKeyID will be identical to

the value for SSLCertificateID.

Edit the Tm1s.cfg File

After adding your certificate to the Windows Certificate Store, the Tm1s.cfg file must include the

following parameters:

ValueParameter

Specifies the name of the principal to whom the TM1® Admin

Server's certificate is issued.

AdminSvrSSLCertID

Specifies the identity key used to export the Admin Server's certifi-

cate from the Windows certificate store.

AdminSvrSSLExportKeyID

274 IBM Cognos TM1

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 275: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ValueParameter

Specifies whether the TM1 client should retrieve the certificate

authority certificate, which was originally used to issue the TM1

server's certificate, from the Windows certificate store.

ClientExportSSLSvrCert

If ClientExportSSLSvrCert=T, the certificate authority certificate is

exported from the certificate store when requested by the TM1

client.

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 Windows certificate store.

ClientExportSSLSvrKeyID

Specifies whether the TM1 Admin Server's certificate should be

exported from the Windows certificate store.

ExportAdminSvrSSLCert

If ExportAdminSvrSSLCert=T, the Admin Server's certificate is

exported from the Windows certificate store when the certificate is

requested by the TM1 server.

This parameter must be set to T to enable the TM1 server to retrieve

the certificate from the Certificate Store.

ExportSvrSSLCert

ExportSvrSSLCert=T

The name of the authority that issued your certificate.SSLCertAuthority

You can determine this value by referring to the Microsoft Manage-

ment Console and clicking Certificates, Personal, Certificates. The

authority name displays in the Issued By column of the Properties

pane.

The name of the principal to whom the TM1 Admin Server's certifi-

cate is issued.

SSLCertificateID

You can determine this value by referring to the Microsoft Manage-

ment Console and clicking Certificates→Personal→Certificates.

The principal name displays in the Issued To column of the Proper-

ties pane.

Operation Guide 275

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 276: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ValueParameter

The full path to the .dat file that contains the encrypted password

for the private key.private key.

SSLPrivateKeyPwdFile

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:

tm1crypt.exe -pwd abc123 -keyfile btkey.dat -outfile

btprk.dat -validate

the correct parameter value isSSLPrivateKeyPwdFile=C:\Program

Files\Cognos\TM1\bin\btprk.dat

The full path to the .dat file that contains the key used to encrypt

and decrypt the password for the private key.

SSLPwdKeyFile

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:

tm1crypt.exe -pwd abc123 -keyfile btkey.dat -outfile btprk.dat -

validate

the correct parameter value is SSLPwdKeyFile=C:\Program Files\

Cognos\TM1\bin\btkey.dat

Specifies the identity key used to export the TM1 server's certificate

from the Windows certificate store.

SvrSSLExportKeyID

In most cases, the value for SvrSSLExportKeyID will be identical

to the value for SSLCertificateID.

Using the File SystemIf you want to implement SSL using independent certificates stored on your file system, simply add

your certificate, certificate authority, password files, etc. to the TM1_install_dir\bin\SSL directory

and modify the appropriate TM1® configuration parameters to point to your independent files.

276 IBM Cognos TM1

Chapter 13: Running TM1 in Secure Mode Using SSL

Page 277: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Chapter 14: Managing Users and Groups

This section explains how to manage users and groups in IBM® Cognos® TM1®. In TM1, security

is based on the groups users belong to.

TM1 Users and Groups Security OverviewTM1® manages security by organizing TM1 users into groups. TM1 includes a set of three predefined

administrative groups and also allows you to create your own custom groups. Users can belong to

one or multiple groups.

TM1 has two major types of user groups:

● Administrative Groups - Includes only the predefined groups of ADMIN, DataAdmin and

SecurityAdmin. For more details, see "Understanding Administrative Groups and Authority".

● User Groups - Includes all user-created groups, which typically contain non-administrative

TM1 users.

You can use the TM1 Clients/Groups box to manage TM1 users and groups. The Clients/Groups

dialog box organizes groups and users separately.

As a TM1 administrator, you must be running TM1 Architect or TM1 Perspectives on your machine

to administer security on the IBM® Cognos® TM1 server.

Implementing a TM1 Security SchemeYou can implement a TM1® security scheme to secure objects on a remote server, in the following

way:

Steps

1. Define security groups.

2. Assign access rights to the groups.

3. Define the TM1 users.

4. Assign users to groups.

The security levels you can implement are:

● Cube-level security - Controls access to cubes.

● Element-level security - Controls access to the cells identified by elements.

● Dimension-level security - Controls the ability to add, remove, and reorder the elements

in a dimension. This type of security is independent of cube-level and element-level security,

except when users have no access to a dimension.

● Cell-level security - Controls access to a cell.

Licensed Materials – Property of IBM277© Copyright IBM Corp. 2007, 2011.

Page 278: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Note: A TM1 client and server communicate directly over the network using a TM1 username

and password. This security is completely independent of standard file system security and is

not affected by user rights on network directories or file servers.

TM1 User and Group Security ExamplesTo illustrate IBM® Cognos® TM1® security and allow you to experiment with security features, the

TM1 sample data (Sdata) that is installed with the IBM Cognos TM1 server comes with a set of

pre-defined groups and users.

To view these groups and users, right-click the Sdata server in the Server Explorer and click Security,

Clients/Groups.

The TM1 Clients/Groups dialog box appears.

The following table contains the passwords for the sample users.

Note: Passwords are hidden in the Clients/Groups window and display as either Defined or

Undefined.

Group MembershipPasswordUser Name

ADMINappleAdmin

North AmericaredUsr1

South AmericaorangeUsr2

North America and South

America

blueUsr3

Understanding Administrative Groups and AuthorityTM1® supports the separation of administrative duties and roles in TM1 by dividing administrative

users into the following predefined administrator groups:

● ADMIN group - Members of the ADMIN group have access to all areas of TM1 and represent

super-users with all privileges.

● DataAdmin group - Members in the DataAdmin group have ADMIN privileges to everything

that is not related to security. This group can view, edit and save TM1 objects, such as cubes,

dimensions, rules and processes, Members in this group can view security settings in read-only

mode but are not allowed to modify security settings.

● SecurityAdmin group -The SecurityAdmin group can only perform security operations in TM1.

This includes creating, editing and deleting TM1 users and groups. This group can manage the

access rights of other users to TM1 objects, such as cubes, dimensions and rules, but this group

can not view the data in those same TM1 objects.

278 IBM Cognos TM1

Chapter 14: Managing Users and Groups

Page 279: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The security assignments for these three administrator groups are hard-coded and can not be

modified.

You can use these predefined administrator groups to control and separate TM1 administrative

roles among different users to satisfy internal or external security requirements and rules.

Note: Replication and synchronization operations in TM1 should only be performed by members

of the ADMIN group. Members of the DataAdmin and SecurityAdmin groups do not have all the

required access privileges to perform these operations.

The following sections provide details about each administrative group.

ADMIN GroupThe ADMIN group, which is created for administrative purposes only, should contain only a very

small group of trusted TM1® administrators.

Members of the ADMIN group always have the highest level of security for all objects on the remote

server, and can do the following:

● Assign and revoke other user's access rights.

● Create and delete cubes, dimensions, elements, processes, and chores.

● Add, remove, and reorder elements in a dimension.

● Change cube data.

● Create and delete public views and subsets.

● Reserve and lock cubes, elements, and dimensions, so that other users cannot update them.

● Remove reservations and locks from cubes, elements, and dimensions.

● Create replicated objects on the server.

● Change TM1 cell security.

● Create and delete TM1 rules.

Joint membership in the ADMIN group and SecurityAdmin group or the ADMIN group and the

DataAdmin group is treated as ADMIN.

Members of the ADMIN group are the only TM1 users that can add users to the ADMIN group.

SecurityAdmin GroupThe SecurityAdmin group can only perform security operations in TM1®. Members can access the

security related features of TM1, but can not view the data in non-security TM1 objects, such as

cubes, dimensions and rules. The members in this group are allowed to create, edit and delete TM1

users and groups. Additionally, these users can manage the access rights of other users to TM1

objects such as cubes and dimensions.

If integrated login is not being used, the security administrator is also able to reset user passwords.

Operation Guide 279

Chapter 14: Managing Users and Groups

Page 280: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

As a member of the SecurityAdmin group, you can manage TM1 security using the following tools

in Server Explorer:

● Clients/Groups window - Assign TM1 clients to TM1 groups.

● Security Assignments windows - Control user access to TM1 objects such as cubes, dimensions

and processes.

● Security control cubes - Manually apply security privileges for TM1 objects and user groups.

Restrictions on Replication and Synchronization

Members of the SecurityAdmin group do not have all the required access privileges to perform

replication and synchronization operations in TM1® and should not attempt to perform these

operations.

Restrictions for Rules and Processes

Members in the SecurityAdmin group can not write or modify rules and processes. They can not

view rules, but can view processes in read-only mode. For more details about processes, see the

IBM® Cognos® TM1® Developers Guide.

Combining SecurityAdmin Membership with Other Groups

Membership in the SecurityAdmin group is not intended to be combined with membership in the

DataAdmin group or any other user group. The SecurityAdmin is restricted from accessing non-

security objects and these restrictions always apply regardless of what other groups the user belongs

to. Additionally, TM1 does not allow users to be added to any other user group after they have

been assigned to the SecurityAdmin group.

These restrictions prevent the SecurityAdmin from adding him or herself to another group to gain

access to data or operations that are not allowed for the SecurityAdmin.

Using the SecurityAdmin Group with the TM1 C API

The TM1® C API does not allow programmers to configure joint membership with the SecurityAdmin

group. The ClientGroupAssign function rejects any attempt to place a user that is a member of the

SecurityAdmin group into another group.

Restrictions on Adding Users to the ADMIN Group

Members of the SecurityAdmin group are not allowed to add users to the ADMIN group. Only

members in the full ADMIN group can add other users to the ADMIN group. This prevents the

SecurityAdmin from creating a user account in the ADMIN group that they could then use with

full administrative privileges.

DataAdmin GroupMembers in the DataAdmin group have ADMIN privileges to everything that is not related to

security. Users in this group can view, edit and save TM1® objects, including cubes, dimensions,

rules and processes. The DataAdmin group can view security settings in read-only mode, but is not

allowed to modify any security settings.

280 IBM Cognos TM1

Chapter 14: Managing Users and Groups

Page 281: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

For example, as a member of the DataAdmin group, you can open the Clients/Groups window or

any of the Security Assignments windows for TM1 objects (cubes, dimensions, processes), however

these windows display in read-only mode and you can not make changes.

Membership in User Groups

Combined membership in the DataAdmin group and any other user group is allowed. However,

this combination is treated as the DataAdmin group. Any restrictions imposed by the user group

access are overridden by the DataAdmin access.

For example, if a user is a member of the DataAdmin group and a user group, and that user group

does not have security rights to a cube, the user will still be able to see the cube based on their

DataAdmin rights.

Membership in both the SecurityAdmin and DataAdmin Groups

Membership in the DataAdmin group is not intended to be combined with membership in the

SecurityAdmin group.

If a user belongs to both the DataAdmin group and the SecurityAdmin group, their security rights

are SecurityAdmin only. Being a member in both the SecurityAdmin and DataAdmin group allows

the user to view and edit security settings for the users and groups.

Restrictions on Replication and Synchronization

Members of the DataAdmin group do not have all the required access privileges to perform replica-

tion and synchronization operations in TM1® and should not attempt to perform these operations.

Restrictions on Rules for Security Control Cubes

A DataAdmin can not create rules on security control cubes. This restriction prevents a DataAdmin

from creating a rule that could modify cells in a security control cube.

Adding and Deleting Users and GroupsYou can add and delete users and groups on the TM1® server.

Adding a UserTo add a user, complete the following steps.

Steps

1. Open the Server Explorer.

2. Select the icon for the server you are working with.

3. Right-click the icon and click Security, Clients/Groups.

The Clients/Groups dialog box opens.

4. Click Clients, Add New Client.

The Creating New Client dialog box opens.

Operation Guide 281

Chapter 14: Managing Users and Groups

Page 282: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

5. Enter the name of the new user in the Enter New Client Name box.

Note:TM1® ignores spaces in user names and passwords. For example, TM1 treats Mc Cormick

with a space and the name McCormick without a space as the same name.

6. Click OK.

TM1 adds the user as a new row in the Clients/Groups grid.

When you first add a new user, the user is granted default object security privileges according

to the following rules:

● If user groups are already defined for your server, the new user has None privilege to all

objects on the server. You must assign the user to a group to allow access to TM1 objects.

● If user groups are not defined for your server, the new user has Write privilege to all objects

on the server.

Adding a GroupThe IBM® Cognos® TM1®server can contain up to 65,535 groups. The GroupsCreationLimit

parameter on the server's TM1s.cfg file determines the number of groups you can create during a

single TM1 server session.

Steps

1. Open the Server Explorer.

2. Select the icon for the server you are working with.

3. Right-click the server icon, and click Security, Clients/Groups.

The Clients/Groups dialog box displays.

4. Click Groups, Add New Group.

The Creating New Group dialog box displays.

5. Enter the name of the new group in the Enter New Group Name box.

6. Click OK.

TM1 adds the group as a new column in the Clients/Groups dialog box.

Note: By default, you can add up to 20 groups per session. To increase the number of groups

you can add per session, change the value of the GroupsCreationLimit parameter in the TM1s.cfg

file.

Deleting a UserTo delete a user, complete the following steps.

Steps

1. From the Server Explorer, right-click the server icon, and click Security, Clients/Groups.

2. In the Clients/Groups dialog box, click the user you want to delete.

282 IBM Cognos TM1

Chapter 14: Managing Users and Groups

Page 283: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

3. Click Clients, Delete Client.

4. Click Yes to confirm the deletion.

Deleting a GroupTo delete a group, complete the following steps.

Steps

1. From the Server Explorer, right-click the server icon, and click Security→Clients/Groups.

2. In the Clients/Groups dialog box, click a cell in the column that represents the group you want

to delete.

3. Click Groups, Delete Group.

4. Click Yes to confirm the deletion.

Assigning Users to GroupsYou can assign users to a group as follows:

Steps

1. From the Server Explorer, right-click the server icon, and click Security, Clients/Groups.

2. In the Clients/Groups dialog box, click the check box at the intersection of the user name and

the group name.

3. Click OK.

Membership in Multiple GroupsA user who is a member of multiple groups receives the highest level of rights from all groups.

For example, in the sample data, Usr3 is a member of two groups.

● North America, which has Write access to the Canada, Mexico, and United States elements in

the Region dimension, and Read access to the other elements in the Region dimension.

● South America, which has Write access to the Argentina, Brazil, Chile, and Uruguay elements

in the Region dimension, and Read access to the other elements in the Region dimension.

TM1® gives Usr3Write access to the Argentina, Brazil, Canada, Chile, Mexico, United States, and

Uruguay elements, and Read access to the other elements in the Region dimension.

Securing TM1 DataBecause your company uses TM1® for high-level planning and analysis, TM1 data can be sensitive

and confidential. TM1 provides all the tools you need to secure your data, but as with any security

Operation Guide 283

Chapter 14: Managing Users and Groups

Page 284: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

system, real security is only as good as the procedures you implement. We suggest implementing

the following procedures to enhance TM1 security:

● Restricting Access to the Data Directory.

● Assigning Passwords.

● Using Standard Security for Passwords.

Restricting Access to the Data DirectoryUsing your network file system security, you should always protect the data directory so it is

invisible to everyone but the network login used by the server itself. No matter how elaborate the

security on the server, if users can see the data directory, they can view data using TM1® directly

from the disk, without connecting to the TM1 server.

Assigning PasswordsMembers of the ADMIN group have rights similar to those of super users or root users on network

systems; they can go anywhere and do anything. Give out ADMIN passwords carefully, and be

sure ADMIN users know they should not reveal or share their passwords with anyone.

Using Standard Security for PasswordsTreat TM1® passwords the same way as other network passwords. Be sure that users know not to

share passwords. Also, either encourage or require users to change their passwords often.

Setting and Clearing PasswordsYou can set, clear, and change passwords for users.

● Passwords can contain any keyboard character.

● Passwords are not case sensitive. For example, the password ABC123 is equivalent to abc123.

● Spaces are allowed in passwords, but spaces are ignored by the TM1® server. The TM1 server

considers the password ABC 123 DEF to be equivalent to ABC123DEF.

Setting a PasswordYou can set up a password.

Steps

1. From the Server Explorer, right-click the server icon, and click Security, Clients/Groups.

2. In the Clients/Groups dialog box, click the cell at the intersection of the user name and the

Password column.

The cell contains the value of Undefined.

3. Type the new password for the user and press Enter.

284 IBM Cognos TM1

Chapter 14: Managing Users and Groups

Page 285: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

A password can contain a maximum of 256 characters.

TM1® prompts you to retype the new password.

4. Retype the password and click OK.

The cell now contains a value of Defined.

5. Click OK.

Clearing a PasswordTo clear a password, complete the following steps.

Steps

1. From the Server Explorer, right-click the server icon, and click Security, Clients/Groups.

2. In the Clients/Groups dialog box, select the cell at the intersection of the Password column and

the user name.

3. Click Clients, Clear Password.

TM1® asks you to confirm whether you really want to clear the password.

4. Click Yes.

TM1 clears the password, and displays a value of Undefined in the cell.

5. Click OK.

Note: When you clear a password, the user can re-establish it the next time they log in to the

TM1® server.

Changing a PasswordNote: You can change your password any time you are connected to a remote server. Users who

are not administrators can do the same.

Steps

1. In the Server Explorer, select the icon for the server you are working with.

2. Click Server, Security, Change Password.

The Password Change dialog box displays.

3. Type the new password in the Password box, and click OK.

TM1® prompts you to retype the new password.

4. Retype the password, and click OK.

Operation Guide 285

Chapter 14: Managing Users and Groups

Page 286: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Setting an Expiration for a UserWhen you add a user to TM1®, you can set a limit on the number of days the user can access the

server.

Steps

1. From the Server Explorer, right-click the server icon, and click Security, Clients/Groups.

2. In the Clients/Groups dialog box, in the cell at the intersection of the user name and the Expi-

ration Days column, enter the number of days you want to allow the user to access the TM1

server.

After the specified number of days, the user will not be able to log in to the server.

3. Click OK.

286 IBM Cognos TM1

Chapter 14: Managing Users and Groups

Page 287: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Appendix A: Control Cubes

This appendix describes the control cubes that IBM® Cognos® TM1® uses.

The IBM CognosTM1 server automatically generates the control cubes. By default, logging is

enabled for all control cubes.

In this appendix, the following information is provided for each control cube:

● Purpose

● Dimensions that form the cube

Note: For a complete description of the control dimensions, see Control Dimensions.

To toggle the display of control cubes and other control objects in Server Explorer, click View,

Display Control Objects. All control cubes appear in Server Explorer with a prefix of a right curly

brace ( }). For example, }CellSecurity_SalesCube.

Security Control CubesSecurity control cubes apply security privileges for TM1® objects to user groups on the TM1 server.

Most of these control cubes are populated with the privileges assigned in the TM1 Security

Assignments window, but you can also apply privileges directly in the control cubes. However, you

cannot apply privileges to the ADMIN group; this group always has ADMIN privileges to all objects

on the TM1 server.

}CellSecurity_CubeNameTM1® creates an empty }CellSecurity_CubeName control cube when you initiate the process of

defining the cell-level security. To do so, select a cube in Server Explorer, and click Security, Create

Cell Security Cube. You can use the control cube to define the cell-level security for the selected

cube. TM1 applies the cell-level security to the user groups.

The cells in a }CellSecurity_CubeName control cube can contain one of the following three strings,

which correspond to the security privileges that you can assign to the cells:

● Read

● Write

● None

For details on defining the cell-level security and for definitions of the security privileges, see the

IBM® Cognos® TM1® Developer Guide.

Licensed Materials – Property of IBM287© Copyright IBM Corp. 2007, 2011.

Page 288: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Dimensions

A }CellSecurity_CubeName cube contains all the dimensions that are present in the cube for which

you want to define the cell-level security. In addition, a }CellSecurity_CubeName cube contains the

following dimension:

ElementsDimension

Each user group defined for the TM1 server.}Groups

For example, if you create a cell security control cube for SalesCube in the TM1 sample data, the

resulting }CellSecurity_SalesCube cube contains all the dimensions of SalesCube (actvsbud, region,

model, account1,and month), and the }Groups dimension.

}ChoreSecurityThe }ChoreSecurity control cube stores security privileges for all chores on the TM1® server. This

control cube is populated with the values applied in the TM1 Security Assignments window, which

you can access by clicking Chores, Security Assignments in Server Explorer.

You can also enter security privileges directly in the }ChoreSecurity cube.

The cells in the }ChoreSecurity cube can contain the string Read, which assigns the Read security

privilege. The cells can also be left empty, which assigns the None security privilege.

For details on using the TM1 user interface to define chore security and for definitions of security

privileges, see the IBM® Cognos® TM1® Developer Guide.

Dimensions

The }ChoreSecurity controlcube contains the following dimensions:

ElementsDimension

Each chore currently defined on the TM1 server.}Chores

Each user group defined for the TM1 server.}Groups

}ClientSecurityThe }ClientSecurity control cube defines user group access to properties for individual clients on

the TM1® server.

For example, in the standard SData sample database that is included with the TM1 server, the

ADMIN group has ADMIN access to properties for all clients on the server. The North America

and South America groups have READ access to properties for all clients on the server.

For example, in the standard SData sample database that is included with the TM1 server, the

ADMIN and DataAdmin groups have ADMIN access to properties for all clients on the server. The

SecurityAdmin group has READ access to properties for all clients on the server, and the North

America and South America groups have NONE access to properties.

288 IBM Cognos TM1

Appendix A: Control Cubes

Page 289: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The access privileges defined in the }ClientSecurity cube are important because several API functions

require specific privileges to read and/or set client properties. For instance, the

TM1ClientPasswordAssign function can be used only by clients who are members of a group with

ADMIN access to properties, for the client to whom a password is assigned. Similarly, the

TM1ObjectPropertyGet function requires READ access to client properties, while

TM1ObjectPropertySet requires WRITE access.

TM1 does not populate this cube through the UI, nor is access assigned when you create a new user

or new group. You must assign access privileges directly in the }ClientSecurity cube.

}CubeSecurityThe}CubeSecurity control cube stores security privileges for all cubes, including other control cubes

on the TM1® server.

This control cube is populated with the values applied in the TM1 Security Assignments window,

which you can access by clicking Cubes, Security Assignments in Server Explorer.

You can also enter security definitions directly in the }CubeSecurity cube.

The cells in the }CubeSecurity control cube can contain one of the following five strings, which

correspond to the security privileges that you can assign to cubes:

● Read

● Write

● Reserve

● Admin

● Lock

The cube does not accept the string None. To assign the None privilege to a cube, leave the

appropriate cell in the }CubeSecurity cube empty.

For details on defining cube security through the TM1 user interface and for definitions of security

privileges, see the IBM® Cognos® TM1® Developer Guide.

Dimensions

The }CubeSecurity control cube contains the following dimensions:

ElementsDimension

Cubes available on the TM1 server.}Cubes

Groups defined for the TM1 server.}Groups

}DimensionSecurityThe}DimensionSecurity control cube stores security definitions for all dimensions, including control

dimensions on the TM1® server.

Operation Guide 289

Appendix A: Control Cubes

Page 290: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

This control cube is populated with the values applied in the TM1 Security Assignments window,

which you can access by clicking Dimensions, Security Assignments in Server Explorer.

You can also enter security definitions directly in the }DimensionSecurity cube.

The cells in the }DimensionSecurity control cube can contain one of the following five strings, which

correspond to the security privileges that you can assign to dimensions:

● Read

● Write

● Reserve

● Admin

● Lock

The cube does not accept the string None. To assign the None privilege to a dimension, leave the

appropriate cell in the }DimensionSecurity cube empty.

For details on defining dimension security through the TM1 user interface and for definitions of

security privileges, see the IBM® Cognos® TM1® Developer Guide.

Dimensions

The }DimensionSecurity control cube contains the following dimensions:

ElementsDimension

Dimensions available on the TM1 server.}Dimensions

Groups defined for the TM1 server.}Groups

}ElementSecurity_DimensionNameThe }ElementSecurity_DimensionName control cube stores security definitions for all the elements

in the DimensionName dimension. A unique }ElementSecurity_DimensionName cube exists for

each dimension for which you have defined element security.

This control cube is populated with the values applied in the TM1® Security Assignments window,

which you can access by selecting a dimension and clicking Dimension,Security, Elements Security

Assignments in Server Explorer.

You can also enter security definitions directly in an }ElementSecurity_DimensionName cube.

The cells in this control cube can contain one of the following five strings, which correspond to the

security privileges that you can assign to dimensions:

● Read

● Write

● Reserve

290 IBM Cognos TM1

Appendix A: Control Cubes

Page 291: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● Admin

● Lock

The cube does not accept the string None. To assign the None privilege to an element, leave the

appropriate cell in the control cube empty.

For details on defining element security through the TM1 user interface and for definitions of

security privileges, see the IBM® Cognos® TM1® Developer Guide.

Dimensions

An }ElementSecurity_DimensionName cube contains the following dimensions:

ElementsDimension

All elements of the dimension are present.DimensionName

Groups defined for the TM1 server.}Groups

}ProcessSecurityThe }ProcessSecurity control cube stores security definitions for all TurboIntegrator processes on

the TM1® server.

Dimensions

The }ProcessSecurity cube contains the following dimensions:

ElementsDimension

All processes defined on the TM1 server.}Processes

Groups defined for the TM1 server.}Groups

Client and Group Administration Control CubesThe client and group administration control cubes assign clients to user groups and store properties

for all clients on the TM1® server.

}ClientsGroupsThe }ClientsGroups cube stores group assignments for all clients on the TM1® server. This control

cube is populated with values that reflect the assignments applied in the Clients/Groups window,

which you can access by clicking Server, Security, Clients/Groups in Server Explorer. You can also

enter values directly in the }ClientsGroups cube.

For details on assigning clients to user groups, see the IBM® Cognos® TM1® Developer Guide.

Operation Guide 291

Appendix A: Control Cubes

Page 292: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

The cells in the }ClientsGroups cube contain strings that assign clients to one or more of the user

groups available on the TM1 server.

In this example:

● Admin client is assigned to the ADMIN group

● Usr1 client is assigned to the North America group

● Usr2 client is assigned to the South America group

● Usr3 client is assigned to both the North America and South America groups

Dimensions

The }ClientsGroups control cube contains the following dimensions:

ElementsDimension

Clients currently defined for the TM1 server.}Clients

Groups defined for the TM1 server.}Groups

}ClientPropertiesThe}ClientProperties control cube stores property values for all clients on the TM1® server. You

can use client properties to define a client password, the maximum number of connections allowed,

client status, and more.

The }ClientProperties cube is populated with values that reflect the settings in the Clients/Groups

window, which you can access by clicking Server, Security, Clients/Groups from Server Explorer.

A MaximumPorts value of 0 for a client in the }ClientProperties cube indicates that a maximum

port limit is not defined for the client.

You can enter or edit values for MaximumPorts and PasswordExpirationDays directly in the

}ClientProperties cube.

Note: You should not edit values for PASSWORD directly in the cube. The passwords are stored

in the cube in an encrypted format; if you edit passwords directly in the cube, the passwords are

unusable and prevent clients from logging on to the TM1 server.

Dimensions

The }ClientProperties cube contains the following dimensions:

ElementsDimension

Clients currently defined for the TM1 server.}Clients

292 IBM Cognos TM1

Appendix A: Control Cubes

Page 293: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ElementsDimension

Properties that can be set for TM1 clients, including Password, Pass-

wordExpirationDays, and MaximumPorts.

}ClientProperties

For complete details on this dimension, see Control Dimensions.

Object Attribute and Property Control CubesThe object attribute and property control cubes store attribute and property values for objects on

the TM1® server.

● }ConnectionProperties.

● }CubeProperties.

● }DimensionProperties.

● }DimensionAttributes.

● }ElementAttributes_DimensionName.

}ConnectionPropertiesThe }ConnectionProperties control cube stores property values for all replication connections on

the TM1® server. The replication connection properties define the client and password to establish

a replication connection, and the synchronization status for the star and planet servers.

Dimensions

The }ConnectionProperties cube contains the following dimensions:

ElementsDimension

Replication connections defined for the TM1 server.}Connections

Properties that can be set for replication connections, including

User, Password, Syncstar and Syncplanet.

}ConnectionProperties

For complete details on this dimension, see Control Dimensions.

}CubePropertiesThe }CubeProperties control cube stores property values for all cubes, both native and replicated,

on the TM1® server. This control cube is populated with values that reflect the settings in the Cube

Properties dialog box, which you can access by selecting a cube and clicking Cube, Properties in

Server Explorer.

Operation Guide 293

Appendix A: Control Cubes

Page 294: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

With replicated cubes, the }CubeProperties cube is populated with values that reflect the settings

in the Replicate Cube dialog box, which you can access by selecting a cube under a replication

connection and clicking Cube, Replicate from Server Explorer.

The }CubeProperties control cube also stores several properties that can only be set directly in the

control cube, such as VMM and VMT.

The cube properties define how a cube is loaded on the TM1 server, which dimension to use as a

measures dimension, which dimension to use as a time dimension, and whether cube logging is

enabled. With replicated cubes, the values in the }CubeProperties cube also define the source cube

for a replication, the replication status of a cube, and whether rules and views should be synchro-

nized.

Dimensions

The }CubeProperties cube contains the following dimensions:

ElementsDimension

Cubes available on the TM1 server.}Cubes

Properties that can be set for cubes.}CubeProperties

For complete details on this dimension, see Control Dimensions.

}DimensionPropertiesThe }DimensionProperties control cube stores property values for all dimensions, both native and

replicated, on the TM1® server. This control cube is populated with values that reflect the settings

in the DimensionElementOrdering dialog box, which you can access by selecting a dimension and

clicking Dimension, Set Elements Order from Server Explorer.

With replicated cubes, the }DimensionProperties cube is also populated with values that reflect the

settings in the Replicate Cube dialog box, which you can access by selecting a cube under a replication

connection and clicking Cube, Replicate in Server Explorer.

The dimension properties define how a dimension is loaded and sorted on the TM1 server. With

replicated dimensions, the values in the }DimensionProperties cube also define the source dimension

for a replicated dimension, the replication status of a dimension, and whether subsets and attributes

should be synchronized.

Dimensions

The }DimensionProperties cube contains the following dimensions:

ElementsDimension

Dimensions available on the TM1 server.}Dimensions

294 IBM Cognos TM1

Appendix A: Control Cubes

Page 295: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ElementsDimension

Properties that can be set for dimensions.}DimensionProperties

For complete details on this dimension, see Control Dimen-

sions.

}DimensionAttributesThe }DimensionAttributes control cube stores attribute values for all dimensions, both native and

replicated, on the TM1® server.

This control cube cube is populated with values that reflect the settings in the Attributes Editor

window, which you can access by selecting a Dimensions group and clicking Dimensions, Edit

Attributes from Server Explorer. You can also enter attribute values directly in the }DimensionAt-

tributes cube.

Dimensions

The }DimensionAttributes cube contains the following dimensions:

ElementsDimension

Dimensions available on the TM1 server.}Dimensions

Attributes that have been defined for dimensions on the TM1

server.

}DimensionAttributes

}ElementAttributes_DimensionNameThe }ElementAttributes_DimensionName control cube stores element attribute values for the

DimensionName dimension. A unique }ElementAttributes_DimensionName cube exists for each

dimension for which you have defined element attributes.

An }ElementAttributes_DimensionName cube is populated with values that reflect the settings in

the Attributes Editor window, which you can access by selecting a dimension and clickingDimension,

Edit Element Attributes in Server Explorer. You can also enter element attribute values directly in

an }ElementAttributes_DimensionName cube.

Dimensions

An }ElementAttributes_DimensionName cube contains the following dimensions:

ElementsDimension

All elements of the dimension are present.DimensionName

Operation Guide 295

Appendix A: Control Cubes

Page 296: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ElementsDimension

Element attributes defined for the DimensionName dimension.}ElementAttributes_Dimension-

Name For details on defining element attributes, see the IBM® Cog-

nos® TM1® Developer Guide.

}HierarchyPropertiesThe }HierarchyProperties control cube stores custom named levels for the hierarchy levels of TM1®

dimensions.

You can enter your own names for these levels in the }HierarchyProperties control cube and then

use these names outside of TM1 to access TM1 data with IBM® Cognos® Report Studio, MDX

statements or other MDX OLAP tools. You can also use this control cube to assign a default

member for the dimension.

For details on using named levels with dimensions, see the related section in the IBM® Cognos®

TM1® Developer Guide.

Dimensions

The }HierarchyProperties cube contains the following dimensions:

ElementsDimension

Contains a list of all the dimension names in the TM1

server.

}Dimensions

Includes only one element for assigning named levels to

the selected dimension.

}Hierarchies

Includes the following two types of elements}HierarchyProperties

● A single element, named defaultMember, for assign-

ing the default member of the dimension.

● A set of 21 elements (level000 - level020) for

assigning names to the dimension hierarchy levels.

For more details, see "}HierarchyProperties" (p. 306).

Performance Monitoring Control CubesTM1® includes a performance monitoring feature that lets you record performance statistics for

clients, cubes, and servers. When you enable performance monitoring, TM1 populates the perfor-

mance monitoring control cubes on a minute-by-minute basis. You can then browse these cubes to

analyze server performance.

296 IBM Cognos TM1

Appendix A: Control Cubes

Page 297: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Performance monitoring is enabled on a per-server basis. To enable performance monitoring for a

server, select the server in Server Explorer and click Server, Start Performance Monitor. For details

on performance monitoring, see Remote Server Operations.

}StatsByClientFor each client on the server, the }StatsByClient control cube tracks the message count, average

message size, total elapsed time, and other measures.

Dimensions

The }StatsByClient cube contains the following dimensions:

ElementsDimension

This dimension contains the following measures:}StatsStatsByClient

Message Count

Message Bytes

Request Count

Elapse Time

Bytes/Message

Measures are described in Control Dimensions.

Each client on the server, plus the consolidated element Clients Total,

which is a consolidation of all clients.

}PerfClients

See a description of the }TimeIntervals dimension in Control Dimensions.}TimeIntervals

}StatsByCubeFor each cube on the server, the}StatsByCube control cube tracks memory use, the number of

populated string cells, populated numeric cells, stored calculated cells, fed cells, and stored views.

Dimensions

The }StatsByCube cube contains the following dimensions:

Operation Guide 297

Appendix A: Control Cubes

Page 298: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ElementsDimension

This dimension contains the following measures:}StatsStatsByCube

Memory Used for Views: Counts views which have been opened.

Counts all views, whether private or public, regardless of user.

It is NOT dependent on who happens to be logged in.

Number of Stored Views: Counts all views which have been

opened, whether private or public, regardless of user. Includes

all views which have been looked at.

Number of Stored Calculated Cells

Number of Populated String Cells

Number of Populated Numeric Cells

Number of Fed Cells

Memory Used for Calculations

Memory Used for Feeders

Memory Used for Input Data

Total Memory Used

This dimension contains numeric elements for each cube on the

server, plus the consolidated element Cubes Total, which is a

consolidation of all clients.

}PerfCubes

See a description of the }TimeIntervals dimension in Control

Dimensions.

}TimeIntervals

}StatsByCubeByClientFor each client and cube on the server, the }StatsByCubeByClient control cube tracks the number

and elapsed time of cell updates, cell retrievals, view calculations, and view retrievals.

Cell updates do not work when setting cells in a view via Architect.

Dimensions

The }StatsByCubeByClient cube contains the following dimensions:

ElementsDimension

Each client on the server, plus the consolidated element Clients

Total, which is a consolidation of all clients.

}PerfClients

Each cube on the server, plus the consolidated element Cubes

Total, which is a consolidation of all cubes.

}PerfCubes

298 IBM Cognos TM1

Appendix A: Control Cubes

Page 299: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ElementsDimension

This dimension contains the following numeric elements:}CubeFunctions

Cell Update

Cell Retrieval

View Calculation

View Retrieval

For complete details on this dimension, see Control Dimensions.

This dimension contains the following measures:}StatsStatsByCubeByClient

Count

Elapse Time (milliseconds)

For complete details on this dimension, see Control Dimensions.

See a description of the }TimeIntervals dimension in Control

Dimensions.

}TimeIntervals

}StatsForServerThe }StatsForServer control cube tracks the connected clients, active threads, and memory used for

the server.

Dimensions

The }StatsForServer cube contains the following dimensions:

ElementsDimension

This dimension contains the following measures:}StatsStatsForServer

Number of Connected Clients

Number of Active Threads

Memory Used (KB)

Memory in Garbage (KB)

For complete details on this dimension, see Control Dimensions.

See a description of the }TimeIntervals dimension in Control

Dimensions.

}TimeIntervals

Other Control CubesThe following sections describe all other control cubes available on the TM1® server.

Operation Guide 299

Appendix A: Control Cubes

Page 300: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

}Hold_UserName_CubeNameThe }Hold_UserName_CubeName control cube tracks the cells held by the UserName client on the

CubeName cube.

Dimensions

The }Hold_UserName_CubeName cube contains the following dimensions:

ElementsDimension

This dimension contains the following elements:}Hold

OriginalVal

Hold Status

For complete details on this dimension, see Control

Dimensions.

The }Hold_UserName_CubeName cube also contains all of the dimensions present in the CubeName

cube. For example, the }Hold_Admin_Sales cube contains the }Hold dimension as well as all the

dimensions present in the Sales cube.

300 IBM Cognos TM1

Appendix A: Control Cubes

Page 301: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Appendix B: Control Dimensions

This appendix describes the control dimensions that IBM® Cognos® TM1® uses to track performance

statistics, administer security, manage clients and groups, and store object attributes and properties.

The following information is provided for each dimension:

● Description of dimension elements

● Control cubes that use the dimension

}ChoresThe }Chores dimension is used only in the }ChoreSecurity control cube. The dimension contains

string elements corresponding to the names of the chores defined on the IBM® Cognos® TM1®

server.

}ClientPropertiesThis }ClientProperties dimension is used only in the }ClientProperties control cube. The dimension

contains the following string elements that corresponds to the following properties that can be

defined for clients on the IBM® Cognos® TM1® server.

DescriptionElement

Indicates the maximum number of ports (connections) that an individual

client can open on the TM1 server.

MaximumPorts

Stores and displays the client password in an encrypted form.PASSWORD

Indicates the number of days for which a given client's password remains

valid.

PasswordExpiration-

Days

Indicates the last time (GMT) the password for a given client was

updated. The time format is yyyymmddhhss .

PasswordLastTimeUp-

dated

When a client is logged on to the TM1 server, the STATUS value is

ACTIVE. Otherwise the STATUS value is empty.

STATUS

Licensed Materials – Property of IBM301© Copyright IBM Corp. 2007, 2011.

Page 302: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

}ClientsThe }Clients dimension contains string elements that correspond to the clients defined on the IBM®

Cognos® TM1® server. This dimension is used in the }ClientGroups and }ClientProperties control

cube.

}ConnectionPropertiesThe }ConnectionProperties dimension is used only in the }ConnectionProperties control cube. This

dimension contains the following string elements that correspond to the properties that can be

defined for replication connections on the IBM® Cognos® TM1® server.

DescriptionElement

Determines if the replication connection uses Integrated Login. If the

connection uses Integrated Login, the value of this property is YES,

otherwise the value is NO.

INTEGRATEDSECU-

RITY

Time (GMT) at which the data was last synchronized on the planet

server, from which the replication connection was established. The

time format is yyyymmddhhss.

LASTSYNC

Time (GMT) at which the data was last synchronized on the star server

for the replication connection. The time format is yyyymmddhhss.

LASTSYNCSTAR

The namespace ID of the Cognos namespace when establishing a

replication connection to a server that uses IBM Cognos 8 security.

Note that this property stores the ID of the Cognos namespace, not

the descriptive name of the namespace.

NAMESPACE

Stores and displays the password in an encrypted format for establishing

a replication connection.

PASSWORD

Determines if the data on the planet server is updated during the syn-

chronization process. If the data on the planet server is updated, the

value of this property is YES, otherwise the value is NO.

SYNCPLANET

Determines if the data on the star server is updated during the synchro-

nization process. If the data on the star server is updated, the value of

this property is YES, otherwise the value is NO..

SYNCSTAR

For a given replication connection, stores the name of the user who

established the connection.

USER

302 IBM Cognos TM1

Appendix B: Control Dimensions

Page 303: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

}ConnectionsThe }Connections dimension contains string elements that correspond to the replication connections

defined on the IBM® Cognos® TM1® server. This dimension is used only in the }ConnectionProperties

control cube.

}CubeFunctionsThe }CubeFunctions dimension is used only in the }StatsByCubeByClient control cube. The

dimension contains the following string elements corresponding to functions that can be performed

on a cube:

DescriptionElement

Cells retrieved by a user in a non-stored view. This metric includes

calculated cells, such as rules, consolidations, and user-defined calcula-

tions.

Cell Retrieval

Cell updates include user input through the Cube Viewer, In-Spread-

sheet Browser, TM1® Web, and slices.

Cell Update

Cells updated through rule calculations or other methods are not

included in this metric.

Number of views requested, which can be user requests for Cube Viewer

or slices.

View Calculation

Number of views requested and displayed.View Retrieval

}CubePropertiesThe }CubeProperties dimension is used only in the }CubeProperties control cube. The dimension

contains the following string elements corresponding to the properties that can be defined for cubes

on the IBM® Cognos® TM1® server.

DescriptionElement

Indicates if a cube is automatically loaded when the server starts or is

loaded 'on demand' only when a cube value is requested.

DemandLoad

When a cube is loaded on demand, the value of the DemandLoad

property is YES, otherwise the property value is NO.

When a cube is locked, this property stores the name of the TM1 client

that has locked the cube.

Lock

Operation Guide 303

Appendix B: Control Dimensions

Page 304: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionElement

Indicates if logging is enabled for a given cube. When cube logging is

enabled, the value of this property is YES, otherwise the value is NO.

Logging

If a measures dimension has been defined for a given cube, this property

stores the name of the dimension.

Measures_Dimension

For replicated cubes, this property stores the name of the replication

connection with which the replicated cube is associated.

Replication

For replicated cubes, this property stores the name of the source cube.RepSrcName

If a cube is replicated on the server, the value of RepStatus is Copied,

otherwise this property value is empty.

RepStatus

For replicated cubes, this property indicates whether rules are synchro-

nized when the associated cube is synchronized.

SyncRule

For replicated cubes, this property indicates whether views are synchro-

nized when the associated cube is synchronized.

SyncViews

If a time dimension has been defined for a given cube, this property

stores the name of the dimension.

Time_Dimension

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. You must,

however, make sure sufficient memory is available for the TM1 server

to load all cubes.

VMM

If no VMM value is specified the default value is 65,536 bytes. The valid

range is 16,384 - 4,2934,943,296 bytes.

For each cube, this property defines the time threshold, in seconds,

beyond which the algorithm that stores TM1 stargate views is triggered.

VMT

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.

If no VMM value is specified the default value is five seconds. The valid

range is 1 - 259,200 seconds.

For details on stargate views, see About Startgate Views.

304 IBM Cognos TM1

Appendix B: Control Dimensions

Page 305: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

}CubesThe }Cubes dimension contains string elements corresponding to the cubes, including control cubes,

on the IBM® Cognos® TM1® server. The }Cubes dimension is used only in the }DimensionAttributes

control cube.

}DimensionAttributesThe }DimensionAttributes dimension contains numeric elements that correspond to the attributes

defined for dimensions on the IBM® Cognos® TM1® server. The }DimensionAttributes dimension

is used in the }CubeSecurity and }CubeProperties control cube.

}DimensionPropertiesThe }DimensionProperties dimension is used only in the }DimensionProperties control cube. The

}DimensionProperties dimension contains the following string elements that correspond to the

properties that can be defined for dimensions on the IBM® Cognos® TM1® server.

DescriptionElement

Not currently used.Default_Hierarchy

Not currently used.DemandLoad

Time (GMT) at which a dimension was last updated. The time format

is yyyymmddhhss.

Last_Time_Updated

When a dimension is locked, this property stores the name of the TM1

client that has locked the dimension.

Lock

For replicated cubes, this property stores the name of the replication

connection with which the replicated cube is associated.

Replication

For replicated dimensions, this property stores the name of the source

dimension.

RepSrcName

If a dimension is replicated on the server, the value of RepStatus is

Copied. Otherwise the RepStatus value is empty.

RepStatus

Not currently used.SortComponentsSense

Not currently used.SortComponentsType

When dimension elements are sorted automatically, this property stores

the sense applied to the selected sorting. Elements can be sorted in

either the Ascending or Descending sense.

SortElementsSense

Operation Guide 305

Appendix B: Control Dimensions

Page 306: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionElement

When dimension elements are sorted automatically, this property stores

the type of sorting used. There are three types of automatic element

sorting: ByName, ByLevel, and ByHierarchy.

SortElementsType

For replicated cubes, this property indicates whether element attributes

are synchronized when the associated dimension is synchronized.

SyncAttributes

For replicated cubes, this property indicates whether subsets are syn-

chronized when the associated dimension is synchronized.

SyncSubsets

}DimensionsThe }Dimensions dimension contains string elements the correspond to the dimensions, including

control dimensions, on the IBM® Cognos® TM1® server. The }Dimensions dimension is used only

in the }DimensionsProperties control cube.

}ElementAttributes_DimensionNameThe}ElementAttributes_DimensionName dimension contains numeric elements that correspond to

the element attributes defined for the DimensionName dimension. The }ElementAttributes_

DimensionName dimension is used only in the }ElementAttributes_DimensionName control cube.

}GroupsThe }Groups dimension contains string elements that correspond to the user groups defined on the

IBM® Cognos® TM1® server. The }Groups dimension is used only in the }ClientGroups control

cube.

}HierarchiesThe }Hierarchies dimension is used in the }HierarchyProperties control cube.

This dimension contains only one element, named hierarchy0, that is used with the }HierarchyProp-

erties dimension to assign named levels to the hierarchy levels of a TM1® dimension.

}HierarchyPropertiesThe }HierarchyProperties dimension is used in the }HierarchyProperties control cube, along with

the }Hierarchies dimension to assign named levels to the hierarchy levels of a TM1® dimension.

The }HierarchyProperties dimension contains the following elements:

306 IBM Cognos TM1

Appendix B: Control Dimensions

Page 307: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionElement

A string element that stores the name of the default

member of the dimension.

defaultMember

The element name you enter here may filter the

dimension when TM1 data is retrieved from an

external application like IBM® Cognos® Report Stu-

dio.

Use the name of the top element in the dimension

hierarchy so all the dimension elements are retrieved

by default.

A set of string elements that store custom names for

the hierarchy levels of a dimension.

level000 - level020

}HoldThe }Hold dimension is used in any }Hold_UserName_CubeName cubes. UserName is the name

of the TM1® user who has applied holds against cube values, while CubeName is the name of the

cube in which values are being held.

The }Hold dimension contains the following elements:

DescriptionElement

This numeric element tracks the most recent value of leaf cells that

are edited in the CubeName cube. These most recent values are

used for several data spreading methods and should not be edited.

OriginalVal

This string element identifies cells held by UserName in the Cube-

Name cube.

HoldStatus

A value of H indicates that UserName has applied a leaf hold to a

cell. A value of C indicates that UserName has applied a consolida-

tion hold against a cell.

}PerfClientsThe }PerfClients dimension contains numeric elements that correspond to the clients defined on the

IBM® Cognos® TM1® server as well as a consolidation of all clients named Clients Total. The

}PerfClients dimension is used in the following performance monitoring cubes:

● }StatsbyClient

● }StatsByCube

Operation Guide 307

Appendix B: Control Dimensions

Page 308: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

● }StatsByCubeByClient

The }PerfClients dimension differs from the }Clients dimension in that the }PerfClients dimension

contains numeric elements, while the }Clients dimension contains string elements.

}PerfCubesThe }PerfCubes dimension contains numeric elements that correspond to the cubes on the IBM®

Cognos® TM1® server and a consolidation of all cubes named Cubes Total. The }PerfCubes

dimension is used in the }StatsByCube and }StatsByCubeByClient performance monitoring cubes.

The }PerfCubes dimension differs from the }Cubes dimension in that the }PerfCubes dimension

contains numeric elements, while the }Cubes dimension contains string elements.

}ProcessesThe }Processes dimension contains string elements that correspond to the TurboIntegrator processes

defined on the IBM® Cognos® TM1® server. The }Processes dimension is used only in the }ProcessSe-

curity control cube.

}StatsStatsByClientThe }StatsStatsByClient dimension is used in the }StatsByClient control cube. This dimension contains

the following measures:

DescriptionElement

Average number of bytes per message. The value for this element

is calculated by the statement ['Bytes/Message']=['Message

Bytes']/['Message Count'] in the rule for the }StatsByClient cube.

Bytes/Message

Time (in milliseconds) required to process requests to the TM1

server.

Elapse Time (ms)

Number of bytes that have been sent across in the requests.Message Bytes

A message is a request to the TM1 server for a list of objects, such

as a list of dimensions,

Message Count

Measures the number of requests for information from the TM1

server.

Request Count

308 IBM Cognos TM1

Appendix B: Control Dimensions

Page 309: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

}StatsStatsByCubeThe }StatsStatsByCube dimension is used only in the }StatsByCube control cube. This dimension

tracks performance statistics when performance monitoring is enabled, and contains the following

elements:

DescriptionElement

This metric measures the memory used in all TM1® calculations,

including consolidations, rules, and user-defined calculations.

Memory Used for Calcula-

tions

This metric measures the amount of memory used to feed cells

through TM1 rules.

Memory Used for Feeders

This includes memory allocated to data loaded through TurboIn-

tegrator or process worksheets. This measures the memory used

for all data input other than slice or Cube Viewer input.

Memory Used for Input Data

This metric measured the amount of memory, in bytes, used to

store views for a given cube on the TM1 server.

Memory Used for Views

This is the number of cells in the cube targeted by feeders.Number of Fed Cells

This metric counts all the populated string cells in a given cube.Number of Populated

Numeric Cells String cells are cells identified by at least one string element.

This metric counts all the populated string cells in a given cube.Number of Populated String

Cells String cells are cells identified by at least one string element.

This metric counts all stored calculated cells including rules,

dimensional consolidations, and user-defined consolidations.

Number of Stored Calculated

Cells

This metric measures the number of named views of a given cube.Number of Stored Views

The total amount of memory used by a cube, measured in bytes.Total Memory Used

}StatsStatsByCubeByClientThe }StatsStatsByCubeByClient dimension is used only in the }StatsByCubeByClient control cube.

The dimension contains the following elements:

DescriptionElement

For a given cube function, this metric measures the number of

functions executed.

Count

Operation Guide 309

Appendix B: Control Dimensions

Page 310: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionElement

For a given type of cube function, this metric measures the elapsed

time required to execute all functions.

Elapsed Time (ms)

}StatsStatsForServerThe}StatsStatsForServer dimension is used only in the }StatsForServer control cube. The dimension

tracks performance statistics when performance monitoring is enabled, and contains the following

elements:

DescriptionElement

TM1® does not release memory back to the operating system while

the TM1 server is running. Instead, the server retains unused memory

in 'garbage' for later use. Memory that has been allocated to the

server but is not in use is represented by this metric.

Memory In Garbage

The total amount of memory used by the server, in bytes.Memory Used

This measures the number of threads active on the TM1 server. Each

client connection constitutes a thread. Threads are also used to exe-

cute chores and processes.

Number of Active Threads

This statistic measures the number of active connections to the TM1

server. An individual client can have multiple connections to the

TM1 server active simultaneously. Each connection is counted in

this metric.

Number of Connected

Clients

}TimeIntervalsAll performance monitoring control cubes use the }Time Intervals control dimension. This dimension

contains 168 numeric elements for time intervals at the minute and hour level, as follows.

● 120 elements corresponding to the minutes of the current and the prior hour. Elements in the

current hour are named 0M00, 0M01, ... 0M59. Elements in the prior hour are named 1M00,

1M01, ... 1M59.

Sampling for the performance monitoring cubes is done every minute. New values are stored in

consecutive minutes of the current hour. When the hour is complete, the values of the current hour

are copied to the prior hour, and the current hour is cleared to accept new values.

● 48 elements corresponding to the hours of the current and the prior day. Elements in the current

day are named 0H00, 0H01, ... 0H23. Elements for the previous day are named 1H00, ...

1H01, 1H23. Every hour, a new summary (average) value from the minutes is posted in the

310 IBM Cognos TM1

Appendix B: Control Dimensions

Page 311: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

corresponding hourly element. When the day is over, the current day's data replaces that of

the prior day and the current day is cleared to accept new data.

Hours and minutes in this dimension reflect the system clock time when you started the performance

monitor. For example, if you start the performance monitor at 10:31 AM local system time, the

first }TimeIntervals element to receive a value is 0M31, whichis the 31st minute of the current hour.

The next element to receive a value would be 0M32.

Operation Guide 311

Appendix B: Control Dimensions

Page 312: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

312 IBM Cognos TM1

Appendix B: Control Dimensions

Page 313: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Appendix C: Excel Events Handled by TM1

This appendix describes the Microsoft® Excel events that are handled by the IBM® Cognos® TM1®

add-in for Excel.

List of Events

DescriptionExcel Event Name

This event is handled to track the number of workbooks opened.NewWorkbook

This event is handled to track number of workbooks opened and

also to set the state of TM1 toolbars and charts.

WorkbookOpen

This event is handled to detect modified status of dependent TM1

Objects and to prompt save on such objects.

WorkbookBeforeSave

This event is handled to detect modified status of dependent objects

and prompt save on such objects, as well as to unload TM1 toolbars

and menu bars when the TM1 add-in is unloaded. To achieve this,

TM1 detects the workbook saved status, posts an appropriate Save

Prompt message box, and handles the saving of the current work-

book.

WorkbookBeforeClose

This event is handled to correctly set the status of TM1 toolbars

and menu bars.

WorkbookActivate

This event is handled to remove TM1 toolbars and menu bars from

a workbook.

WorkbookAddinUninstall

This event is handled to update the TM1 toolbar and menu bar

states, as well as to update sheet-specific variables.

SheetActivate

This event is handled to detect sheet deletion.SheetDeactivate

This event is handled to update TM1 menus and toolbar statesSheetSelectionChange

This event is handled to update the TM1 database with the changes

made to a particular cell.

SheetChange

This event is handled to post TM1-specific dialog boxes on partic-

ular TM1 cells.

SheetBeforeDoubleClick

Licensed Materials – Property of IBM313© Copyright IBM Corp. 2007, 2011.

Page 314: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

DescriptionExcel Event Name

This event is handled to add and modify Excel context menu.SheetBeforeRightClick

314 IBM Cognos TM1

Appendix C: Excel Events Handled by TM1

Page 315: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Index

Symbols.blb file extension, 21

.cfg file, 17, 20, 22, 26

.cho file extension, 21

.cub file extension, 21

.dim file extension, 21

.dit file extension, 21

.ini file, 22, 69, 90

.pro file extension, 21

.rej file, 85, 94, 123

.rux file extension, 21

.sub file extension, 21

.tbu file extension, 21

.tqu file extension, 21

.tru file extension, 21

.vue file extension, 21

.xdi file extension, 21

.xru file extension, 21

}CellSecurity_CubeName control cube, 287

}Chores control dimension, 301

}ChoreSecurity control cube, 288

}ClientProperties control cube, 292

}ClientProperties control dimension, 301

}Clients control dimension, 302

}ClientSecurity control cube, 288

}ClientsGroups control cube, 291

}ConnectionProperties control cube, 293

}ConnectionProperties control dimension, 302

}Connections control dimension, 303

}CubeFunctions control dimension, 303

}CubeProperties control cube, 293

}CubeProperties control dimension, 303

}Cubes control dimension, 305

}CubeSecurity control cube, 289

}DimensionAttributes control cube, 295

}DimensionAttributes control dimension, 305

}DimensionProperties control cube, 294

}DimensionProperties control dimension, 305

}Dimensions control dimension, 306

}DimensionSecurity control cube, 289

}ElementAttributes_DimensionName control cube, 295

}ElementAttributes_DimensionName control dimen-

sion, 306

}ElementSecurity_DimensionName control cube, 290

}Groups control dimension, 306

}Hierarchies control dimension, 306

}HierarchyProperties control cube, 296

}HierarchyProperties control dimension, 306

}Hold_UserName_CubeName control cube, 300

}Hold control dimension, 307

}PerfClients control dimension, 307

}PerfCubes control dimension, 308

}Processes control dimension, 308

}ProcessSecurity control cube, 291

}StatsByClient, 142

}StatsByClient control cube, 297

}StatsByCube, 142, 297

}StatsByCubeByClient, 142

}StatsByCubeByClient control cube, 298

}StatsByCube control cube, 297

}StatsForServer, 142

}StatsForServer control cube, 299

}StatsStatsByClient control dimension, 308

}StatsStatsByCubeByClient control dimension, 309

}StatsStatsByCube control dimension, 309

}StatsStatsForServer control dimension, 310

}TimeIntervals control dimension, 310

-h, 19

Aaccess

control, 215

privileges, and replication, 109

privileges, data directory, 23

privileges, groups, 277

privileges, Read, 109, 115

privileges, synchronization, 115

privileges, Write, 115

Activate Chore, 178

Active Directory, 217

Add Counters, 157

Licensed Materials – Property of IBM315© Copyright IBM Corp. 2007, 2011.

Page 316: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

ADMIN group, 279

assigning passwords, 284

AdminHost, 33, 69

Admin Host, 88, 91

location, 20

resetting, 91

specifying multiple, 21

AdminHost parameter, 144, 267, 268

specify location, 20

SSL, 264

administration

chores, 178

clients, 180

cube properties, 180

dimension properties, 181

processes, 177

web.config, 186

administration, chore toolbar, 178

administrative groups, 278

Admin server, 17, 85, 88

diagram, 17

IP address, 17

name, 17

port number, 17

protocol, 17

status, 20

UNIX, 20

Windows, 19

Windows Startup directory, 19

Windows status, 20

AdminSvrSSLCertAuthority, 69

AdminSvrSSLCert Authority, 264

AdminSvrSSLCertID, 69, 264

AdminSvrSSLCertRevList, 70, 264

AdminSvrSSLExportKeyID, 70, 264

AdvancedRulesEditor, 70

AllowImportCamClients, 70

AllowImportCAMClients, 254

Allowmultimodes, 144

AllowMultiModes, 34

AllowReadOnlyChore Reschedule, 34

AllowSeparateNandCRules, 34

AllRuleCalcStargateOptimization, 35

anonymous access, 201

Architect, 17, 22

architecture, 167

assigning users to groups, 283

Audit log

configuring, 137

copying data, 141

details, 140

exporting results, 141

find feature, 141

object events, 135

queries, 138

results, 140

system-wide events, 135

understanding events, 135

updating with latest records, 137

using, 135

viewing, 138

Audit log, overview, 135

AuditLogMaxFileSize, 36

AuditLogMaxQueryMemory, 36

AuditLogMaxTempFileSize, 37

AuditLogOn, 37

AuditLogUpdateInterval, 37

authentication, 213, 251

importing groups into TM1, 256

integrated login, 213

integrated login diagram, 214

authentication, LDAP, 213

authentication, LDAP diagram, 214

Bbackground mode, 90

Block Access to Server Capability Assignment, 28

BrowseDisplayReadsRightToLeft, 70

browser view, 101

bulk load mode, 101

CCalculationThresholdFor Storage, 38

CAMID, 251

CAMPortalVariableFile, 39, 252

CAMSSLCertificate, 38, 252

cancel TM1 Top, 153

Capability assignments, 28

cell-level security, 277

certificate

authority, 262

revocation, 262

316 IBM Cognos TM1

Index

Page 317: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

store, 262

chain configuration, 106

server, 106

change password, 176, 181, 285

CheckFeedersMaximumCells, 38

chore

administration node, 176

administration toolbar, 178

synchronization, 116

chore, properties, 178

ClassicSliceMode, 70

clearing passwords, 285

ClearType Tuner utility

on Web server, 174

client

connections, 98

disconnecting, 99

messages, 98

properties administration node, 176

query, 124

TM1, 17, 22

client, properties, 180

ClientCAMURI, 39, 252

ClientExportSSLSvrCert, 264

ClientExportSSLSvrKeyID, 264

client logging, 134

ClientMessagePortNumber, 40

ClientPingCAMPassport, 39, 252

ClientPropertiesSyncInterval, 40

ClientVersionMaximum, 41

ClientVersionMinimum, 41

ClientVersionPrecision, 42

Close, 178

Cognos 8 authentication, 251

defining an administrator, 255

Cognos 8 security, 251

administrator considerations, 257

user considerations, 258

CognosGatewayURI, 71, 254

CognosInterfacePath, 43

Cognos security passport, 251

command prompt

TM1 Top, 152

commit TM1 Top, 151

configure

TM1 Top utility, 144

configure login page, 195

ConnectLocalAtStartup, 71

control cube, 97, 142, 287

}CellSecurity_CubeName, 287

}ChoreSecurity, 288

}ClientProperties, 292

}ClientSecurity, 288

}ClientsGroups, 291

}ConnectionProperties, 293

}CubeProperties, 293

}CubeSecurity, 289

}DimensionAttributes, 295

}DimensionProperties, 294

}DimensionSecurity, 289

}ElementAttributes_DimensionName, 295

}ElementSecurity_DimensionName, 290

}HierarchyProperties, 296

}Hold_UserName_CubeName, 300

}ProcessSecurity, 291

}StatsByClient, 297

}StatsByCube, 297

}StatsByCubeByClient, 298

}StatsForServer, 299

client and group administration, 291

object attribute and property, 293

performance monitoring, 296

security, 287

control dimension, 301

}Chores, 301

}ClientProperties, 301

}Clients, 302

}ConnectionProperties, 302

}Connections, 303

}CubeFunctions, 303

}CubeProperties, 303

}Cubes, 305

}DimensionAttributes, 305

}DimensionProperties, 305

}Dimensions, 306

}ElementAttributes_DimensionName, 306

}Groups, 306

}Hierarchies, 306

}HierarchyProperties, 306

}Hold, 307

}PerfClients, 307

}PerfCubes, 308

Operation Guide 317

Index

Page 318: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

}Processes, 308

}StatsStatsByClient, 308

}StatsStatsByCube, 309

}StatsStatsByCubeByClient, 309

}StatsStatsForServer, 310

}TimeIntervals, 310

controlling object security, 215

copy

dimension, 114

Counter Name, 156

cube, 116, 124

enabling and disabling logging, 95, 124

mirror, 106

properties, administration node, 176

replicating, 105, 112

security, 277

source, 106, 112, 113, 114, 115, 116

specifying replication information, 113

synchronizing, 105, 115

cube, properties, 180

Cube Dependancy, 81

Cube Versioning

enabling, 78

how to use, 78

overview, 78

UseCubeVersioning parameter, 78

when to use, 78

Cube Viewer

page size, 193

Cube Viewer, export sheets, 194

custom toolbar, 190

Ddata

backup, 94, 123

data, recovery, 94, 123

DataAdmin group, 280

DataBaseDirectory, 43, 71

data directory

access privileges, 23

definition, 22

local server, 22

multiples, 23

path, 22

remote server, 22

required network access, 23

restricting access, 284

security, 23

Data Reservation

capabilities, 28

configuring and administering, 79

Date and Time, 132

Deactivate Chore, 178

DEBUG

Admin server message severity, 120

logging system message severity, 127

TM1 Web message severity, 203

decrypt, 262

DefaultMeasuresDimension, 43

Dependency in Cubes, 81

DHFile-1024, 262, 264

DHFile-512, 262, 264

Diffie-Hellman, 262

dimension

local, 114

properties, 181

properties administration node, 176

rename, 114

security, 277

specifying replication information, 114

dimension, copy, 114

dimension, properties, 181

DisableMemoryCache, 44

DisableSandboxing, 28, 44

DisableWorksheetView, 45

disconnecting clients, 99

display

control chores, 178

control processes, 177

Display_Info_DBType_R8, 45

Do Not Copy Rule, 114

DownTime, 46

EEdit Chore, 178

editing web.config, 186

element security, 277

encrypt, 262

End Time, 124

ERROR

Admin server message severity, 120

logging system message severity, 127

318 IBM Cognos TM1

Index

Page 319: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

TM1 Web message severity, 203

ETLDAP

Attributes field, 219

building LDAP query, 224

configuring LDAP login parameters, 221

connecting to a TM1 server, 224

Export button, 219

exporting LDAP users to TM1, 226

export options, 225

Filter field, 219

LDAP modified record attribute, 227

LDAP query elements, 222

mapping LDAP attributes to TM1 fields, 225

modifying LDAP attributes, 218

overview, 217

Results table, 219

running from DOS, 220

running from Windows, 219

running in update mode, 227

Search button, 219

Search DN field, 219

Search Scope option, 219

updating TM1 with new LDAP users, 226

using, 217

ETLDAP, integrated login, 231

ETLDAP, LDAP authentication, 248

ETLDAP utility, 217

Excel, 169

Excel Services log, 206

ExcelWebPublishEnabled, 46

Execute Chore, 178

exit TM1 Top, 152

export

maximum sheets, 194

ExportAdminSvrSSLCert, 264

ExportSvrSSLCert, 262, 264

FFATAL logging system message severity, 127

file extensions, 21

Ggarbage memory, 100

group

adding, 277, 282

admin, 279, 284

multiple, 283

GroupsCreationLimit, 47

Hheartbeat interval, 17, 19

Iidentity key, 262

idle

timeout, 192

TM1 Top, 151

IdleConnectionTimeOutSeconds, 47

INFO

Admin server message severity, 120

logging system message severity, 127

TM1 Web message severity, 203

initialization file, 22, 69

installation

software requirements, 169

TM1 Web, 169

integrated login, 213, 214

}ClientProperties cube, 229

access rights, 231

Architect, 243

ETLDAP, 231

installing, 230

Kerberos, 235

NTLM, 234

overview, 229

setting up, 229

setting up manually, 232

TM1 Perspectives, 243

TM1 Web, 234, 235, 243

UniqueID field, 229

IntegratedSecurityMode, 47

Internet Explorer, 169

IPAddress, 49

IX-lock, 150

JJobQueueMaxWaitTime, 50

JobQueueThreadSleepTime, 50

Job Queuing, 50

LLanguage, 51

Operation Guide 319

Index

Page 320: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

LDAP

authentication, 213, 214

building a query, 224

configuring login parameters, 221

exporting users to TM1, 226

mapping attributes to TM1 fields, 225

modified record attribute, 227

modifying attributes, 218

query elements, 222

running ETLDAP in update mode, 227

server, 217

updating TM1 with new users, 226

LDAP authentication

configuring validation, 247

ETLDAP, 248

installing, 247

modifying group assignments, 248

parameters, 245

TM1S.cfg, 247, 248

validating users, 245

LDAP Authentication, 245

LDAPHost, 245

LDAP Load Tool dialog box, 219

LDAPPasswordFile, 245

LDAPPasswordKeyFile, 245

LDAPPort, 245

LDAPSearchBase, 245

LDAPSearchField, 245

LDAPUseServerAccount, 245

LDAPWellKnownUserName, 245

local dimension, 114

local server, 20, 22, 91

lock modes, 150

LockPagesInMemory, 51

log

backing out records, 97, 125

file, 85, 95, 124

file, removing, 97, 126

file, sample, 93, 122

Tm1s.log file, 122

viewing, 95, 124

log, message, 127

LogAppend, 144

logging

disabling, 95, 124

sample properties file, 128

system message severity, 127

transactions, 93, 122

logging, enabling, 95, 124

LoggingDirectory, 52

login, integrated, 229

login page configuring, 195

LogPeriod, 144

LogReleaseLineCount, 52, 96

MMaxBackupIndex, 131

MaxFileSize, 131

MaximumCubeLoadThreads, 52

MaximumLoginAttempts, 53

MaximumMemoryForSubsetUndo, 53

MaximumSynchAttempts parameter, 54

MaximumUserSandboxSize, 55

MaximumViewSize, 55

MaxUndoHoldLineCount, 55

memory

garbage, 100

management, 100

MemorySize, 131

message

clients, 98

log, 127

text, 132

MessageCompression, 56

Message Level, 132

Message log

configuring, 129

properties file, 128

severity Levels, 127

TM1 loggers, 128

using, 127

metadata, 85

Microsoft Excel, 169

Microsoft Internet Explorer, 169

mirror cube, 111, 112

definition, 106

dimension, 114

naming, 113

rules, 113, 114

specify information, 113

synchronization, 115, 116

320 IBM Cognos TM1

Index

Page 321: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

Nnavigation tree

administration node, 191

views node, 191

non-SSL clients, 262

Oobject security, 215

operating system, 169

Optional Tm1s.cfg parameter

AllowReadOnlyChore Reschedule, 34

AllowSeparateNandCRules, 34

AllRuleCalcStargateOptimization, 35

AuditLogMaxFileSize, 36

AuditLogMaxQueryMemory, 36

AuditLogMaxTempFileSize, 37

AuditLogOn, 37

AuditLogUpdateInterval, 37

CalculationThresholdForStorage, 38

CAMSSLCertificate, 38

CheckFeedersMaximumCells, 38

ClientCAMURI, 39

ClientMessagePortNumber, 40

ClientPingCAMPassport, 39

ClientPropertiesSyncInterval, 40

ClientVersionMaximum, 41

ClientVersionMinimum, 41

ClientVersionPrecision, 42

CognosInterfacePath, 43

DefaultMeasuresDimension (OLAP may require), 43

DisableMemoryCache, 44

DisableSandboxing, 44

DisableWorksheetView, 45

Display_Info_DBType_R8, 45

DownTime, 46

ExcelWebPublishEnabled, 46

GroupsCreationLimit, 47

IdleConnectionTimeOutSeconds, 47

IntegratedSecurityMode, 47

IPAddress, 49

JobQueuing, 50

Language, 51

LDAPPasswordFile, 246

LDAPPasswordKeyFile, 247

LDAPUseServerAccount, 246

LockPagesInMemory, 51

LoggingDirectory, 52

MaximumCubeLoadThreads, 52

MaximumLoginAttempts, 53

MaximumMemoryForSubsetUndo, 53

MaximumSynchAttempts, 54

MaximumUserSandboxSize, 55

MaximumViewSize, 55

MaxUndoHoldLineCount, 55

MessageCompression, 56

PasswordMinimumLength, 56

PasswordSource, 245

PerformanceMonitorOn, 57

PortNumber, 57

PrivilegeGenerationOptimization, 58

ProgressMessage, 58

RawStoreDirectory, 59

ReceiveProgressResponseTimeoutSecs, 59

RunningInBackground, 60

SAPLogFilePath, 61

SAPLoggingEnabled, 60

SaveTime, 61

SecurityPackageName, 61

ServerCAMURI, 62

ServerLogging, 62

ServerName, 62

SkipLoadingAliases, 63

SkipSSLCAMHostCheck, 63

SpreadingPrecision, 63

SubsetElementBreatherCount, 65

SyncUnitSize, 65

UseExtenedFetch, 66

UserDefinedCalculations, 66

UseSQLFetch, 66

UseSQLFetchScroll, 66

UseStargateForRules, 67

ViewConsolidationOptimization, 68

ViewConsolidationOptimizationMethod, 68

out-of-process server, 105

override dimension defaults, 114

Pparameters

SSL, 262

parameters, web.config, 186

passport, 251

PasswordMinimumLength, 56

Operation Guide 321

Index

Page 322: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

passwords, 262

assigning, 284

change, 181

for the ADMIN ID, 90

passwords, admin group, 284

passwords, change, 285

passwords, clearing, 285

passwords, setting, 284

PasswordSource, 56, 245

path data directory, 22

pdata, 22

performance counters, 154

performance monitoring, 97, 142

}StatsByClient, 297

}StatsByCube, 297

}StatsForServer, 299

control cubes, 142, 296

PerformanceMonitorOn, 57

permissions

anonymous access, 201

setting, 201

Web folders, 202

Persistent feeders, 31, 32

PersistentFeeders parameter, 57

Personal Workspace Writeback Mode, 28

Perspectives, 17

Planning Manager toolbar, 190

PortNumber, 57

private key, 262

privilege

read access, 109, 115

write access, 115

PrivilegeGenerationOptimization, 58

process

attributes, 177

parameters, 177

Process

administration node, 176

process, properties, 177

ProgressMessage, 58

properties

cube, 180

dimension, 181

QQueuing, 50

quotation marks, 33

RRawStoreDirectory, 59

read access privilege, 109, 115

ReceiveProgressResponseTimeoutSecs, 59

remote server, 26

Admin host, 20

and replication, 106

application, 86

connecting, 90

data directory, 22

diagram, 85

disconnecting, 91

memory management, 100

operations, 85

refreshing servers, 90

replication, 106

source server, 106, 112

starting, 88

target server, 106, 112

Windows service, 88

removing log files, 97, 126

rename a dimension, 114

replicate

a cube, 106, 112

a dimension, 113, 114

Admin Host considerations, 109

advantages, 105

connection, 106, 110

dimension name, 113

mirror cube name, 113

outcome, 115

overview, 105

process, 112

required access privileges, 109

server configurations, 106

server relationships, 106

setting up, 110

source server, 106

specifing rule information, 114

specifying cube information, 113

specifying dimension information, 114

subset, 115

target server, 106

views, 115

322 IBM Cognos TM1

Index

Page 323: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

replication connection

creating, 110

deleting, 112

modifying, 111

overview, 106

Required Tm1s.cfg parameter

AdminHost, 33

CAMPortalVariableFile, 39

CAMSSLCertificate (depends on CAM), 38

DataBaseDirectory, 43

UseSSL (for SSL), 67

review client properties, 180

revocation, 262

R-lock, 150

rollback TM1 Top, 151

rules, 113, 114

RunningInBackground, 60

Ssandbox

behavior in different clients, 77

configuration parameters, 77

files and folders, 77

managing, 76

memory usage, 76

Sandbox Capability Assignment, 28

sandboxes, capability assignments, 28

SAPLogFilePath, 61

SAPLoggingEnabled, 60

Save Chore, 178

SaveTime, 61

saving data, 85

sdata, 22

security

access privileges, 277

adding groups, 282

adding users, 281

assigning passwords, 284

change password, 285

clearing passwords, 285

cube-level, 277

dimension-level, 277

element-level, 277

group, 277, 279, 282, 283, 284

multiple groups, 283

password security, 284

setting passwords, 284

TM1 data, 283

TM1 objects, 215

Web folders, 202

security, Web folders, 202

SecurityAdmin group, 279

SecurityPackageName, 61

server

Admin, 17

audit log, 135

local, 20, 91

out-of-process, 105

performance, 142

performance monitoring, 97, 142

remote, 20, 85, 88, 90, 91, 100, 106, 112

remote shutdown, 99

remote shutting down, 91

serformance, 97

source, 106, 112

star configuration, 106

start and chain configuration, 106

target, 106, 112

server, LDAP, 217

server, message log, 127

ServerCAMURI, 62, 252

ServerLogging, 62

ServerName, 62, 144

service automatic start, 89

session idle timeout, 192

Set Rule to Synchronize, 114

setting passwords, 284

shut down, 127

skins

TM1 Web, 208

SkipLoadingAliases, 63

SkipSSLCAMHostCheck, 63, 252

source cube, 106, 112, 113, 114, 115, 116

source server, 106, 112

SpreadingPrecision, 63, 64

SSL

parameters, 262

TM1 Top, 268

SSLCertAuthority, 262, 264

SSLCertificate, 262, 264

SSLCertificateID, 262, 264

SSLCertRevocationFile, 262, 264

Operation Guide 323

Index

Page 324: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

SSLPrivateKeyPwdFile, 262, 264

SSLPwdKeyFile, 262, 264

star and chain configuration, 106

star configuration, 106

Stargate view, 101

Starting Time, 124

SubsetElementBreatherCount, 65

SupportNonSSLClients, 262

SvrSSLExportKeyID, 262, 264

synchronization

automatic, 116

on-demand, 105, 116

over unstable networks, 117

overview, 106, 115

required access privileges, 115

SyncUnitSize parameter, 65

system configuration, 17

Ttarget server, 106, 112

Thread ID, 132

timeout, 192

TimeZone, 131

TM1

architecture, 17

client, 17

log file, 95, 124

Logger Name, 132

securing data, 283

transaction log file, 85, 93, 122

users and groups security, 277

Web client, 17

Tm1admsrv.exe, 19

tm1admsrv-log.properties sample, 120

TM1ExcelServicePortNumber Parameter, 195

tm1p.ini

location, 69

parameters, 69

Tm1p.ini file, 22, 69, 90

TM1 PerfMon, 154, 155

tm1s_start_example, 89

Tm1s.cfg file, 17, 20, 22, 26

location, 26

parameters, 33

sample, 27

Tm1s.log

properties, 128

removing old log files, 97, 126

TM1 server

remote, 90

shutting down UNIX, 92

UNIX, 89

UNIX background mode, 90

Windows shutting down, 91

tm1srvstop.exe, 87, 92

TM1Top, 34

Tm1top.ini, 144

TM1 Top utility

canceling threads, 153

command prompt, 152

configuring, 144

installing, 144

keys, 144

lock modes, 150

overview, 143

parameters, 144

SSL, 268

thread processing states, 151

TM1 Web

administering, 167

running in Windows Vista, 175

TM1 Web log, 204

toolbars

Chore Administration, 178

Planning Manager, 190

toolbars, custom, 190

top utility, 143

transaction log, 93, 95, 97, 122, 124, 125

query result, 124

transaction log parameters, 124

Cubes, 124

Starting Time, 124

transaction log parameters, Clients, 124

UUNIX, 89

server, 26

user

adding, 281

user and group security, 277

UserDefinedCalculations, 66

324 IBM Cognos TM1

Index

Page 325: IBM Cognos TM1 - 8businessintelligenceonline.webs.com/documents/tm1_Admin.pdf · 4 IBM Cognos TM1 Table of Contents. ... ClassicSliceMode 70 ... Configuring TM1 Web to Use IBM Cognos

UseSQLExtenedFetch, 66

UseSQLFetch, 66

UseSQLFetchScroll, 66

UseSSL, 67, 264

UseStargateForRules, 67

Vvalue, 156

verify TM1 Top, 152

view, Stargate, 101

ViewConsolidationOptimization, 68

ViewConsolidationOptimizationMethod, 68

WWARN logging system message severity, 127

Web

browser, 169

server, 169

Web, setting folder security, 202

web.config

defined, 186

editing, 187

Windows

service, 19

service account, 169

Windows service, 88

Windows Vista

configuring for TM1 Web, 175

W-lock, 150

write access privilege, 115

Operation Guide 325

Index