Archimate

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.

# Makefile
PROJECT=example
WEBSERVER=192.168.5.190

report:
        PATH=~/bin/Archi:$$PATH  \
        UBUNTU_MENUPROXY=0 Archi -application com.archimatetool.commandline.app \
          -consoleLog -nosplash \
          --loadModel $(PROJECT).archimate \
          --html.createReport ./report/

push:
        PATH=/usr/bin:~/bin/Archi:$$PATH \
        rsync -a report deploy@$(WEBSERVER):/var/www/html/architecture/$(PROJECT)


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:

[kwan@infinity archimate]$ make report 2>/dev/null

If all goes well, you should see output similar to this:

PATH=~/bin/Archi:$PATH  \
UBUNTU_MENUPROXY=0 Archi -application com.archimatetool.commandline.app \
  -consoleLog -nosplash \
  --loadModel example.archimate \
  --html.createReport ./report/
[Core] Loaded model: 'Production Deployment'
[HTMLReport] Creating report from 'Production Deployment' to ./report/
[HTMLReport] Report generated!

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.

[kwan@infinity archimate]$ make push

And if all goes well, the ./report directory will get synchronized to the webserver. You should see output like this:

PATH=/usr/bin:~/bin/Archi:$PATH \
rsync -a report kwan@vm-helios-002:/var/www/html/architecture/example
+----------------------------------------------------+
|   Digital Hermit Research Laboratories (DHRL)      |
+----------------------------------------------------+
|  Unauthorized access to this system is prohibited. |
| DHRL reserves the right to monitor the use of this |
| system as required to ensure its stability,        |
| availability and security.                         |
+----------------------------------------------------+
 Hostname   : vm-helios-002
 IP Address : 192.168.5.190
 Application: Development

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

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.

annotate:
    git pull
    git log -n 5 > ./tmp/gitlog.raw
    sed -i -e 's/&/\&/' \
        -e 's/>/\>/' \
        -e 's/</\&lt;/' \
        -e 's/"/\&quot;/g' \
        -e "s/'/\&apos;/g" \
        ./tmp/gitlog.raw
    awk 'NR==FNR { rep = (rep=="" ? "" : rep ORS) $$0; next }\
        /GITCHANGELOG/ { $$0 = rep }\
        { print } ' ./tmp/gitlog.raw model.archimate >./tmp/temporary.archimate
    PATH=/usr/bin:~/bin/Archi:$$PATH UBUNTU_MENUPROXY=0 Archi -application \
      com.archimatetool.commandline.app -consoleLog -nosplash --loadModel \
      ./tmp/temporary.archimate --html.createReport ./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.