XML Add Element

XML Add Element

Type: xml-add-element  ·  Package: XML Activities v1.1.1  ·  Output: string

Adds a new child element to the first node matching an XPath, and returns the modified XML. Use it to build or extend an XML document: add a line to an invoice, a field to a record.

How it works

Finds the parent element with xpath (the first match), creates inside it a child element named elementName (with optional elementValue and attributes) after its existing children and returns the modified XML as a string. Save it with Write XML.

• Every run adds a new element: if you repeat it, the child is duplicated.
• The values in attributes are written as text; a null value leaves the attribute empty ("").
• The returned XML is indented and doesn’t include the <?xml …?> declaration; Write XML writes it when saving.

With namespaces:

• elementName can carry a prefix: cbc:Note creates the element in the cbc namespace and reuses the document’s declaration. If the prefix only comes from namespaces, it is declared on the new element with that same prefix.
• Without a prefix, the element takes the parent’s default namespace (no stray xmlns="" appears).
• The keys of attributes also accept a prefix (xsi:nil). Without a prefix, an attribute has no namespace, as XML requires.

Required parameters

Parameter	Type	Default	Description
xml	string	—	The XML text.
xpath	string	—	XPath to the parent element. It must select an element.
elementName	string	—	Name of the new element, with a namespace prefix if needed (cbc:Note).

Optional parameters

Parameter	Type	Default	Description
elementValue	string	—	Text content of the new element. Without it, the element is empty (<Note />).
attributes	Dictionary	—	Attributes of the new element (name → value), e.g. dictSet(newDict(), "type", "internal"). A value that isn’t a dictionary is ignored.
namespaces	Dictionary	—	Extra prefixes, or prefixes that override the document’s (prefix → URI), for the XPath and for prefixed names. 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 parent node matches the given XPath.	The XPath finds nothing, or selects something that isn’t an element (an attribute, a value). If the document has a default namespace, use d: (the log reminds you).
'…' is not a valid XML name.	elementName or a key of attributes has spaces, starts with a digit or contains characters that aren’t allowed.
The prefix 'x:' is not declared in the XML or in 'namespaces'. Available prefixes: ….	The prefix of the XPath, of elementName or of an attribute doesn’t exist. Define it in namespaces.
'xml' is required. / 'xpath' is required. / 'elementName' is required.	The parameter was left empty or its expression returned null.
The XPath expression «…» is not valid: …	See Common package errors.

Example

Add a <Remark> field inside <Invoice>:

XML Add Element
  xml = xml
  xpath = "//Invoice"
  elementName = "Remark"
  elementValue = "Reviewed automatically"
  attributes = dictSet(newDict(), "source", "robot")
  → output: newXml
Write XML   path = filePath   content = newXml

Result inside <Invoice>: <Remark source="robot">Reviewed automatically</Remark>.

In a UBL invoice:

XML Add Element   xml = invoice   xpath = "/d:Invoice"   elementName = "cbc:Note"   elementValue = "Reviewed"   → output: newInvoice

Related activities

• XML Set Value — change the value of an existing element.
• Write XML — save the result.