The ArchiMate® Verifier

A solution that allows verification of ArchiMate® models against validity statements and formal data sets, e.g. exports from infrastructure services or business apps.

Getting started

Prerequisites

The examples provided below assume that you have installed and configured Docker and Docker Compose.

Clone this repository. Make sure that you have following folders and files in your current folder.

compose.yaml
compose.ui.yaml
compose.git.yaml
examples/
verification_scripts/duplicate-element-names.cypher
verification_scripts/empty-view.cypher
verification_scripts/unused-elements.cypher

Basic verifications

We are going to use Archimate3.2 Reference sheets.archimate model by RemcoSchellekensNS.
Download it from here on GitHub.
Place the model file in examples folder.

Run following command.

ARCHI_FOLDER=./examples \
ARCHI_FILE="Archimate3.2 Reference sheets.archimate" \
docker compose run --rm neo4j

We expect it to produce output as the following.

Importing the Archimate model to Neo4j...
+--------------------+
| Imported elements: |
+--------------------+
| 165                |
+--------------------+
...

Executing verification scripts...
import/verification_scripts/duplicate-element-names.cypher
Error! Duplicate element names, Type, Name
"id-5b620626cb01470fa03cc24e69cfebf6", "ApplicationService", "dummy"
"id-906aee6b07e443fbbaeca8138c89baa2", "ApplicationService", "dummy"
...
"id-7e8ec9f4f0364a69b1d72ade21f8fa9b", "Artifact", "Artifact"
"id-90bc0d5f23b4479183896557f7a9779c", "Artifact", "Artifact"
"id-fdc89820d2da497493d2896399dc7917", "BusinessObject", "Business Object"
"id-9465b2c8e3484e6b97f9eff0cd16abe4", "BusinessObject", "Business Object"

import/verification_scripts/empty-view.cypher
import/verification_scripts/unused-elements.cypher
Verification completed

Verify one of the models you have

Copy your model file to examples folder, or alternatively, modify ARCHI_FOLDER variable to point to your model files folder.
Modify ARCHI_FILE providing the model's file name.

Analyze model using Neo4j's Cypher Query Language (CQL) queries

Using the previous setup, run following command.

ARCHI_FOLDER=./examples \
ARCHI_FILE="Archimate3.2 Reference sheets.archimate" \
docker compose -f compose.yaml -f compose.ui.yaml run --rm --service-ports neo4j

After it's done and has outputted Verification completed, open http://localhost:7474/ in the browser. This is Neo4j Browser's UI.

Copy following CQL query, then paste it to the UI, then press Ctrl-Enter to execute it.

MATCH (n)-[:Archi_LivesIn]->(:Archi_Folder{type:"strategy"})
WHERE NOT n.name=""
RETURN n

With this query we ask it to find all ArchiMate elements that reside in ArchiMate folders of type strategy. (In other words, all elements of Strategy layer of the model.) (We exclude all element that have empty name as Archimate3.2 Reference sheets.archimate model has some, and we are not interested in them.)

Query result should look like this.

Let's try some other query.

MATCH (n:TechnologyService)-[r]-(e)
WHERE NOT n.name=""
  AND NOT r.name STARTS WITH "Archi_"
RETURN n, e, r

Semantics of this query is Find all TechnologyService elements, and show all their relations.

Verify model against "the real world"

In this example we are going to use model stored in examples/aws-resources/model.archimate file and list of S3 buckets, we pretend exist in our AWS account, in file examples/aws-resources/aws-s3-buckets.csv

(You can easily produce similar output by using following AWS CLI command.)

aws s3api list-buckets --query "Buckets[].[Name]" --output text

Let's verify whether our model contains correct representation of the buckets.

ARCHI_FOLDER=./examples/aws-resources \
ARCHI_FILE=model.archimate \
ADDITIONAL_DATA_FOLDER=./examples/aws-resources/additional_data \
NEO4J_SCRIPTS_FOLDER=./examples/aws-resources/verification_scripts \
docker compose run --rm neo4j

This the output we expect from the verification run.

Executing verification scripts...
import/verification_scripts/00-import-data.cypher
Imported items from aws-s3-buckets.csv:
3
import/verification_scripts/01-verify-s3-buckets.cypher
Error!
"S3 bucket not represented in model:  yet_another_example_bucket"
"Model contains bucket that does not exist:  bucket-in-model"
Verification completed

Usage

There are three things you leverage to control how this solution behaves: (1) Compose YAML files; (2) environment variables; (3) Docker Compose's command line parameters.

Compose files

compose.yaml configures basic functionality. Always required. You either explicitly specify -f compose.yaml, or provide no -f parameter letting Docker Compose to default to this file. (Read this part of Docker Compose's documentation.)

compose.ui.yaml enables Neo4j Browser's UI (It also requires providing --service-ports parameter. See below.)

compose.git.yaml makes the solution read the model from Git repository rather than from .archimate file. (It also requires providing GIT_* environment variables. See below.)

You can combine compose.ui.yaml and compose.git.yaml when you need both features.

In case you provide any of the non-default YAMLs, you need to include -f compose.yaml explicitly.
So, full syntax of -f part of Docker command line looks like this.

[-f compose.yaml [-f compose.ui.yaml] [-f compose.git.yaml] ]

Environmant variables

ARCHI_FOLDER Default value is . (current folder)
ARCHI_FILE Default value is model.archimate
The solution processes model file with this name you provide in this folder.

NEO4J_SCRIPTS_FOLDER Default value is ./verification_scripts
The solution runs CQL scripts it finds in this folder.
Regardless to the files' extensions, it treats all files in the folder as CQL scripts.
The folder can contain subfolders. All subfolders get processed recursively. It runs the scripts one by one in alphabetical order of subfolder and file names.

ADDITIONAL_DATA_FOLDER Default value is ./additional_data
Additional data you make available to Neo4j as files in as import/additional_data directory.

(To make GIT_* variables come to effect, you need to enable support for Git as described above.)

GIT_URL Maps to --modelrepository.cloneModel parameter of the Archimate tool's CLI described here.
GIT_USER Maps to --modelrepository.userName
GIT_PASSWORD_FILES_FOLDER and GIT_PASSWORD_FILE map to --modelrepository.passFile

There are several ways how you can provide environment variables to your docker command. Read this part of Docker Compose's documentation

Docker CLI parameters

It is recommended to us --rm parameter to automatically remove the neo4j container when it exits.

So, let's summarize command line syntax.

docker compose run [-f ...] [--service-ports] --rm neo4j

Cleaning up temporary Docker volume

There is a volume this solution create. To remove it, run following command.

docker compose rm --volumes

Roadmap

• Allow model analysis and verification using SQL queries.