"ArchiMate language customization" Project - archimatetool/archi GitHub Wiki

Context

The projet ArchiMate language customization (specialization and custom notation) has been launched in 2021 to support language customization as described in the specification.

It borrows ideas from and should cover or replace:

Requirements

Language customization in Archi should cover:

Core features

Definition of profiles. in ArchiMate, a profile is a named set of properties that can be then applied to any kind of concept. Profiles are often used to centrally manage sets of properties with a common goal. For example, one could define a "Cost" profile containing two properties "One-time Cost" and "Running Costs" and apply them to elements used to model company assets such as servers, applications, facilities... You can also see profiles as name spaces for properties. This requirement has been removed from the MVP which focuses on specialization profiles only.
Definition of specialization. In ArchiMate, a specialization is a new type of concept (element or relationship) forked off a native ArchiMate concept type. Even though the word is the same, this is not related at all to specialization relationship. Specialization relationships are used inside your model (e.g. to model that both Prospects and Customers are both Third Parties) while specialization mecanism is used outside your model but inside your tool (e.g. to make it possible for you to use a new element type "Database" which inherits from "Artifact"). A specialization is a special kind of profile and this can come with a set of properties.
Custom icon for specialization. The most basic notation for specialized concepts uses the guillemet notation (add "<< specialization_name >>" to the concept label on views), but it is usually better to make it more explicit by replacing the default ArchiMate icon that most elements show on their top right corner. When a custom icon is set in the specialization definition, it should be used by default for "instances" of this specialization (ie. concept of this custom type).
Custom Image in views. For communication purposes, it can make sense to complement or replace the default notation by using custom, arbitrary images. This feature should make it possible on a per view basis (i.e. using a custom image inside an element in a view has no impact on other views that use the same element).

Complementary features

User Guide
Model import feature. Importing a model inside another model should also import profiles/specialization definition. A profile/specialization definition should be identified by its name and the type of concept targeted.
Jasper Report. Wherever we show concept type, we should add the specialization name inside parenthesis in the same field (better not to lose some screen real estate by adding another column).
HTML Report. I suggest to add the specialization name inside parenthesis after the concept type in "Elements" and "Relationships" tabs of views pages, but to add a dedicated line showing the specialization name in elements and relationships pages (similar to relationships' source and target)
HTML Report (query engine). Add a "specialization" column in tables "Elements" and "Relationships". Maybe also add a "Profiles" table listing profiles with a boolean flag to know if they are specializations or not. This table could later contain the profile/specialization documentation.
CSV export/import.. A Specialization column should be added on elements.csv and relations.csv. This columns should be the last one (in case someone uses the columns order) and should contain the name of the specialization of the element or relationship (or an empty string if none defined).
Copy/Paste (inside same or different models). Can be splitted in several categories:
- Same model. Everything (reference to specialization and custom image) should be copied.
- Different model, no specialization. Custom image (if any) should be copied.
- Different model, specialization used. In this case we might accept in the MVP that specialization and its image are not copied into the target model (a possible workaround would be to use model import). It would be nice in the future to let the user decide what to do (don't import specialization, use only specialization that already exist with the same type/name in the target, import all specializations needed). **Note:" using specializations if they exist in target model will be needed for toolbox support.
Format Painter. The format painter should take care of applying custom image (not specialization image) to target visual object (in same or different model).
Label Expression. First level of support (for MVP) is to add a new ${specialization} expression that returns the name of the specialization. Other helper expressions (e.g. ${if(condition:string} and ${if:condition:string:string}) may be needed to support some use-cases (such as adding the guillemet notation only if a specialization is defined).
jArchi API support: (note: profiles, specializations and images are not similar to other objects and thus should not be manipulated through collection as no usual methods would apply. But they should all have a type attribute and a delete() method like all other objects)
- model.createImage(data) where data is the base64 representation of an image to add (which format?). Returns the newly created Image object. An Image object is a (read-only?) structure with two attributes: id (String) and data (base64 representation of image data as String). Note: another option is to use the image filename instead of base64 data. Implementation should make sure we don't create duplicates and return an already existing image object if the image is already known.
- model.createSpecialization(specializationName, type, image) where type is the name of the concept type this specialization extends, and image is an Image object. Returns the newly created Specialization object.
- model.specializations should return the list of Specializations objects. A Specialization object is a read-only structure with three attributes: name (String, no null), type (String, not null) and image (Image object, could be null).
- Elements and relationships should have a new String attribute named specialization. Reading this attribute returns the specialization name (or null if none defined), setting this attribute to a string sets the specialization (or unsets it if null).
- Visual objects should be updated to enable access to new, image related, attributes, such as:
  - showIcon (only for ArchiMate related objects), with new constants defined: SHOW_ICON.ALWAYS, SHOW_ICON.NEVER and SHOW_ICON.IF_NO_IMAGE)
  - imageSource (only for ArchiMate related objects), with new constants defined: IMAGE_SOURCE.SPECIALIZATION and IMAGE_SOURCE.CUSTOM
  - image, returns/sets the (custom for ArchiMate related objects) image
  - imagePosition, with new constants defined: IMAGE_POSITION.TOP_RIGHT, IMAGE_POSITION.TOP_CENTER...

Status update

2021/08/23

Most of the work has been tracked through issues #705 and #704

Features implemented to date:

Definition of specialization

It is now possible to access a new Specialization Manager from the Tools menu:

Once defined, it becomes possible to set the specialization on an element or relationship through the new "Specialization" field in the properties tabs. Note that you can also access the Specialization Manager through the "tree dots" button on the right of the "Specialization" field:

Custom icon for specialization

When a specialization has been set on an element, the default ArchiMate icon (on the top right corner) is replaced by the specialization's image if one has been defined in the Specialization Manager.

Custom Image in views

In all cases, a new "Image" property tab has been added:

It works as follows for ArchiMate elements:

Show Icon makes it possible to show/hide the original ArchiMate icon associated with the "native" element type. possible values are: Always, Never and If no image defined. This last value (which is the default one) will make sure that, by default, only the specialization image is visible if one has been defined in the Specialization Manager.
Image makes it possible to define which image should be used: either the one coming From Specialization, or a Custom one.
Custom Image makes it possible to define the custom image to use (if Image has been set to Custom).
Position makes it possible to choose the location of the image inside the figure (default is top-right).

Non ArchiMate objects (e.g. visual notes) only have two options:

Image makes it possible to define the image to use.
Position makes it possible to choose the location of the image inside the figure (default is top-right).

Copy/Paste (inside same or different models)

Copy/Paste MVP has been implemented. In this version pasting a concept from another model will not import/set the specialization. This means that toolbox views cannot be used as they rely on another model.

Format Painter

The format painter now also apply custom image (not specialization).

Label Expression

It is now possible to reference the specialization's name through ${specialization}.

Jasper Report

Jasper Report now exposes specialization.

HTML Report

HTML Report now show the specialization next to concept type in tables and in a dedicated line in concepts' details:

Embedded Alasql database now includes a new 'specialization' column in tables Elements and Relationships:

Related Public Releases

Archi 4.9 EA 2 (August 17 2021)

Fixes

Some figures shouldn't use an icon offset for text position when the position is right/top

Archi 4.9 EA 1 (August 6 2021)

New Features

[Specialization] Add "${specialization}" label expression
[Model Importer] Add support for Specializations (this aspect is a work in progress, subject to change)

Fixes

Optimisations and fixes for Specialization/Profiles

Archi 4.9 Alpha 4 (June 30 2021)

New Features

[Specialization] Can set a concept as a Specialization
[Specialization] Add Specialization Manager to manage Specializations and associated icons/images
[Specialization] Can add images/icons to all objects
[Specialization] Can hide ArchiMate icons if image is shown
[Specialization] Add "Fill" option for images
Added a "Match Size" command to match height and width of selected objects