Due to its capability to give access to all element attributes stored in the object model, the Attribute Explorer is one of the most important and central modules of the Process Modeler. Some of the attributes behave dynamically, meaning that their visibility is dependent on the value of other attributes.  All BPMN 2.0 attributes are supported with drop-down lists and value constrains.

The Attribute Explorer can be displayed by right mouse click on the element-> Attribute or in the Process Modeler BPMN->view ->Attribute.

Entering Documentation

You can enter documentation by using the predefined elements (divided into the sections User Attributes, System Attributes and BPMN Attributes). The simplest way of documenting is using the documentation attribute, shown in the above picture.

Text Documentation

The documentation attribute provides a text area where you can enter plain text or rich text. Choosing plain text always leaves the entire text inside the BPMN XML whereas if you choose to enter rich text a MS Word file (.rtf) is generated and referenced from the BPMN XML. Rich text provides you with the advantage to enter formats (like italics and table definitions) and you can edit the text either in the Attribute Explorer or with Microsoft Word.

References and Hyperlinks

If you already have a series of documents outside of your BPMN diagram you can either reference these documents or set hyperlink to them.

Referencing a document will import a document and save it in the same place as the diagram itself (Team Repository or file system). To reference documents just add a new user defined attribute (UDA) of type Documents and add your documents there.

A hyperlink (to locations in the web or a file system) can be added either in the systems defined attribute Hyperlinks or you can add hyperlinks on a UDA of type Documents.

This feature allows you to create a customizable process documentation.

The process documentation facility may be launched using either the main menu Process->Diagram->Document… or the appropriate context menus of a specific process level (Process Level->Document…), a group of selected shapes (Group->Document…) or a single shape (Element->Document…).

Where to use attribute variables?

Attribute variables may be used in Microsoft Word templates, in Doclets or as an argument in the sort parameter of a Document Pattern. Within a Word template, only the attributes of the Diagram may be used. For example:

%%Bpmn.Diagram.Name%%

There are three different types of attributes that may be used within a Process Documentation: BPMN, System Defined and User Defined Attributes.

A variable referring to an attribute always has the following syntax:

[AttributeType].[ElementType].[AttributeName][(;parameter)*]

AttributeType is one of

• Bpmn
• System
• User

ElementType is one of:

• *
• Diagram
• StartEvent
• IntermediateEvent
• EndEvent
• Task
• SubProcessCollapsed
• SubProcessExpanded
• Gateway
• SequenceFlow
• MessageFlow
• TextAnnotation
• Assocation
• DataObject
• Group
• Pool
• Lane
• DataObjectReference
• DataStore
• CallActivity
• DataAssociation
• DataInputAssociation
• DataOutputAssociation
• DataInput
• DataOutput
• Message
• BoundaryEvent

The wildcard asterisk (*) indicates that an attribute variable is not depending on its Element Type.

Note: If a Doclet is only used for one Element Type (e.g. Task), it is good practice to set the ElementType to Task. If a Doclet is shared by several Element Types, the wildcard asterisk (*) may be used as ElementType.

For example:

%%Bpmn.*.Name%%

%%System.*.Hyperlinks%%

AttributeName is the name displayed in the Attribute Explorer for an attribute. Subsequent attributes are separated by a dot (.). The AttributeName can also be an empty string or an asterisk (*). For this case, all User Defined Attributes are processed.

Examples:

User.*.A.B refers to the User Defined Attribute B within the User Defined Attribute A.

User.*.* refers to all User Defined Attributes of a BPMN element.

Hidden attributes:

• Graphics[;ignoretext|ignoreoutertext][;expand][;ignorenumber] (this attribute can be used to insert a graphical representation of an element. To ignore the text of the graphic, use on of the optional parameter; ignoretext ignores the text for all element types and ignoreoutertext ignores the text only for Event, Sequence Flow, Message Flow, Gateway and DataObject). The parameter expand only affects Sub-Processes. For an Expanded Sub-Process, the whole content is included in the graphic too and for a Collapsed Sub-Process, the referenced Process Level will be inserted as graphic instead of the Collapsed Sub-Process itself. The optional parameter ignorenumber indicates to ignore the element number on the graphic)
• ElementType (this attribute can be used to insert the type of an element (e.g. Task))

Example:

Bpmn.Task.Graphics;ignoretext;ignorenumber refers to the graphical representation of the BPMN element without the description text and without the element number.

Bpmn.*.ElementType refers to the element type of a BPMN element.

Parameters

A parameter has the following syntax:

<parameter> := [;{name|type|description|recursive}][;showborder][;hyperlinks][;default=”default-value”]

The following table shows all parameters that are usable for attribute variables. Those parameters never have a value.

Examples:

%%Bpmn.*.Name;name%%

%%User.StartEvent.A.B;recursive;showborder%%

%%System.*.number;showborder%%

%%Bpmn.Diagram.CreationDate;type%%

%%User.*.*;hyperlinks;default=”<value is empty>”%%

This section describes how to use Document Patterns to create a Process Documentation. Each pattern defines, how BPMN elements are traversed and what structure they deliver to the process documentation. To use a pattern in a Word template (*.dot, *.dotx) file, a predefined variable starting and ending with %% must be defined.

Syntax:

%%PATTERN;type=<type>[;<parameter>]*%%

<parameter> := <name>=<value>

Example:

%%PATTERN;type=generic;recursive=true;elementfilter=4,5,6,7%%

Used in a Word template, the process documentation feature will replace this pattern with attribute values of the selected elements.

Example:

For each Document Pattern, several of parameters may be defined. Each parameter has to be separated by a semicolon (;). The following table shows all common Document Pattern parameters:

The following sub-chapters describe each pattern and how it may be configured.

Generic List Pattern

This pattern is used to create a simple (non-hierarchical) list of BPMN elements. Each element is treated as a row in a table.

Syntax:

%%PATTERN;type=generic[;parameter]*%%

Parameters:

This Document Pattern has no additional parameters to the common parameters.

For example to create a generic list with all BPMN DataObjects sorted by the Name attribute values in ascending order:

%%PATTERN;type=generic;sort=Bpmn.DataObject.Name[asc];elementfilter=12%%

Activity Pattern

This pattern is used to create process documentation containing only activities. The optional parameter hierarchical indicates that for each activity contained in a Sub-Process, a new hierarchy will be created in the document.

Syntax:

%%PATTERN;type=activity[;parameter]*%%

Additional known parameters:

Pool Pattern

This pattern shows the relationship between a pool and its content. There exist an additional parameter message. If this parameter is enabled, also all incoming and outgoing message flows are documented.

Syntax:

%%PATTERN;type=pool[;parameter]*%%

Additional parameters:

Lane Pattern

This pattern shows the relationship between the Lanes and its content. The optional parameter hierarchical indicates that the complete Lane structure needs to be documented in hierarchial order.

Syntax:

%%PATTERN;type=lane[;parameter]*%%

Additional parameters:

Graphics Pattern

This pattern is used to insert the Visio sheets as image into the process documentation. Without parameters, all sheets will be inserted, regardless of any current selection. It simply lists all sheets as bitmaps.

Syntax:

%%PATTERN;type=graphics[;parameter]*%%

Additional parameters:

Except the description parameter, all common parameters have no influence on the created output of this pattern.

The main purpose of the documentation wizard is to simplify the template creation and modification. The templates used for the creation of the process documentation contain different patterns which are used for the output generation. These are in turn mapped to the specified doclet files. The wizard allows the user to mange templates in the process documentation root directory, manage or edit the template patterns and set the mappings for the existing patterns inside the working template.

The wizard is accessible from the process documentation dialog by simply clicking the documentation wizard button. The first view of the wizard form shows the found template files.

Each created document is based on a Microsoft Word template (*.dot, *.dotx) containing directives on what kind of process information should be created. These directives may refer to one of five different Document Patterns currently implemented. Each of these patterns is configurable to your needs. The following section describes all patterns and shows how they relate to the process documentation creation procedure.

Besides using the mechanism of Document Patterns, which conceptually represents a certain level of indirection, to insert attribute values, it is also possible to directly insert variables into a Word template referring to diagram attribute values.

For example, the variable %%Bpmn.Diagram.Name%% will insert the diagram’s name. Which attribute variables exist and how to use them is described here.