Dimension RenameElements

Renames one or more elements within a hierarchy.

Request

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="10" Class="Dimension" Method="RenameElements">
    <Alea:Dimension Name="REGION">
      <Alea:Hierarchy Name="REGION">
        <Alea:Element Name="Netherlands" NewName="The Netherlands" />
        <Alea:Element Name="Botsuana" NewName="Botswana" />
      </Alea:Hierarchy>
    </Alea:Dimension>
    <Alea:LoadUnloadedCubes Value="true" />
  </Alea:Request>
</Alea:Document>

The XML elements <Alea:Dimension> and <Alea:Hierarchy> can be used only once per request. <Alea:Hierarchy> can also be omitted. In this case, the request is rerouted to the default hierarchy.

If the <Alea:Hierarchy> XML element exists, all dimension elements that are to be renamed must be listed within it.

The renaming of elements requires that dependent cubes of the dimension are loaded. A cube is dependent on a dimension when the dimension is contained in the cube.

The function performs the necessary cube load operations automatically unless <Alea:LoadUnloadedCubes Value="false" /> is specified. If this is the case and there are unloaded dependent cubes, this function fails with error 378.

If the <Alea:LoadUnloadedCubes> XML element is missing or if its Value XML attribute is set to "true", then the unloaded dependent cubes are loaded.

Note: Loading cubes can be a lengthy operation. Renaming elements should be used with care.

Answer 1

This is the answer to the request:

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="10">
    <Alea:Return>
      <Alea:User Name="Admin" />
      <Alea:Dimension Name="REGION">
        <Alea:Element Name="Botsuana" NewName="Botswana" />
        <Alea:Element Name="Netherlands" NewName="The Netherlands" />
      </Alea:Dimension>
      <Alea:ChangedCubes />
    </Alea:Return>
  </Alea:Request>
</Alea:Document>

The <Alea:ChangedCubes> XML element in the answer is not used and is always empty.

Answer 2

When rule references are invalidated by element renames, it is reported similar to this:

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="11">
    <Alea:Return>
      <Alea:User Name="Admin" />
      <Alea:Dimension Name="PROFIT">
        <Alea:Element Name="Sales Deduction in percent" NewName="Sales Deduction in %"/>
      </Alea:Dimension>
      <Alea:ChangedCubes/>
      <Alea:RuleErrors>
        <Alea:Cube Name="SALES">
          <Alea:Rules>
            <Alea:Rule Cells="Consolidated" RuleID="0X0009000000">
              <Alea:Target ErrorID="1" ErrorPosition="8">[PROFIT:'Sales Deduction in percent']</Alea:Target>
              <Alea:Formula>[PROFIT:'Sales Deduction']/[PROFIT:'Revenue']</Alea:Formula>
              <Alea:Description>R4: Sales Deduction in percent - C Rule</Alea:Description>
            </Alea:Rule>
            <Alea:Rule Cells="Basic" RuleID="0X000CC00000">
              <Alea:Target>[CURRTYPE:'LC', PROFIT:'Sales Deduction']</Alea:Target>
              <Alea:Formula ErrorID="1" ErrorPosition="51">[CURRTYPE:'LC', PROFIT:'Revenue'] *
[CURRTYPE:'LC', PROFIT:'Sales Deduction in percent']</Alea:Formula>
              <Alea:Description>R9: Sales Deduction for LC</Alea:Description>
            </Alea:Rule>
          </Alea:Rules>
        </Alea:Cube>
      </Alea:RuleErrors>
    </Alea:Return>
  </Alea:Request>
</Alea:Document>

Error 1

When a general error occurs, for example if the requested dimension does not exist, the error response resembles this:

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="21">
    <Alea:Error ErrorID="26" />
  </Alea:Request>
</Alea:Document>

Error 2

If there are problems with a name or a new name of elements, the first incorrect element is returned in the error response. In this case, the complete request fails, that is, nothing is changed in the dimension. For example, if there is no Atlantis element, the error response to the request is:

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="22">
    <Alea:Return>
      <Alea:User Name="Admin" />
      <Alea:Dimension Name="REGION">
        <Alea:Element Name="Atlantis" />
        <Alea:Error ErrorID="37" />
      </Alea:Dimension>
    </Alea:Return>
    <Alea:Error ErrorID="37" />
  </Alea:Request>
</Alea:Document>

Error 3

Another example is when there are multiple renames in the request to the same element name, for example, DuplicatedNewName. The error response to this request is:

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="23">
    <Alea:Return>
      <Alea:User Name="Admin" />
      <Alea:Dimension Name="REGION">
        <Alea:Element Name="DuplicatedNewName" />
        <Alea:Error ErrorID="7" />
      </Alea:Dimension>
    </Alea:Return>
    <Alea:Error ErrorID="7" />
  </Alea:Request>
</Alea:Document>

Error 4

If there is an error in the required cube operations due to element renaming, the error response is similar to this:

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="24">
    <Alea:Return>
      <Alea:User Name="Admin" />
      <Alea:CubeError CubeName="Sales">
        <Alea:Error ErrorID="115" />
      </Alea:CubeError>
    </Alea:Return>
    <Alea:Error ErrorID="115" />
  </Alea:Request>
</Alea:Document>