MatrixEx Add-In

The Extended Matrix (MatrixEx) Add-In allows you to see relationships between elements in packages or on a diagram, under various criteria. As Matrix view, you can see which elements are placed in diagrams, and relationships between elements and classifiers of the elements.

This page covers the following topics.

Features

The MatrixEx Add-In has more features than the built-in Enterprise Architect Relationships Matrix feature. The followings are part of the MatrixEx features.

Matrix Sources and Targets

  • Drag and drop a package from the Browse window as source or target
  • Specify a diagram as source or target, all elements in the diagram are displayed
  • Conditional search by element name, stereotype, or tagged value
  • Specify multiple element types and connector types

View

  • Tree view in the source side, semi-Tree view in the target side
  • Set diagrams as target to display placement of elements to each diagram (Example)
  • Display relationship between classifier of the element and elements placed within the element. (Example)
  • Display two-hop relationship between elements (Example)
  • Conditional row and column highlighting

Other Features

  • Locate source or target item in diagrams or the Browser
  • Export matrix image to the Linked Document
  • Customize target types of elements, connectors, etc. as you like via Ini file
  • Export matrix to Excel, RTF, HTML, etc.

and much more...

How to Use

After installing the Add-In, click the 'MatrixEx' button on the 'Specialize' ribbon, 'Add-Ins' panel. You need to open a project before opening MatrixEx view.

Just after applying a license newly, there is no 'MatrixEx' button in the Ribbon. Please restart Enterprise Architect.

How to Specify Criteria

Specify Source and Target

There are two ways to specify source and target.

  1. By specifying conditions in the Condition panel (In this page, we call this mode 'Basic Matrix')
  2. By dragging and dropping a package from the Browser window onto the Matrix column or row header. (In this page, 'D&D Matrix')

Mode 1 (Basic Matrix) and Mode 2 (D&D Matrix) cannot be used together. If you change the mode (i.e., specify Source or Target package in the Criteria panel or drag and drop a Package), the current information in the matrix will be cleared.

D&D Matrix

You can drag and drop a package from the Browser window onto the matrix. If you want to specify multiple packages, drag a package one by one.

  • Only packages can be dragged and dropped.
  • After specifying packages to source and target, you need to set Types of elements, Types of connectors, and Direction in the Criteria panel.
  • You can specify a package to source or target in the following rule:
    • When there is no package in the source or target, source or target is decided depending on whether the dropped position is closer to the left end (source) or the top end (target) of the matrix.
    • When there is (are) package(s) in the source or target, you can add a package by dropping on the column or row header.
  • When you drop a package which is already added in the column or row, the following rule will be applied.
    • When there is the same package and part of the sub-packages are hidden, the hidden packages will be shown again.
    • When the dropped package's parent package is already added, the dropped package will be added under the parent package.
    • When the dropped package's child package is already added, the child package will be moved under the dropped package.

You can use the context menu to hide part of rows and columns. You can also clear whole matrix contents via the context menu.

If you hide rows or columns, they will remain hidden even if you refresh contents or save as profile.

Criteria Panel

Specify criteria to display in the matrix as you want. Some Criteria can be set by dragging from the Browser window. (This option must be enabled.)

The following table is items in the Criteria panel. Some items work differently when you use 'D&D Matrix' mode.

Please take care, the 'Select All' option in some dropdown list does NOT mean any type, but all types in the selectable options. If you have no type you want, you need to modify the setting Ini file.

# Item Description D&D Matrix
Source side (vertical axis)
1 Target of Source side - Click to display a dialog to select a package or diagram
- When a package is selected, 'P' is displayed. When a diagram is selected, 'D' is displayed
- You can drag and drop a package or a diagram from the Browser window *
Not used
2 Type to display currently, fixed type: 'Elements'
3 Type(s) of Source elements - Two or more element types can be specified from this dropdown list
- You can specify a type by drag & drop an element from the Browser window *
4 Detail specification of Source You can filter elements by Name, Stereotype, or Tagged value
Target side (horizontal axis)
5 Target of Target side The same as Item 1 Not used
6 Type to display - You can specify 'Elements', 'Diagrams', 'Elements in Elements', 'Two-hop Relation'
- See here for details about 'Two-hop Relation'
'Elements' only
7 Type(s) of Target - When 'Elements in Elements' is specified in Item 6, you need to specify both element types and diagram types
- Two or more types can be specified from this dropdown list
- You can specify a type by drag & drop an element or a diagram (depends on Item 6) from the Browser window *
8 Detail specification of Target The same as Item 4, but 'Type' must be 'Elements' to use this button
Connectors
9 Type(s) of connectors - Active when Item 6 is 'Elements'
- Two or more types can be specified from this dropdown list
10 Direction of connectors - Active when Item 6 is 'Elements'
- You can specify multiple directions
Buttons
11 Profile You can re-use the same combinations of criteria by creating a Profile. Items between 1 and 10 are stored in a Profile
12 Refresh Refresh the matrix to display the latest information
13 Save Save the changes in the matrix to the model. Active when there are unsaved changes.
14 Options - Export: Export the matrix to various kind of file
- Profile: Create, update and delete profiles, or create a Matrix specification element
- Options: Specify various kinds of options

*: You need to enable the Option: 'Enable Drag and Drop Operation'.

Detail Specification Dialog

You can specify element criteria to display in the Matrix through this dialog.

# Item Description
1 Element Type(s) Two or more types can be specified from this dropdown list
2 Search Field Select one of 'Name', 'Stereotype', or 'TaggedValue'
3 Search Tag Name - Select or enter target Tagged Value name (Exact match)
- This field is displayed when Item 2 is 'TaggedValue'
4 Search Term Enter search term for Item 2:
  • 'Name': Enter name of elements (Partial match)
  • 'Stereotype': Select or enter a stereotype (Exact match)
  • 'Tagged Value': Enter value of the Tagged Value (Partial match)
    If you want to search for elements which have the Tag specified in Item 3, leave this empty.
5 Show only element rows Summary rows or columns will not be shown in the matrix

Two-hop Relation Settings

Specify type and direction of connectors with the intermediate elements between the Source and the Target, and types of the intermediate elements.

One of use cases of this relation is the following SysML relations. By using this 'Two-hop' relation, you can see a matrix between Requirements and Physical Blocks in the following connectors between elements.

Two-hop Relation Settings Dialog

In the main criteria panel, select 'Two-hop' in the Type dropdown list of the Target side. The Two-hop button will be displayed. By pressing this button, the Two-hop Relation dialog is displayed.

Specify intermediate element types, connector types, and direction to/from intermediate elements


# Item Description
1 Types of connectors (Source - Intermediate) You can specify multiple types
2 Directions of connectors (Source - Intermediate) You can specify multiple directions
3 Types of intermediate elements You can specify multiple types
4 Types of connectors (Intermediate - Target) You can specify multiple types
5 Directions of connectors (Intermediate - Target) You can specify multiple directions

Matrix View

When all criteria are specified, the Matrix view is automatically shown as below.
(Depending on the Options, you may need to click the Refresh button)

When you change criteria, the view will be updated with the new criteria. You can see the latest information by clicking the Refresh button.

When refreshing the view, the packages in the Source side will be displayed as expanded.

By default, the order of packages and elements is the same as in the Browser window.

Here are examples of the matrix view.

Example: Relationships between elements in a package and on a diagram

Adding or Deleting Connectors

To add or delete a connector, use one of the following ways on a target cell:

  • Double-click *
  • Press the spacebar *
  • Select connector type from the context menu by right-clicking

When you add a new connector, the arrow icon will appear in the cell. When you delete a connector, the arrow icon will disappear. In both cases, background of the cell will be yellow, which means the change is not saved yet. When you finish your work, click the Save button to save changes. If more than one connector directions are specified as the criteria, you cannot add or delete connectors.
*: This method is available only when one connector type is specified.

Actions for a Diagram/Element

When you select an item in the Source or Target header, the item will be highlighted in the Browser window. You can perform some action by double-clicking on an item:

  • Diagram: Open the diagram
  • Element: When you specify 'Diagram' as Target, open the diagram and select double-clicked element in the diagram.

Example: Elements and diagrams in which the elements are placed

You can optionally display diagrams in child packages. The hierarchy drawing of the Target side is different from the Source side.

You can check usage of instances in diagrams, as the special icon.

Example: Display packages as the same as elements

The rows and columns of packages show number of connectors, but you can also display packages themselves as the same as elements. You can add or remove connectors as shown below.

If you want to display packages as the same as elements (as shown above), you need to edit the Ini file. For more information on how to edit the Ini file, please see here.

Example: Relationships of 'Elements in Elements'

In the Target side, only elements in another element are displayed. (In the above figure, the Target side Actions are placed in the classified Partitions.)

By using this 'Elements in Elements' matrix, you can assign actions (i.e., features) to each SysML Block in Activity diagrams, and also check all assigned features for each Block through this matrix.

Example: Two-hop Relationships

Expanding and Collapsing the Tree

You can expand and collapse the tree by using the context menu (right click) of the tree as shown below.

'Expand Current, Collapse Others' menu is useful when you want to focus on the elements contained in the selected item.

Use Specification Element (Shortcut Element)

Use MatrixEx Specification Elements

You can create a MatrixEx specification element (shortcut element) by specifying an existing profile to open the MatrixEx easily. For example, if you are double-clicking on a specification element placed on a diagram, it will display MatrixEx view with the specified profile.

Create a Specification Element

To create a specification element, you need to add and activate target profile.

If you select a target diagram, a specification element will be created under the package of the diagram and the element will be placed in the diagram.

Display MatrixEx from a Specification Element

Export Matrix Image into a Specification Element

You can export a matrix image as a linked document of the specification element. The matrix image in the linked document can be used in the EA built-in document generation.

Exporting and Importing Profiles

Profiles can be exported and imported using the built-in XMI export and import feature for the specification elements described above. After importing, double clicking on a specification element will create a profile and display with the profile criteria in the MatrixEx.

If a profile with the same name as the specification element already exists, the existing profile will be used. (not overwritten)

Overlays

The arrowhead icons in cells can be changed to a CRUD-like format or any characters as you like. By using overlay feature, you can show additional information to connectors in the matrix.

  • Overlays can be applied only when the Target side is 'Elements'.
  • Overlays will not be applied when some options are enabled.
  • This overlay setting is compatible with the EA build-in overlays feature.

Example of CRUD overlay

How to edit a overlay

How to add a new overlay

Options

You can set the following options. These options will be retained even after this Add-in is closed. (except the items marked with *)

  • Include Child Packages
  • Sort Element by: specify sorting target (Name (or Alias if next option is enabled), or Tagged Value)
  • Use Alias if Available
  • Display child elements as the same level as their parent elements
    • If this option is enabled and target element types do not include parent types, only child elements will be displayed.
    • Valid only when Source/Target is a package and display types are 'Elements'
    • Show only child elements when specifying only their types
  • Highlight elements under specified condition
  • Highlight the element in the Matrix when selected in Enterprise Architect
  • Display packages which have one or more matched elements, and hide empty packages
  • Display child elements' connectors as parents' connectors
    • If this option is enabled, Child elements will not be displayed.
    • Valid only when Source/Target is a package and display types are 'Elements', and in the Basic Matrix mode
  • Refresh Matrix only when the Refresh button is clicked
    • Valid only in the Basic Matrix mode
  • Refresh Matrix automatically when editing an element or creating / editing a connector *
    (Reset to disabled after this Add-in is closed)
  • Enable Drag and Drop Operation
  • Overlay: select existing a overlay or define a new overlay
    • Valid only when both display types are 'Elements'

Customize Types of Elements, Connectors and Diagrams

The types of elements, connectors, and diagrams to be displayed are set in the Ini file as follows. You can add, delete, change order and rename them.

When this Add-In is installed, the default Ini file (MatrixEX_DefaultEn.ini) is installed in the Enterprise Architect installed directory.

How to Edit the Ini File

Steps

  1. Copy the MatrixEX_DefaultEn.ini file to the folder described below
  2. Edit the copied Ini file

Details

Ini File Requirements:

  • The name of the Ini file must be MatrixEX_*.ini (* is any string)
  • The Ini file is placed in the Windows MyDocument folder (e.g., C:\Users\<your_name>\Documents)
  • Only one Ini file must be placed
  • Character set of the file is UTF-8
  • When Enterprise Architect is started, the Add-In loads the Ini file.
  • When there is no Ini file in the MyDocument folder, the Add-In loads the Ini file in the Enterprise Architect installed directory.
  • If there are more than one Ini file in each case, the Add-In will show an error and will be disabled.

Ini File Specification:

  • One element, one connector, or one diagram type can be set per line
  • Each line contains the following information, separated by commas (CSV format)
    • Item 1: One of 'Element', 'Connector', or 'Diagram'
    • Item 2: Display name
    • Item 3: Type of the element, connector, or diagram
      • Type string must be the same as the internal string in Enterprise Architect
      • When Item 1 is 'Diagram' and if you want to specify non-UML diagram (i.e., defined by a profile), Item 3 should be the profile name and Item 4 should be the stereotype of the diagram.
    • Item 4: Stereotype
      • When Item 1 is 'Element', '*' means elements of any stereotypes will be included.
      • When Item 1 is 'Connector', fully qualified stereotype name can be specified.
      • If you leave this item blank, it does NOT mean any stereotype is matched. When blank, elements (,connector, or diagram) with any stereotype will not be included.
  • The display order in the Criteria panel is the same as order in the Ini file.
  • If you want to display packages as the same manner as elements, copy the next line of the '//Package element' definition in the MatrixEX_SampleEn.ini file and paste it in your Ini file. The sample file is installed as 'sample_MatrixEx' directory in the Enterprise Architect installed directory.

Notes

  • MatrixEX_DefaultEn.ini in the Enterprise Architect installed directory will be always overwritten when the Add-In is installed or updated. When you want to customize, please copy this Ini file to the MyDocument folder.
  • Elements, connectors, and diagrams in the matrix are limited to types defined in the ini file. If you select '(Select All)' in the Criteria panel, it means all types listed in the dropdown list. 'All' does NOT mean all types are included.
  • To know how to add non-UML types to the Ini file, please see the MatrixEX_SampleEn.ini file in the sample_MatrixEx folder of the Enterprise Architect installed directory.

How to update your Ini file to the latest version

When you install a newer version of the Add-In, you may get a message that your Ini file is out of date and may need to be updated. In this case, if you will not update your Ini file, the Ini file might not be loaded correctly and the Add-In might not work properly. Therefore, please follow the steps below to check and update the contents of the Ini file.

  1. Open your Ini file in text editor
  2. See the change log about the ini file, and
    • If you want to use [Added] marked line, add it to your Ini file
    • If there is a [Changed] line and you use the line, copy the line from the change log and overwrite it in your Ini file
    • If there is a [Deleted] line and you do not use the line, delete the line from your Ini file
  3. Copy the first line of MatrixEX_DefaultEn.ini and overwrite as the first line of your Ini file (the first line contains version information)
  4. Restart Enterprise Architect after saving the changes.