Ir para o conteúdo

Funções XML no Jitterbit Studio

As funções XML são normalmente usadas em scripts de mapeamento de transformação que exigem manipulação e acesso a dados XML.

Attribute

Declaração

type Attribute(string attributeName, string attributeValue)

Sintaxe

Attribute(<attributeName>, <attributeValue>)

Parâmetros obrigatórios

  • attributeName: Nome do atributo
  • attributeValue: Valor do atributo

Descrição

Cria um atributo para um nó XML. Consulte também a função CreateNode.

Exemplos

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

[Voltar ao topo]

CreateNode

Declaração

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

Sintaxe

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

Parâmetros obrigatórios

  • namespace: O namespace do nó
  • nodeName: Nome do nó
  • attributeSubelement: Um subelemento: um valor, atributo ou subnó

Parâmetros opcionais

  • attributeSubelement: Subelementos adicionais (um valor, atributo ou subnó), conforme necessário

Descrição

Cria uma string representando um nó XML. Se o nó de destino for o nó de valor de um nó XML Any, um elemento XML correspondente ao nodeName e nodeValue será criado.

A partir do terceiro argumento, é possível especificar uma série de valores, atributos e subnós. Os valores são especificados diretamente. Atributos e subnós podem ser criados com as funções Attribute e CreateNode respectivamente.

Exemplos

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

[Voltar ao topo]

GetNodeName

Declaração

string GetNodeName(type path)

Sintaxe

GetNodeName(<path>)

Parâmetros obrigatórios

  • path: Uma expressão de caminho de referência de string que seleciona um único nó na transformação atual ou XML bruto

Descrição

Recupera o nome de um nó. Este método é normalmente usado para recuperar o nome de um nó retornado por uma das funções SelectNodeFromXMLAny ou SelectSingleNode.

Para inserir um caminho para um nó na função do parâmetro path, arraste e solte a pasta do nó XML desejada da aba Objetos de Origem da paleta de componentes de script para o script a fim de inserir seu caminho qualificado no local do cursor, ou insira seu caminho de referência manualmente. Para mais informações, consulte as instruções sobre inserção de objetos de origem.

Exemplos

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

Veja na prática

  • Rotear mensagens XML por tipo de nó: Combinando GetNodeName com SelectSingleNode para ler qual de vários tipos de mensagem uma carga contém e, em seguida, rotear para a operação correspondente.

[Voltar ao topo]

GetNodeValue

Declaração

string GetNodeValue(type path)

Sintaxe

GetNodeValue(<path>)

Parâmetros obrigatórios

  • path: Uma expressão de caminho de referência de string que seleciona um único nó na transformação atual ou XML bruto

Descrição

Recupera o valor de um nó. Este método é normalmente usado para recuperar o valor de um nó retornado por uma das funções SelectNodeFromXMLAny ou SelectSingleNode.

Para inserir um caminho para um nó na função do parâmetro path, arraste e solte a pasta de nó XML desejada da aba Source Objects (Objetos de Origem) da paleta de componentes de script para o script a fim de inserir seu caminho qualificado no local do cursor, ou insira seu caminho de referência manualmente. Para mais informações, consulte as instruções em inserting source objects.

Exemplos

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 o valor de um nó
GetNodeValue(SelectNodeFromXMLAny("Account", Root$Any.));

[Back to top]

GetXMLString

Declaração

string GetXMLString(type path[, bool qualified])

Sintaxe

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

Parâmetros obrigatórios

  • path: Uma expressão de caminho de referência de string que seleciona um único nó na transformação atual. O caminho definido deve ser para um nó; campos e atributos específicos são ignorados durante a avaliação do caminho

Parâmetros opcionais

  • qualified: Um valor booleano (padrão false); quando qualificado (true), a string XML retornada é mais fácil de ler, mas pode não ser um XML válido por si só

Descrição

Retorna (quando usado em um mapeamento de transformação) a string XML correspondente encontrada no documento XML de origem no caminho especificado.

Para inserir um caminho para um nó na função do parâmetro path, arraste e solte a pasta de nó XML desejada da aba Source Objects (Objetos de Origem) da paleta de componentes de script para o script a fim de inserir seu caminho qualificado no local do cursor, ou insira seu caminho de referência manualmente. Para mais informações, consulte as instruções em inserting source objects.

Nota

O caminho definido deve ser para um nó; campos e atributos específicos são ignorados durante a avaliação do caminho.

Exemplos

// Recupera a string XML correspondente no caminho especificado
GetXMLString([Header$DETAIL.]);

// Recupera a string XML correspondente no caminho especificado
GetXMLString([root$transaction.response$body$queryResponse$result$records.Case$Account$]);

[Back to top]

IsNil

Declaração

bool IsNil(string path)

Sintaxe

IsNil(<path>)

Parâmetros obrigatórios

  • path: Uma expressão de caminho de referência de string que seleciona um único nó na transformação atual

Descrição

Retorna (quando usado em um mapeamento do Formula Builder) se o nó XML correspondente possui o atributo "xsi:nil" com o valor true (ou 1).

Para inserir um caminho para um nó na função do parâmetro path, arraste e solte a pasta de nó XML desejada da aba Source Objects (Objetos de Origem) da paleta de componentes de script para o script a fim de inserir seu caminho qualificado no local do cursor, ou insira seu caminho de referência manualmente. Para mais informações, consulte as instruções em inserting source objects.

Conforme descrito em XML Schema, um elemento pode ser válido sem conteúdo se possuir o atributo xsi:nil com o valor true.

Exemplos

// Retorna se o nó é nil
IsNil("Header$DETAIL.");

[Voltar ao topo]

RunXSLT

Declaração

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

Sintaxe

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

Parâmetros obrigatórios

  • xslt: Uma referência de caminho de string para uma atividade associada a um endpoint do tipo arquivo no projeto atual que retorna uma folha de estilos XSLT
  • xml1...xmlN: Uma referência de caminho de string para uma atividade associada a um endpoint do tipo arquivo no projeto atual que retorna um ou mais documentos XML

Descrição

Oferece suporte à execução de XSLT (v1-3) em vários documentos XML de entrada. Recebe como entrada uma folha de estilos XSLT e um ou mais documentos XML e retorna um array de documentos XML.

O parâmetro xslt usado nesta chamada de função deve ser definido como uma atividade associada a um endpoint do tipo arquivo no projeto atual que retorna uma folha de estilos XSLT. Os parâmetros xml1...xmlN usados nesta chamada de função devem ser definidos como uma ou mais atividades associadas a endpoints do tipo arquivo no projeto atual que retornam um ou mais documentos XML. Isso inclui atividades configuradas de Compartilhamento de Arquivos, FTP, HTTP, Armazenamento Local e Armazenamento Temporário. Para mais informações, consulte as instruções sobre inserção de endpoints.

Se suas folhas de estilos XSLT contiverem instâncias de JSON aninhado incorporado que precisem ser preservadas, defina a variável jitterbit.transformation.ignore_default_value como true antes desta função. Esta variável é compatível ao usar agentes versão 11.36 e posteriores.

Restrições de entidade externa e DOCTYPE

Por padrão, agentes versão 12.11 e posteriores bloqueiam entrada XML para esta função que contenha uma declaração DOCTYPE ou uma referência de entidade externa, por motivos de segurança. Para permitir este processamento, atualize a chave correspondente na seção [XsltEngine] do arquivo de configuração do agente (jitterbit.conf), depois reinicie o agente.

Referenciando arquivos de dentro de uma folha de estilos XSLT

Embora o Jitterbit tenha amplo suporte para XSLT, projetos que usam XSLT devem seguir regras para atender aos padrões de segurança. Essas regras significam que o acesso a arquivos ou URIs deve sempre ser através do uso de atividades definidas no mesmo projeto.

Para referenciar esses arquivos ou URIs em uma folha de estilos, use a função XSLT fn:doc e especifique 'param1' para a primeira entrada XML, 'param2' para a segunda entrada XML e assim por diante para cada arquivo XML adicional.

Dado o exemplo de processamento de três arquivos XML (customers, salesPeople, salesOrders), você poderia referenciá-los em uma folha 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!='']">

Se você tiver um único arquivo XML de entrada, não é necessário usar a sintaxe doc('param1') pois o Jitterbit definirá o contexto inicial para esse arquivo único.

Especificando um template inicial na folha de estilos

Em algumas situações, o Jitterbit precisa saber onde em uma folha de estilos começar o processamento. Isso é feito incluindo na folha de estilos um template com o nome específico start_here:

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

Para solução de problemas, consulte RunXSLT falha com "XML version must be 1.0 or 1.1" no guia de solução de problemas de operação.

Exemplos

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

[Voltar ao topo]

SelectNodeFromXMLAny

Declaração

type SelectNodeFromXMLAny(string nodeName, type anyNodes)

Sintaxe

SelectNodeFromXMLAny(<nodeName>, <anyNodes>)

Parâmetros obrigatórios

  • nodeName: O nome do nó desejado
  • anyNodes: O caminho do elemento de dados de um nó de valor de um elemento XML Any, uma expressão de caminho de referência de string para uma matriz de nós XML na transformação atual, ou XML bruto

Descrição

Retorna o primeiro nó XML de uma lista de nós XML Any que correspondem ao nome do nó.

Para inserir um caminho para uma matriz de nós XML na função para o parâmetro anyNodes, arraste e solte a pasta de nó XML desejada da aba Source Objects (Objetos de Origem) da paleta de componentes de script para o script a fim de inserir seu caminho qualificado no local do cursor, ou insira seu caminho de referência manualmente. Para mais informações, consulte as instruções sobre inserção de objetos de origem.

Exemplos

// Procura pelo primeiro nó que corresponde a "Account"
SelectNodeFromXMLAny("Account", Root$Any#.);

[Voltar ao topo]

SelectNodes

Declaração

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

Sintaxe

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

Parâmetros obrigatórios

  • node: Uma expressão de caminho de referência de string para o nó desejado na transformação atual, um fragmento XML para executar a consulta, ou XML bruto
  • xPathQuery: O caminho do elemento de dados de um nó de valor de um elemento XML Any

Parâmetros opcionais

  • xPathArg1...xPathArgN: Prefixos que especificam os namespaces dos nós na consulta XPath

Descrição

Executa uma consulta XPath (consulte o padrão XPath, v1-v3) em um fragmento XML ou em um nó XML retornado de outra função, e retorna os resultados da consulta.

Se os prefixos opcionais forem usados para especificar os namespaces do nó na consulta XPath, os prefixos devem ser especificados como um ou mais argumentos de string após o XPath (consulte o segundo exemplo).

Para inserir um caminho para um nó na função para o parâmetro node, arraste e solte a pasta de nó XML desejada da aba Source Objects (Objetos de Origem) da paleta de componentes de script para o script a fim de inserir seu caminho qualificado no local do cursor, ou insira seu caminho de referência manualmente. Para mais informações, consulte as instruções sobre inserção de objetos de origem.

Para suportar caracteres HTML, defina jitterbit.decode.html.chars como true antes desta função. Esta variável é suportada com dados de string ao usar agentes versão 10.49 ou posterior.

Exemplos

Exemplo 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>"}
Exemplo 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>"}
Exemplo 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" );
Exemplo 4
SelectNodes(Root$Any$,
    "ns1:E2/ns2:E3",
    "ns1=http://xyz1.example.com/",
    "ns2=http://xyz2.example.com/");

Nota

Neste segundo exemplo, o nó de referência é um nó XML para um nó XML Any. Na consulta XPath, ns1:E2 não é o próprio nó de referência.

Como os prefixos ns1 e ns2 são usados na consulta XPath, eles são definidos como argumentos adicionais após o XPath.

Veja na prática

  • Rotear mensagens XML por tipo de nó: Testando se um nó está presente contando os resultados de uma consulta SelectNodes com Length, incluindo como lidar com uma carga útil com namespace.

[Voltar ao topo]

SelectNodesFromXMLAny

Declaração

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

Sintaxe

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

Parâmetros obrigatórios

  • xPathQuery: Uma consulta XPath
  • anyNodes: O caminho do elemento de dados de um nó de valor de um elemento XML Any, uma expressão de caminho de referência de string para um array de nós XML na transformação atual, ou XML bruto

Parâmetros opcionais

  • xPathArg1...xPathArgN: Prefixos que especificam os namespaces dos nós na consulta XPath

Descrição

Retorna um array de todos os nós XML que correspondem a uma consulta XPath (consulte o padrão XPath, v1-v3) executada em um caminho de um nó de valor de um elemento XML Any ou em um array de nós XML.

Se os prefixos opcionais forem usados para especificar os namespaces do nó na consulta XPath, os prefixos devem ser especificados como um ou mais argumentos de string após o XPath (consulte o segundo exemplo).

Para inserir um caminho para um array de nós XML na função para o parâmetro anyNodes, arraste e solte a pasta de nó XML desejada da aba Source Objects (Objetos de Origem) da paleta de componentes de script para o script a fim de inserir seu caminho qualificado no local do cursor, ou insira seu caminho de referência manualmente. Para mais informações, consulte as instruções sobre inserção de objetos de origem.

Exemplos

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

[Voltar ao topo]

SelectSingleNode

Declaração

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

Sintaxe

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

Parâmetros obrigatórios

  • node: Uma expressão de caminho de referência de string para o nó desejado na transformação atual, um fragmento XML para executar a consulta, ou XML bruto

  • xPathQuery: O caminho do elemento de dados de um nó de valor de um elemento XML Any

Parâmetros opcionais

  • xPathArg1...xPathArgN: Prefixos que especificam os namespaces dos nós na consulta XPath

Descrição

Executa uma consulta XPath (consulte o padrão XPath, v1-v3) em um fragmento XML ou em um nó XML retornado de outra função, e retorna o primeiro nó nos resultados da consulta.

Se os prefixos opcionais forem usados para especificar os namespaces do nó na consulta XPath, os prefixos devem ser especificados como um ou mais argumentos de string após o XPath (consulte o segundo exemplo).

Para inserir um caminho para um nó na função para o parâmetro node, arraste e solte a pasta de nó XML desejada da aba Source Objects (Objetos de Origem) da paleta de componentes de script para o script a fim de inserir seu caminho qualificado no local do cursor, ou insira seu caminho de referência manualmente. Para mais informações, consulte as instruções sobre inserção de objetos de origem.

Para suportar caracteres HTML, defina jitterbit.decode.html.chars como true antes desta função. Esta variável é suportada com dados de string ao usar agentes 10.49 e posteriores.

Para solucionar problemas, consulte SelectSingleNode retorna o nó errado quando usado com um elemento de array SelectNodes no guia de solução de problemas de operação.

Exemplos

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

Veja na prática

[Voltar ao topo]