Mappings: diseño y publicación de transformaciones
Objetivo y modelo
Un Mapping define cómo se obtiene, transforma y entrega información. Su canvas contiene componentes, puertos y conexiones que representan el flujo de datos. Una Session vincula ese diseño con entorno, parámetros y rutas de ejecución; un Workflow orquesta las Sessions.
Distinga cuatro operaciones: editar un borrador, Save draft, Publish y Run. Guardar conserva cambios de diseño; publicar establece una versión consumible; ejecutar procesa datos. Un guardado correcto no demuestra que el destino haya recibido filas ni que los consumidores existentes utilicen automáticamente la nueva versión.
Requisitos y preparación
Necesita permisos de consulta y, para modificar, autorización de edición del Mapping. Publicar o ejecutar puede exigir privilegios distintos. También necesita una ubicación válida en Repository, conectores configurados cuando correspondan y un worker compatible.
Use nombres que empiecen por una letra y contengan letras, números o guion bajo. El campo de nombre del editor admite de 2 a 79 caracteres. En un laboratorio, utilice m_ClientesDemo; evite incluir contraseñas, direcciones privadas o información personal en nombres y descripciones.
Editor y acciones
| Área o control | Uso |
|---|---|
| Components | Buscar y seleccionar componentes disponibles |
| Configuration | Configurar el componente seleccionado |
| Domain / Folder | Establecer la ubicación del Mapping |
| Shared within tenant | Configurar compartición dentro del tenant autorizado |
| Validate | Revisar problemas antes de guardar o publicar |
| Save draft / Publish | Conservar cambios y establecer una versión |
| Auto arrange mapping | Reorganizar posiciones del canvas |
| Zoom / Fit | Ajustar la visualización sin sustituir la validación |
Conecte puertos compatibles y revise cada origen y destino. En archivos planos, el Mapping define formato y esquema; las rutas de ejecución pertenecen a la Session. Esta separación permite reutilizar el mismo diseño sin copiarlo para cada entorno.
Comportamiento de Arrange
La implementación actual ordena componentes de izquierda a derecha a partir de sus dependencias. Requiere al menos dos componentes y un grafo sin ciclos. Si no caben físicamente en el canvas, conserva un diseño legible y permite desplazamiento horizontal. La operación modifica posiciones del borrador; no transforma datos ni publica una versión.
Un ciclo impide el reordenamiento y genera un mensaje de estado. Si el resultado visual no cambia, revise si el diseño ya estaba ordenado, si existe un ciclo o si el Mapping no es editable.
POC reproducible: normalización de clientes
El repositorio incluye una muestra verificada por diseño con 1.000 filas de entrada y ocho componentes Transform:
clean → replace → split → concat → derive → convert → filter → sort
La muestra usa customers.csv y define como resultado customer_normalized.csv, con 667 filas. Sus definiciones coherentes de Mapping, Session y Workflow están en samples/transform_workflows/definitions/.
En una copia local de laboratorio, con la dependencia documentada openpyxl==3.1.5, el generador se invoca desde la raíz:
python samples/transform_workflows/generate_samples.py
El procedimiento regenera artefactos deterministas y un manifest.json con conteos, hashes SHA-256 y resultados de validación. El README declara una comparación byte a byte con un oráculo Python independiente. No se ejecutó ese generador durante la redacción: los 667 registros son el resultado esperado documentado, no una nueva medición.
Revise el diseño de ejemplo componente por componente. Anote qué filas descarta Filter, qué tipos produce la conversión y qué orden fija sort. Publique únicamente la versión de laboratorio que haya validado y vincúlela a una Session con archivos sintéticos.
Validación, errores y recuperación
Ante una validación fallida, abra la lista de problemas y corrija el componente señalado. Un puerto conectado no garantiza que exista la columna requerida. Compruebe nombres, tipos, nulos y compatibilidad del conector.
Si una ejecución falla por una ruta inexistente, revise primero los bindings de la Session y el acceso del worker. Si falla la autenticación, revise Connections; no copie secretos al canvas. Un error por versión o dependencia requiere revisar qué versión está publicada y cuál conserva el consumidor.
Tras editar un Mapping utilizado por Sessions, confirme el aviso de versión y decida explícitamente cuándo actualizar a los consumidores. Conserve una salida anterior del laboratorio para comparar conteo, columnas y valores; “Run succeeded” no sustituye esa comparación.
Límites y continuidad
El catálogo de componentes depende de las capacidades disponibles. Este capítulo no constituye una referencia exhaustiva de expresiones ni garantiza equivalencia entre todos los conectores. Use Monitor para verificar la ejecución y Open items para cambiar entre diseños sin confundir borradores abiertos con versiones publicadas.