Archi Upgrade Procedure - internal storage format

Started by, July 11, 2023, 13:08:25 PM

Previous topic - Next topic

Hi All!

We are a fairly large team in our company that uses Archi and the coArchi plugin for collaboration of a shared model in Git.

The time has come for us to do some regular lifecycle maintenance of Archi and Upgrade to a newer version.

We have found a (very valuable) topic in this forum named Archi Upgrade Procedure that suggests two possible courses to take during upgrade:

   1. The team-members gradually Upgrades their Archi installation, This migration course allows different versions of Archi simultaneously.

   2. The team-members simultaneously Upgrades to the new version with a big bang. This migration course does not allow different versions simultaneously.

Which course to take depends on whether the old and new version of Archi use the same internal storage format or not.

Our upgrade scenario looks like below:
Component   Old Version   New Version
Archi               4.9.3            5.0.2
coArchi            0.8.3            0.8.8
jArchi               1.2.0            1.4.0

Can someone in the forum verify if the same internal storage format is the used in our scenario?
I'm not able to tell from reading the release notes.

We would also appreciate any advice in the matter, so if you have any experience of an Archi upgrade you want so share, or perhaps links to a good blog post, please do so.


Jean-Baptiste Sarrodie


The internal format changed with Archi 5.0. That was needed to support some new features of ArchiMate 3.2 such as the box vs Icon notation for all elements.

BTW, I recently had to update Archi in my team and I now prefer doing things in a slightly different way:

  • Everyone publish their changes. When done, they remove the model from their workspace
  • You refresh to make sure you have the latest version of the model on your workstation
  • You upgrades to the newest version of Archi/coArchi
  • You open the model, it will be automatically updated to the newer internal format
  • You commit this change (using an explicit commit message such as "Model migration to Archi 5.0 format") and publish it
  • Everyone update Archi and import the model into their workspace

This avoids the issue of your colleagues having to create a dummy commit (containing only the header/version change) before being able to refresh the model. With Archi 5.0, tis also speedup the upgrade as during the first run, Archi 5 will copy all your data to a new location (and this can take some time for the local workspace).

An alternative (if you don't want people to remove the model) is the following:
  • Everyone publish their changes
  • Everyone refresh to make sure they have the latest version of the model on their workstation
  • Everyone upgrades to the newest version of Archi/coArchi
  • Everyone can now work as usual and publish their changes when needed.

The  only drawback of this approach is that if at some point, someone wants to refresh (to get changes done by other) but think he/she did not change anything, he/she will still has to commit his/her changes (because the internal model upgrade that happened behind the hood). This might be anoying.


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


Thank you @Jean-Baptiste Sarrodie for clarifying the change of the internal storage format.
I'm also very grateful that you shared the upgrade process with us. That was really useful information that will save us a lot of time and frustration.

@Phil Beauvoir It might be a good idea to version the internal storage format, and include it in the release notes of future releases of Archi so regular users can choose the right upgrade course on their own.

Finally, thanks to you both for your excellent work with Archi.



Hi !

Thank you for the above procedure, we just moved to Archi 5 almost flawlessly in my team thanks to this.

The tricky part was to replicate the migration path on our 2nd branch : we use a dev/master branch strategy, and I needed a few retries to get the merge done :
  - I applied above procedure on our dev branch
  - Then Switched to master branch (still in 4.9), which automaticaly triggered a format migration to 5.0 in Archi, resulting in unwanted conflicts while merging dev (5.0) on master..

I would probably had a smoother ride if I had merge dev on master *before migration*, drop dev branch, migrate master to 5.0 and create a new dev branch.. seems obvious for me now.
Hope this helps others migrating to Archi 5 and using multiples git branches.

Alexis H.