Als ich mich ein wenig mit der REST-API von JIRA beschäftigt hatte, kam mir die Idee, dass es auch möglich sein muss, mit Hilfe von dox42 und der JIRA REST-API Dokumente aus den JIRA-Daten generieren zu können. Da dox42 einen Provider für XML/JSON bietet, wollte ich das mal austesten.
Nachdem ich ein wenig rumgespielt hatte, hatte ich relativ schnell ein Wordtemplate, mit dem man über dox42 eine Liste von JIRA-Vorgängen erzeugen kann.
Hierzu habe ich ganz einfach die Search-Methode der JIRA-API genutzt (mehr zu diesem Thema könnt ihr hier nachlesen: https://developer.atlassian.com/server/jira/platform/jira-rest-api-examples/#searching-for-issues-examples).
Ich bin folgendermaßen vorgegangen:
- Datamap über das dox42 AddIn anlegen
- Als Datenquelle XML/JSON auswählen
- Einen Eingabeparameter definieren (in diesem Beispiel „url“)
URL/XML/JSON: Den Eingabeparameter „url“ als Datenfeld einfügen. Dieser Parameter legt später fest welche Daten angezeigt werden sollen. Die Search-Methode der JIRA-REST Api bietet an dieser Stelle unglaublich flexible Möglichkeiten mit der internen Such-Query „JQL“
Da die Search-API ein Array von Elementen zurückgibt, benötigen wir an als Root-Element das „item“
Als nächstes können wir die gewünschten Eigenschaften als Datenfelder festlegen.
Vorsicht: Mit Parametern an die REST-API kann definiert werden, welche Felder im JSON-Response zurückgegeben werden sollen. Das kann mit dem Parameter „fields“ definiert werden. In unserem Beispiel habe ich die Felder summary, description und issuetype definiert (Kommaseparierte Liste –> fields=summary,description,issuetype
Damit wird zugleich das Ergebnis des Suchaufrufes schlank gehalten, da dann wirklich nur die Daten zurückgegeben werden, die man auch wirklich benötigt (neben ein paar Standardfeldern).
Da das JSON, welches die JIRA-REST-API zurückliefert relativ komplex werden kann, müssen teilweise längere Pfade zur verschachtelten Unterobjekten angegeben werden. In unserem Beispiel sind das z.B. die Felder summary und description sowie der issuetype.
Diese Datenfelder müssen mit dem Typ XPath angegeben werden. Die anderen Felder, die direkt am Rootelement hängen können einfach als SubElement und ohne Pfadangabe angelegt werden.
Ein Beispiel für das JSON, das durch die API geliefert wird, kann wie folgt aussehen:
{
"expand":"schema,names",
"startAt":0,
"maxResults":5,
"total":144,
"issues":[
{
"expand":"operations,versionedRepresentations,editmeta,changelog,renderedFields",
"id":"94049",
"self":"https://XXXXXXX/rest/api/2/issue/94049",
"key":"FT-139",
"fields":{
"summary":"Fieldtest device item - Built-in appliance",
"issuetype":{
"self":"https://XXXXXXX/rest/api/2/issuetype/11401",
"id":"11401",
"description":"",
"iconUrl":"https://XXXXXXX/secure/viewavatar?size=xsmall&avatarId=10316&avatarType=issuetype",
"name":"Device",
"subtask":false,
"avatarId":10316
},
"description":"Device production plan issue"
}
},
{
"expand":"operations,versionedRepresentations,editmeta,changelog,renderedFields",
"id":"94048",
"self":"https://XXXXXXX/rest/api/2/issue/94048",
"key":"FT-138",
"fields":{
"summary":"Fieldtest device item - Free Standing appliance",
"issuetype":{
"self":"https://XXXXXXX/rest/api/2/issuetype/11401",
"id":"11401",
"description":"",
"iconUrl":"https://XXXXXXX/secure/viewavatar?size=xsmall&avatarId=10316&avatarType=issuetype",
"name":"Device",
"subtask":false,
"avatarId":10316
},
"description":"Device production plan issue"
}
}]
}
Die REST-API kann natürlich nicht so ohne Weiteres aufgerufen werden. Im Normalfall erfordert auch die REST-API eine Authentifizierung. In unserem Beispiel habe ich die Basic-Authentifizierung implementiert.
Hierzu muss der HTTP-Aufruf einen Parameter im Header mitschicken.
Der Parameter setzt sich aus einem Key/Value-Paar zusammen.
Key: Authorization
Value: Basic Username:Password oder Basic AuthToken
Username:Password oder AuthToken müssen Base64 Encoded sein. Auf unserer Plattform wird die Methode mit Username und Password noch unterstützt. In der Cloud muss zuvor ein Token erstellt werden. Mehr hierzu kannst Du auch unter https://www.coreworxx.de/2021/05/02/confluence-custom-service-broker/ nachlesen.
Das war es eigentlich schon – nun sollte alles soweit vorbereitet sein, um das eigentliche Template zu bauen und schon kann es losgehen.
Beispiel Template:
Verfügbare Datenfelder:
Beispiel Aufruf (Eingabe der URL):
In unserem Beispiel suchen wir nach Vorgängen in einem Projekt, das den Key FT (jql=project=FT) hat.
Außerdem möchten wir nur insgesamt 5 (maxResults) Ergebnisse haben, beginnend mit den ersten 5 Ergebnissen (startAt=0).
Damit unsere notwendigen Felder auch verfügbar sind und um den JSON-Result schlank zu halten möchten wir neben den Standardfeldern nur die Informationen folgender Felder haben: summary,description,issuetype (fields=summary,description,issuetype)
Unser „url“-Parameter, welches an das dox42-Wordtemplate übergeben wird sieht demnach so aus:
https://<JIRA-URL>/rest/api/2/search?jql=project=FT&startAt=0&maxResults=5&fields=summary,description,issuetype
Sofern das entsprechende Makro auf dem JIRA-Server vorhanden ist, kann die API auch vorab getestet werden:
Das Endergebnis sieht dann z.B. so aus:
