Ir para o conteúdo

Funções XML

Funções XML são normalmente usadas em scripts de mapeamento de transformação que exigem a manipulação e o acesso de 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. Veja também o CreateNodefunção.

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 sub-nó), 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 nó nodeName e nodeValue será criado.

A partir do terceiro argumento, uma série de valores, atributos e subnós podem ser especificados. Os valores são especificados diretamente. Atributos e subnós podem ser criados com o Attribute e CreateNode funções 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 qualquer um dos SelectNodeFromXMLAnyouselectSingleNodefunções.

Para inserir um caminho para um nó na função para o path parâmetro, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado no local do seu cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

Exemplos

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

[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 qualquer um dos SelectNodeFromXMLAnyouselectSingleNodefunções.

Para inserir um caminho para um nó na função para o path parâmetro, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado no local do seu cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

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
// Retrieves the value of a node
GetNodeValue(SelectNodeFromXMLAny("Account", Root$Any.));

[Voltar ao topo]

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 XML válida por si só

Descrição

Retorna (quando usado em um mapeamento do Formula Builder) a string XML correspondente encontrada no documento XML de origem no caminho especificado.

Para inserir um caminho para um nó na função para o path parâmetro, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado no local do seu cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

Nota

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

Exemplos

// Retrieves the corresponding XML string at the specified path
GetXMLString([Header$DETAIL.]);

// Retrieves the corresponding XML string at the specified path
GetXMLString([root$transaction.response$body$queryResponse$result$records.Case$Account$]);

[Voltar ao topo]

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 tiver o atributo "xsi:nil"com o valor de true(ou 1).

Para inserir um caminho para um nó na função para o path parâmetro, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado no local do seu cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

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

Exemplos

// Returns if the node is 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 folha de estilo XSLT
  • xml1...xmlN: Um ou mais documentos XML

Descrição

Suporta a execução de XSLT (v1-3) em vários documentos XML de entrada. Recebe como entrada uma folha de estilo XSLT e um ou mais documentos XML e retorna uma matriz de documentos XML.

Exemplos

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

Conceitos Específicos do Jitterbit

Usando uma Transformação XSLt Existente

Também é possível usar uma transformação XLST existente como o primeiro argumento para RunXSLT(). Uma Transformação XLST é definida como uma entidade separada do script e pode ser reutilizada em vários scripts e operações de Transformação XLST. Esta deve ser uma Transformação XLST definida no projeto atual. Veja as instruções em inserir itens do projeto.

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

Referindo-se a Arquivos de Dentro de uma Folha de Estilo XSLt

Embora o Jitterbit tenha amplo suporte para XSLT, projetos que usam XSLT devem seguir regras para passar pelos padrões de segurança. Essas regras significam que o acesso a arquivos ou URIs deve sempre ser por meio do uso de fontes e alvos definidos no mesmo projeto.

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

Para este exemplo, dado o exemplo anterior de processamento de três arquivos XML (customers, salesPeople, salesOrders), você pode se referir a eles em uma folha de estilo XSLT usando:

<xsl:for-each select="doc('param1')/*:Customers/*:SalesOrder[customer_external_id!=''][id_externo_do_vendedor!='']">
...
<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!=''][id_externo_do_vendedor!='']">

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

Especificando um Modelo Inicial na Folha de Estilo

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

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

[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 Qualquer elemento, 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 anyNodes parâmetro, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado no local do seu cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

Exemplos

// Looks for the first node that matches "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 consultar 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 especificando os namespaces dos nós na consultar XPath

Descrição

Executa uma consultar XPath (veja 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 consultar.

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

Para inserir um caminho para um nó na função para o node parâmetro, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado no local do seu cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

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

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 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>"}
Example 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>"}
Example 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" );
Example 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 consultar XPath, ns1:E2não é o nó de referência em si.

Já que os prefixos ns1 e ns2 são usados na consultar XPath, eles são definidos como argumentos adicionais após o XPath.

[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 consultar XPath
  • anyNodes: O caminho do elemento de dados de um nó de valor de um XML Qualquer elemento, uma expressão de caminho de referência de string para uma matriz de nós XML na transformação atual ou XML bruto

Parâmetros Opcionais

  • xPathArg1...xPathArgN: Prefixos especificando os namespaces dos nós na consultar XPath

Descrição

Retorna uma matriz de todos os nós XML que são correspondidos por uma consultar XPath (consulte o padrão XPath, v1-v3) executado em um caminho de um nó de valor de um elemento XML ou em uma matriz de nós XML.

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

Para inserir um caminho para uma matriz de nós XML na função para o anyNodes parâmetro, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado no local do seu cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

Exemplos

Example 1
// Select all the nodes with the given names
SelectNodesFromXMLAny("Account|Customer|Name", Root$Any#.);
Example 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 consultar 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 especificando os namespaces dos nós na consultar XPath

Descrição

Executa uma consultar XPath (veja 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 consultar.

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

Para inserir um caminho para um nó na função para o node parâmetro, clique duas vezes na pasta do nó XML desejado para inserir seu caminho qualificado no local do seu cursor. Para obter mais informações, consulte as instruções em inserir caminhos de nó XML.

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

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 first matching node given an XPath query:

SelectSingleNode(xmlInput, "/root/father/child");
// Returns <child> <name>John Smith</name> <age>20</age> </child>
Example 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");
Example 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/");

[Voltar ao topo]