display history of views in published websites

Started by jsimoncello, September 11, 2023, 10:56:54 AM

Previous topic - Next topic


Hi all

Some thoughts and a script that I'd like to share even if I am still working on it : it may give you ideas.

I have been mandated to replace our old Mega web publishing server by its brand new equivalent powered by Archi. That is not difficult, but, for years, we have been missing a feature that would show the previous versions of our architecture views. So I have implemented a very basic and raw tool, based on jArchi which I have called "ArcHistory" which complements the published web sites with a page depicting the previous views.

# the Script

The script works by comparing checksums of the current view with a previous checksum stored in a 'database' (just a plain text file, actually).
If checksums are different, the script add the current view as an image to a webpage (one webpage per view). Finally it renders an index page, listing all changes detected by date.
One thing to consider : at each iteration after the first one, the script need the previous checksums and the current websites as it updates the index page and existing view pages.

I will put only some code extracts here, the full script can be found in attachment, still in an early version but I think  it is enough to understand the way it works.

//load checksums from file
let checkSums = new Map();
checkSums = loadChecksumFile(CHECKSUM_FILE);

// initiate the content that we will add to the index view
let newContent = "<h1>" + new Date().toISOString().split('T')[0] + "</h1><br/>"
//loop on each view of the model
$("archimate-diagram-model").each(function (view) {
    //compute checksum for this view
    let newChecksum = computeChecksum(view)
    let oldChecksum = checkSums.get(view.id);
    //if checksum has changed
    if (oldChecksum === null || oldChecksum === undefined || oldChecksum !== newChecksum.toString()) {
        console.log("view changed : " + view.name + " " + oldChecksum + " " + newChecksum)
        //add a link to the html page for this view
        newContent += "<a href='./views/" + view.id + ".html'/>" + view.name + "</a><br/>" + "\r\n";
        //create/update the html page associated with this page
        //add/replace the checksum to the map
        checkSums.set(view.id, newChecksum);


Ok the "cleverest" part of this, is obviously how the script computes checksum for a view :
- I started with a very dump method : get the SHA256 of the image as a base64. Works but... if you change one pixel of the image, it counts as a view change, creating a lot of false positives !
- so I have changed it to compute checksums based on a concatenation of the ids of all concepts and elements that appear in the view. That way, just moving around concepts, or even changing their labels does not count as an update.
Obviously, I think some of you may see things differently and adapt this checksum comparison to his needs.

# updating the website
Now, we have to add a convenient way to access history for each view in the website generated by archi. As I already had a bash script that do some post-processing of the websites, I just add two lines to it :

if [ -d /var/www/html/"$SITE_NAME"_story ]; then
        echo "adding archistory code"
        # insert link to archistory js
        sed -r -i -e "s|</head>|<script type=\"text/javascript\" src=\"js/archistory.js\"></script></head>|g" index.html
        # add history button
        sed -r -i -e "s|<ul class=\"nav navbar-nav navbar-right\">|<ul class=\"nav navbar-nav navbar-right\"><li><a  onclick=\"return openHistory();\" data-toggle=\"modal\" class=\"go\"><span>History</span></a></li>|g" index.html
        # get the js file and copy it to the web server
        cp /applis/archi/noumea/install/commons/archistory.js js/


The new history button :

The javascript file is very basic : it opens a new window with an url that can be
- the index file of the history website if no view is selected
- or if a view is selected the history file of the current view

Some screenshots (yep, it deserves some UI enhancements) the index file :

An sample of a history file, here I have added a second note object (upper-right corner) between the first and second run :

Of course, you have to run this each time the archi website is regenerated.

# Running it periodically

Once a week/month (cron task), I run headless archi on my server, launching this script  :
        xvfb-run /applis/archi/Archi/Archi -application com.archimatetool.commandline.app \
        -consoleLog -nosplash \
        --loadModel $REPO_URL \
        --script.runScript  /applis/archi/noumea/jscripts/Archistory.ajs \
        -siteName=$SITE_NAME -dataFolder=$DATA_FOLDER  -rootfolder=$ROOT_FOLDER

# Enhancements
I have yet to work on some improvements :
- a better UI in the generated history file, maybe some thing closer to the look and feel of the archi site
- a way to make identifying the changes between views easier, maybe turns their border in red



Very interesting and clever! jArchi is indeed very powerful

Phil Beauvoir

If you value and use Archi, please consider making a donation!
Ask your ArchiMate related questions to the ArchiMate Community's Discussion Board.


@jsimoncello BTW, just missing the script code or the link to the script ;)

Phil Beauvoir

Quote from: rchevallier on September 12, 2023, 10:09:16 AM@jsimoncello BTW, just missing the script code or the link to the script ;)

At the bottom of the post, in the attachments.
If you value and use Archi, please consider making a donation!
Ask your ArchiMate related questions to the ArchiMate Community's Discussion Board.



Thanks and ooups too, I have just realized that I have not specified the library I am using to compute checksums : it's https://cryptojs.gitbook.io/docs/