Using the XPATH function for web service qualifications
An XPATH expression identifies an XML element inside an XML document. Its syntax is similar to a directory path. When creating XPATH expressions, follow these guidelines:
- The XPATH function takes one argument, which must be an expression referencing an element or an attribute in the input mapping of the operation.
- The element or attribute being referenced does not have to be mapped to a field; it might exist only in the XML schema and be used only for qualification.
- The expression must start with /ROOT and must list all the elements in the path including the one being referenced.
- When referencing an attribute, use @ before the attribute name.
- The XPATH function can be used anywhere in the qualification, and a value is substituted based on the XML data type.
- For strings, AR Systemadds extra double quotation marks around the value.
- For date-time fields, the XML date/time string is converted to the number of seconds.
- If more than one element matches the expression, the first element is considered.
- An entire qualification string can be passed as one of the XML elements in the input document to create totally dynamic queries. This is analogous to using the EXTERNAL function.
- If an element is missing in the input document, it is resolved to $NULL$.
XPATH expressions are similar to field references, for example, suppose you have this qualification:
$RequestID$ is the value of the RequestID field in the current entry, and 'RequestID' is the field to search on.
Similarly:
XPATH("/ROOT/RequestID") is the value of the RequestID in the current XML document, and RequestID is the field to search on.
This is an example of an XML document and some sample qualification strings using XPATH expressions:
<ROOT>
<Employee ID="112">Adam</Employee>
<Address>
<Street>1500 Salado Dr</Street>
<City>Mountain View</City>
</Address>
<HireDate>2004-01-01T00:00:00.0000000-08:00</HireDate>
<query>
<qualification>'Employee_ID' > 100</qualification>
</query>
</ROOT>
Sample qualification | XPATH resolved qualification | Comments |
|---|---|---|
'Employee_Name'=XPATH(/ROOT/Employee) | 'Employee_Name'="Adam" | Employee is of type string. |
'Employee_ID'=XPATH(/ROOT/Employee/@ID) | 'Employee_ID'=112 | ID is an attribute of type integer. |
'City'=XPATH(/ROOT/Address/City) | 'City'="Mountain View" | City is of type string. |
'HireDate'=XPATH(/ROOT/HireDate) | 'HireDate'=1009872000 | HireDate is of type dateTime. It converts to the number of seconds since 1/1/1970. |
'State'=XPATH(/ROOT/Address/State) | 'State'=$NULL$ | State does not exist in the input document. |
XPATH(/ROOT/query/qualification) | 'Employee_ID'>100 | Qualification is of type string. |
For information about the XPATH specification, see http://www.w3.org/TR/xpath.
To construct XPATH expressions in the Expression Editor
- Expand the WSDL operation panel where you want to add the XPATH expression.
- Click the ellipsis button [...] next to the Qualification field to open the Expression Editor.
- In the Expression Editor, expand the Fields panel.
XPATH panel in the Expression Editor
- Double-click a field name so that it appears in the editing field.
- Click the = button.
- Expand the XPATH panel.
- Double-click an XML element so that it appears in the expression editing area.
Alternatively, you can highlight an element and click the Add XPATH button. Verify that your XPATH expression is correct, for example:
'Request ID' = XPATH(/ROOT/Request_ID)Click OK to save your qualification.
For more information about using the Expression Editor, see Expression-editor-and-content-assist.