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.
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).
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.
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.
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.
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!
Ähnlich zu den Confluence Vorlagen können auch HTML- oder Markdown-Dokumente über den DocBuilder erstellt werden. Diese können dann direkt auf einem Webserver abgelegt werden (bspw. Apache oder Hugo). Ein gutes Beispiel hierfür ist die offizielle Dokumentation zu unseren b4A Packages, mit denen wir relevante Funktionalitäten als Automic Packages ausliefern. Schauen Sie doch mal rein und machen Sie sich ein Bild davon, was alles möglich ist!
Hier geht es direkt zu docs.best4automic.de.
BPMN 2.0 ist eine universelle Modellierungssprache, die es vor allem für Fachbereiche vereinfacht, Prozesse zu verstehen. Normalerweise würde der Fachbereich das BPMN nutzen, um eine Prozessautomatisierung zu beantragen. Daher macht es umso mehr Sinn, dieses Format auch in die umgekehrte Richtung zu nutzen. Dabei generiert der DocBuilder ein BPMN 2.0 konformes Dokument für Ihre Workflows basierend auf Vorlagen, welches in jeder gängigen BPMN Modeler Software geöffnet werden kann. So sieht das für unseren Demo-Workflow generierte BPMN aus:
Wenn gewollt, kann dies natürlich noch mit weiteren Informationen angereichert werden und selbstverständlich auch komplexere Workflows mit beliebig vielen Tasks darstellen.
Mit dem b4A DocBuilder automatisieren Sie den Dokumentations-Prozess, machen Ihre Automation transparenter und entlasten Sie gleichzeitig das Automic Team.
Fachbereiche erhalten auf ihre Bedürfnisse abgestimmte Dokumentationen ihrer Workflows und das Automic Team hat eine Sorge weniger. Generieren Sie Dokumentationen für Ihre Automic Objekte auf Knopfdruck und laden Sie diese innerhalb weniger Sekunden auch direkt in Ihr jeweiliges Dokumentations-Tool hoch.
Dies alles und noch viel mehr ist mit unserer Lösung best4Automic möglich!
Ich hoffe, dass ich Sie als Automic-Anwender mit diesem Beitrag über dieses immer wichtiger werdende Thema detailliert informieren konnte und möchte Sie ermuntern, bei weiteren Fragen, die dieser Blog nicht abdecken konnte, mit mir in Kontakt zu treten.
Nach seinem dualen Studium der Wirtschaftsinformatik bei einer großen deutschen Bank und 9 Jahren Berufserfahrung u.a. im Automic Bereich, wechselte Marcel zur best-blu, wo er fortan Kunden im Bereich Business Process Automation berät. Gleichzeitig hat Marcel als Hauptverantwortlicher einen maßgeblichen Anteil an der Entwicklung unserer Lösung requests4Automation (r4A).