Automating tasks with the Cognos TM1 Application Maintenance utility

The Cognos® TM1® Application Maintenance utility is a command-line utility that helps administrators take actions that were previously only possible from the Cognos TM1 portal.

The utility can be used to deploy a version of the automation for use on a computer other than the Cognos TM1 application server. You can also run the utility from inside a TurboIntegrator Process as part of a wider-ranging chore.

The utility is installed as part of the Cognos TM1 application in install_dir/webapps/pmpsvc/WEB-INF/tools/app_maintenance.bat

To display a list of the actions that can be automated along with the required parameters, use the -h argument. For a formatted version, pipe the output to a temporary text file, for example app_maintenance.bat -h > automate.txt. The help file contains all the parameters and syntax that is needed for each action.

The utility can automate the following actions:

  • Activate/deactivate an application
  • Deploy an application
  • Export/import/merge/refresh rights
  • Reset application state and do not remove sandboxes
  • Reset application state and remove sandboxes
  • Logon with a CAM logon
  • Logon with an encrypted password
  • Logon with an encrypted password created with TM1crypt.exe
  • Create an encrypted password file
  • Create an encrypted password file with increased key strength
  • Reset the application (not included in the -h flag listing). This removes all existing sandboxes for cubes in the application. When you use Reset from the TM1 Applications portal, you are prompted to verify that you want sandboxes removed.

The tool requires a Java™ runtime environment. By default the tool uses the JRE in the usual TM1 installation location. It uses the JAVA_HOME or JRE_HOME environment variables.

To deploy the tool to another machine, a JRE must be available on the other machine. The Javahome variable must be set so that the tool can find it.

You can also deploy a version of the tool and all the required executables it needs into one location. Then you can easily import them to another computer.

For example, you can create a folder that is called D:\AppAutomation\utility on the machine where you want the utility to run. On the original computer, use the following command to package up the tool and its required objects: app_maintenance.bat - package "D:\AppAutomation\utility". This action creates a compressed file called application_maintenance.zip which can be moved to the other machine where you want to run the automation. The compressed file includes the tool and the objects it needs. Extract the compressed file on the secondary computer. Ensure that there is a Java runtime environment available on the secondary computer and that it is identified in the javahome or jrehome environment variable.

The following sample syntax is used to deactivate an application called StorePlan (breaks in syntax are for formatting purposes only. Do not break these lines in your commands):

D:
cd "D:\Program Files\ibm\cognos\tm1_64\webapps\pmpsvc\WEB-INF\tools"
app_maintenance.bat 
-serviceurl voltran.ibm.com:9510/pmpsvc 
-username admin -pwd apple 
-op deactivate 
-app {d06b9060-c3cc-4c4f-ac5d-60276540a9ce}

The service URL is the URL used to browse to the TM1 Applications portal. Your browser may encode the "{}" in the URL. Ensure that your GUID is using the convention you need for your browser.

This command uses TM1 authentication. In a production environment, it is not secure enough to pass the username and password in clear text. Use the TM1Crypt utility to encrypt the necessary admin credentials and then pass in an encrypted password file to this utility.

The GUID can be identified by the aid parameter in the browser link when you open the application in the TM1 Applications portal.

http://localhost:9510/pmpsvc/pmpjs/workflow/workflow.jsp?portal=1&aid=7cc2f875-281f-4e97-b51c-daf7b772a777

Using the automation tool as part of a TurboIntegrator process

You can use this utility as part of a TurboIntegrator process.

For example, suppose that you have a model with the following approval hierarchy:
Figure 1. Store Plan Workflow model
Europe node with leaf children of Central Europe, Northern Europe, GO Accessories, and Southern Europe

For this example, you want to add a new leaf node called "Western Europe" that rolls up into Europe. You can create a set of TurboIntegrator processes combined into a chore. Ensure that the Chore process is set to use Multiple Commit mode, so that the TurboIntegrator process is committed and relevant locks released before the next TurboIntegrator process is run. Then use the automation tool to refresh and update the application in an overnight batch process.

The TurboIntegrator processes take the following actions:

Deactivate
Makes the application unavailable to users while the update is taking place.
Update Country and Region
Updates the approval hierarchy dimension for this application. The command adds Western Europe as a node beneath Europe.
Update Approval Hierarchy Subset
Updates the approval hierarchy subset with the new information.
Deploy Store Plan app
Redeploys the application. In a production environment, data would be added first.
Refresh rights for Store Plan app
Updates the rights for users with review rights to Europe. Those users would inherit the rights to the new node.
Activate Store Plan app
Makes the application available to users again after making those changes.

Here is sample code for the deactivate process:

ExecuteCommand('D:\AppAutomation\StorePlanDeactivate.bat', 1);

The "1" in the command indicates that the command completes before the next command is executed.

When the chore is complete, it can be executed immediately or scheduled to run as an overnight process.