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

  1. Each placeholder starts with $
    • For example $name is replaced by the name of the artifact
  2. 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
  3. 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
  4. 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=/guid= 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=/guid= All Name of the element identified by the mapping id or guid
$abbrev?id=/guid= All except Function, Service Abbreviation of the element identified by the mapping id or guid
$notes?id=/guid= All Notes of the element identified by the mapping id or guid
$link?id=/guid= 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=/guid= All except Function, Service Version of the element identified by the mapping id or guid
$phase?id=/guid= All except Function, Service Phase of the element identified by the mapping id or guid
$stereotype?id=/guid= All Stereotype of the element identified by the mapping id or guid
$status?id=/guid= All except Function, Service Status of the element identified by the mapping id or guid
$alias?id=/guid= All Alias of the element identified by the mapping id or guid
$created?id=/guid= All except Function, Service Date created of the element identified by the mapping id or guid
$modified?id=/guid= All except Function, Service Date modified of the element identified by the mapping id or guid
$repo-path?id=/guid= All Location of the mapped element in the repository tree
$input-params-string?id=/guid= Function, Service List of parameters of the method identified by the mapping id or guid
$return-type?id=/guid= 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=/guid=* 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=/guid= 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=/guid= List of operations of the element identified by the mapping id or guid

Collection item attributes:

| $name?id=/guid= | All | Name of the element identified by the mapping id or guid (if the element is mapped, it links to its page) |

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=/guid= 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=/guid= relationships?id= guid=&type=realization:outgoing
$realized-by/realised-by?id=/guid= relationships?id= guid=&type=realization:incoming
$uses?id=/guid= relationships?id= guid=&type=use:outgoing
$used-by?id=/guid= relationships?id= guid=&type=use:incoming
$depends-on?id=/guid= relationships?id= guid=&type=dependency:outgoing
$needed-by?id=/guid= relationships?id= guid=&type=dependency:incoming
$creates?id=/guid= relationships?id= guid=&type=create:outgoing
$created-by?id=/guid= relationships?id= guid=&type=create:incoming
$traced-to?id=/guid= relationships?id= guid=&type=trace
$associated-to?id=/guid= relationships?id= guid=&type=association

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=/guid=guid 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'