Académique Documents
Professionnel Documents
Culture Documents
Version 9.5
Operations Guide
Product Information
This document applies to IBM Cognos TM1 Version 9.5 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).
Copyright
Licensed Materials - Property of IBM
Copyright IBM Corp. 2007, 2009.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
IBM, the IBM logo, ibm.com, and Cognos are trademarks or registered trademarks of International Business Machines Corp., in many jurisdictions
worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on
the Web 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 Pentium
are 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) reprinted with permission from Microsoft Corporation.
Table of Contents
Introduction
13
15
TM1 Architecture 15
TM1 Admin Server 15
Running the Windows Admin Server 17
Running the UNIX Admin Server 18
Specifying the Location of the Admin Host 18
Specifying Multiple Admin Hosts 19
TM1 Files 19
Data Directory 20
Specifying the Location of the Data Directory 20
Specifying Multiple Data Directories 21
Required Network Access 21
Chapter 2: TM1 System Configuration
23
Table of Contents
DisableWorksheetView 31
Display_Info_DBType_R8 31
DownTime 32
ExcelWebPublishEnabled 32
GroupsCreationLimit 33
IdleConnectionTimeOutSeconds 33
IntegratedSecurityMode 33
IPAddress 35
Language 35
LDAPUseServerAccount 36
LDAPPasswordFile 36
LDAPPasswordKeyFile 36
LoggingDirectory 36
MaximumCubeLoadThreads 36
MaximumLoginAttempts 37
MaximumMemoryForSubsetUndo 37
MaximumUserSandboxSize 37
MaximumViewSize 38
MessageCompression 38
PasswordMinimumLength 38
PasswordSource 38
PerformanceMonitorOn 38
PortNumber 39
PrivilegeGenerationOptimization 39
ProgressMessage 39
RawStoreDirectory 40
ReceiveProgressResponseTimeoutSecs 40
RunningInBackground 41
SAPLoggingEnabled 41
SAPLogFilePath 41
SaveTime 41
SecurityPackageName 42
ServerCAMURI 42
ServerLogging 42
ServerName 42
SkipLoadingAliases 43
SkipSSLCAMHostCheck 43
SpreadingPrecision 43
SpreadingPrecision 44
UserDefinedCalculations 44
UseSQLFetch UseSQLFetchScroll UseExtenedFetch 44
UseSSL 45
UseStargateForRules 45
ViewConsolidationOptimization 45
ViewConsolidationOptimizationMethod 46
The Tm1p.ini File 46
Location of the TM1p.ini File 46
AdminHost 47
AdminSvrSSLCertAuthority 47
Table of Contents
AdminSvrSSLCertID 47
AdminSvrSSLCertRevList 47
AdminSvrSSLExportKeyID 47
AdvancedRulesEditor 47
AllowImportCamClients 48
BrowseDisplayReadsRightToLeft 48
ClassicSliceMode 48
CognosGatewayURI 48
ConnectLocalAtStartup 48
DataBaseDirectory 48
DimensionDownloadMaxSize 49
DisplayApplications 49
DisplayChores 49
DisplayControlCubes 49
DisplayCubes 49
DisplayDimensions 49
DisplayExplorerPropertiesWindow 49
DisplayProcesses 50
DisplayReplications 50
ExpandRowHeaderWidth 50
ExportAdminSvrSSLCert 50
InSpreadsheetBrowser 50
IntegratedLogin 50
Language 51
LocalServerNetworkProtocol 51
MainWindowLayoutInfo 51
PreviousAdminHosts 51
PreviousDataDirectories 51
SecurityAssignmentWindowLayoutInfo 52
SentMsgsToServerCountWarning 52
ShowAdminHostChangeWarning 52
ShowAliasAttributeWarning 52
ShowChoresSchedulingWarning 52
ShowCubeReplicationWarning 52
ShowDimDeleteElementWarning 52
ShowDimensionAccessWarning 53
ShowDynamicSubsetWarning 53
ShowPickOperationWarning 53
ShowProcessUNASCIIWarning 53
ShowProcessUNODBCWarning 53
SliceNewWorkbook 53
SubsetWindowLayoutInfo 54
Chapter 3: Remote Server Operations
55
Operations Guide 5
Table of Contents
Starting a Remote TM1 Server 58
Starting a TM1 Server Set Up as a Windows Application 58
Starting a TM1 Server Installed as a Windows Service 58
Starting a UNIX TM1 Server 59
Connecting to a Remote Server 60
Refreshing the List of Remote Servers 60
Re-Setting the Admin Host 61
Re-Setting Local Server Options 61
Disconnecting from a Remote Server 61
Shutting Down a Windows TM1 Server 61
Shutting Down a Windows TM1 Server Running as a Service 62
Shutting Down a UNIX TM1 Server 62
Shutting Down a UNIX TM1 Server Running in Background Mode 62
Logging Transactions 63
Data Backup and Recovery 64
Enabling and Disabling Logging 65
Viewing the Transaction Log 65
Backing Out Records from the Transaction Log 66
Removing Log Files from the Disk 67
Monitoring Server Performance 67
Managing Client Connections 68
Broadcasting Messages to Clients 68
Disconnecting Clients from the Server 68
Shutting Down a Server Remotely 69
Remote Server Memory Management 69
About Stargate Views 70
Configuring and Managing Sandboxes in your TM1 Environment 70
Memory Usage Considerations for Sandboxes 71
Managing Files and Folders for Sandboxes 71
TM1 Server Configuration Parameters for Sandboxes 71
Chapter 4: Replicating Cubes
73
Replication Overview 73
Relationships Created by Replication 74
Required Access Privileges 76
Admin Server Considerations 77
Configuring the Tm1s.cfg File to Support Replication 77
Maintaining Replication Connections 78
Creating a Replication Connection 78
Modifying a Replication Connection 79
Deleting a Replication Connection 80
Replication Process 80
Replicating a Cube 80
Specifying Information about the Replicated Cube 81
What Happens when TM1 Replicates a Cube 83
Synchronization Process 83
Synchronizing on Demand 84
Scheduling Synchronization 84
Table of Contents
Chapter 5: System and Performance Monitoring
85
123
Operations Guide 7
Table of Contents
Installing the IBM Cognos TM1 Web Software 126
Configuring Language Settings in Microsoft Internet Explorer 126
Displaying and Entering Numbers Based on Regional Settings 127
Configuring Microsoft Internet Explorer Version 7 for IBM Cognos TM1 Web 127
Running IBM Cognos TM1 Web in Mozilla Firefox Web Browser 128
Running the 64-bit version of IBM Cognos TM1 Web on Windows x64 130
Running IBM Cognos TM1 Web on a WAN Server and Exporting Excel and PDF Files 130
Using ClearType on TM1 Web Server to Enhance Display and Rendering of TM1 Websheets 131
Administering the TM1 Server from IBM Cognos TM1 Web 132
Administering Processes 133
Administering Chores 134
Setting Client Properties 135
Setting Cube Properties 136
Setting Dimension Properties 136
Changing Your Password 137
Configuring a Custom Homepage for IBM Cognos TM1 Web 137
Configuring Different Homepages for Individual Users 138
Configuring a Global Homepage for All Users 140
Modifying IBM Cognos TM1 Web Configuration Parameters 142
Editing the Web.Config File 143
Configuring TM1 Workflow Parameters 144
Displaying the Custom Toolbar 146
Displaying the Content of the Custom Toolbar 146
Changing the Height of the Custom Toolbar 146
Displaying or Hiding the Views Node in the Navigation Pane 147
Displaying or Hiding the Administration Node in the Navigation Pane 147
Changing the IBM Cognos TM1 Web Session Timeout 148
Changing the Cube Viewer Page Size 148
Setting the Maximum Number of Sheets to Export from a Cube Viewer 149
Adjusting the HttpRuntime ExecutionTimeout Parameter 149
Setting the TM1ExcelServicePortNumber Parameter 150
Configuring the Login Page using the AdminHostName and TM1ServerName Parameters 150
Configuring IBM Cognos TM1 Web Startup and Appearance Settings 151
Using the CustomLink Parameter to Open Other URLs and Web Pages 154
Configuring the IBM Cognos TM1 Web Virtual Cache Directory 154
Controlling Chart Scaling and Increments with the SmartAxisEnabled Parameter 155
Enabling the Websheet Paging Toolbar 155
Setting Web Permissions 156
Modifying the IBM Cognos TM1 Web Virtual Directory to Allow Anonymous Access 156
Setting Security for IBM Cognos TM1 Web Folders 157
Performing Web Folder Maintenance 159
Using IBM Cognos TM1 Web Logging 160
Message Severity Levels for IBM Cognos TM1 Web Logging 160
IBM Cognos TM1 Web Log 160
TM1 Excel Services Log 163
Multiple Skin Support in IBM Cognos TM1 Web 165
Overview 165
Table of Contents
Configuration 166
Creating Your Own Custom Skins for TM1 Web 168
Chapter 7: TM1 Security Overview
171
Authentication 171
TM1 Authentication 171
Integrated Login 171
LDAP Authentication 172
TM1 Object Security 172
Chapter 8: ETLDAP Utility
175
187
199
Operations Guide 9
Table of Contents
PasswordSource 199
PasswordSource 199
LDAPPort 199
LDAPHost 199
LDAPWellKnownUserName 200
LDAPSearchBase 200
LDAPSearchField 200
LDAPUseServerAccount 200
LDAPPasswordFile 200
LDAPPasswordKeyFile 201
Configuring LDAP Validation 201
Run the TM1 Installation Wizard and Select LDAP Authentication 201
Change the Parameter in TM1S.cfg to TM1 201
Run the ETLDAP Utility 202
Modify Group Assignments for New Users 202
Change the PasswordSource Parameter in TM1S.cfg to LDAP 202
Chapter 11: Using IBM Cognos 8 Security with TM1
205
213
229
Table of Contents
Understanding Administrative Groups and Authority 230
ADMIN Group 231
SecurityAdmin Group 231
DataAdmin Group 232
Adding and Deleting Users and Groups 233
Adding a User 233
Adding a Group 234
Deleting a User 234
Deleting a Group 235
Assigning Users to Groups 235
Membership in Multiple Groups 235
Securing TM1 Data 235
Restricting Access to the Data Directory 236
Assigning Passwords 236
Using Standard Security for Passwords 236
Setting and Clearing Passwords 236
Setting a Password 236
Clearing a Password 237
Changing a Password 237
Setting an Expiration for a User 237
Appendix A: Control Cubes
239
255
}Chores 255
Operations Guide 11
Table of Contents
}ClientProperties 255
}Clients 255
}ConnectionProperties 256
}Connections 256
}CubeFunctions 256
}CubeProperties 257
}Cubes 258
}DimensionAttributes 258
}DimensionProperties 258
}Dimensions 259
}ElementAttributes_DimensionName 260
}Groups 260
}Hierarchies 260
}HierarchyProperties 260
}Hold 260
}PerfClients 261
}PerfCubes 261
}Processes 261
}StatsStatsByClient 262
}StatsStatsByCube 262
}StatsStatsByCubeByClient 263
}StatsStatsForServer 263
}TimeIntervals 264
Appendix C: HP-UX 11i Kernel Parameters
267
271
277
269
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
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 collaborative 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 programming background.
Finding Information
To find the most current product documentation, including all translated documentation, access
one of the IBM Cognos Information Centers at http://publib.boulder.ibm.com/infocenter/cogic/
v1r0m0/index.jsp.
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. Unauthorized duplication is prohibited.
13
Introduction
Accessibility Features
This product does not currently support accessibility features that help users who have a physical
disability, such as restricted mobility or limited vision, to use this product.
TM1 Architecture
TM1 employs a distributed, client-server architecture that consists of remote TM1 servers to which
a combination of the following clients can connect:
TM1 Perspectives
TM1 Architect
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 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 Client are standard TM1 clients. In a normal
LAN/WAN environment, these clients all communicate with a remote server using the TCP/IP
network protocol.
15
TM1 Clients
1
TM1 Server
1
TM1 Admin Server
TM1 Server
1.
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 a 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, a 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 a TM1 server,
that TM1 server becomes registered and available to clients on the network. However, if the Admin
Server does not detect the presence of a registered TM1 server over a period equal to three times
the heartbeat interval, that TM1 server is removed from the list of servers available on the network.
Consequently, the TM1 server will not be available to clients on the network.
By default, the Admin Server uses port 5495. If port 5495 is already in use, you can assign a new
port number by creating a new service called Tm1admsrv. All TM1 applications look for a named
16 IBM Cognos TM1
Parameter
Description
-h
7. Click Next.
The Select Program Folder dialog box opens.
8. Select Startup.
9. Click Next.
The Select a Title dialog box opens.
Operations Guide 17
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.
Details of each TM1 server currently registered with the Admin Server
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 File" (p. 46).
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 Windows TM1 server.
For information on server parameters, see "The Tm1s.cfg File" (p. 23).
TM1 Files
TM1 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 TM1 to store metadata, such as security
information.
The following table lists the files that define cubes, dimensions, and other TM1 objects. These files
are located in the data directory, which is described later in this section.
File Extension
Description
.blb
.cho
.cub
.dim
Compiled dimension
.dit
.pro
.rux
Compiled rule
.sub
Dimension subset
.tbu
.tqu
Saved query
.tru
.vue
Saved view
.xdi
.xru
Operations Guide 19
Data Directory
The 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 TM1 Perspectives, TM1
Architect, or 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:
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.
Choose the path for your data directory when you install TM1.
Data Directory
Default Path
TM1 Perspectives
or TM1 Architect
local server
install_dir\custom\tm1data\pdata
Windows TM1
install_dir\custom\tm1data\sdata
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 File" (p. 46).
For a remote server, specify the location of the data directory by using either the DatabaseDirectory 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 File" (p. 23).
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.
20 IBM Cognos TM1
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.
Operations Guide 21
If you are running a 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 a 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.
For example, this command specifies that TM1 will use the Tm1s.cfg file located in the
c:\salesdata directory:
c:\Program Files\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 UNIX server, 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.
23
Spaces in Values
If a parameter value contains spaces, you must enclose the parameter values within double quotes.
AdminHost
This parameter is required.
Specifies the computer name or IP address of the Admin Host on which an Admin Server is running.
You can specify multiple Admin Hosts by separating each host name with a semicolon on a Windows
TM1 server, or a colon on a UNIX TM1 server. For example:
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.
AllowDynamicSlice
This parameter is optional.
Enables or disables dynamic slices on the TM1 server.
To disable dynamic slices, add the line AllowDynamicSlice=F to Tm1s.cfg.
To enable dynamic slices, add the line AllowDynamicSlice=T to Tm1s.cfg.
If you do not include the AllowDynamicSlice parameter in Tm1s.cfg, dynamic slices are enabled
by default on the TM1 server.
For details, see the IBM Cognos TM1 Users Guide.
AllowReadOnlyChore Reschedule
This parameter is optional.
Provides users with READ access to a chore, and the ability to activate, deactivate, and reschedule
chores.
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.
AllowSeparateNandCRules
This parameter is optional.
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;
['Budget','Argentina']=C:Expression;
are both valid rules statements when you include the AllowSeparateNandCRules parameter in the
Tm1s.cfg file and set to T.
To set the parameter to T, add the following line to Tm1s.cfg:
AllowSeparateNandCRules=T
AllRuleCalcStargateOptimization
The AllRuleCalcStargateOptimization parameter can improve performance in calculating views
that contain only rule-calculated values.
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
Operations Guide 25
If every value in the view is rule-calculated, then TM1 skips the unnecessary calculations for
standard consolidations and just performs the rule-calculated consolidations.
If the view contains even a single value which is not rule-calculated, then this optimization
parameter will have no effect.
When this parameter is set to True, some additional processing will take place for every view that
is requested to first check if the view contains only rule-calculated values. For most views, this
additional processing is minimal since the optimization is stopped after the first value in the view
is found to be not rule-calculated.
To enable this parameter, set the parameters value to T in the TM1 server configuration file,
Tm1s.cfg, as follows:
AllRuleCalcStargateOptimization=T
AuditLogMaxFileSize
This parameter is optional.
Indicates the maximum file size that an audit log file can grow to before it is closed and a new file
is created.
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
Minimum value: 1 KB
Maximum value: 2 GB
AuditLogMaxQueryMemory
This parameter is optional.
Indicates the maximum amount of memory that TM1 can use when running an audit log query
and retrieving the set of results.
This value must include units of KB (kilobytes), MB (megabytes), or GB (gigabytes). For example:
AuditLogMaxQueryMemory=100 MB
Minimum value: 1 KB
Maximum value: 2 GB
AuditLogMaxTempFileSize
This parameter is optional.
Indicates 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.
This value must include units of KB (kilobytes), MB (megabytes), or GB (gigabytes). For example:
AuditLogMaxTempFileSize=100MB
Minimum value: 1 KB
Maximum value: 2 GB
AuditLogOn
This parameter is optional.
Turns audit logging on (T) or off (F).
For example:
AuditLogUpdateInterval
This parameter is optional.
Indicates the maximum amount of time, in minutes, that TM1 waits before moving the events from
the temporary audit file into the final audit log.
For example:
AuditLogUpdateInterval=60
CalculationThresholdForStorage
This parameter is optional.
Defines 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.
Operations Guide 27
CAMSSLCertificate
This parameter is optional.
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.
This parameter is required only if the CAM server is configured to use SSL.
CheckFeedersMaximumCells
This parameter is optional.
Limits the number of cells checked by the Check Feeders option in the Cube Viewer. The CheckFeedersMaximumCells 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.
When TM1 checks feeders from a highly consolidated cell, TM1 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
ClientCAMURI
This parameter is optional.
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
ClientPingCAMPassport
This parameter is optional.
Indicates the interval, in seconds, that a client should ping the CAM server to keep their passport
alive.
CAMPortalVariableFile
This parameter is optional.
The 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..
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.
ClientMessagePortNumber
This parameter is optional.
Identifies a secondary port used to accept client messages concerning the progress and ultimate
cancellation of a lengthy operation without tying up thread reserves.
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. 39) and "ProgressMessage" (p. 39).
ClientPropertiesSyncInterval
This parameter is optional.
Specifies the frequency (in seconds) at which client properties are updated in the }ClientProperties
control cube. Set to 1800 seconds to update cube every 30 minutes. Frequent updating can cause
unnecessary consumption of CPU time and may cause users from connecting/disconnecting until
operation completes.
ClientVersionMaximum
This parameter is optional.
Specifies the maximum client version that can connect to the TM1 server.
The parameter value is expressed as a three digit number without decimal points, corresponding
to the first three digits of the build number for the TM1 client version. For example, the build
number for TM1 9.0 SP3 is 9.0.3.173, so the correct parameter value for this client version is 903.
To determine the build number, choose Help, About from Server Explorer.
If this parameter is not explicitly set, the default value is equal to the currently installed server version.
Operations Guide 29
ClientVersionMinimum
This parameter is optional.
Specifies the minimum client version that can connect to the TM1 server.
The parameter value is expressed as a three digit number without decimal points, corresponding
to the first three digits of the build number for the TM1 client. For example, the build number for
TM1 9.0 SP3 is 9.0.3.173, so the correct parameter value for this client version is 903.
To determine the build number for a TM1 client, choose Help, About from Server Explorer.
If this parameter is not explicitly set, the default value is equal to the base version of the currently
installed TM1 server. Using TM1 server 9.0 SP3 as an example, the default value of ClientVersionMinimum is 900, which corresponds to the base version of the server.
You cannot 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 ClientVersionMinimum is larger than ClientVersionMaximum, only clients with a version number equal to
ClientVersionMaximum can connect to the server.
DataBaseDirectory
This parameter is required.
Specifies the data directory from which the server loads cubes, dimensions, and other objects. You
can list multiple data directories by separating them with semicolons.
For details, see "Data Directory".
DefaultMeasuresDimension
This parameter is optional.
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 "}CubeProperties" (p. 246).
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.
DisableMemoryCache
This parameter is optional.
Disables 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.
DisableSandboxing
This parameter is optional.
Disables the TM1 sandbox feature. The sandbox feature allows users to create personal data
workspaces that they can work in separate from base data. By default, this parameter is set to F
which enables the sandbox feature for all users.
To disable the sandbox feature, add the following line to Tm1s.cfg:
DisableSandboxing=T
To enable the sandbox feature and make it available to TM1 users, add the following line to
Tm1s.cfg:
DisableSandboxing=F
DisableWorksheetView
This parameter is optional.
Please contact customer support to determine if this parameter is applicable to your TM1 system.
DisableWorksheetView 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.
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_R8
This parameter is optional.
Please contact customer support to determine if this parameter is applicable to your TM1 system.
Display_Info_DBType_R8 instructs the TM1 server to store DISPLAY_INFO column data as
DBTYPE_R8.
Operations Guide 31
DownTime
This parameter is optional.
Specifies a time when the server will come down automatically. 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.)
For example, DownTime = 01:03:30 specifies that you want to bring the server down on the following day at 3:30 in the morning.
The DownTime parameter is not available when you run the TM1 server as a Windows service.
When you use the DownTime parameter on the UNIX TM1 server, you must set the RunningInBackground parameter to T. If RunningInBackground=F, the server prompts for confirmation
before shutting down and cannot shut down without manual confirmation from an administrator.
ExcelWebPublishEnabled
This parameter is optional.
Use this parameter to enable 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.
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.
GroupsCreationLimit
This parameter is optional.
Sets the maximum number of groups that can be created in one TM1 server session. 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 TM1 model 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.
IdleConnectionTimeOutSeconds
This parameter is optional.
Specifies a timeout limit for idle client connections, in seconds.
For example, if you include the following line in Tm1s.cfg, the server disconnects idle client connections after 900 seconds.
IdleConnectionTimeOutSeconds=900
IntegratedSecurityMode
This parameter is optional.
This parameter sets the user authentication mode to be used by the TM1 server.
Use the following format to set this parameter:
IntegratedSecurityMode=x
Operations Guide 33
Security Mode
Description
Security Mode
Description
The server uses IBM Cognos 8 security authentication and supports user
groups from both TM1 and Cognos 8.
Use security mode 5 when you are running IBM Cognos TM1 Contributor with IBM Cognos 8 security.
Considerations when using this mode:
IPAddress
This parameter is optional.
This 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.
Note: When this parameter is used in the Tm1s.cfg file, both the TM1 Server and TM1 Admin
Server must run on the same computer. If this parameter is used in the Tm1s.cfg file, but the TM1
Server and TM1 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 TM1 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. 15).
The syntax for Microsoft Windows uses as element separator a semicolon, for example the following
setting specifies two IP addresses for a 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 semicolon.
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.
The syntax for UNIX uses as element separator a colon. For example IPAddress=130.5.32.0:
130.5.64.0
Language
This parameter is optional.
Operations Guide 35
ENG - English
FRA - French
DEU - German
JPN - Japanese
ITA - Italian
ESP - Spanish
LDAPUseServerAccount
See "LDAP Authentication" (p. 199).
LDAPPasswordFile
See "LDAP Authentication" (p. 199).
LDAPPasswordKeyFile
See "LDAP Authentication" (p. 199).
LoggingDirectory
This parameter is optional.
Specifies the directory to which the server saves its log files. If you do not supply this parameter,
the log files are saved to the first data directory specified by the DataBaseDirectory parameter.
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.
MaximumCubeLoadThreads
This parameter is optional.
Specifies whether the cube load and feeder calculation phases of server loading are multi-threaded,
so multiple processor cores can be used in parallel. This results in decreased server load times.
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
MaximumLoginAttempts
This parameter is optional.
Sets 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.
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 administrator changes his password. However, after the TM1 server recycles, the user can log in with his
existing password.
MaximumMemoryForSubsetUndo
This parameter is optional.
Sets the maximum amount of memory, in kilobytes, to be dedicated to storing the Undo/Redo stack
for the Subset Editor. For example, adding the line MaximumMemoryForSubsetUndo=20480 to
the configuration file instructs the server to allot 20480 kilobytes (20 MB) of memory for the
Undo/Redo stack.
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).
MaximumUserSandboxSize
This parameter is optional.
Operations Guide 37
MaximumViewSize
This parameter is optional.
Sets the maximum amount of memory (in MB) to be allocated when a user accesses a view. If you
do not set the MaximumViewSize parameter, the default maximum view size is 100MB on a 32bit system, and 500 MB on a 64-bit system.
To specify a maximum amount of memory allocation for views, add the following line to Tm1s.cfg:
MaximumViewSize=n
MessageCompression
This parameter is optional.
Enables message compression for large messages that significantly reduces network traffic. The
parameter is enabled by default.
To disable message compression, add the following line to Tm1s.cfg:
MessageCompression=F
PasswordMinimumLength
This parameter is optional.
Specifies a minimum password length for clients accessing 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 PasswordMinimumLengt.h
PasswordSource
This parameter is optional.
See "LDAP Authentication" (p. 199).
PerformanceMonitorOn
This parameter is optional.
PortNumber
This parameter is optional.
Sets the server port number used to distinguish between multiple servers running on the same
computer. When multiple TM1 servers are installed on a single computer, each server must use a
unique port number.
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.
PrivilegeGenerationOptimization
This parameter is optional.
When 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 processing and a longer loading time. An example of a sparsely populated security cube would be one
that has a greater ratio of default security settings compared to defined security settings.
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.
ProgressMessage
This parameter is optional.
This parameter determines whether users have the option to cancel lengthy view calculations. When
a user opens a view that takes a significant amount of time to calculate (usually a view with high
levels of consolidation or complex rules), TM1 monitors the progress of the process. When ProgressMessage=T a dialog box opens that allows the user to Stop Building View.
If the user clicks Stop Building View, the view is discarded on the client, but view calculation continues on the server. In some instances, this can tie up the server.
Operations Guide 39
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 versions 9.4 or later, the user can assign a unique Port Number using ClientMessagePortNumber.
This additional port allows these progress messages to travel via a secondary port so that server
processing can continue without tying up thread reserves.
Note: To avoid potentially tying up servers, TM1 9.1 SP3 through 9.4 have ProgressMessage=F
inserted into the 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.
RawStoreDirectory
This parameter is optional.
Indicates the location of the temporary, unprocessed log file for audit logging if logging takes place
in a directory other than the data directory.
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.
ReceiveProgressResponseTimeoutSecs
This parameter is optional.
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
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.
RunningInBackground
This parameter is optional.
When you add the line RunningInBackground=T to Tm1s.cfg, the UNIX TM1 server runs in
background mode.
SAPLoggingEnabled
This parameter is optional and is used only in 9.0 software. 9.1 and higher versions use a property
to set this value.
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.
SAPLogFilePath
This parameter is optional and is used only in 9.0 software. 9.1 and higher versions use a property
to set this value.
This parameter sets the log file to receive SAP logging information.
You should specify the full path to the log file, for example, SapLogFilePath=c:\SAPdata\tm1_
sap.log.
SaveTime
This parameter is optional.
Sets the time of day to execute an automatic save of server data; saves the cubes every succeeding
day at the same time. As with a regular shutdown, SaveTime renames the log file, opens a new log
file, and continues to run after the save.
The SaveTime parameter is not available when running the TM1 server as a Windows service.
The format of the SaveTime parameter is dd:hh:mm where:
Operations Guide 41
dd is the number of days from today that the system will start automatically saving data. For
example, 00 is today, 01 is tomorrow.
SecurityPackageName
This parameter is optional.
If you configure the TM1 server to use Integrated Login, the SecurityPackageName parameter
defines the security package that authenticates your user name and password in Windows.
Valid values are:
For complete descriptions of all login security modes, including Integrated Login, see "Integrated
Login" (p. 187).
ServerCAMURI
This parameter is optional.
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.
For example,
http://10.121.25.121:9300/p2pd/servlet/dispatch
or
https://10.121.25.121:9300/p2pd/servlet/dispatch
ServerLogging
This parameter is optional.
Generates a log with the security activity details on the TM1 server that are associated with Integrated
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.
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.
ServerName
This parameter is optional.
Sets 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.
SkipLoadingAliases
This parameter is optional.
Please contact customer support to determine if this parameter is applicable to your TM1 system.
Use SkipLoadingAliases to speed up the loading of the server and updating of views by skipping
the loading of aliases.
Valid values are:
T - Aliases skipped
F - Aliases loaded
SkipSSLCAMHostCheck
This parameter is optional.
Indicates whether the SSL certificate ID confirmation process can be skipped. The default is FALSE.
Important: This parameter should be set to TRUE only if using a generic certificate for demonstration
purposes.
SpreadingPrecision
Floating point arithmetic on computers is not 100% precise. When a computer calculates very small
numbers, a margin of error is applied to the calculation. If the computer adds a set of numbers,
and the resulting sum is close to the target value within the margin of error, the sum is considered
accurate.
The margin of error for certain TM1 calculations is controlled through the SpreadingPrecision
parameter. The default value is SpreadingPrecision=1e-8. This value is used in the following
spreading scenarios:
SpreadingPrecision=1e-4
Operations Guide 43
SpreadingPrecision=1e-8
SpreadingPrecision=1e-10
SpreadingPrecision=1e-12
SpreadingPrecision
Spreading and Consolidated Holds
You can also use SpreadingPrecision under these conditions:
When you spread values to some leaf cells that roll up into a consolidation
For example, suppose you have the consolidation Q1 with values Jan, Feb, and Mar.
If Q1- has a consolidated hold applied, and you spread values to Jan and Feb, TM1 does the following:
Adjusts Mar.
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.
UserDefinedCalculations
Enables user-defined consolidations on a TM1 server. By default, UserDefinedCalculations is
enabled.
To disable user-defined consolidations on a server, add the following line to Tm1s.cfg:
UserDefinedCalculations=F
UseSSL
Enables or disables SSL on the TM1 server.
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. 213).
UseStargateForRules
By default, any time a rule references a calculated value, the value is retrieved from a Stargate view
stored in memory (if available). By using the Stargate view for rules, in most cases, there is 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
line to Tm1s.cfg to instruct the TM1 rules to always retrieve the calculated values from the server
and improve performance.
UseStargateForRules=F
We strongly recommend that you contact Customer Support to review any performance issues you
might be experiencing before adding the UseStargateForRules parameter.
ViewConsolidationOptimization
Enables or disables view consolidation optimization on the TM1 server, which 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.
Operations Guide 45
ViewConsolidationOptimizationMethod
This parameter defines the method used to achieve view consolidation optimization when the
ViewConsolidationOptimization parameter is enabled on the TM1 server.
There are two methods that ViewConsolidationOptimization can use to calculate and store consolidations: ARRAY or TREE. The ARRAY method stores consolidations in a temporary array. The
TREE method stores consolidations in a tree.
ViewConsolidationOptimizationMethod should be set to TREE in most circumstances. This setting
provides the best performance in normal operations 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
ViewConsolidationOptimizationMethod=ARRAY
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 TM1on 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.
AdminHost
Displays the Admin Host name on which an Admin Server is running. On TM1 Options, use Login
Parameters Admin Host.
AdminSvrSSLCertAuthority
The full path of the certificate authority file that issued the TM1 Admin Server's certificate. On
TM1 Options, use Certificate Authority.
AdminSvrSSLCertID
The 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.
AdminSvrSSLCertRevList
The 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.
AdminSvrSSLExportKeyID
The 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 ExportAdminSvrSSLCert=T.
On TM1 Options, use Export Certificate ID.
AdvancedRulesEditor
Indicates the type of Rules Editor used. The Advanced Rules Editor has an enhanced interface.
Operations Guide 47
AllowImportCamClients
This 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 a TM1 Server to Use IBM Cognos 8 Security" (p. 206).
BrowseDisplayReadsRightToLeft
Indicates how data is oriented in the Cube Viewer. Data can display right to left or left to right.
ClassicSliceMode
Indicates whether the Slice option in the Cube Viewer generates classic slices or dynamic slices.
CognosGatewayURI
This 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 a TM1 Server to Use IBM Cognos 8 Security" (p. 206).
ConnectLocalAtStartup
Indicates whether TM1 Architect or TM1 Perspectives automatically connects to the local server
at startup.
DataBaseDirectory
Uses the full path to the local server data directory. You can specify multiple data directories by
separating the directory names with semicolons.
DimensionDownloadMaxSize
A threshold value of the number of elements in a dimension, beyond which the dimension is
downloaded and cached on the TM1 client. To improve performance when you work with large
dimensions, add DimensionDownloadMaxSize so that large dimensions will cache on the client.
DisplayApplications
Indicates whether the Applications group is visible in Server Explorer on startup.
DisplayChores
Indicates whether the Chores group is visible in Server Explorer on startup.
DisplayControlCubes
Indicates whether the Control Cube group is visible in Server Explorer on startup.
DisplayCubes
Indicates whether the Cubes group is visible in Server Explorer on startup.
DisplayDimensions
Indicates whether the Dimensions group is visible in Server Explorer on startup.
DisplayExplorerPropertiesWindow
Indicates whether the Properties pane is visible in Server Explorer on startup.
Operations Guide 49
DisplayProcesses
Indicates whether the Processes group is visible in Server Explorer at startup.
DisplayReplications
Indicates whether the Replications group is visible in Server Explorer at startup.
ExpandRowHeaderWidth
Indicates if the Row Headers will automatically expand to accommodate the width of the longest
entry in the column.
ExportAdminSvrSSLCert
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.
InSpreadsheetBrowser
Indicates if the In-Spreadsheet Browser or the Cube Viewer is the default browser.
T - In-Spreadsheet Browser is the default browser. When you double-click a cube or view, it
opens in an Excel document.
F (Default) - Cube Viewer is the default browser. When you double-click a cube or view, it
opens in the Cube Viewer.
IntegratedLogin
Indicates if your TM1 client uses Integrated Login or the standard TM1 security to log in to the
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.
Language
Indicates the language used in the TM1 interface.
ENG - English
FRA - French
DEU - German
JPN - Japanese
ITA - Italian
ESP - Spanish
LocalServerNetworkProtocol
Determines the protocol that the local TM1 server uses to communicate with clients. Currently,
the only valid setting is TCP.
MainWindowLayoutInfo
Generates dimension and position coordinates for the Server Explorer window; allows Server
Explorer dimensions and position to be maintained between sessions.
The coordinates are automatically generated when you move or resize the Server Explorer window.
PreviousAdminHosts
Lists up to six of the most recently accessed Admin Hosts from the TM1 OptionsAdmin Host list.
PreviousDataDirectories
Lists up to six of the most recently accessed data directories in the Local Server Data Directory list
from the TM1 Options.
The directories accessed within a single session are separated by semicolons. The directories accessed
in different sessions are separated by commas.
Operations Guide 51
SecurityAssignmentWindowLayoutInfo
Generates dimension and position coordinates for the Clients/Groups window; allows Clients/Groups
dimensions and position to be maintained between sessions.
The coordinates are automatically generated when you move or resize the Clients/Groups window.
SentMsgsToServerCountWarning
The SentMsgsToServerCountWarning parameter is for development use only. The parameter is set
to F by default. Be sure not to change the default setting.
ShowAdminHostChangeWarning
Between session storage of whether to display or suppress a warning when the AdminHost is
changed.
ShowAliasAttributeWarning
Between session storage of whether to display or suppress a warning when the Alias Attribute is
changed.
ShowChoresSchedulingWarning
Between session storage of whether to display or suppress a warning when a chore schedule is
changed.
ShowCubeReplicationWarning
Between session storage of whether to display or suppress a warning when a cube is replicated.
ShowDimDeleteElementWarning
Between session storage of whether to display or suppress a warning when a dimension element is
deleted.
ShowDimensionAccessWarning
Between session storage of whether to display or suppress a warning when a dimension is accessed.
ShowDynamicSubsetWarning
Between session storage of whether to display or suppress a warning when a Dynamic Subset is
changed.
ShowPickOperationWarning
Between session storage of whether to display or suppress a warning when data is copied using the
Pick Elements option.
T (Default)- A warning message displays any time data is copied using the Pick Elements option.
F - No message displays when data is copied using the Pick Elements option.
ShowProcessUNASCIIWarning
Between session storage of whether to display or suppress a warning when an ASCII datasource is
processed.
is changed.
ShowProcessUNODBCWarning
Between session storage of whether to display or suppress a warning when an ODBC datasource
is processed.
SliceNewWorkbook
Determines how slices are generated from the Cube Viewer.
Operations Guide 53
SubsetWindowLayoutInfo
Generates dimension and position coordinates for the Subset Editor window; allows Subset Editor
dimensions and position to be maintained between sessions.
The coordinates are automatically generated when you move or resize the Subset Editor window.
TM1 Server
TM1 Clients
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.
55
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. 66).
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 Tm1syyyymmddhhmmss.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.
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
Parameter
Required/Optional
Description
-n
Required
Name of the TM1 Server. This will become the Windows service name as
shown when you display the properties of an installed service.
-z
Required
Data directory that contains the tm1.cfg file for the TM1 database.
-u
Optional
Valid user name for the computer on which you are working. Use one of the
following formats:
If you do not provide a user name, the current user account is used by default.
-w
Optional
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
Operations Guide 57
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
Step
A server window opens. The server window lists the cubes and dimensions loaded into the server
RAM.
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 TM1 Server - 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.
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,
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 TM1 Server.
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.
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.
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.
Operations Guide 59
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. 61).
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: A TM1 remote server comes with a predefined administrator ID of ADMIN, and a
password of apple.
Step
Click File, Refresh Available Servers. TM1 displays all running servers that are registered on
the Admin Host to which the client is pointing.
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.
Description
Data Directory
Connect to Local Server on Select or clear the Connect to Local Server on Startup check box
Startup
to control whether the TM1 client automatically connects to the
local server at startup.
Steps
1. In Server Explorer, select the icon for the server from which you want to disconnect.
2. Click Server, Log Out.
Step
Operations Guide 61
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 TM1 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. 68).
A 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.
A TM1 server running as a service 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.
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.
Parameter
Required/Optional
Description
-n
Required
The name of the TM1 server you want to shut down. Note that this server
must have been started in background mode.
-v
Required
IP address of the Admin Server on which the TM1 server is registered.
-user
Required
User name of the person bringing down the server. This person must have
the necessary access and privileges to shut down the server.
-pwd
Required
Password for the person bringing down the server.
-time
Optional
Delay, in seconds, at which the server will be shut down after running
tm1srvstop.exe.
-cancel
Optional
Cancels any previously issued Tm1srvstop.exe commands.Valid values are
T and F.
-unsave
Optional
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 Administrator 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 Transactions
Each 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:
Operations Guide 63
Whether the new data is simple data (N) or string data (S).
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","L
Series 1.6 L Sedan","Units","Jun",""
"19980602212744","19980602212744","Admin","N","430.","600.
","salescube","Budget","Belgium","L
Series 1.6 L Sedan","Units","Sep",""
"19980602212749","19980602212749","Admin","N","610.","800.
","salescube","Budget","Belgium","L
Series 1.6 L Sedan","Units","Oct",""
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.
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.
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:
Parameter
Description
Starting Time
Operations Guide 65
Parameter
Description
End Time
End date and time for the query. The date and time format is
MM/DD/YYYY HH:MM:SS
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.
Clients
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.
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.
66 IBM Cognos TM1
Cube
Description
}StatsByClient
Tracks the message count, average message size, total elapsed time,
and other measures for each client on the server.
}StatsByCube
}StatsByCubeByClient
Tracks the number and elapsed time of cell updates, cell retrievals,
view calculations, and view retrievals for each client and cube on the
server.
}StatsForServer
Tracks the connected clients, active threads, and memory used by the
server.
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:
Operations Guide 67
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.
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.
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.
Steps
1. In the left pane of Server Explorer, select the server you want to shut down.
2. Click Server, Server Manager.
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.
Operations Guide 69
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 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 feature, see the sandbox sections in the IBM Cognos TM1
Users Guide and the IBM Cognos TM1 TurboIntegrator Guide.
DisableSandboxing parameter
MaximumUserSandboxSize parameter
For more details about the Tm1s.cfg file and these parameters, see the "TM1 System Configuration" (p. 23) section in this guide.
Operations Guide 71
Replication Overview
Depending 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.
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.
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.
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
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.
73
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. 77).
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 attempting to perform: Could not
register the cube.
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.
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.
Cube A
Target server
Source server
Region 1
Region 2
Source server
Target server
Cube B
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.
Cube A1
Cube A1
(Mirror of cube A)
(Mirror of cube A)
Region 1
Region 4
Cube A
Central server
Cube A1
Cube A1
(Mirror of cube A)
(Mirror of cube A)
Region 2
Region 3
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.
Operations Guide 75
Cube A
(Mirror of cube A)
Central server
Cube A1
(Mirror of cube A)
Region 3
Cube A2
(Mirror of cube A)
Local server
You can combine the star and chain configurations, as shown below.
Cube A1
Cube A1
(Mirror of cube A)
(Mirror of cube A)
Region 1
Region 4
Cube A
(Mirror of cube A)
Central server
Cube A1
Cube A1
(Mirror of cube A)
(Mirror of cube A)
Region 2
Region 3
Cube A2
Cube A2
Local server
Local server
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.
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 Process" (p. 80).
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. 83).
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
Operations Guide 77
Steps
1. Open the Server Explorer.
2. Make sure that the target server is visible.
3. Double-click the Replications icon for the target server.
For example, to replicate a cube from the sdata server to the financiareporting1 server, doubleclick the Replications icon under the financiareporting1 server.
Specify the username and password with which you want to connect to the source server.
5. Click OK.
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 "Synchronization Process" (p. 83).
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.
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.
Operations Guide 79
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 Process" (p. 83).
Replication Process
After 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 Cube
When 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 following error message: Could not register the cube.
Steps
1. Double-click the Replications icon for the target server.
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.
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.
Steps
1. To specify another name for the mirror cube, enter the name in the Name field.
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.
Operations Guide 81
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.
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.
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.
Step
To specify that you do not want TM1 to copy views for the mirror cube, clear the Replicate
Views option.
Step
To specify that you do not want TM1 to copy subsets for the mirror cube, clear the Replicate
Subsets option.
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 Process
You 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.
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.
Operations Guide 83
TM1 uses 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 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 Demand
To 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 Synchronization
You can create a chore to automatically synchronize data at a regular interval using Turbo Integrator.
For details on Turbo Integrator, 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.
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 synchronization should be executed.
8. Click Finish to complete the scheduling.
Admin
Server Log
Performance Counters
Transaction
Log
Server
Message Log
Audit Log
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
a 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.
85
TM1 Top - A utility that dynamically monitors the threads and processes running in an instance
of a TM1 server. TM1 Top is a stand-alone utility that runs within a console (command) window
on a Microsoft Windows computer.
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. 213).
For details about the TM1 Admin Server, see the "TM1 Admin Server" (p. 15).
Parameter
Description
DEBUG
Detailed, technical messages that are useful when customer support or development engineering need to debug the application.
When logging is configured to this level, DEBUG, INFO, and ERROR messages
are logged.
INFO
Informational messages that highlight the progress of the application and report
normal transitions within the application.
When logging is configured to this level, INFO and ERROR messages are
logged.
Parameter
Description
ERROR
Message level
Log file name
Logger section
Appender section
Logger section - Configures the TM1 sub-components and message severity level that you want
to log.
Appender section - Controls the output destination of the logging. The default configuration
uses the RollingFileAppender option to write messages to the tm1admsrv.log file.
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.
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
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.
Operations Guide 87
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:
Thread ID
Message level
Message text
Logging Transactions
Each 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:
Whether the new data is simple data (N) or string data (S).
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","L
Series 1.6 L Sedan","Units","Jun",""
"19980602212744","19980602212744","Admin","N","430.","600.
","salescube","Budget","Belgium","L
Series 1.6 L Sedan","Units","Sep",""
"19980602212749","19980602212749","Admin","N","610.","800.
","salescube","Budget","Belgium","L
Series 1.6 L Sedan","Units","Oct",""
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.
Operations Guide 89
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:
Parameter
Description
Starting Time
End Time
End date and time for the query. The date and time format is
MM/DD/YYYY HH:MM:SS
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.
Clients
Parameter
Description
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.
Steps
1. Highlight the record(s) you want to back out.
To highlight multiple adjacent records, click the first record and SHIFT+click the last
record.
Example of mesages in the TM1 server message log indicating a corrupt transaction log file.
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.
Parameter
Description
DEBUG
INFO
Operations Guide 93
Parameter
Description
WARN
ERROR
FATAL
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.
TM1 Loggers
TM1 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.
Windows system:TM1_install_dir\custom\tm1data\TM1_sample_dir
Operations Guide 95
Setting a TM1 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 TM1 logger value to OFF will stop all logging for the TM1 logger, and you could
miss any potential WARN, ERROR and FATAL messages.
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."
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
MemorySize
MaxFileSize
MaxBackupIndex
TimeZone
Parameter
Description
MemorySize
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.
Default value is 5 MB.
Use the following format:
log4j.appender.S1.MemorySize=Size Units
where:
Specifies the maximum file size that the log file is allowed to take up on
disk.
Default size is 100 MB.
Uses the following format:
log4j.appender.S1.MaxFileSize=SizeUnits
where:
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.
Operations Guide 97
Parameter
Description
MaxBackupIndex
A numeric value that specifies how many backup files are kept before the
oldest log file is erased.
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.
The backup process repeats each time the MaxFileSize is reached, overwriting the oldest backup file so that only the newest backup files remains.
TimeZone
Specifies the timezone for the message timestamps in the log file. Uses the
following format:
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.
Steps
1. Select the TM1 server in the Server Explorer.
2. Click Server, View Message Log.
The Message Log window opens.
Thread ID
Message Text
TM1 Logger Name
Message Field
Description
Thread ID
Message Level
Message Text
Operations Guide 99
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.
Steps
1. Select the line of text you want to copy.
2. Select Edit, Copy or press CTRL+C to copy.
The currently selected line is copied to the Microsoft Windows clipboard and can then be
pasted into other applications.
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. 101).
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. Additionally, TM1 logs events 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:
Steps
1. Open the tm1s.cfg file for that server.
2. Set the following parameters in the tm1s.cfg file:
AuditLogOn=T
AuditLogUpdateInterval=60
Steps
1. Select a TM1 server in Server Explorer.
2. Click Server, Process Audit Log Events.
3. Click Yes to confirm the update process.
The audit log now contains the latest audit event records.
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.
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.
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.
Click All to search for events caused by any TM1 user or any scheduled chore.
Click Scheduled Chore to search for events caused only by a scheduled chore.
To select a specific TM1 user or scheduled chore, click the Select button
related field.
next to the
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.
Click All to search for both types of audit events; system-wide and object related events.
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.
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
related to a specific element, you must manually enter an element name using the following
format:
DimensionName:ElementName
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.
Message Field
Description
Date
User
TM1 client (user) or scheduled chore that was responsible for causing
the event.
Event Type/Description
Object Type
Object Name
Details
You can sort the results in the grid in ascending or descending order for any column by clicking on
the column title.
Step
To copy event data, highlight an individual cell in the Results grid and then click the Copy
button
Steps
1. Click Find
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
XML (*.xml)
4. Click Save.
Description
}StatsByClient
}StatsByCube
}StatsByCubeByClient
}StatsForServer
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 monitoring when a server starts.
Steps
1. Select the server in the Server Explorer.
2. Click Server, Stop Performance Monitor.
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. 239) and "Control Dimensions" (p. 255).
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.
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. 108).
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.
Parameter
Description
ServerName
TM1 server name. This is the ServerName from the server configuration file, Tm1s.cfg.
AdminHost
Refresh
LogFile
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.
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.
LogPeriod
Specifies the time interval between updates being written to the log
file. This value should be a multiple of the Refresh time parameter.
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.
Parameter
Description
LogAppend
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.
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.
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. 110).
Steps
1. Edit the initialization file, Tm1top.ini, as described in "Configuring the Tm1top.ini File" (p. 108).
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
-OptionName2
-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
For more details on TM1 Top parameters, see "Configuring the Tm1top.ini File" (p. 108).
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.
The following table describes the status fields displayed by TM1 Top.
Field Name
Description
ID
Field Name
Description
User Name
The name of the user or process that started the thread. This can be
one of three possible thread types.
C:chore-name
The name of the process running under the chore is displayed in the
Function field.
State
Th:Stats - The Stats thread represents the thread for the performance monitor feature that is started when a user selects the Start
Performance Monitor option in TM1 Architect and Server Explorer.
The current processing state of a specific thread. This value can be one
of the following values:
Idle
Run
Commit
Rollback
Wait
Login
Field Name
Description
R, IX, and W represent the different lock modes on the object. For
more information, see "Understanding TM1 Lock Modes" (p. 113).
Total lock status and count for all objects being used by a thread.
Displayed in the format: R# IX# W#
Where:
Time
# 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 process has been processing.
The name of the API function or chore process is displayed in the
Function field.
Lock Mode
Description
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.
Lock Mode
Description
IX
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.
State
Description
Idle
Run
Indicates the thread is actively running. Also displays the lock mode and
object being accessed by the thread in the following format:
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. 113).
Object Name is the name of the last TM1 object that was being acted
on by the API function displayed in the Function field.
Commit
Rollback
Indicates the thread encountered a conflict while committing and could not
proceed. The thread will automatically re-try until the conflict is resolved.
State
Description
Wait
Login
Object Name is the name of the last TM1 object that was being acted
on by the API function displayed in the Function field.
Command
Description
Command
Description
Displays a user name and password prompt so a TM1 administrator can log into the current session of TM1 Top and enter
commands to cancel processing in other threads.
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.
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.
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.
Steps
1. Enter V to display the following prompt to verify a TM1 Top session:
Verify Admin Access
Admin User Name:
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.
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.
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.
Threads created
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 Performance Counters in the Microsoft Windows Performance Monitor" (p. 121) .
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:
-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
Field
Description
Counter Name
Group name and counter name for each TM1 performance counter.
Displayed in the format: GroupName:CounterName
For example: Threads:Threads Created
Value
Step
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.
"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 TM1 performance counters display in the performance counter list.
3. Select a TM1 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 TM1 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 performance
counters
Build charts
123
(3) Your IIS Web server must have Microsoft .NET Framework
version 3.0 installed.
Workstation with
Microsoft Internet Explorer
(4) 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 Websheets
back to Excel or to PDF.
Corporate Intranet
Workstation with
Microsoft Internet Explorer
Workstation with
Microsoft Internet Explorer
Limiting Access to a Single TM1 Server from IBM Cognos TM1 Web
If 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 TM1 Perspectives, you can use the
For information about configuring IBM Cognos TM1 Web to access multiple Admin Servers,
see "Configuring the Login Page using the AdminHostName and TM1ServerName Parameters" (p. 150).
For information about configuring TM1 Architect and TM1 Perspectives to access multiple
Admin Servers, see "The Tm1p.ini File" in the "TM1 System Configuration" section of the
IBM Cognos TM1 Operations Guide.
"Running IBM Cognos TM1 Web in Mozilla Firefox Web Browser" (p. 128).
"Running the 64-bit version of IBM Cognos TM1 Web on Windows x64" (p. 130).
"Running IBM Cognos TM1 Web on a WAN Server and Exporting Excel and PDF Files" (p. 130).
"Using ClearType on TM1 Web Server to Enhance Display and Rendering of TM1 Websheets" (p. 131).
Software Requirements
For a comprehensive list of supported operating systems, Web servers, and versions, see the IBM
Cognos TM1 Installation Guide.
Software
Requirement
Operating System
Microsoft Windows
Web server
Microsoft IIS
Microsoft Excel
Web browser
Windows Service
Account
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.
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.
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.
Configuring Microsoft Internet Explorer Version 7 for IBM Cognos TM1 Web
If you are using IBM Cognos TM1 Web with Microsoft Internet Explorer 7, make sure you have
the following security setting enabled to allow IBM Cognos TM1 Web dialog windows to display
correctly. If Microsoft Internet Explorer 7 is not configured correctly, some IBM Cognos TM1 Web
dialogs can incorrectly display an address bar causing the OK and Cancel buttons to not display
as shown below.
Address bar
and buttons
display
incorrectly
Steps
1. In Microsoft Internet Explorer 7, select Tools, Internet Options.
The Internet Options dialog opens.
Operations Guide 127
Enables
proper
display
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:
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
Running the 64-bit version of IBM Cognos TM1 Web on Windows x64
To run the 64-bit version of IBM Cognos TM1 Web on a Microsoft Windows x64 system, you
must:
Note: IBM Cognos TM1 Web requires .NET 3.0, however, .NET 2.0 remains on your system
after installing .NET 3.0.
3. 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 PDF
Files
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.
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.
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.
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. 131)
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 of TM1
Websheets
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
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.
Option
Description
Processes
Chores
Client Properties
Cube Properties
Dimension Properties
Change 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
Steps
1. Log in to IBM Cognos TM1 Web as a TM1 administrator.
2. Click Administration in the left Navigation pane.
3. Click the option relevant to the administrative task you want to perform.
Each administrative task is described below.
Administering Processes
You 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.
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.
Process Attributes
Process Parameters
Note: If your process does not use parameters, the Process Parameters box does not appear.
Administering Chores
You 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.
Process List
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.
134 IBM Cognos TM1
Button
Button Name
Description
Save Chore
Execute Chore
Activate
Activate Chore
Deactivate
Deactivate Chore
Edit Chore
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.
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 Save
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.
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 Chores check box. To exclude
control cubes from the list, clear the Display Control Chores 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.
4. To change the value of a cube property, click the down arrow next to a property and select a
value.
5. Click Save
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.
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.
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.
Steps
1. In TM1 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.
Select client
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.
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. 151).
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 displayed 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 Navigation 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.
Cubeviewer
Websheet
URL
The homepage object displays after the user successfully logs in to IBM Cognos TM1 Web.
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.
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 TM1 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 TM1 Architect and
Server Explorer.
The following sections describe using the HomePageObject parameter for Websheets, cube views,
and URLs.
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"
/>
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.
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
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.
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
Where URL_Path can point to a web site or an individual web page file.
For example:
View node
Administration node
Here are the most common IBM Cognos TM1 Web parameters in the Web.config file that you can
change.
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 TM1WebPlanManToolbar.
aspx defines the TM1 Workflow toolbar.
Note: In IBM Cognos TM1 Web 9.x, TM1WebPlanManToolbar.aspx is the only custom toolbar
TM1 supports.
NavTreeDisplayServerView - Hides or displays the Server View 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.
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.
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.
Parameter
Default Setting/
Description
DisplayCustomToolbar
N
Displays or hides the TM1 Workflow toolbar. The default is N.
Set this value to Y to display the TM1 Workflow toolbar.
CustomToolbarUrl
TM1WebPlanManToolbar.aspx
Name of the custom toolbar executable. The only supported
toolbar is the default value shown here.
CustomToolbarHeight
28
Height in pixels, of the TM1 Workflow toolbar.
PM_ToolbarCaption
TM1 Workflow
String caption on the TM1 Workflow toolbar.
PM_ToolbarCaptionWidth
120
Width of the string caption on the TM1 Workflow toolbar caption.
PM_VersionCaption
Process
Caption for the Process list in TM1 Workflow.
PM_VersionCaptionWidth
70
Width of the Caption for the Version list in the TM1 Workflow
toolbar.
PM_VersionListWidth
150
Width of the Version list in TM1 Workflow.
PM_TaskCaption
Task
Caption for the Task list in the TM1 Workflow toolbar.
Parameter
Default Setting/
Description
PM_TaskCaptionWidth
50
Width of the Task list caption in the TM1 Workflow toolbar.
PM_TaskListWidth
200
Width of the Task list in the TM1 Workflow toolbar.
PM_ActionCaption
Action
Caption for the Action list.
PM_ActionCaptionWidth
55
Width of the Action list caption.
PM_ActionListWidth
120
Width of the Action list.
PM_AllTasksCaption
PM_AllTasksCaptionWidth
30
Width of the All Tasks list caption.
PM_StatusCaption
PM_StatusCaptionWidth
30
Width of the Version status button caption.
PM_CustomizeCaption
PM_CustomizeCaptionWidth 30
Width for the Customize button caption.
PM_LoadCaption
PM_LoadCaptionWidth
30
Width of the Load button caption.
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 display
custom 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.
Steps
1. Edit Web.config in the IBM Cognos TM1 Web virtual directory.
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 toolbars
i 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.
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" />
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 to
display "Administration" node in navigation tree -->
<add key="NavTreeDisplayAdministration" value="Y"
/>
Steps
1. Edit Web.config.
2. Locate the following code:
<!--
Steps
1. Edit Web.config.
2. Locate the following code:
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.
Steps
1. Edit Web.config.
2. Locate the following code:
MaximumSheetsForExport
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 PortNumber must be set to a valid port number, as shown in the following example:
<add key="TM1ExcelServicePortNumber" value="4785"
/>
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"
/>
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"
/>
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.
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" />
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 "Configuring a Custom Homepage for IBM Cognos TM1 Web" (p. 137).
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.
If set to true, the Navigation pane will not be displayed when user's log in to IBM Cognos TM1
Web.
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 TM1 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 TM1
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.
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"
/>
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.
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"
/>
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.
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"
/>
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.
Using the CustomLink Parameter to Open Other URLs and Web Pages
The 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
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=Open
the IBM Web Site;Url=http://www.ibm.com"/>
Note: You must follow standard character escape rules for XML when adding a URL to the XMLbased web.config file. For example, replace the & character with the & escape sequence.
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.
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.
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" />
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:
<!-- Websheet Paging Settings -->
<add key="WebsheetPaging" value="Enabled=false;PageSize=100"
/>
Modify the IBM Cognos TM1 Web virtual directory properties to allow anonymous access.
Modifying the IBM Cognos TM1 Web Virtual Directory to Allow Anonymous
Access
The IBM Cognos TM1 Web installation automatically configures the IBM Cognos TM1 Web virtual
directory to allow anonymous access.
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 TM1Web 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.
7. Click OK to close the Authentication Methods dialog box.
8. Click OK to close the TM1Web Properties dialog box.
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 TM1Web directory on your Web server.
Note: If you accepted the default location during installation, the default directory is C:\Inetpub\
wwwroot\TM1Web.
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.
Click Locations.
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. 156).
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.
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, as shown
in the following figure.
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 periodically when the folders become full.
Parameter
Description
DEBUG
Detailed, technical messages that are useful when TM1 customer support
or development engineering need to debug the application.
When logging is configured to this level, DEBUG, INFO, and ERROR
messages are logged.
INFO
ERROR
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" />
3. Change the level to one of the valid values; DEBUG, INFO, or ERROR.
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" />
If you installed IBM Cognos TM1 Web to the default installation location, then the tm1web_err.log
file is located in the following directory:
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>
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 TM1 sub-component name
<Chores> not localized is the message text.
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:
Operations Guide 163
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" />
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" />
Steps
1. Locate the tm1excelservice_err.log file in the TM1_install_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
Overview
IBM 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:
Easily configure TM1 Web to use any of the six built-in IBM Cognos 8 skins.
Use the TM1 Web URL API to dynamically set the skin for applications that use the TM1 Web
URL API.
The following figures show the available predefined IBM Cognos 8 skins for TM1 Web 9.4 MR1.
Corporate
Classic
Business
Contemporary
Modern
Presentation
Configuration
Each skin for 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:
<TM1Web installation>\css
The supporting images for a skin are installed to a folder using the same name as the skin in the
following location:
<TM1Web installation>images\skins\skin name
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"
/>
corporate
Classic
Business
Contemporary
Modern
Presentation
Using the TM1 Web URL API to Set a TM1 Web Skin
If you are using the 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
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"
/>
Corporate
Classic
Business
Contemporary
Modern
Presentation
For example, the following URL string opens a TM1 Web cube view using the business skin.
http://WebServerName/TM1Web/TM1WebMain.
aspx?action=OpenObject&type=Cubeviewer&value=plan_BudgetPlan$$plan_budget_
input&UserStyle=business
Steps
1. In the <TM1Web 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.
Authentication
When 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.
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 Authentication
With TM1 authentication, the TM1 server checks the user name and password against the user
names and passwords in the TM1 database.
Clients
TM1 Server
Attempt to Establish a Connection
TM1 Architect
TM1 Perspectives
TM1 Web Client
Integrated Login
With 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.
Licensed Materials Property of IBM
Copyright IBM Corp. 2007, 2009.
171
Windows
Authentication
Clients
TM1 Server
(2) Attempt to Establish a TM1 Connection
User supplies a
user name,
password, and
Windows domain
name while
logging into a
Windows
workstation
TM1 Architect
TM1 Perspectives
TM1 Web Client
Windows
Domain
Controller
LDAP Authentication
With 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.
TM1
Server
LDAP
Server
(Active
Directory,
Netscape,
etc.)
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@company.com to the }ClientProperties cube.
Add many user names from an LDAP server to the TM1 database quickly.
Migrate information from a legacy LDAP database to TM1, when you install 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.
Maintain user information after you initially load the user data into TM1, by synchronizing
the TM1 data with the LDAP server.
Note: The ETLDAP utility is not available when a TM1 server is configured to use IBM Cognos
Access Manager (CAM) authentication.
Using ETLDAP
Here are the major steps involved in using ETLDAP.
Run ETLDAP
175
Note: You must use ETLDAP with Integrated Login and LDAP authentication. Otherwise, you
will experience problems when you synchronize your TM1 users with your Windows security
information.
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 ability
to transform
strings
// which are read from the LDAP database before they
are inserted into // TM1's datastore.
// To implement this feature, create a class which extends
stringFilter
// and contains a method 'filterString' with the following
signature:
//
// String filterString(String attrName, String value)
//
//
public class myStringFilter extends stringFilter
{
public String filterString(String attrName, String value)
{
if (attrName.equals("ou"))
{
if ( (attrName.equals("R&D")) ||
(attrName.equals("Quality Assurance")) ||
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 ETLDAP
You can run ETLDAP from Windows or the DOS command prompt.
Field or Button
Description
Search DN
Filter
Displays the query string that filters the entries in the directory and
generates the matching records.
Attributes
Displays the attribute values for LDAP entries that assist in validating
the records returned by the search. When you export the LDAP
information to TM1, ETLDAP retrieve the attributes required to create
valid TM1 users.
Note: The attributes are for display purposes only.
Search Scope
Specifies the starting point of the search, and the search level. Select
One level to specify all entries one level below the base Search DN,
but not the base DN itself. Select Sub-tree level to search all entries
beneath the base DN, including the base DN.
Results Table
Displays the search results. Click the column headers to sort the data,
or right-click in a row and click View Entry to examine all attributes
for that entry.
Search Button
Field or Button
Description
Export Button
Exports the displayed set of users to TM1 based on the settings in the
Options dialog box.
Steps
1. Click Start, Programs, Accessories, Command Prompt.
2. Enter the following command line:
java etldap options
Parameter
Description
-f filename
Passes the name of a saved session file to load all configuration settings
from a previous session.
When you run ETLDAP in unattended (batch) mode, you must include
a name for the session save file. If this file does not contain the passwords
necessary to connect to the LDAP and TM1 servers, an error message is
written to the log file and the session is terminated.
-batch
-secure
When you run ETLDAP in batch mode, passing this flag removes all
passwords from the session file referenced by the -f flag after they have
been read.
This parameter reads the save file at the beginning of the session, and
then re-writes the file with the passwords removed. While in use, you
would run ETLDAP and specify the passwords with the user interface.
Then you would exit ETLDAP and run the command line version specifying the '-secure' option. This would insure that the passwords were only
available for the short period of time it takes for the utility to initialize.
-help
Steps
1. In the LDAP Load Tool dialog box, click File, Connect.
2. Enter the following host and user information.
Panel
Field
Description
Host Info
Host
Port
Version
SSL option
Anonymous option
Host Info
Panel
Field
Description
User Info
User DSN
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.
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
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.
ou: People
uid: rsmith
cn: Rob Smith
ou: Groups
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.
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.
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.
Do you need to build multiple queries to capture the list of records you are interested in?
Steps
1. Click Edit, Login, TM1.
2. Enter the following server information:
Field
Description
Host
The machine name of the server on which your TM1 Admin Server
is running.
Server
The name of the TM1 server to which you want to connect. Click
Server and then the Browse button to select a server from the Server
list.
Field
Description
Username
The name of a user with Admin privileges on the target TM1 server.
Password
3. Click Test.
The status bar displays the Connection Succeeded message in green.
4. Click OK.
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 a TM1 user, and map the department attribute to a
TM1 group.
3. Click OK.
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.
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.
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 log.
The Session Log shows that ETLDAP exported three LDAP users and created them on 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" (p. 171).
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)
Steps
1. Locate the newest record line in the LDAP Session Log.
2. Insert the timestamp portion of the string in parentheses into your Filter line.
Important: Be sure to adhere to the syntax supported by LDAP Filters. See RFC 2254, The
String Representation of LDAP Search Filters.
The following table shows a sample Filter string without any changes, and after modification
for both LDAP and Active Directory servers.
Note: Remember, a standard LDAP server uses the modifytimestamp attribute, and an LDAP
server with Microsoft Active Directory uses the whenChanged attribute.
Initial string
(&(objectclass=person)(|(department=R&D)(department=Documentation)))
(&(objectclass=person)(modifytimestamp>=20030515162433Z)(|(department=R&D*)
(department=QA)))
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.
Steps
1. "Select Integrated Login Option During TM1 Installation" (p. 187).
2. "Run the ETLDAP Utility" (p. 188).
3. "Set Access Rights for TM1 Users" (p. 188).
Steps
1. Run the TM1 Installation Wizard.
2. Select the Integrated Login option.
Licensed Materials Property of IBM
Copyright IBM Corp. 2007, 2009.
187
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.
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.
Note: If you use the NTLM protocol, both the Web server and the TM1 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.
4. Save Tm1s.cfg.
5. Restart your TM1 server.
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.
Steps
1. "Set the Security Protocol on the Web Server to Kerberos" (p. 190)
2. "Grant the Web Server Machine Account Delegation Rights" (p. 191)
3. "Modify the .Net Configuration Files" (p. 191)
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.
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).
Refer to your Windows documentation for more information.
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
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. 187)
2. "Grant the Web Server Machine Account Delegation Rights" (p. 191)
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.
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. 192)
2. "Create a New Application Pool for TM1 Web" (p. 193)
3. "Set the TM1 Web Application Pool to Run Under the TM1 Network User ID" (p. 194)
4. "Add the TM1 Domain User to the IIS_WPG group" (p. 194)
5. "Set the Application Pool for Your TM1 Web Virtual Directory" (p. 194)
6. "Grant the TM1 Service Account Delegation Rights" (p. 195)
7. Set the Service Principal Name (SPN)
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.
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.
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.
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.
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
Add the TM1 Web server to the Local Intranet with default security settings. The procedure
for doing this varies depending on the operating system you are running. Refer to the Internet
Explorer help for more information.
On the Advanced tab under Tools, Internet Options, set Enable Integrated Windows Authentication.
Additional Resources
See the Microsoft support website for more information about setting up ASP applications on IIS
with Windows authentication, such as:
For Integrated Windows Authentication (IIS 6.0), see the Microsoft Windows website.
Steps
1. Run ETLDAP and import the user and group information from your LDAP server, as described
in "Using ETLDAP" (p. 175).
2. Shut down the TM1 server.
3. Edit Tm1s.cfg in your TM1 server data directory, and set the IntegratedSecurityMode parameter
to 2.
4. Edit Tm1s.cfg in your TM1 server data directory, and set the SecurityPackageName parameter
to the security protocol you use for Integrated Login. In the following example, the server is
configured to use Kerberos.
[TM1S]
SecurityLogging=F
SecurityPackagename=Kerberos
IntegratedSecurityMode=2
Servername=myserver
DatabaseDirectory=C:\Program Files\
TM1 Architect
TM1 Perspectives
TM1 Web
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 TM1 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.
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 TM1 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.
Steps
1. Run Microsoft Internet Explorer.
PasswordSource
TM1 (Default)
Compares the user-entered password to the password in the TM1 database.
PasswordSource
LDAP
Compares the user-entered password to the password stored in on the LDAP server.
LDAPPort
636 (Default)
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.
LDAPHost
host
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 IBM
Copyright IBM Corp. 2007, 2009.
199
LDAPWellKnownUserName
An LDAP distinguished name. For example:
uid=bjensen,ou=people,o=company.com
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 T.
LDAPSearchBase
A base distinguished name (DN) in the LDAP directory. For example:
ou=people,o=company.com
Specifies the node in the LDAP tree at which the search for the TM1 User being validated begins.
For example, if the distinguished names are of the form:
uid-bjensen, ou-people, o=company.com
then the search base would be:
ou-people, o=company.com
This is a required field.
LDAPSearchField
cn
The name of the LDAP attribute that is expected to contain the name of the TM1 user being validated. If you do not enter an LDAPSearchField value, the default value is cn, which is also the default
value for Microsoft Active Directory.
LDAPUseServerAccount
T 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. We recommend setting this parameter to T whenever the TM1 server and LDAP server exist
on the same domain.
LDAPPasswordFile
A 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 Admin Server's private key.
This parameter is required only when LDAPUseServerAccount=F.
200 IBM Cognos TM1
LDAPPasswordKeyFile
A 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 Utility" (p. 224).
This parameter is required only when LDAPUseServerAccount=F.
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.
You can configure a TM1 component to use LDAP validation by completing the following procedures:
"Run the TM1 Installation Wizard and Select LDAP Authentication" (p. 201).
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.
Steps
1. Edit TM1s.cfg in your TM1 server data directory.
Operations Guide 201
Use the well known user you specified during the installation to log in to LDAP.
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.
Steps
1. Edit TM1s.cfg in your TM1 server data directory.
2. Modify the following line:
PasswordSource=TM1
To use a password before connecting to the server, add the following lines:
LDAPPasswordFile=file
LDAPPasswordKey=key
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.
205
Steps
1. Open the Tm1s.cfg configuration file in a text editor. Tm1s.cfg is located in the TM1 server's
data directory.
2. Add the following parameters to the configuration file.
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
http[s]://host IP address:port/p2pd/servlet/dispatch
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.
CAMSSLCertificate 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.
This parameter is required only if the IBM Cognos 8 server is configured to use SSL.
SkipSSLCAMHost- Indicates whether the SSL certificate ID confirmation process can
Check
be skipped. The default is FALSE.
Important: This parameter should be set to TRUE only if using a
generic certificate for demonstration purposes.
ClientPingCAMPass- Indicates the interval, in seconds, that a client should ping the IBM
port
Cognos 8 server to keep their passport alive.
If an error occurs or the passport expires the user will be disconnected from the TM1 server.
CAMPortalVariable- The path to the variables_TM1.xml file in your C8 installation.
File
In most cases, the path will be:
CAMPortalVariableFile
= portal\variables_TM1.xml
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.
Parameter Name
Description
CognosGatewayURI
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
Steps
1. Log in to your TM1 server 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
If you are not using the TM1 Contributor component, set the parameter to 4.
IntegratedSecurityMode=4
If you are using TM1 Contributor with IBM Cognos 8 security, set the parameter to 5 to
support user groups from both TM1 and Cognos 8.
IntegratedSecurityMode=5
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 a 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
Creating Users
When a 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 appropriate TM1 groups. There is no need to manually assign users to groups in TM1.
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 TM1 Operations Guide.
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.
Authentication Behavior
The following rules govern authentication behavior when logging on to a 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 TM1 server is configured to use IBM Cognos 8
authentication.
Steps
1. From the Server Explorer, click Server, then Logon As.
2. In the Cognos Logon window, enter the User ID and Password you want to use to log on to
the TM1 server.
3. Click OK.
TM1 Servers
not configured to use SSL
TM1 Servers
configured to use SSL
213
TM1-Generated Certificates
When 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 runTM1 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.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
Parameter
Description
SupportNonSSLClients
SSLCertAuthority
The full path of the TM1 Admin Server's certificate authority file.
SSLCertificate
The full path of the TM1 Admin Server's certificate file, which
contains the public/private key pair.
DHFile-512
The full path name of the file that contains a pre-generated DiffieHellman 512 bit key.
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 DiffieHellman 512 bit key should be pre-generated and stored in a file
that is called when the Admin Server starts.
DHFile-1024
SSLPrivateKeyPwdFile
The full path of the file that contains the encrypted password for the
TM1 Admin Server's private key.
SSLPwdKeyFile
The full path of the file that contains the key used to encrypt and
decrypt the password for the private key.
Parameter
Description
ExportSvrSSLCert
SSLCertificateID
Specifies the name of the principal to whom the TM1 Admin Server's
certificate is issued to.
SSLCertRevocationFile
The full path of the TM1 Admin Server's certificate revocation file.
A certificate revocation file will only exist in the event a certificate
had been revoked.
SvrSSLExportKeyID
Specifies the identity key used to export the Admin Server's certificate
from the Windows certificate store.
This parameter is required only if you choose to use the certificate
store.
Parameter
Description
UseSSL
AdminSvrSSLCertID
AdminSvrSSLCertAuthority The full path of the certificate authority file that issued the TM1
Admin Server's certificate.
AdminSvrSSLCertRevList
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
ExportAdminSvrSSLCert
AdminSvrSSLExportKeyID Specifies the identity key used to export the Admin Server's certificate from the Windows certificate store.
SSLCertificate
The full path of the certificate file that contains the public/private
key pair.
SSLCertAuthority
The name of the TM1 server's certificate authority file. This file
must reside on the computer where the TM1 server is installed.
SSLCertRevocationFile
Parameter
Description
SSLCertificateID
ExportSvrSSLCert
SvrSSLExportKeyID
The identity key used to export the TM1 server's certificate from
the Windows certificate store.
This parameter is required only if you choose to use the certificate
store by setting ExportSvrSSLCert=T.
SSLPrivateKeyPwdFile
The full path of the file that contains the encrypted password for
the private key.
SSLPwdKeyFile
The full path of the file that contains the key used to encrypt and
decrypt the password for the private key.
Parameter
Description
ClientExportSSLSvrCert
ClientExportSSLSvrKeyID The identity key used by the TM1 client to export the certificate
authority certificate, which was originally used to issue the TM1
server's certificate, from the Windows certificate store.
DHFile-512
The full path of the file that contains the pre-generated DiffieHellman 512 bit key.
The generation of Diffie-Hellman parameters can be computationally 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.
DHFile-1024
The full path name of the file that contains the pre-generated DiffieHellman 1024 bit key.
The generation of Diffie-Hellman parameters can be computationally 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.
Option Name
Corresponding
Tm1p.ini Parameter
Description
Certificate Authority AdminSvrSSLCertAu- The full path of the certificate authority file that
thority
issued the TM1 Admin Server's certificate.
Option Name
Corresponding
Tm1p.ini Parameter
Description
Certificate Revocation AdminSvrSSLCertRe- The full path of the certificate revocation file
List
vList
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.
Certificate ID
ExportAdminSvrSSLCert
Parameter
Description
AdminSvrSSLCertAuthority The full path of the certificate authority file that issued the TM1
Admin Server's certificate.
AdminSvrSSLCertID
The name of the principal to whom the TM1 Admin Server's certificate is issued.
AdminSvrSSLCertRevList
The 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.
ExportAdminSvrSSLCert
AdminSvrSSLExportKeyID The identity key used to export the certificate authority certificate
which issued the TM1 Admin server's certificate from the Windows
certificate store.
This parameter is required only if you choose to use the certificate
store by setting ExportAdminSvrSSLCert=T.
This default entry configures TM1 Web to use SSL, relying on the TM1-generated certificates that
are included as part of your TM1 installation.
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 -file
ACompanyca.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=Company
com.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.
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.
Parameter
Description
-Djavax.net.sll.truststore
Use this parameter to specify the full path to the Java certificate
store containing the public root authority certificate.
For example, to use the Java certificate store installed with TM1,
use the parameter -Djavax.net.sll.truststore= C:\Program Files\
Cognos\TM1\bin\ssl\tm1store
-Djavax.net.ssl.trustStorePassword
Use this parameter to specify the password used to create the Java
certificate store.
For example, to specify the password used to create the Java certificate store installed with TM1, use the parameter -Djavax.net.ssl.
trustStorePassword=applix
Steps
1. From the Windows Start menu, click Start, Run and enter mmc to open the Microsoft Management 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.
Option
Description
-pwd
The password for the private key. This should be the same password you
used to encrypt your certificate in Step 11 above.
-keyfile
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.
If this parameter is not specified, TM1Crypt generates a file named
tm1key.dat.
-outfile
The name of the .dat file that will be generated to contain the encrypted
password for the private key.
If this parameter is not specified, TM1Crypt generates a file named
tm1cipher.dat.
Option
Description
-validate
If you include the -validate parameter, the utility will decrypt the
encrypted password and display the results as clear text.
The displayed text should correspond to the password you specified with
the -pwd parameter.
This parameter does not allow validation of exiting 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.
Parameter
Value
ExportSvrSSLCert
SSLCertAuthority
SSLCertificateID
The name of the principal to whom the TM1 Admin Server's certificate is issued.
You can determine this value by referring to the Microsoft Management Console and clicking CertificatesPersonalCertificates. The
principal name displays in the Issued To column of the Properties
pane.
Parameter
Value
SSLPrivateKeyPwdFile
The full path to the .dat file that contains the encrypted password
for the private key.private key.
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
SSLPwdKeyFile
The full path to the .dat file that contains the key used to encrypt
and decrypt the password for the private key.
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
SvrSSLExportKeyID
Specifies the identity key used to export the Admin Server's certificate
from the Windows certificate store.
In most cases, the value for SvrSSLExportKeyID will be identical to
the value for SSLCertificateID.
Parameter
Value
AdminSvrSSLCertID
AdminSvrSSLExportKeyID Specifies the identity key used to export the Admin Server's certificate from the Windows certificate store.
Parameter
Value
ClientExportSSLSvrCert
ClientExportSSLSvrKeyID The identity key used by the TM1 client to export the certificate
authority certificate, which was originally used to issue the TM1
server's certificate, from the Windows certificate store.
ExportAdminSvrSSLCert
ExportSvrSSLCert
SSLCertAuthority
SSLCertificateID
The name of the principal to whom the TM1 Admin Server's certificate is issued.
You can determine this value by referring to the Microsoft Management Console and clicking CertificatesPersonalCertificates.
The principal name displays in the Issued To column of the Properties pane.
Parameter
Value
SSLPrivateKeyPwdFile
The full path to the .dat file that contains the encrypted password
for the private key.private key.
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 full path to the .dat file that contains the key used to encrypt
and decrypt the password for the private key.
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
SvrSSLExportKeyID
Specifies the identity key used to export the TM1 server's certificate
from the Windows certificate store.
In most cases, the value for SvrSSLExportKeyID will be identical
to the value for SSLCertificateID.
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 TM1 server.
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:
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.
229
User Name
Password
Group Membership
Admin
apple
ADMIN
Usr1
red
North America
Usr2
orange
South America
Usr3
blue
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.
The security assignments for these three administrator groups are hard-coded and can not be
modified.
ADMIN Group
The 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:
Reserve and lock cubes, elements, and dimensions, so that other users cannot update them.
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 Group
The 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.
As a member of the SecurityAdmin group, you can manage TM1 security using the following tools
in Server Explorer:
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.
DataAdmin Group
Members 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.
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.
Adding a User
To 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.
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.
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 Group
A 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 User
To 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.
3. Click Clients, Delete Client.
4. Click Yes to confirm the deletion.
Deleting a Group
To delete a group, complete the following steps.
Steps
1. From the Server Explorer, right-click the server icon, and click SecurityClients/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.
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.
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.
Assigning Passwords.
Assigning Passwords
Members 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.
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 Password
You 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.
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.
Clearing a Password
To 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 Password
Note: 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.
Steps
1. From the Server Explorer, right-click the server icon, and click Security, Clients/Groups.
Purpose
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.
}CellSecurity_CubeName
TM1 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 Developers Guide.
239
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:
Dimension
Elements
}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.
}ChoreSecurity
The }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. The next figure
shows the }ChoreSecurity cube that corresponds with the settings in the TM1 Security Assignments
window.
For details on using the TM1 user interface to define chore security and for definitions of security
privileges, see the IBM Cognos TM1 Developers Guide.
Dimensions
The }ChoreSecurity controlcube contains the following dimensions:
Dimension
Elements
}Chores
}Groups
}ClientSecurity
The }ClientSecurity control cube defines user group access to properties for individual clients on a
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.
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.
}CubeSecurity
The}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 Developers Guide.
Dimensions
The }CubeSecurity control cube contains the following dimensions:
Dimension
Elements
}Cubes
}Groups
}DimensionSecurity
The}DimensionSecurity control cube stores security definitions for all dimensions, including control
dimensions 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 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 Developers Guide.
Dimensions
The }DimensionSecurity control cube contains the following dimensions:
Dimension
Elements
}Dimensions
}Groups
}ElementSecurity_DimensionName
The }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
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.
Dimensions
An }ElementSecurity_DimensionName cube contains the following dimensions:
Dimension
Elements
DimensionName
}Groups
}ProcessSecurity
The }ProcessSecurity control cube stores security definitions for all TurboIntegrator processes on
the TM1 server.
Dimensions
The }ProcessSecurity cube contains the following dimensions:
Dimension
Elements
}Processes
}Groups
}ClientsGroups
The }ClientsGroups cube stores group assignments for all clients on a 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 Developers Guide.
The cells in the }ClientsGroups cube contain strings that assign clients to one or more of the user
groups available on the TM1 server. For example, the following figure shows the group assignments
for the clients that are part of the sample data that ships with TM1.
In this example:
Usr3 client is assigned to both the North America and South America groups
Dimensions
The }ClientsGroups control cube contains the following dimensions:
Dimension
Elements
}Clients
}Groups
}ClientProperties
The}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:
Dimension
Elements
}Clients
}ClientProperties
Properties that can be set for TM1 clients, including Password, PasswordExpirationDays, and MaximumPorts.
For complete details on this dimension, see Control Dimensions.
}ConnectionProperties.
}CubeProperties.
}DimensionProperties.
}DimensionAttributes.
}ElementAttributes_DimensionName.
}ConnectionProperties
The }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:
Dimension
Elements
}Connections
}ConnectionProperties
}CubeProperties
The }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.
Dimensions
The }CubeProperties cube contains the following dimensions:
Dimension
Elements
}Cubes
}CubeProperties
}DimensionProperties
The }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:
Dimension
Elements
}Dimensions
Dimension
Elements
}DimensionProperties
}DimensionAttributes
The }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 }DimensionAttributes cube.
Dimensions
The }DimensionAttributes cube contains the following dimensions:
Dimension
Elements
}Dimensions
}DimensionAttributes
}ElementAttributes_DimensionName
The }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 clicking Dimension,
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:
Dimension
Elements
DimensionName
Dimension
Elements
}ElementAttributes_DimensionName
}HierarchyProperties
The }HierarchyProperties control cube stores custom named levels for the hierarchy levels of a TM1
dimension.
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
Developers Guide.
Dimensions
The }HierarchyProperties cube contains the following dimensions:
Dimension
Elements
}Dimensions
}Hierarchies
}HierarchyProperties
A single element, named defaultMember, for assigning the default member of the dimension.
}StatsByClient
For 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:
Dimension
Elements
}StatsStatsByClient
}PerfClients
Each client on the server, plus the consolidated element Clients Total,
which is a consolidation of all clients.
}TimeIntervals
}StatsByCube
For 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:
Dimension
Elements
}StatsStatsByCube
}PerfCubes
}TimeIntervals
}StatsByCubeByClient
For 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.
Dimensions
The }StatsByCubeByClient cube contains the following dimensions:
Dimension
Elements
}PerfClients
}PerfCubes
Dimension
Elements
}CubeFunctions
}StatsStatsByCubeByClient
}TimeIntervals
}StatsForServer
The }StatsForServer control cube tracks the connected clients, active threads, and memory used for
the server.
Dimensions
The }StatsForServer cube contains the following dimensions:
Dimension
Elements
}StatsStatsForServer
}TimeIntervals
}Hold_UserName_CubeName
The }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:
Dimension
Elements
}Hold
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.
}Chores
The }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 TM1 server.
}ClientProperties
This }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 TM1 server.
Element
Description
MaximumPorts
PASSWORD
PasswordExpirationDays
Indicates the number of days for which a given client's password remains
valid.
PasswordLastTimeUp- Indicates the last time (GMT) the password for a given client was
dated
updated. The time format is yyyymmddhhss .
STATUS
}Clients
The }Clients dimension contains string elements that correspond to the clients defined on the TM1
server. This dimension is used in the }ClientGroups and }ClientProperties control cube.
255
}ConnectionProperties
The }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 TM1 server.
Element
Description
LASTSYNC
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.
LASTSYNCSTAR
Time (GMT) at which the data was last synchronized on the star server
for the replication connection. The time format is yyyymmddhhss.
PASSWORD
SYNCPLANET
Determines if the data on the planet server is updated during the synchronization process.
SYNCSTAR
Determines if the data on the star server is updated during the synchronization process.
USER
For a given replication connection, stores the name of the user who
established the connection.
}Connections
The }Connections dimension contains string elements that correspond to the replication connections
defined on the TM1 server. This dimension is used only in the }ConnectionProperties control cube.
}CubeFunctions
The }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:
Element
Description
Cell Retrieval
Element
Description
Cell Update
Cell updates include user input through the Cube Viewer, In-Spreadsheet Browser, TM1 Web, and slices.
Cells updated through rule calculations or other methods are not
included in this metric.
View Calculation
Number of views requested, which can be user requests for Cube Viewer
or slices.
View Retrieval
}CubeProperties
The }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 TM1 server.
Element
Description
DemandLoad
Lock
When a cube is locked, this property stores the name of the TM1 client
that has locked the cube.
Logging
Measures_Dimension
If a measures dimension has been defined for a given cube, this property
stores the name of the dimension.
Replication
For replicated cubes, this property stores the name of the replication
connection with which the replicated cube is associated.
RepSrcName
For replicated cubes, this property stores the name of the source cube.
RepStatus
SyncRule
For replicated cubes, this property indicates whether rules are synchronized when the associated cube is synchronized.
Element
Description
SyncViews
For replicated cubes, this property indicates whether views are synchronized when the associated cube is synchronized.
Time_Dimension
If a time dimension has been defined for a given cube, this property
stores the name of the dimension.
VMM
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.
If no VMM value is specified the default value is 65,536 bytes. The valid
range is 16,384 - 4,2934,943,296 bytes.
VMT
For each cube, this property defines the time threshold, in seconds,
beyond which the algorithm that stores TM1 stargate views is triggered.
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 Stargate Views" (p. 70).
}Cubes
The }Cubes dimension contains string elements corresponding to the cubes, including control cubes,
on the TM1 server. The }Cubes dimension is used only in the }DimensionAttributes control cube.
}DimensionAttributes
The }DimensionAttributes dimension contains numeric elements that correspond to the attributes
defined for dimensions on the TM1 server. The }DimensionAttributes dimension is used in the
}CubeSecurity and }CubeProperties control cube.
}DimensionProperties
The }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 TM1 server.
Element
Description
Default_Hierarchy
DemandLoad
Last_Time_Updated
Time (GMT) at which a dimension was last updated. The time format
is yyyymmddhhss.
Lock
When a dimension is locked, this property stores the name of the TM1
client that has locked the dimension.
Replication
For replicated cubes, this property stores the name of the replication
connection with which the replicated cube is associated.
RepSrcName
For replicated dimensions, this property stores the name of the source
dimension.
RepStatus
SortComponentsSense
SortComponentsType
SortElementsSense
SortElementsType
SyncAttributes
SyncSubsets
For replicated cubes, this property indicates whether subsets are synchronized when the associated dimension is synchronized.
}Dimensions
The }Dimensions dimension contains string elements the correspond to the dimensions, including
control dimensions, on the TM1 server. The }Dimensions dimension is used only in the }DimensionsProperties control cube.
}ElementAttributes_DimensionName
The}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.
}Groups
The }Groups dimension contains string elements that correspond to the user groups defined on the
TM1 server. The }Groups dimension is used only in the }ClientGroups control cube.
}Hierarchies
The }Hierarchies dimension is used in the }HierarchyProperties control cube.
This dimension contains only one element, named hierarchy0, that is used with the }HierarchyProperties dimension to assign named levels to the hierarchy levels of a TM1 dimension.
}HierarchyProperties
The }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:
Element
Description
defaultMember
level000 - level020
}Hold
The }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.
Element
Description
OriginalVal
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.
HoldStatus
This string element identifies cells held by UserName in the CubeName cube.
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 consolidation hold against a cell.
}PerfClients
The }PerfClients dimension contains numeric elements that correspond to the clients defined on the
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
}StatsByCubeByClient
The }PerfClients dimension differs from the }Clients dimension in that the }PerfClients dimension
contains numeric elements, while the }Clients dimension contains string elements.
}PerfCubes
The }PerfCubes dimension contains numeric elements that correspond to the cubes on the 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.
}Processes
The }Processes dimension contains string elements that correspond to the TurboIntegrator processes
defined on the TM1 server. The }Processes dimension is used only in the }ProcessSecurity control
cube.
}StatsStatsByClient
The }StatsStatsByClient dimension is used in the }StatsByClient control cube. This dimension contains
the following measures:
Element
Description
Bytes/Message
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.
Message Bytes
Message Count
Request Count
}StatsStatsByCube
The }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:
Element
Description
Memory Used for Input Data This includes memory allocated to data loaded through TurboIntegrator or process worksheets. This measures the memory used
for all data input other than slice or Cube Viewer input.
Memory Used for Views
Element
Description
Number of Populated
Numeric Cells
This metric counts all the populated string cells in a given cube.
String cells are cells identified by at least one string element.
Number of Populated String This metric counts all the populated string cells in a given cube.
Cells
String cells are cells identified by at least one string element.
Number of Stored Calculated This metric counts all stored calculated cells including rules,
Cells
dimensional consolidations, and user-defined consolidations.
Number of Stored Views
}StatsStatsByCubeByClient
The }StatsStatsByCubeByClient dimension is used only in the }StatsByCubeByClient control cube.
The dimension contains the following elements:
Element
Description
Count
For a given type of cube function, this metric measures the elapsed
time required to execute all functions.
}StatsStatsForServer
The}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:
Element
Description
Memory In Garbage
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 Used
Element
Description
Number of Active Threads This measures the number of threads active on the TM1 server. Each
client connection constitutes a thread. Threads are also used to
execute chores and processes.
Number of Connected Cli- This statistic measures the number of active connections to the TM1
ents
server. An individual client can have multiple connections to the
TM1 server active simultaneously. Each connection is counted in
this metric.
}TimeIntervals
All 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
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.
Steps
1. Log on to the HP UX 11i machine as root.
2. From a command prompt, enter /usr/sbin/sam.
The System Administration Manager displays.
3. Double-click Kernel Configuration.
4. Double click Configurable Parameters.
The Kernel Configuration window displays.
5. Double-click the name of the parameter you want to edit.
The Modify Configurable Parameter dialog box displays.
6. Click Specify New Formula/Value.
7. Enter a new parameter value in the Formula/Value field.
8. Click OK.
9. Repeat steps 5 - 8 for any other parameters you want to edit.
10. Choose File, Exit from the Kernel Configuration window.
The Create a New Kernel dialog box appears.
11. Select Create a New Kernel Now.
Licensed Materials Property of IBM
Copyright IBM Corp. 2007, 2009.
267
maxdsiz_64bit
This parameter sets the maximum size (in bytes) of the data segment for any user process.
Recommended Value
We recommend setting this kernel parameter value to 0x400000000 (hex).
maxssiz_64bit
This parameter sets the maximum size (in bytes) of the stack for any user process.
Recommended Value
We recommend setting this kernel parameter value to 0x10000000 (hex).
max_thread_proc
This parameter sets the maximum number of threads allowed per process.
Recommended Value
We recommend setting this kernel parameter value to 0x200 (hex).
Note: This parameter value must be equal to or less than the value of nkthread, which limits the
total number of threads allowed to run simultaneously.
List of Events
Excel Event Name
Description
NewWorkbook
WorkbookOpen
WorkbookBeforeSave
WorkbookBeforeClose
WorkbookActivate
This event is handled to correctly set the status of TM1 toolbars &
menu bars.
WorkbookAddinUninstall
SheetActivate
This event is handled to update the TM1 toolbar and menu bar
states, as well as to update sheet-specific variables.
SheetDeactivate
SheetSelectionChange
SheetChange
This event is handled to update the TM1 database with the changes
made to a particular cell.
SheetBeforeDoubleClick
This event is handled to post TM1-specific dialog boxes on particular TM1 cells.
269
Description
SheetBeforeRightClick
Glossary
access control
In computer security, the process of ensuring that users can access only those resources of a computer
system for which they are authorized.
admin group
In TM1, the access control group that has completely open privileges to modify, create, and delete
data.
alert
A message or other indication that signals an event or an impending event.
alias
An alternative name used instead of a primary name.
authentication
The process of validating the identity of a user or server.
cell security
In TM1, the access control level assigned to the intersection of a row and column of data in a
database, dimension, or spreadsheet.
child
A node that is subordinate to another node in a tree structure.
chore
In TM1, an object that executes one or more processes for importing data at a user-defined frequency.
client
A software program or computer that requests services from a server. In TM1, client can also refer
to the user who initiates a request.
cube
A multidimensional representation of data used for online analytical processing, multidimensional
reporting, or multidimensional planning applications.
data source
In TM1, the file or data used as the source for the TurboIntegrator import process.
271
Glossary
dimension
In TM1, in multidimensional data, a structural attribute of a cube that organizes data at the highest
consolidation level.
drill down
To access information by starting with a general category and moving through the hierarchy of
information.
drill through
In TM1, the ability to see detail or context information about a cells contents.
element
In TM1, an element is a structural attribute of a dimension that organizes data one level below the
dimension.
feeder statements
In TM1, lines of code which cause placeholder values to be stored in rules-calculated cells so that
the cells are not skipped during consolidations.
filter
A device or program that separates data, signals, or material in accordance with specified criteria.
group
In TM1, an organizational structure of clients or users with the same access level.
Integrated Login
In TM1, using the Windows logon information as authentication for access to TM1 so that once
the user has logged into Windows, no additional login is required to log into TM1. Not available
on UNIX servers.
LDAP
Lightweight Directory Access Protocol--an authentication standard used to manage access for directories of users and passwords.
LDAP authentication
Process used to authenticate users and passwords against an external LDAP directory on an LDAP
server, such as Active Directory.
Glossary
leaf
In a data tree, an entry or node that has no children.
MDX
Multidimensional Expression Language: A structured query language (SQL) for OLAP databases,
used for calculations with syntax similar to spreadsheet formulas.
metadata
Data that describes the characteristics of data; descriptive data.
object security
In TM1, the access control level assigned to a programming object.
OLAP
Online Analytical Processing; the process of collecting data from one or many sources; transforming
and analyzing the consolidated data quickly and interactively; and examining the results across
different dimensions of the data by looking for patterns, trends, and exceptions within complex
relationships of that data.
picklist
A list of cell values available to a user when entering data into a cell.
process
A progressively continuing procedure consisting of a series of controlled activities that are systematically directed toward a particular result or end.
process security
In TM1, the access control assigned to a process.
read-only user
In TM1, a level of access assigned to a usergroup that allows the user to look at but not modify the
data in a TM1 database.
rules
In TM1, a set of commands and tools used to create specific calculations and optimizations within
cubes.
rules tracer
In TM1, the utility used to develop and debug TM1 rules.
sandbox
In TM1, the ability to store data value changes before submitting changes to the server.
Glossary
scenario
In TM1, a dimension that stores budget data.
service
In TM1, a software program that runs in the background and manages requests to and from TM1
data, other machines, or other programs.
sibling
One of several nodes within the scope of another node.
slice
In TM1, a view of a cube saved as a standard worksheet that retains a link to the cube so that
changes made in the cube or in the slice update the data.
spreading
In TM1, the distribution of values across a number range using a specific algorithm, such as percent
or increments.
subset
A set of elements from within another set.
TM1 object
In TM1, constructs such as TM1 databases, cubes, dimensions, elements, cells, chores, processes,
spreadsheets, views, or text files on a TM1 server that in object-oriented programming are defined
as instances of a class.
TurboIntegrator
In TM1, the software tool used to automate importing data into TM1.
version
In TM1, a dimension that stores budget data.
websheet
In TM1, an Excel worksheet that is accessed via TM1 Web.
webskin
The visual attributes of the user interface used in a Web-based software program.
Glossary
zero suppression
In TM1, the substitution of blanks for leading zeros in a number. For example, 00057 becomes 57
with zero suppression.
Glossary
Index
Symbols
.blb file extension, 19
.cfg file, 15, 18, 20, 23
.cho file extension, 19
.cub file extension, 19
.dim file extension, 19
.dit file extension, 19
.ini file, 20, 46, 60
.pro file extension, 19
.rej file, 55, 64, 89
.rux file extension, 19
.sub file extension, 19
.tbu file extension, 19
.tqu file extension, 19
.tru file extension, 19
.vue file extension, 19
.xdi file extension, 19
.xru file extension, 19
}CellSecurity_CubeName control cube, 239
}Chores control dimension, 255
}ChoreSecurity control cube, 240
}ClientProperties control cube, 245
}ClientProperties control dimension, 255
}Clients control dimension, 255
}ClientSecurity control cube, 241
}ClientsGroups control cube, 244
}ConnectionProperties control cube, 246
}ConnectionProperties control dimension, 256
}Connections control dimension, 256
}CubeFunctions control dimension, 256
}CubeProperties control cube, 246
}CubeProperties control dimension, 257
}Cubes control dimension, 258
}CubeSecurity control cube, 242
}DimensionAttributes control cube, 248
}DimensionAttributes control dimension, 258
}DimensionProperties control cube, 247
}DimensionProperties control dimension, 258
}Dimensions control dimension, 259
}DimensionSecurity control cube, 242
Licensed Materials Property of IBM
Copyright IBM Corp. 2007, 2009.
A
access
control, 172
privileges, and replication, 76
privileges, data directory, 21
privileges, groups, 229
privileges, Read, 76, 83
privileges, synchronization, 83
privileges, Write, 83
Activate Chore, 134
active directory, 175
Add Counters, 121
277
Index
ADMIN group, 231
assigning passwords, 236
AdminHost, 24, 47
Admin Host, 58, 61
location, 18
resetting, 61
specifying multiple, 19
AdminHost parameter, 108, 219, 220
specify location, 18
SSL, 216
administration
chores, 134
clients, 135
cube properties, 136
dimension properties, 136
processes, 133
web.config, 142
administration, chore toolbar, 134
administrative groups, 230
Admin server, 15, 55, 58
diagram, 15
IP address, 15
name, 15
port number, 15
protocol, 15
status, 18
UNIX, 18
Windows, 17
Windows Startup directory, 17
Windows status, 18
AdminSvrSSLCertAuthority, 47
AdminSvrSSLCert Authority, 216
AdminSvrSSLCertID, 47, 216
AdminSvrSSLCertRevList, 47, 216
AdminSvrSSLExportKeyID, 47, 216
AdvancedRulesEditor, 47
AllowDynamicSlice, 25
AllowImportCamClients, 48
AllowImportCAMClients, 208
AllowReadOnlyChore Reschedule, 25
AllowSeparateNandCRules, 25
AllRuleCalcStargateOptimization, 25
anonymous access, 156
Architect, 15, 20
architecture, 123
assigning users to groups, 235
278 IBM Cognos TM1
attributes, 177
Audit log
configuring, 101
copying data, 105
details, 105
exporting results, 105
find feature, 105
object events, 100
queries, 102
results, 104
system-wide events, 100
understanding events, 100
updating with latest records, 102
using, 100
viewing, 102
Audit log, overview, 100
AuditLogMaxFileSize, 26
AuditLogMaxQueryMemory, 26
AuditLogMaxTempFileSize, 27
AuditLogOn, 27
AuditLogUpdateInterval, 27
authentication, 205
integrated login, 171
integrated login diagram, 171
standard TM1, 171
authentication, LDAP, 171
authentication, LDAP diagram, 172
B
background mode, 60
BrowseDisplayReadsRightToLeft, 48
browser view, 70
C
CalculationThresholdFor Storage, 27
CAMID, 205
CAMPortalVariableFile, 29, 206
CAMSSLCertificate, 28, 206
cancel TM1 Top, 116
cell-level security, 229
certificate
authority, 214
revocation, 214
store, 214
chain configuration, 74
server, 74
Index
change password, 132, 137, 237
CheckFeedersMaximumCells, 28
chore
administration node, 132
administration toolbar, 134
synchronization, 84
chore, properties, 134
ClassicSliceMode, 48
clearing passwords, 237
ClearType Tuner utility
on Web server, 131
client
connections, 68
disconnecting, 68
messages, 68
properties administration node, 132
query, 90
TM1, 15, 20
client, properties, 135
ClientCAMURI, 28, 206
ClientExportSSLSvrCert, 216
ClientExportSSLSvrKeyID, 216
ClientMessagePortNumber, 29
ClientPingCAMPassport, 28, 206
ClientPropertiesSyncInterval, 29
ClientVersionMaximum, 29
ClientVersionMinimum, 30
Close, 134
Cognos 8 authentication, 205
defining an administrator, 209
importing groups into TM1, 210
Cognos 8 security, 205
administrator considerations, 211
user considerations, 211
CognosGatewayURI, 48, 208
Cognos security passport, 205
command prompt TM1 Top, 115
commit TM1 Top, 114
configure
TM1 Top utility, 108
configure login page, 150
ConnectLocalAtStartup, 48
control cube, 67, 106, 239
}CellSecurity_CubeName, 239
}ChoreSecurity, 240
}ClientProperties, 245
}ClientSecurity, 241
}ClientsGroups, 244
}ConnectionProperties, 246
}CubeProperties, 246
}CubeSecurity, 242
}DimensionAttributes, 248
}DimensionProperties, 247
}DimensionSecurity, 242
}ElementAttributes_DimensionName, 248
}ElementSecurity_DimensionName, 243
}HierarchyProperties, 249
}Hold_UserName_CubeName, 253
}ProcessSecurity, 244
}StatsByClient, 250
}StatsByCube, 250
}StatsByCubeByClient, 251
}StatsForServer, 252
client and group administration, 244
object attribute and property, 246
performance monitoring, 249
security, 239
control dimension, 255
}Chores, 255
}ClientProperties, 255
}Clients, 255
}ConnectionProperties, 256
}Connections, 256
}CubeFunctions, 256
}CubeProperties, 257
}Cubes, 258
}DimensionAttributes, 258
}DimensionProperties, 258
}Dimensions, 259
}ElementAttributes_DimensionName, 260
}Groups, 260
}Hierarchies, 260
}HierarchyProperties, 260
}Hold, 260
}PerfClients, 261
}PerfCubes, 261
}Processes, 261
}StatsStatsByClient, 262
}StatsStatsByCube, 262
}StatsStatsByCubeByClient, 263
}StatsStatsForServer, 263
}TimeIntervals, 264
Operations Guide 279
Index
controlling object security, 172
copy
dimension, 82
Counter Name, 119
cube, 84, 90
enabling and disabling logging, 65, 89
mirror, 74
properties, administration node, 132
replicating, 73, 80
security, 229
source, 74, 80, 81, 82, 83, 84
specifying replication information, 81
synchronizing, 73, 83
cube, properties, 136
Cube Viewer
page size, 148
Cube Viewer, export sheets, 149
custom toolbar, 146
dimension
local, 82
properties, 136
properties administration node, 132
rename, 82
security, 229
specifying replication information, 82
dimension, copy, 82
dimension, properties, 136
DisableMemoryCache, 31
DisableSandboxing, 31
DisableWorksheetView, 31
disconnecting clients, 68
display
control chores, 134
control processes, 133
Display_Info_DBType_R8, 31
Do Not Copy Rule, 82
DownTime, 32
D
data
backup, 64, 89
data, recovery, 64, 89
DataAdmin group, 232
DataBaseDirectory, 30, 48
data directory
access privileges, 21
definition, 20
local server, 20
multiples, 21
path, 20
remote server, 20
required network access, 21
restricting access, 236
security, 21
Date and Time, 98
Deactivate Chore, 134
DEBUG
Admin server message severity, 86
logging system message severity, 93
TM1 Web message severity, 160
decrypt, 214
DefaultMeasuresDimension, 30
DHFile-1024, 214, 216
DHFile-512, 214, 216
Diffie-Hellman, 214
280 IBM Cognos TM1
E
Edit Chore, 134
editing web.config, 142
element security, 229
encrypt, 214
End Time, 90
ERROR
Admin server message severity, 86
logging system message severity, 93
TM1Web message severity, 160
ETLDAP
connecting to TM1 Server, 182
exporting LDAP to TM1, 184
export options, 183
overview, 175
running from DOS, 178
running from Windows, 177
using, 175
ETLDAP, integrated login, 188
ETLDAP, LDAP authentication, 202
Excel, 125
ExcelWebPublishEnabled, 32
Execute Chore, 134
exit TM1 Top, 115
export
button, 177
Index
maximum sheets, 149
export, LDAP to TM1, 184
ExportAdminSvrSSLCert, 216
ExportSvrSSLCert, 214, 216
F
FATAL logging system message severity, 93
file extensions, 19
filter, 177
G
garbage memory, 69
group
adding, 229, 234
admin, 231, 236
multiple, 235
GroupsCreationLimit, 33
H
heartbeat interval, 15, 17
I
identity key, 214
idle
timeout, 148
TM1 Top, 114
IdleConnectionTimeOutSeconds, 33
INFO
Admin server message severity, 86
logging system message severity, 93
TM1Web message severity, 160
initialization file, 20, 46
installation
software requirements, 125
TM1 Web, 126
integrated login, 171
}ClientProperties cube, 187
access rights, 188
ETLDAP, 188
installing, 187
overviewl, 187
setting up, 187
setting up manually, 196
TM1 Architect, 197
TM1 Perspectives, 197
TM1 Web, 188, 189, 197
L
Language, 35
LDAP
authentication, 171, 172
building query, 182
configuring login parameters, 179
exporting to TM1, 184
mapping attributes to TM1 fields, 183
modified record attribute, 184
modifying attributes, 176
query elements, 180
server, 175
synchronizing TM1 data, 184
updating TM1, 185
LDAP authentication
configuring validation, 201
ETLDAP, 202
installing, 201
modifying group assignments, 202
parameters, 199
TM1S.cfg, 201, 202
validating users, 199
LDAP Authentication, 199
LDAPHost, 199
LDAP Load Tool, 177
LDAPPasswordFile, 36, 199
LDAPPasswordKeyFile, 36, 199
LDAPPort, 199
LDAPSearchBase, 199
LDAPSearchField, 199
LDAPUseServerAccount, 36, 199
LDAPWellKnownUserName, 199
local dimension, 82
local server, 18, 20, 61
lock modes, 113
log
backing out records, 66, 91
file, 55, 65, 89
Operations Guide 281
Index
file, removing, 67, 91
file, sample, 63, 88
file, Tm1s.log, 88
viewing, 65, 90
log, message, 93
LogAppend, 108
logging
disabling, 65, 89
sample properties file, 94
system message severity, 93
transactions, 63, 88
logging, enabling, 65, 89
LoggingDirectory, 36
login, integrated, 187
login page configuring, 150
LogPeriod, 108
M
MaxBackupIndex, 96
MaxFileSize, 96
MaximumCubeLoadThreads, 36
MaximumLoginAttempts, 37
MaximumMemoryForSubsetUndo, 37
MaximumUserSandboxSize, 37
MaximumViewSize, 38
memory
garbage, 69
management, 69
MemorySize, 96
message
clients, 68
log, 93
text, 98
MessageCompression, 38
Message Level, 98
Message log
configuring, 95
properties file, 94
severity Levels, 93
TM1 loggers, 94
using, 93
metadata, 55
Microsoft Excel, 125
Microsoft Internet Explorer, 125
mirror cube, 79, 80
definition, 74
282 IBM Cognos TM1
dimension, 82
naming, 81
rules, 81, 82
specify information, 81
synchronization, 83, 84
N
navigation tree
administration node, 147
views node, 147
non-SSL clients, 214
O
object security, 172
operating system, 125
out-of-process server, 73
override dimension defaults, 82
overview, TM1, 123
P
parameters
SSL, 214
parameters, web.config, 142
passport, 205
PasswordMinimumLength, 38
passwords, 214
assigning, 236
change, 137
for the ADMIN ID, 60
passwords, admin group, 236
passwords, change, 237
passwords, clearing, 237
passwords, setting, 236
PasswordSource, 38, 199
path data directory, 20
pdata, 20
performance counters, 117
performance monitoring, 67, 106
}StatsByClient, 250
}StatsByCube, 250
}StatsForServer, 252
control cubes, 106, 249
PerformanceMonitorOn, 38
permissions
anonymous access, 156
setting, 156
Index
Web folders, 157
Perspectives, 15, 20
Planning Manager toolbar, 146
PortNumber, 39
private key, 214
privilege
read access, 76, 83
write access, 83
PrivilegeGenerationOptimization, 39
process
attributes, 133
parameters, 133
Process
administration node, 132
process, properties, 133
ProgressMessage, 39
properties
cube, 136
dimension, 136
Q
quotation marks, 24
R
RawStoreDirectory, 40
read access privilege, 76, 83
ReceiveProgressResponseTimeoutSecs, 40
remote server, 23
Admin host, 18
and replication, 74
application, 56
connecting, 60
data directory, 20
diagram, 55
disconnecting, 61
memory management, 69
operations, 55
refreshing servers, 60
replication, 74
source server, 74, 80
starting, 58
target server, 74, 80
Windows service, 58
removing log files, 67, 91
rename a dimension, 82
replicate
a cube, 74, 80
a dimension, 81, 82
Admin Host considerations, 77
advantages, 73
connection, 74, 78
dimension name, 81
mirror cube name, 81
outcome, 83
overview, 73
process, 80
required access privileges, 76
server configurations, 74
server relationships, 74
setting up, 77
source server, 74
specifing rule information, 82
specifying cube information, 81
specifying dimension information, 82
subset, 83
target server, 74
views, 82
replication connection
creating, 78
deleting, 80
modifying, 79
overview, 74
Results Table, 177
review client properties, 135
revocation, 214
R-lock, 113
rollback TM1 Top, 114
rules, 81, 82
RunningInBackground, 41
S
sandbox
configuration parameters, 71
files and folders, 71
managing, 70
memory usage, 71
SAPLogFilePath, 41
SAPLoggingEnabled, 41
Save Chore, 134
SaveTime, 41
saving data, 55
Operations Guide 283
Index
sdata, 20
Search Button, 177
Search DN, 177
Search Scope, 177
security
access privileges, 229
adding groups, 234
adding users, 233
assigning passwords, 236
change password, 237
clearing passwords, 237
cube-level, 229
dimension-level, 229
element-level, 229
group, 229, 231, 234, 235, 236
multiple groups, 235
password security, 236
setting passwords, 236
TM1 Data, 235
Web folders, 157
security, TM1 objects, 172
security, Web folders, 157
SecurityAdmin group, 231
SecurityPackageName, 42
server
Admin, 15
audit log, 100
local, 18, 61
out-of-process, 73
performance, 106
performance monitoring, 67, 106
remote, 18, 55, 58, 60, 61, 69, 74, 80
remote shutdown, 69
remote shutting down, 61
serformance, 67
source, 74, 80
star configuration, 74
start and chain configuration, 74
target, 74, 80
server, LDAP, 175
server, message log, 93
ServerCAMURI, 42, 206
ServerLogging, 42
ServerName, 42, 108
service automatic start, 59
session idle timeout, 148
284 IBM Cognos TM1
T
target server, 74, 80
The ETLDAP Utility, 175
Thread ID, 98
timeout, 148
TimeZone, 96
TM1
.cfg file, 15, 18, 20
.ini file, 20, 60
architecture, 15
Client, 15
log file, 65, 89
securing data, 235
server.log, 42
Index
transaction log file, 55, 63, 88
users and groups security overview, 229
Web client, 15
TM1, Client, 20
TM1, Top utility, 107
Tm1admsrv.exe, 17
tm1admsrv-log.properties sample, 87
TM1ExcelServicePortNumber Parameter, 150
TM1 Excel Services log, 163
TM1 Logger Name, 98
tm1p.ini
location, 46
parameters, 46
Tm1p.ini file, 20, 46, 60
TM1 PerfMon, 117, 118
tm1s_start_example, 59
Tm1s.cfg file, 15, 18, 20, 23
location, 23
parameters, 24
sample, 23
Tm1s.log
properties, 94
removing old log files, 67, 91
TM1 server
remote, 60
UNIX, 59
UNIX, shutting down, 62
UNIX, shutting down background mode, 62
UNIX background mode, 60
Windows shutting down, 61
tm1srvstop.exe, 57, 62
Tm1top.ini, 108
TM1 Top utility
canceling threads, 116
command prompt, 115
configuring, 108
installing, 108
lock modes, 113
overview, 107
parameters, 108
SSL, 220
thread processing states, 114
TM1 Web log, 160
toolbars
Chore Administration, 134
Planning Manager, 146
U
UNIX, 59
server, 23
UseExtenedFetch, 44
user
adding, 233
user and group security, 229
UserDefinedCalculations, 44
UseSQLFetch, 44
UseSQLFetchScroll, 44
UseSSL, 45, 216
UseStargateForRules, 45
V
value, 119
verify TM1 Top, 115
view, Stargate, 70
ViewConsolidationOptimization, 45
ViewConsolidationOptimizationMethod, 46
W
WARN logging system message severity, 93
Web
browser, 125
server, 125
TM1, 15
Web, setting folder security, 157
web.config
defined, 142
editing, 143
Windows
service, 17
service account, 125
Windows service, 58
W-lock, 113
write access privilege, 83