Introduction au langage de requête Jira (JQL) pour la recherche dans Jira

Effectuer une recherche simple dans Jira

En général, Jira propose deux interfaces de recherche simples permettant aux utilisateurs de trouver rapidement des tickets : le champ de recherche et la recherche avancée avec JQL (Jira Query Language).

Le champ de recherche

Vous le trouverez dans la barre de menu en haut à droite, à côté de votre profil utilisateur (Jira Server & Data Center). Dans la version cloud de Jira, vous trouverez le champ de recherche en cliquant sur la loupe dans la barre de navigation de gauche. Les utilisateurs peuvent saisir un mot-clé pour effectuer une recherche rapide basée sur l'identifiant du ticket, le résumé, les commentaires et la description. De plus, vous pouvez utiliser la syntaxe de recherche simple « Smart Querying », qui ressemble à celle de votre boîte de réception Gmail. Cette fonctionnalité est utile si vous souhaitez trouver rapidement le ticket souhaité. Il n’est toutefois pas possible de saisir des détails pour affiner vos requêtes de recherche.

Option de menu « Rechercher des opérations »

L'option de menu « Rechercher des opérations » constitue une autre interface de recherche. Vous pouvez y accéder via l'onglet « Opérations ». Dans la version de base, les utilisateurs peuvent filtrer les tâches à l’aide des champs disponibles dans leur instance. Notez que cette fonction de recherche ne se limite pas au très petit nombre de champs faisant partie du champ de recherche décrit ci-dessus.

Le filtrage s’effectue ici via une interface utilisateur simple comprenant des listes déroulantes et des champs de saisie. Pour vous faciliter la tâche, certains champs fréquemment utilisés sont prédéfinis : projet, type de tâche, statut et responsable. Vous pouvez ajouter d’autres champs en cliquant sur « Plus » et en sélectionnant les champs selon lesquels vous souhaitez effectuer votre recherche.

Ce qui est astucieux avec cette fonctionnalité, c'est que les options de filtrage de chaque champ sont mises à jour dynamiquement en fonction du type de champ que vous sélectionnez.

Même si elle est plus avancée que le simple champ de recherche, cette fonction de recherche a ses limites. C'est là que le JQL peut s'avérer utile.

L'interface de recherche « Rechercher des tickets » propose aux utilisateurs un outil de recherche plus puissant : le JQL. Cliquez sur « Avancé » pour faire apparaître un grand champ de saisie. Si vous avez déjà lancé une recherche simple, ses résultats s'affichent dans ce champ. C'est là que la magie du JQL opère.

Le Jira Query Language (JQL) est essentiellement un langage de recherche textuel qui vous permet de rechercher des tickets dans Jira. Il utilise une syntaxe lisible par l’utilisateur pour proposer une logique et des opérateurs plus complexes que ceux disponibles dans la fonction de recherche de base.

Voici un exemple pour vous montrer comment fonctionne le JQL :

project = SCRUM AND (Reporter = admin OR Assignee = admin)

Cette instruction JQL est assez simple. Aucune connaissance technique n’est nécessaire pour la lire et la comprendre. Elle contient simplement une liste des tickets du projet SCRUM1 dont le « Reporter » (auteur) ou l’« Assignee » (responsable) correspond à l’utilisateur « Admin ».

La requête est très simple, mais vous ne pouvez pas créer quelque chose de similaire dans l’écran « Rechercher des tickets ». Voici pourquoi : la recherche standard limite l’utilisation des mots-clés. Vous ne pouvez inclure ni AND ni OR dans votre requête de recherche. En JQL, vous pouvez le faire – et la combinaison de ces mots-clés est beaucoup plus facile à représenter dans la syntaxe textuelle que dans une syntaxe graphique.

Nous pouvons diviser la syntaxe JQL en cinq éléments clés : les champs, les opérateurs, les valeurs, les mots-clés et les fonctions.

En combinant ces éléments, vous pouvez créer des clauses logiques afin de trouver des ensembles spécifiques ou des tickets individuels.

Voici par exemple une clause combinant un champ, un opérateur et une valeur :
Created >= 15/05/2019

Dans cet exemple, vous trouverez tous les tickets créés à partir du 15 mai 2019. « Created » fait office de champ, « >= » est un opérateur et « 2019-05-15 » fait office de valeur de date. Ensemble, ils forment une expression complexe qui vous permet de trouver facilement les tickets dont vous avez besoin.

La beauté du JQL réside dans sa flexibilité et sa polyvalence. Vous pouvez combiner ces éléments de base de différentes manières pour créer des requêtes très complexes.

Tous ces éléments peuvent être combinés de multiples façons pour former des requêtes très complexes. Lorsque vous créez une requête JQL avancée, commencez par une requête simple, puis développez-la étape par étape. Reliez plusieurs clauses à l’aide de mots-clés tels que AND ou OR pour obtenir une requête qui renvoie les résultats souhaités.

Instructions JQL plus complexes

Essayez d'écrire une instruction JQL qui affiche tous les tickets contenant une description, créés cette année, faisant partie de la version 4.0 ou de la version 5.0, ou marqués comme prioritaires.

La première condition que nous devons inclure dans notre requête concerne la description. Nous recherchons uniquement les tickets dont le champ « Description » est renseigné. Nous écrivons donc :
Description IS NOT EMPTY

Ensuite, nous devons ajouter une clause permettant de trouver tous les tickets créés cette année. Pour cela, nous devons utiliser le champ « created », l’opérateur « supérieur ou égal à » que nous avons utilisé dans l’exemple précédent (>=), et cette fonction : startOfYear(). Nous devons combiner cette clause avec celle que nous venons d’écrire à l’aide du mot-clé AND.

Nous obtenons donc la chaîne suivante :
Description IS NOT EMPTY AND created >= startOfYear()

Enfin, nous devons ajouter une clause OR permettant de trouver les tickets qui font partie soit de la version 4.0, soit de la version 5.0, soit qui sont marqués comme prioritaires.

Pour cela, nous utilisons le champ « fixVersion » avec « IN » et une liste de versions. Puis nous le combinons avec un mot-clé OR et une autre clause permettant de trouver les tickets ayant une priorité spécifique. Cette dernière clause de priorité est une clause simple composée d’un champ + d’un opérateur + d’une valeur.

Voici à quoi cela ressemble :
fixVersion in (« Version 1.0 », « Version 2.0 ») OU priority = 1

Nous devons maintenant combiner cela avec l’instruction JQL écrite précédemment pour créer la requête de recherche complète. C’est là que les parenthèses entrent en jeu. Il est important de savoir comment les utiliser, car elles garantissent l’ordre correct des opérations dans une instruction JQL.

Dans notre exemple, nous devons nous assurer que la dernière clause OR soit traitée avant les autres clauses AND précédentes. Les deux premières clauses sont obligatoires.

L’instruction JQL complète se présente comme suit :
description IS NOT EMPTY AND created>= startOfYear () AND (fixVersion in (‘Version 1.0’, ’Version 2.0’) OR priority = 1)

Cette fonctionnalité n’est également possible qu’à l’aide d’extensions payantes telles que ConfiForms. Celle-ci permet de créer des formulaires sur les pages, dans lesquels il est possible de saisir directement du texte (sans passer par l’édition de la page). Lorsque l’on clique sur le bouton « Envoyer », ces textes sont transmis à Jira sous forme de chaînes JSON via l’interface REST, et Jira crée alors la tâche avec ces données, y compris les champs remplis en conséquence. Ainsi, dans l’exemple, un « auteur » pourrait être saisi dans le formulaire ; celui-ci serait alors désigné comme responsable dans le ticket dédié à la rédaction de l’article de blog.

Conclusion

Cet article n'est qu'une introduction au JQL, qui offre aux utilisateurs de Jira de nombreuses autres possibilités. Une fois que vous maîtriserez la syntaxe décrite ci-dessus, vous pourrez passer à une utilisation plus avancée du JQL. Pour plus d'informations sur le JQL et ses nombreuses possibilités d'utilisation, consultez cette page de la documentation Atlassian.

Vous recherchez des experts Jira pour aider votre entreprise à tirer le meilleur parti de Jira ? N'hésitez pas à nous contacter. Grâce à cet outil de gestion de projet incroyablement polyvalent, nous aidons des entreprises issues de divers secteurs à atteindre leurs objectifs.

N'hésitez pas à utiliser notre formulaire de contactou à nous appeler au 0800 8 776 776.