Learn

MTT Overview

This section gives an overview of the MTT to put the overall process into context. The figure below shows the key components:

• Model loaders. The default modelling tool is Sparx EA and the provided loader for its exported XML format. Any modelling tool that can export an information-model can be used and loaded into the MTT internal model, via a custom model loader.
• Internal model. The internal model provides the secret-sauce that enables two key aspects which separate the MTT from traditional code generators:
  • Generators can be easily developed, using a range of widely-used programming languages and approaches.
  • Supports dependencies between information models, allowing a catalogue of models to be developed and re-used across projects.
• Output generators. Rather than developing models of a particular API or message standard, The MTT works on business information models that are agnostic to the output formats. It is the generators that provide the intelligent mapping from model to specific output. It is this approach that also enables relevant design best-practice and any house standards to be built into the generators.

Deployment

The MTT can be run either:

• Using the web service API Generation MTT, for GitHub based projects (or running the example projects). In this case it can also be integrated with GitHub Actions as part of CD/CI workflow.
• On local infrastructure, as a Docker container. In this case the MTT requires read/write access to project repositories that are mapped as Docker Volumes.

Projects

Projects are where the key inputs and outputs for the MTT are held. These are:

• The exported Information Model. The UML, or other, definition of the information types and relationships that is to be used as the requirements for the generation process. The library.xml file in the figure below.

• The mtt-config file. Which defines project-specific configuration information that is required for the MTT to run. For example: which loader to use, which generators are applicable to this project, any inter-project dependencies, etc.

• The config folder. Any project-specific loader or generator configuration. If many projects use common configuration files then these can be defined once and referenced from many projects mtt-config files.

• The generated folder. Where the generated files are written. Each projects mtt-config can define a different folder structure if needed. The MTT will create the folder structure as specified in the mtt-config file so does not need to be created manually.

• Other files and folders. The files and folders discussed above are either required or generated. However, other files and folders can be stored in the same repository. As shown below, the Sparx EA published html filles are stored in the model folder Library model and the generated markdown files are run through the MkDocs tool to generate a complete model documentation website Library documentation

This file structure and file contents are the same whether the project is hosted on GitHub or locally.

Local Projects

Local projects can be stored anywhere on a file system but it is recommended that a simple structure, similar to GitHub, is used with a repo-base folder and all MTT projects located under that. Unlike with GitHub repositories, maintaining version control through Git or similar, is a manual process and not managed by the MTT

GitHub Projects

MTT has a tight integration with projects stored in GitHub repositories and will manage retrieving the input files and storing and committing and output back to GitHub. Consequently, to run the MTT on a GitHub project requires the user to have a GitHub account and for the MTT to be registered as a GitHub application by the user/organisation. MTT can also be invoked directly from GitHub, using Actions, as part of a CD/CI workflow.

Running the MTT

This section describes the various steps in selecting a project, running the chosen generators and viewing the results of the generation process.

MTT Home page

The MTT Home page consists of two sections, Projects and Learn as shown in the figure and described below.

Projects

As described, Projects can be stored in either GitHub or Local repositories. Clicking on either of the 'Select Project' buttons will go to a page that has a drop-down of available MTT projects and a set of checkboxes to allow selection of the generators to be run. As shown in the figure below.

• Arthefacts Summary. If the automatic validation of the model does not identify any errors (as opposed to warnings) then the selected generators will be run. Once the run is completed, the Artefacts Summary page will be displayed (see the figure below). This page has two sections:
  • A Model Summary. This has drop-downs that show any warnings that have been identified in the model. Warnings should be addressed but are not serious enough to stop the generators from running. There is also a summary of the model provided.
  • A Generator Summary. For each generator that has been run, there is a summary of the artefacts that have been generated. Also, there is a means of accessing the generated artefacts. For GitHub projects, this is a hyperlink to the relevant folder. For local projects, because of browser security restrictions, rather than a link to there is an absolute path to the folder. This can be copied and pasted into a file browser to access the generated files.
• Error page. If the model validated has identified errors, that would cause the generators to fail, then the errors are displayed. Errors must be fixed before the MTT can be successfully run. These errors are often caused by missing dependencies or model sub-folders (rather than the model root folder) being chosen during export from the modelling tool.

Learn

Currently just this page, though this will be expanded to provide training on developing models suitable for use in generating valid and complete outputs.

Generators

Running one or more generators, over an information-model, to produce output files is the fundamental purpose of the MTT.

Existing Generators

There are a number of Generators currently available with the MTT but, as described below, tailoring or developing new generators is often needed for a particular application.

API Specification Generators

• OpenAPI Specifications. Generates an interface specification that complies to the OpenAPI standard.
• GraphQL Specifications. Generates an interface specification that complies to the GraphQL standard.

Schema Definition Generators

• AOCO (Common Services). Generates a set of Micro Format Definition (MGD) documents that conform to the AOCO standard. AOCO is a military standard, primarily used for exchanging information in command and control environments.
• Reversed. Generates a set of JSON Schema definitions that conform to the Reversed standard, which the MTT team invented to illustrate the generation of JSON Schema definitions.

Markdown Document Generators

• Information Model documenter. Generates a set of text documents that conform to the Markdown standard to document the input information-model. The generated Markdown documents can then be used as documentation on GitHub, for example, or run through tools such as Material for MkDocs to generate documentation websites.

Developing New Generators

As described in MTT Overview, a core design principle of the MTT Internal Model is to make adding new Generators, flexible, quick and easy.

However, creating a new Generator does require some key information to be available as described and illustrated below. The figure aims to bring out two key points, using the OpenAPI and Reversed standards as examples:

1. Dependencies between standards. As shown, the OpenAPI standard and the Reversed standard depend on the JSON Schema Standard and the JSON Standard for their syntax.
2. Generators must to conform to all relevant standards. As shown, both the OpenAPI and Reversed standards depend on the lower-level JSON and JSON-Schema standard, for the format (syntax) of the generated files, but it is the higher-level OpenAPI and Reversed standards that define the structure (semantics) of what the generators must produce.

Example Projects

There are four example projects that illustrate various aspects of the information models that input to the MTT process and the generated outputs. Both the information models and the generated outputs can be viewed on the Example Projects page:

• Library. This project covers most of the information modelling techniques that are relevant to MTT generators, including: Relationships (of various types, including Composition and Reflexive), Specialization (Inheritance), Association-Classes and the use of Stereotypes and Tags. As the name suggests, the subject-matter is about Borrowers (Adult and Junior), Books, Loans, Librarians, etc.

• Property Ownership. This project covers similar information modelling techniques as the Library project but is about Actors (People), Properties, Banks, Accounts and the relationships between them. The additional aspect this model illustrates is how to deal with relationships that are time limited. For example, period of ownership of a property.

• Personal Details. A simple representation of a Person type, the relationships between Persons and common other types such as Address. It is intended to be used by some other projects, such as Library, as a model dependency.

• Core Types. This project defines basic types, such as Integer, Float, String, etc. But it also has slightly higher-level types such as URL, URI, UUID, etc. It is intended to be used by most other projects as a model dependency.