Imprint Privacy policy Terms & Conditions Sitemap

Enterprise Architect

The ANALYZE 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 itemis ANALYZE, ANALYZE ships an EA plugin which is described below.

Data access

Configuration

Open the ANALYZE configuration with the ANALYZE 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 relevant files ( .eap, .eapx, .qea, .qeax) for analysis.

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, ANALYZE takes all .eap files residing in requirements folder in project com.itemis.analyze.mt.spec.

When you first start ANALYZE with the adapter enabled, a dialog will ask you for a user name and password if the EA resource is authenticated. You can store this information in Eclipse’s Secure Store such that you don’t need to re-enter it later.

You can also provide the login credentials as java system properties EA_LOGIN_USER_NAME and EA_LOGIN_PASSWORD. You can set these properties either directly via the the command line or in a configuration file that you specify with ANALYZE’s --properties command line option (see Executing itemis ANALYZE in batch mode ). Alternatively, you can define environment variables with the same names.

Enterprise Architect plugin for selection propagation

Installing the EA plugin

In order to receive notifications about selection changes from Enterprise Architect, ANALYZE ships a plugin for Enterprise Architect. Please note that there are some limitations for .eap files that actually reference a database.

To install this plugin, proceed as follows:

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

Configuring the EA plugin

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

ANALYZE:

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

EA:

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

Access models in databases

Supported for EA models stored in a database depends on the database. In the enterprise architect mssql databases are supported natively. For this database a link file with credentials can be used by the EA and the adapter at the same time. Starting with EA, the artifacts can be opened and selected by ANALYZE and the selection in EA is recognized in the same extend as of local files. Beside the EA link files the EA Adapter is based on the YAKINDU EA Bridge which supports .mssql.eap files. These files are property files containing the connection details and can also connect to other databases which the EA supports via ODBC only.

The mariaDB database is supported by the adapter and must be configured in the EA via ODBC database access. In this case the connection details are not stored in the link file of the EA and must be defined on each machine, were the data should be loaded. For mariaDB we support the .mariabd.eap property file only, which can not be opened by the EA directly. Because of this, we do not support selection propagation in both directions.

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 ANALYZE 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 ANALYZE. 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 itemis ANALYZE → Adapters is checked, ANALYZE will open Enterprise Architect artifacts within Enterprise Architect. If that checkbox is unchecked, ANALYZE 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 ANALYZE configuration with the ANALYZE 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
  • include element if( CONSTRAINT ) – Additional constraints for candidates matching the subsets. Constraints are in the form of EXPRESSION OPERATOR VALUE with an expression like valueOf, an operator from below and the expected value (or values in braces). Constraints can be concatenated and the default concatenation is the logical and.
    • contains – Operator for substring check
    • contains_not – Operator for absence of a substring
    • == – Operator for equality check
    • != – Negotiation of the equality check
    • in – „In” operator to use within a condition. The operator will match if the value of the left operand is equal to one of the values in the right operand.
    • not_in – Negation of „in” operator to use within a condition. The operator will match if the value of the left expression is not equal to any of the values.
    • (…), &&, AND, ||, OR – Grouping or concatenation of constraints
  • name – Expression to build the artifact names
  • noteOfValue – Refers to a note of a tagged value of an EA element or connector
  • parent.attribute, parent.valueOf, parent.noteOfValue – Refers to the corresponding values of the parent.
  • 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 and noteOfValue 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
  • BaseGUID – For "Part"s and "Port"s the GUID of the base element (like where it’s inherited from).
  • CreationDate – The creation date of the element. The format is YYYY-MM-DD HH:MM:SS.
  • Constraints – Comma separated list of all constraints specified for an 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
  • ModifiedDate – The last modified date of the element. The format is YYYY-MM-DD HH:MM:SS.
  • 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. ANALYZE 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. The Enterprise Architect supports muliple tagged values with the same name, which are not visible in the UI by default. These values are concatenated and separated by a comma if mapped to an attribute.

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. 

subset metatype "Class"
include element if (
  attribute ("QualifiedName") contains "::Software Engineering::"
  AND (
    valueOf ("ASIL") == "A"
    OR valueOf ("ASIL") == "B"
  )
)
map {
	asil to valueOf ("ASIL")
}

Only Classes which are in a package „Software Engineering” and have ASIL A or ASIL B. The ASIL level is also mapped to an attribute.

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

ANALYZE 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 ANALYZE configuration with the ANALYZE 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.
  • noteOfValue – Refers to a note of a tagged value of an EA element or connector
  • 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 ANALYZE 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 ANALYZE 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, ANALYZE 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 ANALYZE 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.
  • with stereotype … – An additional filter for connector or link target element stereotypes in Enterpsise Architect
  • 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

and can be extended to

link where role has connector_type with stereotype link_stereotype1, link_stereotype2 to element_type with stereotype element_stereotype1, element_stereotype2 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.

ANALYZE 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. If additional link or element stereotypes are provided, they must be set on connectors or elements..

For all of the latter EA elements, ANALYZE checks whether the value of the tag tag is equivalent to filter. Typically, filter refers to the link type’s other artifact type. ANALYZE 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 ANALYZE 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, ANALYZE 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, ANALYZE only creates a connection to it – starting from the EA element that is to be linked to the artifact. Otherwise, ANALYZE 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, ANALYZE 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, ANALYZE will ask you whether it should create that package in EA.

Example:

In this example, ANALYZE 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 ANALYZE, ANALYZE 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, ANALYZE will create a Realisation connection from the EA artifact to be linked to that Requirement. Otherwise, ANALYZE 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.

Eclipse Xtext IBM DOORS