Nós de Loop¶

Introdução¶

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

Em determinadas 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 inferior na origem. Esta configuração de mapeamento é válida, mas pode não resultar nos dados desejados no destino. Neste 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 mapeamento automático, 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 atendam a ambas estas condições:

A cardinalidade do nó de destino deve ser 0+ ou 1+.
Não deve haver nenhum mapeamento em campos folha diretos no nó de destino.

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

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

descartar gif de loop de nó

Ao soltar o nó de origem no nó de destino, um menu é exibido. 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 percorrerá o conjunto de dados de origem. (A linha é exibida mesmo se ainda não houver nenhum mapeamento de folha direto nos campos sob o nó.) Conclua o mapeamento dos campos abaixo do nó do loop como de costume:

drop node define resultado do nó de loop

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 os nós filhos até encontrar o nó de loop:

linha do iterador do nó recolhido

Ajustar Manualmente Nós de Loop Gerados Automaticamente¶

Depois que os nós de loop forem gerados automaticamente, talvez seja necessário ajustá-los manualmente. No exemplo a seguir, uma transformação de solicitação fornece filtros para usar em uma atividade HubSpot Search para consultar registros da empresa. Abaixo, mostramos primeiro a saída ao usar o gerado automaticamente nó de loop e, em seguida, mostre como a saída muda quando o nó de loop é redefinido manualmente.

Geração Automática de Nó 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 destino. item nó:

resultado do nó do loop automático

Quando o mapeamento acima é processado usando os dados de entrada abaixo, resulta nesta saída, que nivela 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 Manual de Nó de Loop¶

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

drop node define loop node change gif

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

drop node define resultado da alteração do nó de loop

Quando o mapeamento acima é processado usando os mesmos dados de entrada usados na geração automática do nó do loop, 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 está configurada para gerar novos registos num nível do destino a partir de um nível inferior na origem (também indicado com um ícone de informação próximo ao 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 alguma destas situações for verdadeira para o seu caso de uso:

Você não deseja criar valores duplicados em registros separados no arquivo de destino.
Você não deseja omitir nenhum valor dos registros no arquivo de destino (devido à falta de um registro filho).
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 filhos.
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 em que 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 de destino têm estas características:

Fonte	Alvo
O arquivo de origem contém registros de clientes. O nó de nível superior é um `0+` nó da matriz cliente/item que contém todos os registros de origem. Cada cliente tem um `0+` nó de matriz de endereços/item que pode conter vários endereços.	O arquivo de destino recebe registros do cliente. O nó de nível superior é um `0+` nó de cliente/matriz simples 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ó 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 do nó de loop é gerada automaticamente do nó de matriz de cliente/item de nível superior de origem para o nó de matriz plana/cliente de destino. Isso indica que para cada novo registro de cliente na origem, será gerado um novo registro de cliente no destino:

nó de loop automático 1

Quando mapeamos o primeiro campo no nó de endereço de origem repetidor (Street) para o campo de endereço de destino correspondente (street), uma mensagem será 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 o final da origem da linha do iterador de loop se mova automaticamente do nó da matriz de cliente/item de nível superior para o nó da matriz de endereços/item aninhados (também indicado com um ícone de informações próximo ao 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:

nó de loop automático 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 desse 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 outro com o segundo endereço.

Importante

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

Ajuste Manual de Mapeamento¶

Usando o cenário de exemplo, não queremos perder nenhum registro de cliente devido à falta de um endereço, portanto, precisamos ajustar manualmente cada mapeamento em nível de campo da matriz 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 do mapeamento).

Para ajustar o mapeamento de cada campo de destino na matriz filho (como street), adicionamos um símbolo hash seguido por um número inteiro à matriz de endereços/item no script de mapeamento. Adicionando o #1 reference 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 esta configuração, cada registro de cliente criado no destino contém apenas o primeiro endereço da matriz de endereços do registro do 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 hash descrita em Notação de caminho de referência.

Para retornar o segundo item ou itens subsequentes da matriz, especifique #2, #3, e assim por diante. O FindValue função também pode ser usado para pesquisar um valor em uma matriz e retornar o campo relacionado. Por exemplo, o script de mapeamento para o destino 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 onde necessário.

Depois de 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 matriz 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 campos adicionais na matriz filho, a linha do iterador do nó de loop retorna à posição original. O processo de adição da referência do item (#1) deve ser repetido como acima para cada mapeamento em 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 de 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 do menu

Descrição

Remover nó de loop remove a definição de 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 todos os seus mapeamentos de folha diretos conforme descrito em Remover um mapeamento em Mapeamento de objetos de origem.

Nota

Se você remover todos os mapeamentos folhas diretos 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 de 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ó 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 possuem um nó de loop definido (manualmente ou por geração automática).