XML Set Value

XML Set Value

Type: xml-set-value  ·  Package: XML Activities v1.1.1  ·  Output: string

Changes the text value of the first element (or attribute) matching an XPath and returns the modified XML. Use it to update data in an XML document: a status, a date, an amount.

How it works

Finds the first match of xpath in the xml, sets the new value on it and returns the whole modified XML (as a string). Remember to save the result with Write XML.

• If the XPath points to an attribute (//cbc:ID/@schemeID), it changes the attribute’s value.
• If it points to an element, it replaces all of its content with the text of value: if the element had children, they are removed. To change an inner value, point to the leaf element (//Customer/Name, not //Customer).
• value can be of any type: its text is written (true, 1500). null leaves the element empty.
• It only changes the first match. To change several, go through the indexes ((//Item)[1], (//Item)[2]…) or use a more precise XPath.
• If nothing matches, the activity fails (it doesn’t return the XML unchanged).

The returned XML is indented and doesn’t include the <?xml …?> declaration; Write XML writes it when saving.

The document’s namespace prefixes work directly. See Namespaces.

Required parameters

Parameter	Type	Default	Description
xml	string	—	The XML text.
xpath	string	—	XPath to the element or attribute to update, e.g. //Invoice/Status or //cbc:ID/@schemeID.
value	object	—	The new value. It is written as text.

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 whole modified XML.

Common errors

Message	Cause and fix
No node matches the given XPath.	The XPath finds nothing. Check it with XML Query Text; if the document has a default namespace, use the d: prefix (the log reminds you).
The XPath must select an element or an attribute.	The XPath computes a value (count(…)) or selects a text node (…/text()). Point to the element or the attribute.
'xml' is required. / 'xpath' is required.	The parameter was left empty or its expression returned null.
The XPath expression «…» is not valid: … / The prefix 'x:' is not declared …	See Common package errors.

Example

Read XML   path = filePath   → output: xml
XML Set Value   xml = xml   xpath = "//Invoice/Status"   value = "Paid"   → output: newXml
Write XML   path = filePath   content = newXml

Changing an attribute of a UBL invoice:

XML Set Value   xml = invoice   xpath = "//cbc:PayableAmount/@currencyID"   value = "USD"   → output: invoice

Returns the XML, doesn’t modify the file

Set Value works on the text: it returns the changed XML but does not touch the file. To persist the change, pass its output to Write XML.

Related activities

• XML Add Element — add a new element.
• Write XML — save the result.