UML-adoc-exporter

UML AsciiDoctor .adoc format class and diagram exporter for MagicDraw UML tool, release 2024x. Note that MagicDraw is now owned and distributed by Dassault Systems as part of the Catia product suite. Developer documentation.

Previous version(s)

Previous versions of this plug-in are found on branches. The version for MagicDraw 19.4 is found here. To build and use a previous version, clone this repo and check out the appropriate branch.

Installation of the plugin

To install the plugin to MagicDraw, the two files UmlAdocExporter.jar and plugin.xml need to be copied from /plugin to the location <MagicDraw-install>/plugins/org.openehr.adoc.magicdraw.

Running the plugin

The plugin is used via direct command line invocation, using a script like the one shown below, assumed to be named uml_generate_msa.sh:

#!/bin/bash

#
# Script created according to MagicDraw documentation file Specifying_batch_mode_program_classpath_and_required_system_properties.html
#
# This script will only work with MagicDraw 2024x or later.
#

if [ -z "$MAGICDRAW_HOME" ]; then
    echo "MAGICDRAW_HOME environment variable not set, please set it to the MagicDraw installation folder"
    exit 1
fi

# Reads CLASSPATH value from magicdraw.properties files (change to your properties file name)
MD_CLASSPATH=`grep "CLASSPATH" $MAGICDRAW_HOME/bin/msa.properties | cut -d'=' -f 2`

# prepend MAGICDRAW_HOME to classpath
MD_CLASSPATH="$MAGICDRAW_HOME/$MD_CLASSPATH"

# add path to plugin
MD_CLASSPATH="$MD_CLASSPATH:$MAGICDRAW_HOME/plugins/org.openehr.magicdraw.adocexporter/MsaAsciidocExporterPlugin.jar"

# Adjust CP for operating system
if [ "$OS" = Windows_NT ]; then
    MD_CLASSPATH=$(echo "$MD_CLASSPATH" | sed "s/\\\:/;/g")
else
    MD_CLASSPATH=$(echo "$MD_CLASSPATH" | sed "s/\\\:/:/g")
fi

echo " ************* CP = $MD_CLASSPATH"

# Note that the version of java needed in the final invocation of this script is Java17 or later
java -Xmx1200M -Xss1024K \
       -cp "$MD_CLASSPATH" \
       -Desi.system.config="$MAGICDRAW_HOME/data/application.conf" \
       -Dfile.encoding=UTF-8 \
       @$MAGICDRAW_HOME/bin/vm.options \
       org.openehr.magicdraw.adocexporter.UmlAdocExporterCommandLine "$@"

Plug-in Usage

The command line arguments passed to the script above are passed to the plugin (see final line of script). Usage is as follows:

-c: component package name(s) under root package to export (comma-separated)
-P: component name prefix to use in links
-d: image format: svg|png (default = all)
-k: spec URL template
-o: output folder (default = current folder)
-l: class headings level (default = 3)
-p: UML package depth for uniqueness (default = 4);
-q: if set, use package-qualified class-names in output files (default = set)
-r: root package name to export (default = openehr)

The command line for openEHR looks as follows:

# create a command that will look like the following
# -d svg
# -k /releases/\${component_prefix}\${component}/{\${component_lower}_release}/docs/\${spec_name}.html
# -p 4
# -r openehr
# -q
# -c AM
# -o docs/UML
# computable/UML/openEHR_UML-AM.mdzip
uml_regen_cmd="$ref_dir/bin/uml_generate_msa.sh -d svg -k ${link_template} -p $pkg_depth -r $uml_root_package ${package_qualifiers:+-q} -c $component -o docs/UML $uml_file"

Plug-in Source Code

The plug-in relies on the UML 2.x OpenAPI from Catia. This is (as far as we can tell) a faithful implementation of the UML 2.5.1 meta-model. Note that breaking changes occurred between UML 2.5 and UML 2.5.1, to do with how stereotypes are represented (described here), which meant that code changes were required between the MD 19.4 version of the extractor and the current one.

Building

The repo is currently set up as an IntelliJ project that builds a .jar that works as a plugin for Magicdraw, as described in the MagicDraw 2024x documentation, found in $MAGICDRAW_HOME/openapi/guide.zip.

Steps to performing a build:

• Clone the repo, e.g. into openEHR/UML-adoc-exporter

• open /UmlAdocExporter.ipr in IntelliJ

• Performing a build will generate the file /out/artifacts/UmlAdocExporter_jar/UmlAdocExporter.jar.

If you make changes, the latest build should be copied to /plugin in this repo, for easy access by users without doing a build. Additionally, if you make changes to the file UmlAdocExporter/plugin.xml, also copy this file to /plugin.

Acknowledgements

The original version of the extractor was created by Boštjan Lah at Better.care; subsequent updates done by Thomas Beale at Ars Semantica & Graphite Health.