Selectively including Enterprise Architect diagrams from XMI exports

Introduction

Similar to the new `lutaml_gml_dictionary` command, the Metanorma work for MLIT Project PLATEAU now provides the lutamleadiagram 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.

While Metanorma has always supported the inclusion of an entire UML package rendered with internal diagrams inside a document, the lutamleadiagram 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 lutamleadiagram command.

Command

The lutamleadiagram 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:

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

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

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

<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 lutamleadiagram:

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

lutamleadiagram will search the diagram with name Fig B1 Full model in ea-export.xmi to retrieve EAID0E029ABFC35A49e39EEA_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 lutamleadiagram 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.