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 el acceso a 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. Ver también la función CreateNode.

Ejemplos

// Agrega un atributo "name" con un valor de "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 sub-nodo

Parámetros opcionales

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

Descripción

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

A partir del tercer argumento, se puede especificar una serie de valores, atributos y sub-nodos. Los valores se especifican directamente. Los atributos y sub-nodos 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 solo 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 del nodo XML deseado desde la pestaña Objetos de origen de la paleta del componente de script al script para insertar su ruta calificada en la ubicación de tu cursor, o ingresa su ruta de referencia manualmente. Para más información, consulta las instrucciones sobre inserción de objetos de origen.

Ejemplos

// Recupera el nombre de un nodo
GetNodeName(SelectNodeFromXMLAny("Account", Root$Any.));

[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 solo 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, arrastra y suelta la carpeta del nodo XML deseado desde la pestaña Objetos de origen de la paleta del componente de script al script para insertar su ruta calificada en la ubicación de tu cursor, o ingresa su ruta de referencia manualmente. Para más información, consulta las instrucciones sobre inserción de objetos de origen.

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
// Recupera 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 solo 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 (por defecto false); cuando es calificado (true), la cadena XML devuelta es más fácil de leer, pero puede no ser válida XML por sí sola.

Descripción

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

Para ingresar una ruta a un nodo en la función para el parámetro path, arrastra y suelta la carpeta del nodo XML deseado desde la pestaña Objetos de origen del panel de componentes de script al script para insertar su ruta calificada en la ubicación de tu 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$]);

[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 solo nodo en la transformación actual

Descripción

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

Para ingresar una ruta a un nodo en la función para el parámetro path, arrastra y suelta la carpeta del nodo XML deseado desde la pestaña Objetos de Origen de la paleta del componente de script al script para insertar su ruta calificada en la ubicación de tu 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 punto final de tipo archivo en el proyecto actual que devuelve una hoja de estilo XSLT
  • xml1...xmlN: Una ruta de referencia de cadena a una actividad asociada con un punto final de tipo archivo en el proyecto actual que devuelve uno o más documentos XML

Descripción

Admite la ejecución de XSLT (v1-3) en varios documentos XML de entrada. Toma como entrada una hoja de estilo XSLT y uno o más documentos XML y devuelve un arreglo de documentos XML.

El parámetro xslt utilizado en esta llamada a función debe definirse como una actividad asociada con un punto final de tipo archivo en el proyecto actual que devuelva una hoja de estilo XSLT. Los parámetros xml1...xmlN utilizados en esta llamada a función deben definirse como una o más actividades asociadas con puntos finales de tipo archivo en el proyecto actual que devuelvan uno o más documentos XML. Estos incluyen actividades configuradas de Compartición de Archivos, FTP, HTTP, Almacenamiento Local y Almacenamiento Temporal. Para más información, consulta las instrucciones sobre inserción de puntos finales.

Si tus hojas de estilo XSLT contienen instancias de JSON anidado incrustado que necesitan ser preservadas, establece la variable jitterbit.transformation.ignore_default_value en true antes de esta función. Esta variable es compatible al usar agentes 11.36 y posteriores.

Referencia a archivos desde dentro de una hoja de estilo XSLT

Si bien Jitterbit tiene un 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 debe ser siempre a través del uso de actividades definidas en el mismo proyecto.

Para hacer referencia a estos archivos o URIs en una hoja de estilo, utiliza la función XLST 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 referirte a ellos en una hoja de estilo 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 solo archivo XML de entrada, no es necesario usar la sintaxis doc('param1') ya que Jitterbit establecerá el contexto inicial en ese único archivo.

Especificando una plantilla de inicio en la hoja de estilos

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

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

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 arriba]

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, arrastra y suelta la carpeta del nodo XML deseado desde la pestaña Objetos de origen de la paleta del componente de script al script para insertar su ruta calificada en la ubicación de tu cursor, o ingresa su ruta de referencia manualmente. Para más información, consulta las instrucciones sobre insertar objetos de origen.

Ejemplos

// Busca el primer nodo que coincide con "Account"
SelectNodeFromXMLAny("Account", Root$Any#.);

[Volver arriba]

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 sobre el cual 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 (ver el estándar XPath, v1-v3) sobre un fragmento XML o un nodo XML devuelto de 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 la XPath (ver el segundo ejemplo).

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

Para soportar caracteres HTML, establece jitterbit.decode.html.chars en true antes de esta función. Esta variable es compatible con datos de cadena al usar 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í.

Desde que los prefijos ns1 y ns2 se utilizan en la consulta XPath, se definen como argumentos adicionales después de la 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 un arreglo 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 un arreglo de todos los nodos XML que son coincidentes con una consulta XPath (ver el estándar XPath, v1-v3) ejecutada contra una ruta de un nodo de valor de un elemento XML Any o un arreglo 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 la XPath (ver el segundo ejemplo).

Para ingresar una ruta a un arreglo de nodos XML en la función para el parámetro anyNodes, arrastre y suelte la carpeta de nodo XML deseada desde la pestaña Objetos de origen del panel de componentes de script al script para insertar su ruta calificada en la ubicación de su cursor, o ingrese su ruta de referencia manualmente. Para más información, consulte las instrucciones sobre insertar objetos de origen.

Ejemplos

Ejemplo 1
// Seleccionar todos los nodos con los nombres dados
SelectNodesFromXMLAny("Account|Customer|Name", Root$Any#.);
Ejemplo 2
// Seleccionar solo direcciones de correo electrónico y números de teléfono
$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 sobre el cual 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 (ver el estándar XPath, v1-v3) sobre un fragmento XML o un nodo XML devuelto de 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 del XPath (ver el segundo ejemplo).

Para ingresar una ruta a un nodo en la función para el parámetro node, arrastre y suelte la carpeta del nodo XML deseado desde la pestaña Objetos de origen de la paleta del componente de script al script para insertar su ruta calificada en la ubicación de su cursor, o ingrese su ruta de referencia manualmente. Para más información, consulte las instrucciones sobre insertar objetos de origen.

Para soportar caracteres HTML, establezca jitterbit.decode.html.chars en true antes de esta función. Esta variable es compatible con datos de cadena al usar 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]