Book Image

IBM Cognos TM1 Developer's Certification guide

By : James D. Miller
Book Image

IBM Cognos TM1 Developer's Certification guide

By: James D. Miller

Overview of this book

IBM Cognos TM1 is enterprise planning software that provides a complete, dynamic environment for developing timely, reliable and personalized forecasts and budgets. It is a real time, in memory tool that helps any sized business perform planning, budgeting and forecasting as well as other financial exercises. This book prepares you to master COG-310 certification using an example-driven method that is easy to understand. The IBM Cognos TM1 Developer's Certification guide provides key technical details and background to clear the current IBM Cognos TM1 Developer (test COG-310) certification exam. This certification book covers all the modules of the certification clearly and in depth. The initial chapters cover in detail the components that make up Cognos TM1 and designing and creating dimensions and cubes. The book then dives deep into basic and advanced scripting using TurboIntegrator and then we learn to understand and write basic Rules. We then learn about the drill-through functionality of TM1, virtual and lookup cubes and lastly Time, and presenting and reporting data
Table of Contents (15 chapters)
IBM Cognos TM1 Developer's Certification Guide
About the Author
About the Reviewer
Free Chapter
The Components of TM1

Chapter 1. The Components of TM1

In this chapter we will identify and discuss each of the components of IBM Cognos TM1 that are covered in the current IBM Cognos TM1 Developer (Test COG-310) certification exam. The current exam assigns a weightage of 3 percent to this topic.

The components of TM1 are divided into two basic types which are:

  • Client components

  • Sever components

Most of these components are installed by default with a standard installation of the product, but some are not.

A standard installation is when you run the provided installation package for the version of the Cognos TM1 product you have purchased and select all of the default (already checked or selected) options.

It is also important to know that a standard install will use the following default (and recommended) values:

Admin server port number


SSL port number


TM1 Server port number


TM1 Client message port number

Whatever the next available port number is on the installation machine

TM1 Server name


Admin server host name

Installation machine name

Sample data directory for TM1 Server

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

Sample data directory for TM1 Perspectives/TM1 Architect

C:\Program Files\Cognos\TM1\Custom\TM1Data\Pdata

Security mode

TM1 Authentication

Each of the TM1 components has a particular purpose and use.

The discussion in this chapter will relate to the functionality and features of the components as it relates to the certification exam and is not meant to be a complete or exhaustive information source.

The components of TM1

First we'll get introduced to the client components of Cognos TM1.

Client components

Client components allow access to the TM1 Servers. During a default installation, the following Client components will be installed:

  • TM1 Client

  • TM1 Perspectives

  • TM1 Architect

  • TM1 API

  • OLE DB Provider

What we mean by OLE DB Provider is simply an external software component that enables TM1 to have specialized access to OLAP data sources such as Microsoft Analysis Services and it is not directly referenced in the current IBM Cognos TM1 Developer (Test COG-310) certification exam, so we will not spend time on it.


All of the client components can be installed on a user (client) machine as well as the (server) machine that the TM1 server components are installed. There is an advantage in having at least one client component installed on a server machine for debugging purposes, however some installation polices may inhibit this practice.

TM1 Client

The TM1 (basic) client is accessed through Microsoft Excel as an Add-In and will allow limited access to available TM1 Servers.

As a Cognos TM1 developer, you should know that a Microsoft Excel Add-In is a file that Excel can load when it starts up. The file contains program code that adds additional functionality to Excel, usually in the form of new functions.

TM1 Client does not allow administrative access to any TM1 Servers. It does not offer the ability to set up and run a local TM1 Server.

During the installation, a local version of TM1 Server is installed and can be accessed by TM1 Client, TM1 Perspectives, or TM1 Architect. A local TM1 Server gives you exclusive (administrative) access to data and objects in a set of Windows folders called data directories. During a TM1 Client session, only you can create, browse, and modify data or objects that a local server stores. You can also control where the data directories should be located.

Since the TM1 Client is limited in functionality, most users will choose to install and use TM1 Perspectives (TM1 Client is not covered in the exam, but you should at least be aware that it exists and what functionality it offers).


During a default installation, TM1 Client and TM1 Perspectives are both installed. Upon loading of the TM1 Add-In in Microsoft Excel, if no valid TM1 Perspectives license file (.lic) is found, you can only start and run TM1 Client even though you have installed TM1 Perspectives.

TM1 Perspectives

As with TM1 Client, TM1 Perspectives is loaded and runs as an Add-In to Microsoft Excel.

With TM1 Perspectives, you can access data within TM1 Servers and you can also create and maintain TM1 objects and data on both local and remote TM1 Servers.


It is important to be aware of the fact that with each installation of TM1 Client and TM1 Perspectives, a "personal configuration" file named Tm1p.ini is installed.

This file is used to configure the settings for the behavior of the Add-In file within Microsoft Excel.

During a TM1 installation, you can choose to automatically load TM1 Perspectives (or TM1 Client) when Excel starts. Don't worry, if you missed this during the installation, you can perform the following easy steps:

  1. 1. Open Microsoft Excel on your desktop.

  2. 2. Click on Tools | Add-Ins from the Excel menu bar.

  3. 3. Select Tm1p.xla.

  4. 4. Click on OK.

When you click on Add-Ins, Microsoft Excel will most likely show you a location where it thinks the TM1P Add-In file exists.

You will almost never find the TM1P file where Excel says it should be, so you will need to browse to the location on your machine where TM1 installed the file as shown in the following screenshot:

The TM1P Add-In file is usually installed during installation to the directory folder Cognos\TM1\bin.

Features of TM1P

The default version of Tm1p.ini allows multiple users to use TM1 on a given computer. Tm1p.ini must be present the first time a user starts TM1 on the computer, as the parameters in the system default version govern the behavior of the initial startup of the TM1 Client for each user.

After a user starts TM1 on the computer, a user-specific copy of Tm1p.ini is created in %APPDATA%\Applix\TM1\Tm1p.ini. In most cases, the full path to the Tm1p.ini file is:

C:\Documents and Settings\<user name>\Application Data\Applix\TM1\Tm1p.ini.

The user-specific copy of Tm1p.ini accepts all parameter settings and changes for the user and governs the behavior of the TM1 Client for all subsequent user sessions of the TM1 Client.

It is important to know how to locate and configure the Tm1p.ini file. As you will find references to the file's purpose and settings of the file in the exam and in practice, you will have occasion to access and update it.

For your users running TM1 Clients on Windows Vista and Windows 7, application data (and therefore the Tm1p.ini file) is stored differently. To locate the .ini file, open a command line prompt, for example - Start | Run | cmd.

Execute the command set APPDATA to discover where the application data (and the Tm1p.ini file) is stored. The directory that is displayed will contain a directory named Applix\TM1 that will contain Tm1p.ini.


The Tm1p.ini file is important because that is where you can set parameters that change the user's TM1 Perspectives experience.

Some of the most interesting (and important) .ini file parameters are:

  • ConnectLocalAtStartup: This parameter is set to True or False and indicates whether the client automatically attempts to connect to the local server at startup. For most users it is advantageous not to connect to the local server.

  • AdvancedRulesEditor: This parameter is set to True or False and will indicate the type of TM1 Rules Editor that is used. The advanced Rules Editor has an enhanced interface and is somewhat more complicated and may or may not be a good choice to offer to the user, depending on that user's skill level.

  • DisplayApplications, DisplayChores, DisplayControlCubes, DisplayCubes, DisplayDimensions, DisplayProcesses: These parameters (set to True or False) indicate whether TM1 Perspectives will display application folders, chores, cubes, dimensions, or processes to the user. At this point in my career I have never seen these parameters set to values other than their default values.

  • DisplayExplorerPropertiesWindow: This is again a True or False parameter that indicates whether the Properties pane is visible in Server Explorer on startup. The Properties pane can be helpful to some users, but there is a slight performance impact with it "turned on" and visible. You may want to set this default to False. The Properties pane can be made visible later in TM1 Server Explorer by clicking on View and then selecting Properties Window.

  • DisplayReplications: This True/False parameter should be set to False for most users. This parameter indicates whether the Replications group is visible in Server Explorer at startup.

TM1 Architect

TM1 Architect is a standalone TM1 Client application (meaning that it does not plug in to Microsoft Excel) and is used to create and maintain data and metadata on both local and remote TM1 servers.

Usually, you will see a separate menu item on your computer's desktop for accessing TM1 Architect directly as shown in the following screenshot:

This is a tool that will be used by a TM1 user who is granted at least minimal "administrator" privileges (that is, a developer or programmer type).

It is best to use Architect when focusing on Turbo integrator scripting or possibly checking security assignments because it allows access to these features of TM1 without having to load Microsoft Excel.


You can actually have both TM1 Perspectives and TM1 Architect open and running at the same time on your machine, accessing the same or different TM1 Servers.

Again, TM1 Architect does not hook into Microsoft Excel and cannot be used directly to create and maintain TM1 enabled Excel worksheets.


Along with TM1 Architect, an application programming interface (API) is installed during a default installation. This interface may be used by more experienced developers to create C++ and VB applications that interact with TM1.


The API is not covered in the exam.

During the installation, JAVA and .NET API are also installed.

Server components

TM1 Server components are the "heart" of TM1. These components run on the machine receiving and replying to all requests from TM1 clients.

Unlike the TM1 Client components (discussed above) not all of the TM1 Server components are installed during a default or standard installation.


A single installation of TM1 Server on a server machine can be used to run multiple TM1 Server application processes. But you will need to check your license agreement to determine if multiple servers are legal under your agreement.

The server-side TM1 components are described next.

TM1 Admin Server

The TM1 Admin Server is considered the "parent process" or "hosting process" of all other TM1 processes.

This is the process that keeps track of all other TM1 Server components running on the network. An Admin Server process runs on a computer and is known as the Admin Host.


The term Admin Host is important for the certification exam.

During the installation, the TM1 Admin Server is automatically set up as a machine service for you. TM1 Servers (discussed later in this chapter) must be set up manually to be run as application services.


TM1 Server can be installed and set up as a machine application service on a standalone machine along with the selected client components. This kind of environment is advantageous for active development.

When each TM1 Server starts, that server registers itself with the Admin Server that is running on a specified Admin Host.

TM1 Clients reference the Admin Server to determine which TM1 Servers are available on the network.

TM1 Server processes (described next) reference the AdminHost parameter in their own configuration file (Tm1s.cfg) to determine which admin host to register with. It is as follows:


If a user cannot access a TM1 application, you should verify that the TM1 Admin Host is configured correctly and is running. In some instances, you may need to stop and then restart the TM1 Admin Host (keeping in mind that all TM1 Servers currently registered with the TM1 Admin Host will need to be restarted).

Also note that, although TM1 Servers register with a single Admin Host, all TM1 clients (TM1 Client, TM1 Perspectives, and TM1 Architect) can reference multiple Admin Hosts simply by listing them all under Login Parameters/Admin Host in the upper left of the TM1 Options dialog.

In the following screenshot, three admin hosts (host1, host2 and host3) are listed and therefore, all TM1 Servers currently running on these machines will be visible in these users' TM1 Server Explorer:

TM1 Server configuration files by default reside in the TM1 Server's SData folder.

The SData folder can be reviewed for file and timestamp information as required to note the last time these objects were updated.


The SData folder is the location on the server where all of the server's object files (cubes, dimensions, processes, and so on.) also reside. This is also the location where TM1 log and error files are written to unless a "logs folder" is set up in the TM1 Server's CFG or configuration file.


The TM1 configuration (.cgf) file is a simple text file that can be accessed and updated using a simple text editor like Windows notepad.


While changing parameters in the configuration file, you will need to stop and restart the TM1 Server to see the effects of the changes.

Some of the most interesting (and important) parameters that are contained in the configuration file are as follows:

  • ClientVersionMaximum: This parameter sets the version of the TM1 Client components that can access this TM1 Server. This is important because, in the production environment, a TM1 Server may be upgraded to a newer version of the software while others in the server farm remain at an older version level. In this case, not all of the TM1 user machines may have the latest TM1 Client software installed and you may wish to limit which versions can access this server.

  • ServerName: This parameter will indicate the TM1 Server name (not the physical machine name where the server is running, but the TM1 application server service name. For example "finance_1").

  • DataBaseDirectory: This will be the specific physical path to the TM1 Server's SData folder and must end with a \.


You do not have to use quotes around the value, but it helps for readability. Both of the following will be valid:

="c:\company_finance_data\sdata\" or =c:\company_finance_data\sdata\

  • LoggingDirectory: This will be the specific physical path to the TM1 Server's logging folder and must end with a \. If no logging folder is provided, TM1 Server will write its logs, errors, and exceptions to the specified SData folder (described above).


It is a good practice to specify a logging directory.

  • AdminHost: This is the physical machine name on which the TM1 Server is installed and running.

TM1 Server

The TM1 Server is a process that manages all requests from all TM1 clients. It loads the names of all available permanent objects (cubes, dimensions, and so on) into the machine's memory and responds to client requests by performing calculations, consolidations, and updates as required. Refer to the following screenshot:

The TM1 Server also manages security-granting or denying access to server objects and maintaining a log of changes to the database.


There may be any number of TM1 Server processes running on the network. The number of TM1 Server processes is only limited by the memory available to them. As mentioned earlier, each TM1 Server must be manually set up to run as a machine application service.

Multiple TM1 Servers can be viewed and accessed through a single TM1 Server Explorer (via TM1 Client, TM1 Perspectives, TM1 Architect, or TM1 Web) if it is configured properly.

TM1 Web

TM1 Web refers to all the web server components required to access the TM1 Servers (and their data) using a web browser.

TM1 Web is not a part of the standard installation and you must perform a TM1 Web installation to install these components.

TM1 Web is commonly used to access TM1-enabled Excel worksheets and reports using a web browser.


In order for worksheets and reports to be available to the users via their web browsers, the worksheets and reports must have a "reference" to them set up in an application folder.

Setting up a worksheet reference

To set up a reference for a TM1 worksheet or report, the developer must publish each of them to the application folder. This is accomplished as follows:

  1. 1. Open the worksheet or report to be published in Microsoft Excel.

  2. 2. Click on the TM1 menu.

  3. 3. Select Save Workbook On TM1 Server....

  4. 4. Select Upload New Application File to TM1 Server....

  5. 5. Navigate to (and select) the application folder location on the server where you want the file to reside.


    After publishing the worksheet, make sure that the file security is appropriately set (the default is private).

Two reports published to a TM1 Server are shown in the following screenshot. The secured or "private" report is visible only to the TM1 user who published the report and is designated with a "key icon":

TM1 Top

TM1 Top is a TM1 "utility" that enables you to dynamically monitor and manage threads (active user sessions) running in an instance of a Windows or UNIX TM1 Server.

The current version of TM1 Top runs only on a Windows system and is available only with the Windows installation of TM1.


To monitor a UNIX TM1 Server, use the TM1 Installation Wizard to install TM1 Top on a Windows system and then configure TM1 Top to connect to the UNIX TM1 Server. When the AdminHost and ServerName parameters are pointing to a UNIX machine, TM1 Top will monitor the UNIX environment. See the IBM Cognos TM1 Operations Guide for details on configuring the Tm1Top.ini file—IBM.

When TM1 Top is installed, it sets up a Tm1Top.ini file that you can configure to point to the TM1 Server that you want to monitor. Using a text editor such as Microsoft's notepad, you can edit the file and provide your server name and the machine (or admin host) that the server is running on. In addition, if you provide a log file name, TM1 will write a snapshot of its display to the file in regular intervals (specified by the logperiod parameter):


If you are a TM1 user with administrative access, TM1 Top may be used to cancel any current TM1 user thread. This practice should be approached with caution as a thorough understanding of what the user thread is doing and the reason for canceling it is recommended.

The following screenshot shows a running TM1 Top session. Note that the two active user sessions shown in the screenshot are actually TM1 Admin Server sessions—not individual TM1 users.

TM1 Contributor

This component is installed by default only as a part of the TM1 Contributor installation, not as a part of the standard TM1 installation.

TM1 Contributor includes:

  • TM1 Contributor Web Client: This is a web-based client used to browse and contribute data within the TM1 Contributor workflow application.

  • TM1 Contributor Administration: This is a configuration, design, and management tool used by administrators to build planning applications and set security on applications.


TM1 Contributor is not a part of the IBM Cognos TM1 Developer (Test COG-310) certification exam.