Controlar loops de dados em transformações no Jitterbit Integration Studio

Introdução

As linhas do iterador do nó de loop, que indicam os nós de origem e destino cujos campos mapeados uma transformação irá iterar, são geradas automaticamente durante o processo de mapeamento, seja ao usar mapeamento automático ou ao mapear manualmente objetos de origem para campos de destino.

Normalmente, a geração automática de nós de loop durante o mapeamento é apropriada para o conjunto de dados. No entanto, quando os dados são tais que existem múltiplos conjuntos de valores de dados repetidos — ou múltiplos nós de loop — pode ser necessário definir manualmente um nó de loop para forçar os dados a iterar em um nó diferente. Se você encontrar erros de validação, consulte Resolver conflitos de mapeamento.

Em certas situações, um campo de origem mapeado pode ter uma linha de iterador acima dele que está configurada para gerar novos registros em um nível no destino a partir de um nível inferior na origem. Essa configuração de mapeamento é válida, mas pode não resultar nos dados desejados no destino. Nesse caso, pode ser necessário ajustar o mapeamento manualmente.

Você também pode, se necessário, remover nós de loop, tanto aqueles que foram gerados automaticamente quanto aqueles que foram definidos manualmente.

Compreendendo nós de loop

Os nós de loop controlam como as transformações iteram através de estruturas de dados repetidas, como arrays e listas. Eles usam linhas de iterador visuais para mostrar o fluxo de dados da origem para o destino.

Os nós de loop servem a três propósitos principais:

1. Controlar a iteração de dados: Eles determinam quais elementos de dados se repetem e quantas vezes.

2. Definir a ordem de processamento: Eles estabelecem a sequência para lidar com estruturas de dados aninhadas.

3. Mapear relacionamentos de dados: Eles conectam dados relacionados entre estruturas de origem e destino.

Você pode reconhecer nós de loop pelas suas linhas de iterador:

Linhas pretas sólidas conectam nós de origem a nós de destino. Essas linhas mostram exatamente onde os dados irão fazer loop.

Quando uma transformação é executada, os nós de loop controlam o fluxo de dados:

1. A transformação começa com o loop superior (mais externo).

2. Cada item de origem gera um ou mais registros de destino.

3. Todos os campos mapeados dentro do loop são processados para cada iteração.

4. Loops internos são concluídos totalmente antes que o loop superior/exterior continue.

5. O processamento continua até que todos os dados de origem sejam consumidos.

Quando os nós de loop são criados automaticamente

Os nós de loop aparecem automaticamente quando você:

• Mapeia campos entre estruturas repetitivas (arrays com cardinalidade [0+] ou [1+])
• Usa automapeamento entre arrays de origem e destino compatíveis
• Cria o primeiro mapeamento de campo entre estruturas repetitivas

Para a criação automática de nós de loop, esses requisitos devem ser atendidos:

• Tanto os nós de origem quanto os de destino devem suportar repetição ([0+] ou [1+])
• Você deve mapear pelo menos um campo entre as estruturas repetitivas

Definir nós de loop

Ao usar automapeamento, os nós de loop são gerados automaticamente.

Os nós de loop também podem ser definidos manualmente em nós de destino que atendem a ambas as condições:

• A cardinalidade do nó de destino deve ser 0+ ou 1+.
• Não deve haver mapeamentos em campos folha diretos dentro do nó de destino.

Além disso, a cardinalidade do nó de origem que está sendo usado para criar o nó de loop de destino deve ser 0+ ou 1+.

Para definir um nó de loop manualmente, arraste um nó de origem qualificado para um nó de destino qualificado:

Ao soltar o nó de origem sobre o nó de destino, um menu aparece. Selecione a opção Definir nó de loop.

O nó de loop agora está definido, e a linha do iterador é exibida, indicando como a transformação irá percorrer o conjunto de dados de origem. A linha é exibida mesmo que ainda não haja mapeamentos diretos de folhas nos campos sob o nó. Complete o mapeamento dos campos abaixo do nó de loop como de costume:

Nós colapsados que contêm mapeamentos de nó de loop são mostrados com uma linha de iterador pontilhada. Clique no triângulo de divulgação para expandir os nós filhos até encontrar o nó de loop:

Ajustar manualmente nós de loop gerados automaticamente

Após a geração automática dos nós de loop, pode ser necessário ajustá-los manualmente. No exemplo a seguir, uma transformação de solicitação fornece filtros a serem usados em uma atividade de pesquisa do HubSpot para consultar registros de empresas. Abaixo, primeiro mostramos a saída ao usar o nó de loop gerado automaticamente e, em seguida, mostramos como a saída muda quando o nó de loop é redefinido manualmente.

Geração automática de nós de loop

Após o mapeamento automático e a geração automática de um nó de loop, o mapeamento da transformação mostra dados em loop no segundo nó item do destino:

Quando o mapeamento acima é processado usando os dados de entrada abaixo, resulta nesta saída, que achata a estrutura de entrada em uma única lista de filtros:

{
  "filterGroups": [
    {
      "filters": [
        {
          "operator": "EQ",
          "propertyName": "name",
          "value": "AZ INC"
        }
      ]
    },
    {
      "filters": [
        {
          "operator": "EQ",
          "propertyName": "name",
          "value": "IQ services"
        },
        {
          "operator": "EQ",
          "propertyName": "hs_object_id",
          "value": "4403735338"
        }
      ]
    }
  ]
}

{
  "filterGroups": [
    {
      "filters": [
        {
          "operator": "EQ",
          "propertyName": "name",
          "value": "AZ INC"
        },
        {
          "operator": "EQ",
          "propertyName": "name",
          "value": "IQ services"
        },
        {
          "operator": "EQ",
          "propertyName": "hs_object_id",
          "value": "4403735338"
        }
      ]
    }
  ]
}

Definição manual do nó de loop

Para alterar o nó no qual os dados estão fazendo loop, arraste o segundo nó item da fonte para o primeiro nó item do destino e selecione Definir nó de loop:

Agora vemos a linha do iterador do nó de loop em ambos os primeiros e segundos nós item do destino:

Quando o mapeamento acima é processado usando os mesmos dados de entrada que foram usados na geração automática do nó de loop, resulta na saída desejada, que mantém a estrutura de entrada:

{
  "filterGroups": [
    {
      "filters": [
        {
          "operator": "EQ",
          "propertyName": "name",
          "value": "AZ INC"
        }
      ]
    },
    {
      "filters": [
        {
          "operator": "EQ",
          "propertyName": "name",
          "value": "IQ services"
        },
        {
          "operator": "EQ",
          "propertyName": "hs_object_id",
          "value": "4403735338"
        }
      ]
    }
  ]
}

{
  "filterGroups": [
    {
      "filters": [
        {
          "operator": "EQ",
          "propertyName": "name",
          "value": "AZ INC"
        }
      ]
    },
    {
      "filters": [
        {
          "operator": "EQ",
          "propertyName": "name",
          "value": "IQ services"
        },
        {
          "operator": "EQ",
          "propertyName": "hs_object_id",
          "value": "4403735338"
        }
      ]
    }
  ]
}

Ajustar manualmente um mapeamento em nós de loop de origem e destino incompatíveis

Um campo de origem mapeado pode ter uma linha de iterador acima dele que está configurada para gerar novos registros em um nível no destino a partir de um nível inferior na origem (também indicado com um ícone de informação ao lado do nó de origem). Essa configuração de mapeamento é válida, mas pode não resultar nos dados desejados no destino.

Você pode querer ajustar manualmente o mapeamento se alguma das seguintes condições for verdadeira para o seu caso de uso:

• Você não quer criar valores duplicados em registros separados no arquivo de destino.
• Você não quer omitir nenhum valor dos registros no arquivo de destino (devido a um registro filho ausente).
• Você tem dados de origem onde o registro filho desejado está em um índice constante ou pode ser encontrado por um valor de pesquisa no array de registros filhos.
• Você não precisa de valores de outros registros filhos no array de registros filhos.

As seguintes subseções abordam um caso de uso onde ajustes de mapeamento são necessários para reter valores dos registros de origem no arquivo de destino. Esta animação fornece uma visão geral dos passos detalhados abaixo:

Neste cenário, os esquemas de origem e destino têm as seguintes características:

Geração automática de nó de loop

Ao começarmos a mapear campos (como Name) do nó de origem de nível superior para o nó de destino de nível superior, uma linha de iterador de nó de loop é gerada automaticamente do nó de array de clientes/itens de nível superior da origem para o nó de array de clientes/flat do destino. Isso indica que para cada novo registro de cliente na origem, um novo registro de cliente será gerado no destino:

Quando mapeamos o primeiro campo no nó de endereço repetido da origem (Street) para o campo de endereço correspondente no destino (street), uma mensagem é exibida para indicar que novos registros de destino serão gerados a partir de um nível inferior na origem:

Clicar em Confirmar resulta na movimentação automática da extremidade de origem da linha do iterador de loop do nó de array de clientes/itens de nível superior para o nó de array de endereços/itens aninhados (também indicado com um ícone de informação ao lado do nó de origem).

Para este cenário de exemplo, isso significa que para cada novo registro de endereço na origem, um novo registro de cliente será gerado no destino:

Isso resultará em um único registro de cliente de origem aparecendo no arquivo de destino uma vez para cada endereço no array de endereços da origem para aquele cliente. Cada registro de cliente terá os mesmos valores de campo de nível superior com valores únicos nos campos de endereço. Por exemplo, se o primeiro registro de cliente da origem contiver dois endereços, então o destino conterá dois registros de cliente: um com o primeiro endereço e um com o segundo endereço.

Mapear de uma fonte de múltiplas instâncias para um destino de única instância

Quando o nó de loop de destino gerado depende de mais de um nó de loop de origem, pode ser necessário resolver uma incompatibilidade de ocorrência com o mapeamento.

Se a estrutura de dados de origem for um array de múltiplos objetos e estiver sendo mapeada para uma estrutura de dados de destino com um único objeto, este diálogo é exibido:

Para usar a primeira instância da origem no mapeamento, selecione Sim para inserir automaticamente um símbolo de hash (#) no caminho de referência do elemento de dados. Isso significa que apenas o primeiro registro será mapeado. Para um exemplo completo, veja Estruturas de dados.

Se você não quiser que a primeira instância da origem seja usada, pode especificar instâncias manualmente (veja abaixo) ou outra lógica usando funções de resolução de instância (veja Funções de instância).

Ajuste manual de mapeamento

Usando o cenário de exemplo, não queremos perder nenhum registro de cliente devido a um endereço ausente, então precisamos ajustar manualmente cada mapeamento de nível de campo do array filho. Quando cada mapeamento é ajustado, a linha do iterador do nó de loop gerado automaticamente se desloca para a localização correta para a saída de destino desejada (com base no ajuste de mapeamento).

Para ajustar o mapeamento para cada campo de destino no array filho (como street), adicionamos um símbolo de hash seguido de um inteiro ao array de endereços/item no script de mapeamento. Adicionar a referência #1 retorna o primeiro item de um array, resultando na criação de um único registro de cliente no destino para cada registro de cliente na origem. Com essa configuração, cada registro de cliente criado no destino contém apenas o primeiro endereço do array de endereços do registro de cliente de origem — os endereços restantes não são movidos para o destino.

<trans>
FindValue("Billing", json$item.Addresses$item#.Type$, json$item.Addresses$item#.Country$)
</trans>

Após adicionar a referência do item (#1) no script de mapeamento de campo, a linha do iterador do nó de loop retorna automaticamente ao nó do array de cliente/item de nível superior da fonte. Isso mostra que, para cada novo registro de cliente na fonte, um novo registro de cliente será gerado no destino:

À medida que mapeamos para campos adicionais no array filho, a linha do iterador do nó de loop retorna à posição original. O processo de adicionar a referência do item (#1) deve ser repetido como acima para cada mapeamento de nível de campo no array.

Remover um nó de loop e mapeamentos

As opções para remover um nó de loop definido manualmente ou para remover qualquer nó de loop e seus mapeamentos estão disponíveis no menu de ações de um nó.

Passe o mouse sobre o nome de um nó e clique no menu de ações . No menu, selecione uma dessas opções de remoção de mapeamento:

Item do Menu	Descrição
	Remover nó de loop remove a definição do nó de loop. Esta ação está disponível apenas em nós que possuem um nó de loop definido manualmente. Para remover uma definição de nó de loop em um nó de loop gerado automaticamente, remova todas as suas mapeações de folha diretas, conforme descrito em Ações do nó de destino. Nota Se você remover todas as mapeações de folha diretas de um nó de loop definido manualmente, a definição do nó de loop ainda existe.
	Remover nó de loop e mapeações remove a definição do nó de loop devido a mapeações que são filhos de folha diretos associados ao nó de loop e remove essas mapeações. Qualquer outra mapeação dentro de nós de loop filhos abaixo do nó de loop pai é preservada, e o nó mantém sua definição de nó de loop se pelo menos um neto estiver mapeado. Esta ação está disponível apenas em nós que têm um nó de loop definido (seja manualmente ou por geração automática).