Saltar al contenido

Funciones XML en Jitterbit Studio

Las funciones XML se utilizan típicamente en scripts de mapeo de transformación que requieren la manipulación y acceso de datos XML.

Attribute

Declaración

type Attribute(string attributeName, string attributeValue)

Sintaxis

Attribute(<attributeName>, <attributeValue>)

Parámetros requeridos

  • attributeName: Nombre del atributo
  • attributeValue: Valor del atributo

Descripción

Crea un atributo para un nodo XML. Consulta también la función CreateNode.

Ejemplos

// Adds an attribute "name" with a value of "value"
Attribute("name","value");

[Volver al inicio]

CreateNode

Declaración

string CreateNode(string namespace, string nodeName, type attributeSubelement[,...])

Sintaxis

CreateNode(<namespace>, <nodeName>, <attributeSubelement>[,...])

Parámetros requeridos

  • namespace: El espacio de nombres del nodo
  • nodeName: Nombre del nodo
  • attributeSubelement: Un subelemento: un valor, atributo o subnodo

Parámetros opcionales

  • attributeSubelement: Subelementos adicionales (un valor, atributo o subnodo), según sea necesario

Descripción

Crea una cadena que representa un nodo XML. Si el nodo de destino es el nodo de valor de un nodo XML Any, se creará un elemento XML correspondiente a nodeName y nodeValue.

A partir del tercer argumento, se puede especificar una serie de valores, atributos y subnodos. Los valores se especifican directamente. Los atributos y subnodos se pueden crear con las funciones Attribute y CreateNode respectivamente.

Ejemplos

// Creates a node with a sub-node
CreateNode("http://example.com/xml",
    "Contact", "Bill  G.", Attribute("Type", "VIP"),
    CreateNode("http://example.com/xml",
        "Title", "Manager")
    );

[Volver al inicio]

GetNodeName

Declaración

string GetNodeName(type path)

Sintaxis

GetNodeName(<path>)

Parámetros requeridos

  • path: Una expresión de ruta de referencia de cadena que selecciona un único nodo en la transformación actual, o XML sin procesar

Descripción

Recupera el nombre de un nodo. Este método se utiliza típicamente para recuperar el nombre de un nodo devuelto por cualquiera de las funciones SelectNodeFromXMLAny o SelectSingleNode.

Para ingresar una ruta a un nodo en la función para el parámetro path, arrastra y suelta la carpeta de nodo XML deseada desde la pestaña Source Objects de la paleta de componentes de script al script para insertar su ruta calificada en la ubicación del cursor, o ingresa su ruta de referencia manualmente. Para más información, consulta las instrucciones sobre inserción de objetos de origen.

Ejemplos

// Retrieves the name of a node
GetNodeName(SelectNodeFromXMLAny("Account", Root$Any.));

Véalo en la práctica

  • Enrutar mensajes XML por tipo de nodo: Emparejamiento de GetNodeName con SelectSingleNode para leer qué tipo de mensaje contiene una carga útil, luego enrutarla a la operación correspondiente.

[Volver al inicio]

GetNodeValue

Declaración

string GetNodeValue(type path)

Sintaxis

GetNodeValue(<path>)

Parámetros requeridos

  • path: Una expresión de ruta de referencia de cadena que selecciona un único nodo en la transformación actual, o XML sin procesar

Descripción

Recupera el valor de un nodo. Este método se utiliza típicamente para recuperar el valor de un nodo devuelto por las funciones SelectNodeFromXMLAny o SelectSingleNode.

Para ingresar una ruta a un nodo en la función del parámetro path, arrastra y suelta la carpeta de nodo XML deseada desde la pestaña Source Objects de la paleta de componentes de script al script para insertar su ruta calificada en la ubicación del cursor, o ingresa su ruta de referencia manualmente. Para más información, consulta las instrucciones sobre insertar objetos de origen.

Ejemplos

Example 1
// XML definition
xmlInput = '<?xml version="1.0" encoding="UTF-8"?>
<root>
    <father>
        <child>
            <name>John Smith</name>
            <age>20</age>
        </child>
        <child>
            <name>Jordan Coleman</name>
            <age>32</age>
        </child>
        <child>
            <name>Joel Parker</name>
            <age>54</age>
        </child>
        <child>
            <name>Roger Wright</name>
            <age>28</age>
        </child>
    </father>
</root>';

// Retrieve the name of the second child:

exampleArray = GetNodeValue(SelectNodes(xmlInput, "/root/father/child[position() = 2]/name"));
result = exampleArray[0];
// Equals "Jordan Coleman"
Example 2
// Recupera el valor de un nodo
GetNodeValue(SelectNodeFromXMLAny("Account", Root$Any.));

[Back to top]

GetXMLString

Declaración

string GetXMLString(type path[, bool qualified])

Sintaxis

GetXMLString(<path>[, <qualified>])

Parámetros requeridos

  • path: Una expresión de ruta de referencia de cadena que selecciona un único nodo en la transformación actual. La ruta definida debe ser para un nodo; los campos y atributos específicos se ignoran durante la evaluación de la ruta

Parámetros opcionales

  • qualified: Un valor booleano (predeterminado false); cuando está calificado (true), la cadena XML devuelta es más fácil de leer pero puede no ser XML válido por sí sola

Descripción

Devuelve (cuando se utiliza en un mapeo de transformación) la cadena XML correspondiente encontrada en el documento XML de origen en la ruta especificada.

Para ingresar una ruta a un nodo en la función del parámetro path, arrastra y suelta la carpeta de nodo XML deseada desde la pestaña Source Objects de la paleta de componentes de script al script para insertar su ruta calificada en la ubicación del cursor, o ingresa su ruta de referencia manualmente. Para más información, consulta las instrucciones sobre insertar objetos de origen.

Nota

La ruta definida debe ser para un nodo; los campos y atributos específicos se ignoran durante la evaluación de la ruta.

Ejemplos

// Recupera la cadena XML correspondiente en la ruta especificada
GetXMLString([Header$DETAIL.]);

// Recupera la cadena XML correspondiente en la ruta especificada
GetXMLString([root$transaction.response$body$queryResponse$result$records.Case$Account$]);

[Back to top]

IsNil

Declaración

bool IsNil(string path)

Sintaxis

IsNil(<path>)

Parámetros requeridos

  • path: Una expresión de ruta de referencia de cadena que selecciona un único nodo en la transformación actual

Descripción

Devuelve (cuando se utiliza en un mapeo de Formula Builder) si el nodo XML correspondiente tiene el atributo "xsi:nil" con el valor true (o 1).

Para ingresar una ruta a un nodo en la función del parámetro path, arrastra y suelta la carpeta de nodo XML deseada desde la pestaña Source Objects de la paleta de componentes de script al script para insertar su ruta calificada en la ubicación del cursor, o ingresa su ruta de referencia manualmente. Para más información, consulta las instrucciones sobre insertar objetos de origen.

Como se describe en XML Schema, un elemento puede ser válido sin contenido si tiene el atributo xsi:nil con el valor true.

Ejemplos

// Devuelve si el nodo es nil
IsNil("Header$DETAIL.");

[Volver al inicio]

RunXSLT

Declaración

array RunXSLT(string xslt, string xml1[, string xml2,... string xmlN)

Sintaxis

RunXSLT(<xslt>, <xml1>[, <xml2>,... <xmlN>])

Parámetros requeridos

  • xslt: Una ruta de referencia de cadena a una actividad asociada con un endpoint de tipo archivo en el proyecto actual que devuelve una hoja de estilos XSLT
  • xml1...xmlN: Una ruta de referencia de cadena a una actividad asociada con un endpoint de tipo archivo en el proyecto actual que devuelve uno o más documentos XML

Descripción

Permite ejecutar XSLT (v1-3) en varios documentos XML de entrada. Toma como entrada una hoja de estilos XSLT y uno o más documentos XML, y devuelve un arreglo de documentos XML.

El parámetro xslt utilizado en esta llamada de función debe definirse como una actividad asociada con un endpoint de tipo archivo en el proyecto actual que devuelve una hoja de estilos XSLT. Los parámetros xml1...xmlN utilizados en esta llamada de función deben definirse como una o más actividades asociadas con endpoints de tipo archivo en el proyecto actual que devuelven uno o más documentos XML. Esto incluye actividades configuradas de File Share, FTP, HTTP, Local Storage y Temporary Storage. Para obtener más información, consulta las instrucciones sobre inserción de endpoints.

Si las hojas de estilos XSLT contienen instancias de JSON anidado incrustado que necesita preservarse, establece la variable jitterbit.transformation.ignore_default_value en true antes de esta función. Esta variable se admite cuando se utilizan agentes versión 11.36 o posterior.

Restricciones de entidad externa y DOCTYPE

De forma predeterminada, los agentes versión 12.11 o posterior bloquean la entrada XML a esta función que contiene una declaración DOCTYPE o una referencia de entidad externa, por razones de seguridad. Para permitir este procesamiento, actualiza la clave correspondiente en la sección [XsltEngine] del archivo de configuración del agente (jitterbit.conf), luego reinicia el agente.

Referencia a archivos desde una hoja de estilos XSLT

Aunque Jitterbit tiene amplio soporte para XSLT, los proyectos que utilizan XSLT deben seguir reglas para cumplir con los estándares de seguridad. Estas reglas significan que el acceso a archivos o URIs siempre debe realizarse mediante el uso de actividades definidas en el mismo proyecto.

Para hacer referencia a estos archivos o URIs en una hoja de estilos, utiliza la función XSLT fn:doc y especifica 'param1' para la primera entrada XML, 'param2' para la segunda entrada XML, y así sucesivamente para cada archivo XML adicional.

Dado el ejemplo de procesar tres archivos XML (customers, salesPeople, salesOrders), podrías hacer referencia a ellos en una hoja de estilos XSLT utilizando:

<xsl:for-each select="doc('param1')/*:Customers/*:SalesOrder[customer_external_id!=''][sales_person_external_id!='']">
...
<xsl:for-each select="doc('param2')/*:SalesPeople/*:Account[*:customer_id/string(number(text()))=$CustomerExtId][1]">
...
<xsl:for-each select="doc('param3')/*:SalesOrders/*:SalesOrder[customer_external_id!=''][sales_person_external_id!='']">

Si tienes un único archivo XML de entrada, no es necesario utilizar la sintaxis doc('param1') ya que Jitterbit establecerá el contexto inicial en ese archivo único.

Especificación de una plantilla de inicio en la hoja de estilos

En algunas situaciones, Jitterbit necesita saber dónde comenzar el procesamiento en una hoja de estilos. Esto se logra incluyendo en la hoja de estilos una plantilla con el nombre específico start_here:

<xsl:template name="start_here" match="/">

Para solucionar problemas, consulta RunXSLT falla con "XML version must be 1.0 or 1.1" en la guía de solución de problemas de operaciones.

Ejemplos

// Running XSLT on XML Files

// Read in a stylesheet
xslt = ReadFile("<TAG>activity:ftp/FTP Endpoint/ftp_read/XSLT</TAG>");

// Read in two XML files for processing
xml1 = ReadFile("<TAG>activity:ftp/FTP Endpoint/ftp_read/XML1</TAG>");
xml2 = ReadFile("<TAG>activity:ftp/FTP Endpoint/ftp_read/XML2</TAG>");

// RunXSLT on the stylesheet and the two XML files
output = RunXSLT(xslt, xml1, xml2);

// As RunXSLT() returns an array,
// retrieve the output from each element
i = 0;
While(i < Length(output),
  // Write output to a file
  WriteFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/XML Output FTP</TAG>",
    output[i], "output" + (i+1) + ".xml");
  i++;
);

[Volver al inicio]

SelectNodeFromXMLAny

Declaración

type SelectNodeFromXMLAny(string nodeName, type anyNodes)

Sintaxis

SelectNodeFromXMLAny(<nodeName>, <anyNodes>)

Parámetros requeridos

  • nodeName: El nombre de nodo deseado
  • anyNodes: La ruta del elemento de datos de un nodo de valor de un elemento XML Any, una expresión de ruta de referencia de cadena a una matriz de nodos XML en la transformación actual, o XML sin procesar

Descripción

Devuelve el primer nodo XML de una lista de nodos XML Any que coincidan con el nombre del nodo.

Para ingresar una ruta a una matriz de nodos XML en la función para el parámetro anyNodes, arrastra y suelta la carpeta de nodo XML deseada desde la pestaña Source Objects (Objetos de origen) de la paleta de componentes de script al script para insertar su ruta calificada en la ubicación del cursor, o ingresa su ruta de referencia manualmente. Para obtener más información, consulta las instrucciones sobre inserción de objetos de origen.

Ejemplos

// Looks for the first node that matches "Account"
SelectNodeFromXMLAny("Account", Root$Any#.);

[Volver al inicio]

SelectNodes

Declaración

array SelectNodes(type node, string xPathQuery[, string xPathArg1,... string xPathArgN])

Sintaxis

SelectNodes(<node>, <xPathQuery>[, <xPathArg1>,... <xPathArgN>])

Parámetros requeridos

  • node: Una expresión de ruta de referencia de cadena al nodo deseado en la transformación actual, un fragmento XML en el que ejecutar la consulta, o XML sin procesar
  • xPathQuery: La ruta del elemento de datos de un nodo de valor de un elemento XML Any

Parámetros opcionales

  • xPathArg1...xPathArgN: Prefijos que especifican los espacios de nombres de los nodos en la consulta XPath

Descripción

Ejecuta una consulta XPath (consulta el estándar XPath, v1-v3) en un fragmento XML o en un nodo XML devuelto por otra función, y devuelve los resultados de la consulta.

Si se utilizan los prefijos opcionales para especificar los espacios de nombres del nodo en la consulta XPath, los prefijos deben especificarse como uno o más argumentos de cadena después de XPath (consulta el segundo ejemplo).

Para ingresar una ruta a un nodo en la función para el parámetro node, arrastra y suelta la carpeta de nodo XML deseada desde la pestaña Source Objects (Objetos de origen) de la paleta de componentes de script al script para insertar su ruta calificada en la ubicación del cursor, o ingresa su ruta de referencia manualmente. Para obtener más información, consulta las instrucciones sobre inserción de objetos de origen.

Para admitir caracteres HTML, establece jitterbit.decode.html.chars en true antes de esta función. Esta variable es compatible con datos de cadena cuando se utilizan agentes 10.49 y posteriores.

Ejemplos

Ejemplo 1
// XML definition
xmlInput = '<?xml version="1.0" encoding="UTF-8"?>
<root>
    <father>
        <child>
            <name>John Smith</name>
            <age>20</age>
        </child>
        <child>
            <name>Jordan Coleman</name>
            <age>32</age>
        </child>
        <child>
            <name>Joel Parker</name>
            <age>54</age>
        </child>
        <child>
            <name>Roger Wright</name>
            <age>28</age>
        </child>
    </father>
</root>';

// Retrieve all the XML nodes that match the XPath query:

SelectNodes(xmlInput, "/root/father/child");
// Returns {"<child> <name>John Smith</name> <age>20</age> </child>","<child> <name>Jordan Coleman</name> <age>32</age> </child>","<child> <name>Joel Parker</name> <age>54</age> </child>","<child> <name>Roger Wright</name> <age>28</age> </child>"}

// Retrieve a range of nodes using a position argument with the XPath query:

SelectNodes(xmlInput, "/root/father/child[position() > 2 and position() <= 4]");
// Returns {"<child> <name>Joel Parker</name> <age>54</age> </child>","<child> <name>Roger Wright</name> <age>28</age> </child>"}
Ejemplo 2
// XML definition with root namespace
xmlInput = '<?xml version="1.0" encoding="UTF-8"?>
<ns0:root xmlns:ns0="urn:ean.ucc:align:2">
    <father>
        <child>
            <name>John Smith</name>
            <age>20</age>
        </child>
        <child>
            <name>Jordan Coleman</name>
            <age>32</age>
        </child>
        <child>
            <name>Joel Parker</name>
            <age>54</age>
        </child>
        <child>
            <name>Roger Wright</name>
            <age>28</age>
        </child>
    </father>
</ns0:root>';

// Retrieve all the XML nodes that match the XPath query with a namespace considered:

SelectNodes(xmlInput, "/ns0:root/father/child", "ns0=urn:ean.ucc:align:2");
// Returns {"<child> <name>John Smith</name> <age>20</age> </child>","<child> <name>Jordan Coleman</name> <age>32</age> </child>","<child> <name>Joel Parker</name> <age>54</age> </child>","<child> <name>Roger Wright</name> <age>28</age> </child>"}
Ejemplo 3
// Connects to an LDAP server, runs a search,
// and then runs an XPath query on the results
LDAPConnect("directory.company.example.com","ghvwright","1LikesPe@ches",0);
searchResults = LDAPSearch("CN=Users,DC=company,DC=example,DC=com",
    "(&(objectCategory=person)(objectClass=user))", 1,
    "name", "whenCreated", "description", "telephoneNumber");
resultNodes = SelectNodes(searchResults,
    "/DirectoryResults/Entry[name='Administrator']/whenCreated" );
Ejemplo 4
SelectNodes(Root$Any$,
    "ns1:E2/ns2:E3",
    "ns1=http://xyz1.example.com/",
    "ns2=http://xyz2.example.com/");

Nota

En este segundo ejemplo, el nodo de referencia es un nodo XML para un nodo XML Any. En la consulta XPath, ns1:E2 no es el nodo de referencia en sí.

Dado que los prefijos ns1 y ns2 se utilizan en la consulta XPath, se definen como argumentos adicionales después de XPath.

Verlo en la práctica

  • Enrutar mensajes XML por tipo de nodo: Prueba si un nodo está presente contando los resultados de una consulta SelectNodes con Length, incluida la forma de manejar una carga útil con espacios de nombres.

[Volver al inicio]

SelectNodesFromXMLAny

Declaración

array SelectNodesFromXMLAny(string xPathQuery, type anyNodes[, string xPathArg1,... string xPathArgN])

Sintaxis

SelectNodesFromXMLAny(<xPathQuery>, <anyNodes>[, <xPathArg1>,... <xPathArgN>])

Parámetros requeridos

  • xPathQuery: Una consulta XPath
  • anyNodes: La ruta del elemento de datos de un nodo de valor de un elemento XML Any, una expresión de ruta de referencia de cadena a una matriz de nodos XML en la transformación actual, o XML sin procesar

Parámetros opcionales

  • xPathArg1...xPathArgN: Prefijos que especifican los espacios de nombres de los nodos en la consulta XPath

Descripción

Devuelve una matriz de todos los nodos XML que coinciden con una consulta XPath (consulta el estándar XPath, v1-v3) ejecutada en una ruta de un nodo de valor de un elemento XML Any o en una matriz de nodos XML.

Si se utilizan los prefijos opcionales para especificar los espacios de nombres del nodo en la consulta XPath, se deben especificar como uno o más argumentos de cadena después de XPath (consulta el segundo ejemplo).

Para ingresar una ruta a una matriz de nodos XML en la función para el parámetro anyNodes, arrastra y suelta la carpeta de nodos XML deseada desde la pestaña Objetos de origen de la paleta de componentes de script al script para insertar su ruta calificada en la ubicación del cursor, o ingresa su ruta de referencia manualmente. Para obtener más información, consulta las instrucciones sobre inserción de objetos de origen.

Ejemplos

Ejemplo 1
// Select all the nodes with the given names
SelectNodesFromXMLAny("Account|Customer|Name", Root$Any#.);
Ejemplo 2
// Select email addresses and phone numbers only
$nodes = SelectNodesFromXMLAny("cust:EmailAddress|cust:PhoneNumber",
    Customer$Any#., "cust=urn:xmlns:25hoursaday-com:customer");

[Volver al inicio]

SelectSingleNode

Declaración

type SelectSingleNode(type node, string xPath,...)

Sintaxis

SelectSingleNode(<node>, <xPath>,...)

Parámetros requeridos

  • node: Una expresión de ruta de referencia de cadena al nodo deseado en la transformación actual, un fragmento XML en el que ejecutar la consulta, o XML sin procesar

  • xPathQuery: La ruta del elemento de datos de un nodo de valor de un elemento XML Any

Parámetros opcionales

  • xPathArg1...xPathArgN: Prefijos que especifican los espacios de nombres de los nodos en la consulta XPath

Descripción

Ejecuta una consulta XPath (consulta el estándar XPath, v1-v3) en un fragmento XML o en un nodo XML devuelto por otra función, y devuelve el primer nodo en los resultados de la consulta.

Si se utilizan los prefijos opcionales para especificar los espacios de nombres del nodo en la consulta XPath, se deben especificar como uno o más argumentos de cadena después de XPath (consulta el segundo ejemplo).

Para ingresar una ruta a un nodo en la función para el parámetro node, arrastra y suelta la carpeta de nodos XML deseada desde la pestaña Objetos de origen de la paleta de componentes de script al script para insertar su ruta calificada en la ubicación del cursor, o ingresa su ruta de referencia manualmente. Para obtener más información, consulta las instrucciones sobre inserción de objetos de origen.

Para admitir caracteres HTML, establece jitterbit.decode.html.chars en true antes de esta función. Esta variable es compatible con datos de cadena cuando se utilizan agentes 10.49 y posteriores.

Para solucionar problemas, consulta SelectSingleNode devuelve el nodo incorrecto cuando se usa con un elemento de matriz SelectNodes en la guía de solución de problemas de operaciones.

Ejemplos

Ejemplo 1
// XML definition
xmlInput = '<?xml version="1.0" encoding="UTF-8"?>
<root>
    <father>
        <child>
            <name>John Smith</name>
            <age>20</age>
        </child>
        <child>
            <name>Jordan Coleman</name>
            <age>32</age>
        </child>
        <child>
            <name>Joel Parker</name>
            <age>54</age>
        </child>
        <child>
            <name>Roger Wright</name>
            <age>28</age>
        </child>
    </father>
</root>';

// Retrieve the first matching node given an XPath query:

SelectSingleNode(xmlInput, "/root/father/child");
// Returns <child> <name>John Smith</name> <age>20</age> </child>
Ejemplo 2
// Connects to an LDAP server, runs a search,
// runs an XPath query on the results, and
// selects the first node in the query results
LDAPConnect("directory.company.example.com", "ghvwright", "1LikesPe@ches", 0);
searchResults = LDAPSearch("CN=Users,DC=company,DC=example,DC=com",
    "(&(objectCategory=person)(objectClass=user))", 1, "name",
    "whenCreated", "description", "telephoneNumber");
resultNode = SelectSingleNode(searchResults,
    "/DirectoryResults/Entry[name='Administrator']/whenCreated");
Ejemplo 3
// Selects the first node in an XPath query result.
// The reference node is an XML node for an XML Any node.
// In the XPath query, "ns1:E2" is not the reference node itself.
// Since the prefixes ns1 and ns2 are used in the XPath query,
// they are defined as additional arguments after the XPath.
SelectSingleNode(Root$Any$,
    "ns1:E2/ns2:E3",
    "ns1=http://xyz1.example.com",
    "ns2=http://xyz2.example.com/");

Verlo en la práctica

[Volver al inicio]