Enterprise Architect

The YT adapter for Enterprise Architect provides access to UML elements as traceable artifacts. More than that, it is possible to derive trace links from UML relations.

Please note: Out of the box, Enterprise Architect doesn’t provide an interface for interprocess communication. To enable selection propagation from Enterprise Architect to YAKINDU Traceability, YT ships an EA plugin which is described below.

Data access

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Enterprise Architect as data access type.

Within the configuration panel, you may specify file patterns consisting of Eclipse projects, folders, or file name patterns describing the .eap files relevant for traceability.

Supported keywords:

  • resource – A pattern for a project, folder, or file in the workspace.

The configuration may contain several resource definitions.

Example:

In this example, YT takes all .eap files residing in project com.yakindu.yt.mt.spec, folder design into account.

Enterprise Architect plugin for selection propagation

Installing the EA plugin

In order to receive notifications about selection changes from Enterprise Architect, YT ships a plugin for Enterprise Architect. Please note that for Enterprise Architect version 10 or lower, there is a restriction preventing selection propagation for .eap files that actually reference a database.

To install this plugin, proceed as follows:

  • In a file explorer, navigate to folder /traceability/scripts/ea.
  • Run the script installAddInForEA.bat with administrator privileges.

Configuring the EA plugin

The EA plugin propagates selections from EA to YT via a TCP socket connection. To establish a socket connection, the same port has to be configured in both YT and EA.

YT:

Select Window → Preferences → YAKINDU Traceability from the main menu. Make sure the TCP Server is enabled. Configure a port number; the default is 1234.

EA:

Select Extensions → Yakindu Traceability → Configure Socket connection from the main menu, then set the port number.

Artifact type

The Enterprise Architect artifact type provides access to the elements and connectors of those EA models that are specified in the Enterprise Architect Data access.

It is possible to restrict the number of UML elements that are visible to YT based on their meta-type, their assigned stereotypes, or their namespace. You may want to see, e.g., only artifacts of type Class with the stereotype <<SafetyRelevant>> in the package safety.

This adapter supports opening the artifact in EA and showing the currently selected artifact in YT. However, this doesn’t work for connectors, because they can’t be displayed in the EA Project Browser.

If Enterprise Architect is not available, it is also possible to open an EAP file with the Eclipse UML2 editor. However, the UML2 model does not support all available Enterprise Architect features. If an element is not available in the UML2 model the artifact cannot be accessed without a native Enterprise Architect instance.

If the checkbox Show artifacts within Enterprise Architect on the preferences page YAKINDU Traceability → Adapters is checked, YT will open Enterprise Architect artifacts within Enterprise Architect. If that checkbox is unchecked, YT will open the artifact in the last editor you used to open an Enterprise Architect file. Selecting the artifact in an editor will work only if that editor is an Eclipse tree editor like the UML2 editor.

Currently, there is an issue regarding the selection of Enterprise Architect artifacts within the UML2 editor when error markers created by the YAKINDU EA Bridge exist for the file. In this case the selection can take very long and can fail if the editor is already open. You can prevent the YAKINDU EA Bridge from creating these markers via an option in the workspace preferences: On page YAKINDU EA-Bridge, uncheck the checkbox "Report loading errors as Resource markers for the eap-file". Now loading errors will still be shown in the editor’s Problems tab, but no markers will be created. Please note that this will not remove already existing markers.

Additionally, if such errors exist and if the UML2 editor is used to open EA artifacts, the editor will by default open on the Problems tab. This is the default behavior of the UML2 editor, but it may be confusing since it may look as if the file has failed to load. However, in order to properly display the model, you can manually switch to the editor’s Selection tab.

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Enterprise Architect data access in the Data access drop-down list.

Supported keywords:

  • subset metatype – Filter elements by metatype
  • subset namespace – Filter elements by namespace
  • subset stereotype – Stereotype filter
  • name – Expression to build the artifact names
  • map – Attribute mappings for custom attributes
  • valueOf – Refers to a tagged value of an EA element or connector
  • attribute – Refers to the value of a property of an EA element or connector

A list of available stereotypes and metatypes can be opened by content assist. Move the text cursor to the right of the metatype, leave at least one space, and press [Ctrl]+[Space]. Instead of explicitly specifying identifiers, you can also construct these identifiers by using complex string expressions. Within these, you can refer to attributes of EA elements via attributes keyword and tagged values via the valueOf keyword.

The attributes keywords supports a fixed set of parameters to access the values of different built-in attributes of elements and connectors in EA. Some of them are not available for all elements (or connectors).

  • Alias – The alias of the element
  • Author – The author of the element
  • Difficulty – The difficulty of the element, only available for requirements. It can be „high”, „medium”, or „low”.
  • GUID – The GUID (Globally Unique IDentifier) of the element
  • Keywords – The keywords field of the element
  • MetaType – The metatype of the element, i.e., the type of the element in EA
  • Name – The name of the element
  • Notes – The notes field of the element
  • Package – The fully qualified name of the package that contains the element. Hierarchy levels in the name are separated by " ::".
  • ParentGUID – The GUID (Globally Unique IDentifier) of the element’s parent
  • ParentName – The name of the element’s parent
  • Phase – The phase of the element
  • Priority – The difficulty of the element, only available for requirements. It can be „high”, „medium”, or „low”.
  • QualifiedName – The fully qualified name of the element. Hierarchy levels in the name are separated by " ::".
  • SignalGUIDs – Only available for StateFlows (i.e. Transitions): a comma-separated list of the GUIDs (Globally Unique IDentifiers) of all signals associated with triggers of the transition
  • SignalNames – Only available for StateFlows (i.e. Transitions): a comma-separated list of the names of all signals associated with triggers of the transition
  • SourceGUID – The GUID (Globally Unique IDentifier) of the connector’s source element
  • Status – The status of the element. YT returns a numerical code for this that corresponds to the selection in EA.
  • Stereotypes – The stereotype(s) of the element. If there are several stereotypes, they are comma-separated.
  • TargetGUID – The GUID (Globally Unique IDentifier) of the connector’s target element
  • TriggerNames – Only available for StateFlows (i.e. Transitions): a comma-separated list of the names of all triggers of the transition
  • TypeGUID – The GUID (Globally Unique IDentifier) of the element’s type
  • TypeName – The name of the element’s type
  • Version – The version of the element

While a stereotype definition requires the fully-qualified name (i.e., including the profile as shown in the example below), a simple name is sufficient for the metatype definition. When using the namespace filter, the individual names in a namespace hierarchy can be delimited either by " .", as shown below, or by " ::". The second variant is mandatory if any name in the fully-qualified name contains a " .".

Note that the configuration supports multiple usages of the same keyword. For example, using the expressions subset metatype Class and subset metatype State in the same configuration means „Class or State”.

The Enterprise Architect adapter supports mapping of artifact attributes to tagged values in Enterprise Architect. For instance, the expression map { attr1 to valueOf(tagKey1) } maps the attribute attr1 to the value of the tagged value with the tag tagKey1.

Example

The image above shows a configuration for the Example Model shipped with Enterprise Architect. It provides all classes with stereotype <<ERD_Entity>> and/or <<ERD_Attribute>>, residing in package Domain Specific Modeling of project Project Models.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

The trace links YT derives from an Enterprise Architect model are based on the Enterprise Architect data access and the Enterprise Architect artifact types configured for the Enterprise Architect adapter. The metatype and stereotype relations in the EA Model are available for mappings.

YT can derive trace links from an Enterprise Architect model in two ways. First, UML relations within the model can directly be interpreted as trace links. Second, trace links can be derived in cases where connected elements (e.g., requirements) of some element A reference other elements B within their tagged values. In this case, trace links from A to B can be inferred.

Open the YT configuration with the YT configuration editor, and add a new link type as described in section "Configuring a link type".

  • As at least one of A and B, select an Enterprise Architect artifact type with Enterprise Architect as its adapter. If you want to derive links from and to the same artifact type, choose this type both as A and as B.
  • As data access, select the very same Enterprise Architect data access that has already been assigned to the artifact types A and B.

For each mapping configuration only one of the two ways mentioned above for deriving trace links can be used. Since both cases are configured very differently, the following description considers them separately.

Supported options:

  • subset metatype – Meta-type filter
  • subset stereotype – Stereotype filter
  • valueOf – Refers to a tagged value of an EA element.
  • attribute – Refers to the value of a property of an EA element.
  • link source is A|B – Optionally specifies whether the link source in EA should be artifact A or artifact B of the link type. By default it is A, which means that a link in EA from an element X to an element Y will result in a link in YT from A to B. If you define the link source to be B, the same link in EA from X to Y will result in a link in YT from B to A.

A list of available metatypes and stereotypes can be displayed by content assist (pressing [Ctrl]+[Space] right from the space right from the metatype). The list of subsets is grouped by the subset type ( metatype and stereotype) and for each present group at least one subset has to match. Instead of explicitly specifying identifiers, you can also construct these identifiers by using complex string expressions. Within these, you can refer to tagged values of EA elements via the valueOf keyword. You can refer to attributes of EA elements by using the attribute keyword. For the possible parameters of this keyword, see the configuration options for the Enterprise Architect artifact type.

Example:

In this example, YT derives a trace link from each UML association existing in the EA model between artifacts that had been specified by type EA artifacts. Refer to this example for the Enterprise Architect artifact type to see how this type is specified.

Since the example configuration does not contain link source is ..., the default is assumed, which is link source is A. Therefore, the source of the association in EA will be artifact A of the link in YT and the target will be artifact B. If instead B was specified as link source, the source of the association would be B and the target would be A.

Supported options:

  • link where … – Defines which conditions must be fulfilled to derive trace links from the tagged values of connected elements.
  • has – Specifies which type of Enterprise Architect connector should be considered for deriving trace links.
  • to – Specifies to which type of Enterprise Architect element connectors must lead to be considered for deriving trace links.
  • with – Specifies which value the tagged value of a connected element must have such that a trace link can be derived.
  • create – Can be used to specify options for creating new links.
  • in – Specifies the package in which new Enterprise Architect elements representing new links should be created.
  • with name = – Specifies the name of newly-created Enterprise Architect elements that represent new links.
  • map – Defines a list of mappings allowing to store attribute values of linked artifacts in Enterprise Architect elements (see below).
  • … based on … to … – Defines a mapping from the values of custom attributes of B or A to a tagged value or an attribute of the Enterprise Architect element that represents the linked artifact in Enterprise Architect. Between based on and to, the string to store in Enterprise Architect can be formed by concatenating attribute values of A or B and static strings. The resulting string will be stored in a tagged value or attribute that can be defined in the to clause by using the keywords valueOf or attribute. The attribute value will be stored in the specified location when creating or updating the link. Left from based on, a custom string attribute of the configured Enterprise Architect link type must be specified. When reading a link from Enterprise Architect, this custom attribute will be set to the value that is read from the location specified in the to clause. When creating or updating a link, the custom attribute will be set to the value of the specified custom attribute of an artifact.
  • valueOf – Allows to specify the tagged value to store the specified string in.
  • attribute – Allows to specify the Enterprise Architect property to store the specified string in. The supported properties depend on the type of Enterprise Architect element that has been selected in the link expression after to. All target elements support Name, Notes and Alias. Furthermore, all elements except Operation and Attribute support Status, Author, Version, Keywords and Phase. Finally, if Requirement is selected, also Difficulty and Priority are available. Note that EA might not allow to set some properties to arbitrary strings, but only to certain values that are selectable in EA via a drop-down list. Other values are ignored for these properties.
  • join {…, …} using … – Can be used to create a composed string by concatenating several other strings with the string provided after using. The strings to concatenate are passed as a comma-separated list within the curly brackets. They can be complex strings concatenated by +, including references to artifact attributes. If any of these expressions evaluates to an empty string (usually because a referenced attribute is empty or undefined) it is ignored. The string after using must be a simple string.

The configuration for this type of configuration always begins with:

link where role has connector_type to element_type with valueOf( tag) = filter

Here, role (can be A or B) defines which of the link type’s artifact type should be considered for connected elements.

YT searches the EA model for connections with the EA connector type connector_type that lead from any EA element that is an artifact of the selected artifact type role to EA elements of element type element_type.

For all of the latter EA elements, YT checks whether the value of the tag tag is equivalent to filter. Typically, filter refers to the link type’s other artifact type. YT creates a trace link from the currently considered artifact of role to all artifacts of the second artifact type for which filter equals tag.

The expression filter is a concatenation of static strings and (meta) attributes of the link type’s second artifact type. This second artifact type is B if role is A, and vice versa. You can access an attribute attr of an artifact type B by using B.attr, the identifier of B by using B.metadata(Identifier), and the resource of B with B.metadata(Resource).

You can display a list of available meta types for connectors or elements by content assist (pressing [Ctrl]+[Space] right from the space right from has or to, respectively). Content assist right from valueOf( will provide a list of all tags of elements in the EA model. Content assist right from attribute( will provide a list of all attributes that are supported for writing.

In YT Editor, you can manually create links from EA elements to other artifacts. These will be stored in EA in the same form as described above, i.e., as a connection to an EA element with a tagged value that references the other artifact. Whenever a new link to an artifact needs to be created, YT first searches for an existing EA element that refers to the artifact via a tagged value in the form defined in the configuration. If such an element already exists, YT only creates a connection to it – starting from the EA element that is to be linked to the artifact. Otherwise, YT also creates a new EA element with a suitable tagged value, which will then be the target of the connection.

When creating a new EA element with a tagged value to reference another artifact, YT by default creates this EA element in the same package as the EA element to be linked. The name of the new EA element will be the same as the name of the referenced artifact. Both, the name of the new element and the package, can optionally be defined explicitly in the configuration. The general form of the configuration is the same as described above, followed by , create in package with name = element_name . Here, package is the package in EA (using :: as separator) to create the new element in. The expression element_name is the name of the EA element to create. It can be defined in the same syntax as the expression filter described above. Alternatively, the name can be defined by mapping the attribute „Name”. In this case, the name (like other mapped attributes or tagged values) will be updated when the link is updated or a new link is created to the element.

You can display a list of available packages to store new EA elements by content assist (pressing [Ctrl]+[Space] right from the space right from create in. You can also specify a new package that does not yet exist. If you do, YT will ask you whether it should create that package in EA.

Example:

In this example, YT considers for each EA artifact A of artifact type A all outgoing connectors of type Realisation that lead to a Requirement. It derives a trace link for each of these requirements with a tagged value Object Identifier that is equivalent to the expression B.ObjectIdentifier. In this case, the expression only consists of one attribute of B. If a new link is created in YT, YT will first search for an existing Requirement with a tagged value equivalent to the attribute ObjectIdentifier of the target artifact. If such a Requirement is found anywhere in the model, YT will create a Realisation connection from the EA artifact to be linked to that Requirement. Otherwise, YT will create a new Requirement in the package Project Models::Analysis and Business Modeling with a suitable tagged value Object Identifier.

The map specifies that several attributes of B are to be mapped to attributes and tagged values of the target requirement. The property Name of the new requirement will be created by composing the values of the three attributes number, heading, and ObjectIdentifier of B, separated by the static string " - ". The join keyword ensures that empty attributes are ignored in this concatenation and no superfluous " - " delimiters are inserted. The result is mapped to the link attribute Name. The property Notes of the requirement will be determined by the value of the custom attribute B.text, which is also mapped to the link attribute Description. The property Alias is mapped in a similar way. Finally, two tagged values, Variant and Created By, are set based on attributes of B.

Suspicious links validation is done by re-evaluating the link’s custom attributes and comparing these values to those stored in the link. If there are any differences, the link is suspicious.

Please note:

Enterprise Architect maintains internal and external links. For suspicious links validation, only external links are taken into account.