Actions de workflow personnalisées
Utilisez l'outil Workflows de HubSpot pour automatiser les processus commerciaux et permettre à votre équipe d'être plus efficace. Vous pouvez créer des actions de workflow personnalisées pour intégrer votre service aux workflows de HubSpot.
Après avoir configuré votre action personnalisée, lorsque les utilisateurs installeront votre application, ils pourront ajouter l'action personnalisée à leurs workflows.
Lorsque ces workflows seront exécutés, les demandes HTTPS seront envoyées à l'URL configurée avec la charge utile définie. Les demandes effectuées pour votre action personnalisée utiliseront la version 2 de X-HubSpot-Signature. Découvrez-en davantage sur la validation des demandes de HubSpot.
Vous pouvez également passer aux sections suivantes :
- Avant de commencer
- Définir votre action personnalisée
- Fonctions
- Champs de saisie
- Récupérer les champs de données externes
- Champs de sortie
- Libellés
- Exécution
- Exécution d'une action personnalisée asynchrone
- Ajouter des messages d'exécution personnalisés avec des règles d'exécution
- Tester et publier votre action personnalisée
- Vous devrez disposer d'un compte de développeur HubSpot avec une application HubSpot. Votre logo d'application sera utilisé comme icône pour l'action personnalisée.
- Lors de la soumission de demandes aux points de terminaison d'action de workflow personnalisée, vous devez inclure votre clé de compte de développeur HubSpot dans l'URL de demande. Par exemple :
https://api.hubspot.com/automation/v4/actions/{appId}?hapikey={API_key}
Pour créer une action de workflow personnalisée, vous devez définir l'action à l'aide des champs suivants. Cela indique également le format de demande pour les demandes provenant de HubSpot, ainsi que le traitement des réponses par votre service.
actionUrl
: l'URL vers laquelle une demande HTTPS est envoyée lorsque l'action est exécutée. Le corps de la demande contient des informations sur l'utilisateur au nom duquel l'action est exécutée et sur les valeurs saisies pour les champs de saisie.objectTypes
: les objets CRM avec lesquels cette action peut être utilisée.published
: par défaut, les actions personnalisées sont créées dans un état non publié. Les actions non publiées ne sont visibles que dans le portail de développeur associé à votre application HubSpot. Pour rendre votre action personnalisée visible par les utilisateurs, mettez à jour l'indicateur published de votre définition d'action et définissez-le sur true.inputFields
: les entrées reçues par l'action. Celles-ci seront renseignées par l'utilisateur.inputFieldDependencies
: ces règles permettent de griser les champs jusqu'à ce que les autres champs répondent à des conditions spécifiques.outboundFields
: les valeurs résultantes de l'action qui peuvent être utilisées par des actions suivantes dans le workflow. Une action personnalisée peut avoir aucun, un ou plusieurs résultats.objectRequestOptions
: propriétés de l'objet inscrit incluses dans la charge utile de actionUrl.labels
: une copie qui décrit pour l'utilisateur ce que représentent les champs de l'action et ce que fait l'action. Des libellés en anglais sont requis, mais les libellés peuvent également être indiqués dans l'une de ces langues prises en charge : français (fr
), allemand (de
), japonais (ja
), espagnol (es
), portugais du Brésil (pt-br
) et néerlandais (nl
).executionRules
: une liste des définitions que vous pouvez spécifier pour identifier les erreurs de votre service vers l'utilisateur qui crée le workflow.functions
: les blocs de code qui sont exécutés afin de transformer la charge utile envoyée vers une URL et/ou de transformer la réponse à partir de cette URL.
Exemple de définition d'action personnalisée
La définition ci-dessus restituera ce qui suit dans l'outil Workflows :
Il existe deux types d'appels effectués pour les actions de workflow personnalisées :
- Récupérations d'options de champ : renseignez une liste des options valides lorsqu'un utilisateur configure un champ. Découvrez-en davantage sur l'utilisation des options de champ pour récupérer des champs de données externes.
- Demandes d'exécution d'action : effectué lorsqu'une action est exécutée par un workflow qui comprend votre action personnalisée.
Les fonctions sont des blocs de code utilisés pour modifier les charges utiles avant de les envoyer à une API. Vous pouvez également utiliser des fonctions pour analyser les résultats d'une API. Les fonctions de HubSpot reposent sur AWS Lambda. Dans le code suivant :
event
contient les données qui sont transmises à la fonction.exports.main
est la méthode qui sera appelée lors de l'exécution de la fonction.- La fonction
callback
peut être utilisée pour renvoyer un résultat.
Le code doit être formaté comme suit :
Lors de la configuration d'une fonction, le format functionSource
sera dans la chaîne. Assurez-vous que les caractères du code ont été échappés.
Généralement, la définition d'une fonction suit le format suivant :
Dans l'exemple ci-dessous, examinez le code saisi, la fonction utilisée et le résultat.
Saisie de fonction :
Fonction utilisée :
Résultats escomptés :
Les définitions des champs de saisie seront conformes au format suivant :
name
: le nom interne du champ de saisie, différent de son libellé. Le libellé affiché dans l'interface utilisateur doit être défini à l'aide de la section Libellés de la définition d'action personnalisée.type
: le type de valeur requis par la saisie.fieldType
: comment le champ de saisie doit être rendu dans l'interface utilisateur. Les champs de saisie imitent les propriétés CRM. Découvrez-en davantage sur les combinaisons valides entretype
etfieldType
.supportedValueTypes
compte deux valeurs valides :OBJECT_PROPERTY
: l'utilisateur peut sélectionner une propriété à partir de l'objet inscrit ou un résultat d'une action précédente à utiliser comme valeur du champ.STATIC_VALUE
: doit être utilisé dans tous les autres cas. Cela signifie que l'utilisateur doit saisir lui-même une valeur.
isRequired
: cela détermine si l'utilisateur doit donner ou non une valeur pour cette entrée.
Les définitions des champs de saisie doivent être formatées comme suit :
Vous pouvez également coder des options en dur pour l'utilisateur :
La charge utile envoyée à optionsURL
sera formatée comme suit :
La réponse attendue devrait être formatée comme suit :
In the code above, note that there's pagination being set to limit the number of returned options. This instructs the workflow that more options can be loaded.
In addition, the list of options is made searchable by including searchable:true
.
Pour gérer les données externes, vous pouvez inclure deux hooks pour personnaliser le cycle de vie de la récupération d'options de champ :
PRE_FETCH_OPTIONS
: une fonction qui configure la charge utile envoyée depuis HubSpot.POST_FETCH_OPTIONS
: une fonction qui transforme la réponse de votre service dans un format pris en charge par HubSpot.
Lorsqu'elle est incluse, cette fonction s'appliquera à chaque champ de saisie. Vous pouvez l'appliquer à un champ de saisie spécifique en spécifiant un id
dans la définition de fonction.
La charge utile envoyée depuis HubSpot sera formatée comme suit :
La réponse doit ensuite être formatée comme suit :
Pour analyser la réponse dans un format attendu, en fonction des champs de données externes, utilisez une fonction POST_FETCH_OPTIONS
. La définition d'une fonction POST_FETCH_OPTIONS
est identique à celle d'une fonction PRE_FETCH_OPTIONS
. Lorsque des options de récupération de données externes sont définies, un menu déroulant sera affiché dans les options de saisie pour l'action.
La saisie de fonction sera formatée comme suit :
La sortie de fonction sera formatée comme suit :
Utilisez les champs de sortie pour générer des valeurs de votre action personnalisée à utiliser dans d'autres actions. La définition des champs de sortie est similaire à la définition des champs de saisie :
- name : référencement de ce champ dans d'autres parties de l'action personnalisée. Le libellé affiché dans l'interface utilisateur doit être défini à l'aide de la section Libellés de l'action personnalisée.
- type : le type de valeur requis par la saisie.
- fieldType : comment le champ de saisie doit être rendu dans l'interface utilisateur. Les champs de saisie imitent les propriétés CRM. Découvrez-en davantage sur les combinaisons valides entre
type
etfieldType
.
Le champ de sortie doit être formaté comme suit :
Lors de l'utilisation d'un champ de sortie, les valeurs sont analysées à partir de la réponse de actionURL
. Par exemple, vous pouvez copier des champs de sortie dans une propriété existante dans HubSpot.
Utilisez des libellés pour ajouter du texte à vos sorties ou entrées dans l'éditeur de workflow. Les libellés sont chargés dans le service de langue de HubSpot et leur affichage peut prendre quelques minutes. Les portails configurés pour différentes régions ou langues afficheront le libellé dans la langue correspondante, le cas échéant.
labels
: une copie qui décrit ce que représentent les champs de l'action et ce que fait l'action. Des libellés en anglais sont requis, mais les libellés peuvent également être indiqués dans l'une de ces langues prises en charge : français (fr
), allemand (de
), japonais (ja
), espagnol (es
), portugais du Brésil (pt-br
) et néerlandais (nl
).actionName
: nom de l'action affiché dans le panneau Sélectionner une action de l'éditeur de workflow.actionDescription
: une description détaillée de l'action affichée lorsque l'utilisateur configure l'action personnalisée.actionCardContent
: une description récapitulative affichée dans la carte de l'action.appDisplayName
: le nom de la section du panneau Choisir une action où toutes les actions de l'application sont affichées. Si appDisplayName est défini pour plusieurs actions, la première trouvée est utilisée.inputFieldLabels
: un objet qui regroupe les définitions de inputFields vers les libellés correspondants que l'utilisateur verra lors de la configuration de l'action.outputFieldLabels
: un objet qui regroupe les définitions de outputFields vers les libellés correspondants indiqués dans l'outil Workflows.inputFieldDescriptions
: un objet qui regroupe les définitions de inputFields vers les descriptions sous les libellés correspondants.executionRules
: un objet qui regroupe les définitions de executionRules vers des messages qui seront affichés pour les résultats d'exécution d'action dans l'historique du workflow. Il existe une section distincte dans ces documents pour les règles d'exécution.
Les définitions des libellés doivent être formatées comme suit :
Lorsqu'une exécution survient, une demande HTTPM est envoyée à actionUrl
.
callbackId
: un ID unique pour l'exécution spécifique. Si l'exécution de l'action personnalisée est bloquée, utilisez cet ID.objet
: les valeurs des propriétés demandées dansobjectRequestOptions
.InputFields
: les valeurs pour les saisies que l'utilisateur a renseignées.
La charge utile d'exécution sera formatée comme suit :
La réponse attendue devrait être formatée comme suit :
Lors de l'examen de la réponse d'exécution :
outputFields
: les valeurs des champs de sortie définis précédemment. Ces valeurs peuvent être utilisées dans des actions ultérieures.hs_execution_state
: une valeur spéciale facultative qui peut être ajoutée à outputFields. Il n'est pas possible de spécifier une nouvelle tentative. Seules les valeurs suivantes peuvent être ajoutées :- RÉSULTATS
- FAIL_CONTINUE
- BLOCK
- ASYNC
SUCCESS
et FAIL_CONTINUE
indiquent que l'action est terminée et que le workflow doit passer à l'action suivante à exécuter. Si aucun statut d'exécution n'est spécifié, des codes de statut seront utilisés pour déterminer le résultat d'une action :
- Codes de statut 2xx : l'action a été correctement effectuée.
- Codes de statut 4xx : l'action a échoué. Les codes de statut Taux limité 429 sont l'exception. Ces derniers sont traités comme des nouvelles tentatives et l'en-tête Retry-After est respecté.
- Codes de statut 5xx : un problème temporaire est survenu avec le service et l'action sera relancée ultérieurement. Un système d'intervalle exponentiel est utilisé pour les nouvelles tentatives, qui se poursuivront pendant 3 jours au maximum avant d'échouer.
Utilisez les fonctions d'exécution pour formater les données avant de les envoyer vers actionURL
et analysez les données de actionURL
. Il existe deux types de fonctions d'exécution :
PRE_ACTION_EXECUTION
POST_ACTION_EXECUTION
Fonction PRE_ACTION_EXECUTION
Utilisez les fonctions PRE_ACTION_EXECUTION
pour formater les données avant de les envoyer vers actionURL
.
La définition de la fonction sera formatée comme suit :
La saisie de fonction doit être formatée comme suit :
La sortie de fonction doit être formatée comme suit :
Fonction POST_ACTION_EXECUTION
Après avoir reçu une réponse de actionURL
, utilisez une fonction POST_ACTION_EXECUTION
pour formater les données pour HubSpot.
La définition de la fonction sera formatée comme suit :
La saisie de fonction doit être formatée comme suit :
The function output should be formatted as follows:
Exécutez des actions de workflow personnalisées de manière asynchrone en bloquant, puis en finalisant l'action.
Utilisez des actions personnalisées pour bloquer l'exécution du workflow. Au lieu d'exécuter l'action suivante dans le workflow une fois que votre action personnalisée a reçu une réponse completed
(code de statut 2xx ou 4xx) de votre service, le workflow cessera d'exécuter (« bloquera ») cette inscription tant que vous n'indiquerez pas au workflow de poursuivre.
Lors du blocage, vous pouvez spécifier une valeur pour le champ hs_default_expiration
, après quoi votre action personnalisée sera considérée comme expirée. L'exécution du workflow reprendra alors et l'action suivant votre action personnalisée sera exécutée, même si l'action n'est pas terminée.
Pour bloquer une action personnalisée, la réponse de l'exécution de votre action doit avoir le format suivant :
Pour terminer une exécution d'action personnalisée bloquée, utilisez le point de terminaison suivant : /callbacks/{appId}/{callbackId}/complete
.
Formatez le corps de la demande comme suit :
Spécifiez des règles sur votre action qui déterminent le message à afficher sur la page d'historique des workflows lorsque l'action est exécutée.
Les règles seront associées aux valeurs de sortie de votre action. Ces valeurs de sortie doivent être fournies dans le corps de réponse de actionURL
, au format suivant :
Les véritables messages peuvent être spécifiés dans la section Libellés de l'action personnalisée :
Les règles executionRules
seront testées dans l'ordre indiqué. S'il existe plusieurs correspondances, seul le message de la première règle correspondante s'affichera pour l'utilisateur.
La règle est associée lorsque le résultat d'exécution correspond à une valeur spécifique dans la règle. Prenons l'exemple de cet ensemble de règles executionRules
:
Les correspondances suivantes se produiront :
{"errorCode": "ALREADY_EXISTS", "widgetName": "Test widget"}
: cela correspond à la première règle, carerrorCode
équivaut àALREADY_EXISTS
. Dans cet exemple, même s'il y a un résultatwidgetName
, il ne sera pas utilisé dans la définition de la règle. Ainsi, toute valeur sera autorisée.{"errorCode": "WIDGET_SIZE", "sizeError": "TOO_SMALL"}
: cela correspond à la deuxième règle, carTOO_SMALL
est l'un des élémentssizeError
correspondants eterrorCode
estWIDGET_SIZE
.{"errorCode": "WIDGET_SIZE", "sizeError": "NOT_A_NUMBER"}
: cela correspond à la troisième règle, car même sierrorCode
estWIDGET_SIZE
,sizeError
ne correspond pas à l'une des valeurs spécifiées par la deuxième règle (TOO_SMALL
ouTOO_BIG
).
Ce mécanisme correspondant vous permet de spécifier des erreurs de secours afin que vous puissiez obtenir des erreurs spécifiques pour des cas d'erreur importants, mais des messages d'erreur plus génériques pour des erreurs moins courantes. Voici un exemple d'affichage du message personnalisé :
Après avoir créé votre nouvelle action personnalisée, vous pouvez la tester et la publier.
Tester des actions personnalisées avant publication
Avant de publier votre action personnalisée, vous pouvez tester les options d'exécution et de récupération de l'action en pointant l'URL vers webhook.site. Cela vous permet d'inspecter la charge utile et de renvoyer une réponse spécifique.
Vous pouvez également tester l'action dans votre portail de développeur en créant un workflow dans l'outil Workflows. Puis, ajoutez votre nouvelle action.
Publier des actions personnalisées
Par défaut, les actions personnalisées sont créées dans un état non publié. Les actions personnalisées non publiées ne sont visibles que dans le portail du développeur associé à l'application HubSpot correspondante. Pour rendre votre action personnalisée visible par les utilisateurs, mettez à jour l'indicateur published
de votre définition d'action et définissez-le sur true
. Si une action n'est pas publiée, les portails qui ont déjà ajouté l'action à leur workflow pourront toujours modifier et exécuter les actions déjà ajoutées. Cependant, ils ne seront pas en mesure d'ajouter l'action à nouveau.
Example 1
A basic example with the following input fields, created for contact and deal workflows:
- a static input field
- a dropdown field with options
- a field whose value is a HubSpot owner
- a field whose value is pulled from a property (that the user creating the workflow selects) on the enrolled object.
Exemple 2
L'action personnalisée suivante utilise une fonction sans serveur pour transformer la charge utile envoyée à l'élément actionUrl configuré. Étant donné qu'aucun élément objectTypes n'est spécifié, cette action sera disponible dans tous les types de workflow.
Exemple 3
L'action personnalisée suivante contient des dépendances de champs et des options récupérées depuis une API. Étant donné que la taille du widget dépend de la couleur du widget, l'utilisateur ne pourra pas saisir une valeur pour la taille du widget tant qu'il n'aura pas choisi une couleur.
Le coût du widget dépend également de la couleur du widget, mais il dépend de la valeur que l'utilisateur sélectionne pour la couleur du widget. L'utilisateur ne pourra pas saisir une valeur pour le coût du widget, sauf si la couleur Red est sélectionnée comme couleur du widget.
Exemple 4
L'exemple suivant présente le blocage d'une action personnalisée. L'API des rappels peut être utilisée pour indiquer à HubSpot de terminer l'action et de faire avancer l'objet inscrit vers la prochaine action du workflow.
Vous n'aurez pas besoin de spécifier que l'action bloque au moment de la création de l'action. Cela sera déterminé par la réponse de votre élément actionUrl configuré.
Merci d'avoir partagé votre avis.