Apps, Technik
Veröffentlicht am 1. April 2022
Atlassian richtet seine Produkte zunehmend für die Cloud aus. Jira Server-Produkte werden nach und nach in die Jira Cloud migriert. Und was passiert mit den Add-ons? Muss alles neu programmiert werden? Ja.
Jira Server-Add-ons sind in der Regel zumindest teilweise in Java geschrieben und lassen sich nicht ohne weiteres in die Cloud migrieren. Hier bietet es sich an, diese als Atlassian Connect-App zu entwickeln, insbesondere, wenn die Businesslogik bestehen bleiben soll.
Dann kann ein Großteil der Java-Klassen und -Methoden wiederverwendet werden. Idealerweise verwendet man dafür Spring Boot und Maven. Atlassian stellt zu diesem Zweck Bibliotheken zur Verfügung.
Atlassian Connect-Apps sind externe Anwendungen, die außerhalb von Atlassian gehostet werden müssen. Sie werden über die Installation mit Atlassian nur verbunden (connected). Das unterscheidet sie von Apps, die mit Atlassian Forge ( https://developer.atlassian.com/platform/forge/Atlassian Forge ) entwickelt werden.
Dieser Nachteil sollte vorher abgewogen werden. Mit Atlassian Forge lassen sich dagegen nicht alle Features umsetzen, die bisher mit Jira Server-Add-ons möglich waren. Soll beispielsweise eine benutzerdefinierte REST API angeboten werden, ist Atlassian Connect die (zurzeit) bessere Wahl. Eine Übersicht über die verschiedenen Plattformen gibt es hier.
Ich zeige heute, wie man eine Jira Cloud-App mit Atlassian Connect erstellt. Ich verwende dafür folgende Frameworks/Tools:
Zuallererst benötigst du eine Jira Cloud, um die App dort zu installieren und zu testen. Hier gibt es die Möglichkeit, sich eine kostenlose Atlassian Cloud für Testzwecke einzurichten.
Damit wir hier unsere App später installieren können, aktivieren wir den Development Modus. Dazu wechseln wir zu Jira > Apps > Manage your Apps und wählen Settings und Enable development mode.
Eine Atlassian Connect-Spring-Boot-Anwendung kann leicht mit Hilfe des Maven Archetyps atlassian-connect-spring-boot-archetype erstellt werden.
Ich habe dies hier im Beispiel mit der IDE Eclipse angewendet.
Maven erstellt für uns ein Projekt unter anderem mit folgenden Dateien:
Die atlassian-connect.json enthält allgemeine Informationen sowie die Module der Connect-App. Nach Projekterstellung sieht diese anfangs so aus:
Code Block 1 atlassian-connect.json
Die pom.xml ist die spezifische Konfigurationsdatei für Maven, die Plug-ins, Build-Profile und Projektabhängigkeiten enthält. Für unsere Connect-App sind das zum Beispiel die folgenden Abhängigkeiten:
In der application.yml werden Spring Properties definiert:
Code Block 2 application.yml
Spring Boot übernimmt das Starten der App inklusive Webserver (Tomcat) und Datenbank (HSQLDB), sobald die Add-on-Application als Java-Anwendung ausgeführt wird.
Um die App in der Atlassian Cloud zu installieren, muss sie über eine https-Verbindung im Internet erreichbar sein. Dazu habe ich ngrok installiert, ein einfaches Kommandozeilenprogramm, mit dem ein Tunnel zum lokalen Host der App erstellt wird.
Ich ergänze die application.yml mit der Zeile „server: port: 9000“, öffne die Kommandozeile im Projektverzeichnis und erstelle einen Tunnel mit dem Befehl „ngrok http 9000“.
Anschließend füge ich die hier erstellte HTTPS-URL als base-url in unsere application.yml ein, sodass diese nun folgendermaßen aussieht:
Code Block 3 application.yml
Jetzt gilt es, die App in der Atlassian Cloud zu installieren. Dazu öffne ich im Browser die angelegte Atlassian Cloud und wähle unter Jira > Apps > Manage Apps den Link Upload app aus. Hier trage ich die HTTPS-URL ein, die ngrok erstellt hat.
Nach dem Upload ist die App installiert.
Im Folgenden möchte ich im Administrationsbereich eine Seite hinzufügen, auf der ich alle Jira-Projekte auflisten kann. Zuerst definiere ich in der atlassian-connect.json die Module webSections und generalPages. Mit webSections werden neue Bereiche in Menüs erstellt, hier im Bereich admin_plugins_menu. In generalPages werden Seiten eingebunden, die über die location einer webSection zugeordnet werden. Dort ist ein Link zur Seite mit dem hier definierten Namen.
In der pom.xml ergänze ich die Thymeleaf-Bibliothek, die unter anderem das Erstellen von HTML-Templates unterstützt.
Code Block 4 pom.xml
Nun wird ein Controller benötigt, der die Anfragen über den Link (url in generalPages) im Administrationsmenü der Atlassian Cloud an die HTML-Seite weiterleitet. Mehr Funktionalität wird hier vorerst nicht benötigt.
Code Block 5 MyAppController.java
Die HTML-Seite liegt im Verzeichnis src/main/resources/templates. Der Name der Datei stimmt mit dem Rückgabewert des Controllers überein.
Code Block 6 myApp.html
Wurden Änderungen an der atlassian-connect.json vorgenommen, muss die App in der Atlassian Cloud neu installiert werden, damit die Änderungen dort auch sichtbar werden. Alle anderen Änderungen (Java, JavaScript, css, etc.) werden automatisch über die URL immer aktuell aus der App geladen.
Im Administrationsbereich sehe ich nun den Bereich „My App“. Beim Anklicken wird der Inhalt meiner Seite mittels iframe in die Jira-Webseite eingebunden.
Von hier aus können nun per Connect JavaScript API Daten über die Jira Cloud REST API abgerufen werden, zum Beispiel:
Code Block 7 nyApp.js
Das JSON Web Token muss dabei mit übergeben werden. Diese Anfrage liefert eine Liste aller Jira-Projekte.
Das HTML sieht nun folgendermaßen aus:
Code Block 8 myApp.html
Im Head-Tag wurden benötigte JavaScript-Dateien ergänzt. Auf der Seite selbst wurden ein Button und eine Tabelle eingefügt.
Das Anfragen der Daten und Befüllen der Tabelle findet in der JavaScript-Datei statt, die im Ordner src/main/resources/static/js liegt.
Code Block 9 myApp.js
So sieht die Seite nun in der Jira Cloud aus:
Beim Klick auf Projekte werden alle Projekte angefragt und in der Tabelle innerhalb der HTML Seite ausgegeben:
Den Erweiterungsmöglichkeiten von Atlassian-Produkten scheinen fast keine Grenzen gesetzt zu sein. Diese bieten nahezu unendlich viele Möglichkeiten, die Funktionalitäten zu erweitern. Das merkt man auch an der Menge der verfügbaren Apps im Marketplace von Atlassian.
Und doch gibt es immer wieder die Notwendigkeit, eigene Apps zu schreiben. Zum Beispiel, weil die vorhandenen Apps nicht ganz genau das erfüllen, was gewünscht ist oder die Anpassung so speziell ist, dass eine Eigenentwicklung unverzichtbar ist.
Diese Mini-App sollte einen Einstieg in das riesige Thema der App-Entwicklung bieten.
Auf jeden Fall bleibt es spannend, was im Bereich Atlassian Forge zukünftig alles kommen wird.
Hast du noch Fragen? Dann poste sie gern in die Kommentare oder schreib uns eine Mail an: atlassian@team-neusta.de
