Dimension Write

This request creates or changes a dimension. A dimension can be created from scratch or changed with the template functionality using the same dimension or another dimension as a template. The existing dimension is overwritten.

These characters are not allowed for dimension and hierarchy names: [ ] \ / : * ? " < > | <TAB> <LF> <CR>

Hierarchy names cannot start with a number. Exceptions are names of implicit hierarchies, for backward compatibility reasons. An implicit hierarchy is created when no hierarchy information is provided in the Dimension Write request. The implicit hierarchy has the same name as the dimension.

Example with implicit hierarchy and BreakOnError request

In this request, replace \t with an actual horizontal tabulator.

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="1" Class="Dimension" Method="Write">
    <Alea:Dimension Name="DimTest" FirstBatch="true" LastBatch="true" BreakOnError="false" Delimiter="\t">
      <Alea:Elements>N\tActual
N\tBudget
C\tVariance
R\tActual2	[Actual] * 2
S\tStringElem
N\tFault[Elem
C\tVariance
\tActual
\tBudget\t-1</Alea:Elements>
    </Alea:Dimension>
  </Alea:Request>
</Alea:Document>

The Alea:Elements tag contains:

  • The list of the elements, with their type and name.
    • The possible types are N (base), C (consolidated), S (string), or R (rule).
    • Rule formulas.
  • The relations between elements.
    • Optionally, the element weight. The default is 1.
    • The alternate format is: ! Parent Child <weight>.

Further characteristics of the Alea:Elements tag:

  • By default, the fields of a line are separated by a horizontal tabulator.
  • The separator can be changed using the Delimiter attribute of the Alea:Dimension tag.
  • Each line, except the last one, ends with a line break.
  • There must be no line breaks or spaces between the opening Alea:Elements tag and the first line.
  • There must be no line breaks or spaces between the last line and the closing Alea:Elements tag.

This request contains an element with the illegal character "[". Because BreakOnError is set to "false", the request does not fail, but creates or changes the dimension omitting the corresponding element. The offending element is returned including the error code and line number.

Answer if BreakOnError="false"

Horizontal tabulators are returned as such, not as "\t".

<Alea:Document> 
  <Alea:Request RequestID="1">
    <Alea:Return> 
      <Alea:Dimension Name="DimTest"> 
        <Alea:Hierarchy Name="DimTest"> 
          <Alea:Elements LinesCount="1">196\t6\tN\tFault[Elem</Alea:Elements> 
        </Alea:Hierarchy> 
      </Alea:Dimension> 
    </Alea:Return>   
  </Alea:Request> 
</Alea:Document>

If BreakOnError is set to "true", this request fails, and the dimension is not created or changed. The default for BreakOnError is "false".

Answer if BreakOnError="true"

<Alea:Document>
  <Alea:Request RequestID="1">
    <Alea:Return>
      <Alea:Dimension Name="DimTest">
        <Alea:Hierarchy Name="DimTest" />
      </Alea:Dimension>
    </Alea:Return>
    <Alea:Error ErrorID="196" ErrorPosition="6" />
  </Alea:Request>
</Alea:Document>
Related topics