Configuración de Mapeo

Una configuración de mapeo es un documento JSON que indica a EZY Integrations exactamente cómo extraer datos de un sistema fuente, cómo interpretar y validar cada campo, y cómo escribir esos campos en el sistema destino. Una configuración de mapeo cubre un tipo de entidad para un par de conectores fuente–destino. Puedes crear y editar configuraciones de mapeo en el editor de configuraciones de mapeo dentro de la interfaz de EZY Integrations.

Descripción general de la estructura

flowchart LR
    A["bloque de extracción\nCómo leer datos\ndel sistema fuente"] --> B["bloque de normalización\nCómo mapear campos fuente\na la entidad canónica"]
    B --> C["bloque de transformación\nCómo mapear campos canónicos\nal payload destino"]

Una configuración de mapeo tiene tres bloques de nivel superior:

Bloque	Propósito
`extraction`	Define qué registros leer del sistema fuente y qué columnas obtener. Incluye la columna del cursor para sincronización incremental.
`normalization`	Mapea los nombres de campos crudos del sistema fuente a las propiedades de la entidad canónica usadas internamente por el pipeline. También aplica conversiones de tipo y establece valores predeterminados.
`transformation`	Mapea las propiedades canónicas a las rutas de campos exactas que el sistema destino espera. Aplica transformadores de valores, valores estáticos y mapeos condicionales.

Bloque de extracción

El bloque de extracción controla cómo el pipeline lee registros del sistema fuente. El modo disponible depende del conector fuente:

Modo	Cuándo usarlo
Config	Construye una consulta a partir de un nombre de tabla y una lista de columnas. Recomendado para la mayoría de extracciones de SAP Business One — los nombres de columnas se validan antes de ejecutar la consulta.
SQL sin formato	Escribe una consulta SQL libre. Úsalo para joins o subconsultas complejas que el modo config no puede expresar.
Procedimiento almacenado	Llama a un procedimiento almacenado con nombre y pasa parámetros. Úsalo cuando la lógica de extracción ya está encapsulada en la base de datos.
API	Especifica un endpoint de API fuente. Se usa para conectores como EZY Portal y Shopify que exponen una API REST o GraphQL.

La columna del cursor en el bloque de extracción indica al pipeline qué columna rastrea la marca de tiempo de última modificación. En cada ejecución, el pipeline recupera solo los registros donde el valor de la columna del cursor es mayor que el cursor guardado de la ejecución anterior. Si no se especifica columna de cursor, la extracción lee todos los registros cada vez.

Bloque de normalización

El bloque de normalización mapea los nombres de campos crudos del sistema fuente (los alias definidos en el bloque de extracción) a las propiedades de la entidad canónica que el pipeline usa internamente. También puedes:

Especificar el tipo de dato esperado (string, decimal, int, bool, datetime) para que el pipeline convierta el valor antes de almacenarlo.
Marcar un campo como required para que la etapa de normalización falle rápidamente si el valor es nulo o vacío.
Establecer un defaultValue para que los campos opcionales faltantes reciban un valor de respaldo sensato en lugar de nulo.
Aplicar un transform (un transformador de valores) para convertir el valor crudo — por ejemplo, convertir un indicador Y/N de SAP a un booleano verdadero/falso.

Bloque de transformación

El bloque de transformación mapea los nombres de propiedades canónicas a las rutas de campos que el sistema destino espera. Una ruta de campo usa notación de punto y admite índices de array: por ejemplo, product.variants[0].price establece el precio en la primera variante de un producto de Shopify.

También puedes agregar:

Campos estáticos — inyecta un valor codificado en cada registro, independientemente de los datos fuente (por ejemplo, siempre establecer product.vendor con un nombre de marca fijo).
Condiciones — aplica un mapeo solo cuando un campo canónico cumple un criterio (por ejemplo, solo mapear discountedPrice cuando hasDiscount == true).
Mapeos multi-fuente — recopila valores de varios campos canónicos en un solo array (por ejemplo, combinar category, subcategory y productType en product.tags).

Consulta Transformadores de Valor para la lista completa de funciones de transformación que puedes aplicar dentro de un mapeo de campo.

Ejemplo de configuración de mapeo

El siguiente ejemplo muestra una configuración de mapeo de artículos mínima. Los nombres de campos fuente, nombres de tablas y rutas destino usan valores de marcador de posición.

{
  "version": "1.0",
  "extraction": {
    "source": "sap-b1",
    "mode": "config",
    "sqlConfig": {
      "baseTable": "<TABLA_FUENTE>",
      "alias": "T0",
      "columns": [
        { "column": "<COLUMNA_CODIGO>",  "alias": "itemCode", "required": true },
        { "column": "<COLUMNA_NOMBRE>",  "alias": "itemName" },
        { "column": "<COLUMNA_PRECIO>",  "alias": "price" },
        { "column": "<COLUMNA_FECHA>",   "alias": "updateDate" }
      ],
      "whereClause": "T0.validFor = 'Y'",
      "cursorColumn": "updateDate",
      "primaryKeyColumn": "itemCode"
    }
  },
  "normalization": {
    "fieldMappings": [
      { "source": "itemCode", "canonical": "sku",   "required": true, "type": "string" },
      { "source": "itemName", "canonical": "name" },
      { "source": "price",    "canonical": "price", "type": "decimal", "defaultValue": 0 }
    ],
    "requiredFields": ["sku"]
  },
  "transformation": {
    "target": "ezyportal",
    "fieldMappings": [
      { "canonical": "sku",   "target": "itemCode" },
      { "canonical": "name",  "target": "itemName" },
      {
        "canonical": "price",
        "target": "price",
        "transform": "formatDecimal",
        "options": { "decimals": 2 }
      }
    ],
    "staticFields": [
      { "target": "itemType", "value": "I" }
    ]
  }
}

Asistente de IA

El editor de configuraciones de mapeo incluye un asistente de IA que puede generar un borrador inicial de configuración de mapeo a partir de una descripción en lenguaje natural. Para usarlo, abre el editor para una nueva configuración de mapeo, escribe una descripción de lo que quieres mapear (por ejemplo, “Mapear artículos de SAP B1 incluyendo precio y peso a productos de Shopify”), y el asistente producirá un borrador. Debes revisar, probar y ajustar el borrador antes de guardarlo — el asistente no tiene acceso a tus datos reales.

Validar una configuración de mapeo

El editor muestra un indicador de validación que verifica la estructura JSON mientras escribes. Un indicador verde significa que el documento es JSON válido con los bloques de nivel superior requeridos. Un indicador rojo indica un error estructural como una propiedad requerida faltante o una ruta JSON inválida. La validación no verifica si los nombres de campos coinciden con tu sistema fuente o destino real — eso lo verificas durante una ejecución de prueba.

Tareas comunes

Abrir el editor de configuraciones de mapeo — Navega a Configuraciones de Mapeo en el menú principal, luego selecciona una configuración existente o haz clic en Nueva.
Crear un mapeo desde cero — Elige el tipo de entidad, selecciona el par de conectores fuente y destino, luego completa los tres bloques.
Usar el asistente de IA — Haz clic en el botón de Asistente de IA en la barra de herramientas del editor, describe tu mapeo y revisa el borrador generado.
Vista previa de los mapeos de campos — Usa el panel de Vista previa para probar un mapeo contra un payload de muestra de tu sistema fuente.
Guardar y validar — Haz clic en Guardar; el editor valida la estructura JSON y muestra los errores en línea.

Relacionado

Transformadores de Valor — Referencia completa de las funciones de transformación disponibles en los mapeos de campos.
Tipos de Entidad — Qué nombre de tipo de entidad usar en tu configuración de mapeo.
Descripción General de la Arquitectura — Cómo la configuración de mapeo encaja en las etapas del pipeline.