TM1s.cfg & How to Create a TM1 Model – A Best Practice Guide

Updated for Planning Analytics. A comprehensive guide for setting up a new TM1/Planning Analytics model (server). This guide to creating new TM1 models includes a downloadable tm1s.cfg, suggested edits to the tm1s.cfg, folder structure, Cognos Configuration settings and screenshots of all steps.

Creating a New TM1 Server

To create a new server you must first create a data directory, this directory must have at very least a configuration file, ‘tm1s.cfg’.

The configuration file (tm1s.cfg) must specify:

  • Server Name
  • Data Directory
  • Logging Directory
  • Server Port

In addition you should include the following:

  • HTTP Port
  • Security Mode

Finally, you might like to add as a minimum:

  • MTQ (for multi threaded queries)
  • Use Excel Dates
  • Enable Sandboxes
  • Enable Persistent Feeders

Here is a screenshot of the key modifications made to our test system:

Minimum TM1s.cfg configuration.

Download ExploringTM1’s Recommended TM1s.cfg

Please note that it is NOT the same as IBM’s sample and has been configured for what we think is a good starting point for creating a new model.

The IBM sample contains 400 odd lines of text that explain each parameter in detail. Download it so you can refer to what the parameters do and see the correct syntax easily.

Note as well that there are well over a hundred different parameters you can insert into tm1s.cfg. Please see this link for a full explanation of each one.

TM1 Server Folder Structure

The typical directory structure of an Application Server is as follows:

  • Server Name (No Spaces)
    • Backup (for model backups – zips of the data folder)
    • Config (tm1s.cfg)
    • Data (model files)
    • Input (Shared Directory)
    • Logs (tm1s.log, tm1server.log)
    • Migrate (for preparing packages of files for migration to/from Prod)
    • Output (Shared Directory)
    • Scripts (for storing scripts that we use to help manage TM1)

The folder structure looks like this:

TM1 model folder set.

If you’d like a zip file of these folders ready for you to deploy, grab it here.

For a more complete discussion on folders, please see this post.

Create a TM1 Model as a Service

To load a server as a service we must first set it up as one. This is done using the Planning Analytics version of Cognos Configuration (NOT the Cognos Analytics version of the tool!).

Here are the steps:

  • Open Cognos Configuration
Planning Analytics Cognos Configuration to add a new TM1 Server/TM1 Model.
  • Navigate to Data Access, right-click on TM1 Server and select New Resource, TM1 Server instance.
Add new TM1 Model/TM1 Server to Cognos Configuration.
  • Name it with a meaningful name (spaces allowed).
Naming your new TM1 Model in Cognos Configuration
  • For that new model, enter the path of the tm1s.cfg file.
Setting the path to tm1s.cfg for a new TM1 Model in Cognos Configuration.
  • Right-click on the model name and select Start
Starting your new TM1 Service/TM1 Model in Cognos Configuration
  • Clicking Start will save Cognos Config and start the Windows Service.
  • If the Windows Service fails to start, you have probably used a port already used on the server. Change ports and try again. Also check that the paths for the data and log folders are exactly correct (see the screenshot at the top of this post for one that works!)

What this process has done is add a new Windows Service to the computer so that your model will run as a service (in other words not linked to a user).

It has also populated the data directory with a all the components needed to start using TM1. You can now open Architect and start working on your model!

Loading a Model as an Application

You can also load a TM1 model as an application, rather than as a service. To load a TM1 server as an application we run the application ‘tm1s.exe’ found in the IBM Cognos TM1 bin Directory. We also provide this executable with a command line reference to the data directory.

The easiest way to do this is by creating a shortcut to ‘tm1s.exe’ and changing the launch field to have an additional ‘ –Z “DataDirectoryHere”.

Loading a Backup of a TM1 Server

Another option for you to create a new TM1 server is to use a backup. Starting up a backup is relatively simple. As the server will most likely be temporarily up its best to start the server as an application instead of a service.

Major Considerations:

  1. Does the server have enough RAM to support another server in memory?
  2. What level of impact will this have (by using one or more CPU cores to load) on the rest of the system?
  3. Do not run the Server on the same port as the existing one (see tm1s.cfg configurations).
  4. Do not use the same name for the server if registering it on the same admin host as Production.
  5. Would it be beneficial to run the backup on the same admin host as Production? (Exposing the point in time backup to end-users)

For more information on backups in TM1, please see our write up on it here.

Moving Cubes/Dimensions Around

You might have created a new TM1 model so you can work in a different environment that your production model. If so, you will need to deploy files from one model to the other.

Since cubes are saved to the hard disk as ‘.cub’ files its easier to move these between servers as opposed to exporting and re-importing data. Unfortunately in order for TM1 to recognize new objects like cubes or dimensions, the TM1 server needs to be restarted.

Note: When moving a cube between servers make sure the new server has all the dimensions used by the cube.

For a full explanation on deploying model objects from one model to another, please see this detailed explanation on migration from Dev to Prod.

TM1 File Extensions

After you have setup your new TM1 server, you might be interested in the files in the new TM1 Data folder. There are various file types in this folder. These include .cub, .dim, .pro, .rux etc. For a full explanation of the TM1 file types, please see this post.

You might also like