Create hierarchy objects using Turbo Integrator functions in Planning Analytics 

The new Turbo Integrator functions provide Planning Analytics users the ability to create hierarchy objects for a dimension In this blog, I describe how to enable the new hierarchy creation setting.  In addition, the different Turbo Integrator functions used to create hierarchy objects in Planning Analytics and when each should be used. 

Enable Hierarchy Creation Setting

Multiple hierarchies are not enabled by default in Planning Analytics.  Thus, an administrator configures this setting in the tm1s.cfg file by adjusting the EnableNewHierarchyCreation setting to “T”.  Thus, allowing the use of multiple hierarchies and the related Turbo Integrator and rules functions.  Multiple hierarchies can be implemented using Turbo Integrator process or Planning Analytics Workspace.  Contrarily, you can’t do so through the dimension editor or dimension worksheets. 

Also, using multiple hierarchies provides greater flexibility when querying by adjusting the EnableNewHierarchyCreation setting.  A single hierarchy model requires all queries to have exactly the same number of hierarchies as the number of dimensions that make up the cube in the query.  With multiple hierarchy models, queries have any number of hierarchies equal to or greater than the number of dimensions that make up the cube in the query. 

Turbo Integrator Functions

There have been several Turbo Integrator functions added to account for hierarchy specification in Planning Analytics.  For example, the HierarchyCreate function can be used in a TI process to create a new hierarchy in a dimension. The syntax is: HierarchyCreate(DimName, HierName);.  The HierarchyDestroy function is used in a TI process to delete a hierarchy from the TM1 database.  The syntax is: HierarchyDestroy(DimName, HierName);. 

There are separate functions available for single and multiple hierarchy models.  The single hierarchy creation function syntax is: DimensionElementInsert(DimName, InsertionPoint, ElName, ElType);. This function adds an element to a dimension and can be used along with the DimensionElementComponentAdd function.  The syntax for this function is: DimensionElementComponentAdd(DimName, ConsolidatedElName, ElName, ElWeight);.  As a result, this function adds an element as a child of a consolidated element in a dimension.  The multiple hierarchy creation function syntax is: HierarchyElementInsert(DimName, HierName, InsertionPoint, ElName, ElType);.  This function will add an element to the specified hierarchy of a dimension and can be used along with the HierarchyElementComponentAdd function.  The syntax for this function is: HierarchyElementComponentAdd(DimName, HierName, ConsolidatedElName, ElName, ElWeight);.  This function adds an element as a child of a consolidated element in the specified hierarchy of a dimension. 

When Each Should be Used

If the cubes in your model contain single hierarchy dimensions only, use either of these functions to create hierarchy objects.  However, if any dimension in your cubes contains a second hierarchy, then the multiple hierarchy function must be used.  When using the multiple hierarchy function in a case where all cubes in your model contain single hierarchy dimensions only, the hierarchy being referenced in the function will be the same as the dimension name.  In addition, using the multi-hierarchy function in a case where a dimension in your cubes contains a second hierarchy, the hierarchy being referenced in the function will call out the specific name of the hierarchy being used. 

These functions allow you to create hierarchy objects in Planning Analytics for both single and multiple hierarchy dimensions.  With a single hierarchy model, you continue to utilize the original DimensionElementInsert and DimensionElementComponentAdd functions to create hierarchy objects for dimensions.  However, if you have a multiple hierarchy models, adjust any TI processes used to create your dimension hierarchies to utilize the new HierarchyElementInsert and HierarchyElementComponentAdd functions which create hierarchy objects for your dimensions. 


Spreadsheets remain one of the most popular tools for business professionals today.  However, while great for personal productivity, they’re ill-suited for large-scale planning, budgeting, and forecasting.

Download the infographic to learn more about the causes and consequences of spreadsheet errors.

Dylan Fodor

Dylan joined the eCapital team in September of 2014. In his time with eCapital, he has done several implementations for a variety of clients across many industries. He has also performed several training courses covering a variety of topics related to Cognos TM1 and Planning Analytics. Dylan has earned certifications as an IBM Certified TM1 Developer, IBM Certified TM1 Administrator, and IBM Certified TM1 Analyst.

Leave a Reply

Your email address will not be published.