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. That can also be the same dimension if you intend to change it. If you do not specify a dimension template, you start with an empty dimension.

Hierarchy templates work in a similar way. 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. In this request, replace \t with an actual horizontal tabulator.

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="2" Class="Dimension" Method="Write">
    <Alea:Dimension Name="OrgNew" FirstBatch="true" LastBatch="true"> 
      <Alea:DimensionTemplate Name="Org" IgnoreSourceNotExist="false">
        <Alea:DeleteElement Name="ErrorElement1" />
        <Alea:RemoveRelation Name="Fire Department" Parent="All" />
      </Alea:DimensionTemplate>
      <Alea:Hierarchy Name="Org as of 2019">
        <Alea:Elements>N\t2019
N\t2020
C\tTotal
\t2019
\t2020</Alea:Elements>
        <Alea:HierarchyTemplate Name="Org as of 2015" IgnoreSourceNotExist="true">
          <Alea:DeleteElement Name="Public Library 2015" />
        </Alea:HierarchyTemplate>
        <Alea:Description>Org as of 2019 New Hierarchy</Alea:Description>
       </Alea:Hierarchy>
    </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 within Alea:HierarchyTemplate.

The Alea:RemoveRelation tag has two attributes:

  • The name of the element.
  • The name of the parent from which 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, becomes a root element.

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

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="ErrorElement1">
            <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 code is 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. The default of IgnoreSourceNotExist is false.

Related topics