Behandlung von Zeitzonen in Datetime-Operationen in Jitterbit Studio

Einführung

Quellsysteme speichern Zeitstempel in ihrer eigenen lokalen Zeitzone. Salesforce erfasst Zeitstempel in der Zeitzone des ausgeführten Benutzers; NetSuite verwendet die Zeitzoneeinstellung des Unternehmens. Wenn Zeitstempel aus diesen Systemen ohne Umwandlung in eine regionsübergreifende Integration fließen, entstehen stille Fehler: Datensätze scheinen Stunden in der Vergangenheit oder Zukunft erstellt worden zu sein, vergleichsbasierte Deduplizierung schlägt fehl, und geplante Trigger werden zu unerwarteten Zeiten ausgelöst.

Diese Anleitung behandelt drei Datums- und Zeitfunktionen, die zusammenarbeiten, um dies zu handhaben:

• GetUTCFormattedDateTime: konvertiert einen lokalen Zeitstempel in einen UTC-ISO-8601-String, geeignet für die Speicherung.
• ConvertTimeZone: verschiebt einen Zeitstempel von einer Zeitzone in eine andere, für die Lieferung oder Anzeige.
• FormatDate: formatiert einen konvertierten Zeitstempel als lesbaren String.

Zwei Muster werden behandelt:

• Teil 1: Eingehende Zeitstempel auf UTC normalisieren: Konvertieren Sie lokale Zeitstempel aus dem Quellsystem bei der Aufnahme zu UTC, sodass alle gespeicherten Werte zeitzonen-neutral sind.
• Teil 2: UTC zur Anzeige in eine lokale Zeitzone konvertieren: Verschieben Sie gespeicherte UTC-Zeitstempel in die lokale Zeitzone des Empfängers und formatieren Sie sie für die Ausgabe.

Designmuster

Alle drei Funktionen werden in Transformations-Feldmappingskripten ausgeführt. Die Operationsstruktur ist für beide Muster gleich:

Die Zeitzonelogik befindet sich im Feldmappingskript für das Zeitstempelfeld auf der Zielseite. Für die Zeitzonekonvertierung ist kein separater Operationsschritt erforderlich.

Teil 1: Eingehende Zeitstempel auf UTC normalisieren

Verwenden Sie GetUTCFormattedDateTime, um einen lokalen Zeitstempel aus dem Quellsystem in einen UTC-ISO-8601-String zu konvertieren. Die Speicherung von UTC beseitigt Zeitzoneambiguität und ermöglicht sichere Vergleiche zwischen Datensätzen aus verschiedenen Systemen.

Schritt 1: Identifizieren Sie die Quellzeitzone

Bestimmen Sie, welche Zeitzone das Quellsystem für Zeitstempel verwendet. Häufige Beispiele:

• Salesforce: Zeitstempel verwenden die Zeitzone des Benutzers, dessen Anmeldedaten die Integration ausführen. Überprüfen Sie die Zeitzone des Benutzers unter Setup > Manage Users > Users.
• NetSuite: Zeitstempel verwenden die Standard-Zeitzone des Unternehmens. Überprüfen Sie dies unter Setup > Company > Company Information.

Verwenden Sie einen vollständigen IANA-TZ-Code, wenn Sie die Zeitzone angeben (beispielsweise "America/Los_Angeles" oder "Europe/London"). Abkürzungen wie "PST" werden unterstützt, sind aber nicht empfohlen: "AST" ist mehrdeutig zwischen Atlantic Standard Time und Arabia Standard Time.

Eine vollständige Liste der IANA-TZ-Codes finden Sie unter https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

Schritt 2: Schreiben Sie das Mappingskript

Öffnen Sie in der Transformation das Feldmapping für das Zeitstempelfeld auf der Zielseite. Schreiben Sie ein Skript, das GetUTCFormattedDateTime mit dem Quellfeld und der Quellzeitzone aufruft:

GetUTCFormattedDateTime(Source.created_at, "America/Los_Angeles");
// If Source.created_at is "2024-03-15 09:00:00"
// Returns "2024-03-15T17:00:00Z"

Der Rückgabewert ist immer im ISO-8601-Format (yyyy-mm-ddTHH:MM:SSZ). Die meisten Systeme akzeptieren ISO 8601 als Standardzeitstempelformat.

Schritt 3: Behandlung des europäischen Datumsformats (optional)

Wenn das Quellsystem Daten als Tag/Monat/Jahr statt als Monat/Tag/Jahr formatiert, setzen Sie das optionale is_european_format-Argument auf 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"

Part 2: UTC-Zeitstempel in lokale Zeitzone konvertieren zur Anzeige

Nach dem Speichern von UTC-Zeitstempeln konvertieren Sie diese in die lokale Zeitzone des Empfängers, wenn Daten an ein Zielsystem gesendet oder eine Benachrichtigung generiert wird. Verwenden Sie ConvertTimeZone, um die Zeit anzupassen, und dann FormatDate, um eine lesbare Zeichenkette zu erzeugen.

Schritt 1: In die Zielzeitzone konvertieren

Verwenden Sie ConvertTimeZone, um den UTC-Zeitstempel in die Zielzeitzone anzupassen. Weisen Sie das Ergebnis einer lokalen Variablen zu:

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"

Standardmäßig berücksichtigt ConvertTimeZone die Sommerzeit bei der Konvertierung zwischen den vier wichtigsten US-Zeitzonen. Um dieses Verhalten zu deaktivieren, übergeben Sie true als optionales ignoreDST-Argument.

Schritt 2: Den konvertierten Zeitstempel formatieren

Verwenden Sie FormatDate, um zu steuern, wie der Zeitstempel im Zielfeld angezeigt wird. Das Format-Argument verwendet Platzhalterzeichen für Jahr (yyyy), Monat (mm), Tag (dd), Stunde (HH), Minute (MM) und Sekunde (SS). strftime-ähnliche Codes (z. B. %B für den vollständigen Monatsnamen) werden ebenfalls unterstützt.

Häufige Formate:

Schritt 3: In ein einzelnes Mapping-Skript kombinieren

Verketten Sie im Feld-Mapping-Skript für das Zielanzeigefeld beide Aufrufe. Weisen Sie das ConvertTimeZone-Ergebnis einer Variablen zu und geben Sie dann FormatDate dieser Variablen zurück:

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

Der letzte Ausdruck in einem Mapping-Skript ist sein Rückgabewert, daher stellt FormatDate den Wert bereit, der in das Zielfeld geschrieben wird.

Integration überprüfen

Part 1 überprüfen (in UTC normalisieren)

1. Fügen Sie in der Transformation das Mapping-Skript GetUTCFormattedDateTime zu einem Ziel-Zeitstempelfeld hinzu.

2. Wählen Sie einen Quelldatensatz mit einem bekannten lokalen Zeitstempel (z. B. einen Datensatz, der um 9:00 Uhr Pacific Time erstellt wurde).

3. Implementieren und führen Sie die Operation aus.

4. Im Operationsprotokoll oder im Zielsystem überprüfen Sie, dass der gespeicherte Zeitstempel dem erwarteten UTC-Äquivalent entspricht (in diesem Beispiel 2024-03-15T17:00:00Z für einen Pacific Standard Time-Offset von −8).

5. Testen Sie mit einem Zeitstempel in der Nähe eines Sommerzeitwechsels in der Quellzeitzone (z. B. ein Datensatz, der um 1:30 Uhr Pacific Time am Tag der Uhrenumstellung erstellt wurde). Überprüfen Sie, dass die UTC-Verschiebung korrekt angepasst wird.

6. Wenn der Ausgabe-Zeitstempel identisch mit dem Eingabe-Zeitstempel ist, überprüfen Sie, dass das time_zone_id-Argument ein gültiger IANA-Code mit korrekter Großschreibung ist. Ein nicht erkannter Zeitzone-Code bewirkt, dass GetUTCFormattedDateTime die Eingabe unverändert zurückgibt.

Part 2 überprüfen (UTC zur Anzeige konvertieren)

1. Fügen Sie das Mapping-Skript ConvertTimeZone und FormatDate zu einem Ziel-Anzeigefeld hinzu.

2. Verwenden Sie einen Quelldatensatz, der einen bekannten UTC-Zeitstempel enthält (z. B. "2024-03-15T17:00:00Z").

3. Implementieren und führen Sie die Operation aus.

4. Bestätigen Sie im Zielsystem, dass das Anzeigefeld die erwartete Ortszeit für die Zielzeitzone anzeigt (in diesem Beispiel 2024-03-15 13:00:00 für Eastern Time).

5. Testen Sie mit einem UTC-Zeitstempel, der nahe bei einem Wechsel der Sommerzeit in der Zielzeitzone liegt. Bestätigen Sie, dass sich der Offset korrekt anpasst.

6. Falls die formatierte Ausgabe unerwartet ist, überprüfen Sie das Format-String-Argument für FormatDate. Zeichen, die nicht als Format-Platzhalter erkannt werden, werden in die Ausgabe unverändert geschrieben, was zu unerwarteten Ergebnissen führt, wenn eine Format-String ein unbeabsichtigtes Token enthält.