HubSpot-Formulareinreichungen in Salesforce in Jitterbit Studio synchronisieren

Einführung

HubSpot-Formulareinreichungen werden als paginierte Liste bereitgestellt, bei der jede Einreichung ein Array von Name/Wert-Paaren (ein Paar pro Formularfeld) anstelle eines flachen Datensatzes mit benannten Eigenschaften enthält. Diese Anleitung zeigt, wie diese Einreichungen mithilfe der HubSpot Forms Submissions API über den HTTP v2-Connector abgerufen werden, sie einzeln nacheinander über das SelectNodes-Loop-Muster von Studio verteilt werden, die E-Mail-Adresse, der Vorname und der Nachname aus dem Values-Array extrahiert werden, Salesforce auf einen vorhandenen Lead überprüft wird, und ein Lead-Datensatz basierend auf dem Ergebnis erstellt oder aktualisiert wird.

Diese Anleitung verwendet:

• Den HTTP v2-Connector zum Aufrufen der HubSpot Forms Submissions API.
• Temporären Studio-Speicher, um den vollständigen Einreichungs-Batch zwischen dem Abrufschritt und der Pro-Datensatz-Verteilungsschleife zu speichern.
• SelectNodes und ReadFile zum Durchlaufen gespeicherter XML-Datensätze.
• SfLookupAll zum Erkennen doppelter Leads nach E-Mail-Adresse.
• Die Create- und Update-Aktivitäten des Salesforce-Connectors zum Schreiben des Lead-Datensatzes.

Diese Anleitung setzt ein HubSpot-Konto mit einer Private App und einem Zugriffstoken voraus. Sie benötigen die GUID des Formulars, dessen Einreichungen Sie synchronisieren möchten. 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 Stufen ab: Ein Batch-Abruf, der alle Einreichungen für ein Formular abruft und als XML speichert, und eine Pro-Datensatz-Schleife, die jede Einreichung einzeln verarbeitet.

Der Batch-Abruf wird einmal pro Formular-Synchronisierung ausgeführt. Die Pro-Datensatz-Schleife wird einmal pro Einreichung ausgeführt.

Teil 1: Projektvariablen und 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 Skripts zu bearbeiten. Öffnen Sie das Aktionsmenü des Projekts und wählen Sie Projektvariablen aus. Fügen Sie dann Folgendes hinzu:

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

Schritt 2: HTTP v2-Verbindung konfigurieren

1. Öffnen Sie in Studio Ihr Projekt und klicken Sie im Design-Komponentenbereich auf die Registerkarte Projektendpunkte und Connectoren.

2. Klicken Sie auf den HTTP v2-Connector, um den Verbindungskonfigurationsbildschirm 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 aus 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 GET Forms Submissions-Aktivität erstellen

1. Ziehen Sie aus der HubSpot API-Verbindung 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: Abrufoperation erstellen

Erstellen Sie eine Operation namens HubSpot - Fetch Form Submissions mit folgenden Schritten in dieser 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 HubSpot - GET Form Submissions-Aktivität als Quellenschritt.

3. Transformation: Fügen Sie eine Transformation nach der GET-Aktivität mit einer Temporary Storage Write-Aktivität als Ziel hinzu. Ordnen Sie das JSON-Quellenschema dem Zielschema auf der results/item- und results/item/values/item-Schleifenebene zu, damit 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 Temporary Storage Write-Aktivität Write HubSpot Submissions.

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

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

Fügen Sie einen Script-Schritt nach der Transformation hinzu. Überprüfen Sie die Anzahl der Übermittlungen 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 die aktuelle Operation ordnungsgemäß ab, ohne einen Fehler auszulösen, wenn keine Übermittlungen vorhanden sind.

Teil 3: Übermittlungen nacheinander verarbeiten

Schritt 1: Dispatch-Script hinzufügen

Fügen Sie einen Script-Schritt zur Operation HubSpot - Fetch Form Submissions nach der Anzahlprüfung hinzu. Dieses Script liest den gespeicherten Batch, extrahiert einzelne Übermittlungsdatensätze mit SelectNodes und ruft eine Operation 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 <SubmissionBatch><Submissions>-Wrapper ist ein fester äußerer Container, der der Quelltransformation der Operation pro Datensatz ein vorhersehbares Wurzelelement bietet. Der extrahierte DocInfo-Knoten wird zum inneren Element, das die Transformation zuordnet.

FlushFile erzwingt, dass der Schreibvorgang abgeschlossen wird, bevor RunOperation die Operation pro Datensatz aufruft. Ohne Leeren kann die Operation die Daten des vorherigen Datensatzes lesen.

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

Konfigurieren Sie einen zweiten Temporary Storage-Endpunkt (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 in der Operation pro Datensatz verwendet wird.

Die beiden Endpunkte halten den vollständigen Batch und den Puffer pro Datensatz getrennt, damit 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 name-Feld und der übermittelte Wert im value-Feld. Die Transformation muss beide Ebenen durchlaufen (results/item für jede Übermittlung und das verschachtelte values/item für jedes Feld) und das name-Feld lesen, um zu wissen, welche Variable gefüllt werden soll.

Schritt 1: Der Pro-Datensatz-Operation erstellen

Erstellen Sie eine Operation namens HubSpot - Process Single Submission. Die Quelle ist die Aktivität Read Single HubSpot Submission Temporary Storage Read.

Schritt 2: Die Feldextraktions-Transformation erstellen

Fügen Sie der Pro-Datensatz-Operation eine Transformation namens HubSpot - Extract Submission Fields hinzu. Definieren Sie 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ügen Sie 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 (wird ausgelöst, nachdem die innere Schleife für jede Übermittlung abgeschlossen ist), rufen Sie die Salesforce-Check-Operation 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 untergeordneten values/item verarbeitet wurden. Dies macht es zum richtigen Ort, um die nachgelagerte Salesforce-Operation auszulösen. Das Normalisieren der E-Mail in Kleinbuchstaben vor der Suche verhindert Fehler bei der Berücksichtigung der Groß- und Kleinschreibung beim Vergleich mit Salesforce-Datensätzen.

Teil 5: Salesforce auf einen vorhandenen Lead überprüfen

Schritt 1: Die Salesforce-Check-Operation erstellen

Erstellen Sie eine Operation namens HubSpot - Check Salesforce Lead. Fügen Sie 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 aufgeführt 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, sie zu überspringen und den Erstellungspfad das Grenzfall bei Bedarf separat zu behandeln.

Informationen zum SOQL-Abfragemuster finden Sie unter Salesforce-Datensätze mit SOQL abfragen.

Teil 6: Den Salesforce Lead erstellen oder aktualisieren

Schritt 1: Den Lead-Datensatz erstellen

Erstellen Sie eine Operation namens HubSpot - Create Salesforce Lead. Fügen Sie einen Transformation-Schritt hinzu, der die Staging-Variablen einer Salesforce-Aktivität Create (Erstellen) zuordnet, die auf das Lead-Objekt abzielt:

Legen Sie einen Literalwert für LeadSource fest, um alle von dieser Integration erstellten Leads zu Berichtszwecken zu kennzeichnen.

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

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

Nach dem Erfassen der ID rufen Sie 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: Den vorhandenen Lead-Datensatz aktualisieren

Erstellen Sie eine Operation namens HubSpot - Update Salesforce Lead. Fügen Sie einen Transformation-Schritt hinzu, der einer Salesforce-Aktivität Update (Aktualisieren) zugeordnet wird, die auf das Lead-Objekt 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-Endpunkt mit der Lead-E-Mail und dem Unternehmensname als Suchschlüssel auf und aktualisiert anschließend 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 mithilfe von ZoomInfo anreichern.

Integration überprüfen

1. Öffnen Sie in HubSpot das Formular, das Sie synchronisieren, und übermitteln Sie einen Testeintrag mit einer eindeutigen E-Mail-Adresse, 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 Übermittlungsanzahl anzeigt und dass HubSpot - Create Salesforce Lead für den Testeintrag 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 eingestellt ist.

3. Übermitteln Sie einen zweiten Testeintrag mit derselben E-Mail-Adresse. 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 leerer Übermittlung, indem Sie den Vorgang für ein Formular ohne Übermittlungen ausführen. Bestätigen Sie, dass die Vorgangsprotokolle „No HubSpot submissions found" anzeigen und dass keine Salesforce-Vorgänge aufgerufen wurden.

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

6. Wenn die GET-Aktivität einen 401-Fehler zurückgibt, bestätigen Sie, dass [$hubspot.access.token] eingestellt 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 privaten HubSpot-App.

7. Wenn SelectNodes keine Knoten zurückgibt, obwohl die GET-Aktivität Daten zurückgibt, bestätigen Sie, dass die Transformation in Teil 2 auf der Ebene results/item wiederholt wird und dass die Temporary Storage Write-Aktivität vor dem Dispatch-Skript abgeschlossen wurde.