Elegir fuentes de esquema

Introducción

Cuando creas transformaciones, necesitas decidir cómo definir tus esquemas de origen y destino. Esta página explica tus opciones.

Puedes definir esquemas de dos maneras:

Esquemas definidos por la actividad: Esquemas que las actividades de conector generan automáticamente.
Esquemas definidos por la transformación: Esquemas personalizados que creas dentro de la transformación.

Entender cuándo usar cada enfoque te ayuda a construir transformaciones que son más fáciles de mantener y más flexibles. Para practicar estos conceptos, consulta Crea tu primera transformación.

Esquemas definidos por la actividad

Los esquemas definidos por la actividad son creados automáticamente por las actividades de conector. Estas actividades incluyen consultas a bases de datos, llamadas a API o operaciones con archivos. Estos esquemas heredan su estructura del sistema conectado.

Los esquemas definidos por la actividad son beneficiosos para estos escenarios:

Tus conectores admiten generación automática. Ejemplos incluyen actividades de bases de datos, Salesforce, NetSuite y ServiceNow.
Quieres actualizaciones automáticas y mantenimiento reducido. Los cambios en el sistema de origen actualizan las transformaciones automáticamente y mantienen los puntos finales sincronizados.
Estás trabajando con formatos de datos estándar y establecidos. Esto incluye esquemas de bases de datos, especificaciones de API y aplicaciones empresariales.

Los esquemas definidos por la actividad siguen este proceso:

Configura tu actividad: Establece conexiones a bases de datos, puntos finales de API o ubicaciones de archivos.
Generación de esquemas: La actividad genera automáticamente esquemas de solicitud, esquemas de respuesta o ambos.
Herencia de esquemas: Las transformaciones adyacentes heredan estos esquemas automáticamente.
Precedencia: Los esquemas de actividad tienen prioridad sobre los esquemas definidos por la transformación.

Ejemplo

Una actividad de consulta a base de datos genera automáticamente un esquema de respuesta basado en los resultados de tu consulta SQL. Cuando agregas una transformación después de esta actividad, hereda este esquema como su origen.

Tipos de esquema de actividad

Las actividades generan esquemas de dos maneras:

Esquemas generados por el conector: Generados directamente a partir de los metadatos del endpoint y se actualizan automáticamente cuando actualizas la actividad. Ejemplos incluyen estructuras de tablas de bases de datos y formatos de respuesta de API.
Esquemas definidos por el usuario en actividades: Esquemas personalizados que subes durante la configuración de la actividad y permanecen fijos a menos que los actualices manualmente. Ejemplos incluyen archivos JSON de muestra para actividades HTTP o plantillas CSV para actividades de archivos.

Esquemas definidos por transformación

Los esquemas definidos por transformación son esquemas personalizados que creas dentro de la transformación misma. Tienes control total sobre su estructura y contenido.

Los esquemas definidos por transformación son beneficiosos para estos escenarios:

Necesitas estructuras especializadas que no son proporcionadas por conectores estándar. Ejemplos incluyen formatos de salida personalizados, combinación de múltiples fuentes de datos y aplicaciones especializadas.
Tus endpoints no proporcionan esquemas automáticos. Esto incluye sistemas heredados, APIs personalizadas sin especificaciones y formatos de archivo manuales.
Quieres esquemas que no cambien con actualizaciones externas. Usa este enfoque para formatos estandarizados, integraciones compartidas y cuando necesites control directo sobre la estructura.

Puedes crear esquemas de transformación utilizando estos métodos:

Tipo de esquema	Descripción	Mejor para
[Personalizado plano]	Estructuras de un solo nivel como archivos CSV.	Datos tabulares y mapeo sencillo.
[Personalizado jerárquico]	Estructuras complejas y anidadas como XML o JSON.	Múltiples niveles, relaciones y organizaciones de datos complejas.
[Archivo de muestra]	Generar esquemas a partir de archivos de datos existentes (CSV, JSON, XML, XSD).	Detección automática de estructura y tipos de datos a partir de ejemplos.
[Reflejado]	Copiar la estructura del otro lado de tu transformación.	Cuando la fuente y el destino tienen formatos similares que necesitan personalización.

Nota

Considera estas reglas de precedencia al construir tus operaciones:

Los esquemas de actividad adyacentes anulan los esquemas de transformación.
Incluso si mueves una actividad, su esquema sigue siendo heredado.
Los esquemas de transformación se utilizan por defecto solo cuando no hay un esquema de actividad disponible.

Example scenario

En esta operación, la precedencia de esquemas funciona de la siguiente manera:

transformation inheritance

Esquema de origen: Heredado de la actividad de consulta de base de datos (definido por la actividad).
Esquema de destino: Heredado de la actividad HTTP v2 POST (si se proporciona un esquema) o definido por la transformación. Si eliminas la actividad HTTP v2 POST, la transformación mantiene el esquema de destino como un esquema definido por la transformación.

Update schemas from endpoints

Cuando los sistemas externos cambian, debes regenerar los esquemas para utilizar esos cambios en tu proyecto. Esto puede ser necesario cuando:

Agregas campos personalizados a un sistema.
Actualizas a una nueva versión de API.
Modificas las estructuras de las tablas de la base de datos.

Update connector-generated schemas

Los esquemas generados por el conector obtienen su estructura de la API del endpoint. Cuando el endpoint cambia, debes actualizar el esquema en Integration Studio.

Para todos los conectores excepto Database, NetSuite, Salesforce, Salesforce Service Cloud y ServiceMax, puedes regenerar el esquema desde dos ubicaciones:

Configuración de actividad: Abre la actividad y navega al paso de Esquema de datos y haz clic en Actualizar.
Transformación: Pasa el cursor sobre la estructura de origen o destino y haz clic en Actualizar esquema.

El esquema se actualiza desde el endpoint y se refresca en todas las ubicaciones donde se hace referencia.

Database, NetSuite, and certain Salesforce connectors

Los conectores de Database, NetSuite, Salesforce, Salesforce Service Cloud y ServiceMax requieren reconfiguración para actualizar los esquemas:

Abre la configuración de la actividad.
Avanza a través de cada paso de configuración.
Realiza al menos un cambio, como agregar o eliminar un carácter del nombre de la actividad.
Completa la configuración.

El esquema se actualiza cuando completas los pasos de configuración.

Nota

Cuando actualizas un esquema, todas las instancias de ese esquema en tu proyecto se actualizan. Esto incluye todas las transformaciones y actividades que hacen referencia al esquema.

Actualizar esquemas definidos por transformación

Los cambios en los esquemas definidos por el usuario se propagan automáticamente a todas las referencias. Cuando editas un esquema utilizado en múltiples lugares, se muestra un diálogo con los componentes afectados:

Texto del diálogo

Esquema utilizado por múltiples componentes
Este esquema es utilizado por múltiples componentes. Cualquier cambio realizado en él podría afectar la validez de estos componentes: - Componente 1 - Componente 2

Para evitar que los cambios afecten a otros componentes, primero elimina o reemplaza la referencia del esquema en esos componentes.

Manejar cambios de esquema en operaciones

Si el esquema de un endpoint cambia pero no lo has regenerado en Integration Studio, tus operaciones pueden fallar. El impacto depende de:

Qué campos cambiaron.
Si los campos cambiados están mapeados.
Si los campos cambiados son obligatorios.

Por ejemplo:

Campo obligatorio eliminado: Las operaciones fallan con errores del endpoint.
Campo opcional eliminado: Las operaciones pueden tener éxito si el campo no está mapeado.
Campo obligatorio agregado: Las operaciones fallan si el campo no está mapeado.
Campo opcional agregado: Las operaciones tienen éxito pero el nuevo campo es ignorado.

Consejo

Regenera los esquemas siempre que modifiques los sistemas de endpoint para prevenir errores en tiempo de ejecución.

Migración de proyectos heredados

Los proyectos creados antes de la versión 10.33.2 de Harmony renombrarán automáticamente los esquemas definidos por el usuario utilizando este patrón:

<Nombre del esquema original>_<Nombre de la transformación>_<Origen o destino>

Por ejemplo, CustomerData se convierte en CustomerData_TransformCustomers_Source.

Esta nomenclatura asegura una identificación única del esquema a través de las transformaciones.