Automating Archimate Reports from Linux
I use Archimate to create diagrams and document my infrastructure. It is a powerful tool but can have a bit of a learning curve. And I'm still learning. This document shows my workflow to create HTML and PDF reports for others to review.
At work I use both Windows and Linux, with Windows as the primary desktop. At home, it is almost entirely Linux. Git is used as a conduit for the Achimate model. I run the build process on Linux via a Jenkins webhook on a git commit trigger. This allows me to check in the model from any location and have the published models update automatically. In this example, I use a Makefile but the Jenkins process is easily added.
To setup this workflow, install Archimate (see Resources for the link) on your Linux system. I place the install in my home folder under ~/bin/Archi.
Next, I create a model. In this example, I diagrammed a code development process and promotion to production. The example is available int the Resources section. After creating the model, I save it to my Git controlled location. Then, I commit to the repository.
On Windows, I use either Git Bash or Git Gui to commit and push the file. Under Linux, I use the command line or in some cases, the Git tools in Atom or whatever IDE I happen to be using (but mostly the command line).
Up to this point it's been a standard git workflow: Edit the file, commit the file, push the file. Now we automate it. As mentioned, my workflow uses a Jenkins webhook on a git commit trigger. Whenever a file is commited, it kicks off the build process. Please see my other documentation on this process. For this example, I am using GNU Make to build.
This Makefile has two targets to create the report and push.
The report section uses the Ubuntu launch code from the Archimate download. It then calls the commandline.app addon (now included in recent versions of Archimate) and the report building module. We run this with:
If all goes well, you should see output similar to this:
The next step is to push the newly generated report to my webserver. For this, we use rsync and a target webserver. The choice of webserver is up to you. I use NginX or Apache, but pushing to an S3 bucket is also possible.
And if all goes well, the ./report directory will get synchronized to the webserver. You should see output like this:
Well, you won't see my banner. If you do, I've done something horribly wrong.
And finally we can browse the model online. I like doing it this way versus a static PDF as it allows more interactivity.
Inserting Git Changelog into Archimate Report
Update (2020.10.05) - Latest versions of Archimate broke this process as the file is now zipped. Unpacking the zipfile and editing the model.xml does still work but the scripts below do not. It was a bit of a hack so I'm revisiting this, with the most likely approach being to unmarshal the XML in Go to update the refs. At some point may even write out the entire model as a child element, something I've been wanting to try. We'll see.
Being a visual tool, creating a changelog in an Archimate file did not appear obvious. If you know a better way, please leave me a comment.
The goal of this process is to insert the git changelog directly into the HTML report. It's a bit of a kludge that uses awk to replace a placeholder keyword in the model with the git log when creating the report.
For example, in an Archimate View object in the model, I add the following lines to the documentation. The operative word is the "GITCHANGELOG" which is the placeholder value that gets replaced. You can have multiple keywords that can be processed with many command line tools such as M4, awk, sed or custom scripts.
In my workflow I include GITCHANGELOG, IP addresses and hostnames, test result links, and other dynamically generated content in the report.
Unfortunately, we cannot just substitute the keyword. First, we must escape the naughty characters in the XML. I use a combination of sed and awk do this. With sed, I escape the ampersand, greater/less than, double quote and single quote characters. There are other ways to do this will xmlstarlet and more than a couple Python libraries, but this served my purpose.
Next, I use awk to subsitute a file for the keyword.
Once that's done, I can run it through the report generation (see the previous article) and push the report.
Once run, the changelog is automatically inserted into the report.
The real point is not to show how to substitute a file -- that's easy -- but to show how automated documentation is key to providing accurate documentation. That is, the documentation matches the implementation because they pull from the same source data.