Example - Refreshing a Document with a Hierarchical Parameter

A GET .../parameters call returns a list of values for a specific parameter of type prompt that asks you to select a city. Values are countries.

The response contains the prompts at the first level in the hierarchy (hierarchical="true"). final="false" means the value is a node of the hierarchy, while final="true" or no tag means value is a leaf.

Response:

<parameters>
    <parameter optional="false" type="prompt" dpId="DPe">
        <id>0</id>
        <technicalName>Select a city:</technicalName>
        <name>Select a city:</name>
        <answer constrained="true" type="Text">
            <info cardinality="Multiple">
                <lov hierarchical="true" partial="false" refreshable="true" searchable="false">
                    <id>UNIVERSELOV_DS2.DObb</id>
                    <values>
                        <value final="false">Australia</value>
                        <value final="false">France</value>
                        <value final="false">Germany</value>
                        <value final="false">Holland</value>
                        <value final="false">Japan</value>
                        <value final="false">Madagascar</value>
                        <value final="false">Middle East</value>
                        <value final="false">Nepal</value>
                        <value final="false">South Africa</value>
                        <value final="false">UK</value>
                        <value final="false">US</value>
                    </values>
                    <columns mappingId="0">
                        <column id="0" type="String">Country</column>
                    </columns> 
                </lov>
            </info>
        </answer>
    </parameter>
</parameters>

In the first PUT call, a value of the first level of the list of values is given as answer to the parameter. Hierarchical lists of values accept an extra <path> element in the <query> section to go down to each level of the hierarchical parameter. The answer is France.

Request body:

<parameters>
    <parameter>
        <id>0</id>
        <answer>
            <info>
                <lov>
                    <query>
                        <path>
                            <value>France</value>
                        </path>
                    </query>
                </lov>
            </info>
        </answer>
    </parameter>
</parameters>

The response contains the list of values of the second level of the parameter. Values represent regions. The path attribute of the <lov> element describes the path to any value of the list of values returned in the call. The number represents the data type (0 for string, 1 for date, 2 for numeric).

Response:

<parameters>
    <parameter optional="false" type="prompt" dpId="DPe">
        <id>0</id>
        <technicalName>Select a city:</technicalName>
        <name>Select a city:</name>
        <answer constrained="true" type="Text">
            <info cardinality="Multiple">
                <lov hierarchical="true" partial="false" refreshable="true" searchable="false" path="[[0,\ France]]">
                    <id>UNIVERSELOV_DS2.DObb</id>
                    <values>
                        <value final="false">French Alps</value>
                        <value final="false">Normandy</value>
                        <value final="false">Paris</value>
                        <value final="false">Provence</value>
                    </values>
                    <columns mappingId="0">
                        <column id="0" type="String">Region</column>
                    </columns> 
                </lov>
            </info>
        </answer>
    </parameter>
</parameters>

In a second PUT call, the value of the list of values of the second level is given as answer to the parameter (Provence). The first level value is recalled (France).

Request body:

<parameters>
    <parameter>
        <id>0</id>
        <answer>
            <info>
                <lov>
                    <query>
                        <path>
                            <value>France</value>
                            <value>Provence</value>
                        </path>
                    </query>
                </lov>
            </info>
        </answer>
    </parameter>
</parameters>

The response contains the list of values of the third and last level of the parameter. Values represent cities.

Response:

<parameters>
    <parameter optional="false" type="prompt" dpId="DPe">
        <id>0</id>
        <technicalName>Select a city:</technicalName>
        <name>Select a city:</name>
        <answer constrained="true" type="Text">
            <info cardinality="Multiple">
                <lov hierarchical="true" partial="false" refreshable="true" searchable="false" path="[[0,\ France], [0,\ Provence]]">
                    <id>UNIVERSELOV_DS2.DObb</id>
                    <values>
                        <value final="false">Bordeaux</value>
                        <value final="false">Marseille</value>
                        <value final="false">Nice</value>
                    </values>
                    <columns mappingId="0">
                        <column id="0" type="String">City</column>
                    </columns>
                </lov>
            </info>
        </answer>
    </parameter>
</parameters>

A last PUT call refreshes the document with a <value>.

Request body:

<parameters>
    <parameter>
        <id>0</id>
        <answer>
            <values>
                <value path="[[0,\ France], [0,\ Provence]]">Bordeaux</value>
            </values>
        </answer>
    </parameter>
</parameters>

Response:

<success>
    <message>The resource of type 'Document' with identifier '9586' has been successfully updated.</message>
    <id>9586</id>
</success>