TM1 Technical Bulletin

Using Named Hierarchy Levels with TM1

Date: August 27, 2008
Relevant TM1 Versions: TM1 9.4

Overview
Using TM1 9.4, you can assign your own custom names to the hierarchy levels 
of a TM1 dimension. These named levels can then be used outside of TM1 
when you use MDX statements or other MDX OLAP tools to access TM1 data. 
You can also assign a default member for the dimension.
For example, instead of using the generic hierarchy level names of level000, 
level001, level002, you could assign names such as All, State, City, Individual.

TM1 dimension levels TM1 named levels

Named levels are defined using the new }HierarchyProperties control cube. 
TM1 also includes a new TurboIntegrator function, RefreshMdxHierarchy, that 
updates dimension hierarchies after you assign named levels.

Cognos TM1 Technical Bulletin 1

Configuring Named Levels
Use the }HierarchyProperties control cube to configure named levels.

The }HierarchyProperties control cube has the following dimensions:
• Title dimension – Contains a listing of all the dimension names in the cur‐
rent TM1 server.
• }Hierarchies row dimension – Includes only one row for assigning named 
levels to the selected dimension.
• }HierarchyProperties column dimension – Includes a single element for 
assigning a default member, and a set of 21 elements (level000 ‐ level020) 
for assigning names to hierarchy levels.
To configure named levels:
1. In TM1 Architect, click View → Display Control Objects.
2. In the navigation pane, click to expand the Cubes node.

2 Cognos TM1 Technical Bulletin

3. Double‐click the }HierarchyProperties control cube.
The }HierarchyProperties control cube opens.
4. Click the title dimension list to select the dimension for which you want to 
assign named levels.
5. In the defaultMember cell, enter an existing element name to set as the 
default member for this dimension.
For example, set Italy as default member for the Region dimension.
6. In the level000 to level020 cells, enter your own custom name for each 
hierarchy level that exists in the dimension.
NOTE: Named levels are limited to a length of 255 single‐byte characters. 
For details, see “String Length Limit for Named Levels”.
7. After configuring, you must do one of the following to apply the changes:
• Restart the TM1 server, or
• Run the RefreshMdxHierarchy function in a TurboIntegrator process. 
For details, see “Using the RefreshMdxHierarchy TurboIntegrator Func‐
tion”.
NOTE: Changes to element names or dimension structure are not 
automatically detected by the named levels feature. If your dimension 
changes, you must use the }HierarchyProperties control cube to manually 
update your named level assignments.

Cognos TM1 Technical Bulletin 3

String Length Limit for Named Levels
Named levels are limited to a length of 255 single‐byte characters. Even though 
the }HierarchyProperties control cube supports long strings, MDX statements 
can return an error with named levels longer than 255 characters.
If you enter a named level with a length greater than 255 single‐byte 
characters, TM1 displays an error when the server starts up:
4648 ERROR 2008-06-27 13:50:04,532 TM1.Hierarchy User-defined level
name modified from ...

Using the RefreshMdxHierarchy TurboIntegrator Function

The RefreshMdxHierarchy function updates the MDX hierarchies in a TM1 
server without requiring you to restart the server.
1. Create a new TI process.
2. Enter the function on the ProLog tab using the following format:
RefreshMdxHierarchy([dimensionName])
where the optional parameter, dimensionName, can either specify a specific 
dimension to update or can be blank to update all dimensions.
For example, to update all dimensions:
RefreshMdxHierarchy('');
To update only the customers dimension:
RefreshMdxHierarchy('customers');
3. Run the TI process.

4 Cognos TM1 Technical Bulletin