Understand the Basics - archimatetool/archi-modelrepository-plugin GitHub Wiki

How it works

Archi used to be a single user solution with no collaboration feature. This changed with the creation, some years ago, of the model repository plugin, usually known as the collaboration plugin.

The plugin follows the KISS principle: instead of reinventing the wheel and implementing the whole set of collaboration features, it uses Git (a source code management system) to manage the hard stuff (branch management, diff/merge...). But the plugin manages all the "plumbing" needed to provide a good user experience without requiring Git knowledge.

From a technical point of view, a model repository is nothing more than a Git server into which you’ll have one git repository per model. Each of those repositories (that you’ll have to create by yourself) will contain a single ArchiMate model stored in a set of XML files. Each file contains the description of a single object (element, relationship or view).

If you are interrested by the underlying logic, note that it is built upon already existing Grafico plugin, so reading Grafico wiki can helps you understand how all this can work.

Important: you shouldn’t use merge, pull requests or similar features from your Git server as this would most certainly lead to model corruption. Though based on Git, the collaboration plugin adds several anti-corruption actions while performing these operations.

Key User Interface elements

ui

  • Collaboration Workspace: allows quick access to all ArchiMate models managed by this plugin. Model icon change depending on sync state. This state is also visible in the status bar when a model is selected.
  • Change History tab: show the list of commits done on selected model. Also allows access to older versions (Extract model from this commit) and rolling back changes (Restore to this commit and Undo the lastest commit).
  • Collaboration menu: offers access to all features. They apply to the currently active model (ie. the model owning the view being edited and in focus, or the one that contains the select element in the model tree).
  • Toolbar: offers quick access to main features. Also apply to the currently active model.

Quick start

  • You need to have a new empty git repository already setup on a git server
  • Ensure the default branch on the git server is named "master" ("main" will be supported in a future version)
  • Note that some Git hosting sites, such as GitHub and BitBucket, require the use of a Personal Access Token for the password if using a HTTPS connection. See https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
  • To add the model from the repository locally, select the first toolbar button in the plugin tab (the green cross). This will clone the repository and create a new blank model
  • Work as usual on your model and save it whenever you want
  • When you're ready to commit your changes, then choose "Commit Changes" (this can be done offline)
  • When you're ready to publish/share your work, then choose "Publish". In case of conflicts (same concept changed and published by someone else) you'll see a windows helping you to fix them.