Validieren und bereichern Sie Datensätze vor einem CRM-Upsert in Jitterbit Studio

Einführung

Das Schreiben eines Datensatzes in ein CRM ohne vorherige Validierung des Inhalts birgt das Risiko, doppelte Einträge zu erstellen, unvollständige Daten zu speichern oder genaue Werte durch veraltete zu überschreiben. Diese Anleitung zeigt, wie man eine mehrstufige Pre-Write-Pipeline erstellt, die erforderliche Felder validiert, nach vorhandenen Datensätzen sucht, um zwischen Erstellen und Aktualisieren zu entscheiden, und die eingehenden Daten optional mit Kontaktinformationen von Drittanbietern bereichert, bevor der endgültige Upsert erfolgt.

Ein zweites Muster ergänzt ein LLM-Genehmigungsgate für agentengesteuerte Workflows. Wenn ein Sprachmodell den CRM-Schreibvorgang steuert, erzwingt die Systemaufforderung einen zweistufigen Bestätigungs-dann-Ausführungs-Ablauf, damit das Modell immer explizite Benutzergenehmigung anfordert, bevor ein Datensatz erstellt oder aktualisiert wird. Dies verhindert, dass eine Benutzeräußerung wie „diesen Kontakt hinzufügen" einen sofortigen Schreibvorgang ohne Bestätigung auslöst.

Diese Anleitung verwendet Salesforce als CRM-Ziel und ZoomInfo als Anreicherungsquelle. Die Feldvalidierungs- und Existenzprüfungsmuster gelten für jeden CRM-Connector oder jede API.

Entwurfsmuster

Die codebasierte Pipeline läuft sequenziell ab. Jede Stufe fährt entweder zur nächsten fort oder verursacht einen Fehler, bevor der Schreibvorgang erreicht wird:

Das LLM-Genehmigungsgate umschließt die Execute-Stufe in agentengesteuerten Workflows:

Teil 1: Erforderliche Felder validieren

Bevor man in Salesforce abfragt oder schreibt, wird bestätigt, dass der eingehende Datensatz die Mindestfelder enthält, die zur Identifizierung und Erstellung eines Kontakts erforderlich sind. Für einen Salesforce Lead sind die erforderlichen Felder typischerweise E-Mail, Vorname und Nachname. Lehnen Sie Datensätze, die eines dieser Felder vermissen, sofort ab, um partielle oder nicht identifizierbare Schreibvorgänge zu verhindern.

Schritt 1: Schreiben Sie das Feldvalidierungsskript

Fügen Sie einen Script-Schritt am Anfang des Pre-Write-Vorgangs hinzu. Das Skript überprüft jedes erforderliche Feld, erfasst alle Meldungen zu fehlenden Feldern und verursacht einen Fehler, wenn der Datensatz nicht fortgesetzt werden kann:

// Validate required fields before any CRM operation
$errors = "";

If(Length(Trim($lead.email)) == 0,
    $errors = $errors + "Email is required. ";
);
If(Length(Trim($lead.firstName)) == 0,
    $errors = $errors + "First name is required. ";
);
If(Length(Trim($lead.lastName)) == 0,
    $errors = $errors + "Last name is required. ";
);

If(Length($errors) > 0,
    RaiseError("Record validation failed: " + $errors)
);

// Normalize the email address before the lookup
$lead.email = ToLower(Trim($lead.email));

WriteToOperationLog("Required field validation passed for: " + $lead.email);

Trim entfernt führende und nachfolgende Leerzeichen. Das Normalisieren der E-Mail auf Kleinbuchstaben vor der Suche verhindert Fehler bei Groß-/Kleinschreibung beim Vergleich mit Salesforce-Datensätzen.

Schritt 2: Überprüfen Sie das E-Mail-Format

Um fehlerhafte Adressen zu erkennen, bevor sie Salesforce erreichen, fügen Sie eine Formatprüfung mit RegExMatch hinzu:

If(!RegExMatch($lead.email, "^[^@]+@[^@]+\\.[^@]+$"),
    RaiseError("Invalid email format: " + $lead.email)
);

Diese Prüfung erkennt offensichtliche Formatierungsfehler (fehlender @-Symbol, fehlende Domäne), ohne gültige Adressen abzulehnen, die ungewöhnliche Zeichen enthalten.

Teil 2: Nach vorhandenen Datensätzen suchen

Nach der Validierung wird Salesforce abgefragt, um festzustellen, ob bereits ein Datensatz mit derselben E-Mail vorhanden ist. Das Ergebnis steuert, ob der nachgelagerte Vorgang einen neuen Datensatz erstellt oder den vorhandenen aktualisiert.

Schritt 1: Salesforce nach einem passenden Lead abfragen

Verwenden Sie SfLookupAll, um nach einem Lead mit derselben E-Mail-Adresse zu suchen. SfLookupAll gibt ein zweidimensionales Array zurück: Jedes innere Array ist eine übereinstimmende Zeile, und jedes Element ist ein Feldwert in der angegebenen Reihenfolge.

Fügen Sie einen Script-Schritt nach dem Validierungsskript hinzu:

// Query Salesforce for an existing lead by email
$sf.existingLeadId = "";
$result = SfLookupAll(
    "<TAG>endpoint:salesforce/Salesforce</TAG>",
    "SELECT Id FROM Lead WHERE Email = '" + $lead.email + "' AND IsConverted = false LIMIT 1"
);

If(Length($result) > 0,
    // Row 0, column 0 is the Id field
    $sf.existingLeadId = $result[0][0];
    WriteToOperationLog("Existing lead found: " + $sf.existingLeadId);
,
    WriteToOperationLog("No existing lead found for: " + $lead.email);
);

LIMIT 1 verhindert, dass das Ergebnis-Array mehrere Treffer enthält, wenn dieselbe E-Mail mehrmals vorkommt, was in CRM-Daten mit historischen Duplikaten vorkommen kann. Weitere Informationen zum SOQL-Abfragemuster finden Sie unter Salesforce-Datensätze mit SOQL abfragen.

Schritt 2: Setzen Sie die Routing-Variable

Nach der Suche wird eine Variable gesetzt, die nachgelagerte Operationen zum Verzweigen zur korrekten Write-Aktivität verwenden:

If(Length($sf.existingLeadId) > 0,
    $sf.operation = "update";
,
    $sf.operation = "create";
);

Überprüfen Sie in Ihrem Controller-Skript oder in der nachgelagerten Operationskette sf.operation, um die entsprechende Salesforce-Aktivität aufzurufen. Anleitungen zum Verzweigen zwischen Operationen basierend auf einer Variablen finden Sie unter Workflows mit Controller-Skripten verwalten.

Teil 3: Datensatz vor dem Schreiben anreichern

Nach der Validierung erforderlicher Felder und der Entscheidung zwischen Erstellen oder Aktualisieren können Sie den eingehenden Datensatz optional mit zusätzlichen Kontaktdaten aus einer Drittanbieterquelle anreichern, bevor der Schreibvorgang stattfindet. Dieser Schritt füllt fehlende Felder aus und kennzeichnet Werte, die sich seit der letzten Synchronisierung möglicherweise geändert haben.

Schritt 1: ZoomInfo-Anreicherung aufrufen

Wenn der Datensatz einen zugehörigen Firmennamen hat, verwenden Sie ZoomInfo, um die aktuelle Berufsbezeichnung, direkte Telefonnummer und E-Mail des Kontakts abzurufen. Die vollständige ZoomInfo-Integrationseinrichtung, einschließlich Authentifizierung und Resource Router, finden Sie unter Kontaktdaten mit ZoomInfo anreichern.

Nach Ausführung der ZoomInfo-Anreicherungsoperation wenden Sie die zurückgegebenen Werte auf die Staging-Variablen an und bewahren dabei alle Werte, die das Quellsystem bereits bereitgestellt hat:

// Apply enrichment results — fill gaps only, do not overwrite existing values
If(Length(Trim($zoom.enriched.phone)) > 0 && Length(Trim($lead.phone)) == 0,
    $lead.phone = $zoom.enriched.phone
);
If(Length(Trim($zoom.enriched.title)) > 0 && Length(Trim($lead.title)) == 0,
    $lead.title = $zoom.enriched.title
);

Die If-Bedingungen bewahren jeden Wert, den das Quellsystem bereits geliefert hat. ZoomInfo-Anreicherung füllt Lücken, anstatt Daten zu überschreiben.

Schritt 2: Veraltete Feldwerte bei vorhandenen Datensätzen erkennen

Beim Aktualisieren eines vorhandenen Salesforce-Datensatzes vergleichen Sie angereicherte Werte mit den gespeicherten Werten, um Felder zu identifizieren, die sich geändert haben. Protokollieren Sie Abweichungen, damit nachgelagerte Operationen entscheiden können, ob der aktualisierte Wert angewendet werden soll:

// Compare enriched title against the Salesforce stored value
If($sf.operation == "update"
    && Length(Trim($zoom.enriched.title)) > 0
    && $zoom.enriched.title != $sf.existing.title,
    WriteToOperationLog(
        "Title change detected for " + $lead.email
        + ": Salesforce has [" + $sf.existing.title + "]"
        + ", ZoomInfo has [" + $zoom.enriched.title + "]"
    );
    $lead.titleChanged = true;
);

Ob der neue Wert angewendet oder zur manuellen Überprüfung gekennzeichnet werden soll, hängt von Ihren Geschäftsregeln ab. Das wichtigste Prinzip ist, vor dem Überschreiben zu vergleichen, damit eine Anreicherungsquelle genaue Daten nicht stillschweigend ersetzt.

Schritt 3: Schreiboperation ausführen

Übergeben Sie den validierten und angereicherten Datensatz an die Salesforce-Schreiboperation. Verwenden Sie sf.operation, um die richtige Operation aufzurufen:

If($sf.operation == "create",
    RunOperation("<TAG>operation:Salesforce - Create Lead</TAG>");
,
    RunOperation("<TAG>operation:Salesforce - Update Lead</TAG>");
);

Verwenden Sie für beide Operationen eine Transformation, die $lead.*-Variablen den entsprechenden Salesforce-Lead-Feldern zuordnet. Ordnen Sie für die Update-Operation auch sf.existingLeadId dem Feld Id zu, damit Salesforce den zu aktualisierenden Datensatz identifizieren kann.

Teil 4: Genehmigungs-Gate für LLM implementieren

In agentengesteuerten Workflows, bei denen ein Sprachmodell Benutzeranfragen verarbeitet und an CRM-Schreibvorgänge weiterleitet, implementieren Sie einen expliziten zweistufigen Bestätigungs-dann-Ausführungs-Ablauf. Das Genehmigungs-Gate stellt sicher, dass die Absicht eines Benutzers, einen Kontakt zu erstellen oder zu aktualisieren, immer vor dem Schreibvorgang bestätigt wird. Eine Aussage wie „diesen Kontakt hinzufügen" gilt nicht als Genehmigung.

Dieses Muster verwendet LLM-Funktionsaufrufe, um zwischen Stufen zu leiten. Eine Einführung in Funktionsaufrufe in Studio finden Sie unter LLM-Antworten mit Funktionsaufrufen zu Studio-Operationen leiten.

Schritt 1: Genehmigungsregeln in der System-Nachricht definieren

Fügen Sie einen Abschnitt mit Genehmigungsregeln zur System-Nachricht hinzu, der das Modell anweist, wie es bestimmt, ob explizite Genehmigung erteilt wurde. Beziehen Sie diesen Text als distinken Block in die Systemnachricht ein, vor der Beschreibung verfügbarer Funktionen:

Approval rules (important):
- A user request to "clean", "update", "create", "add", or "insert" contacts does NOT
  count as approval by itself.
- Approval is valid ONLY IF:
  a) The assistant explicitly asked for confirmation to create or update a contact
     in a previous message, AND
  b) The user responded with a clear approval phrase such as: "yes", "proceed",
     "approved", or "go ahead".
- If the assistant has NOT asked for confirmation previously, you MUST select
  "confirm_create_contact" or "confirm_update_contact" depending on whether the
  action is a create or an update.
- If the assistant previously asked for confirmation and the user responds with
  "no", "not approved", or "do not create", route to "process_response".

Die Unterscheidung zwischen „angefordert" und „genehmigt" ist die Schlüsselregel. Das Modell überprüft den Gesprächsverlauf, um bei jedem Durchlauf zu bestimmen, welcher Fall zutrifft.

Schritt 2: Routing-Funktionen definieren

Registrieren Sie vier Routing-Funktionen im Tool-Manifest, das an das LLM übergeben wird:

Beschreiben Sie jede Funktion deutlich im Manifest. Die Funktionsbeschreibungen haben das gleiche Gewicht wie die System-Prompt-Regeln, wenn das Modell entscheidet, welche Funktion aufgerufen werden soll.

Schritt 3: Routing-Antworten Studio-Operationen zuordnen

Im Controller-Script, das nach jeder LLM-Antwort ausgeführt wird, extrahieren Sie function_name aus dem Tool-Aufruf und führen Sie die entsprechende Operation aus:

$route = TrimChars(
    GetJSONString($jitterbit.response, "/choices/[0]/message/tool_calls/[0]/function/name"),
    "\""
);

Case(
    $route == "confirm_create_contact",
        RunOperation("<TAG>operation:LLM - Confirm Create Contact</TAG>");
    ,
    $route == "confirm_update_contact",
        RunOperation("<TAG>operation:LLM - Confirm Update Contact</TAG>");
    ,
    $route == "execute_create_contact",
        RunOperation("<TAG>operation:Validate and Enrich Lead</TAG>");
        RunOperation("<TAG>operation:Salesforce - Create Contact</TAG>");
    ,
    $route == "execute_update_contact",
        RunOperation("<TAG>operation:Validate and Enrich Lead</TAG>");
        RunOperation("<TAG>operation:Salesforce - Update Contact</TAG>");
    ,
    true,
        RunOperation("<TAG>operation:LLM - Process Response</TAG>");
);

Die Operation Validate and Enrich Lead führt die Feldvalidierungs- und Anreicherungs-Pipeline (Teile 1–3) vor dem Salesforce-Schreibvorgang aus. Durch die Trennung der Validierung vom Routing-Script wird der Validierungsschritt außerhalb des agentengesteuerten Kontexts wiederverwendbar.

Schritt 4: Konversationsverlauf in jeden LLM-Aufruf einbeziehen

Das Approval Gate hängt davon ab, dass das Modell weiß, ob es bereits eine Bestätigung im aktuellen Gespräch angefordert hat. Damit die Genehmigungsregeln ordnungsgemäß funktionieren, muss jeder LLM-Aufruf den vollständigen Konversationsverlauf im Array messages enthalten, nicht nur die aktuelle Benutzernachricht.

Informationen zum verwendeten Muster zum Akkumulieren und Speichern des Konversationsverlaufs über mehrere Operationsläufe hinweg finden Sie unter Erstellen Sie einen mehrteiligen LLM-Chat mit Konversationsverlauf.

Die Integration überprüfen

1. Führen Sie die Pre-Write-Pipeline mit einem Testeintrag aus, bei dem die E-Mail-Adresse fehlt. Bestätigen Sie, dass das Validierungsscript einen Fehler auslöst und dass die Salesforce-Schreiboperation niemals aufgerufen wird. Überprüfen Sie die Operationsprotokolle auf die Fehlermeldung.

2. Führen Sie die Pipeline mit einer gültigen E-Mail-Adresse aus, die mit einem vorhandenen Salesforce-Lead übereinstimmt. Bestätigen Sie, dass sf.existingLeadId ausgefüllt ist und dass sf.operation auf update gesetzt ist.

3. Führen Sie die Pipeline mit einer E-Mail-Adresse aus, die keinem Salesforce-Datensatz entspricht. Bestätigen Sie, dass sf.existingLeadId leer ist und dass sf.operation auf create gesetzt ist.

4. Wenn Sie ZoomInfo-Anreicherung verwenden: Führen Sie den Anreicherungsschritt für einen bekannten Kontakt aus und bestätigen Sie, dass zoom.enriched.phone und zoom.enriched.title vor der Ausführung der Salesforce-Schreiboperation ausgefüllt sind.

5. Um das LLM-Approval Gate zu testen: Senden Sie dem Agent eine Nachricht wie „create a contact for Jane Smith at Acme Corp". Bestätigen Sie, dass das Modell zu confirm_create_contact anstelle von execute_create_contact weitergeleitet wird.

6. Antworten Sie auf die Bestätigungsaufforderung mit „yes, go ahead" und bestätigen Sie, dass das Modell in der nächsten Runde zu execute_create_contact weitergeleitet wird.

7. Um die Ablehnung zu testen: Nachdem das Modell eine Bestätigung anfordert, antworten Sie mit „no, don't create it". Bestätigen Sie, dass das Modell zu process_response weitergeleitet wird und dass die Salesforce-Schreiboperation nicht aufgerufen wird.