Automatische Generierung von Dokumentationen zu Automic Objekten mithilfe des b4A DocBuilder Moduls

Blogbeitrag

In den vorherigen Blogs meines Kollegen Kay Koll wurde das Thema b4A Packages bereits intensiv behandelt und auch die Integration in eine CI/CD Pipeline wurde hervorgehoben. Im Rahmen dieser Integration stellt best4Automic auch weitere Features zur Verfügung, welche die Pipeline weiter anreichen können. Eines davon ist die automatische Generierung von Dokumentationen zu Automic Objekten über das b4A DocBuilder Modul.


Dokumentationen zu erstellen war bei Technikern noch nie ein beliebtes Thema und auch unsere Kollegen können ein Lied davon singen. Seitens Automic gibt es nativ keine Möglichkeit, die Erstellung zu vereinfachen und auch die sehr technische Workflow-Übersicht ist für Fachbereichsnutzer eher schwierig nachzuvollziehen.

Funktionsweise

Der DocBuilder erstellt auf Basis von Vorlagen die Dokumentation für alle Objekte innerhalb eines Packages. Typischerweise wird er bei der Erstellung einer neuen Version eines Packages ausgeführt, sodass alles immer aktuell ist. Die Vorlagen können dabei individuell auf die Bedürfnisse des Kunden abgestimmt werden (s. auch nächstes Kapitel).

Welche Vorlagen werden aktuell ausgeliefert?

Der b4A DocBuilder ist in der Lage, basierend auf beliebigen Vorlagen eine bestimmte Ausgabe zu generieren. Dabei können die Vorlagen auch sehr komplexe und individuelle Formen annehmen und bieten Flexibilität bei der Definition einer Vielzahl von Ausgabeformaten. Bei Bedarf können auch verschiedene DocBuilder Vorlagen kombiniert werden. Die folgenden Formate werden bereits unterstützt und können direkt in Ihrer Umgebung eingesetzt werden.

Der Automic Workflow

Zur Veranschaulichung haben wir einen einfachen Automic Workflow erstellt, der aus drei Schritten besteht: Ausführen eines Shellscripts auf einem Unix Server, Filetransfer einer Output Datei des Shellscripts auf einen SAP Server sowie Ausführung eines SAP Reports.

Der Screenshot alleine ist dabei als Dokumentation unbrauchbar. Zu viele technische Details verwirren Fachbereiche und das nicht standardisierte Format birgt seine Tücken. Schauen wir uns an, was der b4A DocBuilder hieraus erstellen kann.

Grafische Darstellung von Automic Workflows

Um Workflows und die Abläufe dahinter für Fachbereiche verständlicher zu machen, kann es nützlich sein, zu abstrahieren. Über ein SVG geben Sie Ihrem Fachbereich die Möglichkeit, interaktiv mit einem Workflow zu interagieren, der nur notwendige Informationen zu den jeweiligen Child-Aufgaben enthält. Gleichzeitig können die SVG-Dateien an verschiedensten Orten abgelegt werden, je nachdem, wo sie gebraucht werden.

Confluence

Atlassian Confluence hat sich als ein gängiges Tool etabliert, um Dokumentation an zentraler Stelle für alle Mitarbeiter zugänglich zu machen. Warum also nicht auch die Dokumentation für Automic Packages dort ablegen?

Genau dafür haben wir bereits vordefinierte Vorlagen, die die technischen Parameter der Objekte auslesen und in verständlicher sowie einheitlicher Form im Confluence ablegen. Dabei wird für jedes Package eine eigene Seite angelegt.

Die im Package enthaltenen Objekte erhalten ebenfalls eine eigene Seite, welche dann unterhalb der Package-Seite angelegt wird. Mit Hilfe der Index- und Suchfunktion von Confluence kann innerhalb der generierten Hilfe gezielt gesucht werden. Unsere Empfehlung: Nutzen Sie hierbei für Workflow Dokumentationen auch das SVG oder BPMN Feature!