Planning Analytics Configuration File Breakdown

Evan McKirdy, June 8, 2020

Table of Contents

What is the Planning Analytics Configuration File?

In order to initially set up a Planning Analytics server/service/database (hereafter referred to as ‘server’), the server requires a configuration file that contains specific parameters and information about the server. These items cover a variety of functions including system administration, performance tuning, optimization, and security. The following information and parameters discussed in this article will focus on two primary aspects:

1. The contrast between parameters that can be set dynamically (while the server is up and running) vs. parameters that must be set prior to the service being started, otherwise known as static.
2. The concept of required parameters vs optional parameters.

How is it set up?

All this information will be triggered through IBM’s configuration tool IBM Cognos Configuration.

This tool can be used to stop, start, restart, configure, and save the settings for each Planning Analytics Server set up. The ‘TM1 Server configuration path’ will be the location of where your configuration file is stored on the Admin Host server. For a demo or laptop installation, it is recommended to place Planning Analytics files directly on the local C:\ drive. For a shared Planning Analytics server or production environment, the recommended location would be on a separate data drive or shared network drive.

How is it maintained, going forward?

The IBM Cognos Configuration tool only needs to be used once upon initial setup of the server. After that, the server will be registered, and you can start/stop the server from the Windows Services Console as shown below.

Types of Parameters

Static Parameters

Static Parameters are Planning Analytics configuration parameters that require a restart of the Planning Analytics server if they are ever modified.

Dynamic Parameters

Dynamic Parameters are Planning Analytics configuration parameters that can be edited while a Planning Analytics Server is running. Note that some dynamic parameters take 30-60 seconds to take effect.

Regardless of whether static or dynamic, parameters can be either required or optional parameters.

Required Parameters

Planning Analytics needs these parameters set up properly for configuration purposes, as well as for server maintenance and features. Below we will list the parameters that are required to configure, start and properly maintain a Planning Analytics server.

Optional Parameters

Planning Analytics does not require these parameters, however, they do provide more specificity and unique attributes for each server configured. Some optional parameters can become required when working with multiple Planning Analytics Servers on one Admin Host machine.

List of Parameters

As we go through the following list of parameters, please note that there are many other Planning Analytics configuration file parameters available that span a wide array of customizations for the server. The list below will focus on essential, basic, and commonly used configuration parameters that you will need to know in order to properly configure multiple Planning Analytics servers on one machine.

Server Specific

1. AdminHost [static | required] – a static parameter that designates IP address or Computer Host Name on which the Planning Analytics server will run. If this parameter is left blank, the AdminHost parameter will default to local CPU machine where the configuration file is saved.
2. ServerName [static | optional] – a static parameter that designates the name of the Planning Analytics server that you are configuring. Typically, a client will have a ‘Production’ server and a ‘Development’ server. If this parameter is left blank, the server’s name will be defaulted to ‘Local’.
3. PersistentFeeders [static | optional] – a static parameter that designates when and how feeders are stored. If Set to T (for True), Planning Analytics will save a calculated FEEDERS file. This is done in order to improve the reload time of cube with feeders. This parameter is recommended for servers with longer startup times.

Directory Specific

1. DatabaseDirectory [static | required] – the Data Directory parameter defines the location where the ‘Data’ folder will be located on the server’s admin host computer. The data directory will typically be located in a directory adjacent to the tm1s.cfg file. This is a required, static parameter as it is where all Planning Analytics model object files for a particular PA server are stored. It cannot be left blank.
2. LoggingDirectory [static | required] – the Log Directory parameter defines the location in which the ‘Logs’ folder will be located on the admin host computer. Typically, this will also be in a directory adjacent to the Data folder and tm1s.cfg locations. (e.g. If DataDirectory is set to “C:\PA Models\Planning Sample\Data”, then the Log directory will be “C:\PA Models\Planning Sample\Logs”. This parameter is also static.

*Please note that if there are any spaces in your file paths, you will need to use quotation marks so the configuration file can be read properly.

Port Specific

1. PortNumber [static | required] – this static parameter sets the server port number used to separate and uniquely identify multiple servers running on the same Admin Host. Later in this article, we will discuss issues caused by duplication of port numbers on two different Planning Analytics Servers. Per IBM, valid port numbers are between 5001 and 65535.
2. HTTPPortNumber [static | required] – a static parameter that sets the port number on which the Planning Analytics server looks for HTTP requests. This is a required parameter that is used by the web interfaces (Planning Analytics Workspace/TM1 Web) as their specific port numbers. Without this value, these web-based services will not be able to reach the server. If left blank, it is set to 5001 by default.

Security Specific

1. IntegratedSecurityMode [dynamic | required] – a dynamic parameter that sets a method, 1 through 5, of user authentication modes for the Planning Analytics service that you are configuring. If you are to change this parameter while the server is running, it is a good idea to refresh security as a confirmation of the changes made.
2. UseSSL [static | optional] – a static parameter that enables (T) or disables (F) SSL on your Planning Analytics server. By default, UseSSL is set to true. If enabled, please be sure to visit IBM’s Data transmission security Page.
3. SecurityPackageName [static | required] – a static parameter that, for IntegratedSecurityMode=3 or above, defines the security package that authenticates the usernames and passwords for Windows Authenticated accounts. Valid entries for this parameter are: 1. Kerberos 2. NTLM and 3. Negotiate. Use NTLM and negotiate when running Planning Analytics locally. Kerberos for cloud. Negotiate selects Kerberos unless it cannot be used by one of the systems used to authenticate in the server.

CAM Security Specific

1. ClientCAMURI [dynamic | optional] – a dynamic parameter that defines the URI for the IBM Cognos Server connection used to authenticate Planning Analytics clients. This is an optional parameter (mandatory when using CAM) that is typically specified in the following form: http[s]://<host>/<cognos_location>/cgi-bin/cognos.cgi.
2. ServerCAMURI [dynamic | optional] – a dynamic parameter that defines the URI for the internal dispatcher that the IBM Planning Analytics server uses to connect to CAM (Cognos Authentication Manager). This is an optional parameter (mandatory when using CAM) that is typically specified in the following form: http[s]://fully-qualified host IP address:port/p2pd/servlet/dispatch. To configure the Cognos TM1 Applications Server to work with CAM SSL:
   • Ensure the following settings are made in the Cognos Configuration tool:
     • Force Qualified Paths set to False.
     • Use Mutual Authentication set to True
   • Accept the certificate when saving.
3. ClientPingCAMPassport [dynamic | optional] – a dynamic parameter that indicates the interval, in seconds, that a client should ping the CAM server to keep their passport enabled. If left blank, the default parameter value is 900 (15 minutes). If an error occurs or the passport expires, the user will be disconnected from the Planning Analytics server
4. CAMPortalVariableFile [static | required] – a static parameter that sets the path to the variables_TM1.xml file in My IBM Cognos Installation. This parameter is required for IBM Cognos interoperability when using IBM Cognos Analytics with Planning Analytics Workspace and Planning Analytics server.

IP Configurations

1. IPVersion [static | optional] – a static parameter that indicates the internet protocol used by the Planning Analytics server to identify the proper IP address to associate with the network. This can be set for IPv4, IPv6 or dual – supporting use of either.
2. IPAddressV4 or IPAddressV6 [static | optional] – a static parameter that specifies the IPv4 or IPv6 Address identified with a Planning Analytics server. These are optional parameters that if specified, can help narrow down when working with multiple networks.

Timeout Specific

1. IdleConnectionTimeOutSeconds [dynamic | optional] – a dynamic parameter that specifies, in seconds, a timeout limit for idle connections for all clients. This is an optional parameter that can help aid server traffic between end-users when hosting a server with tens, if not hundreds of end-users.
2. HTTPSessionTimeoutMinutes [dynamic | optional] – a dynamic parameter that specifies, in minutes, a timeout limit for idle connections within the Planning Analytics REST API. This is an optional parameter that if left blank, defaults to 20.

Server Logging / Auditing

1. ServerLogging [dynamic | optional] – a dynamic parameter that enables the Planning Analytics server to generate a log, named Tm1server.log, saved to the logging directory. The log includes all activity details from your live Planning Analytics server since inception. If you do choose to change this parameter dynamically (without restarting the TM1 Server), logging will only register for new client sessions. This is an optional parameter.
2. AuditLogOn [dynamic | optional] – a dynamic parameter that turns audit logging on (T) or off (F). This is an optional parameter that defaults to F when left blank. The audit log monitors changes to all metadata; changes to dimensions, views and subsets, as well as logins and TI Process execution (but not data changes). The log can be viewed directly from Planning Analytics Server Explorer, under the edit tab.
3. AuditLogUpdateInterval [dynamic | optional] – a dynamic parameter that indicates the maximum amount of time, in minutes, that the Planning Analytics server waits before moving the events from the temporary audit file to the final audit log. This is an optional parameter that when left blank, is defaulted to 60 or 1 hour. Minimum value is 1.
4. AuditLogMaxFileSize [dynamic | optional] – a dynamic parameter that indicates the maximum file size that the audit log file can grow before a new audit file is created. This is an optional parameter that when specified, must include a file size specification of KBs, MBs or GBs. The value is 100 MB when left blank.
5. EnableNewHierarchyCreation [static | optional] – a static parameter that specifies whether multiple hierarchy creation is enabled (T) or disabled (F). The new Planning Analytics Workspace and Planning Analytics for Excel interfaces allow for development and usage of multiple attribute driven hierarchy structures within each dimension. This optional parameter enables this feature. By default, the parameter is set to disabled (F).

Performance-Based

1. MTQ [dynamic | optional] – a dynamic parameter that sets the maximum number of threads on an individual end user’s connection, when multi-threaded optimization is applied. This parameter is used during cube loads, querying data and batch feeders. It improves performance on numeric cubes only, where consolidation can be optimized. Since Planning Analytics does not consolidate string values, MTQ has no bearing on their performance. MTQ is an optional parameter that is specified via a basic equation [MTQ=n]; where n is any integer representing the number of threads used. In order to configure this parameter properly, it is critical to understand how this number is then used by the configuration file. When (n) is a negative number (-), Threads = M – n + 1, where M = # of threads on the server. If you have a 64-core server and MTQ = -5, the system will use 60 threads. -1 would be the maximum, consuming all threads. When set to 0 or 1, multi-threaded optimization will be turned off.
2. ParallelInteraction [static | optional] – a static parameter that turns parallel interaction on or off for the user-created and control cubes in a Planning Analytics server. Parallel Interaction is a Planning Analytics server feature that allows for greater concurrency of read and write operations on the same cube object. Parallel Interaction is enabled by default and is used by all cubes in the Planning Analytics server.
3. MaximumCubeLoadThreads [static | optional] – a static parameter that specifies whether the cube load and feeder calculations of server loading are multi-threaded. This allows for multiple processor cores to be used in parallel, which results in decreased server load times. Optimal performance is achieved when the value is set to (# of processor cores – 1). If your computer has 4 cores, MaximumCubeLoadThreads should be set to 3. When MaximumCubeLoadThreads is set to 0, cube loading and feeder processing are not multi-threaded. Please note that when enabled, Planning Analytics cannot manage the order of the feeders calculation. There may be cases where processing order has an adverse effect on your server due to ordering dependencies in the multi-threaded environment.

Troubleshooting

Several issues can arise due to incorrect tm1s.cfg file parameters, but the most common are:

1. Port numbers getting crossed/duplicated – When running multiple Planning Analytics servers on the same admin host, it is common that architects will use an existing configuration file on the server to use as a starting point for the next service creation. This can lead to Port numbers not being changed across configuration files, which will cause the servers to crash into each other. This is an important note to ensure that Port numbers are varied across services.
2. Proper syntax and usage of file path locations- Several parameters reference file paths that can often be entered incorrectly due to improper syntax, incorrect listing of the path, or issues with a local reference (i.e. C:/). Please double check your directory paths and always use UNC references to avoid directory accessibility issues.
3. Typos/Human error- A common pitfall that should always be accounted for, especially when working in Planning Analytics. This issue can arise pretty much anywhere where configurations are made manually or written out (TI, Rules and Configuration). Sometimes it is as simple as the IP address having an extra period, or the misspelling of an admin host or server name. If you have distinct port numbers running through multiple services, you should go back and double-check your configuration file for these issues.

Conclusion

Once you have finalized and saved the tm1s.cfg file to your server directory and set the location of the configuration file within Cognos Configuration, your server should now be queued up to be started. One final test is to right-click on the newly configured server and select ‘Test’. This will test the service before starting, just to have one final check in case anything was missed during the configuration. Once the test passes successfully, right-click the server name and press Start which will execute the initialization of the PA server per the contents of the tm1s.cfg file and will start up the PA server for the first time.

In conclusion, the configuration file is essentially a free form text canvas where hundreds of different configurations can be made for a new Planning Analytics server. This blog post highlights the specific parameters that we at PMsquare have found to be the most common and useful in our configurations of Planning Analytics solutions. Whether required or optional, static or dynamic, the above parameters will be of use to developers when setting up and maintaining Planning Analytics servers.

The following link to IBM’s website will allow you to download the current boilerplate tm1s.cfg file.

Next Steps

We hope you found this article informative. Be sure to subscribe to our newsletter for data and analytics news, updates, and insights that are delivered directly to your inbox.

If you have any questions or would like PMsquare to provide guidance and support for your analytics solution, contact us today.