Getting started with TM1 Applications (part 1)

TM1 Applications, commonly refereed to as TM1 Contributor, provides a structured workflow to enter data into a TM1 model. Most commonly this is used for Planning and Forecasting applications.

Lets walk through deploying a simple application using the IBM provided sample. Before you can deploy your first TM1 Application you will need an existing model. The model being used should contain a dimension used for the applications approval hierarchy, and at one or more cube that users will enter data into. At least one of the cubes being used for data entry must contain the dimension used for the application approval hierarchy.

These steps assume that we have TM1 installed (including sample models) and the all TM1 services are running.

1 - Browse to the TM1 Applications web portal. In my case this is http://tm1.tm1masters.com:9510/pmpsvc. If this is the first time using the TM1 Applications web portal we will see the following initialization page.

I've configured the Admin Host to point to the system running my TM1 Admin service and selected the Planning Sample model. Note that we must select a single TM1 model on this screen, but we can add other TM1 models for use with TM1 Applications later. Click OK to continue.

2 - Once we are past the initialization page we will be prompted to login. The username and password for the samples are admin\apple. We are assuming the Planning Sample model was left in TM1 native security mode (not configured for CAM security).

3 - After we login we might see the following warnings.

All three of these warnings can be safely ignored for now. If you want to prevent these warning we can update the Planning Sample models tm1s.cfg file.

The value of the ForceReevaluationOfFeedersForFedCellsOnDataChange should be considered carefully as setting ForceReevaluationOfFeedersForFedCellsOnDataChange=T can have a very extreme performance impact. SettinForceReevaluationOfFeedersForFedCellsOnDataChange=T is not required just because you are going to use TM1 Applications or the Performance Modeler client.

Restart the Planning Sample TM1 service if any of these parameters in the tm1s.cfg file are updated.

4 - Launch Performance Modeler by clicking the Performance Modeler icon. If Performance Modeler was not already installed you will be prompted to install.

Performance Modeler is an MSI installation package. The following error has be noted when installing on Windows Server 2008 and 2012.

To work past this error choose to download the PerformanceModeler64.msi file and run it from a command prompt window that was opened with the 'Run as administrator' option.

Performance Modeler client should automatically update itself if the TM1 server installation was updated with a Fixpack. For some reason this only happens when Performance Modeler is launched from the TM1 Application web portal.

5 - Switch to the Application Design view (bottom left of Performance Modeler) and create a new application.

In this example we are creating an approval type application. The approval type is the most commonly used for a planning cycle application. To keep things simple we will name the application Planning Sample. It's worth noting that it's common to have multiple applications using the same TM1 model. We will talk about that in detail later. 

6 - Lets add our approval hierarchy dimension and a cube that users will enter data into. The approval hierarchy dimension used is really just a subset and the contributor cube is really just a view. Expand the dimension folder in the TM1 Objects area, expand the Department dimension, then drag the Default subset to the Approval hierarchy area.

Drag the Budget Input Detailed view from the plan_BudgetPlan cube to the Contributor views area.

7 - Before we deploy the application we should also examine the application properties. In this example we will use cell security to enforcement the application rights. Application rights are used to determine which groups and users can access specifics areas (nodes) in the workflow. Cell security is the modern method of rights enforcement that was introduced in TM1 10.2. The major advantage of cell security over element security is that it lets us deploy multiple application that use the same input cubes. This was a serious limitation in previous versions.

We have also disabled the Cognos Insight options since we ignored the previous warning about the DistributedPlanningDir parameter in the tm1s.cfg file. We can enable this option at a later point if we choose to use Cognos Insight as an alternative to TM1 Application Web.

8 - Before we can use our application we must save and deploy it. Click the save and deploy buttons highlighted in the screenshot.

Assuming the application was defined correctly we should see a message saying it was validated and deployed.

9 - At this point the application has been deployed. We simply need to activate it then we should be able to open it and start examining the workflow. Return to the TM1 Applications web portal and click the refresh button, the application should appear.

Click the activate button highlighted below.

The following warning can be ignored for now. We will discuss the order of dimension at a later time.

10 - We can test opening our application and accessing the workflow view. Click on the application name (Planning Sample) to access the workflow. In the screenshot below all nodes (left side) have been expanded. Although no rights have been assigned to the application nodes we can still see all nodes since we are using the Admin account in the Planning Sample model.

In part 2 we will cover application rights and go into more detail about how TM1 Applications interacts with the TM1 model.

TM1Top

What is TM1Top?

TM1Top is command line utility used to understand what activity is occurring in a TM1 model, It displays a list of threads running. TM1Top will display details for each thread running on the TM1 server. A thread is either a user that is connected to the TM1 server or a Ti processes running as a chore. The thread information provided by TM1Top is often critical to diagnosing lock contention problem and understanding how users are using the TM1 model. These details are ONLY found in TM1Top, not the TM1 model messaging log (tm1server.log file).

Unfortunately TM1Top is not enabled by default and must be configured for each TM1 model. It's strongly recommended that TM1Top be configured and running at all times. Most importantly TM1Top should be configured to output a log files. If and when a TM1 server problem occurs, both the tm1server.log file and the log file from TM1Top should be reviewed.

Some TM1Top history

TM1Top was the only option provided by IBM to examine thread activity in TM1 in version 9.5.x. In version 10.1 IBM introduced a web based version of TM1Top known as Operations Console,. While Operations Console does have some advantages over TM1Top it came with it's own set of problems and was not well received. TM1 Operations Console did show a bit more thread detail than TM1Top. IBM decided to remove TM1Top in versions 10.2 and 10.2.2. However, previous versions of TM1Top still worked correctly with TM1 10.2 and 10.2.2. An updated version of TM1Top was reintroduced in Fixpack 4 for TM1 10.2.2.

The version of TM1Top included with TM1 10.2.2 Fixpack 4 is strongly recommended as it provides slightly more detail than previous versions. The level of thread detail in this version matches TM1 Operations Console.

How do I run TM1Top?

The IBM Cognos documentation talks about creating a tm1top.ini file. There is a much simpler method to starting TM1Top.

Create a Windows shortcut to the tm1top.exe file in the TM1 bin64 directory with the following target:

tm1top.exe -adminhost localhost -servername "Planning Sample -logfile C:\TM1\Models\MyModel\Logs\tm1top.log -logperiod 2 -logappend T -refresh 2

A shortcut can be created for each TM1 model in use. The above shortcut uses the logfile parameter which will create and update a tm1top.log file. The logperiod parameter indicates the log file is updated every 2 seconds and logappend prevents TM1Top from overwriting the log file if TM1Top is restarted.

How do I start TM1Top automatically when the TM1 server is started or restarted?

This technique is useful when the TM1 model has a scheduled automatic restart and tm1top logging is required.

1 - Create a Ti process that uses the ExecuteCommand function to start tm1top. In this example we name the Ti process tm1top.

ExecuteCommand('C:\Program Files\ibm\cognos\tm1_64\bin64\tm1top.exe', 0);

This assumes that a tm1top.ini file already exists in the C:\Program Files\ibm\cognos\tm1_64\bin64 directory. You can avoid using an tm1top.ini file with an ExecuteCommand function such as this:

ExecuteCommand('C:\Progra~1\ibm\cognos\tm1_64\bin64\tm1top.exe -adminhost tm1admin.domain.com -servername tm1model -logfile C:\tm1top.log -logperiod 2 -logappend T -refresh 2 ', 0);

2 - Create an inactive Chore that runs the Ti process created in step 1. In this example we will call the Chore tm1top. Here we can see both the Ti process and Chore with the same name

3 - In the tm1s.cfg file set the following parameter:

StartupChores=tm1top

When the TM1 service is restarted tm1top.exe will start automatically. Note that the tm1top.exe process will not automatically end when the TM1 server next restarts. A scheduled chore to restart the TM1 server should first run an ExecuteCommand function to end the tm1top.exe process. For example:

ExecuteCommand('taskkill /f /im tm1top.exe', 0);

TM1Top does not include a date in the timestamp or logging!

This makes it difficult to know which section of the TM1Top log file to review when the TM1Top log file spans multiple days.

It is useful to compare logging at the same time from the TM1top and tm1server log files. Since the date isn't displayed in the TM1Top log file it can be difficult to determine what section of the tm1top log file to examine.

To make the TM1Top log file easier to understand we can generate a separate TM1Top log file for each day. This can be done using a scheduled Chore in the TM1 server as follows. The Chore can scheduled to run at the start of each day (e.g 12:01 AM).

Here is the prolog section of a Ti process that restarts TM1Top .

# 1- Location of TM1 bin64 directory
vTM1BinDir = 'C:\Program Files\ibm\cognos\tm1_64\bin64';
# 2- Host name of system running the TM1 Admin Server
vTM1AdminHost = 'localhost';
# 3 - TM1 model name
vTM1ServerName = 'Planning Sample';
# 4- Logging directory to store TM1Top log files
vLogDirectory = 'C:\TM1\Models\MyModel\logs';

vCommand = vTM1BinDir | '\tm1top.exe -adminhost ' | vTM1AdminHost | ' -servername "' | vTM1ServerName | '" -logfile "' | vLogDirectory | '\' | vTM1ServerName | '_tm1top_' | TODAY(0) | '.log" -logperiod 2 -logappend T -refresh 2';

# This stops any currently running tm1top.exe processes
ExecuteCommand('taskkill /f /im tm1top.exe', 1);
# This start the tm1top.exe process
ExecuteCommand(vCommand, 0);

Replace the four variables so they match the the TM1 server where this Chore is run.