The Definitive Guide to Turbo Integrator Troubleshooting

Turbo Integrator Overview

Turbo Integrator (TI) Processes are scripts that execute within the TM1 server to perform data manipulation. Most TI Processes use a data source which is processed line by line.

There are 7 major sections to a Process:

  • Data source Settings
  • Data source Variables
  • Parameters
  • Prolog
  • Metadata
  • Data
  • Epilog

Data source Settings

Here you can change the file/query that is being imported. It’s important when sourcing data from a file to have the “Data source Name for Server” being the Path to the source file as known by the server. (From the Physical Machine that the server is running on).

Data source Variables

A variable will be added to this tab for every column/field in your data source. These are names for the relative information within each column and will be updated as the process is executed row by row.

Parameters:

These are variables which take a value from the user who is running the process by prompting him/her to fill them when the process is executed.

Prolog

This is a place for the initial code for the process to run. Code entered here is executed once at the very beginning of the process before the data source file/query is opened/executed.

Metadata

The code entered here is executed once per line in the data source. Each time the process moves to the next line it updates the Data source Variables with the data from the new line and respective column. Primarily for Meta Changes (Dimensions/Elements/Subsets/Cubes/Views)

Data

The code entered here is executed once per line in the data source. Each time the process moves to the next line it updates the Data source Variables with the data from the new line and respective column. Primarily for Data Changes (Sending Data into a cube)

Turbo Integrator Syntax

Turbo Integrator Code is similar to C++ in that every line of code must be terminated with a semicolon.

The logical operators: for ‘and’ and ‘or’ are ‘&’ and ‘%’ respectively.

The Assignment operator is ‘=’.

Arithmetic operators +,-,*, / are all valid.

The Comparative operators are =,>,<,>=,<=,<> for Numeric data .

The Comparative operators are ‘@=’ or ‘@<>’ for Textual data.

Simple Example:

IF( mystring @= ‘Hello World’);

    DOAFUNCTION(parameter1, parameter2, parameterN);

ENDIF;

Or:

IF( mynumber >= 2);

    mynumber= mynumber-1;

ENDIF;

Checking for Problems in Turbo Integrator

The best way to check a Process for errors is the Message Log. This is accessed by right clicking on the server (In Sever Explorer) and selecting “View Message Log…”.

A Process can finish execution in 5 ways:

  • Completely Successfully
  • With Errors
  • Process Aborted
  • With ProcessBreak, ProcessError, ProcessQuit (TI Functions)
  • With Process Canceled (From TM1 Top or User)

By double clicking on the error line you can directly access the Process Log.

Turbo Integrator Error/Abort Cheat Sheet

Here we present the main errors or aborts you will receive in a TM1 Turbo Integrator (TI) process and what they mean.

Error: Invalid key: Dimension Name: “*Dimension*”, Element Name (Key): “*Element*”
Error Level: minor – not all data is loaded
Description: An Element supplied to a ‘CELLPUT’ function does not exist within the relative dimension or the elements have not been supplied in the order of the dimensions within the Cube.
Error: *Tab* procedure line (x): Cell type is consolidated
Error Level: minor – not all data is loaded
Description: The data source is providing data at an intersection of elements – one of which elements is a consolidation.An Element supplied to a ‘CELLPUT’ function is a consolidation.
Error: Dimension Update Fail. Rule Is Invalid: Error compiling rule, line number x: Element not found “*Element*”
Error Level: major – no changes were made (all changes were rolled back)
Description: The Process is Deleting/Renaming an element that is used in a Cube rule. Since the Element no longer exists the Rule will not evaluate correctly and will reject the changes.
Error: *Tab* procedure line (x): Unable to register subset
Error Level: major – process will abort
Description: The Process is trying to create a Subset which already exists or the Expression given to a “SUBSETCREATEBYMDX” function has errors
Error: *Tab* procedure line (x): Subset already exist
Error Level: major – process will abort
Description: The Process is trying to create a Subset which already exists.
Error: *Tab* procedure line (x): Consolidated Element “*Element*” not found.
Error Level: minor – Data structure will not be as expected
Description: The Process is trying to add an element as a child of another parent element (using DIMENSIONELEMENTCOMPONENTADD); the parent element does not exist (yet).
Error: *Tab* procedure line (x): View “*viewname*” not found
Error Level: major – process will abort
Description: The Process is trying to modify (ViewExtractSkipCalcsSet etc) or zero out (ViewZeroOut) a view which does not exist.
Error: *Tab* procedure line (x): Component Element “*Element*” not found.
Error Level: minor – Data structure will not be as expected
Description: The Process is trying to add an element as a child of another parent element (using DIMENSIONELEMENTCOMPONENTADD); the child element does not exist (yet).
Error: Cannot convert field number 9, value “*textdata*” to a real number.
Error Level: major – the datasource fields aren’t mapped correctly
Description: A textual field in the data source has been setup as a numeric value within the Process Variables Tab.
Error: Unable to open data source “*datasourcefilename*”.
Error Level: major – the datasource is invalid
Description: The datasource path given is invalid as known by the server.
Error: *Tab* procedure line (x): Attribute dimension “*Dimension*” not found
Error Level: minor – attribute will be blank
Description: The process is trying to retrieve or set an attribute which doesn’t exist per a specific dimension and element.
 

Backing Out Changes (Where Possible)

Under specific circumstances, data changes made to a cube can be ‘Backed out’ via the TM1 Transaction Log. In order for this to be possible the cube must have logging enabled (“}cube_properties” control cube).

To back out data changes:

  1. Right Click on the Server within “Server Explorer”
  2. Select “View Transaction Log”
  3. Select the Date you wish to search from
  4. Select the Cube and/or User (who’s actions you wish to reverse)
  5. Execute the Search
  6. Highlight the items you wish to “back out”
  7. Under “View” click “Select”
  8. Under “View” click “Back out”

Additional commentary on the TM1 Transaction Log is available here.

Process in Process

In Turbo Integrator, processes can execute other processes, This is particularly useful for executing a group of processes from a Single Process with given parameters. This saves the user from having to enter in the parameters into each of the child processes.

Syntax:

EXECUTEPROCESS (‘ProcessName’,’NameOfVariable1’,Variable1Value ,… );

Example:

ExecuteProcess(‘SYS.Logging Start’);

A more complete discussion of the ExecuteProcess command can be found here.

Using ASCIIOUTPUT/Logging to Debug

When troubleshooting complex Processes that use a lot of nested conditional statements, the “ASCIIOUTPUT” function helps to determine flow of the Program and further more reveal hidden issues. This outputs the data given as parameters 2-20 to the file specified as parameter 1.

Syntax:

ASCIIOUTPUT (filename,item1,item2,itemN);

ASCIIOUTPUT (‘Debug my issue.txt’, VariableImWorriedAbout, OtherVariables…);

Example:

Within the Metadata Tab of a Process:

File = ‘debug.txt’;

iRow=iRow+1;

IF(SomeValue = 1);

 IF(SomeOtherValue = 2);

    ASCIIOUTPUT (File, SomeValue, SomeOtherValue, “Did Something”);

 ELSE;

    ASCIIOUTPUT (File, SomeValue, SomeOtherValue, “Did Something Else”);

ENDIF;

ELSE;

    ASCIIOUTPUT (File, SomeValue, SomeOtherValue, “Made it to Else”);

ENDIF;

The file called ‘debug.txt’ can be found in the server’s Data directory which contains the output of the process.

Further discussion on AsciiOutput can be read here.

If you like this post, please spread the love…

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.