Zum Inhalt springen

Quell-Daten Salesforce-Datumsfeldern zuordnen und Antwortwehler in Jitterbit Studio protokollieren

Einführung

Beim Schreiben von Daten aus Studio in Salesforce werden zwei Scripting-Muster in Transformationszuordnungen konsistent benötigt:

  • Formatierung von Datumsfeldern: Salesforce-Felder vom Typ Date und DateTime erfordern Werte in bestimmten String-Formaten. Wenn die Quelldaten eine Datetime-Zeichenkette enthalten (z. B. einen Datenbank-Timestamp im Format YYYY-MM-DD HH:MM:SS), muss der Wert in das von Salesforce erwartete Format konvertiert werden, bevor der Schreibvorgang ausgeführt wird.
  • Protokollierung von Antwortwehler: Salesforce-Schreibvorgänge (wie Upsert, Insert und Update) geben ein Ergebnis pro Datensatz zurück. Wenn die Verarbeitung für einen oder mehrere Datensätze fehlschlägt, wird das Feld success in der Antwort auf false gesetzt und ein Array errors mit einer oder mehreren Meldungen gefüllt. Ohne eine explizite Überprüfung in der Antworttransformation können diese datensatzspezifischen Fehler unerkannt bleiben, selbst wenn der Gesamtvorgang in Studio Erfolg meldet.

Dieses Handbuch stellt beide Skripte bereit, erklärt jede Komponente und beschreibt, wo sie zu platzieren sind.

Designmuster

Beide Skripte werden in Transformationen innerhalb derselben Salesforce-Schreibvorgangskette platziert. Das Datumkonvertierungsskript gehört in die Request-Transformation, die Quelldaten vor dem Versand an Salesforce formatiert. Das Fehlerprotokollierungsskript gehört in die Response-Transformation, die die Salesforce-Schreibvorgangsantwort zuordnet:

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A[Quellaktivität] --> B[Request-Transformation] --> C[Salesforce-Schreibaktivität] --> D[Response-Transformation] --> E[Zielaktivität]

Dieses Handbuch setzt voraus, dass eine Salesforce-Verbindung bereits im Projekt konfiguriert ist.

Teil 1: Quell-Datum einem Salesforce-Datumsfeld zuordnen

Salesforce-Felder vom Typ Date erwarten Werte im Format YYYY-MM-DD. Salesforce-Felder vom Typ DateTime erwarten Werte im ISO 8601-Format (YYYY-MM-DDTHH:MM:SSZ). Die Funktionen GetUTCFormattedDate und GetUTCFormattedDateTime erzeugen diese Formate aus einer Quell-Datetime-Zeichenkette. Dieser Teil geht davon aus, dass das Quellfeld eine Datetime-Zeichenkette im Format YYYY-MM-DD HH:MM:SS enthält und dass die Quellzeit UTC ist.

Schritt 1: Script-Editor für das Zieldatumsfeld öffnen

  1. Öffnen Sie in Studio die Transformation, bei der das Zielschema aus einer Salesforce-Schreibaktivität (z. B. Upsert, Insert oder Update) stammt.

  2. Suchen Sie im Zielschema das Datums- oder Datetime-Feld, das Sie zuordnen möchten.

  3. Klicken Sie auf das Feld, um seinen Script-Editor zu öffnen.

Schritt 2: Datumkonvertierungsskript schreiben

Verwenden Sie für ein Salesforce-Feld vom Typ Date die Funktion GetUTCFormattedDate, die nur den Datumsteil im Format YYYY-MM-DD zurückgibt:

// Source field must be in YYYY-MM-DD HH:MM:SS format, expressed in UTC.
// GetUTCFormattedDate returns YYYY-MM-DD, which is the required format for
// Salesforce Date fields.
// If the source date uses a different format, apply a conversion function
// before passing it to GetUTCFormattedDate. See the date and time functions
// reference for available options.
// The third argument (false) uses non-European (month-first) date format.
GetUTCFormattedDate(<source_field>, "UTC", false);

Verwenden Sie für ein Salesforce-Feld vom Typ DateTime stattdessen GetUTCFormattedDateTime, das die vollständige ISO 8601-Datetime-Zeichenkette zurückgibt:

GetUTCFormattedDateTime(<source_field>, "UTC", false);

Ersetzen Sie <source_field> durch den Pfad zum Quell-Datumsfeld, wie er im Quellschema der Transformation angezeigt wird.

Tipp

Wenn sich die Quelldaten in einer anderen Zeitzone als UTC befinden, ersetzen Sie "UTC" durch den entsprechenden Zeitzonencode. Verwenden Sie beispielsweise "America/New_York" für die US-Ostküstenzeit. Die Funktion konvertiert den Quellwert von dieser Zeitzone nach UTC, bevor das Ausgabeformat angewendet wird.

Hinweis

Wenn der Agent, der diesen Vorgang ausführt, ein privater Agent ist, kann seine Systemzeitzone beeinflussen, wie die Funktion Quellwerte interpretiert, die keine explizite Zeitzone enthalten. Cloud-Agenten werden immer in UTC ausgeführt. Für Projekte, die sowohl auf Cloud- als auch auf privaten Agenten ausgeführt werden sollen, geben Sie immer einen expliziten Zeitzonecode an, anstatt sich auf die lokale Systemzeit zu verlassen.

Teil 2: Fehler aus einer Salesforce-Vorgangsantwort protokollieren

Salesforce-Schreibvorgänge geben eine Antwort zurück, die ein result-Array enthält. Jedes Element entspricht einem Eingabedatensatz und enthält:

  • success: Ein boolescher Wert, der angibt, ob dieser Datensatz verarbeitet wurde.
  • errors: Ein Array mit einem oder mehreren Fehlerobjekten, von denen jedes ein message-Feld enthält. Wird ausgefüllt, wenn success false ist.
  • Ein Schlüsselfeld (z. B. eine externe ID oder die Salesforce-Datensatz-ID).

Da result ein Array ist, durchläuft die Antworttransformation es einmal pro Eingabedatensatz. Das Skript in diesem Teil überprüft success bei jeder Iteration und schreibt bei Bedarf, wenn es false ist, einen Logeintrag, der den fehlgeschlagenen Datensatz durch seinen Schlüsselfeldwert identifiziert.

Schritt 3: Eine Antworttransformation zum Vorgang hinzufügen

Wenn die Salesforce-Schreibaktivität noch keine nachgelagerte Transformation hat, die die Antwort abbildet:

  1. Fügen Sie auf der Design-Arbeitsfläche einen Transformation-Schritt nach der Salesforce-Schreibaktivität ein.

  2. Öffnen Sie die Transformation. Das Antwortschema aus der Salesforce-Aktivität wird als Quelle angezeigt, einschließlich des result-Knotens (der einmal pro Eingabedatensatz durchläuft), der success- und errors-Felder in result und des Schlüsselfelds von der Anfrageseite des Schemas.

  3. Fügen Sie für das Zielschema ein einzelnes String-Feld hinzu (z. B. response), oder verwenden Sie ein vorhandenes Zielschema, wenn die Antwort einem nachgelagerten System zugeordnet wird.

Schritt 4: Das Fehlerprotokollierungsskript schreiben

Klicken Sie in der Transformation auf das Zielfeld, um dessen Skript-Editor zu öffnen. Schreiben Sie ein Skript, das success für den aktuellen Ergebnis-Datensatz überprüft und, wenn es false ist, den Schlüsselfeldwert und Fehlermeldungen protokolliert:

// Check whether Salesforce processed this record successfully.
// If not, log the key field value and Salesforce error messages to the operation log.
// Update the field references below to match the paths in your response schema.
// If the key field changes in your Salesforce operation, update the FindByPos reference.
If(<result.success> == false,
    WriteToOperationLog("The following record failed to process. Record: " +
    FindByPos(SourceInstanceCount(), <request.records#.keyField>) +
    " The issue was: " +
    SumString(<result.errors#.message>, ". ", false)));

Ersetzen Sie die Platzhalterverweise durch die tatsächlichen Feldpfade aus dem Quellschema Ihrer Transformation:

Platzhalter Ersetzen durch
<result.success> Das success-Feld im Salesforce-Antwort-result-Knoten
<request.records#.keyField> Das Schlüsselfeld (externe ID oder Datensatz-ID) aus dem Salesforce-Anforderungsknoten, wobei #-Notation verwendet wird, um alle Instanzen als Array zurückzugeben
<result.errors#.message> Das message-Feld innerhalb des errors-Instanzknotens des aktuellen Ergebnis-Datensatzes

Jede Funktion im Skript hat eine spezifische Aufgabe:

  • Die Transformation durchläuft das result-Array, sodass If success einmal pro Eingabedatensatz wertet.
  • WriteToOperationLog schreibt die Fehlerdetails in das Operationsprotokoll, wo sie nach dem Vorgang sichtbar sind.
  • SourceInstanceCount gibt den 1-basierten Index der aktuellen Schleifenwiederholung zurück. Da das result-Array und das Anforderungs-Datensatz-Array in derselben Reihenfolge vorliegen, ordnet dieser Index das aktuelle Ergebnis dem entsprechenden Eingabedatensatz zu.
  • FindByPos ruft den Schlüsselfeldwert bei diesem Index ab. Der Schlüsselfeldbezug verwendet #-Notation, um das vollständige Array von Instanzen zurückzugeben, damit FindByPos das richtige Element auswählen kann.
  • SumString verkettet alle message-Werte im errors-Array für den aktuellen Ergebnis-Datensatz in eine einzelne Zeichenkette, getrennt durch ". ". Wenn Salesforce mehrere Fehler für denselben Datensatz zurückgibt, sind alle im Logeintrag enthalten.

Tipp

Wenn der Vergleich success nicht wie erwartet funktioniert, versuchen Sie einen expliziten String-Vergleich: <result.success> == "false". Einige Schema-Konfigurationen stellen boolesche Felder als Strings dar.

Integration überprüfen

  1. Stellen Sie die Operation bereit und führen Sie sie aus mit einer Test-Payload, die mindestens einen gültigen Datensatz enthält.

  2. Öffnen Sie die Operation Logs und bestätigen Sie, dass die Datumsfeldwerte in der Salesforce-Anfrage dem erwarteten Format für den Zielfeld-Typ entsprechen: YYYY-MM-DD für Date-Felder, YYYY-MM-DDTHH:MM:SSZ für DateTime-Felder.

  3. Um das Error-Logging-Skript zu testen, fügen Sie einen bewusst ungültigen Datensatz in die Test-Payload ein (zum Beispiel einen Datensatz, der gegen eine Salesforce-Validierungsregel verstößt oder auf einen nicht existierenden verknüpften Datensatz verweist). Überprüfen Sie nach dem Ausführen der Operation das Operation Log auf einen Eintrag, der den Datensatz anhand seines Schlüsselfeldwerts identifiziert und die Salesforce-Fehlermeldung enthält.

  4. Bestätigen Sie in Salesforce, dass gültige Datensätze wie erwartet erstellt oder aktualisiert wurden.