JQL, ou Jira Query Language, est un outil flexible qui vous permet de rechercher des demandes dans Jira et de définir avec précision ce que vous recherchez.

Savoir effectuer une recherche efficace dans votre instance Jira peut littéralement vous faire économiser des heures de travail.

Même si les utilisateurs chevronnés qui utilisent Jira quotidiennement maîtrisent le langage de requête Jira, des compétences en rédaction de requêtes efficaces peuvent être très utiles à d’autres membres de l’équipe.

Voici ce que nous allons présenter dans cet article :

• Qu’est-ce que le JQL ?
• Anatomie d’une requête JQL
• Un tutoriel JQL : Pour faire la synthèse
• Utilisation des fonctions Jira JQL pour les recherches avancées
• La délimitation ou le tri dans JQL : pour affiner vos résultats.
• Astuces JQL intelligentes
• Modules complémentaires JQL

De nombreux utilisateurs Jira ne sont pas attirés par la technique et ont tendance à négliger JQL. Certains termes comme “opérateurs” et “mots-clés” peuvent repousser les employés qui ne baignent pas dans ce secteur. C’est exactement le cas pour moi quand j’ai commencé à utiliser Jira !

Mais cet outil a été conçu pour que n’importe qui puisse profiter de ses fonctionnalités. Même les utilisateurs peu attirés par la technique peuvent s’y familiariser s’ils sont correctement guidés. Par exemple, si vous voulez trouver toutes les demandes qui vont sont affectées, tapez juste « my » dans la barre de recherche ou « r:me » pour obtenir toutes les Issue que vous avez rapportées. Et ce n’est qu’une infime partie de ce que cet outil propose !

Dans ce guide, nous vous accompagnerons dans la découverte de tous les concepts fondamentaux que vous devez connaître pour maîtriser JQL et devenir un pro de la recherche Jira.

Qu’est-ce que le JQL ?

Le Jira Query Language (ou JQL) est l’un des outils les plus puissants disponibles dans Jira.

Le système utilise les données suivantes pour filtrer les demandes :

• Champs
• Opérateurs
• Valeurs
• Mots clés
• Fonctions

En retour, il vous aide à trouver beaucoup plus vite ce que vous recherchez.

Par exemple, si vous souhaitez rechercher toutes les Issues non planifiées, vous pouvez rechercher celles ayant un champ de statut non clôturé et des champs vides au niveau des liens récits et des versions fixes.

De plus, imaginons que vous ayez besoin de savoir si votre projet a des problèmes quant à sa portée. Vous pouvez affiner votre recherche aux Issues qui ne sont pas clôturées dans le sprint en cours AND (ET) qui ont déjà été affectées à un autre sprint. Cela vous indiquera combien d’Issues se situaient hors de la portée du projet dans le dernier sprint et qui n’ont pas pu être terminées.

Le JQL est également bien plus performant depuis la sortie de Jira 8.0. Le JQL actuel cherche 33 % plus vite que Jira 7.12 et élimine pratiquement tous les problèmes de mémoire rencontrés auparavant pendant les recherches complexes.

Aperçu de l’interface de Jira Query Language

Sous « Issues », dans le menu déroulant, vous pouvez voir l’option « Rechercher des Issues » :

Cela permet d’ouvrir l’écran de recherche. Par défaut, cet écran vous amène à l’outil de recherche de base. Vous pouvez l’utiliser pour filtrer des Issues à l’aide de champs prédéfinis, comme par exemple :

• Status (Statut)
• Assignee (Responsable)
• Project (Projet)
• Contains text (Contient du texte)

Vous remarquerez l’option « Advanced » (Avancé) sur la droite des filtres :

C’est à partir de là que vous avez accès au JQL de Jira.

Recherche de base et recherche avancée dans Jira

Les recherches de base dans Jira sont utiles mais sont limitées. Elles sont rapides à remplir et faciles à utiliser.

Cependant, vous en atteindrez les limites assez rapidement dues aux formulaires existants.

Grâce à la recherche avancée, vous allez pouvoir créer vos propres requêtes JQL.

Anatomie d’une requête JQL

Une requête JQL est un ensemble de mots et d’opérateurs qui définissent la manière dont Jira affinera votre recherche.

Dans les recherches de base, les requêtes sont déjà prédéfinies pour vous. Par contre, il vous faudra les réécrire entièrement dans JQL.

Toutes les requêtes sont composées de champs, d’opérateurs et de valeurs.

Les champs dans Jira Query Language

Un champ est un élément d’information qui décrit des Issues – c’est ce que vous remplissez quand vous faites des recherches de base.

Voici quelques exemples de champs Jira :

• Issue type (Type de demande)
• Project (Projet)
• Priority (Priorité)
• Fix Version (Version fix)
• Étiquette Récit (Epic tag)

Vous pouvez consulter la liste de tous les champs dans la documentation de Jira.

Les valeurs dans Jira Query Language

Les valeurs sont des points de données dans vos requêtes.

Ce sont ces valeurs que vous recherchez par rapport à vos champs.

Par exemple, les valeurs possibles du champ priorité seraient :

• Urgente
• Forte
• Moyenne
• Faible

Les opérateurs dans Jira Query Language

Les opérateurs sont des signes mathématiques comme “égal à” (=), “non égal” à (!=), “supérieur à” (>), “inférieur ou égal à” (<=), etc.

Ils décrivent le lien entre votre champ et votre valeur.

Par exemple :

Dans la recherche ci-dessus, vous recherchez les Issues ayant un Epic Name (champ) égal à (opérateur) « Audio Development » (valeur).

« IN » (« DANS ») est aussi utile et vous permet de simplifier les requêtes. Au lieu de lancer des requêtes à statuts multiples, par exemple, vous pouvez utiliser la requête suivante :

statut IN (DANS) (« À faire », « En cours », « Clôturé »)

Vous pouvez aussi utiliser :

issue IN linkedIssues(“ID-101 »)

Ceci permet d’identifier toutes les Issues liées à une Issue spécifique. Vous pouvez aussi utiliser « NOT IN » (« PAS DANS ») pour identifier tout ce qui ne fait pas partie de cette requête.

Un autre opérateur puissant est « CONTAINS » (« CONTIENT »), qui vous permet de rechercher les champs sommaire, description, environnement et commentaires et les champs personnalisés qui ont recours à la « Recherche par texte libre ».

« WAS » (« ÉTAIT »), pour sa part, vous permet de faire apparaître tout ce qui était auparavant connecté à un état donné mais qui ne l’est plus, par ex. :

assignee WAS francis

Vous pouvez utiliser « WAS » (« ÉTAIT ») ainsi que « WAS NOT » (« N’ÉTAIT PAS »), « WAS IN” (« ÉTAIT DANS ») et « WAS NOT IN » (« N’ÉTAIT PAS DANS ») selon vos besoins.

Les mots clés dans Jira Query Language

Les mots clés constituent le langage JQL. Chaque mot clé a un sens spécifique qui affine davantage la recherche, comme « AND » (« ET ») et « OR » (« OU »).

En tapant “AND” (« ET ») dans votre requête, vous obtiendrez les Issues qui correspondent aux deux conditions de votre recherche.

Par exemple, cette recherche présente toutes les Issues qui sont actuellement en priorité élevée et qui ont également le statut « To Do » (à faire) :

D’un autre côté, « OR » (« OU ») présente toutes les Issues qui remplissent l’une de vos conditions.

La même recherche que précédemment avec le mot clé « OR » (« OU ») donnerait :

• toutes les Issues qui ont une priorité élevée,
• toutes les Issues qui ont un statut « To Do » (à faire),
• et toutes les Issues qui ont une combinaison de ces deux conditions.

Un tutoriel JQL : Pour faire la synthèse

Maintenant que vous connaissez les bases, examinons un exemple de JQL dans Jira.

Quand vous cliquez sur « Advanced Search » (Recherche avancée), vous obtenez une barre de recherche sans filtres prédéfinis.

Une fois que vous commencez à taper votre requête, Jira vous indique si votre requête est valide à l’aide d’une coche verte sur la gauche. Si vous obtenez un X rouge, cela signifie que votre recherche n’est pas valide :

Si vous avez besoin d’aide pour référencer la syntaxe, vous pouvez toujours cliquer sur le point d’interrogation à droite de la fenêtre de recherche.

Ce qui est vraiment pratique avec Jira JQL, c’est qu’il vous donne des suggestions automatiques au fur et à mesure de votre saisie. Cela vous permet d’obtenir la syntaxe exacte lorsque vous ne la connaissez pas par cœur.

Par exemple, supposons que nous commencions notre requête en cherchant dans le champ « Priority » (« Priorité »). Vous pouvez taper « Priority » (« Priorité ») dans le champ de recherche et JQL suggérera automatiquement ce qui est supposé suivre : un opérateur.

Vous pouvez alors cliquer sur l’un des opérateurs suggérés pour continuer à construire votre requête JQL.

Exemple de Jira Query Language avec AND

Pour cet exemple, imaginons que nous voulons trouver toutes les Issues urgentes qui ne sont pas résolues dans un lien Epic spécifique.

Votre requête ressemblerait à ceci :

Comment cette requête cadre-t-elle avec ce que nous avons appris auparavant ? Prenons chaque section de cette requête et décomposons-la étape par étape :

Priority (Priorité) : Champ

= : Opérateur (égal à)

Urgent (Urgente) : Valeur du champ « Priority »

AND : Mot clé

Status (Statut) : Champ

!= : Opérateur (pas égal à)

Done (Terminé) : Valeur du champ « Status »

AND : Mot clé

« Epic Link » (« Lien Epic ») : Champ

= : Opérateur (égal à)

STAN-5 : Valeur du champ « Epic Name » (Nom de l’Epic)

Exemple JQL pour le mot clé « OR »

Comment faire si vous recherchez des Issues urgentes qui ne sont pas résolues pour un Epic spécifique, mais que vous souhaitez également voir des Issues à priorité élevée ?

Exécutons à nouveau la même requête, mais cette fois en utilisant « OR » :

Le reste de la requête est identique, à l’exception de l’ajout d’un mot clé « OR » et d’une requête pour les Issues de haute priorité.

L’ordre de priorité dans JQL

Mais que se passe-t-il si vous utilisez les deux mots clés « AND » et « OR » ? En bref, « AND » prend le dessus. Cela signifie que si deux conditions sont reliées par un « AND », elles seront regroupées et traitées comme une seule unité. Les conditions liées par un « OR », par contre, seront traitées comme des unités séparées. Par conséquent :

Exemple. 1: status=resolved OR project=”Planning” AND assignee=Francis

Exemple. 2: status=resolved AND project=”Planning” OR assignee=Francis

Dans l’exemple 1, la requête donnera tous les éléments résolus en plus de tous les éléments affectés à Francis dans le projet Planning. Dans l’exemple 2, la requête donnera tous les éléments résolus du projet Planning et tous les éléments affectés à Francis. Cela dit, si vous écrivez :

status=resolved AND (project=”Planning” OR assignee=Francis)

vous obtiendrez tous les éléments résolus du projet Planning ainsi que les éléments résolus affectés à Francis.

Utilisation des fonctions Jira JQL pour les recherches avancées

Vous pouvez faire beaucoup avec les champs, les valeurs, les opérateurs et les mots-clés. Mais si vous souhaitez exploiter une logique complexe facilement accessible, vous avez besoin de fonctions.

Une fonction est une commande prédéfinie que les utilisateurs peuvent intégrer à leur requête pour obtenir certaines valeurs.

Les fonctions sont toujours représentées sous forme d’un mot suivi de parenthèses contenant des champs ou des valeurs.

Par exemple, si on voulait trouver toutes les demandes liées dans une autre Issue, on pourrait utiliser la fonction linkedIssues () :

La valeur entre parenthèses est la demande dans laquelle on recherche les liens.

Toutes les fonctions JQL n’ont pas besoin d’avoir une valeur entre parenthèses. Par exemple, si vous souhaitez savoir quelles Issues sont affectées à un sprint terminé, vous devez saisir les éléments suivants :

sprint in closedSprints();

Les fonctions Jira JQL sont particulièrement puissantes lorsqu’elles sont combinées avec les autres éléments de JQL.

Supposons que j’essaie de rechercher les Issues urgentes d’un projet (cet article, par exemple) qui doivent être réglées dans les deux jours et attribuées à un utilisateur spécifique (moi). La fonction endOfDay () serait utile ici.

La requête ressemblerait à ceci :

due < endOfDay(“+2”) AND assignee = francis AND project = “BLOG” AND priority = Urgent

J’ai ajouté +2 à la fonction endOfDay () car je veux savoir ce qui doit être terminé dans deux jours. Alors que la fonction JQL ne donnerait que ce qui doit être terminé à la fin de la journée en cours.

Comme vous pouvez le constater, on a 3 mots clés « AND », qui séparent 4 conditions différentes dans notre requête JQL. Si on devait traduire cette information par un graphique, il ressemblerait à ceci :

Remarque : Pour obtenir une liste de toutes les fonctions disponibles, de la syntaxe appropriée et des champs et des opérateurs pris en charge, vous pouvez vous reporter à la page de référence d’Atlassian.

La délimitation ou le tri dans JQL : pour affiner vos résultats.

Bien que Jira JQL soit assez doué pour affiner un résultat à partir d’un grand nombre d’Issues, il se peut que le résultat de votre requête vous en donne une trop grande quantité.

À ce stade, la délimitation et le tri entrent en jeu pour vous aider à obtenir les informations dont vous avez besoin, dans l’ordre de priorité qu’il vous faut.

La délimitation

La délimitation implique de cibler votre requête de manière spécifique afin que la recherche ne renvoie que les informations qui vous intéressent.

Il peut souvent être fastidieux de commencer par une requête longue et complexe lorsque vous effectuez votre recherche. Vous pouvez donc commencer par une recherche large et affiner à partir de là.

Voici un exemple.

Commençons par une requête très générale : toutes les demandes en suspens d’un projet spécifique :

Project = “BLOG” AND status = open

Cela va vous donner un grand nombre d’Issues, alors affinons la recherche par sprint en cours :

Project = “BLOG” AND status = open AND fixVersion = “Current Sprint”

Imaginons qu’on veut savoir quelles Issues étaient urgentes ou à priorité élevée dans notre sprint actuel et ont été déplacées depuis le dernier sprint pour savoir si des Issues urgentes sont laissées de côté. Vous pouvez affiner la recherche comme ceci :

Project = “BLOG” AND status = open AND fixVersion = “Current Sprint” AND fixVersion WAS “Last Sprint” AND (priority = Urgent OR priority = High)

Avec la recherche ci-dessus, vous obtiendrez une vue très spécifique des Issues prioritaires ou urgentes reportées depuis le dernier sprint.

Cela vous permettra d’enquêter sur la fréquence à laquelle cela se produit et pourquoi.

Le tri

Par ailleurs, le tri JQL vous permet de classer la liste des Issues obtenues d’une manière spécifique à l’aide du mot clé « ORDER BY » (« TRIER PAR »).

Je vous explique ce que je veux dire par là.

Si vous voulez que la requête ci-dessus soit triée par responsable, vous pouvez la compléter comme ceci :

Project = “BLOG” AND status = open AND fixVersion = “Current Sprint” AND fixVersion WAS “Last Sprint” AND (priority = Urgent OR priority = High) ORDER BY assignee

Si vous voulez trier vos Issues en utilisant plus d’un champ – par exemple, par responsable et par échéance – vous devez lister vos champs de tri par ordre de priorité :

ORDER BY assignee, duedate

Dans la requête ci-dessus, Jira vous donnerait d’abord une liste d’Issues triées par responsable, puis triées par échéance pour toutes les Issues concernant le même responsable.

Astuces JQL intelligentes

Voilà pour les bases de l’utilisation de Jira Query Language.

Cependant, il existe de nombreuses autres fonctionnalités qui vous permettront d’économiser encore plus de temps et d’éviter les tracas.

Examinons quelques astuces JQL futées.

Enregistrement des filtres JQL

Pas besoin de ressaisir les mêmes filtres encore et encore. Si vous avez besoin de faire la même requête régulièrement, vous pouvez l’enregistrer pour une utilisation ultérieure.

Vous pouvez configurer vos filtres pour qu’ils apparaissent sur votre tableau de bord. De cette façon, vous aurez accès à vos résultats de recherche en un seul coup d’œil.

Pour enregistrer votre filtre actuel, cliquez sur le bouton « Save As » (« Enregistrer sous ») situé en haut à gauche. Vous serez invité à nommer votre filtre.

Notez que cette fonctionnalité est également disponible pour les recherches de base.

Partage de vos requêtes JQL

Une fois qu’un filtre est créé, vous pouvez le sélectionner pour le partager avec d’autres utilisateurs.

Vous pouvez le faire de plusieurs façons :

• Utiliser le bouton « Share » (« Partager »), en haut à droite
• Exporter le filtre sous un autre format en utilisant le bouton « Export » (« Exporter ») (à côté de « Share » (« Partager »))
• Modifier les autorisations sur votre filtre pour ajouter plus d’utilisateurs

Abonnements planifiés

Un abonnement obligera Jira à exécuter des requêtes JQL de manière planifiée et à vous envoyer les résultats par e-mail.

Cela vous évitera de vous connecter régulièrement à Jira uniquement pour effectuer une requête vous-même.

Vous pouvez même envoyer vos abonnements à d’autres utilisateurs.

Quand vous configurez un nouvel abonnement, vous pouvez choisir de les planifier selon un intervalle de temps spécifique, comme ci-dessous :

Cela est particulièrement utile pour :

• Créer des rapports sur une base régulière
• Garder une trace des demandes importantes
• Obtenir une visibilité des nouvelles demandes entrantes

Cohérence de la dénomination des filtres

Quand vous vous retrouvez avec plusieurs filtres, il est important d’utiliser une nomenclature de dénomination cohérente.

Par exemple, vous ne voulez pas que vos noms de filtres ressemblent à ceci :

• OrderedByDueDate_ClosedSprint_BlogWritingEpic
• AudioDevEpic_OrderedByAssignee_CurrentSprint

En regardant les deux noms de filtres ci-dessus en un coup d’œil, il est très difficile de les organiser car ils semblent avoir été nommés de manière aléatoire.

Utilisez une nomenclature spécifique pour le suivi de vos filtres et assurez-vous que votre équipe fait de même.

Cela permet de s’assurer que tout le monde comprend à quoi servent les filtres. Cela évite aussi aux autres utilisateurs de créer des filtres en double s’ils n’ont pas pris conscience que ce filtre existait déjà.

Par exemple, si on devait nommer les deux filtres ci-dessus, on pourrait utiliser la nomenclature suivante :

Sprint_Epic_OrderedBy

Cela nous donnerait les noms suivants :

• ClosedSprint_BlogWritingEpic_OrderedByDueDate
• CurrentSprint_AudioDevEpic_OrderedByAssignee

Vous ne regretterez pas d’avoir fait cela, quand vous rechercherez plus tard des filtres spécifiques !

Suivi de projet

Un certain nombre de champs JQL sont particulièrement utiles pour le suivi de projet.

• “workRatio” – rechercher des Issues selon le pourcentage de travail déjà réalisé, par exemple, “workRatio > 25” (quand plus de 25 % du travail est terminé)
• “worklogDate” – trouver des Issues qui ont des commentaires dans des entrées du worklog sur des plages de dates spécifiques, “worklogDate > “2020/12/12″”
• “worklogAuthor” – rechercher les Issues par utilisateurs ayant consigné leur travail, vis-à-vis d’eux-mêmes, par exemple, “worklogAuthor = “Francis””
• “watchers” – suivre les Issues selon le nombre de personnes qui les regarde, par exemple, “watchers > 10”
• “watcher” – vous permet de visualiser les Issues que certaines personnes suivent ; et «voter» et «votes» ont des fonctions équivalentes.

Modules complémentaires JQL

Si vous maîtrisez les bases de JQL, Atlassian Marketplace propose plusieurs plug-ins prêts à être installés pour améliorer votre expérience de recherche :

• JQL Tricks Plugin : Ce plugin offre plus de 50 fonctions supplémentaires. Il vous permet également de limiter la fonctionnalité du plug-in aux groupes sélectionnés et/ou de limiter les fonctions individuelles aux projets sélectionnés.
• JQL Search Extensions : Ces add-ons de mots-clés faciles à utiliser étendent vos possibilités pour la recherche d’Issues, de commentaires, de sous-tâches, de pièces jointes, de versions, de récits et de liens. C’est actuellement l’extension de recherche la plus populaire pour Jira Cloud.
• JQL Booster Pack : Avec ce plug-in, vous aurez plus de 15 fonctions pour étendre vos capacités de recherche. Celles-ci incluent des fonctions liées aux utilisateurs pour un meilleur contrôle de l’équipe et pour une vue d’ensemble des activités récentes de vos utilisateurs et des fonctions pour supprimer les versions archivées.
• JQL Functions Collection : Les fonctions supplémentaires disponibles dans ce plugin permettent des fonctionnalités plus complexes ayant recours à des formats de chaîne et de date.
• Groups and Organisations JQL : Avec deux paires de fonctions simples à utiliser, vous pouvez faire correspondre les valeurs de champs personnalisés à un ou plusieurs groupes avec des groupes d’utilisateurs, mais aussi, le champ Organisations avec les organisations auxquelles un utilisateur appartient.
• Scripted JQL Functions : Pratique, ce plugin vous permet d’exploiter les fonctions JQL sans avoir à apprendre le SDK Atlassian. C’est à la fois une bibliothèque de fonctions JQL que vous pouvez modifier/étendre et un moyen simple de créer vos propres fonctions JQL.

Conclusion

Voici la conclusion sur les bases de JQL !

Désormais, vous avez savez comment évaluer et trier les bases de données Jira, que nous venons de vous exposer :

• L’anatomie d’une requête JQL
• Comment utiliser des mots-clés et des opérateurs pour affiner votre recherche dans plusieurs domaines ?
• Comment utiliser le champ d’application et le tri pour tirer le meilleur parti de JQL ?
• Comment sauvegarder les filtres et les abonnements pour gagner du temps lors de vos futures recherches

La maîtrise de JQL vous permettra de naviguer rapidement dans Jira et d’obtenir une meilleure valeur du produit. En tirant le meilleur parti de l’ensemble des fonctionnalités de Jira, vous serez également en mesure de gérer vos projets et d’ajuster vos workflow de manière beaucoup plus efficace- pour rendre votre équipe meilleure, plus rapide et plus performante !

Lectures recommandées :

• Guide des bonnes pratiques relatives au workflow Jira (avec exemples concrets)
• Intégration Jira ServiceNow : comment configurer une intégration en 6 étapes
• Intégration et déploiement continu d’un projet IT avec Jira Software et Bitbucket Cloud
• Le guide de la migration Jira: préparation, planification, tests et exécution