Adding a unique element

Unique elements are added using the Alea:NewElement tag. A unique element is an element that is guaranteed not to exist in the dimension before.

Their names are generated by the server in the form of a prefix followed by a number. The prefix is given in the request and the number is chosen by the server so that the element name is unique in the whole dimension.

The syntax of Alea:NewElement is:

<Alea:NewElement Prefix="Elem" Digits="5" Placeholder="{{plac}}" />

Prefix is a string representing the prefix of the unique element name. Digits is a number between 1 and 9 representing the number of digits to be appended to the prefix. Placeholder is a string that identifies the element name in the content of Alea:Elements. With the values of the parameters provided, a unique name in the range Elem00001 to Elem99999 is generated.

The same restrictions with regards to the length and the allowed characters apply to the unique element names as to the regular element names. In addition, the Alea:NewElement tag can only be used in single-batch requests. A single-batch request is defined by FirstBatch="true" and LastBatch="true".

Request

This request adds a new unique element to the Org dimension and the Org as of 2019 hierarchy. The new element will be a base element. The new elements name will be from the Employee001 to Employee999 range.

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="1" Class="Dimension" Method="Write">
    <Alea:Dimension Name="Org" FirstBatch="true" LastBatch="true" >
      <Alea:DimensionTemplate Name="Org" />
      <Alea:NewElement Prefix="Employee" Digits="3" Placeholder="{{emp}}" />
      <Alea:Hierarchy Name="Org as of 2019">
        <Alea:HierarchyTemplate Name="Org as of 2019" />
        <Alea:Elements>N\t{{emp}}</Alea:Elements>
      </Alea:Hierarchy>
    </Alea:Dimension>
  </Alea:Request>
</Alea:Document>

Answer

If the request succeeds and the unique element is added to the dimension, this response is returned:

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="1">
    <Alea:Return>
      <Alea:Dimension Name="Org">
        <Alea:Hierarchy Name="Org as of 2019" />
        <Alea:NewElement Placeholder="{{emp}}" Name="Employee001" />
      </Alea:Dimension>
    </Alea:Return>
  </Alea:Request>
</Alea:Document>

The name that the server generated for the new element is returned in the Alea:NewElement tag.

Error

If the request fails to update the dimension, for example if there is no available element name in the dimension, this error response is returned:

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="1">
    <Alea:Return>
      <Alea:Dimension Name="Org">
        <Alea:DimensionTemplate Name="Org" />
        <Alea:Hierarchy Name="Org as of 2019">
          <Alea:HierarchyTemplate Name="Org as of 2019" />
        </Alea:Hierarchy>
        <Alea:NewElement Placeholder="{{emp}}" Name="">
          <Alea:Error ErrorID="361" />
        </Alea:NewElement>
      </Alea:Dimension>
    </Alea:Return>
    <Alea:Error ErrorID="359" />
  </Alea:Request>
</Alea:Document>

The main error code is reported by Alea:Error at the bottom of the response inside Alea:Request. If additional information is available, it is reported by Alea:Error that belongs to the respective Alea:NewElement.