Nós de Loop

Introdução

Nó de loop linhas do iterador, que indicam os nós de origem e destino cujos campos mapeados uma transformação iterará, são geradas automaticamente durante o processo de mapeamento, seja ao usar automapping ou quando mapeando 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 há múltiplos conjuntos de valores de dados repetidos — ou múltiplos nós de loop — você pode precisar definir manualmente um nó de loop para forçar os dados a fazerem um loop em um nó diferente.

Em certas situações, um campo de origem mapeado pode ter uma linha iteradora acima dele que é configurada para gerar novos registros em um nível no destino a partir de um nível mais baixo 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.

Definir Nós de Loop

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

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 nenhum mapeamento em campos de folhas diretas 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, em modo de mapeamento, arraste um nó de origem qualificado para um nó de destino qualificado:

drop node loop gif

Ao soltar o nó de origem no nó de destino, um menu aparece. Selecione a opção Define loop node.

O nó do loop agora está definido, e a linha do iterador é exibida, indicando como a transformação fará um loop pelo conjunto de dados de origem. (A linha é exibida mesmo se ainda não houver nenhum mapeamento de folhas direto em campos sob o nó.) Conclua o mapeamento de campos sob o nó do loop como de costume:

soltar nó definir nó de loop resultado

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

linha do iterador do nó recolhido

Ajuste Manualmente os Nós de Loop Gerados Automaticamente

Após os nós de loop serem gerados automaticamente, pode ser necessário ajustá-los manualmente. No exemplo a seguir, uma transformação de solicitação fornece filtros para uso em uma atividade de pesquisa do HubSpot para consultar registros da empresa. Abaixo, mostramos primeiro a saída ao usar o gerado automaticamente nó de loop e então mostrar 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 de transformação mostra o loop de dados no segundo nó do alvo item nó:

resultado do nó do loop de automapeamento

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

Input

{
  "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"
        }
      ]
    }
  ]
}

Output

{
  "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 de Nó de Loop Manual

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

soltar nó definir nó de loop alterar gif

Agora vemos a linha do iterador do nó do loop no primeiro e no segundo nó do alvo. item nós:

soltar nó definir nó de loop alterar resultado

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

Input

{
  "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"
        }
      ]
    }
  ]
}

Output

{
  "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 iteradora acima dele que é 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). Esta configuração de mapeamento é válida, mas pode não resultar nos dados desejados no destino.

Você pode querer ajustar manualmente o mapeamento se qualquer um destes for verdadeiro para 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 na matriz de registros filho.
Você não precisa de valores de nenhum outro registro filho na matriz de registros filho.

As subseções a seguir 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 das etapas detalhadas abaixo:

visão geral do nó de loop

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

Origem	Destino
O arquivo de origem contém registros de clientes. O nó de nível superior é um `0+` nó de matriz de cliente/item que contém todos os registros de origem. Cada cliente tem um `0+` nó de matriz de endereços/itens que pode conter vários endereços.	O arquivo de destino recebe registros de clientes. O nó de nível superior é um `0+` nó de matriz cliente/plana para armazenar os registros de origem recebidos. Cada cliente tem um único conjunto de campos de endereço, sem matrizes aninhadas no destino.

configuração do nó de loop

Geração Automática de Nós de Loop

À medida que começamos a mapear campos (como Name) do nó de origem de nível superior para o nó de destino de nível superior, uma linha iteradora de nó de loop é gerada automaticamente do nó de array de cliente/item de nível superior de origem para o nó de array de cliente/plano de destino. Isso indica que para cada novo registro de cliente na origem, um novo registro de cliente será gerado no destino:

loop node automatic 1

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

iterador sendo reconfigurado

Clicar em Confirmar faz com que a extremidade de origem da linha do iterador do loop se mova automaticamente do nó de matriz de cliente/item de nível superior para o nó de matriz de endereços/item aninhado (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:

loop node automatic 2

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

Importante

Com a geração automática de nó de loop neste cenário, um registro de cliente de origem sem endereços não gerará um registro de cliente de destino.

Ajuste de Mapeamento Manual

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 muda automaticamente para o local correto 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 por um inteiro ao array de endereços/itens no script de mapeamento. Adicionando o #1 referência retorna o primeiro item de uma matriz, 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 da matriz de endereços do registro de cliente de origem — os endereços restantes não são movidos para o destino.

manual do nó de loop 1

Dica

Este exemplo usa a sintaxe de hash descrita em Notação de caminho de referência.

Para retornar o segundo ou os itens subsequentes da matriz, especifique #2, #3, e assim por diante. O FindValue função também pode ser usado para pesquisar um array por um valor e retornar o campo relacionado. Por exemplo, o script de mapeamento para o alvo country campo poderia ser baseado em um Type de Billing:

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

Observe que quando você usa Funções de instância, o símbolo de hash é inserido automaticamente quando necessário.

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ó de array de cliente/item de nível superior de origem. Isso mostra que para cada novo registro de cliente na origem, um novo registro de cliente será gerado no destino:

manual do nó de loop 2

À medida que mapeamos para campos adicionais no array filho, a linha do iterador do nó do 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 na matriz.

Remover um Nó de Loop e Mapeamentos

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ó.

De qualquer modo de mapeamento ou modo script, passe o mouse sobre o nome de um nó e clique no ícone do menu de ações para abrir o menu de ações. No menu, selecione uma destas opções de remoção de mapeamento:

nó de destino remove nó de loop anotado

Item de menu

Descrição

Remover nó de loop remove a definição do nó de loop. Esta ação está disponível somente em nós que têm um nó de loop definido manualmente.

Para remover uma definição de nó de loop em um nó de loop gerado automaticamente, remova todos os seus mapeamentos de folhas diretas, conforme descrito em Nós de destino no modo de mapeamento.

Nota

Se você remover todos os mapeamentos de folhas diretas de um nó de loop definido manualmente, a definição do nó de loop ainda existirá.

Remover nó de loop e mapeamentos remove a definição do nó de loop devido a mapeamentos que são filhos folhas diretos associados ao nó de loop e remove esses mapeamentos.

Quaisquer outros mapeamentos dentro de nós de loop filho abaixo do nó de loop pai são preservados, e o nó retém sua definição de nó de loop se pelo menos um neto for mapeado.

Esta ação está disponível somente em nós que têm um nó de loop definido (manualmente ou por geração automática).