Models4Insight Documentation¶
Welcome to the documentation for Models4Insight!
Models4Insight is a Software as a Service solution, that helps you to manage the lifecycle of your ArchiMate models. It consists of 4 parts:
- Model Repository
- Platform
- Analytics Library
- Data2Model
- Consistency Metrics
By storing your models in the Models4Insight Model Repository, you create a single source of truth which can be used for analysis. The repository is accessible via the Models4Insight Platform, which also provides model management features, such as:
- Collaboration
- Versioning
- Conflict management
- Branching
Data2Model helps you to automatically generate ArchiMate models from structured datasets like Excel spreadsheets, CSV, or JSON. This includes deriving concepts from your data, as well as arranging them into meaningful views. Data2Model integrates well with the Models4Insight repository and platform.
The analytics library provides a basis for automated model generation, as well as advanced analytics using models. It is available as a Python distribution upon request.
If you are new to Models4Insight, please have a look at our getting started guides!
Getting started guides¶
Get started with the Models4Insight Platform
Get started with Models4Insight Consistency Metrics
Models4Insight Platform User Guide¶
About Models4Insight¶
Models4Insight is a Software as a Service solution, that helps you to manage the lifecycle of your ArchiMate models. It consists of 4 parts:
- Model Repository
- Platform
- Analytics Library
- Data2Model
- Consistency Metrics
By storing your models in the Models4Insight Model Repository, you create a single source of truth which can be used for analysis. The repository is accessible via the Models4Insight Platform, which also provides model management features, such as:
- Collaboration
- Versioning
- Conflict management
- Branching
Data2Model helps you to automatically generate ArchiMate models from structured datasets like Excel spreadsheets, CSV, or JSON. This includes deriving concepts from your data, as well as arranging them into meaningful views. Data2Model integrates well with the Models4Insight repository and platform.
The analytics library provides a basis for automated model generation, as well as advanced analytics using models. It is available as a Python distribution upon request.
This user guide is intended as a reference to help you get set up with the Models4Insight platform.
Registration¶
Before getting started, please register an account. To register, please visit www.models4insight.com and click the register button.
Clicking the register button takes you to the user registration page where you are asked to provide some personal information. Note: A username cannot use capital letters, special characters or double spaces.
Once you have filled in all the information, click on register. You will receive a verification email at the address you provided. You need to verify your registration before you can log in.
You should immediately receive an email from Aurelius Enterprise. The link within is valid for 5 minutes. Check your spam folder if you cannot find the email. If 5 minutes have passed, please click the re-send email button.
Login¶
All Models4Insight services use a single sign-on. This means you only need to log in once to use either. To log in, press the login button at the top of the Models4Insight homepage. You will also be prompted to log in when visiting the platform directly, if you have not already done so.
Once logged in, you will be directed to the Models4Insight platform.
Accessing the Models4Insight Platform¶
You can access the platform by clicking on the platform button on the Models4Insight homepage. Alternatively, you can navigate directly to the platform.
On some mobile devices, it is possible to save the platform to your home screen. You will be prompted to do so after you first log in. Using the platform as an app provides a more seamless user experience and helps you get back to the platform more easily.
The platform is where you upload models, do version control, and control the authorization of project members. You can upload different versions, retrieve the versions that you previously uploaded, clone branches to work simultaneously on different versions of the same model and merge them back together.
Home¶
Welcome¶
On first visiting the Models4Insight platform, you will be presented with an introductory page that is intended to help you get started quickly. Depending on your preferred role, please select the option that fits best. You will then be presented with a set of recommended actions. If you do not like the role you have selected, you can go back and choose another.
Returning user¶
If you are a returning user, you will instead be presented with a quick access menu. The continue working button will take you back to the page that you last visited when using the platform. There is also a list of your favourite projects, as well as your most recently visited projects. You can directly open a project by clicking the corresponding table row.
Projects Overview¶
The projects page gives an overview of all the projects you have access to. This includes private projects of which you are a member, as well as all public projects. Here you also have the option to create a new project.
Create project¶
To create a project, fill in a project name and description. You cannot use the same project name twice. Furthermore, it must contain at least three characters, and cannot contain special characters or double spaces. Next, please provide some description of your project. The description cannot be empty. Under subscription, you have an option to make this project public or private. When you decide to make a project public, anyone who has access to the platform can see it, access it and download your models. Creating a private project limits access to you and those you have authorized (how to add new members to your project is explained under the Add member section). Please select your preference and click the create button.
Opening an existing project¶
In addition to creating projects, you can also open your previously created projects or any projects shared with you. The table on the right of the page lists all projects of which you are a member. You can open any project by clicking its name in the table. You can search for any specific project using the search bar on top of the table. In addition, you can sort each column of the table by clicking the respective column headers.
Project Homepage¶
Opening a project redirects you to that project’s homepage. On your first visit, you will be presented with a short introduction. This introduction will guide you in setting up your project.
On returning visits, you will instead be presented with an overview of the recent activity in the project.
Project welcome¶
Whenever you open a project without any models in it, you will be presented with a short introduction that is intended to help you get set up.
Project actions¶
There are various actions you can perform related to version control, tracking your team’s activities, access control and publishing your model(s) to the portal. Each of these actions is described in the sections below. Some of these actions (e.g. publishing a model and adding new project members) are only available to users with elevated permissions.
Upload a model¶
Available to: Model contributor and higher
To add new models to your project, or to update existing models, you can upload ArchiMate model files from your computer to the Models4Insight repository. The repository currently supports ArchiMate models created in the open-source tool Archi (www.archimatetool.com). You can recognize Archi model files by the .archimate extension.
When you upload a model, you will update the branch you have selected with a new version.
To select a file to upload, drag a file into the striped upload area, or click the button inside of the area to open a ‘select file’ dialog window. After selecting a file, please select your target branch. If you want to publish your model to a new branch, please click the Plus button next to the branch field and enter the name of your new branch. Please also provide a short description in the Comment section (this cannot be empty!). Finally, please click the Upload file button.
A progress bar will appear at the top of the window to indicate the progress of the upload. After the upload completes, your model will be available from the model repository.
When the repository recognizes that your upload contains changes to the model, you will be prompted to choose which changes to keep. You can read more about how this works in the Conflict Resolution section.
In some specific cases, you may want to set additional parameters for your model upload. The settings button next to the upload button opens an options window that allows you to do the following:
| Option | Description |
|---|---|
| Conflict resolution template | By selecting a conflict resolution template here, the selected template will be automatically applied when conflicts are detected. This skips the manual conflict resolution step. |
| Keep original ids | By default, concepts are assigned an id when they are first imported into the repository. The repository uses these ids to detect whether two concepts are the same. When importing a model from another project, the concepts in that model will already have tracking ids assigned to them. When this option is enabled, the repository will use these ids rather than newly generated ones. This ensures that changes made to the model (in either project) can be shared between projects without causing model inconsistencies. |
Retrieve model¶
Available to: Business user and higher
To retrieve a model from your project, click on Retrieve a Model in the menu under the project banner. Here you will find an overview of all versions of the model currently in the repository. The overview is on the right side of the page. On the left side of the page, you will find a number of filter options that will help you find the version of the model you’re looking for. You can filter based on the branch containing the model, the time period in which it was committed, as well as the description of the model and the person who committed it. Once you have found the version of the model you’re looking for, you can download it by hovering over the corresponding context menu with your cursor (represented by three dots) and clicking ‘Retrieve model.
If you are looking for the latest version of a model for a particular branch, you can also click ‘Retrieve latest’ under the context menu for that branch.
You can use Archi to open the retrieved models. The name of the file you retrieve is automatically generated. Do not be confused if this is different from the original name of the file you uploaded; the content of the model is still the same.
Model explorer¶
If you would instead like to view the model in your browser, click the ‘Explore Model’ under the context menu for the version you would like to view.
Model view¶
The model explorer shows a single view of the model. You can pan and zoom the view using your mouse and scroll wheel.
Additionally, the model view has several buttons at the top right corner of the view. Use these to access the following functions:
- Show more information about the current view in the side window
- Show the current view in full screen mode (or to exit full screen mode)
- Reset the view to its original position and zoom level
- Download a picture of the current view.
Note that when exporting a picture of the current view from the model explorer, Models4Insight automatically adds metadata that allows you to track the following:
- The project the model is in
- The branch the model is in
- The version of the model
- The id of the view
- The name of the view
- When the picture was exported
- Who exported the picture
This metadata is especially helpful when using the architecture model outside of the repository, such as in documents or presentations. The version info can help identify when such documents need to be updated.
You can click concepts in the view to bring up additional details about the selected concept in the side window. The view info and selection info sections are discussed separately in more detail.
Browse the model¶
To open another view, start by clicking the Browse the model button to the top right above the view. This will open the side window with the model browser.
The model browser consists of a navigation tree that mirrors the folder structure of the model like in Archi. You also have the option to search for a specific view using the dropdown and search menu above the navigation tree.
When you select another view, it will show up in the model viewer. The model browser will then automatically close. You also have the option to keep the model browser open by pinning it to the side. You can enable this by clicking the pin icon at the top of the side window.
Model details¶
In addition to the model browser, the side window also contains the following tabs:
- Model: an overview of all elements and relationships in the model
- View info: details about the current view
- Selection info: details about the currently selected concept (if any are currently selected)
Model¶
To open the model tab, select the model tab in the side window.
The model tab consists of two tables respectively listing the elements and relationships that make up the model. By clicking on any element or relationship, it will be selected in the model and the selection details will be opened. You can then use the details tab to navigate to any view the concept is used in, or to find connected elements and relationships.
There is also a search bar that allows you to search for any concept in the model via a full text search. Some examples include:
- Searching for a concept by name
- Searching for a concept by type
- Searching for a concept by description
- Searching for a concept by id
Note that you can also use any combination of the above methods. For example, you could use business process finance to find all business processes that include finance in their name or description.
Searching for a concept by id is especially powerful in conjunction with the consistency metrics application.
View info¶
To open the view info tab, you can use the view info button in the model viewer, or select the view info tab in the side window.
The view info tab shows the name of the current view, as well as the description and any other metadata. If you use view references in your model, there will be a list of view references in the current view, as well as a list of all views referencing it. You can open these views directly by clicking their respective names.
Selection info¶
If you have a concept selected in the model, the side window will also have the selection info tab available. When you select a concept in the view, the side window will open to this tab directly. You can also open it by clicking the selection info tab in the side window, if you already have a concept selected.
The selection info shows the name of the currently selected concept, its type, as well as the description and any other metadata. If this concept is used in any views, there will be a list of referencing views shown here. You can open any referencing views directly by clicking their respective names.
If the concept you have currently selected is an element, the selection tab will list all connected relationships. Conversely, if the current selection is a relationship, there will be a table listing the source and target elements. You can select any connected concept by clicking its name in the table.
You can unselect a concept by selecting another concept, or by clicking the selected concept again.
Compare¶
In addition to viewing a model, the model explorer also has the capability to compare two models with one another. The model comparison allows you to see what has changed between versions of a model. This is useful e.g. when reviewing the changes made by a team member. Alternatively, you can use the comparison to review changes between an as-is and to-be scenario.
You can access the comparison in the same way as the model explorer, via the context menu for a model version or branch. Instead of ‘Explore’, choose ‘Compare’. This opens a window where you can specify the branch and version of the models that should be compared.
After choosing two models to compare, the model explorer will color elements and relationships in the model viewer to indicate differences. The view info section provides a legend for the colors used. Further, the navigation tree includes additional folders that organize the views based on whether or not they have changed.
Move branch¶
If you want to isolate a version of your model to make adjustments without affecting the original, you have the option of moving that version into another branch. Branching creates a separate version of the model that you can edit in a vacuum.
To create a new branch, click on Manage branches under the project ribbon. This will open the move branch view. Please specify an existing branch in the left drop-down menu.
Next to the right drop-down menu, click the plus button. Fill in the name of this new branch (which must be unique for the project), as well as a description, and click ‘Add’.
Finally, please provide a comment that describes the reason for the move. The comment section cannot be empty.
Alternatively, to move a branch to an existing branch, you can select the branch you want to move to from the right drop-down menu. When moving the branch, you will be prompted to choose which changes to keep. You can read more about how this works in the Conflict Resolution section.
Conflict resolution¶
Conflicts in your model may arise for a number of reasons. For example, you and a colleague may have made changes simultaneously. Alternatively, you may be attempting to move a model from one branch to another, where another model resides. If this happens, a pop-up appears prompting you to reconcile the conflict(s).
You can resolve the conflicts in your model under the conflict resolution section which is accessible via the project ribbon.
In the conflict resolution screen, you will be initially presented with a list of all uploads/moved branches which have resulted in conflicts. Click any set of conflicts to get started.
Once you have selected a conflict set, you will be presented with an overview of all conflicts found. You can now start resolving the conflicts.
Models4Insight provides several standard conflict resolution templates which help you to resolve your conflicts automatically. You also have the option to reconcile the changes manually.
For each conflict, you have the option to either apply the change from your new version, or to save the current state of the model in the repository. The changes you do not apply are subsequently ignored.
| Template | Description |
|---|---|
| Keep repository | De facto nothing changes |
| Replace repository | Replace the repository head with the new model or source branch |
| Union keep repository | In case of conflicts, keep repository changes |
| Union replace repository | In case of conflicts, replace the repository with the new model or source branch |
| Manual conflict resolution | Manually resolve each conflict |
By clicking any conflict in the overview, you will be presented with additional details about that specific conflict. Here you will also be able to resolve that conflict manually. The left column represents the current state in the repository. The right side represent the state of the new version. By clicking the button in either column you can choose which version to keep.
Once you have resolved all conflicts, or chosen a template, you can apply the conflict resolution to the repository by clicking the ‘Apply’ button at the bottom of the overview.
Project Settings¶
Available to: Maintainer and higher
Under project settings, you can configure various aspects of the project.
Project description¶
To edit the project description, change the text in the input box and click save. You should see the project description updated in the ribbon.
Delete project¶
Available to: Project Owner
This section allows you to delete the project and all associated models permanently from the repository. To do so, please hold the red ‘delete project’ button for 3 seconds.
Access management¶
The Members function below settings allows you to grant or revoke other users’ access to your project. The settings page displays a list of all users who currently have access to the project, along with their current permission level. There following permission levels are available:
| Permission Level | Description |
|---|---|
| Owner | Can access all project functions |
| Maintainer | Cannot delete the project, or assign new project owners |
| Contributor | Cannot access the project settings |
| Model User | Can retrieve models, but cannot commit new versions or move branches |
| Business User | Can access the model explorer |
To add a user, click the add user button. Provide the username, email or name of each member you wish to add to the project. This username needs to be valid. You will see a top selection of users matching the search criteria. You can add a user to your project by clicking the ‘Add’ button next to their name. Every new user is assigned the ‘Business User’ role by default. You can change the role of your users via their corresponding drop-down menu.
You can remove existing members of a project by hovering over the dots behind their name, and holding the delete button for a second.
Definitions¶
Archi¶
Archi is a free to use, open source editor for ArchiMate models. It can be downloaded on www.archimatetool.com.
Branch¶
A branch is a separate version of the model that you can edit in a vacuum. The initial model uploaded within the project is saved as the master branch. You have the option of cloning branches and merging them again.
Move branch¶
Moving a model into a new branch means creating an identical copy of your model that can be edited in isolation. If your project has two or more branches, you have the option to merge two of them into a single branch. Merging combines the versions from each branch into a new version of your model.
Project member¶
A project member is a user who has access to a project. This includes the creator of the project and any people they have granted project membership to. See section Add member on how to add people to your project.
Retrieve model¶
You can use the platform to download a version of your model as a file. These files can be used with the Archi editor to make changes to your model. To read more, please see Retrieve model.
Tracking information¶
Any model retrieved from the platform has tracking information associated with it. The tracking information helps us to keep track of the changes you and your team make to the model. You can view this information in Archi under the properties section. Do not change these properties.
Upload model¶
You can upload new versions of your model to the repository via the project homepage. To read more, please review Upload model.
Common Issues¶
If you run into any issues while using Models4Insight, please let us know via info@models4insight.com. We will be happy to assist you.
Models4Insight Platform¶
If you are having trouble uploading a model, make sure that:
- The comment section is not empty
- Your model is using the .archimate extension
If you are having trouble creating a branch, make sure that:
- The name of the new branch is not empty and unique for the project. The name should also not contain any special characters.
- The comment section is not empty
If you are having trouble moving your model between branches, make sure that:
- The source and target branch are specified
- The comment section is not empty
If you are having trouble adding new people to your project, please make sure their username/e-mail is spelled correctly
Data2Model User Guide¶
About Data2Model¶
Data2Model is a software as a service solution that allows the automatic generation of ArchiMate models from various data sources. Its intent is to enable a repeatable, automated workflow for people who would normally create models by hand, such as enterprise architects, information architects or business analysts. Data2Model integrates with the Models4Insight platform and repository for version management and model persistence.
This guide is intended to help you get started with Data2Model quickly. It describes the basic steps to turn data into a model, as well as the capabilities of the Data2Model tool.
Registration¶
If you are not already a Models4Insight user, you will need to register first. To do so, please visit www.models4insight.com and click the register button.
Clicking the register button takes you to the user registration page where you are asked to provide some personal information. Note: A username cannot use capital letters, special characters or double spaces.
Once you have filled in all the information, click on register. You will receive a verification email at the address you provided. You need to verify your registration before you can log in.
You should immediately receive an email from Aurelius Enterprise. The link within is valid for 5 minutes. Check your spam folder if you cannot find the email. If 5 minutes have passed, please click the re-send email button.
Login¶
All Models4Insight services use a single sign-on. This means you only need to log in once to use all services. If you are not already logged in, you will be prompted to do so when you initially visit Data2Model.
Installation¶
If you are a mobile user, or if you are using Chrome, you have the option to install Data2Model as an app on your device. This will add a shortcut to your home screen or desktop, and will allow Data2Model to run as a dedicated app/window. You will find the installation button in the navigation menu.
It is recommended that you install the app if you intend to use Data2Model regularly. You will not miss out on any functionality if you do not install or if you are using a different browser.
Workflow¶
The basic workflow for Data2Model is as follows:
- Choose a dataset and upload it for parsing
- Review the parsed dataset
- Define model extraction rules
- Extract a model from the data based on the rules defined
- Review the model
- If you like the generated model, commit it to the repository. If not, adjust the rules and try again.
Upload some data¶
The first step in generating a model is to choose the dataset you want to base the model on. Depending on the structure of your dataset, you may need to do some data preparation outside of Data2Model first. Data2Model supports datasets in the following formats:
- XLS
- XLSX
- CSV
- A list of flat JSON objects
When you first open Data2Model, you will be presented with a file upload page. Here you can provide your dataset as a file. You can either drop the file into the striped area, or you can click the ‘Choose a file’ button to browse for the file.
Once you have selected the file, click the ‘Submit File’ button. This will upload your file to the Data2Model server for processing. A progress bar will pop up to indicate that the server is still busy. When processing is completed, you will be moved on to the next step.
Review the data¶
Next, you will be shown the result of the data processing. The page contains a table, where each row should mirror a row/object in your original dataset. The data shown here is the data from which a model will be extracted. Please check whether the processed data matches your expectations. When you’re done, please move on to the next step.
Define extraction rules¶
Data2Model uses rules to define which elements, relationships and views it should extract from your dataset. This rule-based approach provides a couple of key benefits:
- A relatively small set of rules can be applied to generate a complex model from a large dataset.
- Rules enable an incremental modelling workflow, where you tweak the rules to improve the quality of the model.
- Rules can reflect your organization’s modelling conventions, and they can be used to uniformly apply these conventions.
- Rules can serve as provenance of model concepts and views.
- Rules can be reused in case of e.g. a time-series dataset that is updated over time.
- Rules can be shared with colleagues.
Since every dataset is different, we ask that you define these rules yourself. There are 2 primary ways of defining rules in Data2Model:
- Easy mode: Define rules from suggested relationships based on the structure of your dataset. This approach provides more guidance and creates extractor rules automatically.
- Expert mode: Define rules completely manually using the rule editor. This approach gives you more control at the cost of more complexity.
The next chapters explain each approach in more detail.
Building a model in easy mode¶
To get started building a model in Easy mode, please navigate to the suggestions tab.
When you open the suggestions tab, you will be presented with a set of suggested relationships grouped per ArchiMate relationship class, these being:
- Dynamic relationships: Relationships which describe temporal dependencies between elements within the architecture.
- Structural relationships: Relationships which represent the static coherence within an architecture. These include composition, aggregation, assignment and realization.
- Other relationships: Relationships which do not fall into either of the above categories. This includes dependency relationships and composite relationships.
You can switch between suggestions for the given relationship classes using the respective tabs on top of the suggestions table.
For every suggested relationship, the names of the columns representing the source and target elements are given. To get started defining rules for a relationship, click its respective row in the table.
When selecting a suggestion, the associated element, relation and view rules are generated automatically.
After selecting a suggestion, the model builder and model preview appear below the suggestions table.
The model builder allows you to customize the generated rules. You can select a type for the source and target elements, as well as for the relationship itself. Note that if there already exists an element rule which corresponds to the same column as the source or target columns, the type of the element will be inherited from this rule.
If you want to turn around the relationship to point from target to source, rather than from source to target, you can click the green button next to the relationship type field. You can also select a name for your relationship, which will appear as a text above the arrows, if your dataset contains suitable values.
Finally, you can customize the views that will be generated for the relationship. You have the option to:
- Group views by source column,
- Group views by target column, or
- Add all generated elements and relations into a single view
Whenever you change an aspect of your rules, the model preview will update to show you what the resulting model would look like based on a small subset of your data.
Building a model in expert mode¶
To get started building a model in Expert mode, please navigate to the rules tab.
The rules overview presents your current ruleset categorized by elements, relationships and views.
To add a new extractor rule, click the ‘add a rule’ button at the top of the overview. This will open a side window, where you can define rules for elements, relationships and views. If you need to reference your dataset while defining the rule, you can switch back and forth to the data overview while the rule definition screen stays open.
For elements, the following configurations are available:
| Field | Description |
|---|---|
| Rule Name* | A descriptive name for the rule |
| Rule Description | A short description of the intention of the rule |
| Is Active* | Whether or not the rule is currently enabled for the extractor |
| ID Key | The name of the column that uniquely identifies this element |
| ID Prefix | A namespace for when the same ID is shared between multiple elements |
| Name Key* | The name of the column that contains the name of this element |
| Name Prefix | A namespace that is added in front of the element name |
| Attribute Mapping | Columns that should be added as attributes to the element |
For relationships, the following configurations are available:
| Field | Description |
|---|---|
| Rule Name* | A descriptive name for the rule |
| Rule Description | A short description of the intention of the rule |
| Is Active* | Whether or not the rule is currently enabled for the extractor |
| ID Key | The name of the column that uniquely identifies this relationship |
| ID Prefix | A namespace for when the same ID is shared between multiple relationships |
| Source Element* | The rule which defines the source of this relationship |
| Target Element* | The rule which defines the target of this relationship |
| Name Key* | The name of the column that contains the name of this relationship |
| Name Prefix | A namespace that is added in front of the relationship name |
| Attribute Mapping | Columns that should be added as attributes to the relationship |
Finally, for views, the following configurations are available:
| Field | Description |
|---|---|
| Rule Name* | A descriptive name for the rule |
| Rule Description | A short description of the intention of the rule |
| Is Active* | Whether or not the rule is currently enabled for the extractor |
| ID Key* | The name of the column that uniquely identifies this view |
| ID Prefix | A namespace for when the same ID is shared between multiple views |
| Name Key* | The name of the column that contains the name of this view |
| Name Prefix | A namespace that is added in front of the view name |
| Path | Where the view should be placed in the folder structure of the model |
| Layout* | The type of layout that should be applied to the view |
| Attribute Mapping | Columns that should be added as attributes to the view |
| Elements | The rules which define the elements that should be added to this view |
| Relationships | The rules which define the relationships that should be added to this view |
* = required
When you’re done defining a rule, press the ‘save’ button at the bottom of the rule definition screen. This empties out the form and adds a new rule to rules overview. If you just want to clear out the form without saving the rule, hit the ‘clear’ button instead.
To edit an existing rule, or to simply view its details, click any rule in the rules overview. This will open the rule definition screen for the selected rule. You can now make changes to this rule, use this rule as the basis for a new rule, or delete the selected rule. To overwrite an existing rule with your changes, press the ‘save’ button. To save a new rule based on your changes, press the ‘save as’ button. To delete a rule, press and hold the ‘delete’ button for 1 second.
When you have created multiple rules, it could be that some rules conflict with others. If this is the case, the rules overview will indicate this with an icon next to the conflicting rules. When you hover over the icon, there will be an indication of what is going on. Some conflicts will prevent you from extracting a model until you have resolved them.
We recommend saving your rules when you are done defining them. To do so, press the ‘save rules’ buttons at the top of the rules overview. This brings up a window where you can give your ruleset a name. Hit the ‘save rules’ button at the bottom of this window to download a file containing all the rules you have defined.
To load a set of rules you previously saved, press the ‘load rules’ button at the top of the rules overview. This brings up a file explorer window which you can use to locate your ruleset.
When you are satisfied with your current set of rules, and the rules are not conflicting with each other, you can press the ‘extract model’ button to extract a model from the dataset based on the rules you have defined. This sends your rules and data to our server, where a model will be generated. This might take a while depending on the complexity of the model. A progress bar will indicate the current status. Once the extraction is completed, you will be moved to the final screen.
Review the model¶
When model extraction is complete, you can review the generated model in the model explorer. Here you can see all the views that have been generated by the extractor.
Model view¶
In the dropdown at the top of the page, you can choose which view you would like to display. After selecting a view, it will become visible in the area below. You can zoom and pan the view. You can reset the view to its original position by clicking the reset zoom button. When you click a concept, its associated data will be shown. Additionally, you can toggle the full screen button to hide the other elements of the explorer.
Concept data¶
Whenever you click on a concept in the model, the concept data section shows its associated data. The selected concept receives green outline. To unselect, press the concept again. You can also select the relations. If no data is available for the selected concept, a ‘no data’ message is displayed instead.
Filter¶
You can use the filter to the left of the model view to find a specific view you may be looking for. This narrows down the list of views in the dropdown menu. You have the option of searching for a view by name. You can also use the organization structure of the model itself to narrow down your selection further.
After reviewing the model, you can either choose to commit the model to the repository if you are satisfied with it, or to alter the rules and extract another model to improve the quality of the extraction result.
Saving the model¶
To commit the model to the repository, hit the ‘save model’ button at the top of the model explorer. A window will open which allows you to specify the project to which the model should belong. Once you have selected a project, the available branches will automatically be loaded. Please select either an existing branch from the dropdown menu, or enter a new branch name to create a new branch for the model. Next, please select a conflict resolution template which will be applied in case of a conflict with the previous version of the model. At the moment, it is not possible to resolve these conflicts manually.
| Template | Description |
|---|---|
| Keep repository | De facto nothing changes |
| Replace repository | Replace the repository head with the new model or source branch |
| Union keep repository | In case of conflicts, keep repository changes |
| Union replace repository | In case of conflicts, replace the repository with the new model or source branch |
Finally, please enter a description of the extracted model.
When you are done, please hit the ‘Save’ button at the bottom of the window to save the model to the repository. A progress bar will be shown to indicate the status of the commit.
Alter the rules¶
If you are not satisfied with the extracted model, you can go back to the rules overview to edit your rules. The extracted model remains available for reference.
I have extracted a model, what’s next?¶
After committing a model to the repository, it becomes part of your project. It is then accessible via the Models4Insight platform. Typical use cases from this point on include downloading the model for manual edits, or merging the extracted model with an existing model to assemble a complete architecture of your organization.
Models4Insight Consistency Metrics User Guide¶
About Consistency Metrics¶
Models4Insight Consistency Metrics is an analytics software as a service solution to assess the quality of an ArchiMate model by automatically generating a quality assessment report called consistency metric report. Quality of an enterprise architecture model in the context of this service is based on a set of architecture modeling guidelines and reports the compliance of the actual enterprise architecture model (EA model) with these guidelines.
Please note that the consistency of an EA model does not reflect whether or not the enterprise architecture model completely represents the modeled environment. Rather, it reflects whether the EA model that has been constructed adheres to agreed upon best practices structurally.
This guide is intended to help you get started with Models4Insight Consistency Metrics quickly. It describes the basic steps from generating an architecture model quality report, to taking action to improve your architecture model. To be able to apply a consistency check to your EA model, you must have a model uploaded in the Models4Insight Platform.
Key concepts¶
The basis of the quality report are the best-practice architecture modeling guidelines. You can read more about these architecture modeling guidelines here <ADD A LINK TO THE GUIDELINES DOCS>.
The Models4Insight Consistency Metrics application allows you to easily check the degree to which your enterprise architecture model adheres to these guidelines. It generates a report which lists all cases where your model does not conform with the guidelines in some way. Such a case is called a consistency metric non-compliance condition. Please note that some of these conditions are applicable to multiple architecture modeling guidelines and therefore are described as consistency metrics related to an architecture modeling guideline.
For every non-compliance condition, the report contains detailed information about the non-compliant EA model concepts as well as a summary of the checks performed. This summary contains information about the amount of compliant and non-compliant concepts, as well as the number of exemptions.
An exemption can be made for a non-compliance condition, of which an architect has determined that it is an intended violation of a best-practice EA modelling guideline. Exemptions are made on an individual concept basis, and apply only to a single consistency metric. Thus, while the EA model may still deviate a particular modelling guideline, the non-compliance conditions for which exemptions have been made will not show up in the report.
Models4Insight Consistency Metrics integrates with the Models4Insight platform and repository for version management and model persistence. Every version of an EA model stored in the repository can be assessed using the consistency metrics service.
Registration¶
If you are not already a Models4Insight user, you will need to register first. To do so, please visit www.models4insight.com and click the register button.
Clicking the register button takes you to the user registration page where you are asked to provide some personal information. Note: A username cannot use capital letters, special characters or double spaces.
Once you have filled in all the information, click on register. You will receive a verification email at the address you provided. You need to verify your registration before you can log in.
You should immediately receive an email from Aurelius Enterprise. The link within is valid for 5 minutes. Check your spam folder if you cannot find the email. If 5 minutes have passed, please click the re-send email button.
Login¶
All Models4Insight services use a single sign-on. This means you only need to log in once to use all services. If you are not already logged in, you will be prompted to do so when you initially visit Models4Insight Consistency Metrics.
Installation¶
If you are a mobile user, or if you are using Chrome, you have the option to install Models4Insight Consistency Metrics as an app on your device. This will add a shortcut to your home screen or desktop, and will allow Models4Insight Consistency Metrics to run as a dedicated app/window. You will find the installation button in the navigation menu.
It is recommended that you install the app if you intend to use Models4Insight Consistency Metrics regularly. You will not miss out on any functionality if you do not install or if you are using a different browser.
Workflow¶
The basic workflow for Models4Insight Consistency Metrics is as follows:
- Choose an enterprise architecture model for which you want to make a quality report
- Generate for the selected enterprise architecture model a consistency metric report
- Review the consistency metrics non-compliances
- Make changes to improve your enterprise architecture model based on the results of the consistency metrics analysis
- Commit your improved enterprise architecture model to the Models4Insight repository via the Models4Insight Platform
- Run the analysis again to see how the quality of the enterprise architecture model has improved
The remainder of the guide below will take you through each of the above steps in detail.
Choose an enterprise architecture model¶
The first step in generating an consistency metric report is to choose the enterprise architecture model on which the report will be based. The model must be selected from the Models4Insight repository, thus three pieces of information are needed to specify the enterprise architecture model:
- To which project the enterprise architecture model belongs
- To which branch the enterprise architecture model belongs
- For which version of the enterprise architecture model you want to generate a report
When you first open the Models4Insight Consistency Metrics application, you will see the ‘Generate a report’ page.
On this page, you are first asked to select the project to which your enterprise architecture model belongs. The select box shows the names of the projects to which you have access. You can see more details by clicking the search button next to the select box.
After choosing a project, the application will present the branches which belong to this project. Please select the branch to which your enterprise architecture model belongs. Again, if you need more information about the branches, click the search button next to the select box.
After choosing a branch, the versions of the enterprise architecture model which belong to this branch will be presented. Finally, you need to select the version of the enterprise architecture model for which you want to generate the consistency metrics report. The list will be sorted in decreasing order of the upload date of the enterprise architecture model. Details for each enterprise architecture model version are available by clicking the search button.
Generate the report¶
After choosing an enterprise architecture model version, the ‘Generate report’ button at the bottom of the page will light up. When you click this button, you will be redirected to the consistency metrics report page for the enterprise architecture model you have selected.
You can share the URL for the consistency metrics report you have generated with anyone who has access to the same enterprise architecture model version.
Review the consistency metrics report¶
Once you have selected an enterprise architecture model and generated a report, you can now browse through the related consistency metric report to learn about the consistency of your enterprise architecture model.
On the left side of the page is a table of contents which shows all available consistency metrics and their grouping into different consistency metric categories. These metrics are:
| Metric | Category | Description |
|---|---|---|
| Actor Role Assignment | Pattern | These relationships are not assignment between business actors, business roles and business processes, thus non compliant |
| Copy Text | Textual | These elements were copied but still include “(copy)” in their label |
| Cycles | Pattern | The set of elements connected via aggregation or composition relationships that form a cycle |
| Equipment Facility Assignment | Pattern | These relationships are not assignment between equipment and facilities, thus non compliant |
| Facility Structure | Pattern | These relationships are not aggregation/composition/realization between facilities and facilities, thus non compliant |
| Process Event Flow | Pattern | These relationships are not triggering between events and processes of the same type, or events and junctions, thus non compliant |
| Process Junctions | Pattern | These relationships are not triggering/aggregation/composition between similar-type processes or triggering/flow between processes and junctions, thus non compliant |
| Process Trigger Flow | Pattern | These elements connect to multiple in- or outgoing, flow or trigger relationships |
| Sentence | Textual | The names of these concepts are not structured as a sentence |
| Single Trigger Flow | Pattern | These process steps trigger other process steps at different abstraction levels in the model |
| Tree Property | Pattern | The child elements connect via aggregation or composition to more than one parent, and thus violates the tree property |
| Trigger Context | Structural | These process steps trigger other process steps at different abstraction levels in the model |
| Unconnected Elements | Structural | These elements are not connected to any other elements |
| View Based | Structural | These elements are not used in any ArchiMate Views |
By clicking on each of the consistency metric categories (the blue headers), you will get an overview of all underlying consistency metrics and a summary of their results. By clicking on a specific consistency metric in the table of contents, you will see the detailed results for that metric specifically.
When you first open a consistency metric, you will see a table listing all concepts in the model which do not comply with the consistency metric conditions. For every concept, the table will show what has been determined to be the non-compliance. Now you have three options:
- You try to solve the non-compliance by modifying the enterprise architecture model
- You create an exemption for this specific non-compliance, thus, this non-compliance will not be shown in a new version of the consistency metrics report
- You ignore the non-compliance without creating an exemption, thus, this non-compliance will be presented in a new version of the consistency report
The section ‘Improve your model’ covers how to solve a non-compliance by modifying the enterprise architecture model. In the following the management of exemptions is discussed.
Exemptions¶
There may, however, be reasons why you do not want to change your enterprise architecture model. For example, the consistency metrics check marks the name MES, which stands for Manufacturing Execution System, not compliant for concept labels. However, the abbreviation MES is a technical term, which all users of the model recognize and would write the same way. In this case, you make a conscious decision to deviate for this concept name from the architecture modeling guidelines and therefore add an exemption for the MES concept. As a consequence, the MES concept will no longer be recognized as a non-compliance for the naming of concepts metrics.
You add an exemption by clicking the ‘add exemption’ button. A window will open, asking you to provide some details on the exemption.
You need to choose whether to exempt this case from the check for this version of the enterprise architecture model, for the branch the project, or for the entire project:
| Exemption Scope | Description |
|---|---|
| This project | This exemption should apply to the whole project |
| This branch | This exemption should apply to the current branch |
| This version | This exemption should apply to the current version |
Once you have selected a scope, you need to add a short description of why you have made the exemption. Afterwards, click ‘Save’ to save the exemption, which will also close the window.
You can see the exemption that you have created, along with any other ones that apply to the current metric, by looking at the ‘Exemptions’ tab. Here, you can edit the exemptions you have created, or delete them.
Improve your enterprise architecture model¶
If you have found a non-compliance which you want to resolve, the next step is to change the enterprise architecture model accordingly. If you have not yet downloaded the model, you can do so now by hovering over the three dots on the top of the consistency metrics report page and clicking ‘Retrieve the model’.
Next, open your enterprise architecture model in Archi.
Finding the right concept in the model¶
Once you have opened the enterprise architecture model, you need to find the concept in the model to which the non-compliance belongs. The report shows an ID for every non-compliance. This ID corresponds with a concept in the enterprise architecture model.
To find the right concept in the enterprise architecture model using the concept ID, you can use the Archi search function. First, copy the concept ID from the report to your clipboard. You can do so by clicking the copy button in the corresponding row.
Next, open the model browser in Archi. This is typically the left-most section of the window. It shows the folder structure of your model, along with all the concept and views in it. At the top of this section is a search button that has a looking glass icon. Click this button to open the search bar.
To the left of the search bar is a button that allows you to specify what you are searching for. You need to tell Archi that you are looking for a concept ID. To do so, make sure the ‘properties -> propidIEAIdentifier’ setting is enabled. An enabled setting has a check-mark next to it.
Once you have enabled the correct search option, you can paste the concept ID from your clipboard to the search bar. Now Archi will show the concept in the model that corresponds with the given ID. This can be an element, a relationship, or a view.
Fixing the issue¶
Once you have found the right concept, you can now make changes to your enterprise architecture model to fix the non-compliance.
To begin, select the concept in the Archi model browser to bring up the ‘Properties’ section on the bottom of the window. This section allows you to already change basic properties such as the name of the concept, and also allows you to find related elements ,relationships and views.
To find out which elements, relationships and views are related to the concept, open at the analysis tab.
This tab has a ‘Used in views’ section which lists all related views. Double click the view name in the table to open it.
For enterprise architecture model elements, the analysis tab also has a ‘Model relations’ section which allows you to drill down on the connected relationships.
The required changes dependent on the consistency metrics reporting the non-compliance. Some suggestions are provided in the detailed documentation of the individual metrics.
Fixing the next issue¶
Once you are done fixing a non-compliance, you can move on to fixing the next non-compliance, following the same steps as described above. Repeat this until you have no more non-compliances left, or you are otherwise satisfied with the non-compliances you have fixed.
Commit your changes¶
Once you are done making changes to your enterprise architecture model, you can commit it to the Models4Insight repository via the Models4Insight Platform. Open the project to which your enterprise architecture model belongs. You can open your project easily by hovering over the tree dots at the top of the report page, and clicking ‘Open the project’.
Next, commit your model via the ‘Upload a model’ tab. If you are committing to an existing branch, you will be asked to resolve conflicts with the previous version. By choosing the ‘upload only’ conflict resolution template, you apply all the changes you have made to solve the non-compliance issues.
Create a new consistency metrics report¶
To see the effect of the changes you have made, you can generate another consistency metrics report on the new version of the enterprise architecture model you have committed. It is possible that your changes had unintended ripple effects in the enterprise architecture model. The consistency metrics report will help you figure these out.
To generate the new report, follow the steps as described above, but now select the new version of your enterprise architecture model on the ‘Generate a report’ page.