XML Query Text

XML Query Text

Type: xml-query-text  ·  Package: XML Activities v1.1.1  ·  Output: string

Evaluates an XPath expression over an XML and returns the first text value that matches. It is the way to extract data from an XML document: the number of an invoice, the name of a customer, a total.

How it works

Applies the xpath to the xml and returns the text of the first match in document order:

• An element: its text. If it has children, the text of all its descendants, joined.
• An attribute (//cbc:PayableAmount/@currencyID): its value.
• A computed value (count(//cac:InvoiceLine), sum(//Total), a comparison): the number (2, 1785000.5) or true/false.

If there is no match it returns null (it doesn’t fail) and logs a warning. See XPath in a scoop.

The document’s namespace prefixes work directly (//cbc:ID) and the default namespace is written with d: (/d:Invoice). See Namespaces.

The xml can also be an XML embedded as text, for example the content of a CDATA you extracted with another query. See XML inside XML.

It doesn’t modify the input xml.

Required parameters

Parameter	Type	Default	Description
xml	string	—	The XML text (from Read XML or another query). Also an embedded XML, like the content of a CDATA.
xpath	string	—	The XPath expression, e.g. //Invoice/Number, //cbc:ID or //Total/@currency.

Optional parameters

Parameter	Type	Default	Description
namespaces	Dictionary	—	Extra prefixes, or prefixes that override the document’s (prefix → URI). The ones declared in the XML are registered automatically. Since 1.1.0.
defaultPrefix	string	"d"	Prefix used in the XPath for the document’s default namespace (xmlns="…"). Empty means "d". Since 1.1.0.

Output

Returns a string with the text of the first match, or null if the XPath finds nothing. An empty element (<Note/>) returns "", not null: that is how you tell “missing” from “empty”.

Common errors

Message	Cause and fix
'xml' is required. / 'xpath' is required.	The parameter was left empty or its expression returned null (for example, a previous query didn’t find the CDATA). Check the variable with an If first.
The XPath expression «…» is not valid: …	Wrong syntax in the XPath.
The prefix 'x:' is not declared in the XML or in 'namespaces'. Available prefixes: ….	Use one of the listed prefixes or define it in namespaces.
XML parser / DTD / size / nesting message	The xml is not valid or exceeds the limits. See Common package errors.

Finding no match is not an error: check whether the output is null.

Example

Read XML   path = filePath   → output: xml
XML Query Text   xml = xml   xpath = "//Invoice/Total"   → output: total
If   condition = total == null
 └─ then:
      Throw   message = "The invoice has no total"
Log   message = "Invoice total: " + total

With namespaces (UBL invoice):

XML Query Text   xml = invoice   xpath = "//cac:LegalMonetaryTotal/cbc:PayableAmount"   → output: total
XML Query Text   xml = invoice   xpath = "//cac:LegalMonetaryTotal/cbc:PayableAmount/@currencyID"   → output: currency
XML Query Text   xml = invoice   xpath = "count(//cac:InvoiceLine)"   → output: lineCount

Related activities

• XML Query All — return all the matching values.
• XML to Dictionary — convert the whole document.
• Read XML — load the document.