Selectively including Enterprise Architect diagrams from XMI exports

Kwan Koon Wa on 26 Aug 2024

Introduction

Similar to the new lutaml_gml_dictionary command, the Metanorma work for MLIT Project PLATEAU now provides the lutaml_ea_diagram command for including an Enterprise Architect (EA) diagram inside your Metanorma document.

Metanorma users that document conceptual or implementation models in standards utilize a “model-based authoring” approach to ensure a single source of truth for their models. A significant portion of those users, utilize UML through Enterprise Architect.

Note	The LutaML for UML plugin used by Metanorma supports navigating through UML models stored in XMI files (version 2.4+) generated by Enterprise Architect version 15 or above.

While Metanorma has always supported the inclusion of an entire UML package rendered with internal diagrams inside a document, the lutaml_ea_diagram command now allows users to selectively incorporate an EA diagram as a figure, when the EA model is exported into an XMI file with accompanying images.

This post describes how users can directly incorporate EA diagrams into their Metanorma documents using the lutaml_ea_diagram command.

Command

The lutaml_ea_diagram command allows to quickly render a EA diagram as an image file by specifying the name of diagram.

The specified name of the diagram is searched across all packages in the XMI file.

Syntax:

Syntax for lutaml_ea_diagram

lutaml_ea_diagram::[name="{name-of-diagram}",base_path="{base-path-to-xmi-images}",format="{format}"]

Where,

name="{name-of-diagram}": provides the name of the diagram to be matched. Only the first diagram that matches will be returned.
base_path="{base-path-to-xmi-images}": provides the base path of all images exported by Enterprise Architect accompanying the XMI export file. Typically, it is generated as Images/ at the same location of the XMI export file.
format="{format}": sets the expected format of the image files exported together with the XMI export file. Enterprise Architect supports export of the PNG and SVG formats. The svg format is recommended for image scaling clarity.

Internally, the lutaml_ea_diagram command searches for a diagram that matches the name in the EA XMI export file, and resolve the xmi_id to find the actual diagram, and then include it into the Metanorma document.

Underlying image rendering of lutaml_ea_diagram

[[figure-{{ diagram.xmi_id }}]]
.{{ diagram.name }}
image::{{ base_path }}/{{ diagram.xmi_id }}.{{ format | default: 'png' }}[]

Usage example

Suppose there is an Enterprise Architect exported XMI file named ea-export.xmi, and the diagram with name Fig B1 Full model is to be included, and the exported images are located at the path xmi-images as PNG files.

Directory structure

current-directory/
├── ea-export.xmi
└── xmi-images/
  └── EAID_0E029ABF_C35A_49e3_9EEA_FFD4F32780A8.png

Example 1. Diagram content in ea-export.xmi

For those curious about details, Enterprise Architect provides the diagram in the following manner in the exported XMI file.

<diagrams>
  <diagram xmi:id="EAID_0E029ABF_C35A_49e3_9EEA_FFD4F32780A8">
    <properties name="Fig B1 Full model" type="Logical"/>
    ...
</diagram>

This is how to render the diagram by lutaml_ea_diagram:

Example 2. Render EA diagram by lutaml_ea_diagram

lutaml_ea_diagram::[name="Fig B1 Full model",base_path="./xmi-images",format="png"]

lutaml_ea_diagram will search the diagram with name Fig B1 Full model in ea-export.xmi to retrieve EAID_0E029ABF_C35A_49e3_9EEA_FFD4F32780A8 and then render it in Metanorma Semantic XML as:

<figure id="_auto_id">
  <name>Fig B1 Full model</name>
  <image src="./xmi-images/EAID_0E029ABF_C35A_49e3_9EEA_FFD4F32780A8.png"
    mimetype="image/png" id="_auto_id" height="auto" width="auto"/>
</figure>

Conclusion

The lutaml_ea_diagram command provides a convenient way to include EA diagrams in Metanorma documents, allowing users to selectively include diagrams from Enterprise Architect models.

Questions or suggestions, please feel free to file an issue at the metanorma-plugin-lutaml repo.