Workflows | Actions de code personnalisé

​

Bibliothèques Node.js prises en charge

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

​

Bibliothèques Python prises en charge

• 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

​

Premiers pas

​

Exemples de code

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"

# }

​

Créer une action de code personnalisé

• Dans votre compte HubSpot, naviguez vers 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 gauche, recherchez et sélectionnez Code personnalisé.

• Par défaut, les actions de code personnalisé utiliseront Node.js. 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.
• Dans le champ Description, saisissez une description pour votre action de workflow personnalisée. Cette description apparaîtra dans la carte d’action de workflow correspondante.
• Vous pouvez utiliser un secret avec votre action de code personnalisé, comme un jeton d’accès d’application privée. L’application doit également inclure les domaines 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.
  • Pour utiliser un secret existant, cliquez sur Ajouter un secret. Ensuite, sélectionnez les cases à cocher à côté des images que vous souhaitez enregistrer.
  • Pour ajouter un nouveau secret, cliquez sur Ajouter un secret. Dans la boîte de dialogue, saisissez le nom du secret et la valeur du secret. Cliquez ensuite 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 Sélectionner une propriété, puis sélectionnez une propriété dans le panneau de données. 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 Modifier les fiches d’informations :
  • Sous Résultats des données, cliquez sur Ajouter un résultat.
  • 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.
• En haut de l’écran, cliquez sur Enregistrer.

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

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

​

Définir une limite de débit pour votre action (BÊTA)

• Dans la chronologie du workflow, cliquez sur l’action de code personnalisé.
• En bas, cliquez sur Configurer la limite de débit pour développer la section de limite de débit.
• Cliquez pour activer l’option Activer la limitation de débit. Par défaut, ce paramètre est désactivé.
• Définissez votre limite de débit :
  • **Exécutions d’actions **: définissez le nombre maximum d’exécutions par période.
  • Période : définissez le cadre temporel de votre limite. Vous pouvez définir cette période en secondes, minutes ou heures.

​

Tester l’action

• Dans l’aperçu du workflow, cliquez sur l’action de code personnalisé.
• En bas, cliquez sur Action de test pour développer la section de test.
• Sélectionnez une fiche d’informations à tester en cliquant sur le menu déroulant Objet, puis sélectionnez une fiche d’informations.
• 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.
• Lorsque vous avez terminé de tester l’action, cliquez sur Enregistrer pour enregistrer vos modifications.

​

Secrets

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é

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

​

Journalisation

​

Comment définir les sorties

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

• 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 Modifier les fiches d’informations, prenez note des propriétés sources et cibles compatibles.
• Lors de la mise à jour des propriétés de date :
  • Si vous copiez un résultat dans une propriété d’horodatage, le résultat devra être formaté en millisecondes UNIX.
  • Si vous utilisez un résultat pour mettre à jour une propriété de date au lieu d’une propriété d’horodatage, la sortie devra être au format millisecondes UNIX et l’heure de la date devra être définie sur minuit UTC.

​

Limites

​

Nouvelles tentatives

• 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é.

​

Avertissements

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

• 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