Managing and creating process documentation templates¶
Process documentation are comprehensive documents that can include diagrams as well as all element descriptions, and dictionary entries. They are created in Microsoft Word or PDF format.
You can create custom templates that suits your organization’s needs and later generate a process documentation based on such a template.
Through this function you have the possibility, for example,
- to create an overview of all BPMN 2.0 process diagram tasks in your diagrams.
- to create a matrix with all dictionary entries linked in the diagrams.
- to 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 in the folder tree on the left side of the Explorer if 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:
- Select in the menu bar under Setup the Show process documentation templates entry.
- Select in the navigation on the left the Process documentation templates folder.
Creating a new template¶
- To create a template, navigate to the template overview by selecting Templates in the folder tree on the left side of the Explorer.
If the template folder is not shown in the folder tree, you can activate the display as described above.
- Select in the menu bar under New the Process documentation template entry.
- Alternatively, you can also create example template and then customize this according to your needs. This allows you to retain many details that are included in the default template.
To create and edit new templates, you are directed to the Editor. Here, you can define the document structure, edit header and footer or specify diagram details. In the following sections you will learn how to configure your template.
Working with templates¶
Editing templates is similar to editing diagrams - elements are placed on the canvas via drag & drop and be customized via attributes, which you can edit on the right side in the attribute editor. The alignment of the elements is done mostly automatically.
If you create a new template the following default sections are applied automatically:
- cover page
- table of contents, which automatically updates itself in accordance with each edit.
- content pages, containing the actual process documentation.
You can then adjust the sections as needed, add new pages, or remove one of the standard sections.
- To delete a section, first select the element to delete, and then click in the menu bar Delete.
- In the panelon the left, under Document Structure all available elements are listed. To add an element, add an element, drag it on the canvas while holding the left mouse button.
- You can format labels of elements in the menu bar. Select the element and then click the text format button. Here, you can define font size and color. This can be useful to distinguish between various pieces of information that are displayed as a list from each other, or to highlight certain information.
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 picker 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.
If you want to use an already applied template in an other Signavio workspace, you can export it here. Templates are exported as Signavio archive SGX file and can easily imported in another workspace for reuse.
- Select the template file you want to export.
- Click in the menu bar Import/Export and then the Export Signavio archive (SGX) entry. The corresponding dialog opens.
- By default, the latest revision of each template will be exported. However, you can disable this option.
- Click Export. The selected template is downloaded as SGX-file.
The cover page¶
By default, when you create a new template, the first section is the cover page.
Cover page attributes¶
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.
In addition you can define template parameters for the cover page. Each template parameter shape, available in the Document Structure header in the shape repository, contains information about the process documentation file in general.
Template parameters can contain one of the following variables:
- Organization (default)
- Date or
In the attribute panel, you can define which kind of information should be displayed. The data is automatically retrieved and added every time when you create the actual documentation. You can also change the parameter label (for example, ‘author’) and determine whether this should be displayed before the value.
- Drag the desired template parameter from the palette on the cover page.
- Configure its type in the attribute editor.
Adding an image¶
You can insert an image of your choice into the cover page. The image can be selected from the workspace or uploaded from your computer. The corresponding element can be found in the modeling palette under Static contents.
- To add an image drag the Image element from the Static Contents section of the shape repository to the cover page.
- Select a picture from your computer or from the Signavio workspace by clicking the Edit button of the attribute Image. The dialog Edit: Image, link a file/picture opens.
- Click Save to insert the image.
The table of contents¶
The table of contents is created and updated automatically. When you create comprehensive templates, this update may may take a little while. In this case we recommend to deactivate the automatic updating during modeling by unchecking the box of the attribute Preview.
Deactivating the live preview of the table of contents.
If you enable the preview again, the contents is updated.
The process documentation¶
The process documentation pages are configurable and can be adapted to your needs.
Chapters and sections¶
Before you can add any variable elements to the content section, you need to add a chapter/section element.
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.
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.
- Create a chapter by dragging a Chapter/Section element from the shape repository to the template.
- To divide this chapter into sub-chapters, drag another Chapter/Section element on it.
- In a chapter, you can drag different static elements whose values are set during the modeling of the template. Such elements do not need any containers.
- In the attribute editor, 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.
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 or Folder Structure 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 for example, dragging a Chapter/Section element onto a Per Diagram element.
Sample chapter ‘Introduction’
A chapter can contain different elements. For example, the chapter “Introduction” could contain a free text element as the introduction text. Drag the Text element from the section Static Content in the shape repository to a chapter. Add free text to the introduction template.
Sample ‘Complete overview of the individual diagrams’
In the following example, a graphic for all diagrams is displayed in the chapter “Overview of individual diagrams”:
- Drag the container element to the appropriate chapter.
For each diagram, the container element will later create a new section.
- Then drag the element Diagram Image from the section Diagram Details to the Per Diagram-element.
- In the attribute editor, you can restrict what diagram type to be inserted (if for example only BPMN 2.0 process diagrams should be documented, disable all other chart types).
In addition to a graphical representation, you can represent numerous information on the diagram as a whole, such as the diagram attribute and modeling elements of a certain type. The subitems indicate the specific attributes for each template element that can be defined:
|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.|
Creates an image of the diagram. The following attributes can be defined:
|Attribute on diagram level||
Select an attribute (or more in ‘Multiple choice’), which value should be presented for each diagram (for example process description).
Displays all roles of a diagram. Pool/lanes, additional owner and organizations that are linked through a dictionary entry are included here.
|Data objects||Lists all used data objects of a diagram.|
|IT Systems||Lists all used IT systems of a diagram.|
Lists all start events of a diagram.
Lists all end events of a diagram.
|Linked dictionary entries||
Displays all dictionary entries linked in the diagram regardless of their category. Entries that are linked via a diagram element as well as links via own attributes are considered.
This overview displays all versions of the diagram including the creator and revision comment.
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.
- Add a Table of Process Elements or a List of Process Elements to the documentation template. To change the layout later, alter the value of the Display as-attribute.
- The new element will function as a frame to display element-based information. Now you can add content to the table/list and define their attributes.
- The columns ‘Name’ and ‘Responsible’ are created by default. Now you can drag and drop ‘Element Details’ elements into the table/list. A column will be added for each new element.
In list view, subitems are added instead of columns that you can also select and edit.
- If you want to delete a column, select it and click the Delete button in the menu bar of the Editor, or alternatively use the delete key on your keyboard.
- If you have selected an Attribute on element level or Attribute on element level (Multiselection), specify now a column header (attribute Title in the attribute editor) and select the attributes to be viewed.
- In the attribute editor, click the Edit button. In the dialog that opens, select the corresponding attribute for each modeling element. The elements Process participants, Data objects, IT systems and Used dictionary entries provide information about the named item regarding the listed elements.
- Configure the appearance and content of the table (or list) in the attribute editor.
Table column elements¶
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 (multiselection)||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:
Sample: element overview table
Sample: element overview list
Sample exported table
This example table contains the name, the responsible role and documents that are connected to each element of the diagram:
An exported element overview table
Table and list-specific attributes¶
You can configure the following properties of a table/list of process element shapes 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.
Defining multiple languages for templates¶
It is possible to define multiple languages for diagrams in 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.
Missing translations are highlighted in a different color.
The original language will be displayed in the attribute editor. You can translate the elements 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.