Saltar al contenido

Funciones XML en Jitterbit Design 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");

[Back to top]

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")
    );

[Back to top]

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, haz doble clic en la carpeta del nodo XML deseado para insertar su ruta calificada en la ubicación del cursor. Para más información, consulta las instrucciones sobre inserción de rutas de nodos XML.

Ejemplos

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

[Back to top]

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 cualquiera de las funciones SelectNodeFromXMLAny o SelectSingleNode.

Para ingresar una ruta a un nodo en la función para el parámetro path, haz doble clic en la carpeta del nodo XML deseado para insertar su ruta calificada en la ubicación del cursor. Para más información, consulta las instrucciones sobre inserción de rutas de nodos XML.

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 name of the second child:

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

[Volver al inicio]

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 usa en una asignación del Generador de fórmulas) 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, haz doble clic en la carpeta del nodo XML deseado para insertar su ruta calificada en la ubicación del cursor. Para obtener más información, consulta las instrucciones sobre inserción de rutas de nodos XML.

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

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

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

[Volver al inicio]

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 usa en una asignación del Generador de fórmulas) 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, haz doble clic en la carpeta del nodo XML deseado para insertar su ruta calificada en la ubicación del cursor. Para obtener más información, consulta las instrucciones sobre inserción de rutas de nodos XML.

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 hoja de estilos XSLT
  • xml1...xmlN: 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.

Si tus 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 es compatible cuando se usan agentes 11.36 y posteriores.

Restricciones de entidad externa y DOCTYPE

Por defecto, los agentes versión 12.11 y posteriores 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.

Ejemplos

// Running XSLT on XML Files

// Read in a stylesheet
xslt = ReadFile("<TAG>Sources/XSLT</TAG>");

// Read in two XML files for processing
xml1 = ReadFile("<TAG>Sources/XML1</TAG>");
xml2 = ReadFile("<TAG>Sources/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>Targets/XML Output FTP</TAG>",
    output[i], "output" + (i+1) + ".xml");
  i++;
);

Conceptos específicos de Jitterbit

Usar una transformación XSLT existente

También es posible usar una transformación XSLT existente como primer argumento de RunXSLT(). Una transformación XSLT se define como una entidad separada del script y puede reutilizarse en múltiples scripts y operaciones de transformación XSLT. Debe ser una transformación XSLT definida en el proyecto actual. Consulta las instrucciones sobre insertar elementos del proyecto.

// Runs an existing XSLT Transform, passing values
// using variables customers, salesPeople, salesOrders
mergedOut = RunXSLT("<TAG>XSLT Transforms/Merge Transform</TAG>",
    customers, salesPeople, salesOrders);

Hacer 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 a través del uso de orígenes y destinos definidos 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.

Para este ejemplo, dado el ejemplo anterior de procesamiento de tres archivos XML (customers, salesPeople, salesOrders), podrías hacer referencia a ellos en una hoja de estilos XSLT usando:

<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 usar la sintaxis doc('param1') ya que Jitterbit establecerá el contexto inicial en ese archivo único.

Especificar 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="/">

[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 un arreglo 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 coinciden con el nombre del nodo.

Para ingresar una ruta a un arreglo de nodos XML en la función para el parámetro anyNodes, haz doble clic en la carpeta de nodo XML deseada para insertar su ruta calificada en la ubicación del cursor. Para más información, consulta las instrucciones sobre insertar rutas de nodos XML.

Ejemplos

// Busca el primer nodo que coincida con "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, haz doble clic en la carpeta del nodo XML deseado para insertar su ruta calificada en la ubicación del cursor. Para obtener más información, consulta las instrucciones sobre inserción de rutas de nodos XML.

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í.

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

[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, 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 una matriz de nodos XML en la función para el parámetro anyNodes, haz doble clic en la carpeta del nodo XML deseado para insertar su ruta calificada en la ubicación del cursor. Para obtener más información, consulta las instrucciones sobre inserción de rutas de nodos XML.

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, los prefijos deben especificarse como uno o más argumentos de cadena después de XPath (consulta el segundo ejemplo).

Para introducir una ruta a un nodo en la función para el parámetro node, haz doble clic en la carpeta del nodo XML deseado para insertar su ruta calificada en la ubicación del cursor. Para obtener más información, consulta las instrucciones sobre inserción de rutas de nodos XML.

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 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/");

[Volver al inicio]