Manual
This document describes how the generated content of the page can be controlled using placeholders that are replaced with data during page re/generation.
0. General Rules
- Each placeholder starts with
$
- For example
$name
is replaced by the name of the artifact
- For example
- Placeholders could be specified by various parameters which are included after the questionmark
?
- The parameters have a
key=value
form. - Example:
$name?id=15
- The individual parameters are separated by ampersand
&
- Example:
$modules?id=15&alias=value
- The parameters have a
- Guids are always used without the enclosing brackets
- If the EA guid is
{86712225-2F1E-4137-BD71-97881287E078}
, the generator expects?guid=86712225-2F1E-4137-BD71-97881287E078
- If the EA guid is
- If the placeholder allows both
<mid>
and<guid>
parameter:- For the Basic, mapping id cannot be used as this licence type does not support artifacts mapping
- For other licence types
mid
should be prefered as the generator will automatically detects the project associated with the mapping. When the guid is used, links always refer to the documentation pages.
1. General Page
General page is a general document which is not related to any specific artifact. It could be used to describe an overview, system specification or any other type of documentation. Unlike Artifact page, it has no underlying artifact associated, so all placeholders must include identification (mid
or guid
).
Examples:
- Artifact page:
$name
generates the name of the artifact represented by the page - General page:
$name?id=15
generates the name of the artifact associated with the mapping id 15
1.1 Variables
Variables are placeholders which are replaced by an element attribute. For example $name?id=15
is replaced by 'Customer Management System' which is the name of the element with mapping id 15.
Placeholder | Applicable on | Replaced by |
---|---|---|
$name?id= |
All | Name of the element identified by the mapping id or guid (if the element is mapped, it links to its page) |
$name-no-link?id= |
All | Name of the element identified by the mapping id or guid |
$abbrev?id= |
All except Function, Service | Abbreviation of the element identified by the mapping id or guid |
$notes?id= |
All | Notes of the element identified by the mapping id or guid |
$link?id= |
All | Link to the element identified by the mapping id or guid. If it is identified by mapping id, link goes to the documentation page or project page depending on the mapping. If it is identified by guid, link goes to the documentation mapping. |
$version?id= |
All except Function, Service | Version of the element identified by the mapping id or guid |
$phase?id= |
All except Function, Service | Phase of the element identified by the mapping id or guid |
$stereotype?id= |
All | Stereotype of the element identified by the mapping id or guid |
$status?id= |
All except Function, Service | Status of the element identified by the mapping id or guid |
$alias?id= |
All | Alias of the element identified by the mapping id or guid |
$created?id= |
All except Function, Service | Date created of the element identified by the mapping id or guid |
$modified?id= |
All except Function, Service | Date modified of the element identified by the mapping id or guid |
$repo-path?id= |
All | Location of the mapped element in the repository tree |
$input-params-string?id= |
Function, Service | List of parameters of the method identified by the mapping id or guid |
$return-type?id= |
Function, Service | Return type of the method identified by the mapping id or guid |
$image?id= |
All | Artifact image identified by the image id |
$diagram-image?guid= |
All | Diagram image, diagram identified by its guid |
$tag:aaa?id= |
All | Value of the tag 'aaa' of the element identified by the mapping id or guid |
$tag:aaa
- $tag:aaa - aaa is not enclosed in apostrophes and can consist only of alphanumeric characters
- $tag:'I\'m a tagged value' - tagged value name is enclosed in apostrophes, can include any character, apostrophes and backslashes must be escaped by backslash
$image
Placeholder parameters:
Parameter | Value | Default Value | Meaning |
---|---|---|---|
$source* | ftp/confluence | confluence | 'Ftp' only replaces the placeholder with the link to the image on the ftp server. 'Confluence' generates the image, attaches it to the page and replaces the placeholder with it. |
$width | Number | Original width | New image width |
$clickable | true/false | true | If it is clickable the element description is displayed on mouse over. |
Image update
- Confluence: regenerating page does not update the image. To update the image, replace the generated image by the image placeholder and regenerate the page. This will trigger uploading the current version.
- Ftp: image must be updated manually from the application
$diagram-image
Placeholder parameters:
Parameter | Value | Default Value | Meaning |
---|---|---|---|
$source | ftp/confluence | confluence | 'Ftp' replaces the placeholder with the link to the diagram on the ftp server (it is not generated or regenerated), 'confluence' re/generates the diagram, attaches it to the page and replaces the placeholder with it |
$width | Number | Original width | New diagram image width |
$clickable | true/false | false | Whether it should be possible to navigate to the element's artifact page and to the composite diagram by clicking on the diagram element. If the element is not mapped, it is not made clickable as there is no page artifact page to display. If the child diagram page does not exist, it is then created. Otherwise the existing page is referenced. |
$auto-update | true/false | true | Diagram will be regenerated and reuploaded when the containing page is regenerated. |
$max-depth | 0-5 | 0 | How deep it should be possible to navigate through composite diagrams. Works only if clickable=true. '0' means diagram pages will not be created for child diagrams but it still will be possible to navigate to artifact pages. |
$project-id | Number | -1 | Only elements with the specified project mapping will be cklickable |
1.2 Collections
Collections are placeholders which are replaced by a list of related entities. For example $attributes?id=15
is replaced by a list of attributes of the element with mapping id 15. It could be specified which attributes of the collection items should be generated ($.name
will generate the name of the collection item ) and how the list should be filtered ($modules?version=5
will generate only modules whose version attribute is 5).
Attributes
Placeholder | Applicable on | Replaced by |
---|---|---|
$attributes?id= |
Data Object, Data File, Table | List of attributes of the element identified by the mapping id or guid |
Collection item attributes:
Attribute | Replaced by |
---|---|
$.name | Atribute name |
$.type | Attribute type (and link to its classifier if it exists) |
$.notes | Attribute notes |
$.link | Link to the attribute classifier |
Filters
- Stereotype
- Alias
- Tag
Operations
Placeholder | Applicable on | Replaced by |
---|---|---|
$operations?id= |
List of operations of the element identified by the mapping id or guid |
Collection item attributes:
| $name?id=
Attribute | Replaced by |
---|---|
$.name | Operation name (if the operation is mapped, it links to its page) |
$.name-no-link | Operation name |
$.notes | Operation notes |
$.link | Link to the operation artifact |
$.input-parameters-string | Operation input parameters |
$.return-type | Operation return type |
Filters
- Stereotype
- Alias
- Tag
Tagged Values
Placeholder | Applicable on | Replaced by |
---|---|---|
$tags?id= |
All with tagged values | List of tagged values of the element identified by the mapping id or guid |
Collection item attributes:
Attribute | Replaced by |
---|---|
$.name | Atribute name |
$.value | Attribute type |
Filters
- None
Artifacts
Following placeholders generate a list of artifacts which are related to the artifact represented by the mapping id. The Relationship column specifies how the collection items are retrieved.
Placeholder | Relationship | Replaced by |
---|---|---|
$projects?id= |
Stored in the database | Projects which the artifact has mapping for |
$modules?id= |
Stored in the database | Modules of the given system |
$submodules?id= |
Stored in the database | Submodules of the given module or system |
$processes?id= |
Association | Processes which the artifact is associated with |
$requirements?id= |
Association | Requirements which the artifact is associated with |
$business-rules?id= |
Association | Business rules which the artifact is associated with |
$terms?id= |
Association | Terms which the artifact is associated with |
$use-cases?id= |
Association | Use cases which the artifact is associated with |
$actors?id= |
Association (going from the actor to the other element) | Actors which the use case is associated with |
$privileges?id= |
Association | Privileges which the artifact is associated with |
$activities?id= |
Association | Activities which the artifact is associated with |
$functions?id= |
Operations of the element (mapped as functions) | Functions which the artifact is associated with |
$services?id= |
Operations of the element (mapped as services), operations of its modules and submodulesof and operations of all its interfaces | Services which the artifact is associated with |
$interfaces?id= |
Stored in the database | Interfaces which the artifact is associated with |
$screens?id= |
Association | Screens which the artifact is associated with |
$documents?id= |
Association | Documents which the artifact is associated with |
$data-objects?id= |
Association | Data objects which the artifact is associated with |
$data-files?id= |
Association | Data files which the artifact is associated with |
$tables?id= |
Association | Tables which the artifact is associated with |
Collection item attributes:
Attribute | Replaced by |
---|---|
$.name | Artifact name (if the artifact is mapped, it links to its page) |
$.name-no-link | Artifact name |
$.notes | Artifact notes |
$.element-type | Element type |
$.artifact | Artifact type |
$.link | Link to the artifact |
Services and Functions Only:
Attribute | Replaced by |
---|---|
$.input-params-string | String representation of the input parameters |
$.return-type | Return type |
Services Only:
Attribute | Replaced by |
---|---|
$.interface | Name and link to the interface which owns the service |
Nested Collections:
Attribute | Valid for | Replaced by |
---|---|---|
$.attributes | Elements with attributes | List of attributes of this element. A list of fields can be set: $.attributes?fields=name,type,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
$.operations | Elements with operations | List of operations of this element. A list of fields can be set: $.operations?fields=name,input,output,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
$.services | Elements with operations | List of services of this element. A list of fields can be set: $.services?fields=name,input,output,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
$.functions | Elements with operations | List of functions of this element. A list of fields can be set: $.functions?fields=name,input,output,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
Filters
- All filters specified in Filters-Items except mapped-only since these collections contain only mapped artifacts
Relationships
A set of placeholders which are replaced by elements or artifacts that are in the specified relationship with the source element or artifact.
The basic placeholder is:
$relationships?id=<mid>&type=type:direction
$relationships?guid=guid&type=type:direction
The type attribute specifies which relationship types (for example associtation or trace) and which relationship directions (incoming or outgoing) will be included. The complete list of filtering options is included in the section Filters-Relationships.
Besides the basic $relationships
placeholder, there is a couple of shortcuts:
Relationship | Shortcut For | |
---|---|---|
$realizes/realises?id= |
relationships?id= |
guid= |
$realized-by/realised-by?id= |
relationships?id= |
guid= |
$uses?id= |
relationships?id= |
guid= |
$used-by?id= |
relationships?id= |
guid= |
$depends-on?id= |
relationships?id= |
guid= |
$needed-by?id= |
relationships?id= |
guid= |
$creates?id= |
relationships?id= |
guid= |
$created-by?id= |
relationships?id= |
guid= |
$traced-to?id= |
relationships?id= |
guid= |
$associated-to?id= |
relationships?id= |
guid= |
Collection item attributes:
Attribute | Replaced by |
---|---|
$.name | Relationship name |
$.stereotype | Relationship stereotype |
$.type | Relationship type |
$.direction | Relationship direction (incoming/outgoing) |
$.icon | Relationship direction represented by an icon |
$.element-name | Name of the element on the other end of the relationship |
$.element-type | Type of the element on the other end of the relationship |
$.artifact | Type of the artifact on the other end of the relationship |
$.link | Link to the artifact on the other end of the relationship |
$.tags | List of the relationship tags |
Filters
- All filters specified in Filters-Relationships
Package Content
Placeholder | Applicable on | Replaced by |
---|---|---|
$package?guid=guid | Package | List of elements in the package identified by the guid |
Collection item attributes:
Attribute | Replaced by |
---|---|
$.name | Element name (if the element is mapped, it links to its page) |
$.name-no-link | Element name |
$.type | Element type |
$.notes | Element notes |
$.link | Link to the artifact if the element is mapped |
Nested Collections:
Attribute | Valid for | Replaced by |
---|---|---|
$.attributes | Elements with attributes | List of attributes of this element. A list of fields can be set: $.attributes?fields=name,type,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
$.operations | Elements with operations | List of operations of this element. A list of fields can be set: $.operations?fields=name,input,output,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
$.services | Elements with operations | List of services of this element. A list of fields can be set: $.services?fields=name,input,output,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
$.functions | Elements with operations | List of functions of this element. A list of fields can be set: $.functions?fields=name,input,output,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
Filters
- All filters specified in Filters-Items
Input Parameters
Generates a list of the method input parameters.
Placeholder | Applicable on | Replaced by |
---|---|---|
$input-params?id= |
Method / Function, Service | List of input parameters for the given mapping or method guid |
Collection item attributes:
Attribute | Replaced by |
---|---|
$.name | Parameter name |
$.type | Parameter type. Links to the parameter type classifier if it exists. |
$.default-value | Parameter default value |
$.notes | Parameter Notes |
Filters
- None
Artifact Image Elements
Generates a list of image elements created using the built-in editor.
Placeholder | Applicable on | Replaced by |
---|---|---|
$image-elements?id= |
Screen,Document | List of image elements for the given image id |
Collection item attributes:
Attribute | Replaced by |
---|---|
$.number | Id of the image element |
$.name | Image element name |
Filters
- None
Diagram Elements
Generates a list of elements visible on the specified diagram.
Placeholder | Applicable on | Replaced by |
---|---|---|
$diagram-elements?guid= |
- | List of diagram elements. Diagram is specified by the GUID |
Collection item attributes:
Attribute | Replaced by |
---|---|
$.name | Diagram element name (if the element is mapped, it links to its page) |
$.name-no-link | Diagram element name |
$.notes | Diagram element notes |
$.element-type | Diagram element type |
$.artifact | Diagram element artifact in case it is mapped |
$.link | Link to the artifact represented by this diagram element in case the element is mapped |
$.tags | List of diagram element tags. Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
Nested Collections:
Attribute | Valid for | Replaced by |
---|---|---|
$.relationships | All elements | List of functions of this element. The same parameters and filters as for the standalone relationships table can be applied. A list of fields can be set: $.functions?fields=name,input,output,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
$.attributes | Elements with attributes | List of attributes of this element. A list of fields can be set: $.attributes?fields=name,type,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
$.operations | Elements with operations | List of operations of this element. A list of fields can be set: $.operations?fields=name,input,output,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
$.services | Elements with operations | List of services of this element. A list of fields can be set: $.services?fields=name,input,output,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
$.functions | Elements with operations | List of functions of this element. A list of fields can be set: $.functions?fields=name,input,output,notes . Important: the table is always regenerated from scratch so it is not safe to insert custom data in it. |
Filters
- All filters specified in Filters-Items
Modifiers
- project-id - defines how the artifact links will be generated. If no project id is specified, all links will go to the documentation pages. If the project id is specified, all links will go to the project mapping page - if the element is mapped within the specified project.
2. Artifact Page
An artifact page is a page that describes a single mapped element - an artifact. It can include the same placeholders as the general page, but also placeholders which generates data that are specific for the artifact.
For example, artifact page can include $name
placeholder. Such placeholder works solely in the context of the artifact so it does not require ?id=<mid>
and generates the artifact's name.
2.1 Variables
The use of variables is the same as for the general page, the following list shows just the differences.
Placeholder | Applicable on | Description |
---|---|---|
$name | See general page variables | See general page variables |
$name-no-link | See general page variables | See general page variables |
$abbrev | See general page variables | See general page variables |
$notes | See general page variables | See general page variables |
$stereotype | See general page variables | See general page variables |
$alias | See general page variables | See general page variables |
$version | See general page variables | See general page variables |
$phase | See general page variables | See general page variables |
$status | See general page variables | See general page variables |
$created | See general page variables | See general page variables |
$modified | See general page variables | See general page variables |
$generated | All | When the page was re/generated |
$repo-path | See general page variables | See general page variables |
$system-name | All | Name of the parent system (links to its page) |
$system-name-no-link | All | Name of the parent system |
$system-abbrev | All | Abbreviation of the parent system. |
$system-link | All | Link to the parent system. |
$module-name | All | Name of the parent module (links to its page) |
$module-name-no-link | All | Name of the parent module |
$module-abbrev | All | Abbreviation of the parent module |
$module-link | All | Link to the parent module |
$submodule-name | All | Name of the parent submodule (links to its page) |
$submodule-name-no-link | All | Name of the parent submodule |
$submodule-abbrev | All | Abbreviation of the parent submodule |
$submodule-link | All | Link to the parent submodule |
$interface-name | Service | Name of the parent interface (links to its page) |
$interface-name-no-link | Service | Name of the parent interface |
$interface-abbrev | Service | Abbreviation of the parent interface |
$interface-link | Service | Link to the parent interface |
$project-name | All, project mapping only | Name of the associated project (links to its page) |
$project-name-no-link | All, project mapping only | Name of the associated project |
$project-abbrev | All, project mapping only | Abbreviation of the associated project |
$project-link | All, project mapping only | Link to the associated project |
$doc-link | All, project mapping only | Link to the documentation page |
$input-params-string | See general page variables | See general page variables |
$return-type | See general page variables | See general page variables |
$image?id= |
See general page variables | See general page variables |
$diagram-image?guid= |
See general page variables | See general page variables |
$tag:aaa | See general page variables | See general page variables |
2.2 Collections
The use of collections is the same as for the general page, the following sections show just the differences.
Attributes
- $attributes
Operations
- $operations
Tagged Values
- $tags
Artifacts
Placeholder |
---|
$projects |
$modules |
$submodules |
$systems |
$processes |
$requirements |
$business-rules |
$terms |
$use-cases |
$actors |
$privileges |
$activities |
$functions |
$services |
$interfaces |
$screens |
$documents |
$data-objects |
$data-files |
$tables |
Note: If the collection is generated for the documentation mapping, then only items with documentation mapping are generated. If it is generated for project mapping, then only items with the same project mapping are generated.
Relationships
Relationship |
---|
$relationships |
$realizes/realises |
$realized-by/realised-by |
$uses |
$used-by |
$needed-by |
$depends-on |
$creates |
$created-by |
$traced-to |
$associated-to |
Note: If the collection is generated for the documentation mapping, then only items with documentation mapping are generated. If it is generated for project mapping, then only items with the same project mapping are generated.
Input Parameters
- $input-params
Artifact Image Elements
- $image-elements?id=id
Diagram Elements
$diagram-elements?guid=guid
3. Filters
This section describes how to control which collection items will be generated when collection placeholders are used. For example $modules
generates modules of the system, whereas $modules?version=5
generates only modules that have the attribute version set to 5.
3.1 General Rules
Multiple occurences of the same filter means logical OR
- Example:
modules?tag:aaa=bbb&tag:ccc=ddd
means that the collection will include only items that have the tag aaa=bbb or the tag ccc=ddd
Characters \,&,%,=,: must be escaped by backslash (do not enclose filter values in apostrophes)
- Example:
$systems?tag: c \:\\ \& '\=' %= c \:\\ \& '\=' %&id=82
- Example:
$systems?alias='''''&id=82
- Example:
$systems?alias="""""&id=82
- Example:
$systems?tag:'''''='''''&id=82
- Example:
$systems?tag:"""""="""""&id=82
3.2 Items
Filters specify what criteria the collection items must meet to be included:
Filter | Replaced by | Default Filter Value | Multiple Occurences Allowed |
---|---|---|---|
?mapped-only=true/false* | Include item only if it is mapped as artifact | False | No |
?tag:aaa=bbb | Include item only if it has tag 'aaa' with value 'bbb' | All Tags | Yes |
?tag-not:aaa=bbb | Exclude item if it has tag 'aaa' with value 'bbb' | No Tag | Yes |
?version=aaa | Include item only if its version equals 'aaa' | All Versions | Yes |
?phase=aaa | Include item only if its phase equals 'aaa' | All Phases | Yes |
?stereotype=aaa | Include item only if its stereotype equals 'aaa' | All Stereotypes | Yes |
?status=aaa | Include item only if its status equals 'aaa' | All Statuses | Yes |
?alias=aaa | Include item only if its alias equals 'aaa' | All Aliases | Yes |
?element-type=use-case | Include item only if it is a use case element | All elements | Yes |
?element-type-not=use-case | Exclude item if it is a use case element | No element | Yes |
?artifact=use-case | Include item only if it is mapped as use case artifact | All artifacts | Yes |
?artifact-not=use-case | Exclude item if it is mapped as use case artifact | No artifacts | Yes |
?project-id= |
Include item only if it has the given project mapping | Not filtered by project | Yes |
*Works only for documentation mapping. It generates items with documentation mapping or with no mapping.
**pid = mapping id of the given project. Works only for $diagram-elements
as for other collections, the project is associated with the mapping id (for project mappings) or it does not make sense to specify the project at all (for documentation mapping).
3.3 Relationships
Filters specify what criteria the relationships and/or the elements on the other end of the relationship must meet to be included:
Filter | Replaced by | Default Filter Value | Multiple Occurences of the Same Filter Allowed |
---|---|---|---|
?mapped-only=true/false* | Include item only if it is mapped as artifact (applies to documentation mapping only) | False | No |
?tag:aaa=bbb | Include relationship only if it has tag 'aaa' with value 'bbb'. Applies to $relationships not to shortcuts such as $uses. | All tags | Yes |
?tag-not:aaa=bbb | Exclude relationship if it has tag 'aaa' with value 'bbb'. Applies to $relationships not to shortcuts such as $uses. | No tag | Yes |
?type=type:direction** | Include relationship only it is of the specified type and direction. | All types and directions | Yes |
?type=type | Include relationship only it is of given type (all direction accepted) | All types | Yes |
?type-not=type:direction | Exclude relationship only it is of the specified type and direction. | No type | Yes |
?element-type=use-case | Include item only if it is a use case element | All elements | Yes |
?element-type-not=use-case | Exclude item only if it is a use case element | No element | Yes |
?element-tag:aaa=bbb | Include relationship if the element on the other end has tag 'aaa' with value 'bbb' | All tags | No |
?element-tag-not:aaa=bbb | Exclude relationship if the element on the other end has tag 'aaa' with value 'bbb' | No tag | Yes |
?artifact=use-case | Include item only if it is mapped as use case artifact | All artifacts | Yes |
?artifact-not=use-case | Exclude item only if it is mapped as use case artifact | No artifacts | Yes |
?element-stereotype=aaa | Include item only if its stereotype equals 'aaa' | All Stereotypes | Yes |
?stereotype=aaa | Include relationship only if its stereotype equals 'aaa' | All Stereotypes | Yes |
?element-alias=aaa | Include item only if its alias equals 'aaa' | All Aliases | Yes |
?alias=aaa | Include relationship only if its alias equals 'aaa' | All Aliases | Yes |
?project-id= |
Include item only if it has the given project mapping | Not filtered by project | Yes |
*See section 3.2
**Type or direction can be replaced with '*' which means that all types or directions will be included
***See section 3.2
Types:
Type | UML Relationship | Note |
---|---|---|
association | Association | Direction is ignored |
realization | Realization | |
dependency | Dependency | |
use | Usage | |
trace | Trace | Direction is ignored |
create | Dependency with create stereotype | |
controlflow | Control flow | |
informationflow | Information flow |
Directions:
- outgoing
-
incoming
-
Examples
$relationships?type=use:*
- shows use relationships, both directions$relationships?type=use:outgoing
- shows use relationships, only outgoing$relationships?type=*:incoming
- shows all incoming relationships$relationships?type=association
- shows all associations (direction is not relevant for associations)
- The other end of the relationship is also filtered - see the previous section for filter criteria
- Example:
$relationships?type=use:outgoing&version=5
- shows elements which are used by this artifact and have version '5' - Example:
$relationships?type=association&tag:aaa=bbb&element-tag:ccc=ddd
- shows elements associated to this artifact, the association must have tag 'aaa'='bbb' and the associated element must have tag 'ccc'='ddd'
- Example: