Manejar zonas horarias en operaciones de fecha y hora en Jitterbit Studio

Introducción

Los sistemas de origen almacenan marcas de tiempo en su propia zona horaria local. Salesforce registra marcas de tiempo en la zona horaria del usuario que ejecuta la operación; NetSuite utiliza la configuración de zona horaria de la empresa. Cuando las marcas de tiempo de estos sistemas fluyen hacia una integración entre regiones sin conversión, resultan errores silenciosos: los registros parecen crearse horas en el pasado o futuro, la deduplicación basada en comparación falla y los disparadores programados se activan en momentos inesperados.

Esta guía cubre tres funciones de fecha y hora que funcionan en conjunto para manejar esto:

• GetUTCFormattedDateTime: convierte una marca de tiempo local a una cadena UTC ISO 8601, adecuada para almacenamiento.
• ConvertTimeZone: desplaza una marca de tiempo de una zona horaria a otra, para entrega o visualización.
• FormatDate: formatea una marca de tiempo convertida como una cadena legible.

Se cubren dos patrones:

• Parte 1: Normalizar marcas de tiempo entrantes a UTC: Convertir marcas de tiempo locales del sistema de origen a UTC en la ingesta, de modo que todos los valores almacenados sean neutrales respecto a la zona horaria.
• Parte 2: Convertir UTC a una zona horaria local para visualización: Desplazar marcas de tiempo UTC almacenadas a la zona horaria local del destinatario y formatearlas para la salida.

Patrón de diseño

Las tres funciones se ejecutan dentro de scripts de transformación de mapeo de campos. La estructura de la operación es la misma para ambos patrones:

La lógica de zona horaria reside en el script de mapeo de campos para el campo de marca de tiempo en el lado del destino. No se necesita un paso de operación separado para la conversión de zona horaria.

Parte 1: Normalizar marcas de tiempo entrantes a UTC

Utiliza GetUTCFormattedDateTime para convertir una marca de tiempo local del sistema de origen a una cadena UTC ISO 8601. Almacenar UTC elimina la ambigüedad de zona horaria y permite comparaciones seguras entre registros de diferentes sistemas.

Paso 1: Identificar la zona horaria del origen

Determina qué zona horaria utiliza el sistema de origen para las marcas de tiempo. Ejemplos comunes:

• Salesforce: Las marcas de tiempo utilizan la zona horaria del usuario cuyas credenciales ejecutan la integración. Verifica la zona horaria del usuario en Setup > Manage Users > Users.
• NetSuite: Las marcas de tiempo utilizan la zona horaria predeterminada de la empresa. Verifica esto en Setup > Company > Company Information.

Utiliza un código IANA TZ completo al especificar la zona horaria (por ejemplo, "America/Los_Angeles" o "Europe/London"). Las abreviaturas como "PST" son compatibles pero no recomendadas: "AST" es ambigua entre Atlantic Standard Time y Arabia Standard Time.

Una lista completa de códigos IANA TZ está disponible en https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

Paso 2: Escribir el script de mapeo

En la transformación, abre el mapeo de campos para el campo de marca de tiempo en el lado del destino. Escribe un script que llame a GetUTCFormattedDateTime con el campo de origen y la zona horaria de origen:

GetUTCFormattedDateTime(Source.created_at, "America/Los_Angeles");
// Si Source.created_at es "2024-03-15 09:00:00"
// Retorna "2024-03-15T17:00:00Z"

El valor devuelto siempre está en formato ISO 8601 (yyyy-mm-ddTHH:MM:SSZ). La mayoría de sistemas aceptan ISO 8601 como formato de marca de tiempo estándar.

Paso 3: Manejar formato de fecha europeo (opcional)

Si el sistema de origen formatea las fechas como día/mes/año en lugar de mes/día/año, establece el argumento opcional is_european_format en true:

GetUTCFormattedDateTime(Source.created_at, "Europe/London", true);
// Parses "15/03/2024 09:00:00" as 15 March 2024 at 09:00
// Returns "2024-03-15T09:00:00Z"

Parte 2: Convertir una marca de tiempo UTC a una zona horaria local para su visualización

Después de almacenar marcas de tiempo UTC, conviértelas a la zona horaria local del destinatario al enviar datos a un sistema destino o generar una notificación. Utiliza ConvertTimeZone para cambiar la hora, luego FormatDate para generar una cadena legible.

Paso 1: Convertir a la zona horaria destino

Utiliza ConvertTimeZone para cambiar la marca de tiempo UTC a la zona horaria destino. Asigna el resultado a una variable local:

localTime = ConvertTimeZone(Source.updated_at, "UTC", "America/New_York");
// If Source.updated_at is "2024-03-15T17:00:00Z"
// Returns "2024-03-15 13:00:00"

Por defecto, ConvertTimeZone tiene en cuenta el horario de verano al convertir entre las cuatro principales zonas horarias de EE.UU. Para desactivar este comportamiento, pasa true como argumento opcional ignoreDST.

Paso 2: Dar formato a la marca de tiempo convertida

Utiliza FormatDate para controlar cómo aparece la marca de tiempo en el campo destino. El argumento de formato utiliza caracteres de marcador de posición para año (yyyy), mes (mm), día (dd), hora (HH), minuto (MM) y segundo (SS). También se admiten códigos de estilo strftime (por ejemplo, %B para el nombre completo del mes).

Formatos comunes:

Paso 3: Combinar en un único script de mapeo

En el script de mapeo de campos del campo de visualización destino, encadena ambas llamadas. Asigna el resultado de ConvertTimeZone a una variable, luego devuelve FormatDate de esa variable:

localTime = ConvertTimeZone(Source.updated_at, "UTC", "America/New_York");
FormatDate(localTime, "yyyy-mm-dd HH:MM:SS");

La última expresión en un script de mapeo es su valor de retorno, por lo que FormatDate proporciona el valor escrito en el campo destino.

Verificar la integración

Verificar la Parte 1 (normalizar a UTC)

1. En la transformación, agrega el script de mapeo GetUTCFormattedDateTime a un campo de marca de tiempo destino.

2. Elige un registro de origen con una marca de tiempo local conocida (por ejemplo, un registro creado a las 9:00 a.m., hora del Pacífico).

3. Implementa y ejecuta la operación.

4. En el registro de operación o en el sistema destino, confirma que la marca de tiempo almacenada coincide con el equivalente UTC esperado (en este ejemplo, 2024-03-15T17:00:00Z para una diferencia horaria de zona estándar del Pacífico de −8).

5. Prueba con una marca de tiempo cerca de una transición del horario de verano en la zona horaria de origen (por ejemplo, un registro creado a la 1:30 a.m., hora del Pacífico, el día en que los relojes avanzan). Confirma que la diferencia horaria UTC cambia correctamente.

6. Si la marca de tiempo de salida es idéntica a la de entrada, confirma que el argumento time_zone_id es un código IANA válido con capitalización correcta. Un código de zona horaria no reconocido hace que GetUTCFormattedDateTime devuelva la entrada sin cambios.

Verificar la Parte 2 (convertir UTC para su visualización)

1. Agrega el script de mapeo ConvertTimeZone y FormatDate a un campo de visualización destino.

2. Utiliza un registro de origen que contenga una marca de tiempo UTC conocida (por ejemplo, "2024-03-15T17:00:00Z").

3. Implementa y ejecuta la operación.

4. En el sistema de destino, confirma que el campo de visualización muestre la hora local esperada para la zona horaria de destino (en este ejemplo, 2024-03-15 13:00:00 para la hora de Eastern).

5. Prueba con una marca de tiempo UTC que caiga cerca de una transición de horario de verano en la zona horaria de destino. Confirma que el desplazamiento se ajuste correctamente.

6. Si la salida formateada no es la esperada, verifica el argumento de cadena de formato en FormatDate. Los caracteres que no se reconocen como marcadores de posición de formato se escriben en la salida tal cual, lo que puede producir resultados inesperados cuando una cadena de formato contiene un token no intencional.