A solution that allows verification of ArchiMate® models against validity statements and formal data sets, e.g. exports from infrastructure services or business apps.
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/
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
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
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.
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).
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.
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.
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
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.
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.
sqlite
to execute SQL scripts.
neo4j
to execute CQL scripts.
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] ]
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
It is recommended to us --rm
parameter to automatically remove the container when it exits.
There is a volume this solution create. To remove it, run following command.
docker compose rm --volumes