Managing and creating process documentation templates¶
You can create custom templates generate process documentation that suits your organization’s individual needs.
For example, you can...
- ...create an overview of all BPMN 2.0 process diagram tasks in your diagrams.
- ...create a matrix with all dictionary entries linked in the diagrams.
- ...create a detailed overview of the element usage in your diagrams.
Not only the content of process documentations can be configured, but also their visual properties.
Process documentation templates are stored in the Process documentation templates folder. This folder will appear on the left side of the Explorer as soon as you activate the process documentation templates as described below.
Activating the process documentation templates¶
Follow these steps to activate the Process documentation templates folder in the Signavio Explorer’s navigation panel:
- Click Setup, then Show process documentation templates in the top drop-down menu of the Signavio Explorer.
The menu entry for editing process documentation templates.
- Select the folder Process documentation templates on the left:
Open the process documentation templates folder.
The process documentation templates that were created before will now be displayed.
Editing process documentation templates¶
A newly created process documentation template consists of three different parts that now need to be filled with content:
- A cover page
- A table of contents
- Content pages, containing the actual process documentation
Shapes are dropped into the different sections by drag and drop from the shape repository on the left. The shapes are further adjusted by altering their attributes in the attributes panel. When creating the template, the elements are filled with the information that the selected diagrams will provide.
You can also alter the color and style of certain kinds of information only in the toolbar, not in the attribute panel. Just click the text format button. This can be helpful to easier distinguish different sorts of information in a list-based section.
Many shapes have similar general attributes that can be set in the attribute panel. These will be explained here. Other, shape specific attributes will be explained in the section about the corresponding shape.
- Color - You can change the background color of a section, sometimes also the color of a label. You can either choose a color from the color pallet or define a hexadecimal value.
- Label - Many shapes have a label that will stand in front of a value (for example Organization: [name of organization]). You can define whether a label should be displayed (check/uncheck the box ‘Show label’) and what the label should be by configuring the corresponding attributes.
- Show Label - Define if the label shall be displayed for the element by checking or unchecking the box.
- Hide page header/footer - Available in the More Attributes section of all sections - check or uncheck the box to hide the header or footer for the whole section.
- Display - Here you can choose whether you would like the information to be displayed in a list or in a table.
Designing the cover page¶
The cover page has a header and a footer, two spaces for content and the document title in the center of the page.
You can configure the following attributes for the cover page section by clicking onto the page and opening the attribute panel:
- Title - Configure the title of a process documentation (per default, it is set to ‘Process Documentation’).
- Subtitle - An explanatory subtitle (in the example below it is “Business processes 2012”)
- Show a separator - When a subtitle is given, it can be separated optically by a horizontal line.
- Alignment - The title and subtitle can be aligned left, right or center. This option only affects the text on the cover page.
The two empty areas can be filled with an Image or one or more Template Parameter shapes.
- Each Template parameter shape, available in the Document Structure header in the shape repository, contains information about the process documentation file in general. In the attribute panel, you can define which kind of information should be displayed. You can choose between Organization (default), Author, Date or Version of the documentation. You can put as many shapes of this kind into one section of the page as required.
- The Image shape for the cover page is available in the Static Contents section of the shape repository (adding the picture shape from the ‘header and footer’ section is not possible). Then you can can resize and shift the image by altering the template element. You can add a picture from your computer or from the Signavio workspace by clicking Image - ‘...’ in the attributes panel.
Drag a template parameter from the shape repository to the cover page...
...and configure its type in the attribute panel.
Designing the table of contents¶
The table of contents is created and updated automatically. You can deactivate the automatic updating during modeling by unchecking the box of the attribute Preview. As soon as the Preview is re-activated, the table of contents is updated. You can also change the title, by default ‘Table of Contents’.
Activate the live preview of the table of contents.
Designing the documentation: Chapters and sections¶
Before you can add any variable shapes to the content section, you need to add a chapter/section template shape. If you drop another chapter into a chapter, a sub-chapter will be created. If you drop a chapter below another chapter, a new chapter will be created. In case you don’t need an elaborate chapter structure, you can simply place a per Diagram or a Folder structure element. These are needed as a container for information elements on diagram and element level. Chapters and sub-chapters can be named and will be numbered and added to the table of contents automatically.
When you added a chapter, you can place static information elements. These elements do not need a container. Static information can be defined in the attribute panel and does not change with the diagrams a handbook includes.
A static attribute can for example be a disclaimer, a chapter overview, an image or a table. You can put text directly into the table by double clicking it. Note that a table can contain a header or a footer.
You can enforce page breaks, for example after large chapters, by placing a Page Break element.
In the attributes panel, you can choose between the numbering style of the chapters (Arabic numbers (default), Roman numbers or bullet points) for the whole section. You can also define if the corresponding chapter should be listed in the table of contents and if the numbers are displayed or hidden.
When configuring the display of dynamic diagram information, you can either use a chapter per diagram with the Per Diagram element or use the Folder Structure element to create a chapter per folder (with a sub chapter for each diagram). In any case, the order of the diagrams is aligned to the folder structure.
Drag a Chapter/Section element from the shape repository...
...and drop it onto the following page.
Now you can start adding content shapes to the corresponding structure shapes.
Similar to attributes, there are two different kinds of information shapes you can include: diagram level information and element level information.
A chapter can contain different elements. E.g., the chapter “Introduction” could contain a Free Text element as the introduction text. Drag the Free Text element from the section Static Content in the shape repository to a chapter:
Add free text to the introduction template.
This template element creates a new chapter for each diagram. The Folder Structure element would additionally create subsections for sub folders.
It is possible to create dynamic content based on the diagrams a process documentation is created for. Dynamic content is kept in the Per Diagram element.
Dynamically created chapters will get a small loop symbol on their upper right corner in the template. You can easily combine static and dynamic chapters by e.g. dragging a Chapter/Section element onto a Per Diagram element.
In the following example, the chapter “Diagram overview” will contain a picture of each diagram:
- Drag a Per Diagram element into the appropriate chapter:
The per diagram element creates a new chapter for each exported diagram.
When exporting the process documentation, the per diagram element will create a (sub-)chapter for each diagram that is included in the report.
Drag a Diagram Image into the per diagram element on the canvas. Diagram specific elements like such an image can be found in the Diagram Details section of the shape repository:
A diagram graphic will be displayed for every exported diagram.
The Diagram Details section contains elements that compose information about the whole diagram, such as diagram attributes and an overview of special modeling element types. Drag those into the chapter to display such information.
To enhance readability, it is recommended to create a sub-chapter for each list.
For example, to display an Attribute on diagram level for each diagram, follow these steps:
Drag an Attribute on diagram level into the Per Diagram element and click Attribute in the attribute editor.
Select attributes that will appear in the diagram overview.
A dialog opens and you can choose the diagram attributes to be displayed:
Select the attributes for the various diagram types.
The section Element details in the shape repository allows you to create tables and lists of certain types of elements and selected attributes. You can learn more about this type of shapes in the section Shapes on element level
Adding shapes on diagram level¶
The information shapes on diagram level will be displayed for each diagram - the sections will be ordered as you defined earlier. Shapes that can be put here are:
Information about the diagram - displays one of the diagram attributes Author, Diagram type, Last modified, Link, Path, Revision number, Last author, Publishing status, Publishing date or Authors (all people who worked on the diagram), which can be chosen in the attribute panel. You can add more than one shape to display different attributes.
Diagram Image - creates an image of the diagram. The following attributes can be defined:
- Rotate defines if the diagram image should be rotated 90°. The default setting ‘Automatic’ rotates the diagram if it is too large to fit.
- Orientation defines in which direction a diagram should be rotated.
- If Stretch over multiple pages is activated, a diagram is printed in its original size, over multiple pages if necessary.
Attribute on Diagram Level - displays one attribute on diagram level that you can choose in the attribute panel by clicking the value for Attribute, then ‘...’. You can choose attributes from different notations. The shape Attribute on Diagram Level (Multiselection) lets you pick several attributes at once.
Process Participants - displays all roles that participate in the diagram. This can include pools & lanes, additional process participants and organizations that are linked in a dictionary entry. You can choose whether pools, lanes and (what kind of) additional participants should be listed (Depending on their RACI property) in the attribute panel.
Data Objects - lists all data objects in the documented diagram(s)
IT Systems - lists all IT systems in the documented diagram(s)
Process Triggers - lists all start events. You can choose if only labeled events shall be listed in the attributes panel.
Process Results - lists all end events. You can choose if only labeled events shall be listed in the attributes panel.
Linked Dictionary Entries - lists all linked dictionary entries. You can choose what categories shall be listed and if additional information about the entry shall be displayed in the attribute panel.
Linked Diagrams - lists all linked diagrams
Document Revisions - lists all revisions with information about version number, date, editor and what was altered. In the attribute panel (Limit) you can define the maximum number of revisions displayed (default: 10).
Adding shapes on element level¶
Information shapes on element level require another kind of sorting shape as diagram elements will be listed in a certain way here. You have to choose between a table or a list view. If you add for a table, for each new information a column will be added for the table.
Before you add content to this section, you must add a Table of Process Elements or a List of Process Elements to the documentation template. To change the displaying method later, alter the value of the Display as-attribute.
The new element will function as a frame to display element-based information. The columns ‘Name’ and ‘Responsible’ are created by default. Now you can drag and drop ‘Element Details’ shapes into the table/list. A column will be added for each new shape. A Table/List of Process Elements will be created for each diagram contained in the report.
Drag a Table of Process Elements from the shape repository and drop it onto a chapter:
Add a process element table to a per diagram element.
You can configure the following properties of a table/list of process elements shape in the attribute panel:
- Diagram element types - choose elements that are supposed to be displayed for each modeling language or notation.
- Numbered - define whether the elements should be numbered.
- Ignore unnamed elements - select whether to ignore or list unnamed elements.
- Sorting - element information can be sorted by diagram and process flow or alphanumerically by element type and label.
- Display as - Choose between list and table.
Add an attribute to the table.
To delete a column, select it and use the tool bar button Delete or press the delete key on your keyboard.
Select the attribute type.
The following elements can be dragged into a table as a column:
- Attribute on element level - Select an attribute whose value will be listed for each element in the diagram. A dialog will open, allowing you to configure the selection.
- Attribute on element level (multi selection) - Select multiple attributes whose value will be listed for each element in the diagram. A dialog will open, allowing you to configure the selection.
- Process Participants- Insert a column that displays the element’s process participants (organizations, departments or additional participants).
- Data Objects - Insert a column that displays the data objects that are connected to the element.
- IT Systems - Insert a column that displays the IT systems connected to the element.
- Linked dictionary entries - Insert a column that displays all the dictionary entries linked to the element.
- Element type - Insert a column that displays the element type. The resulting table could look as follows:
an element overview table
an element overview list
This example table contains the name, the responsible role and documents that are connected to each element of the diagram:
An element overview table
Defining multiple languages for templates¶
It is possible to define multiple languages for diagrams in the Process Manager. This feature is also available for templates.
If multiple languages are defined for you workspace, a little flag symbol in the upper right corner of the template editor will allow switching the language of the template content:
Change the content language.
Elements that are not available in the selected language will be highlighted. By clicking their title, you can translate them:
The subtitle of the cover page has not been translated, yet.
The original language will be displayed in the attribute editor. elements can be translated here:
The subtitle is translated in the attribute editor.
If templates were defined in multiple languages you can choose the desired language each time a process documentation is created.