Workflow-Aktionen mit benutzerdefiniertem Code

Verwenden Sie in Workflows die Aktion Benutzerdefinierte Code, um JavaScript-Code oder Python-Code (in der Beta-Phase) zu schreiben und auszuführen. Mit Aktionen mit benutzerdefiniertem Code können Sie die Workflow-Funktionalität innerhalb und außerhalb von HubSpot erweitern. Um mehr über die APIs von HubSpot zu erfahren, können Sie sich entweder die Entwicklerdokumentation für die neuesten Versionen oder die frühere Entwicklerdokumentation für unsere älteren APIs ansehen. Beispiele für gängige benutzerdefinierte Code-Aktionen finden Sie in den Anwendungsfällen für programmierbare Automatisierung von HubSpot.

Aktionen mit benutzerdefiniertem Code unterstützen JavaScript über das Node 16.x-Runtime-Framework. Wenn Sie Python für Ihre benutzerdefinierte Code-Aktion verwenden, verwendet die benutzerdefinierte Code-Aktion das Runtime-Framework Python 3.9. Wenn eine Aktion ausgeführt wird, wird die Laufzeit-Verarbeitung über eine serverlose Funktion von HubSpot und AWS Lambda verwaltet.

Wenn Sie allgemeine Probleme bei der Implementierung Ihrer benutzerdefinierten Code-Aktion haben, wenden Sie sich bitte an den HubSpot-Support. Wenn Sie jedoch Probleme mit Ihrem geschriebenen benutzerdefinierten Code haben, wird empfohlen, im HubSpot-Entwicklerforum nach Tipps und Ratschläge zu suchen und Fragen zu stellen oder um Hilfe bei der Fehlerbehebung für Ihren Code zu bitten.

Unterstützte Node.js-Bibliotheken

Wenn Sie Node.js verwenden, stehen die folgenden Bibliotheken für die Verwendung innerhalb der Code-Aktion zur Verfügung. Die Bibliotheken können am Anfang Ihres Codes mit der normalen require()-Funktion geladen werden.

  • @hubspot/api-client ^10
  • async ^3.2.0
  • aws-sdk ^2.744.0
  • axios ^1.2.0
  • lodash ^4.17.20
  • mongoose ^6.8.0
  • mysql ^2.18.1
  • redis" ^4.5.1
  • request" ^2.88.2
  • bluebird ^3.7.2
  • random-number-csprng ^1.0.2
  • googleapis ^67.0.0
Bitte beachten: Die Zuordnungen-API (v4) wird in Version 9.0.0 oder höher des NodeJS-HubSpot-Clients und in Version 8 des NodeJS-HubSpot-Clients unterstützt.
 

Unterstützte Python-Bibliotheken

Wenn Sie Python verwenden, können Sie die folgenden Bibliotheken mit einer import-Anweisung oben im Code laden. Die import-Anweisung sollte als from [libraryname] import [item] formatiert sein, z. B. from redis.client import redis.

  • requests 2.28.2
  • @hubspot/api-client ^8
  • google-api-python-client 2.74.0
  • mysql-connector-python 8.0.32
  • redis 4.4.2
  • nltk 3.8.1

Wenn Sie etwas aus der Standardbibliothek verwenden, können Sie import verwenden, z. B. import os.

Get started

Verwenden Sie die Codebeispiele unten, um mit benutzerdefinierten Code-Workflow-Aktionen loszulegen. 

Code samples

NODE16X, v8
const hubspot = require('@hubspot/api-client'); exports.main = async (event, callback) => { /***** How to use secrets Secrets are a way for you to save API keys or private apps and set them as a variable to use anywhere in your code Each secret needs to be defined like the example below *****/ const hubspotClient = new hubspot.Client({ accessToken: process.env.SECRET_NAME }); let phone; try { const ApiResponse = await hubspotClient.crm.contacts.basicApi.getById(event.object.objectId, ["phone"]); phone = ApiResponse.properties.phone; } catch (err) { console.error(err); // We will automatically retry when the code fails because of a rate limiting error from the HubSpot API. throw err; } /***** How to use inputs Inputs are a way for you to take data from any actions in your workflow and use it in your code instead of having to call the HubSpot API to get that same data. Each input needs to be defined like the example below *****/ const email = event.inputFields['email']; /***** How to use outputs Outputs are a way for you to take data from your code and use it in later workflows actions Use the callback function to return data that can be used in later actions. Data won't be returned until after the event loop is empty, so any code after this will still execute. *****/ callback({ outputFields: { email: email, phone: phone } }); } /* A sample event may look like: { "origin": { // Your portal ID "portalId": 1, // Your custom action definition ID "actionDefinitionId": 2, }, "object": { // The type of CRM object that is enrolled in the workflow "objectType": "CONTACT", // The ID of the CRM object that is enrolled in the workflow "objectId": 4, }, "inputFields": { // The property name for defined inputs }, // A unique ID for this execution "callbackId": "ap-123-456-7-8" } */
NODE16X, v3
const hubspot = require('@hubspot/api-client'); exports.main = async (event, callback) => { /***** How to use secrets Secrets are a way for you to save API keys or private apps and set them as a variable to use anywhere in your code Each secret needs to be defined like the example below *****/ const hubspotClient = new hubspot.Client({ apiKey: process.env.SECRET_NAME }); let phone; try { const ApiResponse = await hubspotClient.crm.contacts.basicApi.getById(event.object.objectId, ["phone"]); phone = ApiResponse.body.properties.phone; } catch (err) { console.error(err); // We will automatically retry when the code fails because of a rate limiting error from the HubSpot API. throw err; } /***** How to use inputs Inputs are a way for you to take data from any actions in your workflow and use it in your code instead of having to call the HubSpot API to get that same data. Each input needs to be defined like the example below *****/ const email = event.inputFields['email']; /***** How to use outputs Outputs are a way for you to take data from your code and use it in later workflows actions Use the callback function to return data that can be used in later actions. Data won't be returned until after the event loop is empty, so any code after this will still execute. *****/ callback({ outputFields: { email: email, phone: phone } }); } /* A sample event may look like: { "origin": { // Your portal ID "portalId": 1, // Your custom action definition ID "actionDefinitionId": 2, }, "object": { // The type of CRM object that is enrolled in the workflow "objectType": "CONTACT", // The ID of the CRM object that is enrolled in the workflow "objectId": 4, }, "inputFields": { // The property name for defined inputs }, // A unique ID for this execution "callbackId": "ap-123-456-7-8" } */
PYTHON (für alle Versionen gleich)
import os from hubspot import HubSpot from hubspot.crm.contacts import ApiException def main(event): # How to use secrets # Secrets are a way for you to save API keys or private apps and set them as a variable to use anywhere in your code # Each secret needs to be defined like the example below hubspot = HubSpot(access_token=os.getenv('SECRET_NAME')) phone = '' try: ApiResponse = hubspot.crm.contacts.basic_api.get_by_id(event.get('object').get('objectId'), properties=["phone"]) phone = ApiResponse.properties.get('phone') except ApiException as e: print(e) # We will automatically retry when the code fails because of a rate limiting error from the HubSpot API. raise # How to use inputs # Inputs are a way for you to take data from any actions in your workflow and use it in your code instead of having to call the HubSpot API to get that same data. # Each input needs to be defined like the example below email = event.get('inputFields').get('email') # How to use outputs # Outputs are a way for you to take data from your code and use it in later workflows actions # Use the callback function to return data that can be used in later actions. # Data won't be returned until after the event loop is empty, so any code after this will still execute. return { "outputFields": { "email": email, "phone": phone } } # A sample event may look like: # { # "origin": { # # Your portal ID # "portalId": 1, # # Your custom action definition ID # "actionDefinitionId": 2, # }, # "object": { # # The type of CRM object that is enrolled in the workflow # "objectType": "CONTACT", # # The ID of the CRM object that is enrolled in the workflow # "objectId": 4, # }, # "inputFields": { # # The property name for defined inputs # }, # # A unique ID for this execution # "callbackId": "ap-123-456-7-8" # }

Eine benutzerdefinierte Code-Aktion erstellen

So fügen Sie eine benutzerdefinierte Code-Aktion zu Ihrem Workflow hinzu:

  • Gehen Sie in Ihrem HubSpot-Account zu Automatisierung > Workflows.
  • Klicken Sie auf den Namen eines Workflows oder erstellen Sie einen neuen Workflow. 
  • Klicken Sie auf das + Plus-Symbol, um eine Workflow-Aktion hinzuzufügen.
  • Wahlen Sie im rechten Bereich Benutzerdefinierter Code aus.
 

custom-code-action-select

  • Richten Sie im rechten Bereich Ihre Eigenschaft ein:
    • Standardmäßig verwenden benutzerdefinierte Code-Aktionen Node.js 16.x. Wenn Sie sich in der Python-Beta befinden und Ihre Aktion mit Python entwickeln möchten, klicken Sie auf das Dropdown-Menü Sprache und wählen Sie Python aus.
    • Um ein neues Geheimnis hinzuzufügen, z. B. ein Zugriffstoken von einer privaten App, klicken Sie auf Geheimnis hinzufügen. Die App muss die jeweiligen Bereiche aller Daten enthalten, die Sie aus HubSpot abrufen möchten, z. B. contacts oder forms.  Erfahren Sie mehr über private HubSpot-Apps.
    • Geben Sie im Dialogfeld den Geheimnisnamen und den Geheimniswert ein.
    • Klicken Sie auf Speichern. Sie können nun dieses Geheimnis in zukünftigen Aktionen mit benutzerdefiniertem Code auswählen.
    • Um vorhandene Geheimnisse zu bearbeiten oder zu löschen, klicken Sie auf Geheimnisse verwalten.
  • Um Eigenschaften in Ihren benutzerdefinierten Code aufzunehmen, klicken Sie auf das Dropdown-Menü Eigenschaften auswählen und wählen Sie dann eine Eigenschaft aus. Sie können vorhandene Eigenschaften oder zuvor formatierte Eigenschaftenwerte im Workflow verwenden. Nachdem Sie Ihre Eigenschaft ausgewählt haben, geben Sie einen Namen für die Eigenschaft ein, der in Ihrem Code verwendet werden soll. Erfahren Sie, wie Sie in Ihrem benutzerdefinierten Code auf eine Eigenschaft verweisen.
  • Klicken Sie auf Eigenschaft hinzufügen, um eine weitere Eigenschaft hinzuzufügen. Jede Eigenschaft kann nur einmal hinzugefügt werden und muss über eine eindeutige Variablen-ID verfügen.  Sie können bis zu 50 Eigenschaften mit Ihrem benutzerdefinierten Code verwenden. 
  • Um eine Eigenschaft zu löschen, kicken Sie auf das Symbol für Löschen.
  • Geben Sie im Code-Feld Ihren JavaScript- oder Python-Code ein.
  • So definieren Sie die Datenausgaben, die später als Eingaben im Workflow verwendet werden können, z. B. mit einer Eigenschaftswert kopieren-Aktion:
    • Klicken Sie unter Datenausgaben auf das Dropdown-Menü Dateityp und wählen Sie einen Datentyp aus.
    • Geben Sie im Feld Name einen Namen für die Datenausgabe ein.
    • Um mehrere Ausgaben hinzuzufügen, klicken Sie auf Ausgabe hinzufügen.
  • Klicken Sie auf Speichern.

workflow-custom-code

 

Bitte beachten: Das Code-Feld zeigt keine lint-Fehler an, wenn Python verwendet wird. 

Wenn Sie benutzerdefinierte Code-Aktionen erstellen, beachten Sie Folgendes:

  • Die def main(event):-Funktion wird aufgerufen, wenn die Code-Snippet-Aktion ausgeführt wird.
  • Das event-Argument ist ein Objekt, das Details für die Workflow-Ausführung enthält.
  • Die callback()-Funktion wird verwendet, um Daten zurück an den Workflow zu übergeben. Sie sollte in der exports.main-Funktion aufgerufen werden. Dies kann nur mit Node.js verwendet werden. 

Das event-Objekt enthält die folgenden Daten:

//example payload { "origin": { // Your portal ID "portalId": 1, // Your custom action definition ID "actionDefinitionId": 2, }, "object": { // The type of CRM object that is enrolled in the workflow "objectType": "CONTACT", // The ID of the CRM object that is enrolled in the workflow "objectId": 4, }, // A unique ID for this execution. "callbackId": "ap-123-456-7-8" }

Die Aktion testen

Wenn Sie eine benutzerdefinierte Code-Aktion zu einem Workflow hinzufügen, können Sie die Aktion testen, um sicherzustellen, dass Ihr Code wie erwartet ausgeführt wird, bevor Sie den Workflow aktivieren.

Wenn Sie eine benutzerdefinierte Code-Aktion testen, wählen Sie zunächst einen Datensatz aus, mit dem der Code getestet werden soll, und führen Sie dann den Code aus. Bei diesem Test wird nur der Code in Ihrer benutzerdefinierten Aktion ausgeführt, nicht in einer der anderen Aktionen im Workflow. Wenn der Code ausgeführt wurde, können Sie die Code-Ausgaben und das Protokoll Ihres Tests anzeigen.

Bitte beachten: Wenn Sie Ihren benutzerdefinierten Code testen, wird der Code ausgeführt und alle Änderungen gelten für den ausgewählten Testdatensatz. Es wird empfohlen, einen eigenen Testdatensatz zu erstellen, wenn Sie eine Aktualisierung Ihrer Live-Datensätze vermeiden möchten. 

So testen Sie eine benutzerdefinierte Code-Aktion:

  • Klicken Sie in der Workflow-Chronik auf die benutzerdefinierte Code-Aktion.
  • Klicken Sie am unteren Rand der rechten Seitenleiste auf Testaktion, um den Testabschnitt zu erweitern.
    workflow-custom-code-test-expand
  • Wählen Sie einen Datensatz zum Testen Ihres Codes aus, indem Sie auf das Dropdown-Menü Objekt klicken und dann einen Datensatz auswählen.
    workflow-custom-code-action-test2
  • Wenn Sie Werte von zuvor formatierten Eigenschaften im Workflow verwenden, geben Sie einen Testwert für die formatierten Daten ein.  

  • Um den Code auszuführen, klicken Sie auf Testen.
  • Bestätigen Sie im Dialogfeld, dass Sie Ihren Code mit dem ausgewählten Datensatz testen möchten, indem Sie auf Testen klicken.
  • Sobald Ihr Code ausgeführt wurde, zeigt die Seitenleiste die Ergebnisse Ihres Tests an:
    • Status: Der Erfolgs- oder Fehlerstatus Ihrer benutzerdefinierten Code-Aktion.
    • Datenausgaben: Die Werte, die sich für Ihre definierten Datenausgaben ergeben haben. Eine Warnung wird neben allen Ausgaben angezeigt, die der Code generiert hat und die weder im Abschnitt Datenausgaben noch im Code-Editor definiert wurden. Sie müssen diese Ausgaben hinzufügen, um sie später im Workflow verwenden zu können.
    • Protokolle: Informationen zum Test selbst, z. B. wie viel Speicher die Aktion benötigt hat, um ausgeführt zu werden, und die Gesamtlaufzeit. 

      workflow-custom-code-action-test0results0
  • Klicken Sie zum Aktualisieren der benutzerdefinierten Code-Aktion auf Aktion erstellen, um den Editor für Aktionen zu erweitern. Aktualisieren und testen Sie Ihren Code nach Bedarf.
  • Wenn Sie mit dem Testen der Aktion fertig sind, klicken Sie auf Speichern,um die Änderungen zu übernehmen.

Geheimnisse

Es kommt vor, dass Ihr Code auf etwas verweisen soll, das nicht für alle geteilt werden sollte. Meistens ist dies ein Mittel zur Authentifizierung, wie das Zugriffstoken von einer privaten App. Sie können die Geheimnisse, auf die Ihre Funktion Zugriff hat, direkt in der Definition einer Workflow-Aktion verwalten. Bei der Verwendung mehrerer Geheimnisse innerhalb eines benutzerdefinierten Codes darf die Gesamtlänge aller Geheimniswerte 1000 Zeichen nicht überschreiten.

workflow-custom-code-secrets

Nach dem Hinzufügen sind die Geheimnisse als Umgebungsvariablen verfügbar, auf die Sie im benutzerdefinierten Code zugreifen können, wie unten gezeigt:

const hubspot = require('@hubspot/api-client'); exports.main = (event, callback) => { return callback(processEvent(event)); };function processEvent(event) { // secrets can be accessed via environment variables const hubspotClient = new hubspot.Client({ accessToken: process.env.secretName }); hubspotClient.crm.contacts.basicApi.getById(event["object"]["objectId"], ["email", "phone"]) .then(results => { let email = results.body["properties"]["email"] let phone = results.body["properties"]["phone"] // ... }) .catch(err => { console.error(err) }) }

HubSpot-Eigenschaften zu Ihrem benutzerdefinierten Code hinzufügen

Manchmal müssen Sie möglicherweise Objekteigenschaften in Ihrer benutzerdefinierten Code-Aktion abrufen. Anstatt die APIs von HubSpot zu verwenden, können Sie diese Eigenschaften direkt in der Definition einer Workflow-Aktion hinzufügen. Fügen Sie Eigenschaften hinzu und legen Sie Eigenschaftsnamen fest, um Eigenschaften in Ihrem Code zu referenzieren. Sie können bis zu 50 Eigenschaften in jeder benutzerdefinierten Code-Aktion hinzufügen.  

Nach dem Hinzufügen kann die Eigenschaft im benutzerdefinierten Code referenziert werden. 

const email = event.inputFields['email']; email = event.get('inputFields').get('email')

Protokollierung

Ein wichtiges Tool für Entwickler ist die Möglichkeit, Ausgaben von ihrem Code zu drucken. Es hilft Ihnen, Probleme zu debuggen und Ihren Endbenutzern besseren Support zu bieten. Wenn Sie die Ausgabe der Protokolle anzeigen möchten, gehen Sie zur Registerkarte „Verlauf“ des Workflows.  

custom_code_logs

How to Define Outputs

Definieren Sie in der Funktion die Ausgabefelder, die Sie später im Workflow verwenden möchten. Wählen Sie dann in der rechten Seitenleiste den Datenausgabetyp aus (z. B. Zahl, Zeichenfolge, boolescher Wert, Datum/Uhrzeit, Enumeration, Datum/Telefonnummer) und geben Sie das Feld ein, das Sie ausgeben möchten.

Die Ausgabefelder sollten je nach verwendeter Sprache Teil eines entsprechend formatierten JSON-Objekts sein:

callback({ outputFields: { email: email, phone: phone } }); return { "outputFields": { "email": email, "phone": phone } }
custom-code-output

Sie können dann die Ausgabe Ihrer Code-Aktion verwenden, wie in der Eingabe für die Aktion Eigenschaftswert kopieren. Dadurch entfällt die Notwendigkeit, einen weiteren API-Aufruf vorzunehmen, um den Wert als Eigenschaft in Ihrem Objekt zu speichern.

Beachten Sie beim Definieren Ihrer Ausgabe Folgendes:

  • Wenn Ihr Datenausgabetyp im Zeichenfolgenformat ist, beträgt die Obergrenze für Ausgabewerte im Zeichenfolgenformat 65.000 Zeichen. Ein Überschreiten dieses Limits führt zu einem OUTPUT_VALUES_TOO_LARGE-Fehler.
  • Wenn Sie die Aktion Eigenschaftswert kopieren verwenden, beachten Sie bitte auch die kompatiblen Quell- und Zieleigenschaften.
  • Beim Kopieren in Datumseigenschaften:
    • Wenn Sie eine Ausgabe in eine Datums-/Uhrzeiteigenschaft kopieren, muss die Ausgabe im UNIX-Millisekundenformat sein.
    • Wenn Sie eine Ausgabe in eine Datumseigenschaft anstelle einer Datums-/Uhrzeiteigenschaft kopieren, muss die Ausgabe im UNIX-Millisekundenformat erfolgen und die Uhrzeit beim Datum muss auf Mitternacht UTC eingestellt sein.
currentDate.setUTCHours(0,0,0,0)
custom_code_actions_output_usage

Limitations

Die Ausführung von benutzerdefinierten Code-Aktionen muss innerhalb von 20 Sekunden abgeschlossen sein, und sie dürfen nur bis zu 128 MB Speicherplatz verbrauchen. Ein Überschreiten einer dieser Beschränkungen führt zu einem Fehler. 

Retries

Möglicherweise müssen Sie Objekteigenschaften mithilfe der HubSpot-API abrufen oder andere HubSpot-API-Endpunkte in Ihrer benutzerdefinierten Code-Aktion aufrufen. Wie jeder andere API-Aufruf müssen Sie die API-Ratenbeschränkungen von HubSpot einhalten.

  • Wenn Sie Node.js verwenden und auf einen ratenbeschränkenden Fehler stoßen, HubSpot Ihren Anruf jedoch erneut versuchen soll, müssen Sie den Fehler im catch-Block Ihrer benutzerdefinierten Code-Aktion auslösen.

  • Wenn Sie Python verwenden und auf einen ratenbeschränkenden Fehler stoßen, HubSpot Ihren Anruf jedoch erneut versuchen soll, müssen Sie den Fehler im excep-Block Ihrer benutzerdefinierten Code-Aktion auslösen.

Bitte beachten: Wenn der Aufruf aufgrund eines Ratenbeschränkungsfehlers oder eines 429- oder 5xx-Fehlers von axios oder @hubspot/api-client fehlschlägt, versucht HubSpot eine Minute nach dem Fehler bis zu drei Tage lang erneut, Ihre Aktion auszuführen. Nachfolgende fehlgeschlagene Webhooks werden in größeren Intervallen mit einer maximalen Lücke von acht Stunden versucht, erneut auszuführen.

Caveats

Wenn Sie Node.js für Ihren benutzerdefinierten Code verwenden, beachten Sie die folgenden Vorbehalte:

  • Generieren von Zufallszahlen: Es ist üblich, Math.random zu verwenden, um Zufallszahlen zu generieren, aber Benutzer stellen möglicherweise fest, dass die gleichen Zahlen können über verschiedene Ausführungen generiert werden. Dies liegt daran, dass Math.random von der aktuellen Zeit gesetzt wird. Da HubSpot viele Objekte gleichzeitig in einen Workflow einschreiben und den Status bei jeder Ausführung löschen kann, setzen unterschiedlichen Ausführungen Math.random am Ende auf die gleiche Weise. Stattdessen können Sie die random-number-csprng 1.0.2-Bibliothek verwenden, die ein kryptographisch sicheres Generieren von Pseudo-Zufallszahlen gewährleistet.
  • Wiederverwendung von Variablen:  Um Speicher zu sparen, können alle Variablen, die außerhalb der exports.main-Funktion deklariert wurden, für zukünftige Ausführungen der benutzerdefinierten Code-Aktion wiederverwendet werden. Dies ist nützlich, wenn Sie eine Verbindung zu externen Diensten wie einer Datenbank herstellen, aber jede Logik oder Information, die für die einzelnen Ausführungen der benutzerdefinierten Code-Aktion eindeutig sein muss, sollte sich innerhalb der exports.main-Funktion befinden.

Wenn Sie Python für Ihren benutzerdefinierten Code verwenden, beachten Sie die folgenden Vorbehalte:

  • Wiederverwendung von Variablen: Ähnlich wie oben, können alle Variablen, die außerhalb der def main-Funktion deklariert wurden, für zukünftige Ausführungen der benutzerdefinierten Code-Aktion wiederverwendet werden.
    • Wenn Sie eine Variable außerhalb der def main-Funktion deklariert haben, jedoch nicht vorhaben, sie zu ändern, können Sie die Variable direkt referenzieren.
    • Wenn Sie eine Variable ändern möchten, können Sie die Variable innerhalb der def main-Funktion mit einem globalen Schlüsselwort deklarieren, bevor Sie sie referenzieren.
a = 1 def main(event): global a a += 1
War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.