XML Add Element

XML Add Element

Tipo: xml-add-element  ·  Paquete: XML Activities v1.1.1  ·  Salida: string

Agrega un elemento hijo nuevo al primer nodo que coincide con un XPath, y devuelve el XML modificado. Úsala para construir o ampliar un documento XML: agregar una línea a una factura, un campo a un registro.

Cómo funciona

Localiza el elemento padre con xpath (la primera coincidencia), crea dentro un elemento hijo llamado elementName (con elementValue y attributes opcionales) al final de sus hijos y devuelve el XML modificado como string. Guárdalo con Write XML.

• Cada ejecución agrega un elemento nuevo: si la repites, el hijo queda duplicado.
• Los valores de attributes se escriben como texto; un valor null deja el atributo vacío ("").
• El XML devuelto lleva sangría y no incluye la declaración <?xml …?>; Write XML la escribe al guardar.

Con namespaces:

• elementName puede llevar prefijo: cbc:Note crea el elemento en el namespace de cbc y reutiliza la declaración del documento. Si el prefijo viene solo de namespaces, se declara en el elemento nuevo con ese mismo prefijo.
• Sin prefijo, el elemento toma el namespace por defecto del padre (no aparece un xmlns="" suelto).
• Las claves de attributes también aceptan prefijo (xsi:nil). Sin prefijo, un atributo no tiene namespace, como manda XML.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
xml	string	—	El texto XML.
xpath	string	—	XPath al elemento padre. Debe seleccionar un elemento.
elementName	string	—	Nombre del nuevo elemento, con prefijo de namespace si hace falta (cbc:Note).

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
elementValue	string	—	Contenido de texto del nuevo elemento. Sin valor, el elemento queda vacío (<Nota />).
attributes	Dictionary	—	Atributos del nuevo elemento (nombre → valor), p. ej. dictSet(newDict(), "tipo", "interna"). Un valor que no sea diccionario se ignora.
namespaces	Dictionary	—	Prefijos extra o que reemplazan a los del documento (prefijo → URI), para el XPath y para los nombres con prefijo. Desde la versión 1.1.0.
defaultPrefix	string	"d"	Prefijo con que se escribe en el XPath el namespace por defecto del documento (xmlns="…"). Vacío equivale a "d". Desde la versión 1.1.0.

Salida

Devuelve un string con el XML completo modificado.

Errores comunes

Mensaje	Causa y solución
Ningún nodo padre coincide con el XPath indicado.	El XPath no encuentra nada o selecciona algo que no es un elemento (un atributo, un valor). Si el documento tiene namespace por defecto, usa d: (el log te lo recuerda).
'…' no es un nombre XML válido.	elementName o una clave de attributes tiene espacios, empieza por número o lleva caracteres no admitidos.
El prefijo 'x:' no está declarado en el XML ni en 'namespaces'. Prefijos disponibles: ….	El prefijo del XPath, de elementName o de un atributo no existe. Defínelo en namespaces.
'xml' es obligatorio. / 'xpath' es obligatorio. / 'elementName' es obligatorio.	El parámetro quedó vacío o su expresión dio null.
La expresión XPath «…» no es válida: …	Ver Errores comunes del paquete.

Ejemplo

Agregar un campo <Observacion> dentro de <Factura>:

XML Add Element
  xml = xml
  xpath = "//Factura"
  elementName = "Observacion"
  elementValue = "Revisado automáticamente"
  attributes = dictSet(newDict(), "origen", "robot")
  → output: xmlNuevo
Write XML   path = ruta   content = xmlNuevo

Resultado dentro de <Factura>: <Observacion origen="robot">Revisado automáticamente</Observacion>.

En una factura UBL:

XML Add Element   xml = factura   xpath = "/d:Invoice"   elementName = "cbc:Note"   elementValue = "Revisada"   → output: facturaNueva

Actividades relacionadas

• XML Set Value — cambiar el valor de un elemento existente.
• Write XML — guardar el resultado.