Skip to content

MaksimAniskov/archi-powertools-verifier

Folders and files

NameName
Last commit message
Last commit date
Jan 3, 2024
May 6, 2024
Jan 27, 2024
Feb 12, 2024
Dec 26, 2024
Jan 27, 2024
Jan 13, 2024
Jan 13, 2024
Dec 17, 2023
Feb 12, 2024
Jan 27, 2024
Jan 13, 2024
Jan 27, 2024

Repository files navigation

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_sql/
verification_scripts_cql/

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 sqlite

We expect it to produce output as the following.

Executing verification scripts...
/usr/var/verification_scripts/duplicate-element-names.sql
Error! Duplicate element names:|Artifact|Artifact
Error! Duplicate element names:|Business Object|BusinessObject
Error! Duplicate element names:|dummy|ApplicationService
...
/usr/var/verification_scripts/empty-view.sql
/usr/var/verification_scripts/unused-elements.sql
/usr/var/verification_scripts/unused-relations.sql
Verification completed

Capability of leveraging Neo4j graph database and Cypher Query Language (CQL) for verifications

To test this capability, run following command. The only difference from the above is that runs neo4j container.

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

This time we expect the output to be like the following.

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

Executing verification scripts...
import/verification_scripts_cql/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_cql/empty-view.cypher
import/verification_scripts_cql/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 interactively using SQL 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  sqlite

It is important that we specify -f compose.ui.yaml which makes the setup run SQLite as interactive shell. So, expect to see sqlite command prompt waiting for your interactive commands.

...
Verification completed
SQLite version 3.32.1 2020-05-25 16:19:56
Enter ".help" for usage hints.
sqlite>

Let's type in following SQL query.

SELECT e.Name, e.ID
FROM elements e 
JOIN folder_content fc ON fc.ObjectID=e.ID 
JOIN folders f ON f.ID=fc.FolderID
WHERE f.Type="strategy"
  AND e.Name!="";

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.)

We expect to see following result.

Course of Action|id-0bd5f8241c0b428da90329046a7899f8
Resource|id-63ea29e7eba542df8395f96bc17cff26
Capability|id-76c259bd73124d2b9a0382fe6346cb96
Value Stream|id-7a4447848ab846cd843885116ee9d4be

To exit SQLite shell, type in and "execute" .quit command.

sqlite> .quit<Enter>

In case you are interested in learning more on using SQLite's power, let we forward you to these two pages: SQL As Understood By SQLite and Special commands to sqlite3 (dot-commands).

Analyze model interactively using CQL queries

Using the previous setup, run following command. Similar to the above, but this time we are going to use Neo4j and its Browser web UI.

Run it with this 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

It's important the command line has --service-ports option to make the container's port 7474 available for requests.

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

Query result should look like this. image

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.

image

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.

The repository has both SQL and CQL versions of the verification scripts.

To execute SQL scripts, run this command.

ARCHI_FOLDER=./examples/aws-resources \
ARCHI_FILE=model.archimate \
ADDITIONAL_DATA_FOLDER=./examples/aws-resources/additional_data \
SQLITE_SCRIPTS_FOLDER=./examples/aws-resources/verification_scripts_sql \
docker compose run --rm sqlite

This is the output we expect from the verification run:

Executing verification scripts...
/usr/var/verification_scripts/00-import-data.sql
/usr/var/verification_scripts/01-verify-s3-buckets.sql
Error! Model contains bucket that does not exist:|bucket-in-model
Error! S3 bucket not represented in model:|yet_another_example_bucket
Verification completed

To execute CQL version of the scripts, run following command.

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_cql \
docker compose run --rm neo4j

The output we expect:

Executing verification scripts...
import/verification_scripts_cql/00-import-data.cypher
Imported items from aws-s3-buckets.csv:
3
import/verification_scripts_cql/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

Compare two models

There is an example which demonstrates detecting discrepancies between two views in two different models.

System-A model has Default view in it. And Enterprise model is supposed to have its System A view equal to System-A's Default.

Views equality means that those two views represent same elements and relations between the elements.

To detect if there any inequality between the views, let's run following command.

ARCHI_FOLDER=./examples/model-federation \
ARCHI_FILE=enterprise.archimate \
ARCHI_FILE2=system-a.archimate \
NEO4J_SCRIPTS_FOLDER=./examples/model-federation/verification_scripts_cql \
NEO4J_VERSION=4.4 \
COMPOSE_PROJECT_NAME=archi-powertools-verifier-44 \
docker compose run --rm neo4j

Note: This example runs Neo4j version 4.4 which has support for apoc.diff.graphs procedure.

This is the output we expect from the verification run:

Executing verification scripts...
import/verification_scripts/00-compare-views.cypher
difference, entityType, id, sourceLabel, destLabel, source, dest
"Destination Entity not found", "Node", 0, "Element", NULL, {}, NULL
"Destination Entity not found", "Node", 1, "Element", NULL, {}, NULL
difference, entityType, id, sourceLabel, destLabel, source, dest
"Destination Entity not found", "Node", 3, "Element", NULL, {}, NULL
"Destination Entity not found", "Node", 4, "Element", NULL, {}, NULL
Verification completed

Non-empty result of running the verification script means that there are model elements or relations that represented differently in those two view of interest.

TODO: Make output of the script human-friendly.

Usage

This is summary of command line syntax:

docker compose [-f compose.yaml [-f compose.ui.yaml] [-f compose.git.yaml]] run [--service-ports] --rm sqlite|neo4j

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

Which container

sqlite to execute SQL scripts.

neo4j to execute CQL scripts.

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 SQLite interactive shell or Neo4j Browser's UI (Neo4j Browser 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] ]

Environment 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.
ARCHI_FILE2 (Optional) The second model for model comparison.

SQLITE_SCRIPTS_FOLDER Default value is ./verification_scripts_sql
The solution runs SQL scripts it finds in this folder.
Regardless to the files' extensions, it treats all files in the folder as SQL 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.

NEO4J_SCRIPTS_FOLDER Default value is ./verification_scripts_cql
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.
NEO4J_VERSION Default value is 5.15
Make Neo4j container run the specified version.

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 container when it exits.

Cleaning up temporary Docker volume

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

docker compose rm --volumes

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published