Append Dimension Members (Master and Analytic Models)

Append Dimension Members (Master and Analytic Models)

Use this API to append dimension members in Master and Analytic models. You can load Display Label as an optional parameter.

POST /modeling/model/member/append HTTP/1.1
Content-Type: application/xml
Accept: application/xml
X-ACCESS-TOKEN:
<?xml version="1.0" encoding="UTF-8"?>
<append-member-payload>
<model-name>$ModelName</model-name>
<dimension-name>$DimensionName</dimension-name>
<delimiter>$Delimiter</delimiter>
<hierarchy>$ParentChildHierarchyPlusOperatorLabel</hierarchy>
<dimension-member>$DimensionMemberPlusOperatorLabel</dimension-member>
… add more dimension members if needed
</append-member-payload>

Parameters

@@ - Delimiter

1. $ModelName: (type: string) Name of the model. If the model specified does not exist, the operation is canceled.

2. $DimensionName: (type: string) Name of the Dimension that is associated with this model. If the dimension specified does not exist, the operation is canceled.

3. $Parent@@Child@@Operator@@label: Specify the location of the child member, parent member , rollup operator and label delimited by delimiter string(@@)

4. DimensionMemberPlusOperatorlabel: Specify the new dimension member, its parent , rollup operator land label delimited by delimiter string in the same order as specified in the hierarchy tag. Add multiple dimension members using different dimension-member tags.

Sample Payload

<?xml version="1.0" encoding="UTF-8"?>
<append-member-payload>
<model-name>Operating Expense</model-name>
<dimension-name>Account</dimension-name>
<delimiter>@@</delimiter>
<hierarchy>parent@@child@@operator@@label</hierarchy>
<dimension-member>Account@@Income Statement@@~@@Jan2010 
	Income</dimension-member>
<dimension-member>Income Statement@@Income Statement 100@@+@@Feb2019 
	Income</dimension-member>
</append-member-payload>

<?xml version="1.0" encoding="UTF-8"?>

Response

Success Response

HTTP/1.1 204 OK

Error Responses

Service Not Available (Possibly due to maintenance)

HTTP/1.1 404 Not Found

One or more HTTP headers were missing

HTTP/1.1 412 Precondition Failed

Model/Dimension not found

HTTP/1.1 412 Precondition Failed

Unauthorized Access (Access key lookup failed)

HTTP/1.1 401 Unauthorized

Invalid XML (Bad Request)

HTTP/1.1 400 Bad Request

Page dimensions

Page dimensions are optional. If the user chooses not to have page dimensions, they may skip this tag completely. Alternately an empty tag can be specified as well.

Page-dimensions tag comprises of all dimensions that have page level scope. In order to have page level scope, the single unique dimension member of this dimension should apply to all data-records.

Column dimensions

Column-dimensions tag comprises of all other dimensions that are not identified as page-dimensions. Each data-record provides a dimension member for every dimension identified in this tag. These dimension members can be unique or non-unique across all data records.

For example: Consider the following records for loading the data:

Table 1

These records are to be loaded into a model with four dimensions:

• Account (with dimension members 1001, 1002, 1003, 1004, 1005)

• Scenario (with dimension member ‘Actual’)

• Department (with dimension members ‘Sales’ and ‘Marketing’)

• Time (with dimension member ‘Jan-13’)

Here, Scenario: Actual and Time: Jan-13 qualifies to be extracted to page level scope. But, since page-dimensions are entirely optional, below four examples are valid.

Scenario As Page Dimension

<page-dimensions>
<entry>
<key>Scenario</key>
<value>Actual</key>
</entry>
</page-dimensions>
<column-dimensions>
<entry>
<key>1</key>
<value>Account</value>
</entry>
<entry>
<key>2</key>
<value>Department</value>
</entry>
<entry>
<key>3</key>
<value>Time</value>
</entry>
</column-dimensions>

Time As Page Dimension

<page-dimensions>
<entry>
<key>Time</key>
<value>Jan-13</key>
</entry>
</page-dimensions>
<column-dimensions>
<entry>
<key>1</key>
<value>Account</value>
</entry>
<entry>
<key>2</key>
<value>Scenario</value>
</entry>
<entry>
<key>3</key>
<value>Department</value>
</entry>
</column-dimensions>

Empty Page Dimensions

<pagedimensions/>

No Page Dimensions: Skip This Tag Completely

Additional Information with a Sample Payload

Consider a model that has four dimensions:

1. Account (includes dimension members 1001 and 1002)

2. Scenario (includes dimension member Actual)

3. Department (includes dimension members Sales and Marketing)

4. Time (includes dimension members Jan-13, Feb-13 and Mar-13)

To insert the following table of amounts into the model:

Table 2

Design a payload first creating column-dimensions as follows:

<column-dimensions>
<entry>
<key>1</key>
<value>Account</value>
</entry>
<entry>
<key>2</key>
<value>Scenario</value>
</entry>
<entry>
<key>3</key>
<value>Department</value>
</entry>
<entry>
<key>4</key>
<value>Time</value>
</entry>
</column-dimensions>

The order of dimensions above specifies their order in the data-records section below. For each entry in column-dimensions, ‘value’ identifies the Dimension name, and ‘key’ indicates the position number dedicated to that dimension in every data-record.

For example:

Value: Account

Key: 1

Indicates that the first column in data-record is dedicated to an Account dimension member

Value: Time

Key: 4

Indicates that the fourth column in data-records is dedicated to a Time dimension member

Next, indicate the delimiter used in data-records to separate columns

<delimiter>@@</delimiter>

column-members tag contains information about dimension members that are shared by all data-records in the payload. This is a mandatory tag. It can contain one or more entries. The number of entries in this tag determine the number of columns dedicated to values in data-records. Two entries in column-members signifies two amount columns.

In this example below, entry with key=2 and value=’Actual’ indicates the second column of the data row is associated with member: Actual. This allows us to enter the amount in the second column for every data record.

<column-members>
<entry>
<key>2</key>
<value>Actual</value>
</entry>
</column-members>

Every row in table 2 has an entry in data-records tag. column-dimensions entry key determines the order of the dimension members in every data-record. As an example Department:Sales and Marketing are in column 3 as noted in column-dimensions tag Note that the amount in every Table 2 row is input in the second column of every record.

<data-records>

<data-record>1001@@100@@Sales@@Jan-13</data-record>

<data-record>1001@@200@@Sales@@Feb-13</data-record>

<data-record>1001@@300@@Sales@@Mar-13</data-record>

<data-record>1002@@400@@Marketing@@Jan-13</data-record>

<data-record>1002@@500@@Marketing@@Feb-13</data-record>

<data-record>1002@@600@@Marketing@@Mar-13</data-record>

</data-records>

Additional Information with Multiple Columns per Dimension

Often, there is a need to enter data for multiple members of a dimension. Consider the following example:

Table 3

The following payload can be used to enter data in this format:

<page-dimensions>
<entry>
<key>Scenario</key>
<value>Actual</key>
</entry>
</page-dimensions>

Extract Scenario: Actual to page since all records in Table 3 relate to Scenario: Actual

<column-dimensions>
<entry>
<key>1</key>
<value>Account</value>
</entry>
<entry>
<key>2</key>
<value>Department</value>
</entry>
<entry>
<key>3</key>
<value>Time</value>
</entry>
<entry>
<key>4</key>
<value>Time</value>
</entry>
<entry>
<key>5</key>
<value>Time</value>
</entry>
</column-dimensions>

This says that column 1 of every data-record contains an Account member, column 2 contains a Department member and Columns 3 to 5 contain Time dimension members.

<column-members>
<entry>
<key>3</key>
<value>Jan-16</value>
</entry>
<entry>
<key>4</key>
<value>Feb-16</value>
</entry>
<entry>
<key>5</key>
<value>Mar-16</value>
</entry>
</column-members>

The above xml snippet indicates that column 3 of every data-record contains amount related to Time: Jan-16, column 4 of data-record contains amount related to Time: Feb-16 and column 5 contains amount related to Time: Mar-16.

Specify delimiter as follows:

<delimiter>@@</delimiter>

The below xml snippet adds data per Table 3:

<data-records>
<data-record>1001@@Sales@@100@@200@@300</data-record>
<data-record>1002@@Marketing@@400@@500@@600</data-record>
</data-records>