Jira custom reports: eigene Jira-Skripte mit Report Builder | Teil 1

Report Builder unterstützt Firmen dabei, unterschiedliche Berichte für sämtliche Jiradaten zu erstellen. Die App hält hierfür zahlreiche Berichtvorlagen bereit. In der Sektion Scripted Reports können zudem individuelle Berichte von Grund auf erstellt werden. Hierfür werden ein eigener Rechenalgorithmus, Parameter und Designbibliotheken verwendet. Erstellen Sie Ihren Bericht mit HTML und JavaScript Grundlagen.

1. Sie füllen die Parameter für Ihren Bericht aus: Umfang, Datum etc.
2. Sie erhalten Rohdaten auf Basis der Parameter: Projekte, Tickets, Zeiterfassung etc.
3. Sie nutzen einen Algorithmus, um Ihren Bericht mittels Rohdaten und Parameter zu erstellen
4. Sie formatieren den Bericht so, dass er die Daten in einer Tabellen-, Diagramm-Form, etc. anzeigt

Die Berichterstellung in Scripted Reports findet in drei Reitern statt:

1. Allgemein
2. Vorlage
3. Skript

Im vierten Tab, Berechtigungen, können die erstellen Berichte mit anderen geteilt werden. Mehr dazu am Ende des Guides.

Werfen wir einen Blick in jeden Reiter und versuchen den Bericht mit Jiradaten basierend auf JQL Abfragen zu erstellen.

In diesem Reiter können Sie die nötigen Felder und die Kategorie Ihres Berichts definieren. Momentan sind mehr als 10 Feldtypen vorhanden. Sie können diesen Schritt auch überspringen.

In unserem Fall wählen wir die Kategorie „Tabelle“ aus, um die aufgewandte und geschätzte Zeit für Tickets vergleichen zu können.

Sie erstellen zwei Eingabefelder:

• JQL: für JQL Abfragen und Syntax-Checks
• Feldwähler: Um die Felder der Zeiterfassung eines Jira Tickets auszuwählen

Sie füllen die Felder folgendermaßen:

• Feldname: Sie wählen einen Feldnamen, der Teil des HTML Tags und der Skriptlogik wird.
• Titel: Sie wählen einen Titel, der am oberen Rand des Feldes erscheint.
• Typ: Sie wählen einen Typ, der das Verhalten des Feldes beeinflusst (Syntax Check oder Objektwahl).

Um die finale Ansicht zu beeinflussen, ist in den Reiter Vorlage ein Handlebar Vorlagen Editor eingebaut. Wenn Sie damit nicht vertraut sind, werfen Sie einen Blick auf die offizielle Seite von Handlebars.

Wie bereits erwähnt, haben wir uns für das Tabellenformat entschieden. Wir gehen davon aus, dass eine Ansammlung von Aufgabenobjekten der Jira API vorhanden ist, wobei alle Objekte ihre eigene Zeile benötigen.

Um die Daten zu verwalten, kann JavaScript im Allgemeinen Reiter verwendet werden. Der Code wird im Top-Level Wartebereich mit dem definierten SR Objekt ausgeführt. Das Objekt ist so konstruiert, dass es bei Interaktionen mit der Jira API, sowie beim Datenabruf der Eingabefelder des Allgemeinen Reiter und bei der Datenweiterleitung zur Vorlage unterstützt.

Hier die Methoden:

• SR.getValueByFieldName(fieldName:String)  – zeigt den Wert des Eingabefeldes basierend auf dem fieldName string Parameter
• SR.getIssuesByJQL(jql:String, <fields:String>) – zeigt die Sammlung der Jira Aufgaben basierend auf der JQL Abfrage und der Liste mit durch Komma getrennten Feldern an. Wenn die Parameter des Feldes nicht definiert sind, werden Jira Navigable Felder ausgegeben.
• SR.render(templateValues:Object, <callback:Function>) – überträgt den Wert des JavaScripts in das Template Reiter. Dies kann entsprechend der Renderlogik mit einem Callback-Parameter definiert werden.

Sie füllen das JQL Feld und den Feldwähler aus. Dann müssen Sie die Daten in das Skript übertragen.

Um die Daten des Eingabefeldes mithilfe von SR.getValueByFieldName() zu erhalten, müssen Sie den Feldnamenwert übergeben, der im Allgemeinen Reiter festgelegt wurde. Hinweis: Beim Feldwähler ist eine Mehrfachauswahl möglich, die eine Sammlung an Werten ausgibt.

Da SR.getIssuesByJQL() den Zeichenfolgentyp für beide Parameter verwendet, können Sie die ausgewählten Felder in eine kommagetrennte Zeichenfolge umwandeln. Da die Abfrage der Jira API ein asynchroner Vorgang ist, sollten Sie den Top-Level Wartebereich verwenden.

Nun holen Sie die Jira Aufgaben und überwachen das Datenobjekt. Dies ist durch die JavaScript map() Methode möglich:

Die Aufgabe im letzten Code zeigt die Zeit in Millisekunden an. Sie müssen die Werte mittels Helferfunktion in Stunden umwandeln.

Diese Konversion muss nun auf die Map Callbackfunktion übertragen werden.

Nun übertragen Sie den Wert als Teil des Renderobjekts in die SR.render() Methode. Wenn Sie weitere Werte übertragen möchten, müssen Sie dem Renderobjekt zusätzliche Eigenschaften hinzufügen.

Nun erstellen Sie den Bericht mit dem Button „Bericht erstellen“ im oberen rechten Rand.

Hier der vollständige Code für das Skript Tab:

Um die Berechtigungen für Ansicht, Bearbeitung und Admin Ihres Berichts anzupassen, nutzen Sie das Berechtigungs Tab. Der ausgewählte User sieht den geteilten Bericht im „Geteilt “ Reiter in Scripted Reports.

Momentan existieren drei mögliche Rollen für User:

1. Ansichtsmodus – der User kann den Bericht sehen, die Parameter oder die Einstellungen nicht verändern.
2. Bearbeitungsmodus – der User kann den Bericht einsehen und die Parameter verändern, jedoch keine neuen Einstellungen vornehmen.
3. Adminmodus – der User kann den Bericht sehen, die Parameter und Einstellungen verändern.

Der Ersteller eines Berichtes hat immer Adminrechte. Diese können nicht verändert werden.

Der Berechtigungsreiter erlaubt es, Berichte mit anderen zu teilen. Stellen Sie sicher, dass der entsprechende User auch Ansichtsrechte für den Bericht erhält.

Wenn Sie mit Ihrem Bericht zufrieden sind, speichern Sie diesen und vergeben Sie einen eindeutigen Namen.

Sie wissen nun, wie Sie die tatsächliche Zeit mit der geschätzten Zeit für Jira Aufgaben berechnen können. Wie sieht der Prozess der Berichterstellung für ein gesamtes Projekt aus? Mit kleinen Veränderungen im Skript ist dies möglich.

Zunächst müssen Sie das Objekt benennen, dass jede Zeiterfassung für das Projekt als Schlüsselwert speichert.

Als Nächstes wählen Sie das Projektfeld im Feldwähler, das von der Jira API zurückgegeben wird. Definieren Sie den Rechenalgorithmus innerhalb des foundIssues.map() callback:

Übertragen Sie die „Projekt“ Objekt als Teil des Renderobjekts und updaten Sie den Vorlagenreiter.

Nun erhalten Sie die zusätzlichen Daten.

Hinweis: Sie haben den vorherigen Bericht nicht verloren, sondern zusätzliche Projektprotokolle erstellt. Das zeigt die Flexibilität von Scripted Reports, um Jiradaten auf unterschiedliche Weise auszuspielen.

Die integrierte Berichtgalerie beinhaltet zahlreiche Vorlagen. Diese können in der Galerie nicht bearbeitet werden, jedoch in den Bereich „Meine Berichte“ kopiert und dort angepasst werden.

Um den Bericht zu kopieren, drücken Sie auf  „Kopieren“ im oberen rechten Rand der Berichtansicht. Anschließend wird der ausgewählte Bericht automatisch im Reiter „Meine Berichte“ erstellt.

Wenn Sie Bedarf an individuellen Berichtvorlagen haben, diese jedoch nicht selbst erstellen möchten, kontaktieren Sie unseren Report Building Service. Unser Team wird Ihnen einen individuellen Bericht erstellen. Lesen Sie hier mehr.