Im nächsten Teil zum Thema JIRA Custom Service Broker möchte ich zeigen wie man mit dem Smartobjekt Attachments zu einem Issue hinzufügen kann und wie man die JIRA REST Api zum Suchen mit JQL verwenden kann.
Für das Anfügen von Dateianhängen zu einem Issue bietet der Servicebroker aktuell 3 Möglichkeiten
Beschreibung der API auf Ihrem JIRA-Server: <Ihre_Jira_URL>/plugins/servlet/restbrowser#/resource/api-2-issue-issueidorkey-attachments
Anfügen eines K2-File-Attachments (z.B: mit einer Smartform)
Hierzu bietet das Smartobjekt die Methode AssAttachmentToIssueFromBase64. Die Methode erfordert nur 2 Parameter
- IssueKey
- K2 FileAttachment
Beispiel Upload mit einer SmartForm:
Ergebnis in JIRA:
Anfügen einer Datei über eine Web-Adresse
Mit dieser Möglichkeit kann einfach eine beliebige URL als Parameter angegeben werden. Der Servicebroker lädt diese Datei herunter und häng diese an den Issue in JIRA an.
Für meinen Anwendungsfall ist das eine wichtige Möglichkeit, da unser dox42-Server einen REST-Service bietet, über den Dokumente aus Powerpoint, Excel oder Wordvorlagen Dokumente in vielen verschiedenen Formaten generiert werden können. (siehe auch Dokumentengenerierung mit K2 und dox42)
Hierzu kann die Methode AddAttachmentToIssue verwendet werden. Die Methode bietet die Möglichkeit sowohl über die o.a. erwähnter URL Dokumente hochzuladen, als auch über physikalische Dateipfade (z.B.: Fileshares)
Upload über eine Web-Adresse
Hierzu werden mindestens 3 Parameter benötigt:
- IssueKey
- InputFilePath (in diesem Fall die URL zu unserem Dokument)
- InputIsWebContent (boolean) – sollte es sich um eine URL handeln, so muss dieser Parameter den Wert „true“ haben
- Optional: InputFileName – sofern sich der Dateiname aus der Url nicht ermitteln lässt, sollte der gewünschte Dateiname angegeben werden – die Datei, die an den Issue in JIRA angehängt wird, bekommt diesen Namen
Beispiel Upload über eine Webadresse:
Beispiel Ergebnis in JIRA:
Upload mit Angabe eines physikalischen Pfades
Diese Möglichkeit ist an sich analog zur Möglichkeit mit der Web-Adresse – der Parameter „InputIsWebContent“ muss lediglich auf „false“ gesetzt werden und der Parameter „InputFilePath“ erfordert den PFad zu einer Datei, die über den physikalischen Pfad erreichbar ist. Das kann eine Datei auf einem Fileshare sein, oder aber auch eine Datei, die auf dem K2-Server liegt.
Der K2-Serviceuser benötigt zumindest Leserechte für die gewünschte Datei.
Die notwendigen Parameter:
- IssueKey
- InputFilePath (in diesem Fall der physikalische Pfad zu unserem Dokument)
- InputIsWebContent (boolean) – in diesem Fall muss dieser Parameter den Wert „false“ haben
- Optional: InputFileName – möchte man die Datei mit einem anderen Namen statt des Originaldokuments an den JIRA Issue hängen, so kann man der Methode diesen Namen an dieser Stelle mitgeben.
Beispiel Upload über einen physikalischen Pfad:
Beispiel Ergebnis in JIRA:
Suchen
Der JIRA Rest-Service search bietet eine coole Möglichkeit beliebige Vorgänge in JIRA zu finden. Der wichtigste Parameter stellt die JQL-Query dar, mit deren Hilfe die Suchergebnisse mit allen verfügbaren Eigenschaften gefunden werden können. Sei es Projektbezogen, anhand des Assignees, des Status des Issue-Typs usw. Natürlich sind auch komplexe Verschachtelung über die Query möglich. Diese können zudem zuvor ausgiebig direkt in JIRA über getestet werden.
Beschreibung der API auf Ihrem JIRA-Server: <Ihre_Jira_URL>/plugins/servlet/restbrowser#/resource/api-2-search
Die Methode zum Suchem mit JQL nimmt folgende Parameter entgegen:
- JQL – die Query die definiert nach was gesucht werden soll (Ein sehr einfaches Beispiel: project=COR AND issuetype=Task)
- StartAt – Der Index des ersten Datensatzes, der zurückgegeben werden soll (0-basierend)
- MaxResults: – die maximale Anzahl der Ergebnisse, die zurückgegeben werden sollen- Der Standard ist 50
- ValidateQuery – legt fest ob die Query validiert werden soll oder nicht
- SearchFields – definiert, welche Felder für die Suchergebnisse zurückgegeben werden sollen. Dies kann wichtig sein, um z.B. die Größe der zurückgegebenen Antwort der API zu reduzieren oder um selbst definierte Felder (Custom Fields) im Ergebnis zurückgeben zu können. Die Namen der Felder müssen mit einem Komma separiert werden. Läßt man dieses Feld leer, werden alle navigierbaren Felder zurückggeben.
- Expand – eine Komma separierte Liste von Parametern, um die die Anforderung erweitert werden soll
Mit Hilfe der Parameter „StartAt“ und „MaxResult“ könnte auch relativ einfach eine Blätterfunktion implementiert werden – zumal das zurückgelieferte JSON immer auch die Anzahl aller zur JQL-Query passenden Ergebnisse mitliefert, unabhängig von der definierten Ergebnismenge mit „MaxResults“.
Unser Smartobjekt bietet für die Suche zwei Methoden:
- JQLSearch – komplette Anfrage mit den o.a. Parametern, die das komplette Suchergebnis zurück gibt.
- JQLSearchResultCount – eine Methode, die nur die JQL-Query als Parameter entgegen nimmt und ein sehr schlankes Objekt mit der Anzahl der gefunden Ergebnissen zurück gibt. Damit kann z.B. angezeigt werden wie viele Vorgänge z.B. für eine Person offen sind
JQLSearch
Folgendes Beispiel zeigt, wie eine Suche aussehen könnte. Aktuell hat die Methode noch keine deserialisierte Ausgabe. Das Ergebnis wird im JSON Rohformat zurückgegeben. Ich arbeite aktuell daran, ein Standardergebnis deserialisiert zurückzugeben, welches nur die wichtigsten Informationen beinhaltet und auf alle Vorgänge passt, unabhängig davon, ob eigene Felder defniert wurden oder nicht.
JQLSearchResultCount
Wie oben bereits beschrieben, nimmt diese Methode nur das JQL als Parameter entgegen und liefert lediglich die Anzahl der Ergebnisse zurück, ohne weitere Informationen zur den eigentlich gefundenen Vorgängen.
So, damit bin ich zunächst mal am Ende angekommen. Als nächstes werde ich den Servicebroker noch hinsichtlich der Benennung der Methoden etc. anpassen. Außerdem werde ich den Servicebroker noch um die ein oder andere Methode erweitern.
ArtikelbildBild von Markus Winkler auf Pixabay