HubSpot-Formularübermittlungen in Salesforce in Jitterbit Studio synchronisieren

Einführung

HubSpot-Formularübermittlungen treffen als paginierte Liste ein, in der jede Übermittlung ein Array von Name/Wert-Paaren (ein Paar pro Formularfeld) statt eines flachen Datensatzes mit benannten Eigenschaften enthält. Diese Anleitung zeigt, wie man diese Übermittlungen mithilfe der HubSpot Forms Submissions API über den HTTP v2-Connector abruft, sie einzeln durch das SelectNodes-Schleifenmuster von Studio versendet, die E-Mail-Adresse, den Vornamen und den Nachnamen aus dem Werte-Array extrahiert, Salesforce auf einen vorhandenen Lead überprüft und einen Lead-Datensatz basierend auf dem Ergebnis erstellt oder aktualisiert.

Diese Anleitung verwendet:

• Den HTTP v2-Connector zum Aufrufen der HubSpot Forms Submissions API.
• Studio-Zwischenspeicher zum Speichern des vollständigen Übermittlungs-Batches zwischen dem Abrufschritt und der Schleife zur Verarbeitung einzelner Datensätze.
• SelectNodes und ReadFile zum Durchlaufen gespeicherter XML-Datensätze.
• SfLookupAll zum Erkennen doppelter Leads nach E-Mail-Adresse.
• Die Aktivitäten „Erstellen" und „Aktualisieren" des Salesforce-Connectors zum Schreiben des Lead-Datensatzes.

Diese Anleitung setzt ein HubSpot-Konto mit einer privaten App und einem Zugriffstoken voraus. Man benötigt die GUID des Formulars, dessen Übermittlungen man synchronisieren möchte. Jedes HubSpot-Formular hat eine eindeutige GUID, die in der Formular-Editor-URL oder über die HubSpot Forms API sichtbar ist.

Designmuster

Die Integration läuft in zwei Phasen ab: ein Batch-Abruf, der alle Übermittlungen für ein Formular abruft und als XML speichert, und eine Schleife pro Datensatz, die jede Übermittlung einzeln verarbeitet.

Der Batch-Abruf läuft einmal pro Formularsynchronisierung. Die Schleife pro Datensatz läuft einmal pro Übermittlung.

Teil 1: Projektvariablen und die HTTP v2-Verbindung konfigurieren

Schritt 1: Projektvariablen erstellen

Speichern Sie das HubSpot-Zugriffstoken und die Formular-GUID als Projektvariablen, damit sie aktualisiert werden können, ohne Skripte zu bearbeiten. Öffnen Sie das Menü für Projektaktionen und wählen Sie Projektvariablen. Fügen Sie dann folgende hinzu:

Markieren Sie hubspot.access.token als verborgen. Hinweise zum sicheren Speichern von Anmeldedaten finden Sie unter Endpunkt-Anmeldedaten verwalten.

Schritt 2: Die HTTP v2-Verbindung konfigurieren

1. Öffnen Sie in Studio Ihr Projekt und klicken Sie auf die Registerkarte Projektendpunkte und Connectors in der Design-Komponentenpalette.

2. Klicken Sie auf den HTTP v2-Connector, um den Bildschirm zur Verbindungskonfiguration zu öffnen.

3. Verbindungsname: Geben Sie HubSpot API ein.

4. Basis-URL: Geben Sie https://api.hubapi.com ein.

5. Autorisierung: Wählen Sie Bearer Token und geben Sie [$hubspot.access.token] als Token-Wert ein.

6. Klicken Sie auf Test, um die Verbindung zu überprüfen, und klicken Sie dann auf Änderungen speichern.

Schritt 3: Die Aktivität „GET Form Submissions" erstellen

1. Ziehen Sie aus der Verbindung HubSpot API eine GET-Aktivität auf die Design-Canvas.

2. Name: Geben Sie HubSpot - GET Form Submissions ein.

3. Pfad: Geben Sie /form-integrations/v1/submissions/forms/[$hubspot.form.guid] ein.

   Studio ersetzt [$hubspot.form.guid] zur Laufzeit durch den Projektvariablenwert. Um ein anderes Formular zu synchronisieren, aktualisieren Sie die Projektvariable, ohne die Aktivitätskonfiguration zu ändern.

4. Fügen Sie auf der Registerkarte Anfrage einen Header hinzu:

   • Schlüssel: Content-Type
   • Wert: application/json

5. Klicken Sie auf Fertig.

Teil 2: Übermittlungen abrufen und in temporären Speicher schreiben

Schritt 1: Den Abrufvorgang erstellen

Erstellen Sie einen Vorgang namens HubSpot - Fetch Form Submissions mit diesen Schritten in der angegebenen Reihenfolge:

1. Script: Initialisieren Sie die Variablen, die bei der Verarbeitung pro Datensatz verwendet werden:

   // Reset per-run staging variables
   $hubspot.email = "";
   $hubspot.firstName = "";
   $hubspot.lastName = "";
   
   WriteToOperationLog("Starting HubSpot form submission sync for form: " + [$hubspot.form.guid]);
   

2. GET-Aktivität: Platzieren Sie die Aktivität HubSpot - GET Form Submissions als Quellschritt.

3. Transformation: Fügen Sie nach der GET-Aktivität eine Transformation mit einer Aktivität Temporary Storage Write als Ziel hinzu. Ordnen Sie das JSON-Quellschema dem Zielschema auf den Schleifenebenen results/item und results/item/values/item zu, sodass alle Übermittlungsdatensätze in einem einzigen Durchgang in den temporären Speicher geschrieben werden.

   Benennen Sie die Transformation HubSpot - Write Submissions to Temp Storage und benennen Sie die Aktivität „Temporary Storage Write" Write HubSpot Submissions.

Die Aktivität „Temporary Storage Write" speichert die Übermittlungsdatensätze als XML. Studio schreibt jedes Element auf der innersten Schleifenebene als DocInfo-Element, das ist das Format, das die Dispatch-Schleife in Teil 3 liest.

Schritt 2: Den Fall behandeln, in dem keine Übermittlungen gefunden werden

Fügen Sie nach der Transformation einen Script-Schritt hinzu. Überprüfen Sie die Übermittlungsanzahl vor dem Starten der Schleife:

$count = Length(SelectNodes(
    ReadFile("<TAG>activity:tempstorage/HubSpot Temp Storage/tempstorage_read/Read HubSpot Submissions</TAG>"),
    "//DocInfo"
));

If($count == 0,
    WriteToOperationLog("No HubSpot submissions found. Exiting.");
    CancelOperation("<TAG>operation:HubSpot - Fetch Form Submissions</TAG>");
,
    WriteToOperationLog("Found " + $count + " submission(s) to process.");
);

CancelOperation bricht den aktuellen Vorgang sauber ab, ohne einen Fehler auszulösen, wenn keine Übermittlungen vorhanden sind.

Teil 3: Übermittlungen einzeln verteilen

Schritt 1: Das Dispatch-Script hinzufügen

Fügen Sie einen Script-Schritt zum Vorgang HubSpot - Fetch Form Submissions nach der Anzahlprüfung hinzu. Dieses Script liest den gespeicherten Batch, extrahiert einzelne Übermittlungsdatensätze mit SelectNodes und ruft einen Vorgang pro Datensatz einmal pro Übermittlung auf:

data = ReadFile("<TAG>activity:tempstorage/HubSpot Temp Storage/tempstorage_read/Read HubSpot Submissions</TAG>");
nodes = SelectNodes(data, "//DocInfo");
counts = Length(nodes);

WriteToOperationLog("Dispatching " + counts + " submission(s).");
i = 0;
While(i < counts,
    node = nodes[i];

    // Wrap the single node so the per-record operation has a valid XML source
    xml = "<SubmissionBatch><Submissions>" + String(node) + "</Submissions></SubmissionBatch>";

    WriteFile(
        "<TAG>activity:tempstorage/HubSpot Temp Storage 2/tempstorage_write/Write Single HubSpot Submission</TAG>",
        xml
    );
    FlushFile(
        "<TAG>activity:tempstorage/HubSpot Temp Storage 2/tempstorage_write/Write Single HubSpot Submission</TAG>"
    );

    RunOperation("<TAG>operation:HubSpot - Process Single Submission</TAG>");
    i = i + 1;
);

Der Wrapper <SubmissionBatch><Submissions> ist ein fester äußerer Container, der der Quelltransformation des Vorgangs pro Datensatz ein vorhersehbares Stammelement bietet. Der extrahierte DocInfo-Knoten wird zum inneren Element, das die Transformation zuordnet.

FlushFile erzwingt den Abschluss des Schreibvorgangs, bevor RunOperation den Vorgang pro Datensatz aufruft. Ohne Leerung kann der Vorgang die Daten des vorherigen Datensatzes lesen.

Schritt 2: Temporären Speicher für die Verteilung pro Datensatz einrichten

Konfigurieren Sie einen zweiten Endpunkt für temporären Speicher (z. B. HubSpot Temp Storage 2) mit:

• Eine Write-Aktivität namens Write Single HubSpot Submission.
• Eine Read-Aktivität namens Read Single HubSpot Submission, die als Quelle im Vorgang pro Datensatz verwendet wird.

Die beiden Endpunkte halten den vollständigen Batch und den Puffer pro Datensatz getrennt, sodass die Dispatch-Schleife die Quelldaten, über die sie iteriert, nicht überschreibt.

Teil 4: Feldwerte aus der Übermittlung extrahieren

HubSpot-Formularübermittlungen speichern Feldwerte als values-Array von Name/Wert-Objekten. Der Feldname (email, firstname, lastname) befindet sich im Feld name, und der übermittelte Wert befindet sich im Feld value. Die Transformation muss beide Ebenen durchlaufen (results/item für jede Übermittlung und das verschachtelte values/item für jedes Feld) und das Feld name lesen, um zu wissen, welche Variable gefüllt werden soll.

Schritt 1: Erstelle die Operation pro Datensatz

Erstelle eine Operation mit dem Namen HubSpot - Process Single Submission. Die Quelle ist die Aktivität Read Single HubSpot Submission Temporary Storage Read.

Schritt 2: Erstelle die Feldextraktions-Transformation

Füge der Operation pro Datensatz eine Transformation mit dem Namen HubSpot - Extract Submission Fields hinzu. Definiere zwei Schleifenebenen in der Transformation:

• Äußere Schleife: results/item in der Quelle, Zuordnung zum entsprechenden Zielpfad.
• Innere Schleife: results/item/values/item in der Quelle, verschachtelt innerhalb der äußeren Schleife.

Füge in der inneren Schleife diese Zuordnungsskripte hinzu:

Für den Zielknoten values/item/name:

$hubspot.fieldName = json$results$item.values$item.name$

Für den Zielknoten values/item/value:

If($hubspot.fieldName == "email",
    $hubspot.email = json$results$item.values$item.value$
);
If($hubspot.fieldName == "firstname",
    $hubspot.firstName = json$results$item.values$item.value$
);
If($hubspot.fieldName == "lastname",
    $hubspot.lastName = json$results$item.values$item.value$
);

Für den äußeren Zielknoten results/item/pageUrl (der nach Abschluss der inneren Schleife für jede Übermittlung ausgelöst wird), rufe die Salesforce-Prüfoperation auf:

If(Length(Trim($hubspot.email)) > 0,
    $hubspot.email = ToLower(Trim($hubspot.email));
    RunOperation("<TAG>operation:HubSpot - Check Salesforce Lead</TAG>");
,
    WriteToOperationLog("Submission missing email field. Skipping.");
);

Die pageUrl-Zuordnung wird einmal pro Übermittlungsdatensatz ausgeführt, nachdem alle seine values/item-Kinder verarbeitet wurden. Dies ist der richtige Ort, um die nachgelagerte Salesforce-Operation auszulösen. Die Normalisierung der E-Mail auf Kleinbuchstaben vor der Suche verhindert Fehler bei der Groß-/Kleinschreibung bei der Suche in Salesforce-Datensätzen.

Teil 5: Überprüfe Salesforce auf einen vorhandenen Lead

Schritt 1: Erstelle die Salesforce-Prüfoperation

Erstelle eine Operation mit dem Namen HubSpot - Check Salesforce Lead. Füge einen Script-Schritt als einzigen Operationsschritt hinzu:

$sf.existingLeadId = "";

$result = SfLookupAll(
    "<TAG>endpoint:salesforce/Salesforce</TAG>",
    "SELECT Id FROM Lead WHERE Email = '"
        + $hubspot.email
        + "' AND IsConverted = false LIMIT 1"
);

If(Length($result) > 0,
    $sf.existingLeadId = $result[0][0];
    WriteToOperationLog("Existing lead found: " + $sf.existingLeadId);
    RunOperation("<TAG>operation:HubSpot - Update Salesforce Lead</TAG>");
,
    WriteToOperationLog("No existing lead for: " + $hubspot.email);
    RunOperation("<TAG>operation:HubSpot - Create Salesforce Lead</TAG>");
);

SfLookupAll gibt ein zweidimensionales Array zurück: Jedes innere Array ist eine Ergebniszeile, und jedes Element ist ein Feldwert in der Reihenfolge, die in der SELECT-Klausel aufgelistet ist. $result[0][0] ist das Feld Id aus der ersten (und einzigen) zurückgegebenen Zeile. LIMIT 1 verhindert, dass mehrere Treffer einen Array-Indexfehler verursachen, wenn dieselbe E-Mail in mehr als einem Lead-Datensatz vorhanden ist.

IsConverted = false schließt Leads aus, die bereits in Kontakte, Chancen oder Konten konvertiert wurden. Das Aktualisieren eines konvertierten Leads in Salesforce führt zu einem Fehler. Daher ist es sicherer, diese zu überspringen und den Erstellungspfad den Grenzfall bei Bedarf separat behandeln zu lassen.

Für das SOQL-Abfragemuster siehe Salesforce-Datensätze mit SOQL abfragen.

Teil 6: Erstelle oder aktualisiere den Salesforce Lead

Schritt 1: Erstelle den Lead-Datensatz

Erstelle eine Operation mit dem Namen HubSpot - Create Salesforce Lead. Füge einen Transformation-Schritt hinzu, der die Staging-Variablen einer Salesforce-Aktivität Create zuordnet, die auf das Objekt Lead abzielt:

Lege einen Literalwert für LeadSource fest, um alle von dieser Integration erstellten Leads zu kennzeichnen und Berichte zu erstellen.

Die Salesforce Create-Aktivität gibt die neue Datensatz-ID zurück. Erfasse sie zur Verwendung im optionalen Anreicherungsschritt:

$sf.newLeadId = TrimChars(
    GetJSONString($jitterbit.response, "/id"),
    "\""
);
WriteToOperationLog("Created Salesforce lead: " + $sf.newLeadId);

Rufe nach dem Erfassen der ID die ZoomInfo-Anreicherungsoperation auf, um zusätzliche Felder auszufüllen (siehe Teil 7):

If(Length($sf.newLeadId) > 0,
    RunOperation("<TAG>operation:ZoomInfo - Enrich Lead</TAG>")
);

Schritt 2: Aktualisiere den vorhandenen Lead-Datensatz

Erstelle eine Operation mit dem Namen HubSpot - Update Salesforce Lead. Füge einen Transformation-Schritt hinzu, der einer Salesforce-Aktivität Update zugeordnet wird, die auf das Objekt Lead abzielt. Die Update-Aktivität erfordert das Feld Id, um den Datensatz zu identifizieren:

Nur die Felder zuordnen, die die Integration besitzt. Wenn man Felder aus der Transformation weglässt, bleiben die vorhandenen Werte im Salesforce-Datensatz erhalten.

Teil 7: Neue Leads mit ZoomInfo anreichern

Nach dem Erstellen eines neuen Salesforce-Leads verwendet ein optionaler Anreicherungsschritt ZoomInfo, um die aktuelle Berufsbezeichnung, das Unternehmen und die direkte Telefonnummer des Kontakts auszufüllen. Der Anreicherungsvorgang ruft den ZoomInfo-Anreicherungs-Endpunkt mit der Lead-E-Mail und dem Unternehmensname als Suchschlüssel auf und aktualisiert dann den Salesforce-Lead mit den zurückgegebenen Daten.

Informationen zur ZoomInfo-API-Verbindungseinrichtung und zum Resource-Router-Muster, das in diesem Schritt verwendet wird, finden Sie unter Kontaktdaten mit ZoomInfo anreichern.

Integration überprüfen

1. Öffnen Sie in HubSpot das Formular, das Sie synchronisieren, und senden Sie einen Test-Eintrag mit einer eindeutigen E-Mail-Adresse ein, die nicht in Salesforce vorhanden ist. Führen Sie HubSpot - Fetch Form Submissions manuell aus und überprüfen Sie die Vorgangsprotokolle. Bestätigen Sie, dass das Protokoll die korrekte Anzahl der Einreichungen anzeigt und dass HubSpot - Create Salesforce Lead für die Test-Einreichung ausgeführt wurde.

2. Suchen Sie in Salesforce nach dem Lead-Datensatz anhand der Test-E-Mail-Adresse. Bestätigen Sie, dass FirstName, LastName und Email ausgefüllt sind und dass LeadSource auf HubSpot gesetzt ist.

3. Senden Sie einen zweiten Test-Eintrag mit derselben E-Mail-Adresse ein. Führen Sie den Abrufvorgang erneut aus und bestätigen Sie, dass HubSpot - Update Salesforce Lead statt des Erstellungsvorgangs ausgeführt wurde und dass der vorhandene Salesforce-Lead aktualisiert und nicht dupliziert wurde.

4. Testen Sie den Fall der leeren Einreichung, indem Sie den Vorgang für ein Formular ohne Einreichungen ausführen. Bestätigen Sie, dass die Vorgangsprotokolle „No HubSpot submissions found" anzeigen und dass keine Salesforce-Vorgänge aufgerufen wurden.

5. Um eine Einreichung ohne E-Mail-Feld zu testen, fügen Sie vorübergehend einen Test-Eintrag ohne E-Mail hinzu. Bestätigen Sie, dass das Protokoll „Submission missing email field. Skipping." anzeigt und dass keine Salesforce-Vorgänge für diesen Datensatz ausgeführt wurden.

6. Wenn die GET-Aktivität einen 401-Fehler zurückgibt, bestätigen Sie, dass [$hubspot.access.token] gesetzt ist und dass das private App-Zugriffstoken nicht abgelaufen ist. HubSpot-Token für private Apps laufen standardmäßig nicht ab, können aber rotiert werden. Überprüfen Sie das Token in den Einstellungen der HubSpot-Private-App.

7. Wenn SelectNodes trotz der von der GET-Aktivität zurückgegebenen Daten null Knoten zurückgibt, bestätigen Sie, dass die Transformation in Teil 2 auf der Ebene results/item eine Schleife durchläuft und dass die Temporary Storage Write-Aktivität vor dem Dispatch-Skript abgeschlossen wurde.