Technik, Tutorials

Veröffentlicht am 9. Juli 2020

JQL – Tipps und Tricks

In diesem Beitrag möchte ich dir einige bekannte und weniger bekannte Funktionen der Jira Query Language (JQL) zeigen. Mithilfe dieser Funktionen wird es dir leichter fallen, Vorgänge (Issues) nach deinen Wünschen und Bedürfnissen zu finden und zu sortieren.

Grundsätzliches

Um Vorgänge zu finden, kann folgende, in der Navigationsleiste vorhandene Option genutzt werden: „Nach Vorgängen suchen“.

Ein Klick hierauf öffnet die Suchmaske. Abhängig von der vorherigen Verwendung öffnet sich entweder die einfache oder die erweiterte Suche:

Anmerkung: In diesem Beitrag ignoriere ich die einfache Suche, da es um JQL gehen soll. Ein Klick auf „Erweitert“ schaltet bei Bedarf auf die erweiterte Suche um. 


QuickSearch

Ein nützlicher aber meiner Erfahrung nach wenig genutzter Weg, um Vorgänge zu finden, ist die Nutzung der QuickSearch-Box in der Navigationsleiste. Diese ist auf jeder Seite vorhanden.

Die Möglichkeiten sind limitiert, dennoch möchte ich dir hier zwei praktische Suchen zeigen:

Alle Vorgänge, die dir zugewiesen sind

Einfach „my“ in die QuickSearch eingeben und Enter drücken. Dies listet alle Vorgänge auf, bei denen du der Bearbeiter bist.

Freitextsuche

Diese Suche kannst du nutzen, wenn du Vorgänge mit bestimmten Inhalten suchst. In die QuickSearch eingegebener Text wird automatisch in Zusammenfassung, Beschreibung und Kommentaren gesucht.

Suche nach Vorgängen

Nachdem du die Suchmaske geöffnet hast, siehst du in der Ergebnisliste alle für dich sichtbaren Vorgänge – standardmäßig sortiert nach Erstellungsdatum absteigend (neueste zuerst). Um die Ergebnisliste einzugrenzen, stehen dir eine Reihe von Möglichkeiten zur Verfügung, die ich im Folgenden vorstellen möchte.

Grundsätzliches zum Aufbau einer JQL Abfrage

Die Syntax ist: Feldname = Wert

Kommen in dem Wert oder Feldnamen Leerzeichen vor, müssen diese mit Anführungszeichen umschlossen werden.

Es lassen sich auch mehrere Attribute gleichzeitig abfragen. Dies ist durch die Operatoren AND und OR möglich. 

Neben der Möglichkeit, auf einen bestimmten Wert zu prüfen, lässt sich, im Gegensatz zur Basissuche, mit dem Schlüsselwort IN auch auf eine Wertemenge prüfen.

Eine weitere Möglichkeit, die es in der Basissuche nicht gibt: einzelne Ausprägungen aus der Suche auszuschließen. Also zum Beispiel alle Vorgänge, die keine Story sind. Dies ist sowohl bei einem Wert ( != ) als auch bei Wertemengen möglich (NOT IN).

Erweiterte Funktionen

linkedIssues(…)

Hiermit suchst du alle Vorgänge, die mit einem bestimmten Vorgang verknüpft sind.

Syntax: issue IN linkedIssues(„ID des Issues“)

linkedIssues bietet noch weitere Parameter an, die sehr hilfreich sein können. So kannst du dir beispielsweise alle Vorgänge anzeigen lassen, die von einem bestimmten Vorgang blockiert werden oder es blockieren. 

Anmerkung: Ich zeige jetzt nur das Beispiel für Blockierungen. Es funktioniert selbstverständlich auch für alle anderen Verknüpfungstypen.

Wichtig: „blocks“ ist die Bezeichnung in meinem verwendeten Jira. Die Bezeichnung kann bei dir abweichen.

Syntax: issue IN linkedIssues(„ID des Issues“, Typ der Verknüpfung)

closedSprints() and openSprints()

Hiermit suchst du alle Vorgänge, die einem abgeschlossenen beziehungsweise einem noch offenen Sprint zugeordnet sind. 

Syntax: issue in openSprints()

endOfDay(), endOfMonth(), endOfWeek(), endOfYear(), startOfDay(), startOfMonth(), startOfWeek(), startOfYear(), now()

Dies ermöglicht die Suche nach bestimmten Zeiträumen, zum Beispiel die Suche nach allen Vorgängen, die seit Monatsbeginn geändert wurden:

Syntax: created >= startOfMonth()

Dies funktioniert auch mit allen Datumsfeldern in Jira.

Zusätzlich kannst du noch ein Attribut mit übergeben, um den Zeitraum anzupassen. Wenn du etwa die Vorgänge der letzten drei Monate finden möchtest, kannst du dieses in der Funktion angeben:

Syntax: created >= startOfMonth(-2M)

Somit wird das zu vergleichende Datum noch um weitere zwei Monate in die Vergangenheit verlegt.

Mit „-“ erfolgt eine Verlegung in die Vergangenheit, mit „+“  eine Verlegung in die Zukunft.

Mögliche Einheiten sind hier: 

y = Jahr

M = Monat

w = Woche

d = Tag

h = Stunde

m = Minute

Wird keine Einheit angegeben, dann wird die Einheit der Funktion angenommen, also bei endOfYear() Jahr und bei endOfWeek() Woche.

Suche nach bestimmten Feldern

Bei bestimmten Feldern bietet JQL erweiterte Funktionen, um einfacher nach diesen suchen zu können.

Anhänge

Es ist möglich, nach allen Vorgängen zu suchen, die Anhänge beziehungsweise keine Anhänge haben.

Syntax: attachments IS NOT EMPTY   

Lässt du das Schlüsselwort NOT weg, werden dir alle Vorgänge angezeigt, die keine Anhänge haben.

Textfelder

Bei Textfeldern kannst du entweder ein bestimmtes Textfeld durchsuchen oder du durchsuchst alle Textfelder auf einmal.

Ich zeige dir die Suche in einem bestimmten Textfeld mit den Kommentaren:

Syntax: comment ~ „Ein Kommentar“

Hier findest du alle Vorgänge mit einem Kommentar, die so ähnlich sind wie „Ein Kommentar“.
Wenn du ganz genau diesen Text suchen möchtest, machst du das wie folgt:
Syntax: comment ~ „\“Ein Kommentar\““

Fälligkeitsdatum

Die Suche nach dem Fälligkeitsdatum ist grundsätzlich – wie bei allen anderen Datumsfeldern – möglich, beispielsweise mit endOfWeek().

Wenn du wissen möchtest, welche Vorgänge bis zum Ende dieser Woche Fällig sind, findest du dies so heraus:

Syntax: due <=endOfWeek()

due und dueDate sind Synonyme füreinander. Dementsprechend ist es egal, welches von den beiden Wörtern du benutzt.
Möchtest du alle Vorgänge finden, die schon überfällig sind, kannst du die Funktion overdue() benutzen.

Syntax: issue in overdue()

Schätzung und Worklogs

Wenn du in Jira Schätzungen und Zeiten erfasst, möchtest du vielleicht auch danach suchen.
Grundsätzlich kannst du hier nach den einzelnen Feldern wie „Original Estimate“ suchen. Interessiert dich allerdings der Fortschritt, dann gibt es ein extra Feld das sich „Work ratio“ nennt. Dieses ist folgendermaßen definiert:

workRatio = (erfasste Zeit / ursprüngliche Schätzung) * 100.

Möchtest du also wissen, bei welchen Vorgängen schon mehr als 75 % der ursprünglichen Schätzung „verbraucht“ sind, kannst du da das so herausfinden.

Syntax: workRatio > 75

Suche in historischen Daten

Manchmal möchtest du nicht nur nach den aktuellen Daten suchen, sondern wissen, welche Vorgänge durch einen bestimmten Benutzer geändert wurden oder zuvor einen bestimmten Status hatten.
Auch dies ist eingeschränkt in Jira möglich.

WAS, WAS NOT, WAS IN, WAS NOT IN

Mit dem Operator WAS lässt sich überprüfen, ob ein Vorgang in der Vergangenheit einen bestimmten Status hatte.

Syntax: status was Accepted

Dieser Operator lässt sich noch detaillieren, indem du angibst, wann der Vorgang diesen Status gehabt haben soll.

Hier ist after „Datum“, before „Datum“, during („Datum 1“, „Datum 2“)sowie on „Datum“ möglich.

Zusätzlich lässt sich durch BY „Benutzername“ festlegen, welcher Benutzer diese Änderung verursacht hat.

Syntax: status was Accepted AFTER „Datum” BY „Benutzername”

Mit dem Zusatz IN lassen sich hier zahlreiche Werte abfragen, mittels NOT lässt sich die Suche umkehren.

Der Operator WAS kann mit den Feldern Bearbeiter, Lösungsversion, Priorität, Autor, Lösung und Status verwendet werden.

CHANGED

Der Operator Changed ermöglicht es, nach Vorgängen zu suchen, an denen eine konkrete Änderung erfolgt ist, zum Beispiel ein Statuswechsel an einem bestimmten Tag.

Syntax:
Status changed: überprüft, ob der Status geändert wurde.

Status changed from „Alter Wert“ to „Neuer Wert”: überprüft, ob der Status von „Alter Wert“ zu „Neuer Wert“ geändert wurde.

Status changed from „Alter Wert“ to „Neuer Wert” on „Datum” By „Benutzername”: überprüft, ob dies an einem bestimmten Datum passiert und durch den genannten Benutzer erfolgt ist.

Für die Datumseinschränkung stehen auch hier wieder die Möglichkeiten „before“, „after“, „on“ oder „during ()“ zur Verfügung.
Dieser Operator kann nur mit den Feldern Bearbeiter, Lösungsversion, Priorität, Autor, Lösung und Status verwendet werden.

Sortieren von Vorgängen in Listen

Wenn die Suchergebnisse angezeigt werden, sind sie standardmäßig sortiert nach Erstellungsdatum absteigend (neueste zuerst). Um eine andere Sortierung zu erreichen, kannst du entweder die angezeigten Spalten-Header anklicken, um die Vorgänge auf- oder absteigend nach der jeweilige Spalte zu sortieren oder direkt im Suchfeld mit „ORDER BY“ arbeiten. Der Vorteil der Verwendung des Suchfeldes liegt darin, dass du auch nach nicht angezeigten Spalten oder nach mehreren Spalten sortieren kannst.

ORDER BY … ASC / DESC

So wird die Anzeige der Vorgänge nach dem angegebenen Feld sortiert. Der Parameter ASC (= aufsteigend) oder DESC (= absteigend) ist optional. 

Syntax: Suchfilter ORDER BY Feldname [ASC/DESC]

Verschachteltes ORDER BY

Verschachteltes ORDER BY kann genutzt werden, um innerhalb einer Sortierung weiter zu sortieren. 

Syntax: Suchfilter ORDER BY Feldname1 [ASC/DESC], Feldname2 [ASC/DESC]

Beispiel: Anzeige aller Vorgänge, sortiert nach Status und Aktualisierungsdatum:

Aufheben der Sortierung

Wie du vielleicht beim Anwenden gemerkt und gesehen hast, löst das Anklicken eines Spalten-Headers nicht anderes aus, als ein ORDER BY Statement im Suchfeld hinzuzufügen. Dieses bleibt bestehen und verhindert eventuell sinnvolles Weiterarbeiten mit anderen Sortierungen. 

Um die Sortierung wieder rückgängig zu machen, muss das ORDER BY Statement aus dem Suchfeld gelöscht und neu gesucht werden.

Erweiterungen der JQL Möglichkeiten

Einige Apps erweitern JQL um weitere Befehle. So bringt zum Beispiel die App Script-Runner unter anderem die folgenden Möglichkeiten mit:

hasLinks()

Anzeige aller Vorgänge, die eine Verknüpfung mit anderen Vorgängen haben.

Syntax: issueFunction IN hasLinks()

hasLinkType(…)

Anzeige aller Vorgänge, die eine Verknüpfung mit anderen Vorgängen vom angegebenen Typ haben.

Syntax: issueFunction IN hasLinkType(Typ der Verknüpfung)

linkedIssuesOf(…)

Anzeige aller Vorgänge, die eine Verknüpfung mit einem Vorgang entsprechend dem angegebenen Filter haben.

Szenario: Zeige mir alle Issues, die mit Issues auf Projekt XY verknüpft sind:

Syntax: issueFunction IN linkedIssuesOf(Filter)

linkedIssuesOfAll(…)


Hat im Grunde die gleiche Funktionalität wie linkedIssueOf(…), allerdings werden hier auch Epic-Links und Subtasks berücksichtigt.
Syntax: issueFunction IN linkedIssuesOfAll++(Filter)


Weiterführende Links

Hier findest du weitere Informationen und Referenzen zu den behandelten Themen:

Erweiterte Suche

QuickSearch

JQL


3 Antworten auf "JQL – Tipps und Tricks"

  • Thomas Niemann sagt:

    Gibt es in Jira eine Möglichkeit Filter variabel zu gestalten? Ich möchte im konkreten Beispiel nicht abgeschlossene BUGs filtern, die zu verschiedenen Einführungsterminen geplant sind. Der jeweilige Einführungstermin sollte dabei vorgegeben werden können. Geht so etwas oder muss ich für jeden Termin den Filter kopieren und entsprechend anpassen (habe also eine große Zahl an gleichartigen Filtern).

  • Martin sagt:

    Hallo Thomas,
    es gibt out of the box keine Variablen, die innerhalb der JQL queries verwendet werden könnten. Für die Kategorisierung von Bugs zu unterschiedlichen Releases oder Terminen würde ich entweder Sprints oder Lösungsversionen nutzen – diese können dann auch entsprechend in JQL verwendet werden.

    1. Ingo sagt:

      Hallo Martin,

      hatte gerade auch das Problem und habe die Lösung gefunden:
      fixVersion => Lösungsversion
      https://support.atlassian.com/jira-software-cloud/docs/advanced-search-reference-jql-fields/

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

Weitere Themen