Lidar com fusos horários em operações de data e hora no Jitterbit Studio

Introdução

Os sistemas de origem armazenam timestamps em seu próprio fuso horário local. O Salesforce registra timestamps no fuso horário do usuário em execução; o NetSuite usa a configuração de fuso horário da empresa. Quando timestamps desses sistemas fluem para uma integração entre regiões sem conversão, erros silenciosos resultam: registros parecem ser criados horas no passado ou futuro, a deduplicação baseada em comparação falha e acionadores agendados disparam em momentos inesperados.

Este guia aborda três funções de data e hora que trabalham juntas para lidar com isso:

• GetUTCFormattedDateTime: converte um timestamp local em uma string ISO 8601 UTC, adequada para armazenamento.
• ConvertTimeZone: desloca um timestamp de um fuso horário para outro, para entrega ou exibição.
• FormatDate: formata um timestamp convertido como uma string legível.

Dois padrões são abordados:

• Parte 1: Normalizar timestamps recebidos para UTC: Converter timestamps locais do sistema de origem para UTC na ingestão, de modo que todos os valores armazenados sejam independentes de fuso horário.
• Parte 2: Converter UTC para um fuso horário local para exibição: Deslocar timestamps UTC armazenados para o fuso horário local do destinatário e formatar para saída.

Padrão de design

As três funções são executadas dentro de scripts de mapeamento de campos de transformação. A estrutura da operação é a mesma para ambos os padrões:

A lógica de fuso horário fica no script de mapeamento de campos do campo timestamp no lado alvo. Nenhuma etapa de operação separada é necessária para a conversão de fuso horário.

Parte 1: Normalizar timestamps recebidos para UTC

Use GetUTCFormattedDateTime para converter um timestamp local do sistema de origem em uma string ISO 8601 UTC. Armazenar UTC elimina ambiguidade de fuso horário e permite comparações seguras entre registros de diferentes sistemas.

Passo 1: Identificar o fuso horário de origem

Determine qual fuso horário o sistema de origem usa para timestamps. Exemplos comuns:

• Salesforce: Timestamps usam o fuso horário do usuário cujas credenciais executam a integração. Verifique o fuso horário do usuário em Setup > Manage Users > Users.
• NetSuite: Timestamps usam o fuso horário padrão da empresa. Verifique isso em Setup > Company > Company Information.

Use um código IANA TZ completo ao especificar o fuso horário (por exemplo, "America/Los_Angeles" ou "Europe/London"). Abreviações como "PST" são suportadas, mas não recomendadas: "AST" é ambígua entre Atlantic Standard Time e Arabia Standard Time.

Uma lista completa de códigos IANA TZ está disponível em https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

Passo 2: Escrever o script de mapeamento

Na transformação, abra o mapeamento de campos do campo timestamp no lado alvo. Escreva um script que chame GetUTCFormattedDateTime com o campo de origem e o fuso horário de origem:

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

O valor de retorno sempre está em formato ISO 8601 (yyyy-mm-ddTHH:MM:SSZ). A maioria dos sistemas aceita ISO 8601 como um formato de timestamp padrão.

Passo 3: Lidar com formato de data europeu (opcional)

Se o sistema de origem formatar datas como dia/mês/ano em vez de mês/dia/ano, defina o argumento opcional is_european_format como 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: Converter um timestamp UTC para o fuso horário local para exibição

Após armazenar timestamps em UTC, converta-os para o fuso horário local do destinatário ao enviar dados para um sistema de destino ou gerar uma notificação. Use ConvertTimeZone para deslocar a hora e, em seguida, FormatDate para produzir uma string legível.

Etapa 1: Converter para o fuso horário de destino

Use ConvertTimeZone para deslocar o timestamp em UTC para o fuso horário de destino. Atribua o resultado a uma variável 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 padrão, ConvertTimeZone leva em conta o horário de verão ao converter entre os quatro principais fusos horários dos EUA. Para desabilitar esse comportamento, passe true como argumento opcional ignoreDST.

Etapa 2: Formatar o timestamp convertido

Use FormatDate para controlar como o timestamp aparece no campo de destino. O argumento de formato usa caracteres de espaço reservado para ano (yyyy), mês (mm), dia (dd), hora (HH), minuto (MM) e segundo (SS). Códigos no estilo strftime (por exemplo, %B para nome completo do mês) também são suportados.

Formatos comuns:

Etapa 3: Combinar em um único script de mapeamento

No script de mapeamento de campo para o campo de exibição de destino, encadeie ambas as chamadas. Atribua o resultado de ConvertTimeZone a uma variável e, em seguida, retorne FormatDate dessa variável:

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

A última expressão em um script de mapeamento é seu valor de retorno, portanto FormatDate fornece o valor gravado no campo de destino.

Verificar a integração

Verificando a Parte 1 (normalizar para UTC)

1. Na transformação, adicione o script de mapeamento GetUTCFormattedDateTime a um campo de timestamp de destino.

2. Escolha um registro de origem com um timestamp local conhecido (por exemplo, um registro criado às 9:00 AM no horário do Pacífico).

3. Implante e execute a operação.

4. No log de operação ou no sistema de destino, confirme que o timestamp armazenado corresponde ao equivalente em UTC esperado (neste exemplo, 2024-03-15T17:00:00Z para um deslocamento de Horário Padrão do Pacífico de −8).

5. Teste com um timestamp próximo a uma transição de horário de verão no fuso horário de origem (por exemplo, um registro criado às 1:30 AM no horário do Pacífico no dia em que os relógios avançam). Confirme que o deslocamento de UTC muda corretamente.

6. Se o timestamp de saída for idêntico ao de entrada, confirme que o argumento time_zone_id é um código IANA válido com capitalização correta. Um código de fuso horário não reconhecido faz com que GetUTCFormattedDateTime retorne a entrada inalterada.

Verificando a Parte 2 (converter UTC para exibição)

1. Adicione o script de mapeamento ConvertTimeZone e FormatDate a um campo de exibição de destino.

2. Use um registro de origem que contenha um timestamp UTC conhecido (por exemplo, "2024-03-15T17:00:00Z").

3. Implante e execute a operação.

4. No sistema de destino, confirme que o campo de exibição mostra a hora local esperada para o fuso horário de destino (neste exemplo, 2024-03-15 13:00:00 para horário do Leste).

5. Teste com um timestamp UTC que caia próximo a uma transição de horário de verão no fuso horário de destino. Confirme que o deslocamento se ajusta corretamente.

6. Se a saída formatada for inesperada, verifique o argumento da string de formato para FormatDate. Os caracteres que não são reconhecidos como espaços reservados de formato são gravados na saída como estão, o que pode produzir resultados inesperados quando uma string de formato contém um token não intencional.