Capella Add-ons: Collaborate better + Generate Docs
When Capella was made open source in 2014, feedback was collected from early users and adopters. The feedback showed several topics were important to the open source community.
First and foremost, users wanted to learn how to efficiently collaborate on a single Capella model and minimize configuration and version management problems.
Second, users wanted to generate their documentation efficiently. How could they import and export excel data, generate HTML reports and rich documents?
In order to meet users’ demands, Obeo and Thales developed a number of Capella add-ons, including two key extensions that are described in this article, Team for Capella and M2Doc.
Team for Capella
Team for Capella, a commercial offer proposed by Obeo, is a tool to achieve real-time collaboration on Capella models with fine-grained lock management. Users starting out with Capella, quickly find themselves facing the problem of sharing files between multiple users who are collaborating on the same model. Whatever strategy are used to address the problem they inevitably cost time and effort, as users have to wait for others to complete their work or manage comparison and merge processes.
To remedy this waste of time, Team for Capella provides a shared repository that allows users to simultaneously edit the same model.
The scope of Team for Capella is to manage collaboration on Capella models. It is not a tool intended to manage versions and configurations, only a tool that supports collaboration.
The actual collaboration process is quite simple. Once a user modifies a model, a green lock is displayed on the user’s screen indicating that the element is now locked. Simultaneously, other users will see a red lock appear on their screens indicating that somebody else is modifying that element. However, these other users can still modify objects that aren’t locked. When the original user saves the model, other users are instantly notified of the changes and can refresh their diagrams to see the latest changes.
Furthermore, if a user intends to work on a package or a dedicated portion of the model and doesn’t want anyone interfering on it for a period of time, then that user can lock the whole portion of the model and work on it individually.
Administration tools are also available for administrators to manage locks, back-ups, and so on.
The release date of Team for Capella 1.2 is expected for January 2018 and will be compatible with Capella 1.2. Each year, Obeo releases at least one major and one minor version of Team for Capella.
M2Doc
Developed by Obeo, M2Doc is a recent open source document generation solution that works with Capella. It provides Capella users with the ability to generate MS Word™ files from their models.
Let’s start by asking ourselves why users produce documentation. They do for two main reasons.
- First, they need to deliver information to people who will not use Capella models.
- Then, they have to fulfil certain company obligations that require the production of many documents.
Document generation can also be useful in many other circumstances, like facilitating model reviews for example.
In any case, the generated documents have to reflect the current state of the model(s) being used so that they remain the sole reference point.
With M2Doc, users can generate the documents they need by applying their own templates to their models. M2Doc users can also apply the same template to different models, as well as different templates to the same model in order to generate different types of documentation, with each template being used to address a particular aspect of the model. Templates and generated documents use the MS Word™ docx (OOXML) format, which is the only format currently supported.
Three roles are involved with the documents generation process.
First, the end user simply uses M2Doc to generate documents after having worked on the model. End users may need to enter and maintain “user text” in some generated documents where text cannot be generated by the models. M2Doc supports this kind of incremental generation.
Second, the template author creates M2Doc templates in the OOXML format (Office Open XML), and for that he will use AQL (Acceleo Query Language) services. This role requires some knowledge of Capella metamodels. The template author also has to test and debug templates before making them available to end users. M2Doc supports this work and helps with developing templates by providing accurate and relevant error detection.
Finally, a Capella expert may sometimes be needed to provide reusable AQL services to template authors. These services can capture complex navigations and logic, and facilitate the creation of robust templates. Capella Experts require advanced knowledge of Capella metamodels as well as a good working knowledge of java development. No prior knowledge of AQL syntax is required to create AQL services.
M2Doc is an easy and smooth user experience for both the end user and the template author. Its syntax is quite simple and the tool provides a lot of support in terms of template creation. Maintenance is efficient and it includes powerful and reliable error reporting. Errors are accurately indicated in the file at the location of the error. Last but not least, M2Doc offers high production performance, generating hundreds of pages of documentation in just a few seconds.
The latest version of M2Doc 1.0 is available on its new official website, and is compatible with the current Capella 1.1.2 as well as the next 1.2 release.
Other add-ons
As explained in the introduction above, other add-ons exist to cover other user needs, including:
- The Requirements add-on, which enables the import of a set of requirements from a ReqIF file.
- The System to subsystem transition add-on, which initializes a new Capella project from an existing model. This transition extracts suitable model information from a selected Capella Component and manages top/down update propagation. The automated and iterative transition between system and subsystems is a great help for managing several levels of engineering. The contract and model of the subsystems are computed from the system. Ideally, subsystems stakeholders are involved in co-engineering activities at system level before the transition occurs.
- The XHTML Document Generation add-on enables the generation of an HTML website from a Capella project. Sharing models with all stakeholders is essential in model-based systems engineering. Publishing and sharing HTML versions of models helps make models the reference in all engineering activities.
Links
About the Author
