Ir para o conteúdo

Funções de instância no Jitterbit Integration Studio

Introdução

Essas funções são destinadas ao uso em mapeamentos de transformação (ou scripts chamados durante mapeamentos), pois usam instâncias de elementos de dados (origens e destinos) encontrados nos mapeamentos.

Inserção de um hash para retornar um array

Nos casos em que um parâmetro de entrada obrigatório para uma função de instância é uma matriz, um símbolo de hash (#) pode ser inserido no caminho de referência de um elemento de dados para retornar uma matriz de dados em vez de um único campo.

Por exemplo:

SumString(_Root$customer.contact#.Email, ",", true);

No exemplo acima, o caminho do elemento de dados (_Root$customer.contact#.Email) é construído para retornar uma matriz de endereços de email (.Email) dentro de uma matriz de contatos (.contact). O # é inserido antes do conjunto de endereços de email (#.Email) para indicar que, em cada contato, pode haver uma matriz de endereços de email. Isso resulta em um mapeamento que percorre a matriz nos registros de contato, mas não percorre a matriz nos emails.

Este conceito também se aplica aos nós de loop em transformações. Para obter mais explicações sobre a sintaxe dos caminhos dos elementos de dados, consulte Notação de caminho de referência em Nós e campos.

Uso avançado

As funções de instância podem, em geral, ser aninhadas umas dentro das outras. À medida que são aninhadas, os resultados sobem na hierarquia e abrangem mais resultados. Essas funções podem retornar um único valor ou uma matriz de valores, dependendo do contexto em que são usadas.

Por exemplo, um Sum função que tem uma Count a função interna somará os resultados de cada invocação do Count função e produzir um total:

Sum(Count(_Root$customer.sales#.items#.ID));

Count

Declaração

int Count(type de)

int Count(array arr)

Sintaxe

Count(<de>)

Count(<arr>)

Parâmetros obrigatórios

  • de: (Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino
  • arr: (Segunda forma) Um array; todos os elementos do array devem ser do mesmo tipo

Descrição

Conta todas as instâncias de um elemento de dados em um nível hierárquico específico em uma origem ou destino, onde esse elemento de dados contém um valor válido (e não é nulo).

A função retorna um inteiro ou um array de instâncias, dependendo do contexto em que é chamada.

Exemplos

Suponha que um banco de dados contenha um campo "Quantidade" em uma tabela "Itens" que é filha de "CabeçalhoPO" (um pedido de compra) e que haja muitos itens dentro de um CabeçalhoPO. Então, esta instrução retorna o número de linhas de itens para um CabeçalhoPO específico que possuem valores na coluna Quantidade que não são nulos:

Count(POHeader.Items#.Quantity);

Neste caso, considere um arquivo de dados com múltiplas instâncias, com clientes que possuem vendas que possuem itens; e cada item possui um campo ID. Esta instrução contará quantos itens diferentes existem em cada venda e usará o Sum função para somar todos os itens devolvidos em cada venda; este será o número total de itens diferentes comprados:

Sum(Count(_Root$customer.sales#.items#.ID));

[Voltar ao topo]

CountSourceRecords

Declaração

int CountSourceRecords()

Sintaxe

CountSourceRecords()

Descrição

Retorna o número de instâncias de origem para um nó de destino, quando o nó de destino se refere a um pai de um campo de mapeamento.

Se o nó de destino não for um nó de loop, a função retornará 1. Veja também SourceInstanceCount função.

Nota

O modo de streaming de uma transformação Flat-to-Flat não seria afetado pelo uso desta função, enquanto o modo de streaming seria desativado para uma transformação_XML-to-Flat_.

Exemplos

Suponha uma origem com registros de cliente que tenham instâncias de vendas com instâncias de itens com um campo Tipo:

// This statement shows the instance count of a record compared
// to the total number of source records
"Record " + SourceInstanceCount() + " of " + CountSourceRecords();

[Voltar ao topo]

Exist

Declaração

bool Exist(type v, type de)

bool Exist(type v, array arr)

Sintaxe

Exist(<v>, <de>)

Exist(<v>, <arr>)

Parâmetros obrigatórios

  • v: Um valor a ser encontrado
  • de: (Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino
  • arr: (Segunda forma) Uma matriz; todos os elementos da matriz devem ser do mesmo tipo e ser do mesmo tipo que v

Descrição

Verifica a existência de um valor (v) em instâncias de um elemento de dados (de) ou uma matriz (arr) e retorna verdadeiro (ou falso) dependendo se for encontrado.

A função retorna um booleano ou um array de instâncias, dependendo do contexto em que é chamada.

Exemplos

Suponha uma origem com registros de cliente que tenham instâncias de vendas com instâncias de itens com um campo Tipo:

// Returns if true if the value "subscription" is
// found in any instances of a field "customer.sales.items.Type"
// at the level of "sales":
Exist("subscription",_Root$customer.sales.items#.Type);

// To test this at the next highest level of the hierarchy,
// at the level of the customer,
// enclose this in a nested "Exist", testing for "true":
Exist(true, Exist("subscription",_Root$customer.sales#.items#.Type));

// The last statement answers, at the customer level, if a customer
// has any items in any sales with a Type field equal to "subscription"

[Voltar ao topo]

FindByPos

Declaração

type FindByPos(int pos, type de)

type FindByPos(int pos, array arr)

Sintaxe

FindByPos(<pos>, <de>)

FindByPos(<pos>, <arr>)

Parâmetros obrigatórios

  • pos: O índice (de qual ocorrência; base 1) para recuperar o valor
  • de: (Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino; ou arr: (Segunda forma) Um array; todos os elementos do array devem ser do mesmo tipo

Descrição

Retorna o valor de um elemento de dados de uma instância que ocorre várias vezes. Também pode ser usado para retornar um elemento de uma matriz, de forma 1.

Se um número negativo for especificado para a ocorrência ou matriz, a contagem começará a partir da última linha ou elemento. Observe que o índice é de base 1.

Exemplos

// Assume a database has a child-parent relationship
// where for each parent the child occurs multiple times

// To retrieve the second child, use:
FindByPos(2, ParentTab.ChildTab#.Value$);

// To retrieve the last child, use:
FindByPos(-1, ParentTab.ChildTab#.Value$);

[Voltar ao topo]

FindValue

Declaração

type FindValue(type0 v, type1 de1, type2 de2)

Sintaxe

FindValue(<v>, <de1>, <de2>)

Parâmetros obrigatórios

  • v: Um valor a ser pesquisado
  • de1: Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino, a ser usado como uma correspondência
  • de2: Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino, a ser retornado se uma correspondência for encontrada.

Descrição

Pesquisa múltiplas instâncias de um elemento de dados (de1) procurando o valor especificado em v. Se a função encontrar o valor, ela retornará o valor no campo especificado no terceiro parâmetro (de2) para a instância encontrada. Se o valor não for encontrado, a função retornará nulo. Veja também HasKey função.

Exemplos

Esta instrução pesquisará as instâncias de B sob A e verificar o conteúdo de field1. Ele selecionará a primeira instância de B ele encontra onde field1 contém "ID", e então retornar o valor de field2 desse mesmo exemplo:

FindValue("ID", A.B#.field1, A.B#.field2);

Estas instruções mostram como implementar um teste de inclusão de um valor em um array. Ele busca um valor em um array e retorna verdadeiro se encontrado e falso se não encontrado. É o equivalente em array ao dicionário. HasKey função. Observe que duas instâncias do mesmo array são passadas para a função:

arr = {1, 2, 3};
value = 1;
t = (FindValue(value, arr, arr) == value);
// t will be 1 (true)

value = 4;
t = (FindValue(value, arr, arr) == value);
// t will be 0 (false)

[Voltar ao topo]

GetInstance

Declaração

type GetInstance()

Sintaxe

GetInstance()

Descrição

Esta função retorna o elemento de dados da instância que foi definido pela chamada de SetInstances função durante a geração do pai. Como alternativa a esta função, veja o ArgumentList função.

Exemplos

Suponha que um dos mapeamentos pais de uma transformação contenha estas instruções:

...
r1=DBLookupAll("<TAG>endpoint:database/My Database</TAG>",
    "SELECT key_name, key_value, key_type FROM key_values");
SetInstances("DETAILS", r1);

r2 = {"MS", "HP", "Apple"};
SetInstances("COMPANIES", r2);
...

No DETAILS nó de destino, podemos criar uma condição de mapeamento usando:

<trans>
GetInstance()["key_value"] != "";
// Same as GetInstance()[0] != ""
</trans>

Ou, em um dos atributos, o mapeamento pode conter:

<trans>
x=GetInstance();
x["key_name"] + "=" + x["key_value"];
// Same as x[0] + "=" + x[1]
</trans>

Em um dos atributos do COMPANIES nó de destino ou o próprio nó de destino, o mapeamento pode conter:

<trans>
GetInstance();
// This will return
// "MS" for the first instance
// "HP" for the second instance
// "Apple" for the third instance
</trans>

Exemplo visual e saída

Abaixo está um exemplo de configuração de esquema aplicando o acima r2 exemplo para um getInformationRequest nó de loop e um COMPANIES nó de loop de destino. DETAILS foi excluído por simplicidade.

Exemplo de SetInstances

O XML resultante se a saída for escrita diretamente após a transformação:

<?xml version="1.0" encoding="UTF-8"?>
<root xmlns="http://www.jitterbit.com/XsdFromWsdl" xmlns:ns="com.iex.tv.webservices.services.agentResourcesService" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <transaction>
        <body>
            <ns:getInformation>
                <ns:getInformationRequest>
                    <ns:COMPANIES>MS</ns:COMPANIES>
                    <ns:COMPANIES>HP</ns:COMPANIES>
                    <ns:COMPANIES>Apple</ns:COMPANIES>
                </ns:getInformationRequest>
            </ns:getInformation>
        </body>
    </transaction>
</root>

[Voltar ao topo]

Max

Declaração

type Max(type de)

type Max(array arr)

Sintaxe

Max(<de>)

Max(<arr>)

Parâmetros obrigatórios

  • de: (Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino
  • arr: (Segunda forma) Um array; todos os elementos do array devem ser do mesmo tipo

Descrição

Retorna o valor máximo de instâncias de um elemento de dados em um nível específico na hierarquia de uma estrutura de dados. Ele verifica todas as instâncias naquele nível e retorna a maior. Também pode ser usado para retornar o valor máximo de uma matriz.

Exemplos

Suponha que um banco de dados contenha um campo "Quantity" em uma mesa "Items" que é uma criança de "POHeader"(uma ordem de compra) e que há muitos itens dentro de um POHeader. Então, esta instrução retorna o valor máximo de Quantity para qualquer item de um POHeader específico:

Max(POHeader.Items#.Quantity);

[Voltar ao topo]

Min

Declaração

type Min(type de)

type Min(array arr)

Sintaxe

Min(<de>)

Min(<arr>)

Parâmetros obrigatórios

  • de: (Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino
  • arr: (Segunda forma) Um array; todos os elementos do array devem ser do mesmo tipo

Descrição

Retorna o valor mínimo de instâncias de um elemento de dados em um nível específico na hierarquia de uma estrutura de dados. Ele verifica todas as instâncias naquele nível e retorna a menor. Também pode ser usado para retornar o valor mínimo de um array.

Exemplos

Suponha que um banco de dados contenha um campo "Quantity" em uma mesa "Items" que é uma criança de "POHeader"(uma ordem de compra) e que há muitos itens dentro de um POHeader. Então, esta instrução retorna o valor mínimo de Quantity para qualquer item de um POHeader específico:

Min(POHeader.Items#.Quantity);

[Voltar ao topo]

ResolveOneOf

Declaração

type ResolveOneOf(type de)

type ResolveOneOf(array arr)

Sintaxe

ResolveOneOf(<de>)

ResolveOneOf(<arr>)

Parâmetros obrigatórios

  • de: (Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino
  • arr: (Segunda forma) Um array; todos os elementos do array devem ser do mesmo tipo

Descrição

Retorna o primeiro valor não nulo de instâncias de um elemento de dados. Esta função é geralmente usada para recuperar o valor de um elemento de dados de origem "one-of". Também pode ser usada com matrizes e retornará o primeiro elemento não nulo.

[Voltar ao topo]

SetInstances

Declaração

null SetInstances(string nodeName, array de)

Sintaxe

SetInstances(<nodeName>, <de>)

Parâmetros obrigatórios

  • nodeName: Nome de um alvo
  • de: Um caminho de entidade para instâncias de um elemento de dados no destino

Descrição

Define as instâncias de origem para um nó de loop de destino. Normalmente, uma instância de destino de loop é gerada a partir de uma instância de origem de loop. Às vezes, os dados podem vir de outras fontes. Esta função destina-se a casos em que os dados estão em vários conjuntos e cada conjunto gera um único elemento de destino.

A instância é um elemento de dados que pode ser um valor simples ou uma matriz de elementos de dados. Ao criar o destino, cada instância será usada para gerar uma instância de destino.

Para ver como usar um elemento de dados de instância, consulte GetInstance e ArgumentList funções.

Esta função deve ser chamada nos mapeamentos do nó pai do alvo pretendido. Se nenhum nó folha estiver disponível no nó pai, você pode criar um nó de condição que chame esta função. A condição deve terminar com true para que seja sempre aceito.

A função não deve ser chamada mais de uma vez com o mesmo nó de destino, pois a última chamada substitui as anteriores. Para evitar ser substituída, você pode criar pastas de mapeamento múltiplo.

Um elemento de dados nulo é retornado por esta função e deve ser ignorado.

Exemplos

Suponha que exista um pai comum para o DETAILS e COMPANIES nós de destino; ambos são nós de loop; e uma pasta de mapeamento múltiplo foi criada para o DETAILS nó de destino.

...
r1 = DBLookupAll("<TAG>endpoint:database/My Database</TAG>",
  "SELECT key_name, key_value FROM key_values");
SetInstances("DETAILS", r1);
SetInstances("DETAILS#1", r1);
// DETAILS#1 is the name of the
// 1st multiple-mapping-folder for DETAILS

r2 = {"MS", "HP", "Apple"};
SetInstances("COMPANIES", r2);

// Note: Renaming the display name of a
// multiple-mapping-folder doesn't change
// the folder's actual name, which can be
// found by control-clicking the node and using
// "Copy node name to clipboard"
...

Exemplo visual e saída

Abaixo está um exemplo de configuração de esquema aplicando o acima r2 exemplo para um getInformationRequest nó de loop e um COMPANIES nó de loop de destino. DETAILS foi excluído por simplicidade.

Exemplo de SetInstances

O XML resultante se a saída for escrita diretamente após a transformação:

<?xml version="1.0" encoding="UTF-8"?>
<root xmlns="http://www.jitterbit.com/XsdFromWsdl" xmlns:ns="com.iex.tv.webservices.services.agentResourcesService" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <transaction>
        <body>
            <ns:getInformation>
                <ns:getInformationRequest>
                    <ns:COMPANIES>MS</ns:COMPANIES>
                    <ns:COMPANIES>HP</ns:COMPANIES>
                    <ns:COMPANIES>Apple</ns:COMPANIES>
                </ns:getInformationRequest>
            </ns:getInformation>
        </body>
    </transaction>
</root>

[Voltar ao topo]

SortInstances

Declaração

null SortInstances(string nodeName, array sourceDataElements1[, bool sortOrder, ..., array sourceDataElementsN, bool sortOrderN])

Sintaxe

SortInstances(<nodeName>, <sourceDataElements1>[, <sortOrder>, ..., <sourceDataElementsN>, <sortOrderN>])

Parâmetros obrigatórios

  • nodeName: Nome dos elementos do loop de destino a serem classificados
  • sourceDataElements: Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino

Parâmetros opcionais

  • sourceDataElementsN: Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino
  • sortOrder: Uma ordem de classificação opcional, padrão verdadeiro para crescente. O argumento não é opcional se houver vários sourceDataElements argumentos fornecidos.

Descrição

Classifica a geração de elementos de dados do loop de destino com base em um ou mais elementos de dados na origem ou no destino.

Todas as instâncias de classificação devem ter o mesmo número de instâncias que o número de instâncias de destino.

A ordem de classificação é assumida como crescente, e um argumento escalar opcional pode ser colocado ao lado de cada elemento de dados de classificação para substituir a ordem de classificação padrão. Se sortOrder é falso, a ordem de classificação é decrescente.

Os elementos de dados do loop de destino serão classificados primeiro pelas instâncias dos primeiros elementos de dados de origem e, depois, classificados pelas instâncias dos segundos elementos de dados, e assim por diante.

Esta função deve ser chamada nos mapeamentos do nó pai. Se não houver nenhum campo para mapear no nó pai, um script pode ser chamado com esta função ou uma condição pode ser adicionada para esse propósito.

Um valor nulo é retornado desta função e deve ser ignorado.

Exemplos

// The target node "detail" will be ordered
// by "price" from high to low and,
// if the prices are the same for two items,
// the node will be ordered by "quantity" from low to high
SortInstances("detail", Invoice$Item#.price, false, Invoice$Item#.quantity);

O próximo exemplo poderia ser usado em uma condição em um mapeamento para classificar todas as vendas de cada cliente por data. Ele seria colocado no nível de customer nó. Observe a inclusão da declaração true no final do bloco de código para que a condição seja sempre aceita:

<trans>
SortInstances("SalesOrders", _Root$customer.sales#.SalesDate);
true
</trans>

[Voltar ao topo]

Sum

Declaração

type Sum(type de)

type Sum(array arr)

Sintaxe

Sum(<de>)

Sum(<arr>)

Parâmetros Obrigatórios

  • de: (Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino
  • arr: (Segunda forma) Um array; todos os elementos do array devem ser do mesmo tipo

Descrição

Pega o valor de cada instância de um elemento de dados em um nível hierárquico específico e retorna a soma. O tipo de dado de ambos de e arr Deve ser inteiro, longo, flutuante, duplo ou string. Os tipos de dados de todas as instâncias ou de todos os elementos devem ser os mesmos.

Se o array estiver vazio, 0 (zero) será retornado. Embora valores nulos sejam ignorados em arrays com outro tipo de dados, um array com apenas nulos retornará um erro.

Exemplos

Suponha um banco de dados contendo um campo "Quantidade" em uma tabela "Itens" que é filha de POHeader (há muitos itens dentro de um POHeader).

// Returns the sum of the field "Quantity" for
// all items for a particular "POHeader"
Sum(POHeader.Items#.Quantity);

[Voltar ao topo]

SumCSV

Declaração

string SumCSV(type de)

string SumCSV(array arr)

Sintaxe

SumCSV(<de>)

SumCSV(<arr>)

Parâmetros obrigatórios

  • de: (Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino
  • arr: (Segunda forma) Um array; todos os elementos do array devem ser do mesmo tipo

Descrição

Concatena cada instância de um campo de um elemento de dados ou cada elemento de uma matriz, com uma vírgula delimitadora entre cada instância ou elemento.

Se o campo ou elemento da matriz contiver caracteres especiais, como quebras de linha ou vírgulas, o campo ou elemento da matriz será colocado entre aspas duplas. Nenhum delimitador é adicionado após a última instância ou elemento ser concatenado.

Consulte também o SumString função para uma função semelhante, mas com opções adicionais.

Exemplos

// Concatenates all instances of a field of email addresses
// with a comma between each address
SumCSV(_Root$customer.contact#.Email);

[Voltar ao topo]

SumString

Declaração

string SumString(type de[, string delimiter, bool omitLast])

string SumString(array arr[, string delimiter, bool omitLast])

Sintaxe

SumString(<de>[, <delimiter>, <omitLast>])

SumString(<arr>[, <delimiter>, <omitLast>])

Parâmetros obrigatórios

  • de: (Primeira forma) Um caminho de entidade para instâncias de um elemento de dados em uma origem ou destino
  • arr: (Segunda forma) Um array; todos os elementos do array devem ser do mesmo tipo

Parâmetros opcionais

  • delimiter: Uma string para delimitar os itens; o valor padrão é ponto e vírgula
  • omitLast: Um sinalizador que indica se o delimitador deve ser incluído após o último item; o valor padrão é falso.

Descrição

Concatena cada instância dos elementos de dados especificados ou cada elemento de uma matriz, com um delimitador anexado automaticamente ao final de cada string concatenada.

Se o parâmetro omitlast for verdadeiro, o delimitador após a última string será omitido.

Veja também SumCSV função.

Exemplos

// Concatenates all instances of a field of email addresses
// with a comma between each address,
// but does not place a delimiter after the last address
SumString(_Root$customer.contact#.Email, ",", true);

[Voltar ao topo]