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

À quoi ça sert

Sens-AI propose trois actions JIRA prêtes à l’emploi :

Cas d’usage typiques :

• Un visiteur signale un bug → le bot ouvre automatiquement un ticket dans le projet SUPPORT.
• Un client demande « où en est mon ticket SUPPORT-412 ? » → le bot interroge JIRA et répond avec le statut courant.
• Une demande urgente arrive → le bot rajoute un commentaire « Client a relancé » et passe la priorité à High.

Prérequis

• Une instance JIRA Cloud (les URLs en *.atlassian.net — JIRA Server / Data Center n’est pas supporté).
• Un compte Atlassian avec les droits de créer / lire / modifier des tickets dans le projet visé.
• Un jeton API Atlassian (voir étape suivante).
• 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 + un jeton API (HTTP Basic). Pour générer le jeton :

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

Conseil : créez un compte Atlassian dédié à votre bot ([email protected]) plutôt que d’utiliser un compte personnel. L’historique JIRA sera plus lisible, et un départ d’employé ne cassera pas votre intégration.

Étape 2 — Créer le connecteur JIRA

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

1. Votre bot → Actions → onglet Connecteurs → Ajouter un connecteur.
2. Choisissez le modèle JIRA.
3. Remplissez les champs :
   • URL JIRA : https://votre-domaine.atlassian.net (sans / final, sans /rest/api/3).
   • E-mail Atlassian : l’e-mail du compte qui a généré le jeton.
   • Jeton API : la valeur copiée à l’étape 1.
4. Nommez le connecteur (ex. : JIRA Production).
5. Tester la connexion, puis Enregistrer.

Détails pratiques : Sens-AI appelle JIRA sur *.atlassian.net uniquement (les domaines extérieurs sont bloqués) et envoie l’authentification Basic base64(email:token) à chaque requête. Le délai d’attente d’une requête est de 10 secondes.

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

1. Votre bot → Actions → Ajouter une action.
2. Catalogue → JIRA — Créer un ticket JIRA.
3. Sélectionnez le connecteur créé à l’étape 2.
4. Configurez les champs spécifiques à cette action :
   • Clé du projet (obligatoire) : par exemple SUPPORT. C’est le préfixe des tickets de votre projet.
   • Type de ticket (obligatoire) : Task, Bug, Story ou Epic. Les types disponibles dépendent de la configuration de votre projet JIRA ; un type inexistant sur votre projet entraînera une erreur côté JIRA au moment de la création.
5. Donnez un nom à l’action (ex. : « Ouvrir un ticket support ») et une description que le LLM lira pour décider quand l’utiliser (ex. : « À utiliser quand le visiteur signale un bug ou demande l’ouverture d’un ticket »).
6. Testez l’action avant d’activer (cf. Tester et déboguer).

Champs que le bot remplit à l’exécution

Une fois l’action déclenchée par le LLM, ces informations sont collectées dans la conversation :

Le message renvoyé au visiteur à la fin contient la clé du ticket et son URL (par exemple : Ticket SUPPORT-412 créé : https://votre-domaine.atlassian.net/browse/SUPPORT-412).

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

1. Actions → Ajouter une action → JIRA — Consulter un ticket JIRA.
2. Sélectionnez le même connecteur JIRA.
3. Pas de configuration supplémentaire — l’action est prête.

À l’exécution, le bot demande au visiteur la clé du ticket (format PROJET-NUMÉRO, par exemple SUPPORT-412), puis interroge JIRA et restitue les champs suivants : summary, status, assignee, priority, created, updated. La réponse est ensuite reformulée naturellement par le bot (ex. : Ticket SUPPORT-412 — Connexion impossible (In Progress)).

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

1. Actions → Ajouter une action → JIRA — Mettre à jour un ticket JIRA.
2. Sélectionnez le connecteur JIRA.
3. Pas de configuration supplémentaire.

Champs collectés à l’exécution :

Au moins un champ optionnel doit être fourni pour que l’appel ait du sens — sinon JIRA recevra une requête vide.

Exemple de conversation

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

Bot : Pouvez-vous m’en dire un peu plus ? Quel navigateur utilisez-vous, et quel message d’erreur apparaît (si un message apparaît) ?

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

Bot : Merci. J’ai ouvert le ticket SUPPORT-418 dans notre outil de suivi. Vous pouvez le consulter ici : https://acme.atlassian.net/browse/SUPPORT-418. Notre équipe va le prendre en charge.

Limites connues

• JIRA Cloud uniquement. Les instances JIRA Server et JIRA Data Center (auto-hébergées) ne sont pas supportées : le connecteur n’autorise que les domaines *.atlassian.net.
• Pas de gestion des sprints, epics liés, transitions de workflow ou champs personnalisés dans les actions livrées en standard. Les trois actions couvrent : création (summary, description, priority, labels, projet, type), lecture (summary, status, assignee, priority, dates) et mise à jour (commentaire, priority, labels). Pour aller plus loin (changer le statut via une transition, remplir un champ custom, créer un sous-ticket), il faut créer une action personnalisée appelant directement l’API JIRA (cf. Créer une action personnalisée).
• Pas de Markdown dans description ni comment. Le contenu est encapsulé dans un document ADF avec un seul paragraphe texte. Les sauts de ligne, listes, titres et formatages ne seront pas interprétés.
• labels en mise à jour est un remplacement. Si le ticket avait ["bug", "urgent"] et que le bot envoie ["regression"], le ticket aura ["regression"] — bug et urgent sont supprimés.
• Création d’un Epic. Sur certaines instances JIRA, créer un Epic exige des champs personnalisés supplémentaires (ex. : Epic Name). L’action standard ne les gère pas et JIRA renverra une erreur ; utilisez plutôt Task ou Story depuis le bot, et faites les Epics à la main dans JIRA.
• Timeout 10 s. Si votre instance JIRA est lente à répondre, l’action échoue. Une nouvelle tentative est automatique (cf. la section sur les erreurs 5xx dans Tester et déboguer).

Dépannage

Erreur 401 — Unauthorized

JIRA refuse l’authentification.

• Cause la plus fréquente : le jeton API a été révoqué (depuis id.atlassian.com/manage-profile/security/api-tokens) ou a été mal copié (espace en trop, caractère manquant).
• Cause secondaire : l’adresse e-mail renseignée dans le connecteur n’est pas celle du compte qui a généré le jeton.
• À faire : régénérer le jeton, mettre à jour le connecteur, retester.

Erreur 403 — Forbidden

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

• Vérifiez que le compte Atlassian configuré 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é de projet n’existe pas (typo, ou projet archivé).
• À la lecture / mise à jour : la clé du ticket fournie 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 accepte la requête mais refuse le contenu.

• Cause typique : le type de ticket configuré (Task, Bug, Story, Epic) n’existe pas sur ce projet, ou un champ obligatoire spécifique au projet manque (souvent le cas pour Epic).
• À faire : ouvrez un ticket à la main dans JIRA pour identifier les champs requis ; si vous avez besoin de champs custom, passez par une action personnalisée.

L’URL renvoyée pointe vers une page « Issue does not exist » dans JIRA

• Le ticket a bien été créé mais l’utilisateur qui ouvre le lien n’est pas connecté à JIRA ou n’a pas le droit de voir ce projet. Le bot renvoie l’URL telle quelle ; JIRA gère les permissions de consultation.

La description ou le commentaire s’affiche sur une seule ligne

• C’est attendu : le contenu est encapsulé dans un paragraphe ADF unique. Pour des descriptions riches, éditez le ticket directement dans JIRA après création.

Étape suivante

• Centraliser plusieurs intégrations sur le même outil : Connecteurs et authentification.
• Aller au-delà des champs standards (statut, champs custom, sous-tickets) : Créer une action personnalisée.
• Vérifier que tout fonctionne avant la mise en production : Tester et déboguer une action.