Jira

Maintenu par OrkyvoVersion 1.0.0Inclus dans l'offre DevOps9 actions · 4 déclencheurs

Tickets Jira Cloud ou Data Center : création, recherche JQL, commentaires, assignation, transitions.

Intégration maintenue par Orkyvo pour Jira Cloud et Jira Data Center / Server, avec des profils de connexion distincts : Cloud (OAuth 2.0 avec choix du site, ou jeton d'API) et Data Center (jeton d'accès personnel, ou identifiant et mot de passe pour les versions antérieures). Les types de ticket, champs obligatoires et transitions sont lus sur votre Jira ; les descriptions et commentaires sont convertis au format ADF sur Jira Cloud. Déclencheurs : ticket créé, ticket modifié, commentaire ajouté, transition de statut.

Opérations

Opération	Type	Description
Lister les projets	action	Projets visibles par le compte (pagination bornée, 500 au plus).
Obtenir les champs d'un type de ticket	action	Champs disponibles et obligatoires, valeurs autorisées, pour un projet et un type de ticket (lus sur Jira).
Créer un ticketeffet externe : demande une confirmation avant une exécution manuelle	action	Crée un ticket. Les champs obligatoires du projet sont vérifiés avant l'envoi ; avec une clé de dédoublonnage, un ticket déjà créé est renvoyé au lieu d'un doublon.
Obtenir un ticket	action	Lit un ticket ; la description ADF est convertie en texte.
Modifier un ticketeffet externe : demande une confirmation avant une exécution manuelle	action	Modifie résumé, description, priorité, échéance, libellés ou champs supplémentaires. Seuls les champs renseignés sont envoyés.
Rechercher (JQL)	action	Recherche JQL : /search/jql (jeton de page) sur Cloud, /search (startAt) sur Data Center ; 1 000 résultats au plus.
Ajouter un commentaireeffet externe : demande une confirmation avant une exécution manuelle	action	Commente un ticket (ADF sur Cloud), visibilité restreinte à un rôle en option.
Assigner un ticketeffet externe : demande une confirmation avant une exécution manuelle	action	Assigne (ou désassigne si vide) un ticket.
Changer le statut (transition)effet externe : demande une confirmation avant une exécution manuelle	action	Applique une transition du workflow Jira, par nom, identifiant ou statut cible ; les transitions sont lues sur le ticket.
Ticket créé	déclencheur	Démarre le workflow pour chaque nouveau ticket correspondant au filtre.
Ticket modifié	déclencheur	Démarre le workflow à chaque modification d'un ticket correspondant au filtre.
Commentaire ajouté	déclencheur	Démarre le workflow pour chaque nouveau commentaire sur un ticket correspondant au filtre.
Transition de statut	déclencheur	Démarre le workflow quand un ticket change de statut (historique des modifications).

Connexion

Choisissez votre déploiement : les adresses et méthodes d'authentification de Jira Cloud et de Jira Data Center ne sont jamais mélangées. Utilisez un compte dédié aux droits limités aux projets concernés.

Documentation

Jira

Intégration maintenue par Orkyvo (non certifiée par Atlassian) pour Jira Cloud et Jira Data Center / Server.

Profils de connexion (distincts)

Les adresses, versions d'API et méthodes d'authentification de Cloud et de Data Center ne sont jamais mélangées : le profil choisi détermine l'URL de base et l'en-tête envoyé.

Profil	URL de base des appels	Authentification	Versions
Cloud · OAuth 2.0 (recommandé)	`https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3`	Jeton d'accès OAuth 2.0 (3LO), renouvelé côté serveur	Jira Cloud
Cloud · jeton d'API	`https://<site>.atlassian.net/rest/api/3`	Basic (adresse e-mail + jeton d'API)	Jira Cloud
Data Center · jeton d'accès personnel	`<URL>/rest/api/2`	`Authorization: Bearer <PAT>`	Jira Data Center / Server 8.14 ou ultérieur
Data Center · identifiant et mot de passe	`<URL>/rest/api/2`	Basic	Versions antérieures à 8.14 (à éviter si possible)

Jira Cloud avec OAuth 2.0

Prérequis (administrateur du serveur Orkyvo) : une application OAuth 2.0 (3LO) dans la console développeur Atlassian, avec l'URL de rappel https://<votre-domaine-orkyvo>/api/oauth/atlassian/callback et les portées read:jira-work, write:jira-work, read:jira-user (+ offline_access, ajoutée automatiquement). Ses identifiants sont fournis au serveur par ATLASSIAN_CLIENT_ID et ATLASSIAN_CLIENT_SECRET.
Créez la connexion (Jira Cloud · OAuth 2.0), enregistrez-la, puis cliquez sur « Se connecter avec Atlassian ».
Après votre consentement, choisissez le site si votre compte en voit plusieurs.
Les jetons sont chiffrés ; le jeton de renouvellement (rotatif) ne quitte jamais le serveur, seul un jeton d'accès de courte durée est transmis au nœud.

Sans application OAuth configurée sur le serveur, utilisez le profil jeton d'API.

Data Center

Jetons d'accès personnels : *Profil → Jetons d'accès personnels* (Jira 8.14+). « Tester la connexion » lit la version (/serverInfo) et signale un jeton d'accès personnel utilisé sur une version trop ancienne. Instance privée : une règle d'un administrateur de la plateforme est nécessaire (Administration → Réseaux privés) ; autorité de certification interne acceptée, vérification TLS toujours active.

« Tester la connexion » lit /myself et /serverInfo : aucune écriture.

Droits limités : utilisez un compte dédié membre des seuls projets concernés (permissions *Parcourir les projets*, *Créer des tickets*, *Modifier*, *Ajouter des commentaires*, *Assigner*, *Transitionner* selon vos workflows).

Actions

Action	Cloud (v3)	Data Center (v2)
Lister les projets	`GET /project/search` (paginé)	`GET /project`
Champs d'un type de ticket	`GET /issue/createmeta/{projet}/issuetypes/{type}`	idem (Jira 8.4+)
Créer un ticket	`POST /issue` (description ADF)	`POST /issue` (texte wiki)
Obtenir / modifier un ticket	`GET` / `PUT /issue/{clé}`	idem
Rechercher (JQL)	`POST /search/jql` (`nextPageToken`)	`POST /search` (`startAt`)
Commenter	`POST /issue/{clé}/comment` (ADF)	idem (texte)
Assigner	`PUT /issue/{clé}/assignee` (`accountId`)	idem (`name`)
Transition	`GET` puis `POST /issue/{clé}/transitions`	idem

Types, champs obligatoires et transitions lus sur Jira : « Créer un ticket » vérifie les champs obligatoires du projet et du type avant l'envoi et nomme ceux qui manquent (ex. customfield_10050). Les transitions sont résolues par nom, identifiant ou statut cible, avec la liste des transitions possibles en cas d'erreur.
ADF : sur Cloud, descriptions et commentaires saisis en texte sont convertis (paragraphes, titres #, listes -, blocs de code, gras, liens) ; en sortie, l'ADF est converti en texte lisible.
Sans doublon : avec une clé de dédoublonnage, un libellé technique orkyvo-… est ajouté ; un ticket portant déjà ce libellé est renvoyé (existing: true). Une création n'est jamais relancée automatiquement après une réponse réseau perdue.
Pagination bornée : 1 000 résultats par recherche, 500 projets.

Déclencheurs : interrogation JQL persistante

Les webhooks Jira exigent des droits d'administration (Data Center) ou une application enregistrée (Cloud) ; Orkyvo interroge donc Jira côté serveur, toutes les 60 s par défaut (30 s minimum) :

Premier passage : point de départ enregistré, rien n'est rejoué.
Passages suivants : JQL … AND updated >= -Nm ORDER BY updated ASC (fenêtre relative, indépendante du fuseau horaire du compte), 100 tickets au plus.
Identifiants stables (ticket + date de modification, commentaire, entrée d'historique) : doublons écartés, curseur conservé en base et repris après un redémarrage.

Déclencheur	Détection
Ticket créé	`created`
Ticket modifié	`updated`
Commentaire ajouté	commentaires du ticket postérieurs au curseur
Transition de statut	historique (`changelog`) : champ `status`, statut cible filtrable

Erreurs

401 identifiants refusés ou autorisation expirée (reconnecter Atlassian) · 403 permission de projet manquante · 404 ticket ou projet introuvable · 400 champ invalide (message de Jira) · 429 limite de débit (lectures relancées selon Retry-After) · 5xx indisponibilité.

Limites

Tests automatisés sur API simulées ; test réel sur un site Jira Cloud gratuit ou une instance Data Center d'évaluation : docs/INTEGRATIONS.md.