Documentation › Les hooks
Lancer un process depuis un autre outil : les service hooks
Un hook est une adresse qu’un autre outil appelle quand il se passe quelque chose : un élément de travail ou un ticket est créé, un message est publié dans Teams, un e-mail arrive… SerenForce trouve alors le bon process et lance automatiquement une instance de process, avec le titre de l’élément dans une variable si vous le souhaitez. Cinq outils sont pris en charge : Azure DevOps, Jira, Microsoft Teams, E-mail Outlook et Personnalisé (tout outil capable d’envoyer des données à une adresse).
À quoi sert un hook ?
- Dans l’autre outil, un abonnement (service hook, webhook, flux…) prévient SerenForce dès que quelque chose est créé. Le hook décide quel process lancer.
- L’instance de process est lancée à votre nom, dans votre organisation, avec les personnes et les valeurs que vous avez choisies pour ce process. Elle apparaît dans Process instances comme les autres.
- Son nom vient d’un modèle, par exemple {Id} - {Title} : 1042 - Connexion impossible.
- L’Integration d’un hook (l’outil qui l’appelle) se choisit à la création et ne peut plus être changée ensuite : créez un autre hook pour un autre outil.
Comment le process est-il choisi ?
Le formulaire a deux onglets sous How is the process chosen? :
- Manual configuration : vous fixez vous-même les conditions et choisissez un ou plusieurs process. Un seul process sans condition se lance pour chaque élément de travail, ticket, message ou e-mail. Avec plusieurs process, mettez-les dans l’ordre : chacun a des conditions, nommées comme l’outil les nomme (par exemple Work item types, Tags (at least one), Area path starts with pour Azure DevOps ; Issue types, Labels (at least one), Component starts with pour Jira). Le premier process dont l’élément remplit toutes les conditions est lancé ; une condition vide accepte tout. Si aucun ne convient, rien n’est lancé. Une condition qui n’a pas de sens pour un outil n’est pas proposée (pas de tags pour un message Teams, pas de zone pour un e-mail).
- AI configuration : pour chaque process, vous décrivez en une phrase ce qui le concerne (When is this process the right one?) et, dans Instructions for the AI, vous pouvez ajouter un prompt (2000 caractères au plus) qui dit à l’IA ce qu’elle doit chercher et comment décider, par exemple les éléments de sécurité ne vont jamais au process du support. Une IA lit l’élément, vos instructions et vos descriptions, puis choisit le process qui convient, ou aucun.
1. Créer un hook
- Cliquez sur New service hook
Dans l’onglet Service Hooks. Le bouton n’apparaît que si vous pouvez gérer des service hooks et voir les process.
- Integration
Choisissez l’outil qui appellera le hook : Azure DevOps, Jira, Microsoft Teams, Outlook email ou Custom.
- Connection
Dès que vous choisissez l’outil, la section Connection affiche l’URL à renseigner dans celui-ci pour que son service hook (par exemple le web hook d’Azure DevOps) appelle SerenForce, avec un bouton pour la copier. Pour les outils qui envoient un en-tête (Azure DevOps, Teams, Outlook, personnalisé), elle affiche aussi le nom de l’en-tête, X-Hook-Secret. Renseignez l’URL dans l’outil, puis enregistrez : SerenForce génère alors une clé d’API, affichée une seule fois, à envoyer dans l’en-tête X-Hook-Secret. L’URL ne change pas à l’enregistrement, et l’outil choisi change son adresse. En modification, la même URL est affichée avec un bouton qui ouvre les détails de connexion.
- Details
Donnez un Name (obligatoire) et, si vous le souhaitez, un Name of the process instances avec les champs reçus : {Id}, {Type}, {Title}, {Description}, {State}, {Url}, {Tags}, {AreaPath}, {AssignedTo}, {Project}, {Author}. Par défaut, le nom est {Id} - {Title} pour Azure DevOps et Jira, et {Title} pour les autres.
- Manual ou AI configuration
Choisissez l’onglet (voir Comment le process est-il choisi ?).
- Process
Choisissez le process publié, qui joue chaque participant, et les valeurs des variables. Avec Copy a field, un champ reçu remplit une variable du process (le formulaire explique ce que chaque champ veut dire pour l’outil). Avec Add a process, ajoutez d’autres process.
- Cliquez sur Save
SerenForce affiche ce qu’il faut donner à l’autre outil : l’adresse et le secret.
2. Connecter l’autre outil
Après la création (ou avec le bouton Connect to… d’un hook), SerenForce affiche les étapes pour l’outil, l’URL à appeler et la façon de prouver qui appelle. Un outil peut envoyer la clé d’API de trois façons : dans l’en-tête X-Hook-Secret (à préférer), comme jeton bearer, ou à la fin de l’adresse (?secret=…, pour les outils qui ne savent que mémoriser une adresse). La clé d’API n’est montrée qu’une seule fois : copiez-la tout de suite. Vous l’avez perdue ? Utilisez Renew the API key : une nouvelle clé d’API est affichée et l’ancien cesse de fonctionner.
Azure DevOps
- Dans Azure DevOps
Ouvrez Project settings › Service hooks › Create subscription et choisissez Web Hooks.
- Évènement
Choisissez Work item created (vous pouvez filtrer sur le type ou l’area path).
- Adresse et authentification
Collez l’URL ; laissez l’authentification vide. Dans HTTP headers, ajoutez l’en-tête affiché suivi de la clé d’API, écrit X-Hook-Secret: votre-clé-d’api.
- Testez
Le résultat du dernier appel s’affiche sur le hook.
Jira
- Dans Jira
Ouvrez Settings › System › WebHooks et choisissez Create a WebHook.
- Évènement
Choisissez Issue created (vous pouvez restreindre les tickets avec une requête JQL).
- Adresse
Collez l’URL : juste après la création du hook, elle contient déjà la clé d’API (?secret=…), car Jira ne peut pas envoyer d’en-tête. Si la clé d’API n’est plus affichée, renouvelez-le pour obtenir l’adresse complète.
- Testez
Créez un ticket : le résultat de l’appel s’affiche sur le hook. Le champ Number est la clé du ticket (PROJ-12), Area path son premier composant, Project la clé du projet et Author le rapporteur.
Microsoft Teams
- Dans Teams
Ouvrez Workflows et créez un flux à partir du déclencheur When a new channel message is added.
- Appelez SerenForce
Ajoutez l’action HTTP avec la méthode POST et collez l’URL.
- Authentification et message
Ajoutez l’en-tête affiché (X-Hook-Secret) avec la clé d’API, et envoyez le message comme corps : son texte, son expéditeur, son canal et son lien.
- Testez
Publiez un message dans le canal. Title est l’objet ou la première ligne du message, Area path le canal, Project l’équipe et Author l’expéditeur.
E-mail Outlook
- Dans Power Automate
Créez un flux à partir du déclencheur Outlook When a new email arrives (V3) ; choisissez la boîte aux lettres et, si vous le souhaitez, filtrez sur le dossier, l’expéditeur ou l’objet.
- Appelez SerenForce
Ajoutez l’action HTTP avec la méthode POST et collez l’URL.
- Authentification et e-mail
Ajoutez l’en-tête affiché (X-Hook-Secret) avec la clé d’API, et envoyez l’e-mail comme corps : objet, corps, expéditeur, importance, catégories et lien.
- Testez
Envoyez-vous un e-mail. Title est l’objet, Type l’importance (low, normal, high), Tags les catégories, Assigned to le premier destinataire et Author l’expéditeur.
Personnalisé
Pour tout autre outil capable d’envoyer des données (un HTTP POST avec un corps JSON) à une adresse. SerenForce ne peut pas deviner où se trouve chaque information dans ce que l’outil envoie : vous l’indiquez dans la section Where are the fields? du formulaire, avec pour chaque champ le chemin dans le JSON, par exemple issue.key ou items[0].title. Renseignez au moins un chemin et laissez les autres vides.
- Dans votre outil
Envoyez une requête POST avec le JSON de l’évènement à l’URL chaque fois qu’il se passe quelque chose.
- Authentification
Ajoutez l’en-tête affiché (X-Hook-Secret) avec la clé d’API, ou utilisez un jeton bearer.
- Testez
Le résultat du dernier appel s’affiche sur le hook ; vérifiez que les chemins trouvent leurs valeurs.
3. Suivre et gérer vos hooks
La page Service Hooks liste vos service hooks : leur outil, leur façon de choisir, leurs process, leur état (Active ou Paused), le dernier appel et son résultat :
- Process instance started : une instance a été lancée (le bouton Open the last process instance l’ouvre).
- No process found : aucune règle ne convenait (ou l’IA n’a rien trouvé) ; rien n’a été lancé.
- Ignored : l’évènement n’était pas une création (une modification, un commentaire…).
- Failed : l’instance n’a pas pu être lancée (process plus publié, IA indisponible…) ; le message est affiché sur le hook.
- Test (debug mode) : seulement quand SerenForce tourne en mode debug, sur le poste d’un développeur. SerenForce envoie au service hook ce que son outil envoie quand un élément est créé, comme un vrai appel, avec un élément qui remplit les conditions de son premier process. Un message dit ce qui s’est passé, et le dernier appel du hook l’affiche. Ce bouton n’apparaît jamais dans l’application déployée.
- Pause / Resume : un hook en pause refuse les appels de l’autre outil.
- Edit : changez le nom, la configuration (manuelle ou IA), les conditions, les descriptions, les instructions pour l’IA et, pour un service hook personnalisé, les chemins. L’outil, le process, les personnes et les valeurs d’un process déjà dans le hook ne changent pas : retirez le process et ajoutez-le de nouveau.
- Delete : supprime le hook (l’autre outil recevra une erreur). Les instances déjà lancées sont conservées.
À savoir
- Chaque hook garde la version publiée du process choisie à sa création : publier une nouvelle version n’y change rien tant que vous ne le modifiez pas.
- La AI configuration envoie à une IA le titre, la description, les tags et la zone (ou le canal, le composant…) de l’élément, ainsi que vos descriptions et vos instructions. Il n’est disponible que si l’administrateur de la plateforme l’a configuré ; sinon le hook affiche Failed.
- Une clé d’API dans une adresse (?secret=…) peut finir dans les journaux des outils intermédiaires : préférez un en-tête dès que l’outil sait en envoyer un.
- Le nom et les valeurs trop longs sont coupés (200 et 250 caractères).
Permissions
- Voir la page Service Hooks : View service hooks. Chacun ne voit que ses hooks.
- Créer, modifier, mettre en pause, renouveler la clé d’API et supprimer : Manage service hooks (et View processes pour choisir les process). Utilisateurs et rôles explique comment les obtenir.