Request using templates

Templates facilitate the creation and modification of dimensions. When using a dimension template, all elements, hierarchies, and properties are taken over from the specified dimension. It can also be the same dimension that you intend to change. If you do not specify a dimension template, you start with an empty dimension.

Hierarchy templates are similar. Although they require the dimension template to have an effect.

Request

This request creates a dimension and hierarchy using templates. By using the same dimension and hierarchy as the template, a dimension and hierarchy can be changed. This is the preferred way to change a dimension or hierarchy. 

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="2" Class="Dimension" Method="Write">
    <Alea:Dimension Name="OrgNew" FirstBatch="true" LastBatch="true" >
      <!-- optional -->
      <Alea:DimensionTemplate Name="Org">
        <!-- optional -->
        <Alea:DeleteElement Name="Elem1"/>
        <!-- optional -->
        <Alea:RemoveRelation Name="Fire Department" Parent="All" />
      </Alea:DimensionTemplate>
      <!-- optional -->
      <Alea:Hierarchy Name="Org as of 2019">
        <Alea:Elements>N\t2019
N\t2020
C\tTotal
\t2019
\t2020</Alea:Elements>
        <!-- optional -->
        <Alea:HierarchyTemplate Name="Org as of 2015" IgnoreSourceNotExist="true">
          <Alea:DeleteElement Name="Driver License 2015"/>
        </Alea:HierarchyTemplate>
        <!-- optional -->
        <Alea:Description>Org as of 2019 New Hierarchy</Alea:Description>
        <Alea:Properties/>
      </Alea:Hierarchy>
      <!-- optional -->
      <Alea:Properties />
    </Alea:Dimension>
  </Alea:Request>
</Alea:Document>

The Alea:DeleteElement child tag removes the specified element. Within Alea:DimensionTemplate it only works for the default hierarchy. For a non-default hierarchy, Alea:DeleteElement must be placed in Alea:HierarchyTemplate.

The Alea:RemoveRelation tag has two attributes:

  • The name of the element.
  • The name of the parent where it should be removed.

When the element gets removed from the specified parent, the relationship to other parents remains untouched. If an element no longer has a parent, it remains as a root element.

For an element in a non-default hierarchy, the Alea:RemoveRelation tag must be placed inside the Alea:HierarchyTemplate tag. For a non-default hierarchy, Alea:RemoveRelation must be placed in Alea:HierarchyTemplate.

Alea:Properties can be in the same way configured as in the Dimension PutProperties function.

Answer

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="2">
    <Alea:Return>
      <Alea:Dimension Name="OrgNew">
        <Alea:DimensionTemplate Name="Org">
          <Alea:DeleteElement Name="Elem1">
            <Alea:Error ErrorID="65" />
          </Alea:DeleteElement> 
        </Alea:DimensionTemplate>
        <Alea:Hierarchy Name="Org as of 2019"> 
          <Alea:HierarchyTemplate Name="Org as of 2015"/>
        </Alea:Hierarchy>
        <Alea:Hierarchy Name="Org as of 2019"/>              
      </Alea:Dimension>
    </Alea:Return>
  </Alea:Request>
</Alea:Document>

The following error codes are delivered inside the Alea:DimensionTemplate element:

  • 65 - The dimension element could not be found.

Use IgnoreSourceNotExist=true within the Alea:DimensionTemplate and Alea:HierarchyTemplate tags to specify that, if the source dimension or hierarchy does not exist, the template is ignored, and the dimension or hierarchy is created from an empty state.

Related topics