Powerful customization for code generation & model validation for Enterprise Architect models

This repository contains a technical demonstrator for customized code generation and model validation for Enterprise Architect (EA) models. It's an Add-in for Enterprise Architect which calls a command-line Java-application containing the actual logic.

Advantages of this approach are:

• Performance: the CLI application loads and processes large EA models much faster (up to 50x) than using EA's API directly with an Add-in.
• Standard compliance: the model is loaded as a standard UML model and can be processed with powerful languages such as Java, Kotlin, or Xtend.
• Seamless integration: the EA Add-in integrates powerful model processing into the UI of Enterprise Architect.

Screencast for code generation (currently focussing state machines):

Keep in mind that this demonstrator is just an example and not feature-complete by any means! It serves as a starting point for customized code generation, model validations, or any kind of reporting.

Screencast for model validation (UML constraints and one exemplary custom validation rule):

Tested with Enterprise Architect 15, 16, and 17.

How to run this example

Follow these steps to try the example on your local machine:

1. Download the zip-package and extract it to some location on your hard-drive.
2. Download the Add-in msi-installer and install it (EA must not be running).
3. Download the Example.eap file and open it.
4. Go to Specialize → Itemis Integrate-EA → Configure CLI Path → and set the path to the folder into which you extracted the zip-package.
5. To validate your model: open the context-menu on a package in the Project Browser and select Specialize → Itemis Integrate-EA → Example Model Validation → it will take a few seconds*, then check the Add-in window for the result.
6. To generate code: open the context-menu on a state-machine and select Specialize → Itemis Integrate-EA → Generate Code... → a dialog will popup to configure and finally run the code generation; it will take a few seconds*, then check the result in the selected target folder.

* keep in mind that a new processed is spawned in the background to perform the task; this takes a while, but processing the model is very fast. So performance first pays off with large models.

Technical details

The Add-in is just a facade that integrates the model processing capabilities of the Java command-line interface (CLI) into the UI of Enterprise Architect.

For the validation use-case, standardized UML checks and also custom validation rules are executed, and the Add-in displays the validation issues in a custom UI view including the possibility to navigate to the corresponding elements in the EA project browser or in existing diagrams. For the code-generation use-case, UML state-machines can be generated to different target languages.

The following diagram illustrates how the different components of the example work together:

flowchart TB
    user@{ shape: circle, label: "User" }
    user -- - validate model<br>- generate code --> Action
    user -- navigate to elements --> View

    code@{ shape: docs, label: "C/C++/C#/Java/Python Files" }
    CREATE -- generates --> code

    eap[(".eap(x)/.qea(x) File")]
    EA -- query model --> eap
    INTEGRATE -- load model --> eap

    subgraph EA["Enterprise Architect"]
        subgraph AddIn["EA Add-in"]
            View["Validation View"]
            Action["Actions"]
            CLIHandler["CLI Handler"]
        end
        Browser["Project Browser"]
        Diagram
    end
    Action --> CLIHandler
    CLIHandler -- update--> View
    View -- highlight element --> Browser
    View -- highlight element --> Diagram

    subgraph CLI["CLI Application"]
        Logic["CLI Logic"]
        INTEGRATE["Itemis INTEGRATE-EA"]
        CREATE["Itemis CREATE"]
        Validator
        UML["UML"]
        Rules["Custom Rules"]
    end

    Logic -- load UML model --> INTEGRATE
    Logic -- call --> Validator
    Logic -- call --> CREATE
    CLIHandler -- call --> Logic
    Logic -. Validation Report (JSON) .-> CLIHandler
    Validator -- uses --> UML
    Validator -- uses --> CREATE
    Validator -- uses --> Rules

    click CLIHandler "https://github.com/itemisCREATE/ea-bridge-integration-example/blob/main/AddIn/Itemis_Integrate_EA_Example_AddIn/ApplicationHandlers/ExampleHeadlessApplicationHandler.cs" "ExampleHeadlessApplicationHandler.cs"
    click View "https://github.com/itemisCREATE/ea-bridge-integration-example/blob/main/AddIn/Itemis_Integrate_EA_Example_AddIn/UI/ValidationIssuesControl.cs" "ValidationIssuesControl.cs"
    click Logic "https://github.com/itemisCREATE/ea-bridge-integration-example/blob/main/CLI/com.yakindu.bridges.ea.example.cli/src/com/yakindu/bridges/ea/example/cli/ExampleCLI.java" "ExampleCLI.java"
    click Validator "https://github.com/itemisCREATE/ea-bridge-integration-example/blob/main/CLI/com.yakindu.bridges.ea.example.cli.validation/src/com/yakindu/bridges/ea/example/cli/validation/ModelValidation.java" "ModelValidation.java"
    click Rules "https://github.com/itemisCREATE/ea-bridge-integration-example/blob/main/CLI/com.yakindu.bridges.ea.example.cli.validation/src/com/yakindu/bridges/ea/example/cli/validation/custom/RuleAbstractClassPrefix.java" "RuleAbstractClassPrefix.java"

Loading

This repository consists of two codebases:

• The command-line interface (CLI) is a headless Java Eclipse application containing an EA-integration adapter for loading UML models from ea-files and itemis CREATE for code-generation.
  The validation performs UML syntax validation, runs an exemplary custom validation rule, and returns the result as JSON for further processing with the EA Add-in.
  The code-generation collects state-machines and generates code for the selected languages (C/C++/C#/Java/Python).

• The EA Add-in provides UI actions in EA for triggering model validation and code-generation; it further lists the validation results in a custom view inside EA without the need to use the command line. A double click on a validation result in EA selects the corresponding element in the Project Browser and opens the diagram containing that element (if such a diagram exists).

ℹ️ Both, the CLI and the Add-in, serve as starting points to add powerful building blocks into your tool-chain; i.e. they can easily be extended with further use-cases like further customized actions in EA or generation of other kinds of code like reports or component models.

How to build this example

• CLI application:

  The CLI is an OSGi application written in Java (it requires Java 21). Run the following maven command to build it.

  cd CLI

  mvn clean verify

• EA Add-in:

  The Add-in is written in C# and uses the automation API provided by Enterprise Architect to access the model and add custom views to the UI. To build the Add-in you need the following tools:

  • Visual Studio 2022 or newer. In the IDE, the following extensions are required:
    • NUnit 4 Test Adapter: required to build and run tests. It can be installed using the extension manager in Visual Studio.
    • Wix Toolkit Visual Studio 2022 extensions: The Wix toolset is required to build the Add-in installer package. It can be installed using the extension manager in Visual Studio. However, it must be accompanied by the installation of the Wix tool which can be downloaded here.
  • Enterprise Architect version 15.2 (or newer)

  After installing these tools, open the solution AddIn/Itemis_Integrate_EA_Example_AddIn.sln and build all projects contained in it. To register the built Add-in DLL with Enterprise Architect, run the script AddIn/Itemis_Integrate_EA_Example_AddIn\Install.bat. This script registers the DLL built by the IDE with Enterprise Architect as the Add-in. It needs to be run only once. When the Add-in installer is used, the DLL in the specified installation location will be used instead.

Contribute

We are always happy to see suggestions, bug reports, feature requests as well as pull requests. Please feel free to raise an issue or contribute with a pull request.

Further information

The Itemis INTEGRATE-EA adapter has a free 30-day trial period which can be used with models containing up to 1000 elements.
The Itemis CREATE code generator also has a free 30-day trial period. Please use the Contact forms on the Websites for specific questions related to these components.