A real example: the 'Use case catalog' template

In order to get familiar with template building, let’s examine one of the predefined templates, the "Use case catalog" template. In our template classification, this template is meant to be an overview analysis template, like "Requirements" or "Process", as opposed to technical reference guides like "Class Reference" or "Diagram Reference".

The "Use case catalog" template can be applied to Packages, and provides an overview of all the actors and use cases of the system. For each use case, a detailed description of its content is added. Interactions contained in use cases are described as scenarios.

Dividing into procedures

When creating a template, it is important to think about the different parts of the document you want to generate, and to break down your template according to those parts, in order to make the template development and maintenance easier.

Let’s start with our example’s main organization, procedures.

Keys:

The root node shows the name of the template, and contains the main sections as well as calls towards the procedures.
The first procedure, " ProcGetActors ", produces a table showing all actors involved in the system.
The " ProcGetUseCases " procedure produces a table showing all use cases involved in the system.
The " ProcGetUseCasesDiagrams " procedure generates the use case diagrams.
The "ProcDetailledUseCases" procedure is used to generate all information about use cases and references towards scenarios .
The last procedure, "ProcGetSequenceDiagram", is used to add a list of scenarios and details about each scenario .

Main sections

Section nodes in the template define the organization of the generated document, visible in the table of contents.

Each section node indicates its own style, therefore generating the proper section level.

An "anchor" for links is also created automatically for each section, allowing reference nodes producing hyperlinks to target the proper area.

Please note that nodes have been renamed to show their use instantly without selecting them.

Actor & use case tables

In this part of the template, we see two similarly built procedures, generating the tables presenting all the actors and use cases.

Creating a table in a template requires:

A table node ( "ListOfActors" in this example) indicating the number of columns and their titles
One or several navigation nodes, to gather the elements to be produced in the table (in this example, a node finder producing actors)
A table cell for each column, producing the content of the table (in this example, "NameOfActor" and "DescriptionOfActors")

Putting the navigation node between table and table cells allows the creation of those cells for each actor.

Please note that in the example above, the "DescriptionOfActor" cell is created only when the current actor has a description, due to the second navigation node.

Use case diagram production

This procedure is used to generate the use case diagrams in the document, in a specific section.

In all predefined templates, diagram generation is always preceded by the generation of the diagram’s description, as this is meant to describe what is presented in this diagram.

Diagram production requires:

A navigation node, to gather the diagrams
In this example, a section node is created for each diagram
A navigation node to get the diagram’s description, here it is a finder called "Find All UseCase Diagrams"
A paragraph to produce this description
A diagram node to insert the image, named "PictureOfDiagram" in this example

Detailed use cases

This procedure groups the content of the detailed use case section. The pattern for each part is simple:

Insert a subtitle ("Pre-Conditions", "Description"…)
Get a specific note ("Description", "PreCondition"…)
Generate the note content in a paragraph

The only exception is the actor part:

Gather all associated actors with a predefined navigation node
Generate them with a comma separated to keep them on the same line

Reference towards a scenario

At the end of the detailed use case section, a scenario subsection is created when interactions are found in the use case.

As before, a subtitle is added for each scenario, containing the description of the interaction.

The interesting part is the "See Also", which creates a hyperlink reference towards another section in the document containing the sequence diagrams from this interaction.

To create a reference, you have to:

Navigate on an element, here a sequence diagram (the example uses a metamodel navigation, "Foreach Sequence Diagram")
Create a paragraph like in this example ("SeeAlso"), or another container like a table cell, or a list entry
Create the reference inside
In the reference property page, on the right part of the template editor, add the production node to reference, usually a section node

The hyperlink will be created upon generation only when an "anchor" can be found for this model element. Otherwise only the element name is produced. "Anchors" are automatically created for section nodes, but you can manually add an "Anchor" in several other production nodes, using the "added to index" checkbox.

Please note that if a single element has several possible anchors in the same document, only the first one will be used upon generation.

Interaction table

This procedure of the "Use Case catalog" template generates the scenarios, created in the model as interactions in use cases.

The first part presents all use cases and their scenarios, with links towards the details of each scenario.

The interesting part is the "Scenario of Use Case" table cell. Unlike the actor table (see paragraph 5.3) described earlier, there are navigation nodes before and after the cell:

"Find All Use Cases" enables the creation of two cells for each use case.
The two other navigation nodes, "Foreach Interaction" and "Foreach SequenceDiagram", before the paragraph creation, are meant to create content inside the current cell rather than creating a new cell.

Please note that when a table cell has nothing to produce directly from the current element, but only in child nodes, the embedded paragraph should be deactivated. Otherwise, a useless empty line will be added in the cell before its real content.

Scenario details

The second part of the procedure generates the detailed scenarios. This is similar to use case diagram production:

Navigation nodes to gather sequence diagrams
In this example, a section node is created for each of them
Another navigation node to get the diagram’s description
A paragraph to produce this description
A diagram node to insert the image