JIRA — créer et suivre des tickets depuis le bot

À quoi ça sert

Sens Ai propose trois modèles d’actions JIRA :

Cas d’usage typiques :

• un visiteur signale un bug → l’agent ouvre un ticket dans le projet SUPPORT ;
• un client demande « où en est mon ticket SUPPORT-412 ? » → l’agent interroge JIRA et répond avec le statut ;
• une demande urgente arrive → l’agent ajoute un commentaire « Client a relancé » et passe la priorité à High.

Prérequis

• Une instance JIRA Cloud (adresse en *.atlassian.net — JIRA Server et Data Center ne sont pas pris en charge).
• Un compte Atlassian avec les droits de créer / lire / modifier des tickets dans le projet visé.
• Un jeton API Atlassian (voir l’étape 1).
• La clé du projet JIRA (par exemple SUPPORT, BUG, DEV — visible dans l’URL de votre projet).

Étape 1 — Générer un jeton API Atlassian

Sens Ai s’authentifie auprès de JIRA avec votre adresse e-mail Atlassian et un jeton API. Pour générer le jeton :

1. Connectez-vous à id.atlassian.com/manage-profile/security/api-tokens avec le compte Atlassian à utiliser.
2. Cliquez sur Create API token.
3. Donnez-lui un nom parlant (ex. : Sens Ai production).
4. Copiez la valeur affichée. Elle ne sera plus jamais affichée ensuite — si vous la perdez, il faudra en générer une autre.

Conseil : créez un compte Atlassian dédié à votre agent (bot@votre-domaine.com) plutôt que d’utiliser un compte personnel. L’historique JIRA sera plus lisible, et un départ ne cassera pas votre intégration.

Étape 2 — Créer le connecteur JIRA

Le connecteur centralise l’adresse et le jeton : vous le configurez une fois, les trois actions s’y rattachent.

1. Dans le menu du haut, cliquez sur Intégrations, onglet Catalogue, puis Configurer sur JIRA.
2. Remplissez :
   • Nom : par exemple JIRA Production ;
   • URL JIRA : https://votre-domaine.atlassian.net (sans / final, sans /rest/api/3) ;
   • Email API : l’e-mail du compte qui a généré le jeton ;
   • Token API : la valeur copiée à l’étape 1.
3. Cliquez sur Créer.
4. Dans Mes connecteurs, cliquez sur Tester : Sens Ai lit votre profil JIRA et affiche « Connexion réussie » si tout va bien.

Vous pouvez aussi créer le connecteur depuis la page de l’action (bouton Créer un connecteur s’il n’en existe aucun, ou Nouveau pour en créer un autre). Détails pratiques : les actions JIRA n’appellent que des adresses en *.atlassian.net, et chaque appel a 10 secondes pour aboutir.

Étape 3 — L’action « Créer un ticket JIRA »

1. Dans le menu de gauche de l’agent : Configuration Agent › Compétences › onglet Catalogue › Configurer sur Créer un ticket JIRA.
2. Description pour l’agent : donnez un Nom explicite (ex. : « Ouvrir un ticket support »).
3. Configuration :
   • Connecteur : celui de l’étape 2 ;
   • Clé du projet (obligatoire) : par exemple SUPPORT ;
   • Type de ticket (obligatoire) : Task (par défaut), Bug, Story ou Epic. Les types disponibles dépendent de votre projet ; un type absent de votre projet fera échouer la création.
4. Test : Tester l’action, remplissez summary et description, Lancer le test, puis vérifiez le ticket dans JIRA (voir Tester et déboguer).
5. Cliquez sur Créer.

Ce que l’agent remplit à l’exécution

L’agent a pour consigne de demander au visiteur ce qui manque plutôt que d’inventer, et de choisir la priorité selon l’urgence exprimée.

Les champs à collecter que vous ajoutez sont joints à la fin de la description du ticket.

Après la création, l’agent reçoit « Ticket SUPPORT-412 créé. » et l’annonce au visiteur.

Étape 4 — L’action « Consulter un ticket JIRA »

1. Compétences › Catalogue › Configurer sur Consulter un ticket JIRA.
2. Choisissez le même connecteur JIRA. Aucun autre réglage.
3. Testez avec une clé de ticket existante (ticketKey), puis Créer.

À l’exécution, l’agent demande la clé du ticket (format PROJET-NUMÉRO, par exemple SUPPORT-412) si le visiteur ne l’a pas donnée. Il reçoit alors le titre et le statut du ticket (par exemple « Ticket SUPPORT-412 — Connexion impossible (In Progress) ») et les reformule pour le visiteur.

Étape 5 — L’action « Mettre à jour un ticket JIRA »

1. Compétences › Catalogue › Configurer sur Mettre à jour un ticket JIRA.
2. Choisissez le connecteur JIRA. Aucun autre réglage.
3. Testez sur un ticket de test, puis Créer.

Informations remplies à l’exécution :

Seules les informations fournies sont envoyées à JIRA : sans priorité ni labels, ceux du ticket ne changent pas ; sans commentaire, aucun commentaire n’est ajouté. Au moins une information optionnelle doit être fournie pour que l’appel ait un sens.

Les champs à collecter de cette action sont joints à la fin du commentaire ; quand l’agent n’en écrit pas, les informations collectées forment le commentaire.

Exemple de conversation

Visiteur : Bonjour, j’ai un bug sur le formulaire de contact, il n’envoie rien quand je clique sur « Envoyer ».

Agent : Pouvez-vous m’en dire un peu plus ? Quel navigateur utilisez-vous, et un message d’erreur apparaît-il ?

Visiteur : Chrome 130, aucun message, le bouton reste cliquable mais rien ne se passe.

Agent : Merci. J’ai ouvert le ticket SUPPORT-418 dans notre outil de suivi. Notre équipe va le prendre en charge.

Limites connues

• JIRA Cloud uniquement. Les instances JIRA Server et JIRA Data Center ne sont pas prises en charge : les actions n’appellent que les adresses *.atlassian.net.
• Pas de sprints, d’epics liés, de transitions de workflow ni de champs personnalisés. Les trois modèles couvrent la création (titre, description, priorité, labels, projet, type), la lecture (titre et statut) et la mise à jour (commentaire, priorité, labels). Pour aller plus loin, voir Créer une action personnalisée.
• Pas de lien vers le ticket. L’agent connaît la clé du ticket créé, pas son adresse web.
• Pas de Markdown dans description ni comment. Le contenu est placé dans un seul paragraphe : sauts de ligne, listes et titres ne sont pas interprétés.
• labels en mise à jour est un remplacement. Si le ticket avait ["bug", "urgent"] et que l’agent envoie ["regression"], le ticket aura ["regression"].
• Création d’un Epic. Sur certaines instances, un Epic exige des champs supplémentaires (ex. : Epic Name) que le modèle ne gère pas : JIRA renverra une erreur. Utilisez plutôt Task ou Story.
• Délai de 10 secondes. Si votre instance JIRA répond trop lentement, l’action échoue (statut Expiration). Elle n’est pas relancée automatiquement.

Dépannage

Le code d’erreur apparaît au début du résumé, dans le résultat du test et dans le Journal de l’action.

Erreur 401 — Unauthorized

JIRA refuse l’authentification.

• Cause la plus fréquente : le jeton API a été révoqué ou mal copié (espace en trop, caractère manquant).
• Cause secondaire : l’Email API du connecteur n’est pas celui du compte qui a généré le jeton.
• À faire : régénérez le jeton, mettez à jour le connecteur, puis Enregistrer et tester.

Erreur 403 — Forbidden

Authentification correcte, mais le compte n’a pas les droits sur le projet ou l’opération.

• Vérifiez que le compte Atlassian a accès au projet ciblé.
• Vérifiez les permissions JIRA : Create Issues, Browse Projects, Edit Issues, Add Comments selon les actions utilisées.

Erreur 404 — Not Found

• À la création : la Clé du projet n’existe pas (faute de frappe, ou projet archivé).
• À la lecture / mise à jour : la clé de ticket donnée par le visiteur n’existe pas, ou appartient à un projet auquel le compte n’a pas accès.

Erreur 400 — Bad Request à la création

JIRA reçoit la requête mais refuse son contenu.

• Cause typique : le Type de ticket choisi n’existe pas dans ce projet, ou un champ obligatoire propre au projet manque (souvent pour Epic).
• À faire : créez un ticket à la main dans JIRA pour repérer les champs requis, puis changez le Type de ticket de l’action.

La description s’affiche sur une seule ligne

C’est attendu : le contenu est placé dans un seul paragraphe. Pour une description riche, modifiez le ticket directement dans JIRA après sa création.

Étape suivante

• Gérer vos identifiants JIRA : Connecteurs et authentification.
• Aller au-delà des champs standards : Créer une action personnalisée.
• Vérifier que tout fonctionne avant de laisser l’agent s’en servir : Tester et déboguer une action.