Workflows | Benutzerdefinierte Code-Aktionen

​

Unterstützte Node.js-Bibliotheken

• @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

​

Unterstützte Python-Bibliotheken

• 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

​

Erste Schritte

​

Codebeispiele

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"
}

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

• Navigieren 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.
• Suchen Sie im linken Bereich nach Benutzerdefinierter Code und wählen Sie diese Option aus.

• Standardmäßig verwenden benutzerdefinierte Code-Aktionen Node.js. 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.
• Geben Sie im Feld Beschreibung eine Beschreibung für Ihre benutzerdefinierte Workflow-Aktion ein. Diese wird dann in der entsprechenden Workflow-Aktionskarte angezeigt.
• Sie können ein Geheimnis mit Ihrer benutzerdefinierten Code-Aktion verwenden, z. B. ein Token für privaten App-Zugriff. 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.
  • Um ein vorhandenes Geheimnis zu verwenden, klicken Sie auf Geheimnis hinzufügen. Aktivieren Sie dann das **Kontrollkästchen ** neben dem Geheimnis, das Sie hinzufügen möchten.
  • Um ein neues Geheimnis hinzuzufügen, klicken Sie auf „Geheimnis hinzufügen“. Geben Sie im Dialogfeld den Geheimnisnamen und den Geheimniswert ein. Klicken Sie dann 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.
• So fügen Sie Eigenschaften in Ihren benutzerdefinierten Code ein:
  • Klicken Sie auf Eigenschaft auswählen und wählen Sie dann im Datenbereich 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 Datensatz bearbeiten-Aktion:
  • Klicken Sie unter Datenausgaben auf Ausgabe hinzufügen.
  • Klicken Sie auf das Dropdown-Menü für den Dateityp und wählen Sie entsprechenden Typ aus.
  • Geben Sie im Feld Name einen Namen für die Datenausgabe ein.
  • Um mehrere Ausgaben hinzuzufügen, klicken Sie auf Ausgabe hinzufügen.
• Klicke oben auf Speichern.

• Die Funktion def main(event): 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.

//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"
}

​

Ratenbegrenzung für Ihre Aktion festlegen (BETA)

• Klicken Sie in der Workflow-Chronik auf die benutzerdefinierte Code-Aktion.
• Klicken Sie unten auf Ratenbegrenzung konfigurieren, um den Abschnitt Ratenbegrenzung zu erweitern.
• Klicken Sie dann auf den Schalter Ratenbegrenzung aktivieren, um ihn zu aktivieren. Standardmäßig ist diese Einstellung deaktiviert.
• Richten Sie Ihre API-Ratenbegrenzung ein:
  • Aktionsausführungen: Legen Sie die maximale Anzahl von Ausführungen pro Zeitraum fest.
  • Zeitrahmen: Legen Sie den Zeitrahmen für Ihre Ratenbegrenzung fest. Sie können diesen Zeitraum auf Sekunden, Minuten oder Stunden festlegen.

​

Die Aktion testen

• Klicken Sie in der Workflow-Vorschau auf die benutzerdefinierte Code-Aktion.
• Klicken Sie am unteren Rand auf Testaktion, um den Testabschnitt zu erweitern.
• Klicken Sie auf das Dropdown-Menü Objekt und wählen Sie dann einen Datensatz aus, mit dem Sie Ihren Code testen möchten.
• 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, erscheinen die Ergebnisse Ihres Tests hier:
  • 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.
• Wenn Sie mit dem Testen der Aktion fertig sind, klicken Sie auf Speichern,um die Änderungen zu übernehmen.

​

Geheimnisse

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

const email = event.inputFields['email'];

​

Protokollierung

​

So definieren Sie Ausgaben

callback({
outputFields: {
email: email,
phone: phone,
},
});

• 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 Datensätze bearbeiten verwenden, beachten Sie bitte die kompatiblen Quell- und Zieleigenschaften.
• Beim Aktualisieren von Datumseigenschaften:
  • Wenn Sie eine Ausgabe zum Aktualisieren einer Datums-/Uhrzeiteigenschaft verwenden, muss die Ausgabe im UNIX-Millisekundenformat erfolgen.
  • Wenn Sie eine Ausgabe zum Aktualisieren einer Datumseigenschaft anstelle einer Datums-/Uhrzeiteigenschaft verwenden, muss die Ausgabe im UNIX-Millisekundenformat erfolgen und die Uhrzeit beim Datum muss auf Mitternacht UTC eingestellt sein.

​

Beschränkungen

​

Erneute Versuche

• 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 except-Block Ihrer benutzerdefinierten Code-Aktion auslösen.

​

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.

• 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