Value resolver – Abstract

Purpose: This parses a string or content object into an XML DOM object that can be evaluated with the Object property resolver via XPath expressions.

images/download/attachments/201657493/image-2025-2-25_15-2-28-version-1-modificationdate-1740492148571-api-v2.png

The Parse XML value resolver requires an XML structure given as a text (String) or ‘content’ object as an input value, which is then parsed into a DOM object.

The overarching data type ‘XML element’ (org.w3c.dom.Element), which also applies to all parsed XML elements within a DOM object, is specified in the hint for the DOM object provided as the return value.

The Object property value resolver can be used to access the parsed content, whereby a valid XPath 2.0 expression must be specified in conjunction with the ‘XML element’ data type instead of a path to a data field.

Examples:

The screenshot on the right shows a very simple example for which a simple XML structure was entered as static Text in the Entity resolver of an Execute with event action.

The concatenated Parse XML resolver generates a DOM object from this, which is subsequently used for different accesses.
The concatenated Object property resolver accesses the second li element via the XPath expression //li[2]], which is found when the complete DOM object is searched.
- If a corresponding element exists, it is used as a temporary reference object for the following action block.
- 'XML Element’ appears again as a type hint.
The action block contains a Show alert event action that displays two contents from the DOM object:
- The Object property resolver in the Title uses the XPath expression //@topic[1] to search the entire DOM object (//) again for an XML attribute topic and returns exactly the attribute value of the first match ([1]).
- The Object property resolver for the Message begins a similar search relative to the reference object (.), which is searched completely for the first match ([1]) for an attribute with the name SRC. Accessing the attribute value here returns a text value (reddot.bmp).

►NOTE◄ The expressions in this example are aimed at quick, easily comprehensible ‘success’ in the extremely simple setting. The ‘complete search’ for elements in an XML structure using // simplifies the expressions considerably in formal terms, but should not be misunderstood as best practice. The approach is often too imprecise and can be computationally intensive.

images/download/attachments/201657493/image-2025-2-25_18-56-5-version-1-modificationdate-1740506165586-api-v2.png

Configuration

The Parse XML resolver does not use any parameters.

A number of rules apply to read access to a DOM object via XPath expressions in the Object property resolver, which will be explained using the example data used above.

Example data that can define a temporary reference object in the header of an Execute with (as above), for example.		►IMPORTANT◄ The input value for the Parse XML value resolver must describe a well-formed XML document: The XML syntax for describing elements, attributes (etc.) must be adhered to exactly. The structure must be held together by exactly one parent element (top node). CAUTION Errors when parsing the input value are treated as an exception. The absence of an input value is also considered an error. In the context of a workflow, the event action Try/Catch actor can be used to prevent the cancellation with rollback that may result. In Association criteria, however, an error during parsing is intercepted with the return value ‘Failed’ (`$false`).
Scenario/Target	Configuration	Description
No XPath expression		Without an XPath expression, the Object property value resolver returns the complete DOM object. The type hint for the return value is ‘XML element’. This means that exactly one (or no) XML element is expected as the return value.
Read attribute value		The XPath expression `@topic` searches the ‘XML element’ expected as input value for an XML attribute whose name is exactly (including upper/lower case) `topic` and returns its value. As attributes must be uniquely named, exactly one (or no) return value is expected. The type hint for the return value is `String`.
Read all child elements of a type		The XPath expression `li` searches in the ‘XML element’ expected as input value (here: the top node `ul`) for direct child elements whose name is exactly (including upper/lower case) `li`, and returns these as a list. If no elements with the name you are looking for exist, an empty list (`[]`) is returned. The type hint for the return value is `XML Element[]`.
Read one child element of a type		The XPath expression `li[1]`searches in the ‘XML element’ expected as input value (here: the top node `ul`) for direct child elements whose name is exactly (including upper/lower case) `li`, and returns the first match. Instead of `1`, a different index value (ascending from 1) can be used. If there is no match with the addressed index, ‘No value’ (`$null`) is returned. The type hint for the return value is `XML Element`.
Read selected child elements of a type		The XPath expression `li[1]` searches in the 'XML element' expected as input value (here: the top node `ul`) for direct child elements whose name is exactly (including upper/lower case) `li` and returns the subset of `li` elements that have at least one child element with the name `img`. In the sample data, all `li` elements fulfill this condition. The type hint for the return value is `XML Element[]`.
Read selected child elements of a type		The XPath expression `li[img[starts-with(@SRC,"red")]]` searches in the ‘XML element’ expected as input value (here: the top node `ul`) for direct child elements whose name is exactly (including upper/lower case) `li`, and returns the subset of `li` elements that have at least one child element with the name img whose `SRC` attribute contains a text value that begins with the `red` character string. In the sample data, exactly one `li` element fulfils this requirement. It is returned as the only entry in a list. The type hint for the return value is `XML Element[]`.
Search for all elements of a type and read a specific attribute value from each one		The XPath expression `//img/@SRC` searches in the ‘XML element’ expected as input value (here: the top node `ul`) for directly or indirectly contained child elements whose name is exactly (including upper/lower case) `img`, and outputs the text value of the `SRC` attribute for each element. `img` elements that do not have an `SRC` attribute are skipped (not relevant in the example). The type hint for the return value is `String[]`.
Search for all elements of a type for which the value of any attribute contains a text		The XPath expression `//img/@SRC` searches in the ‘XML element’ expected as input value (here: the top node `ul`) for directly or indirectly contained child elements whose name is exactly (including upper/lower case) `img` and which have at least one attribute with any name (`@*`) whose value contains the text ‘dot’. `img` elements that do not have an attribute with the searched substring are skipped. In the example, all `img` elements are returned. The type hint for the return value is `XML Element[]`.
Search for elements of any type that have an attribute whose name corresponds to a text pattern		The XPath expression `///@[ends-with(name(),"c")]`searches all elements in the ‘XML element’ expected as input value (including the top node) for those that have at least one attribute whose name (`name()`) contains a ‘c’ as the last character. In the example, this only applies to the top node (`ul` with the `topic` attribute), which is returned as the only entry in a list. The type hint for the return value is `XML Element[]`.
		The XPath expression `//[@[ends-with(lower-case(name()),"c")]]` searches all elements in the ‘XML element’ ‘XML element’ expected as input value (including the top node) for those that have at least one attribute whose name (`name()`) contains a ‘`c`’ or a ‘`C`’ as the last character. In the example, this applies to the top node (with the `topic` attribute) and all `img` elements (each with an `SRC` attribute), which are returned as a list.
The following examples use sample data in which the XML structure contains text nodes
Read text from an element		The XPath expression `text()`searches the ‘XML element’ expected as input value for text nodes and returns the first text value found. Only the character string ‘`SEND` ’ (without inverted commas) is returned with the sample data. The type hint for the return value is `String`.
		The XPath expression `/a/text()`searches the ‘XML element’ expected as input value for text nodes and returns all text values that are contained directly in the node (here: `a` element). The sample data returns a list with the character strings ‘`SEND` ’ and ‘ `NOW`’ (without inverted commas) is returned. The type hint for the return value is `String[]`.
		The XPath expression `/a/text()`searches the ‘XML element’ expected as input value for text nodes and returns all text values that are contained directly or indirectly in the top node (here: `a` element). With the sample data, a list with the character strings `"SEND ", "EMAIL", " NOW"` (without inverted commas) is returned. The type hint for the return value is `String[]`.