TM1 Undocumented Function - Renaming the Element Name

Renaming the element name – SwapAliasWithPrincipalName

In Realtime Scenarios, sometimes we get the requirement to correct/update the Principal element name(s) in a Dimension. This would relatively be easy if the dimension is being used in one cube. In case where the dimension is used in multiple cubes, updating element name(s) without affecting the data of all the cubes, is a bit challenging. Either we export data of the cube and change the element name(s), then import the data and validate cube before and after the element change. Or deploy the Bedrock process, which requires the reboot of Instance.

All these processes look long and time taking. Hence, IBM has an undocumented function called - SwapAliasWithPrincipalName(). By using this function, you can rename the element(s) within few mins. 

Below are the steps:

1. Create an Alias with the Updated names for the Elements in the Dimension.

Note: Make sure the Attribute type is ‘Alias’, as the Swap function doesn’t work for ‘Numeric’ and ‘Text’ Attributes throwing a message “Error: Invalid attribute type. Object name: "dimName", Attribute name: "attributeName"

2. Make sure the Alias values are Unique across the existing and Updated element names.

3. Create a TI process using the below Function in the Prolog section-

SwapAliasWithPrincipalName( dimName, aliasName, flag );

Where, dimName is the Dimension name defined between single quotes.

aliasName is the alias created in the 1st Step above defined between single quotes.

Flag value should be 0.

4. For a clear start, we can either perform a ‘SaveDataAll’ manually in the Architect or include SaveDataAll; function in the Prolog section of the TI process before defining the Swap Alias function as shown in the below screenshot:

Note: Always use the Swap Alias Function in the Prolog Section, as its Swaps all the Element names available within the Dimension with its respective Alias values.

5. Execute the TI process and on process completion, the Alias values will be swapped with the Principal element Names for the Dimension elements.

For example, the below screenshot shows us the way how the principal element is getting replaced with the Alias value which the TI process is executed.

If we need to rename/change only some of the Element names in the Dimension,

- Provide the alias values only for the elements names that needs to be updated and leave the rest as blank.( The elements with unpopulated aliases will retain their original name)