Controlar bucles de datos en transformaciones en Jitterbit Integration Studio

Introducción

Las líneas de iterador de nodo de bucle, que indican los nodos de origen y destino cuyos campos mapeados una transformación iterará, se generan automáticamente durante el proceso de mapeo, ya sea al usar mapeo automático o al mapear manualmente objetos de origen a campos de destino.

Normalmente, la generación automática de nodos de bucle durante el mapeo es apropiada para el conjunto de datos. Sin embargo, cuando los datos son tales que hay múltiples conjuntos de valores de datos repetidos —o múltiples nodos de bucle— es posible que necesite definir manualmente un nodo de bucle para forzar que los datos se repitan en un nodo diferente. Si encuentra errores de validación, consulte Resolver conflictos de mapeo.

En ciertas situaciones, un campo de origen mapeado puede tener una línea de iterador encima que está configurada para generar nuevos registros en un nivel en el destino a partir de un nivel inferior en el origen. Esta configuración de mapeo es válida, pero puede no resultar en los datos deseados en el destino. En este caso, es posible que necesite ajustar el mapeo manualmente.

También puede, si es necesario, eliminar nodos de bucle, tanto los que se han generado automáticamente como los que se han definido manualmente.

Comprender los nodos de bucle

Los nodos de bucle controlan cómo las transformaciones iteran a través de estructuras de datos repetitivas como arreglos y listas. Utilizan líneas de iterador visuales para mostrar el flujo de datos desde el origen hasta el destino.

Los nodos de bucle sirven para tres propósitos principales:

1. Controlar la iteración de datos: Determinan qué elementos de datos se repiten y cuántas veces.

2. Definir el orden de procesamiento: Establecen la secuencia para manejar estructuras de datos anidadas.

3. Mapear relaciones de datos: Conectan datos relacionados entre las estructuras de origen y destino.

Puedes reconocer los nodos de bucle por sus líneas de iterador:

Las líneas negras sólidas conectan nodos de origen a nodos de destino. Estas líneas muestran exactamente dónde se repetirá el dato.

Cuando se ejecuta una transformación, los nodos de bucle controlan el flujo de datos:

1. La transformación comienza con el bucle superior (más externo).

2. Cada elemento de origen genera uno o más registros de destino.

3. Todos los campos mapeados dentro del bucle se procesan en cada iteración.

4. Los bucles internos se completan completamente antes de que el bucle superior/exterior continúe.

5. El procesamiento continúa hasta que se consume toda la data de origen.

Cuando se crean automáticamente los nodos de bucle

Los nodos de bucle aparecen automáticamente cuando tú:

• Mapeas campos entre estructuras repetitivas (arreglos con cardinalidad [0+] o [1+])
• Usas automapeo entre arreglos de origen y destino compatibles
• Creas el primer mapeo de campo entre estructuras repetitivas

Para la creación automática de nodos de bucle, se deben cumplir estos requisitos:

• Tanto los nodos de origen como los de destino deben soportar repetición ([0+] o [1+] de cardinalidad)
• Debes mapear al menos un campo entre las estructuras repetitivas

Definir nodos de bucle

Al usar automapeo, los nodos de bucle se generan automáticamente.

Los nodos de bucle también se pueden definir manualmente en nodos de destino que cumplan con ambas condiciones:

• La cardinalidad del nodo de destino debe ser 0+ o 1+.
• No debe haber mapeos en campos hoja directos dentro del nodo de destino.

Además, la cardinalidad del nodo de origen que se utiliza para crear el nodo de bucle de destino debe ser 0+ o 1+.

Para definir un nodo de bucle manualmente, arrastra un nodo de origen calificado a un nodo de destino calificado:

Al soltar el nodo fuente sobre el nodo objetivo, aparece un menú. Selecciona la opción Definir nodo de bucle.

El nodo de bucle ahora está definido, y se muestra la línea del iterador, indicando cómo la transformación recorrerá el conjunto de datos fuente. La línea se muestra incluso si aún no hay asignaciones directas de hojas en los campos bajo el nodo. Completa la asignación de campos debajo del nodo de bucle como de costumbre:

Los nodos colapsados que contienen asignaciones de nodos de bucle se muestran con una línea de iterador punteada. Haz clic en el triángulo de divulgación para expandir los nodos secundarios hasta que encuentres el nodo de bucle:

Ajustar manualmente los nodos de bucle generados automáticamente

Después de que los nodos de bucle se generan automáticamente, es posible que necesites ajustarlos manualmente. En el siguiente ejemplo, una transformación de solicitud proporciona filtros para usar en una actividad de búsqueda de HubSpot para consultar registros de empresas. A continuación, primero mostramos la salida al usar el nodo de bucle generado automáticamente y luego mostramos cómo cambia la salida cuando el nodo de bucle se redefine manualmente.

Generación automática de nodos de bucle

Después de la automatización y la generación automática de un nodo de bucle, la asignación de transformación muestra datos que se repiten en el segundo nodo item del objetivo:

Cuando la asignación anterior se procesa utilizando los datos de entrada a continuación, resulta en esta salida, que aplana la estructura de entrada en una sola 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"
        }
      ]
    }
  ]
}

Definición manual del nodo de bucle

Para cambiar el nodo en el que los datos están en bucle, arrastre el segundo nodo item de la fuente al primer nodo item del destino y seleccione Definir nodo de bucle:

Ahora vemos la línea del iterador del nodo de bucle en ambos nodos item del destino, primero y segundo:

Cuando el mapeo anterior se procesa utilizando los mismos datos de entrada que se usaron en la generación automática del nodo de bucle, resulta en la salida deseada, que mantiene la estructura 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 un mapeo en nodos de bucle de origen y destino desajustados

Un campo de origen mapeado puede tener una línea de iterador encima que está configurada para generar nuevos registros en un nivel en el destino a partir de un nivel inferior en la fuente (también indicado con un ícono de información junto al nodo de origen). Esta configuración de mapeo es válida, pero puede no resultar en los datos deseados en el destino.

Puede que desee ajustar manualmente el mapeo si alguna de estas afirmaciones es verdadera para su caso de uso:

• No desea crear valores duplicados en registros separados en el archivo de destino.
• No desea omitir ningún valor de los registros en el archivo de destino (debido a un registro hijo faltante).
• Tiene datos de origen donde el registro hijo deseado está en un índice constante o se puede encontrar mediante un valor de búsqueda en el arreglo de registros hijos.
• No necesita valores de ningún otro registro hijo en el arreglo de registros hijos.

Las siguientes subsecciones explican un caso de uso donde se requieren ajustes de mapeo para retener valores de los registros de origen en el archivo de destino. Esta animación proporciona una visión general de los pasos detallados a continuación:

En este escenario, los esquemas de origen y destino tienen estas características:

Generación automática de nodos de bucle

A medida que comenzamos a mapear campos (como Name) desde el nodo fuente de nivel superior hasta el nodo objetivo de nivel superior, se genera automáticamente una línea de iterador de nodo de bucle desde el nodo de matriz de clientes/artículos de nivel superior de la fuente hasta el nodo de matriz plana de clientes de destino. Esto indica que por cada nuevo registro de cliente en la fuente, se generará un nuevo registro de cliente en el destino:

Cuando mapeamos el primer campo en el nodo de dirección fuente repetido (Street) al campo de dirección correspondiente en el destino (street), se muestra un mensaje para indicar que se generarán nuevos registros de destino desde un nivel inferior en la fuente:

Hacer clic en Confirmar resulta en que el extremo de la fuente de la línea de iterador de bucle se mueva automáticamente desde el nodo de matriz de clientes/artículos de nivel superior hacia abajo al nodo de matriz de direcciones/artículos anidados (también indicado con un ícono de información junto al nodo fuente).

Para este escenario de ejemplo, esto significa que por cada nuevo registro de dirección en la fuente, se generará un nuevo registro de cliente en el destino:

Esto resultará en que un único registro de cliente fuente aparezca en el archivo de destino una vez por cada dirección en la matriz de direcciones fuente para ese cliente. Cada registro de cliente tendrá los mismos valores de campo de nivel superior con valores únicos en los campos de dirección. Por ejemplo, si el primer registro de cliente fuente contiene dos direcciones, entonces el destino contendrá dos registros de cliente: uno con la primera dirección y otro con la segunda dirección.

Mapear de un origen de múltiples instancias a un destino de instancia única

Cuando el nodo de bucle de destino generado depende de más de un nodo de bucle de origen, puede ser necesario resolver un desajuste de ocurrencias con el mapeo.

Si la estructura de datos de origen es un arreglo de múltiples objetos y se está mapeando a una estructura de datos de destino con un solo objeto, se mostrará este diálogo:

Para usar la primera instancia del origen en el mapeo, seleccione Sí para insertar automáticamente un símbolo de hash (#) en la ruta de referencia del elemento de datos. Esto significa que solo se mapeará el primer registro. Para un ejemplo completo, consulte Estructuras de datos.

Si no desea que se use la primera instancia del origen, puede especificar instancias manualmente (consulte a continuación) o aplicar otra lógica utilizando funciones de resolución de instancias (consulte Funciones de instancia).

Ajuste manual del mapeo

Usando el escenario de ejemplo, no queremos perder ningún registro de cliente debido a una dirección faltante, por lo que necesitamos ajustar manualmente cada mapeo a nivel de campo del arreglo hijo. Cuando se ajusta cada mapeo, la línea del iterador del nodo de bucle generado se desplaza automáticamente a la ubicación correcta para la salida de destino deseada (basada en el ajuste del mapeo).

Para ajustar el mapeo de cada campo de destino en el arreglo hijo (como calle), agregamos un símbolo de hash seguido de un entero al arreglo de direcciones/item en el script de mapeo. Agregar la referencia #1 devuelve el primer elemento de un arreglo, lo que resulta en la creación de un solo registro de cliente en el destino para cada registro de cliente en el origen. Con esta configuración, cada registro de cliente creado en el destino contiene solo la primera dirección del arreglo de direcciones del registro de cliente de origen; las direcciones restantes no se trasladan al destino.

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

Después de agregar la referencia del ítem (#1) en el script de mapeo de campo, la línea del iterador del nodo de bucle regresa automáticamente al nodo de arreglo de cliente/ítem de nivel superior de origen. Esto muestra que para cada nuevo registro de cliente en el origen, se generará un nuevo registro de cliente en el destino:

A medida que mapeamos a campos adicionales en el arreglo hijo, la línea del iterador del nodo de bucle regresa a la posición original. El proceso de agregar la referencia del ítem (#1) debe repetirse como se indicó anteriormente para cada mapeo a nivel de campo en el arreglo.

Remove a loop node and mappings

Las opciones para eliminar un nodo de bucle definido manualmente o para eliminar cualquier nodo de bucle y sus mapeos están disponibles dentro del menú de acciones de un nodo.

Pasa el cursor sobre el nombre de un nodo y haz clic en el menú de acciones . Desde el menú, selecciona una de estas opciones de eliminación de mapeo:

Elemento del menú	Descripción
	Eliminar nodo de bucle elimina la definición del nodo de bucle. Esta acción está disponible solo en nodos que tienen un nodo de bucle definido manualmente. Para eliminar una definición de nodo de bucle en un nodo de bucle generado automáticamente, elimine todos sus mapeos directos de hojas como se describe en Acciones del nodo objetivo. Nota Si se eliminan todos los mapeos directos de hojas de un nodo de bucle definido manualmente, la definición del nodo de bucle sigue existiendo.
	Eliminar nodo de bucle y mapeos elimina la definición del nodo de bucle debido a mapeos que son hijos directos de hojas asociados con el nodo de bucle, y elimina esos mapeos. Cualquier otro mapeo dentro de nodos de bucle hijos debajo del nodo de bucle padre se conserva, y el nodo retiene su definición de nodo de bucle si al menos un nieto está mapeado. Esta acción está disponible solo en nodos que tienen un nodo de bucle definido (ya sea manualmente o por generación automática).