Example - Refreshing a Document with a Hierarchical List of Values

Hierarchical LOVs accept an extra <path> element in the <query> section to go down to each level of the hierarchy. You must repeat the query until you have reached the final leaf of the node. Consider the hierarchy below:

The refresh is performed as follows:

  1. Send a first call without any <path> entry get the first level, as if there were no hierarchy, except for the hierarchical="true" tag. final="false" means the value is a node of the hierarchy, whereas final="true" or no tag at all means value is a leaf.
  2. Send a second call with any of the known first-level values, this will get the corresponding second level values
  3. Repeat the call, updating the query body with the required values for each level, until there are no more nodes, i.e. the user has reached a final leaf.
  4. Refresh the document as usual, providing all required <value> and the mandatory <path>.

Example

Sending the first call

A first call without any <path> entry get the first level, as if there were no hierarchy, except for the hierarchical="true" tag. final="false" means the value is a node of the hierarchy, whereas final="true" or no tag at all means value is a leaf.

GET <webiURL>/documents/9586/parameters

The response returns the prompts at the first level in the hierarchy:

<parameters>
    <parameter optional="false" type="prompt" dpId="DPe">
        <id>0</id>
        <technicalName>Enter values for Customer in TreeViewLov:</technicalName>
        <name>Enter values for Customer in TreeViewLov:</name>
        <answer constrained="true" type="Text">
            <info cardinality="Multiple">
                <lov hierarchical="true" refreshable="true">
                    <id>UNIVERSELOV_DS2.DObb</id>
                    <intervals>
                        <interval id="0">
                            <value final="false">Australia</value>
                            <value final="false">US</value>
                        </interval>
                    </intervals>
                    <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>
                </lov>
            </info>
        </answer>
    </parameter>
</parameters>
Request body: use the information retrieved from the response to write the second request body:
<parameters>
    <parameter>
        <id>0</id>
        <answer>
            <info>
                <lov>
                    <query>
                        <path>
                            <value>France</value>
                        </path>
                    </query>
                </lov>
            </info>
        </answer>
    </parameter>
</parameters>
Send the request again, this time referencing the XML file:

PUT <webiURL>documents/9586/parameters

The response returns the prompts at the next level in the hierarchy:

<parameters>
    <parameter optional="false" type="prompt" dpId="DPe">
        <id>0</id>
        <technicalName>Enter values for Customer in TreeViewLov:</technicalName>
        <name>Enter values for Customer in TreeViewLov:</name>
        <answer constrained="true" type="Text">
            <info cardinality="Multiple">
                <lov hierarchical="true" refreshable="true">
                    <id>UNIVERSELOV_DS2.DObb</id>
                    <intervals>
                        <interval id="0">
                            <value final="false">French Alps</value>
                            <value final="false">Provence</value>
                        </interval>
                    </intervals>
                    <values>
                        <value final="false">French Alps</value>
                        <value final="false">Normandy</value>
                        <value final="false">Paris</value>
                        <value final="false">Provence</value>
                    </values>
                </lov>
            </info>
        </answer>
    </parameter>
</parameters>

Use the information retrieved from the response to update your request body XML file:

<parameters>
    <parameter>
        <id>0</id>
        <answer>
            <info>
                <lov>
                    <query>
                        <path>
                            <value>France</value>
                            <value>Provence</value>
                        </path>
                    </query>
                </lov>
            </info>
        </answer>
    </parameter>
</parameters>
Send the request again, referencing the updated XML file:

PUT <webiURL>/documents/9586/parameters

The response returns the prompts at the next level in the hierarchy:

<parameters>
    <parameter optional="false" type="prompt" dpId="DPe">
        <id>0</id>
        <technicalName>Enter values for Customer in TreeViewLov:</technicalName>
        <name>Enter values for Customer in TreeViewLov:</name>
        <answer constrained="true" type="Text">
            <info cardinality="Multiple">
                <lov hierarchical="true" refreshable="true">
                    <id>UNIVERSELOV_DS2.DObb</id>
                    <intervals>
                        <interval id="0">
                            <value final="false">Bordeaux</value>
                            <value final="false">Nice</value>
                        </interval>
                    </intervals>
                    <values>
                        <value final="false">Bordeaux</value>
                        <value final="false">Marseille</value>
                        <value final="false">Nice</value>
                    </values>
                </lov>
            </info>
        </answer>
    </parameter>
</parameters>

Use the information retrieved from the response to update your request body XML file:

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

Send the request again, referencing the updated XML file:

PUT <webiURL>/documents/9586/parameters

The response returns the prompts at the next level in the hierarchy:

<parameters>
    <parameter optional="false" type="prompt" dpId="DPe">
        <id>0</id>
        <technicalName>Enter values for Customer in TreeViewLov:</technicalName>
        <name>Enter values for Customer in TreeViewLov:</name>
        <answer constrained="true" type="Text">
            <info cardinality="Multiple">
                <lov hierarchical="true" refreshable="true">
                    <id>UNIVERSELOV_DS2.DObb</id>
                    <updated>2012-12-11T15:59:15.000+01:00</updated>
                    <intervals>
                        <interval id="0">
                            <value>Piaget</value>
                            <value>Piaget</value>
                        </interval>
                    </intervals>
                    <values>
                        <value>Piaget</value>
                    </values>
                    <columns mappingId="0">
                        <column id="0" type="string">Customer in TreeViewLov </column>
                    </columns>
                </lov>
            </info>
        </answer>
    </parameter>
</parameters>

The document can now be refreshed as usual, providing a <value> (<path> is not mandatory anymore as the values are now known).

Use the information retrieved from the response to update your body XML file:

<parameters>
    <parameter>
        <id>0</id>
        <answer>
            <values>
                <value>Piaget</value>
            </values>
        </answer>
    </parameter>
</parameters>

Now all the information is in the body file, you can refresh the document using the PUT command and the XML file. When the refresh is successful, you get the following response:

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