In diesem Beitrag möchte ich euch eine kurze Einführung in den Scriptrunner für Jira geben und anhand eines konkreten Beispiels für ein Scripted Field aufzeigen, wie ihr Daten für einen schnellen und unkomplizierten Überblick über die Jira-Standard-Funktionalitäten hinaus aufbereiten könnt.
Scriptrunner für Jira
Scriptrunner für Jira ist eine App für Jira, die auf dem normalen Weg über den Atlassian Marketplace bezogen werden kann. Scriptrunner dient dazu, Nicht-Standard-Jira-Funktionalitäten entweder aus mitgelieferten Scripten und Scriptfragmenten auszuwählen und auszuführen oder aber eigene Scripte in Groovy/Java zu entwickeln. Der Scriptrunner erfreut sich großer Beliebtheit und ist aufgrund der umfassenden Funktionalität und Variabilität sehr weit verbreitet. Für mich persönlich ist Scriptrunner so etwas wie das „Schweizer Taschenmesser“ für Jira.
Ihr erreicht Scriptrunner nach der Installation über einen Klick auf das Einstellungssymbol rechts oben auf jeder Seite in Jira und einen anschließenden Klick auf „Apps verwalten“
In der Systemadministration findet ihr Scriptrunner nun auf der linken Seite, die je nach Anzahl der installierten Apps unter Umständen auch sehr stark gefüllt sein kann:
Hier könnt ihr schon einen ersten Überblick gewinnen, was mit Scriptrunner alles möglich ist.
Browse
Vollständiger Überblick über alle Scriptrunner Module inkl. Suchfunktion
Console
Konsole mit Script-Editor, in der direkt online Scripte erstellt und ausgeführt werden können
Built-in Scripts
Auswahl von mitgelieferten nützlichen Scripten, die direkt konfiguriert und ausgeführt werden können
Jobs
Erstellung von individuellen regelmäßig auszuführen Jobs nach Muster der bekannten CronJobs
Listeners
Erstellung von Listeners, die auf frei konfigurierbare Ereignisse (z.B. Vorgangsaktualisierungen) reagieren und frei wählbare Funktionalitäten ereignisgesteuert ausführen
Fields
Benutzerdefinierte Felder, die nicht nur Daten anzeigen, sondern auch aus allen zur Verfügung stehenden Daten dynamische Inhalte zur Anzeige generieren können
Workflows
Auswahl aus diversen Möglichkeiten zur bedingungsgesteuerten Workflow-Automatisierung
Fragments
Erstellung von Scriptfragmenten, die der Anpassungen der Benutzeroberfläche dienen und frei scriptbare Funktionalitäten ausführen können (z.B. Schaltflächen, Dialoge, etc.)
JQL Functions
Übersicht über die durch Scriptrunner zusätzlich zur Verfügung gestellten Befehle, die systemweit in jeder JQL-Abfrage genutzt werden können
REST Endpoints
Erstellung von frei scriptbaren REST Endpunkten, die sich genau wie die Jira-Standard-API über REST ansprechen lassen
Resources
Erstellung von Datenbank-Konnektoren
Script Editor
Erstellung und Bearbeitung von Script-Dateien
Settings
Einige konfigurative Einstellungen
Ebenso zu Scriptrunner gehört der Menü-Eintrag Behaviours:
Behaviours dienen dazu, Feldern Bedingungen und/oder Eigenschaften hinzuzufügen, zum Beispiel die Eigenschaft, dass ein bestimmtes Feld abhängig vom Inhalt anderer Felder zum Pflichtfeld wird. Dies ist fein-granular konfigurierbar. Im Folgenden möchte ich Euch exemplarisch Schritt für Schritt die Erstellung eines Scripted Fields zeigen, um einen tieferen Einblick in den Scriptrunner zu geben.
Scripted Field
Wie oben schon erwähnt sind Scripted Fields Felder, welche dazu dienen, Daten dynamisch aufzubereiten und auch nicht sofort ersichtliche Daten anzuzeigen, Berechnungen durchzuführen oder aber auch Daten benutzerfreundlicher darzustellen, als Jira dies von Haus aus macht. Ist ein Scripted Field konfiguriert, kann es wie ein normales Benutzerdefiniertes Feld beliebigen Bildschirmmasken zugeordnet werden. Zu Benutzerdefinierten Feldern lege ich euch den Blog-Beitrag meines Kollegen Jörg sehr ans Herz.
Einfaches berechnetes Scripted Field
Fangen wir mit einem einfachen Beispiel an, um die grundlegenden Schritte zur Erstellung eines Scripted Fields zu verdeutlichen und gehen davon aus, dass wir eine Bildschirmmaske haben, auf der Budgets angezeigt werden:
Nun möchten wir dem Benutzer das Kopfrechnen ersparen und ein zusätzliches Feld anzeigen, in welchem das Restbudget, also Plan minus Ist angezeigt wird.
Hierzu wählen wir zunächst im Menü (siehe oben) „Fields“ aus und klicken dann auf „Create Script Field“:
Nun haben wir diverse Auswahlmöglichkeiten, was für eine Art von Feld wir erstellen wollen. Für unseren Zweck wählen wir „Custom Script Field“:
In der nächsten Maske finden wieder alles, um ein Scripted Field mit frei definierbarem Inhalt anzulegen:
Als erstes starten wir mit der Eingabe des Basisdaten:
Field Name
Name des Feldes, der später auch als Bezeichner in der Bildschirmmaske angezeigt wird
Field Description
Beschreibung des Feldes
Field Note
Optionale zusätzliche Beschreibung zur Anzeige in der Bildschirmmaske
Template
Hier muss die passende Feldvorlage ausgewählt werden, je nachdem was letztendlich angezeigt werden soll. In unserem Fall eine Zahl, also ein numerisches Feld.
Im nächsten Schritt wählen wir nun das eigentliche Script-Feld an, um unser Script zu schreiben. Alternativ kann über den Schalter „FILE“ eine auf dem Server befindliche vorgefertigte Groovy-Datei ausgewählt werden, die dem Feld zugeordnet werden soll. Über die Schaltflächen rechts unten lässt sich die Größe des Scriptfensters anpassen.
In das Script-Feld tragen wir nun das Script ein.
An dieser Stelle sei angemerkt, dass wir nicht weiter auf die Syntax eingehen. Hierzu referenzieren wir gerne auf die offizielle Scriptrunner-Dokumentation.
Hier das Script zum kopieren:
import com.atlassian.jira.component.ComponentAccessor
import com.atlassian.jira.issue.CustomFieldManager
import com.atlassian.jira.issue.Issue
//definitions
def customFieldManager = ComponentAccessor.getCustomFieldManager();
def plan = issue.getCustomFieldValue(customFieldManager.getCustomFieldObjectsByName("Plan-Sachkostenbudget").getAt(0))
def ist = issue.getCustomFieldValue(customFieldManager.getCustomFieldObjectsByName("Ist-Sachkostenbudget").getAt(0))
//output
return plan - ist
Eventuelle „falsche“ rote Fehler-Markierungen treten hier öfter auf, da der im Editor eingebaute Code-Checker nicht immer zuverlässig arbeitet, insbesondere bei Type-Checks. Abseits von offensichtlichen Fehlern im Code können diese ignoriert werden und haben keine Auswirkungen.
Zur Überprüfung des neuen Scriptes müssen wir nun nicht extra das Feld in eine Maske einbauen. Wir können direkt hier einen Test durchführen. Dazu müssen wir nur unter „Preview Issue Key“ eine existierende Vorgangsnummer eintragen und auf „Preview“ klicken, dann wird unten die Ausgabe unseres Scriptes mit den Werten des angegebenen Vorganges angezeigt:
Mit Klick auf „Add“ wird das Feld nun angelegt und kann wie jedes andere Benutzerdefinierte Feld einer Bildschirmmaske hinzugefügt werden.
Fortgeschrittene Anpassung der Ausgabe
Als Nächstes wollen wir für den Benutzer die Ausgabe noch übersichtlicher in Form einer platzsparenden Tabelle darstellen. Hierzu wählen wir wieder ein „Custom Field“ aus und wählen als Template „HTML“:
Nun geben wir unser Script, diesmal mit Berechnungslogik und Ausgabe-Inhalts-Bereich ein. Hierbei haben wir auch die gestalterischen Möglichkeiten, die HTML über CSS mitbringt:
Mit Klick auf „Add“ wird das Feld nun angelegt und kann wie jedes andere Benutzerdefinierte Feld einer Bildschirmmaske hinzugefügt werden.
Weiteres über den Scriptrunner
Dieser Beitrag war nur ein erster Schritt in den großen Bereich von Möglichkeiten des Scriptrunners. In diesem Blog werden wir euch in Zukunft weitere Möglichkeiten dieser App aufzeigen und vorstellen. Teilt uns gerne in den Kommentaren mit, welche Funktionalität wir für Euch genauer beleuchten sollen.
