MENU
    Append Dimension Members (Master and Analytic Models)
    • 4 Minutes to read
    • Dark
    • PDF

    Append Dimension Members (Master and Analytic Models)

    • Dark
    • PDF

    Article summary

    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>
    Shell

    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.

    Note:
    Label is optional but if it has been defined in <hierarchy> then define all <dimension-member> tag

    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>
    Shell

    <?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

    AccountScenarioDepartmentAmountTime

    1001

    Actual

    Sales

    100

    Jan-13

    1002

    Actual

    Sales

    200

    Jan-13

    1003

    Actual

    Sales

    300

    Jan-13

    1004

    Actual

    Marketing

    400

    Jan-13

    1005

    Actual

    Marketing

    500

    Jan-13

    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>
    Shell

    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>
    Shell

    Empty Page Dimensions

    <pagedimensions/>
    Shell

    No Page Dimensions: Skip This Tag Completely

    Note:
    Amount is available at the intersection of all dimension members in every row. It should not be used in either a page-dimension or a column-dimension
    Note:
    Dimensions in either tag can assume any order

    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

    AccountScenarioDepartmentAmountTime

    1001

    Actual

    Sales

    100

    Jan-13

    1001

    Actual

    Sales

    200

    Feb-13

    1001

    Actual

    Sales

    300

    Mar-13

    1002

    Actual

    Marketing

    400

    Jan-13

    1002

    Actual

    Marketing

    500

    Feb-13

    1002

    Actual

    Marketing

    600

    Mar-13

    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>
    Shell

    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>
    Shell

    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

    AccountScenarioDepartment

    Jan-16

    Amount


    Feb-16

    Amount


    Mar-16

    Amount


    1001

    Actual

    Sales

    100

    200

    300

    1001

    Actual

    Marketing

    400

    500

    600

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

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

    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>
    Shell

    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>
    Shell

    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>
    Shell

    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>
    Shell

    Was this article helpful?