Actions de workflow à code personnalisé

Dans les workflows, utilisez l'action Code personnalisé pour rédiger et exécuter un code JavaScript ou Python (bêta). Avec des actions de code personnalisé, vous pouvez étendre la fonctionnalité du workflow dans HubSpot et en dehors. Pour en savoir plus sur les API de HubSpot, vous pouvez vous référer à la documentation pour les développeurs pour les dernières versions ou à l'ancienne documentation pour les développeurs pour nos anciennes API. Pour consulter des exemples d'actions de code personnalisé, consultez Cas d'utilisation de l'automatisation programmable de HubSpot.

Les actions de code personnalisé prennent en charge JavaScript à l'aide du modèle d'exécution Node 16.x. Si vous utilisez Python pour votre action de code personnalisé, l'action de code personnalisé utilisera le modèle d'exécution Python 3.9. Lors de l'exécution d'une action, le calcul d'exécution est géré via une fonction sans serveur par HubSpot et AWS Lambda.

Si vous rencontrez des problèmes généraux de mise en œuvre de votre action de code personnalisé, vous pouvez contacter le support HubSpot. Cependant, si vous rencontrez des problèmes avec votre code personnalisé écrit, il est recommandé de rechercher et de publier sur le Forum des développeurs HubSpot pour obtenir des conseils, des astuces ou de l'aide.

Bibliothèques Node.js prises en charge

Si vous utilisez Node.js, les bibliothèques suivantes sont disponibles pour l'utilisation dans l'action de code. Ces bibliothèques peuvent être chargées à l'aide de la fonction normale require() en haut de votre code.

  • @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
Remarque : L'API Associations v4 est prise en charge dans la version 9.0.0 ou une version ultérieure du client NodeJS HubSpot et dans la version 8 du client NodeJS HubSpot.
 

Bibliothèques Python prises en charge

Si vous utilisez Python, vous pouvez charger les bibliothèques suivantes avec une instruction d'import en haut de votre code. L'instruction d'import doit être formatée comme from [bibliothèque] import [élément] (ex : 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

Si vous utilisez un élément de la bibliothèque standard, vous pouvez utiliser import, tel que import os.

Get started

Utilisez les exemples de code ci-dessous pour commencer à utiliser des actions de workflow à code personnalisé. 

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 (identique pour toutes les versions)
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" # }

Créer une action de code personnalisé

Pour ajouter une action de code personnalisé à un workflow :

  • Dans votre compte HubSpot, accédez à Automatisation > Workflows.
  • Cliquez sur le nom d'un workflow ou créez un nouveau workflow. 
  • Cliquez sur l'icône Plus (+) pour ajouter une action de workflow.
  • Dans le panneau de droite, sélectionnez Code personnalisé.
 

custom-code-action-select

  • Dans le panneau de droite, configurez votre action :
    • Par défaut, les actions de code personnalisé utiliseront Node.js 16.x. Si vous utilisez la version bêta de Python et que vous souhaitez créer votre action avec Python, cliquez sur le menu déroulant Langue, puis sélectionnez Python.
    • Pour ajouter un nouveau secret, comme un jeton d'accès d'application privée, cliquez sur Ajouter un secret.L'application doit également inclure les périmètres respectifs de toutes les données que vous essayez d'extraire de HubSpot, tels que contacts ou forms.  Découvrez-en davantage sur les applications privées HubSpot.
    • Dans la boîte de dialogue, saisissez le nom et la valeur du secret.
    • Cliquez sur Enregistrer. Vous pouvez désormais sélectionner ce secret dans les actions de code personnalisé futures.
    • Pour modifier ou supprimer des secrets existants, cliquez sur Gérer les secrets.
  • Pour inclure des propriétés dans votre code personnalisé, cliquez sur le menu déroulant Choisir une propriété, puis sélectionnez une propriété. Vous pouvez utiliser des propriétés existantes ou des valeurs de propriétés précédemment formatées dans le workflow. Après avoir sélectionné votre propriété, saisissez un nom de propriété à utiliser dans votre code. Découvrez comment référencer une propriété dans votre code personnalisé.
  • Pour ajouter une autre propriété, cliquez sur Ajouter une propriété. Chaque propriété ne peut être ajoutée qu'une seule fois et doit avoir un ID de variable unique.  Vous pouvez utiliser jusqu'à 50 propriétés avec votre code personnalisé. 
  • Pour supprimer une propriété, cliquez sur l'icône Supprimer.
  • Dans le champ de code, saisissez votre code JavaScript.
  • Pour définir les résultats de données qui peuvent être utilisés ultérieurement comme entrées dans le workflow, pour des exemples avec une action Copier la valeur de la propriété :
    • Sous Résultats des données, cliquez sur le menu déroulant Type de données et sélectionnez un type de données.
    • Dans le champ Nom, saisissez un nom pour le résultat de données.
    • Pour ajouter plusieurs résultats, cliquez sur Ajouter un résultat.
  • Cliquez sur Enregistrer.

workflow-custom-code

 

Remarque : Le champ de code n'affichera pas les erreurs de lint lors de l'utilisation de Python. 

Lorsque vous créez des actions de code personnalisé, gardez à l'esprit ce qui suit :

  • La fonction def main(event): est appelée lorsque l'action de bloc de code est exécutée.
  • L'argument event est un objet contenant des informations pour l'exécution du workflow.
  • La fonction callback() est utilisée pour renvoyer des données au workflow. Elle doit être appelée dans la fonction exports.main. Cela ne peut être utilisé qu'avec Node.js. 

L'objet event contiendra les données suivantes :

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

Tester l'action

Lorsque vous ajoutez une action de code personnalisé à un workflow, vous pouvez tester l'action pour vous assurer que votre code s'exécute comme prévu avant d'activer le workflow.

Lors du test d'une action de code personnalisé, vous devez commencer par sélectionner une fiche d'informations avec laquelle tester le code, puis exécuter le code. Ce test exécutera uniquement le code dans votre action personnalisée et aucune autre action dans le workflow. Lorsque l'exécution du code est terminée, vous pourrez voir les résultats de code et le journal de votre test.

Remarque : Lors du test de votre code personnalisé, le code s'exécutera et toute modification s'appliquera à la fiche d'informations de test sélectionnée. Il est recommandé de créer une fiche d'informations de test dédiée si vous souhaitez éviter de mettre à jour vos fiches d'informations en direct. 

Pour tester une action de code personnalisé :

  • Dans la chronologie du workflow, cliquez sur l'action de code personnalisé.
  • En bas de la barre latérale droite, cliquez sur Action de test pour développer la section de test.
    workflow-custom-code-test-expand
  • Sélectionnez une fiche d'informations à tester en cliquant sur le menu déroulant [Objet], puis sélectionnez une fiche d'informations.
    workflow-custom-code-action-test2
  • Si vous utilisez des valeurs de propriété précédemment formatées dans le workflow, saisissez une valeur de test pour les données formatées.   

  • Pour exécuter le code, cliquez sur Tester.
  • Dans la boîte de dialogue, confirmez que vous souhaitez tester votre code par rapport à la fiche d'informations sélectionnée en cliquant sur Tester.
  • Une fois votre code exécuté, la barre latérale affichera les résultats de votre test :
    • Statut : le statut de réussite ou d'échec de votre action de code personnalisé.
    • Résultats des données : les valeurs qui découlent pour vos résultats de données définis. Une alerte s'affiche à côté de tous les résultats générés par le code qui n'ont été définis dans la section Résultats des données ou dans l'éditeur de code. Vous devrez ajouter ces résultats afin de les utiliser ultérieurement dans le workflow.
    • Journaux : informations sur le test lui-même, telles que le volume de mémoire que l'action a nécessité pour s'exécuter et le temps d'exécution total. 

      workflow-custom-code-action-test0results0
  • Pour mettre à jour votre action de code personnalisé, cliquez sur Créer une action pour développer l'éditeur d'action. Continuez à mettre à jour et à tester votre code si nécessaire.
  • Lorsque vous avez terminé de tester l'action, cliquez sur Enregistrer pour enregistrer vos modifications.

Secrets

Parfois, vous souhaiterez que votre code fasse référence à quelque chose qui ne devrait pas être largement partagé. Le plus souvent, il s'agit d'un moyen d'authentification, comme un jeton d'accès d'application privée. Vous pouvez gérer les secrets auxquels votre fonction a accès directement dans la définition de l'action de workflow. Lors de l'utilisation de plusieurs secrets dans un code personnalisé, la longueur totale de toutes les valeurs secrètes ne doit pas dépasser 1 000 caractères.

workflow-custom-code-secrets

Une fois ajoutés, les secrets seront disponibles sous forme de variables d'environnement, auxquelles vous pouvez accéder dans le code personnalisé, comme indiqué ci-dessous :

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

Ajouter des propriétés HubSpot à votre code personnalisé

Parfois, vous pourrez avoir besoin de récupérer des propriétés d'objet dans votre action de code personnalisé. Plutôt que d'utiliser les API de HubSpot, vous pouvez ajouter ces propriétés directement dans la définition de l'action de workflow. Ajoutez des propriétés et définissez des noms des propriétés pour référencer des propriétés dans votre code. Vous pouvez ajouter jusqu'à 50 propriétés par action de code personnalisé.  

Une fois ajoutée, la propriété peut être référencée dans le code personnalisé. 

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

Journalisation

Un outil important pour les développeurs est l'impression des résultats à partir de leur code. Ainsi, vous pouvez résoudre les problèmes et fournir une meilleure assistance à vos utilisateurs finaux. Vous pouvez consulter les résultats des journaux dans l'onglet Historique du workflow.  

custom_code_logs

How to Define Outputs

Dans la fonction, définissez les champs de résultats que vous souhaitez utiliser ultérieurement dans le workflow. Ensuite, dans la barre latérale droite, sélectionnez le type de résultats de données (par exemple, nombre, chaîne, booléen, horodatage, énumération, date, numéro de téléphone) et saisissez le champ que vous souhaitez sortir.

Les champs de résultats doivent faire partie d'un objet JSON formaté en conséquence, en fonction de la langue utilisée :

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

Vous pouvez ensuite utiliser la sortie de votre action de code comme entrée dans l'action Copier la valeur de la propriété. Cela évite d'effectuer un autre appel d'API pour stocker la valeur en tant que propriété sur votre objet.

Lorsque vous définissez vos résultats, veuillez tenir compte des aspects suivants :

  • Si votre type de résultats de données est au format de chaîne, la limite pour les valeurs de sortie de chaîne est de 65 000 caractères. Le dépassement de cette limite entraînera une erreur OUTPUT_VALUES_TOO_LARGE. 
  • Si vous utilisez l'action Copier la valeur de propriété, veuillez également prendre note des propriétés sources et cibles compatibles.
  • Notez également que si vous copiez un résultat dans une propriété d'horodatage, le résultat devra être formaté enmillisecondes UNIX.
custom_code_actions_output_usage

Limitations

Les actions de code personnalisé doivent se terminer dans un délai de 20 secondes et peuvent utiliser jusqu'à 128 Mo de mémoire. Le dépassement de l'une de ces limites entraînera une erreur. 

Retries

Vous devrez peut-être récupérer les propriétés l'objet à l'aide de l'API HubSpot ou appeler d'autres points de terminaison d'API HubSpot dans votre action de code personnalisé. Comme tout autre appel d'API, vous devrez toujours respecter les limites des API HubSpot.

  • Si vous utilisez Node.js et que vous rencontrez une erreur de limite, mais que vous souhaitez que HubSpot réessaie votre appel, vous devrez lancer l'erreur dans le bloc catch de votre action de code personnalisé.

  • Si vous utilisez Python et que vous rencontrez une erreur de limite, mais que vous souhaitez que HubSpot réessaie votre appel, vous devrez lancer l'erreur dans le bloc except de votre action de code personnalisé.

Remarque : Si l'appel échoue en raison d'une erreur de limite ou d'une erreur 429 ou 5XX d'axios ou de @hubspot/api-client, HubSpot tentera à nouveau d'exécuter votre action pendant trois jours maximum, en commençant une minute après l'échec. Les tentatives après les échecs ultérieurs seront effectuées à intervalles croissants, avec un écart maximum de huit heures entre les tentatives.

Caveats

Si vous utilisez Node.js pour votre code personnalisé, tenez compte des points suivants :

  • Génération de nombres aléatoires : il est courant d'utiliser Math.random pour générer des nombres aléatoires, mais les utilisateurs peuvent voir les mêmes nombres générés à travers différentes exécutions. En effet, Math.random dépend de l'heure actuelle. Étant donné que HubSpot peut inscrire de nombreux objets dans un workflow en même temps et effacer l'état sur chaque exécution, différentes exécutions finissent par utiliser Math.random de la même manière. À la place, vous pouvez utiliser la bibliothèque random-number-csprng 1.0.2 qui garantit la génération cryptographiquement sécurisée de nombres pseudo-aléatoires.
  • Réutilisation des variables : pour sauvegarder la mémoire, toutes les variables déclarées en dehors de la fonction exports.main peuvent être réutilisées pour des exécutions futures de l'action de code personnalisé. Ceci est utile lors de la connexion à des services externes tels qu'une base de données, mais toute logique ou information qui doit être unique à chaque exécution de l'action de code personnalisé doit se trouver à l'intérieur de la fonction exports.main.

Si vous utilisez Python pour votre code personnalisé, tenez compte des points suivants :

  • Réutilisation des variables : comme indiqué précédemment, toutes les variables déclarées en dehors de la fonction def main peuvent être réutilisées pour des exécutions futures de l'action de code personnalisé.
    • Si vous avez déclaré une variable en dehors de la fonction def main mais que vous ne prévoyez pas de la modifier, vous pouvez référencer directement la variable.
    • Si vous prévoyez de modifier une variable, vous pouvez déclarer la variable dans la fonction def main avec un mot-clé global avant de la référencer.
a = 1 def main(event): global a a += 1
Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.