Datumsabfrage mit JQL: Jira Spotlight

In diesem Video werden wir  zeigen, wie Sie mit JQL in Jira Projekten die Vorgänge mithilfe einer Datumsabfrage suchen können. Dabei gehen wir auf die Suche nach exakten Daten ein, die Datumsfunktionen und die Kalenderfunktionen.

JQL ist ein mächtiges Werkzeug, das es Ihnen ermöglicht, nach bestimmten Kriterien zu suchen, wie zum Beispiel nach dem Erstellungs- oder Aktualisierungsdatum der Vorgänge.

In Jira gibt es drei Haupttypen von Datumsabfragen: exakte Datumssuche, Datumsfunktionen und Kalenderfunktionen. In diesem Video geht es erstmal nur um die exakte Datumssuche, wir gehen aber kurz auf die Unterschiede ein:

Exakte Datumssuche: Dies ist die einfachste Form der Datumsabfrage. Es handelt sich um eine genaue Übereinstimmung mit einem bestimmten Datum (z.B. "created = 2022-12-31").

Datumsfunktionen: Diese Funktionen ermöglichen es, nach Daten zu suchen, die sich im Verlauf eines bestimmten Zeitraums befinden. Zum Beispiel kann man mit der Funktion "created >= startOfMonth()" alle Vorgänge anzeigen, die im aktuellen Monat erstellt wurden.

Kalenderfunktionen: Diese Funktionen ermöglichen es, nach Daten zu suchen, die mit bestimmten Kalenderwochen oder -monaten in Verbindung stehen. Zum Beispiel kann man mit der Funktion "duedate >= startOfWeek()" alle Vorgänge anzeigen, die in der aktuellen Woche fällig sind.

Es ist möglich, diese Funktionen in Kombination mit Operatoren wie ">", "<", ">=", "<=" und "=" zu verwenden, um komplexere Datumsabfragen zu erstellen. So kann man beispielsweise nach Vorgänge suchen, die in einem bestimmten Zeitraum erstellt wurden (z.B. "created >= 2022-01-01 AND created <= 2022-12-31").

Jeder Vorgang in Jira besteht aus Feldern (Standartfelder, die benutzerdefinierten Felder, die von einem Admin festgelegt werden und Felder, die von Apps erstellt werden), mit der JQL Suche können wir nach Werten (in diesem Fall Datumsangaben) suchen.0

Auf folgende Felder, kann man die JQL Datumsabfrage setzten : 

• Created - Datum, an dem das vorgangerstellt wurde
• Updated - Datum, an dem das vorgangzuletzt aktualisiert wurde
• Due Date - Datum, bis zu dem ein vorgangabgeschlossen sein sollte
• Resolution Date - Datum, an dem das vorganggelöst wurde
• Last Viewed - Datum, an dem das vorgangzuletzt angeschaut wurde
  
  Es ist auch möglich, benutzerdefinierte Datumsfelder zu erstellen, um spezifische Anforderungen zu erfüllen.
  

  In Jira gibt es folgende Arten von benutzerdefinierten Datumsfeldern:
  
  

  1. Datum/Uhrzeit - ermöglicht das Eingeben eines Datums und einer Uhrzeit
  2. Datum - ermöglicht nur das Eingeben eines Datums
  3. Kalenderwoche - ermöglicht das Eingeben einer Kalenderwoche
  4. Relative Datumsangaben - ermöglicht das Eingeben einer relativen Zeitspanne (z.B. "in 3 Tagen")

Wenn Sie also eine JQL Suche ausführen, mache dir zuerst klar, wonach Sie genau suchen.

Exakte Daten:

Beginnen wir mit der Suche nach exakten Daten. Sie können in Jira nach einem Vorgang mit einem exakten Datum suchen, indem Sie in der Hauptnavigationsleiste auf "Suchen" klicken und dann "Erweiterte Vorgangssuche" auswählen. Um die erweiterte Suche in JQL zu verwenden, wählen Sie "Zu JQL wechseln" aus.

Um nach einem bestimmten Datum zu suchen, können Sie die Syntax "Due Date = yyyy-mm-dd" verwenden. Hierbei entspricht yyyy dem Jahr, mm dem Monat und dd dem Tag des Datums, nach dem Sie suchen.

Lassen Sie uns ein Beispiel machen: "Due Date = 2022-12-31". Diese Abfrage sucht nach allen Aufgaben mit einem Fälligkeitsdatum von 31. Dezember 2022.

Sie können Daten auch mit Bindestrichen oder Schrägstrichen eingeben, wobei die Reihenfolge immer Jahr, Monat, Tag ist. Wenn Sie Schrägstriche verwenden, müssen Sie Anführungszeichen verwenden.

Was ist, wenn Sie nach einem Datumsbereich suchen möchten? Kein Problem, denn Sie können auch nach Datumsbereichen suchen, indem Sie die Operatoren "<" (vor), ">" (nach) und "~" (etwa gleich) verwenden. Hier ist ein Beispiel: "Due Date >= 2022-01-01 and Due Date <= 2022-12-31". Diese Abfrage sucht nach allen Aufgaben mit einem Fälligkeitsdatum zwischen dem 1. Januar 2022 und dem 31. Dezember 2022.

In JQL gibt es einige Operatoren, die bei der Datumsabfrage häufig verwendet werden:

= - Übereinstimmung mit einem bestimmten Datum (z.B. "created = 2022-12-31")
> - Größer als ein bestimmtes Datum (z.B. "updated > 2022-12-31")
< - Kleiner als ein bestimmtes Datum (z.B. "dueDate < 2022-12-31")
>= - Größer oder gleich einem bestimmten Datum (z.B. "resolutionDate >= 2022-01-01")

<= - Kleiner oder gleich einem bestimmten Datum (z.B. "lastViewed <= 2022-12-31")
!= - Ungleich einem bestimmten Datum (z.B. "created != 2022-12-31")

Datumsabfrage mit der Basis Suche?

Wenn wir in der einfachen Suche auf "+more" klicken, können wir die entsprechenden Felder hinzufügen:

• "created" (Erstellungsdatum)
• "updated" (letztes Änderungsdatum)
• "resolved" (Datum, an dem das Issue gelöst wurde)
• "duedate" (Fälligkeitsdatum)

Diese Funktionen können mit Operatoren wie ">=" oder "<=" verknüpft werden, um bestimmte Zeiträume oder Datenpunkte zu suchen.

Für die ersten 3 Befehle geht Jira mit der Suche in die Vergangenheit; die Befehle sind hier:

within, more than, between und in range - alle bis auf in between gehen vom heutigen Tag aus, between benötigt die genaue Datumsangabe in der Suche

Für Due Dates gehen wir in die Zukunft: + now overdue und + due in next

Der JQL Befehl für diese Suchanfrage wird uns mit einem Klick auf "Advanced search" angezeigt:
created >= 2023-01-02 AND created <= 2023-01-03

Unterstütze Funktionen:

• currentLogin()
• lastLogin()
• now()
• startOfDay()
• startOfWeek()
• startOfMonth()
• startOfYear()
• endOfDay()
• endOfWeek()
• endOfMonth()
• endOfYear()

Mit der Funktion currentLogin() können Sie Benutzern suchen, die sich in den letzten 24 Stunden angemeldet haben. Wenn Sie nach Benutzern suchen möchten, die sich vor mehr als 24 Stunden angemeldet haben, verwenden Sie die Funktion lastLogin().

Die Funktion now() gibt das aktuelle Datum und die Uhrzeit zurück. Mit startOfDay(), startOfWeek(), startOfMonth() und startOfYear() können Sie den Beginn des aktuellen Tages, der aktuellen Woche, des aktuellen Monats und des aktuellen Jahres abfragen.

Ähnlich können Sie mit endOfDay(), endOfWeek(), endOfMonth() und endOfYear() das Ende des aktuellen Tages, der aktuellen Woche, des aktuellen Monats und des aktuellen Jahres abfragen.

Zeiträume:

Um nach Vorgängen zu suchen, die zu einem bestimmten Zeitpunkt erstellt oder aktualisiert wurden, können Sie verschiedene Operatoren verwenden. Zum Beispiel:

• Finde alle Vorgänge, die am 1. Januar 2023 erstellt wurden: created = 2023-01-01
• Finde alle Vorgänge, die vor dem 1. Januar 2023 erstellt wurden: created < 2023-01-01
• Finde alle Vorgänge, die nach dem 1. Januar 2023 erstellt wurden: created > 2023-01-01

Es ist wichtig zu beachten, dass das Datumsformat in JQL dem Format "YYYY-MM-DD" entspricht.

Sie können auch komplexere Abfragen erstellen, indem Sie die Datumsoperatoren mit anderen Operatoren wie UND, ODER und NICHT kombinieren.

• Finden Sie alle Vorgänge, die zwischen dem 1. Januar und dem 31. Dezember 2022 erstellt wurden:
  created >= 2022-01-01 AND created <= 2022-12-31
  
  

Datumsfunktion:

Wenn Sie nicht exakte Daten verwenden möchten, können Sie stattdessen eine Datumsfunktion verwenden. Datumsfunktionen können verwendet werden, damit das JQL nicht aktualisiert werden muss, wenn es in einem gespeicherten Filter verwendet wird. Mit Datumsfunktionen können SIe nach Vergangenheit oder Zukunft suchen, indem Sie Minuten, Stunden, Tage, Wochen, Monate oder Jahre verwenden.

Der Tag oder der Zeitraum kann sowohl in der Zukunft, als auch in der Vergangenheit liegen.

Werte: Minute, Stunde, Tag, Woche, Monat, Jahr

Ein Beispiel: Sie möchten alle Projekte finden, die vor zwei Wochen aktualisiert wurden. Dazu geben Sie im JQL-Feld "updated" ein, wählen den "kleiner als"-Operator aus und geben dann "-2w" ein. Das Minuszeichen zeigt an, dass wir in der Vergangenheit suchen und "2w" bedeutet, dass wir nach Projekten suchen, die vor zwei Wochen aktualisiert wurden.

Suche wir also nach Vorgängen, die in den letzten 2 Wochen geupdated wurden, lautet die JQL Suche:
updated < "-2w"

Kalenderfunktion:

Ist eigentlich eine Smarte Datumsabfrage: letzter Monat erster Montag: vorletzter Monat, 2. Woche

Richtet sich nach der aktuellen Zeit in unserer Zeitzone:
Befehle wie startOfWeek gehen dann immer von dem heutigen Tag aus.

Öffnen Sie dazu zunächst den JQL-Textbereich und leere ihn. Geben dann 'resolved' ein, da wir nach gelösten Vorgängen suchen möchten. Anschließend fügen Sie den Operator 'greater than or equals' hinzu. Danach tragen Sie die Funktion 'start of week' ein. Die leeren Klammern bedeuten, dass Jira die aktuelle Uhrzeit und das aktuelle Datum als Ausgangspunkt für die Suche verwendet.

Jetzt klicken Sie auf 'Suchen' oder drücken Enter auf deiner Tastatur. Sie sehen nun alle Vorgänge innerhalb deines Projekts, die seit dem Beginn dieser Woche gelöst wurden.

Beachten Sie, dass der Schalter zur Basissuche deaktiviert ist. Das bedeutet, dass eine solche datenbasierte Suche in der Basissuche nicht möglich ist.

Lassen Sie uns nun einen Schritt weitergehen und die Kalender-Funktionen mit Operatoren kombinieren, um schnell Vorgänge an bestimmten Punkten in der Vergangenheit zu finden. Dazu nutzen wir den Operator innerhalb der Kalenderfunktion.

Ein Beispiel: Der Operator 'less than' und die Kalenderfunktion 'start of week' zeigen uns, dass wir nach Vorgängen suchen, die vor dem Beginn einer Woche entstanden sind. Das -5 innerhalb der Kalender-Funktion sagt Jira, dass wir Vorgänge suchen möchten, die vor dem Beginn der fünften Woche in der Vergangenheit entstanden sind. In diesem Beispiel geht Jira davon aus, dass wir 'week' meinen, ohne das 'w' hinzuzufügen, da die Funktion auf Wochen basiert.

Beachte, dass Sie für Inkremente, die ein Plus enthalten, immer Anführungszeichen verwenden musst, da sonst ein Fehler auftritt.

Wir suchen einfach mal nach Vorgängen, die seit dem Beginn dieser Woche gelöst wurden. Dazu nutzen wir die Kalenderfunktion 'Start of Week'.

Die Daten und Zeiten sind von Jira festgelegt, daher bestimmt Jira auch die Start- und Endzeit automatisch.

• „startOfWeek ()“, zum Beispiel. „created > startOfWeek(-2)“ zeigt Vorgänge an, die am Montag vor zwei Wochen erstellt wurden.
• „endOfWeek“: „duedate < endOfWeek(2)“ zeigt die Vorgänge an, die bis Sonntag in zwei Wochen abgeschlossen werden müssen. Beim Doppelklicken auf „endOfWeek“ erscheint ein Drop-down, der die möglichen Funktionen für zeitliche Angaben zeigt.

Ein Praxisbeispiel aus dem Softwareentwicklungsbereich könnte sein, dass ein Entwicklungsteam die Anzahl der Fehler, die während eines bestimmten Zeitraums behoben wurden, analysieren möchte. Mit JQL kann das Team einfach nach allen Vorgängen suchen, die in diesem Zeitraum als "behoben" markiert wurden und so schnell einen Überblick über die Anzahl der behobenen Fehler erhalten. Dies kann dazu beitragen, die Leistung des Entwicklungsteams zu messen und zu verbessern, indem man sieht, wie viele Fehler in welcher Zeit behoben werden konnten. Es kann auch dazu beitragen, potenzielle Vorgänge frühzeitig zu erkennen und entsprechende Maßnahmen einzuleiten.

resolutiondate >= startOfPeriod AND resolutiondate <= endOfPeriod AND resolution = fixed

In diesem Beispiel werden die Start- und Enddaten des Zeitraums durch die Variablen "startOfPeriod" und "endOfPeriod" repräsentiert. Sie können diese Variablen durch konkrete Daten ersetzen, zum Beispiel

resolutiondate >= 2021-01-01 AND resolutiondate <= 2021-12-31 AND resolution = fixed.

Dieser Befehl sucht nach allen Vorgängen, die in dem angegebenen Zeitraum als "behoben" markiert wurden. Es können auch andere Kriterien hinzufügt werden, um die Suche weiter zu verfeinern.