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

⏱ 5 minutes📍 Onglet Service Hooks (page d’accueil)✅ Prérequis : un process publié

À quoi sert un hook ?

Comment le process est-il choisi ?

Le formulaire a deux onglets sous How is the process chosen? :

1. Créer un hook

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

  2. Integration

    Choisissez l’outil qui appellera le hook : Azure DevOps, Jira, Microsoft Teams, Outlook email ou Custom.

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

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

  5. Manual ou AI configuration

    Choisissez l’onglet (voir Comment le process est-il choisi ?).

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

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

  1. Dans Azure DevOps

    Ouvrez Project settings › Service hooks › Create subscription et choisissez Web Hooks.

  2. Évènement

    Choisissez Work item created (vous pouvez filtrer sur le type ou l’area path).

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

  4. Testez

    Le résultat du dernier appel s’affiche sur le hook.

Jira

  1. Dans Jira

    Ouvrez Settings › System › WebHooks et choisissez Create a WebHook.

  2. Évènement

    Choisissez Issue created (vous pouvez restreindre les tickets avec une requête JQL).

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

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

  1. Dans Teams

    Ouvrez Workflows et créez un flux à partir du déclencheur When a new channel message is added.

  2. Appelez SerenForce

    Ajoutez l’action HTTP avec la méthode POST et collez l’URL.

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

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

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

  2. Appelez SerenForce

    Ajoutez l’action HTTP avec la méthode POST et collez l’URL.

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

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

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

  2. Authentification

    Ajoutez l’en-tête affiché (X-Hook-Secret) avec la clé d’API, ou utilisez un jeton bearer.

  3. 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 :

À savoir

Permissions