In Vorbereitung auf das große Atlassian-Entwickler-Event „AtlasCamp“ in Amsterdam Ende Mai habe ich mir endlich mal angeschaut wie man denn ein eigenes Plugin für die Atlassian-Produkte schreibt. Die riesige Anzahl von Plugins im Atlassian-Marketplace läßt vermuten, daß die Pluginentwicklung von Atlassian gut unterstützt und gefördert wird und auch auf dem AtlasCamp ist sie das zentrale Thema.
Nachdem ich das nun ausprobiert habe kann ich nur sagen: Toll gemacht Atlassian! Ein erstes Plugin kann wirklich jeder ohne jegliche Hindernisse erstellen! Die Anleitung ist detailliert und gut verständlich, selbst für Nicht-Programmierer durchführbar und die Erfolgserlebnisse treten schon nach kurzer Zeit ein. Ein erstes HelloWorld-Plugin läßt sich in weniger als einer Stunde schreiben und in einer eigenen JIRA-Instanz, die gleich mitgeliefert wird, aufrufen und ausprobieren. Als einzige Systemvorraussetzung muss ein Java SDK 1.6.* installiert und der Port 2990 offen und zugänglich sein, aber auch hierfür gibt es eine detaillierte Anleitung. Alles andere wird von dem Atlas-SDK mitgebracht, neben einer Jira-Standalone-Version auch Maven 2.1.0 und ein Tomcat 6-Server.
Die genaue Anleitung auf englisch von Atlassian findet ihr hier. Ich werde nur eine kurze Zusammenfassung geben, um euch auf den Geschmack zu bringen 🙂
Atlas-SDK installieren
Das SDK gibt es für Windows, für Mac gibt es einen OSX Installer oder ein .tgz-File für Linuxsysteme zum Download.
Auf dieser Seite werden nochmal ausführlich die Systemvorraussetzunge erklärt, also wie man das Java SDK installiert, die Umgebungsvariablen richtig setzt und überprüft, ob der Port frei ist.
Anschließend sollte mit dem Befehl atlas-version im Root-Verzeichnis überprüft werden, ob alle benötigten Tools richtig installiert sind. Die Ausgabe zeigt den Pfad an in welchem das SDK installiert wurde, sowie die benutzte Java- und Mavenversion und Informationen über das Betriebssystem.
Atlas-SDK: Aufbau und Befehle für die Konsole
Das SDK befindet sich dort, wo sich die ATLAS_HOME Umgebungsvariable hininstalliert hat. Auf dem Mac ist dies unter /usr/share/atlassian-plugin-sdk-<version> und unter Windows unter C:Usersusernameatlassian-plugin-sdk-<version>. Dieses Verzeichnis beinhaltet die folgenden Ordner:
- apache-maven : Beinhaltet die Apache Maven 2 installation. Maven ist ein bekanntest Build Management Tool. Atlassian hat sein SDK rund um Maven gebaut, das gesamte Paket nennt sich die Atlassian Maven Plugin Suite (AMPS). Dadurch lassen sich viele der Entwicklungsaufgaben automatisieren. Maven ist dafür zuständig die aktuellen Bibliotheken, die für die Pluginentwicklung benötigt werden, aus dem entfernten Repository zu laden und die Abhängigkeiten aufzulösen.
- bin : Beinhaltet Kommandozeilen Wrapper für die gängigsten AMPS Aufrufe. Alle SDK-Befehle beginnen mit dem Präfix
atlas-
. - repository : Beinhaltet Code Repositories von denen das Atlas SDK abhängig ist.
Sollte ein Proxy für die Internetverbindung benutzt werden muss die settings.xml-Datei in Maven angepasst werden. Wie das geht wird hier beschrieben.
Erzeugen und starten einer neuen JIRA-Instanz auf dem localhost
Jetzt kann mit der Plugin-Entwicklung losgelegt werden. Als erstes wird eine lauffähige Jira-Standalone-Instanz speziell für die Pluginentwicklung erzeugt. Dazu legen wir einen neuen Ordner an in dem alle zugehörigen Dateien für die Entwicklung abgelegt werden. Also auf die Konsole und fertig, los!
Einen neuen Ordner anlegen:
mkdir meinAtlasPlugin
In diesen Ordner wechseln:
cd meinAtlasPlugin
Und die letze Version von JIRA an dem Port 2990 starten mit dem Atlas-Befehl:
atlas-run-standalone --product jira
Maven lädt nun erstmal einiges an Kram aus dem Internet, das für die Installation gebraucht wird, startet den Tomcat-Server und deployed eine aktuelle JIRA-Instanz auf dem Server. Deshalb kann dieser Vorgang eine Weile dauern. Am Ende sollte aber diese Ausgabe erscheinen:
Wie man sieht hat dieser Vorgang bei mir 197s gedauert, was nicht gerade rasend schnell ist. Aber es passiert ja auch einiges 🙂
JIRA läuft als Tomcat-Web-Application auf Deinem localhost. Maven legt in dem neuen Ordner meinAtlasPlugin ein Verzeichnis amps-standalone an, in welchem sich das durch den Maven-Build erzeugte target-Verzeichnis befindet, und darin findet sich der Container für den Tomcat-Server und die JIRA-Instanz, die auf diesen Server deployed wird.
Eine lokale JIRA-Instanz ist nun für uns unter dem Port 2990 erreichbar und kann im Browser unter einer der folgenden Adressen aufgerufen werden:
http://myhost.local:2990/jira oder http://localhost:2990/jira
Und schon kann man sich mit den Standard-Benutzerdaten BN: admin PW: admin einloggen.
Wir stoppen den Server wie oben angegeben auf der Konsole mit ctrl -d. JIRA ist nun nicht mehr im Browser verfügbar.
Ein HelloWorld-Plugin für JIRA schreiben
Jetzt können wir unser erstes Plugin schreiben. Dazu wechseln wir auf der Konsole wieder in unser Verzeichnis meinAtlasPlugin.
Dann geben wir den folgenden Befehl ein, der ein Beispiel-Mavenprojekt für ein Atlas-Plugin anlegt.
atlas-create-jira-plugin
Die Konsole wird Dir nun ein paar Fragen stellen. Zunächst fragt sie Dich für welche JIRA-Version Du das Plugin erstellen willst. Gebe 1 für Jira 5 ein und dann Enter.
Dann werden die üblichen Maven-Projektdaten abgefragt. Du kannst folgende Daten angeben:
Define value for groupId | com.atlassdk.test |
---|---|
Define value for artifactId | helloworld |
Define value for version | 1.0-SNAPSHOT |
Define value for package | com.atlassdk.test.helloworld |
Es wird nun ein Standard-Projekt für ein Atlas-Plugin angelegt. Dieses kannst Du Dir auch in deinem Ordner meinAtlasPlugin anschauen. Es wird ein einem neuen Verzeichnis „helloworld“ angelegt, oder wie auch immer Deine artifactId lautet.
Maven-Goals auf dem Atlas-Projekt ausführen
Damit die richtig vorkonfigurierte Maven-Version 2.1.0 verwendet wird (vor allem wenn man mehrere/neuere Versionen installiert hat) sollte das Atlas-Präfix vor den Maven-Befehlen verwendet werden. Um Maven-Befehle in dem Projekt ausführen zu können, muss demnach allen mvn-Befehlen ein atlas- vorangestellt werden, also atlas-mvn package oder atlas-mvn install. Dann klappts auch mit dem Build 🙂
Atlas-Projekt in Eclipse importieren
Natürlich läßt sich das Projekt auch in Eclipse importieren, wenn das Maven-Plugin für Eclipse installiert ist. Dort müssen aber zunächst folgende Einstellungen vorgenommen werden:
1. In Eclipse -> Einstellungen -> Java -> Installed JREs muss das JDK 1.6 als Standard ausgewählt sein.
2. In Eclipse -> Einstellunge -> Maven -> Installations das von Atlassian mitgelieferte maven als Standard auswählen. Wo dies zu finden ist, zeigt Dir der Befehl atlas-version.
Lade das neue Plugin in den JIRA Universal Plugin Manager (UPM)
Als nächstes muss das neue Plugin in die JIRA-Instanz geladen werden damit es dort auch verfügbar ist. Dazu wechseln wir in das Verzeichnis unseres Plugins mit cd meinAtlasPlugin/helloworld. Dann geben wir folgenden Atlas-Befehl ein:
atlas-run
Maven spult wieder eine Menge Informationen ab und startet am Ende den Server und JIRA neu.
Wenn Du Dich nun erneut in JIRA einloggst und die Administration aufrufst, findest Du Dein neues Plugin unter Plugins -> Verwalte Erweiterungen -> Vom Benutzer installierte Plugins. Es ist dort zwei mal aufgeführt, einmal das Plugin selbst und einmal für die Plugin Tests.
Fertig! Du hast ein erstes Plugin gebaut und in JIRA installiert! Großartig! Jetzt musst Du Dir nur noch eine schicke Anwendung dafür überlegen 🙂