Hallo zusammen, heute möchte ich Euch einen Use Case für Jira Automation vorstellen. Es geht um automatisierte Erstellung von Vorgangsdokumentation in Confluence. Genauer, wir wollen automatische bei der Vorgangserstellung in Jira eine zugehörige Confluence Seite erstellen, vielleicht sogar mit Unterseiten.
Jira Automation begann einst als eine separate App und ist nun ein integriertes Feature in Jira Cloud und Jira Software Data Center sowie Jira Service Management Data Center. Wir haben in der Vergangenheit bereits Automation vorgestellt.
Der hier vorgestellte Use Case bezieht sich auf Jira und Confluence in der Cloud.
Automation funktioniert mithilfe Code-freier Regeln nach dem If-This-Then-That-Prinzip. Code-frei bedeutet, dass zur Erstellung der Regeln keinerlei Programmier- oder Scripting-Kenntnisse notwendig sind und die Regeln sozusagen „zusammengeklickt“ werden können. Die Komponenten, aus denen die Regeln bestehen, kann man grob in drei Kategorien einteilen: Trigger, Bedingungen und Aktionen.
- Trigger bestimmen, durch was eine Regel ausgelöst wird.
- Bedingungen bestimmen, was zutreffen muss, damit die Regel ausgeführt wird.
- Aktionen bestimmen, was tatsächlich passieren soll.
Automation für Confluence befindet sich immer noch in Entwicklung, und auch wenn erste Versionen bereits verfügbar sind, so ist der Umfang an Funktionen sehr begrenzt. Ich verwende daher für die meisten meiner Automation-Zwecke in Richtung Confluence eine mir besonders ans Herz gewachsene Aktion – den Web Request.
Die Web Request Aktion erlaubt es uns, aus Jira einen Aufruf an eine REST API zu richten, zum Beispiel an einen Endpunkt von (demselben oder einem beliebigen anderen) Jira oder auch Confluence. Damit stehen uns weitgehend alle von der REST API unterstützten Funktionen zur Verfügung: von der Erstellung von Vorgängen über Hinzufügen von Optionen zu einem benutzerdefinierten Feld bis hin zur automatisierten Anlage ganzer Projekte mit entsprechenden Schemata. Ebenfalls möglich ist die Erstellung von Inhalten in Confluence. Heute möchte ich diese Funktionalität anhand eines Use Case zeigen: Anlegen einer Seite in Confluence, ausgelöst durch Erstellung eines Vorgangs in Jira.
Wir werden einige Daten in sogenannten Smart Values speichern, bevor wir den Inhalt zu Confluence schicken. Wir haben hier einen Beitrag zu Smart Values verfasst, schreibt uns gerne, falls Ihr noch Fragen dazu habt. Die meisten dieser Daten müssen nicht in Variable ausgelagert werden, ich tue dies trotzdem gerne, um darüber schnell und einfach Konfigurationsänderungen durchführen zu können.
Folgende Daten werden wir in Smart Values erfassen:
Vorgangstitel und -schlüssel aus dem auslösenden Vorgang
Diese nutzen wir als Seitentitel für die neue Seite. Wir erfassen die Daten aus dem initiierenden Vorgang und entfernen vorsichtshalber Sonderzeichen, daher lautet der Inhalt unseres Smart Value:
{{issue.summary.replaceAll(“[^a-zA-Z0-9-:äöüß]”, ” “).trim()}} ({{issue.key}}
Dies speichern wir in der Variable {{ConfluencePageTitle}}
Confluence-Bereich, in dem wir die Seite erstellen
{{ConfluenceSpace}} – Hier brauchen wir nur den Bereichsschlüssel – ich bevorzuge es, ihn in einer Variable zu speichern zur besseren Pflege und Wiederverwendbarkeit der Regel
Seiteninhalte für Haupt- und Unterseiten unserer Vorgangsdokumentation
Wir können jeglichen Inhalt im Storage Format in JSON verpacken und an Confluence schicken. Ich lege mir in solchen Fällen die Seiten direkt in Confluence an, mit der gewünschten Formatierung und Layout, und kopiere dann die fertige Seite als Storage Format. Die Option, Storage Format zu sehen, findet ihr in dem „Drei Punkte“ Menu unter „Advanced details“:
Den Inhalt der jeweiligen Seite im Storage Format speichere ich dann in jeweils einer Variable, hier {{ParentPage}}, {{ChildPageA}} und {{ChildPageB}}.
Basic API-Token zur Authentifizierung in Confluence
Zur Authentifizierung an der REST API benötigen wir ein API-Token, und müssen dieses dann Base64 encoden. Wie genau das vor sich geht, hat Atlassian hier verständlich erklärt. Den resultierenden hexadezimalen String speichern wir zusammen mit dem Schlüsselwort „Basic“ und einem Leerzeichen in einer Variable:
Die URL der Confluence Instanz
Ich lagere die BaseURL in eine Variable namens {{AtlassianURL}} aus, falls ich diese Regel exportieren und in einer anderen Instanz einsetzen möchte, so brauche ich die BaseURL nur in der Variablen anzupassen.
Die Ancestor ID
Über die Ancestor ID wird festgelegt, unter welche Seite die neu erstellte Seite gehängt wird, worunter also sich die neue Seite in der Navigations- und Berechtigungshierarchie befindet. Falls unsere Hauptseite unter einer anderen Seite erzeugt werden soll, können wir die ID dieser übergeordneten Seite hier in der {{AncestorID}} Variablen hinterlegen.
Nach dem Erstellen der Hauptseite können wir eine weitere Variable aus dem Response Body mit der AncestorID unserer neu erstellten Hauptseite befüllen, z. B. in {{ParentID}}. Im weiteren Verlauf der Automation-Regel können wir Unterseiten unterhalb unserer Hauptseite erzeugen, da wir nun auf diese als Ancestor verweisen können.
Der Web Request
Der Web Request ist eine Standard-Aktion für Automation Regeln. Wir müssen zunächst das Ziel unseres Requests festlegen. Da wir die BaseURL bereits in einer Variable hinterlegt haben, ist das Ziel zur Erstellung einer Seite: {{AtlassianURL}}/wiki/rest/api/content
Wir benötigen auch mindestens zwei Header:
Authorization: {{BasicAPIToken}}
Content-Type: application/json
Die HTTP-Methode ist POST und web request body ist: “Custom data” In dem Feld für Custom Data kommt nun unser gesamter Inhalt:
<code macro JSON>
"type":"page",
"title":"{{ConfluencePageTitle}} ",
"ancestors":[{"id":{{AncestorID}}}],
"space":{
"key":"{{ConfluenceSpace}}"},
"body":{
"storage":{
"value":"{{ParentPage.replace("\"","'")}}",
"representation":"storage"
}}}
</code macro JSON>
Wir setzen noch einen Haken bei „Delay execution of subsequent rule actions until we’ve received a response for this web request“ damit wir die Daten der Antwort auf unser POST verwenden können.
Wir sehen hier, dass die meisten Angaben sich aus unseren vorher festgelegten Variablen speisen. Beim Aufruf der {{ParentPage}} Variable wird die Replace Methode aufgerufen, um Anführungsstriche zu escapen. Das wars! Damit haben wir unsere erste Seite in Confluence per REST API eingespielt.
Nach diesem Web Request – und wirklich in der Regelsequenz danach – erstellen wir eine weitere Variable, die bereits erwähnte {{ParentID}}. Wir befüllen sie mit der ID, die wir zurückerhalten, über die Standardvariable {{webResponse.body.id}}.
<a href=”{{AtlassianURL}}/browse/{{issue.key}}” data-card-appearance=”block”>{{AtlassianURL}}/browse/{{issue.key}}</a><br/>
Damit erhalte ich eine Zusammenfassung des initialen Jira-Vorgangs in Kartenformat auf meiner Seite. Diese Karte ist dynamisch, sie zieht bei jedem Aufruf die aktuellen Daten aus dem Vorgang, und durch die Referenz zu dem Jira-Vorgang erscheint die Confluence Seite auch automatisch in dem Vorgang selbst, unser „mentioned on“. Das erspart mir, explizit einen Link zum Vorgang hinzuzufügen.
Schreibt uns gerne, falls Ihr ebenfalls die Web Requests in Euren Automation Regeln nutzt, oder – wie immer – falls Ihr Fragen oder Anregungen habt.
