ea_mdg

ea_mdg works with modeling languages: the MDG Technologies and UML profiles that define stereotypes, tagged values, diagram types and toolboxes in Enterprise Architect. It finds out which technologies exist and which are actually active, installs them, writes and reads MDG technology files, exports a profile package from the model, and translates technical stereotype names into display terms. It has 12 operations in five groups.

Examples in this chapter use the fictitious Westbrook Bank technology: id WBA, display name WestbrookBankArchitecture, stereotypes such as WBA::WBABusinessApplication. Replace them with your own technology's id and stereotypes. Nothing here assumes you have the Westbrook model.

What EA must be doing. Most operations need Enterprise Architect running with a project open: list_available_modeling_languages, get_embedded_mdgs, list_registered_technologies, assess_mdg_situation, publish_package_as_profile, and install_mdg when installing into a model. Installing for the whole workstation needs EA running only to refresh its view, on a best-effort basis. parse_mdg_xml, write_mdg_xml, set_active_mdg, resolve_display_term and get_mdg_search_paths need neither. get_mdg_from_runtime asks EA when it can and answers that it cannot determine the state, rather than failing, when it cannot.

Read-only mode. In read-only mode (see How tools and operations work) install_mdg, set_active_mdg and write_mdg_xml are refused, even though the last two do not change the repository. publish_package_as_profile is not refused, because it writes a file and changes no repository content.

Skills that use this tool. ea-mdg-assess is built around assess_mdg_situation and the discovery operations. ea-mdg-author uses write_mdg_xml, parse_mdg_xml and install_mdg. ea-mdg-model-build uses publish_package_as_profile. ea-mdg-deploy uses install_mdg and checks the result. ea-stakeholder-reporting uses resolve_display_term.

Technology states: registered, installed, embedded, loaded

"Is the technology there?" has four different answers, and each operation in this tool sees a different subset of them. Confusing the states is the usual cause of "I installed it but nothing changed".

Three consequences follow:

• Installed does not mean loaded, and loaded does not mean enabled. EA picks up an installed file when it starts, so a technology written after EA started is not active until EA restarts. A technology disabled in Manage Technologies stays registered and EA still reports it loaded, but its toolbox, diagram types and quick links are not offered. get_mdg_from_runtime reports such a technology as registered but not enabled, and assess_mdg_situation leaves it out of the loaded technologies.
• Embedded does not mean the only copy. A file in the per-user folder that declares the same id shadows the model's embedded copy. The author's workstation then shows one version while everyone else sees another. The same id can also be stored at both Locations in one model: Manage Technologies then lists two entries and EA answers from the Location: Project copy. list_registered_technologies deliberately lists the same name more than once, one row per location, so both kinds of shadowing are visible, and get_mdg_from_runtime names the other copy and warns about it.
• No operation can list every registered technology. EA's automation interface has no call that does. The discovery operations work from a list of technology ids they already know, plus what the model holds, and they say so in a completeness note. A technology under an id the server does not know is found only by asking for it by its exact id with get_mdg_from_runtime.

A technology whose file declares no version of its own reports no version. AI Power Tools does not fill in one, so an empty version means the technology was built without one.

Session memory

parse_mdg_xml remembers what it reads until the server restarts. Other operations then recognize that technology: it appears in list_available_modeling_languages, get_mdg_from_runtime can answer from it, resolve_display_term can resolve its aliases, and create_element_in_language in Elements can resolve its stereotypes. This memory records what a file says, not what EA loaded, and get_mdg_from_runtime labels such an answer as coming from a parsed file.

Discovering technologies

Five reads. Four of them are limited by what EA's automation interface can report, and each says how complete its answer is.

Notes

• list_available_modeling_languages is not exhaustive. It builds its list from the technologies stored in the model (at either Location), the languages the server has definitions for, a list of stock Sparx technology ids it asks EA about, and any technology parsed this session. A customer technology that is loaded in EA but has not been parsed this session and is not on the list does not appear. Ask for it directly with get_mdg_from_runtime, using the exact id from Manage Technologies, which can differ from the display name. A technology you authored is labeled as learned this session, because the server cannot tell who installed it and does not guess.
• The demonstration language is hidden. The fictitious Westbrook technology is merged into the language lists only when a demonstration setting is on (see Demo languages). Customer installs do not turn it on.
• A disabled technology is visible only where AI Power Tools can find it. get_mdg_from_runtime reads EA's enabled flag for any id you name, and list_registered_technologies reads it for every technology stored in the model. For its other rows, the enabled state list_registered_technologies shows is whether EA reports the technology loaded, which is also true of a disabled technology, so confirm a technology that matters with get_mdg_from_runtime. A technology disabled in Manage Technologies with no copy in the model and an id the server does not know is indistinguishable from an unregistered one through EA's interface. list_registered_technologies does not guess, and it has been reported to disagree with Manage Technologies in some repositories. Cross-check one against the other before acting. The assistant can read Manage Technologies itself when it has computer use; otherwise you read it to the assistant.
• get_embedded_mdgs lists what the model stores, not what EA uses. A technology loaded from a file on the workstation is not stored in the model and does not appear; an empty result means the model stores no technology. Whether a stored copy is enabled is answered by list_registered_technologies and get_mdg_from_runtime. A stored copy that cannot be decoded is listed with the reason, not skipped. The server cannot read the Manage Technology dialog (Specialize > Technologies > Manage Technology), where each copy's Location shows. With computer use the assistant opens it and reads it; without computer use, you open it and tell the assistant what it shows.

What get_mdg_from_runtime tells you

This is the operation to trust for "what does this technology contain in this session". The definitions come from the technology file EA itself read, not from a table the server maintains. It looks in three places, in EA's own precedence order: first a registered file in a folder EA loads at startup (the per-user folder first, then configured search paths, then EA's install folder, matched by the id the file declares), then the copy stored in the open model at Location: Project, then the copy stored at Location: Model. If none holds a definition and you parsed the technology this session, it returns the parsed copy and says so.

It answers one named technology, not the whole repository. The answer says where the definitions came from: a registered file, with its path, or the model, with the Location. It also says whether EA has the technology loaded and whether it is enabled. The answer comes with one of these outcomes:

When nothing is readable, one of four reasons is given. cannot_determine means EA could not be reached (not running, or no project) and no copy exists; treat it as unknown, not absent, and retry with EA running. model_technology_unreadable means the model stores a copy under this id that could not be decoded; the answer names the Location and the reason, and the remedy is the same export described next. mdg_loaded_no_definition means EA reports the technology loaded but its file is neither in a folder EA loads from nor in the open model; export it from Manage Technology and have the file parsed. The export is done in EA's window: with computer use the assistant does it; without it, you export the file and give the assistant the path. unknown_mdg means no definition anywhere and nothing loaded under that exact id; check the id in Manage Technologies.

When EA reports one version and the definition read declares another, the answer carries a version-mismatch flag. EA is then loading a different build than the one read. Resolve that before trusting either side.

A technology stored at both Locations. When the open model holds the same id at Location: Project and at Location: Model, Manage Technologies lists both, and EA answers from the Project copy. get_mdg_from_runtime answers from that same copy, lists the other copy with the version it declares, and adds a shadowing warning: remove the copy you do not want in Manage Technologies. This is the usual reason a technology installed at Location: Model seems not to take effect; see Installing.

Other points to know:

• "Loaded" describes the EA session you are connected to, not the model file. EA reports a disabled technology as loaded, which is why the enabled flag is read as well.
• The same technology can be both a registered file and embedded. The file wins, because that is what EA loads; the model's copies are then listed as also stored.
• A technology hosted in the cloud is not reachable this way (reported, not independently verified).

What get_mdg_search_paths can and cannot tell you

Any technology file EA finds in a search path at startup is registered automatically. That makes a build output folder on the list a trap: a file written there silently registers itself and can shadow the copy you meant to test. Asking about the build folder before writing a build tells you whether that will happen.

EA's automation interface has no call for the search-path list, so the server reads it from the current user's Windows settings. If it cannot resolve the list, it says the list is unknown, which is not the same as "none configured"; fall back to Specialize > Technologies > Manage Technology > Advanced in EA, which the assistant reads with computer use or asks you to read. The check covers only the search-path list. It does not examine the per-user folder or EA's install folder, which EA also loads technologies from. Windows only.

Managing technologies

Installing

Three scopes, with different consequences:

• Workstation (the default). A technology file (or XML text) is copied to %APPDATA%\Sparx Systems\EA\MDGTechnologies\<technology id>.xml, overwriting a file of that name. EA registers it when it starts, so the technology is available to every model on this workstation after a restart.
• Model, from a technology file (Location: Project). The file is imported into the open model through EA's file import, which stores it at Location: Project. On EA 17.1 this Location keeps the technology's profiles and diagram profile but no toolbox pages: users get only an automatic toolbox page built from the stereotypes. The server reads back what EA stored and lists each populated part of the file that was not stored. When anything is missing, the reply marks the install as incomplete and warns, naming the two ways to keep the whole technology: the package scope below, or EA's own Import to Model. If EA reports success but stores nothing, the reply says so as a named failure.
• Model, from an MDG Technology package (Location: Model). The technology is built from a package in the open model that carries the mdg technology stereotype, as produced by a model-driven technology build (ea-mdg-model-build), and imported at Location: Model. The whole technology is kept, toolbox pages included. The server reads the stored copy back and reports its id, version, and the numbers of stereotypes, diagram types and toolbox pages, and flags it when EA reports a different version than the stored copy declares. A package without that stereotype is refused. Importing the same package again replaces the stored copy rather than adding a second one.

Both model scopes travel with the model. The server suppresses EA's confirmation dialog for the call, because a prompt would otherwise block the connection, and restores EA's settings afterward. Prefer a model scope when the technology should travel with one model, and prefer the package scope when you have the package.

Installing a technology file at Location: Model. EA's automation interface has no call that imports a technology file at Location: Model, so the server cannot do it, and the package scope does not take a file. Use EA's own Specialize > Publish Technology > Import MDG Technology, and choose Import to Model. With computer use the assistant does this in EA's window; without it, you do it and the assistant then verifies the result.

Replacing a copy at Location: Project. If the model already holds the same technology id at Location: Project, EA lists both copies and answers from the Project copy, so the Location: Model copy just installed has no effect. The install then reports itself as installed but shadowed, with a warning. Ask for the Project copy to be replaced and the install removes it after importing. If EA leaves it in place, which was seen once in a long-running EA session, the reply still says shadowed and shows what EA returned: reopen the project and ask again (in the one case measured, that removed it), or remove the copy in Manage Technologies. If removing the Project copy also took the Location: Model copy just installed with it, the reply says so as a failure, and the install must be repeated.

Restart EA before judging the toolbox. After a Location: Model install in a running EA, the diagram types resolve and the toolbox pages are listed at once, but the toolbox does not dependably switch to them when a diagram opens until EA restarts. The reply says so. The server cannot restart EA. With computer use the assistant restarts it after asking you; without computer use, you restart it.

Notes

• "Installed" is not proof that it works. A success message and a true import result do not show the technology works. Verify with get_mdg_from_runtime (expect the live outcome, the expected version and the expected Location) and in Manage Technologies, and restart EA after a deploy. The server cannot restart EA or read Manage Technologies. With computer use the assistant restarts EA and checks the dialog. Without computer use, it asks you to restart EA and read the dialog back.
• A workstation install can shadow an embedded copy of the same id, and a Location: Project copy shadows a Location: Model copy. Check Manage Technologies for a single enabled entry at the expected version and Location. The assistant does this with computer use, or asks you to.
• The technology id is limited to 12 characters by EA, and EA rejects a longer id silently when it loads the file. If a model import fails, the likely causes are invalid XML, an id that is too long, or base technologies that are not installed.
• Installing does not add the technology to the session memory. Parse the file as well if you want other operations to recognize it immediately.

set_active_mdg does not protect you

The preference is stored in memory and nothing reads it. In particular, setting strict mode does not reject elements that violate the technology, and the response says so. Setting it and assuming you are protected is worse than not setting it. To check conformance, run a ruleset with ea_validate. The preference is lost when the server restarts, and the id is not checked against any installed technology.

The situation assessment is a rule-based judgment

assess_mdg_situation is a first look, not a finding. It applies fixed rules, so the same repository gives the same answer, and it can be wrong. It compares the stereotypes in use with the languages it considers loaded, and applies a 5 percent threshold:

1. It splits the loaded languages into client technologies (installed by a customer, or stored in the model at either Location) and technologies Sparx ships. A technology stored in the model but disabled in Manage Technologies is not counted as loaded.
2. It reads which stereotypes the repository uses, counted by element, with any language prefix removed.
3. A stereotype counts as covered when its name appears in the server's definitions for any loaded language. Everything else is ad hoc.
4. The scenario follows from those counts.

It also reports the number of elements that carry an uncovered stereotype and the percentage covered.

Cross-check it against EA's Manage Technologies dialog (the assistant reads it with computer use, or asks you to). Several things can make the assessment wrong:

• "Covered" is tested against the server's own stereotype definitions for loaded languages, not against the stereotypes your loaded technology really declares. A client technology is recognized only when the server classifies it as client-installed or model-embedded. A technology it learned from a parsed file, or does not list at all, is not counted. The assessment can therefore report that no client technology is loaded (scenario 1) for a repository that does have one loaded. Confirm with list_registered_technologies and get_mdg_from_runtime.
• An empty repository, or one with no stereotyped elements, and a loaded client technology gives the heavy ad hoc usage result (scenario 3).
• It looks at stereotype usage and loaded languages only. It cannot see whether a source model or profile package exists for the technology. Where one exists, ea-mdg-model-build is the right next step regardless of the recommendation.
• It has been reported to disagree with EA's own Manage Technologies view in some repositories. Treat the scenario as a hypothesis to confirm, not a result to act on.

Authoring

Two operations convert between a technology file and a plain description of its contents. parse_mdg_xml reads a file into the description. write_mdg_xml turns a description into a file. They are inverses, which is what makes a round trip a useful check: write a file, read it back, and compare what comes back with what you intended.

The description of a technology holds:

• the technology's id (the id EA registers), display name, version and free-text notes (the place to record where a generated technology came from)
• each stereotype: name, display alias, the EA element or connector type it applies to (such as Component, Class, Activity or Dependency), notes, its tagged values (name, type, default, description, and an allowed-values list for enumerations), any constraints, any Quick Linker rules, and two display options (hide UML links, and a forward meaning for connectors)
• each diagram type: name, alias, EA base diagram type, an id, and the toolbox it uses
• each toolbox page: a name and its items, each pointing at a stereotype
• any scripts the technology carries

Notes on write_mdg_xml

• Id length. EA allows technology ids of up to 12 characters and rejects a longer one silently at load time. The writer checks the id up front, and also the ids it derives from it: one for the diagram profile (which adds five characters) and one for the toolbox profile. The effective limit on the technology id is therefore 7 characters, and an 8-character id is refused even when the technology has no diagram types.
• No reference data. The output carries no EA reference data for tagged value types. Allowed-values lists are written on each tag and drive a dropdown in a hand-authored file, but a technology installed from this output alone can present free-text fields where a closed list was intended. Say so when handing it over.
• It does not check your content. Stereotype names, element types and tag types are written as given. Round-trip the result and compare counts, names, element types and tags with what you intended before installing.
• Parent folders of the output path are created if missing, and an existing file is overwritten.

Notes on parse_mdg_xml

• It reads the technology's metadata, stereotypes with their tagged values, constraints and Quick Linker rules, diagram types, toolbox pages and scripts. Toolbox entries are kept separate from stereotypes. It tolerates minor structural differences and common text encodings, and does not validate the file against a schema.
• Reading a file never redefines a language the server already knows. Existing definitions are kept.
• XML that declares a document type or entity definitions is refused wherever the declaration stands ahead of the root element, however long the comments before it, as is input over 64 MB, because EA writes neither. The same check applies to every XML the server reads, including query results from EA.
• The version reported is the one the technology declares for itself. A file that declares none reports no version; the version on the file's outermost element describes the file format, not the technology, and is not used.
• A path is recognized only if a file exists at exactly that path. A leading ~ and environment variables are not expanded.
• A technology learned this way is labeled as learned this session, so assess_mdg_situation does not count it as a client technology. The memory lasts until the server restarts.

Publishing a profile

Notes

• The version is always passed. EA reads a package's version only the first time that package is published in an EA session, then caches it and keeps emitting it however the package changes. Without an explicit version you can silently get a stale or empty one. The assistant passes the version on every call, and the server then rewrites the output's version to exactly that value. The rest of the file is left as EA wrote it.
• The package must be a profile package, meaning it holds stereotype elements, in the open model. Otherwise the export fails with a general message rather than a specific cause.
• The output is one input to a technology, not a complete technology file. "Save Package as MDG Technology", the model-driven generation of a complete technology, is a step in EA's own user interface. With computer use the assistant drives that step; without it, you do it by hand and the assistant continues from the file you produce. "Import Package as MDG Technology" is a different menu entry; it loads the technology into the session without writing a file.

Display terms

It works from the server's in-memory alias tables, not from EA, so it needs no connection. Optionally it can be limited to one technology; otherwise every known language is searched in alphabetical order of technology id and the first match wins.

How each kind resolves:

• Stereotypes and connector stereotypes: the language's alias first (for example ArchiMate 3's ApplicationComponent becomes "Application"). Otherwise, if the stereotype is in the language's definitions, the name split into words (BusinessService becomes "Business Service"). A language-qualified name is retried on its plain form, only after every language has been tried exactly.
• Tagged values: the language's tag aliases. A standard installation has none, so tag lookups usually miss. Use the labels that get_element_business_view and aggregate_portfolio (in Project) return, or title-case the tag name.
• Diagram types: found when the name is among a language's diagram-type definitions (currently ArchiMate 3's layers). The alias is the name itself.

Notes

• It only knows what the session knows. A technology's stereotypes resolve to its own aliases only after its file has been parsed this session, or if the language has built-in aliases. Parse the technology first, or read its aliases directly with get_mdg_from_runtime.
• The kind for tags must be the tagged-value kind. Any unrecognized kind falls through to "not found" without an error.
• The fictitious demonstration technology's aliases are available only when the demonstration setting is on.