Remote Model Documentation

DETAILS: Remote Model Documentation

(Details - Use - Extend)

This building block is designed as an add-on mechanism to simplify integration of reporting functionality into your modelling tool. The idea is to have the reporting mechanisms centrally maintained and deployed on a server, while each and every client can interact with this engine through a thin AdoScript-based client. This applies, on one hand, on the generation itself, on the other on configuration of additional reports and formats.


The idea  of implementing this building block is to enable a remote mechanism for documentation generation. This means that the mechansim is not available within the tool itself, but rather only the interaction logic is implemented. Reports and documentation artifacts are centrally maintained on a dedicated documentation server. The advantange of the approach is that, even after packaging, deployment and installation at multiple users, the method engineer can dynamically add, remove, or update new formats available the next time the modeller uses the mechanism.

Consider that the current implementation only provides formats that are independent of your modelling language.

Example report formats


This remote characteristic of this building block is two-fold:

  1. Configuration items: the configuration of reports is exchanged between the modelling toolkit and server. This means that the reports format and models, respectively, model structure is dynamically retrieved.
  2. Generation: The generation is done on the server, including a report storage mechanism that the administrator has an overview on the usage and trace reports run by the modellers. Access to the reports can be offline or online (based on the report storage part, the modeller can re-generate at any given point in time, directly from the server).


The building block is realized using Apache Cocoon as a transformation framework. Available transformation pipelines are made available via a registry, exposed as a webservice. The registry provides dynamic configuration parameters to the client (report format, model selection mode) and triggers the necessary pipeline when requested. Apache Cocoon enables a modular implementation of transformations (so called "blocks"), whereas each block is a seperate Maven project.


For the RemoteDocumentation service one block is defined (it can be run in debug mode without any further work). This block is added as a Maven dependency to the WebApplication project. The figure below provides an abstract view on the block available for the documentation service.

Interaction View

From an interaction perspective, the building block enables the generation flow by providing the necessary pipelines/matchers to the client. The AdoScript client allows the integration in ADOxx-based modelling tools in 4 steps, from the registry retrieval to download and storage of the report.

A detailed explaination on the pipeline and its functionality can be found in the extend section for this building block.


Apache Cocoon 2.2, incl. Tutorials and First Steps Documentation

Extension Ideas