DimensionElementInsert TM1 Function: Use, Syntax and Examples
DimensionElementInsert, as you would expect, inserts a new element into a dimension in TM1. It could have been written as DimensionElementAdd, to add an element, but this would have been confusing!
Syntax of DimensionElementInsert
DimensionElementInsert (Dimension, InsertionPoint, ElName, ElType);
- Dimension refers to the dimension to which you want to add a new element.
- InsertionPoint is an existing dimension element. The element being added to the dimension will be inserted immediately before this existing element (note, if this parameter is empty, the new element is added to the end of the dimension).
- ElName is the name you want to assign to the new element.
- ElType is the element type. There are three possible ElType values, namley:
- N – for a numeric element.
- S – for a string element.
- C – for a consolidated element.
Example and Usage
DimensionElementInsert ('GL Account', '', vSub_Account, 'n');
This will insert the defined value of the variable vSub_Account into the dimension GL Account at the very end (the empty single quotes) as an “N” level element.
Combined Example to Add a New Element and Consolidate
DimensionElementInsert is often used in combination with an IF statement along with a DIMIX statement to test if an element exists in a dimension. We then insert if it does not exist and use a DimensionElementComponentAdd statement to then add it into a hierarchy.
If we were including it in a Turbo Integrator process to check if it exists and then add it if it doesn’t and roll it up into a parent, the TI process would look like this:
DimName = 'Test';
IF ( DIMIX ( DimName , pNew ) = 0);
DimensionElementInsert ( DimName , pInsertAfter, pNew , 'N' );
DimensionElementComponentAdd ( DimName , pParent , pNew , pWeight);
Adding Elements Immediately (rather than at the end of the TI Step)
If you need to add elements directly, rather than waiting for the end of the TI step (ie the Metadata tab), please see this post.
If you are looking to add an element to a parent, rather than insert an element into a dimension, please use DimensionElementComponentAdd.
This function is the opposite of DimensionElementDelete, which you can use to delete an element from a dimension.
This function can only be used in Turbo Integrator processes.