DimensionElementPrincipalName, How to Use and Syntax

Today I needed to lookup an element ID from an alias in a TI process.  I found the DimensionElementPrincipalName function that looks up the TM1 element principal name from the alias. Woohoo! It will also check if what you are looking for is a primary element ID as well, and if so, return that.

Syntax of DimensionElementPrincipalName

The syntax is:

DimensionElementPrincipalName( DimName, ToFind );


  • DimName is the name of the dimension you are wanting to check, and
  • ToFind is the text you want to find the element ID from.


An example of this is:

sAward = DimensionElementPrincipalName ( 'Payroll Award' , sAwardDesc );

In this code we are updating a string variable, sAward, by looking up the text in sAwardDesc from the ‘Payroll Award’ dimension.

Notes re DimensionElementPrincipalName

  • This only works for aliases or the primary ID of an element.
  • It can ONLY be used in TI Processes (not Rules).
  • The syntax does not require you to identify an attribute to check. this is because aliases and element IDs are unique. TM1 checks all aliases and the elements of a dimension to find the primary ID.
  • If the contents of ToFind are not found in either an alias or a primary ID, then the contents of ToFind are returned. NULL is not returned.
  • If ToFind is found, either in an alias or as the primary element ID, then the primary ID is returned.

Looking for DimensionElementPrincipalName in Excel?

If you are looking to how to do the equivalent of this in Excel using TM1 functions, see this post for a combination of DIMNM and DIMIX that gives you the primary element for an alias in Excel. It’s pretty cool!

You might also like