Extension/CognitiveProcessDesigner

Business Process Model and Notation (BPMN) is a standard for representing business processes graphically. BlueSpice provides a graphical editor for creating and editing BPMN diagrams. The editor is based on the open-source project bpmn.io.

Open the BPMN editor

The BPMN editor can be opened from the following locations:

1. Select Processes in the main navigation. On the Processes page, select Processes in the page tools panel. Administrators can deactivate the Processes entry in the Config Manager.
2. Open Wiki actions and select Processes in the Overview section.
3. Select the New content button in the header bar and select New process.
   

The BPMN editor opens after selecting one of these options.

Create a process diagram

All process pages are created in the Process namespace.
To create a process diagram:

1. Enter a process name.
2. Select Done. The BPMN editor opens with a start event already added.
   

The diagram must meet the minimum requirements before it can be saved.

Add shapes to the diagram

Each process diagram requires a start event and an end event. Additional shapes can be used to represent activities, decisions, data, participants, and other elements of the business process. The main BPMN elements are:

• Events: Represent something that happens during a process, such as a start or end event.
• Activities: Represent work performed as part of a process, mainly tasks.
• Gateways: Represent decision points and determine how process paths are split or merged.
  

If a BPMN symbol is unfamiliar, refer to the Camunda BPMN 2.0 Symbol Reference. Not all BPMN symbols are available in the BlueSpice BPMN editor. For example, expandable subprocesses cannot be added. To add a shape:

1. Select the preceding shape.
2. Select the required symbol to append the next shape.
   

Shapes can also be dragged from the toolbar onto the diagram.

Shape types

The following shape types are available in the BPMN editor:

Shape	Description
Start event	Represents the trigger of a process. A start event has a single narrow border and can only be a catching event. It is therefore displayed with an open or outline icon.
Intermediate/boundary event	Represents an event that occurs during a process between activities. An intermediate or boundary event is shown with a thin double border. For example, a task can lead to an event that sends a message to another pool, where another event waits to receive the response before the process continues.
End event	Represents the result of a process. An end event has a thick border and can only be a throwing event. It is therefore displayed with a solid icon.
Gateway	Represents a decision point and determines how process paths are split or merged, depending on the defined conditions.
Task	Represents a single unit of work that cannot be broken down into a lower-level process activity. A task is the lowest-level activity shown in a process diagram. A set of tasks can represent a higher-level procedure.
Data object reference	Represents information used by a process, such as a document in physical or digital form. It is displayed as a page with a folded top-right corner.
Data store reference	Represents information that needs to be stored persistently. Data stores can represent IT systems and applications, as well as physical folders or archives.
Pool / participant	Represents a major participant in a process, such as an organization. A pool can contain one or more lanes. An open pool displays its internal details, while a collapsed pool hides the internal details.
Group	Groups activities visually without affecting the process flow. A group is an artifact represented by a rounded rectangle with a dashed border.

Events represent something that happens, while activities represent something that is done. Events can be catching or throwing events, depending on whether they receive or trigger an event.
Data objects and data stores can be connected to process elements with a data association. Data associations show how process steps use data but are not part of the process flow.

Shape actions

When a shape is selected, the available actions are displayed.

Action	Description
Append end event	Adds an end event with a connector after the selected shape.
Append gateway	Adds a gateway with a connector after the selected shape.
Append task	Adds a task with a connector after the selected shape.
Append intermediate/boundary event	Adds an intermediate or boundary event with a connector after the selected shape.
Add text annotation	Adds an annotation to the shape. The annotation line and bounding box can be resized and repositioned.
Change element	Changes the shape to a more specific shape type.
Delete	Deletes the shape.
Set color	Changes the fill color of the shape. For line objects, the outline color is changed.
Connect to other element	Connects the selected shape to an existing shape. This action is only available when an endpoint for the connection exists.

Editor tools

The toolbar provides tools for working with the diagram. Hover over a tool to display its name.

Tool	Description
Hand tool	Allows navigation across the canvas without accidentally moving elements.
Lasso tool	Selects multiple shapes at the same time. An object is selected only if the entire object is within the selection. Hold the Shift key to add or remove individual objects from the selection.
Create/remove space tool	Adds or removes horizontal or vertical space in the diagram.
Global connect tool	Connects a shape to a distant shape. The tool is automatically deactivated after creating the connection and must be selected again for another connection.

If an action does not produce the intended result, press Ctrl + Z to undo the changes.

Validate and save the diagram

A diagram must meet the following requirements before it can be saved:

• A start event is present.
• An end event is present.
• Every shape that generates a wiki page has a unique label.
  

If the diagram cannot be saved, select the Toggle linting overlays button to display errors and warnings. The affected elements are highlighted in the diagram.
Correct the reported issues and select Save changes to save the diagram.
During the save process, a dialog provides the option to create wiki pages for the relevant process elements. These pages can also be created later.

Unique label requirements

The label of an event or task is used to create its associated wiki page. Therefore, each event and task that generates a wiki page requires a unique label within the process.
Gateways and other shapes that do not generate wiki pages do not require unique labels. For example, the same Yes or No label can be used for multiple gateways in a diagram.

Rename a shape

To rename a shape:

1. Double-click the shape.
2. Change the label.
3. Save the diagram.
   

If a shape with the same name already exists, BlueSpice automatically adds a number to the new name to make it unique.
If the shape already has an associated wiki page, renaming the shape also renames the associated page.

Create wiki pages for process elements

Description pages can be created for process elements when the diagram is saved. To create description pages:

1. In the save dialog, select the checkbox for creating description pages.
2. Complete the save process.
3. Review the list of created pages in the confirmation dialog.
   

Description pages are created for start and end events and for the different task types, such as user tasks and script tasks. A Call activity does not create a description page.
After the pages are created, the corresponding shapes in the diagram become interactive and link to their description pages. Select a shape to open its page.
Each description page contains information about the process element:

Element	Description
Breadcrumb	Shows the location of the description page as a subpage of the process page.
Incoming connections	Lists the connections that precede the process element.
Outgoing connections	Lists the connections that follow the process element.
Page flow	Provides links to the preceding and succeeding description pages.
BPMN task description	Provides a placeholder for a custom description. Edit the page to replace the placeholder with the required content. Once content has been added, the placeholder template can be removed.

Embed a process diagram in a wiki page

BPMN diagrams are created and edited in the Process namespace. Existing diagrams can be embedded on any wiki page. To embed a process diagram:

1. Open the page in the VisualEditor.
2. Open the Content droplets menu in the editor toolbar.
3. Search for process.
4. Select the Process content droplet.
5. Select Insert.
6. Enter the name of the process.
7. Select Save.
   

The embedded diagram can include a toolbar with additional options if the toolbar toggle is enabled.

Option	Description
Go to the diagram page	Opens the process page where the diagram can be edited.
Download diagram as SVG	Downloads a copy of the diagram in SVG format.
Center diagram	Centers the diagram in the display. This is useful for large diagrams that require repositioning while viewing.
Show raw XML	Displays the XML source of the diagram.
Show diagram	Returns from the XML source to the diagram.

Limitations and special considerations

The following limitations apply when working with BPMN diagrams:

• Process and activity page names: Wiki page titles are limited to approximately 255 characters. Very long process names combined with long activity or swim lane names can cause errors when activity pages are created.
• Slashes in activity names: Slashes (/) are not permitted in activity names because they are used to create the subpage path.
• Subprocesses: Expandable subprocesses cannot be created in the BPMN editor. A call activity can be created, but it does not create a description page.
• Description pages: Wiki pages are only created for the supported activity types. Switching to a special activity type, such as a manual activity, does not create a description page.

Business Process Model and Notation (BPMN) is a graphical representation for specifying business processes. BlueSpice provides an intuitive GUI (graphical user interface) for creating BPMN diagrams. The feature is based on the open source project bpmn.io. The extension Page Forms is used to facilitate the input of information for each element.

How to start

To get to the BPMN editor, you can choose between 3 options:

1. The Entrypoint Processes in the main navigation. Note that administrators can deactivate this link in the configuration manager. On the Processes page, you can click the link New Process in the page tools panel.
2. The link Processes in the Overview section of the Global actions menu.
3. The menu item New process of the plus-icon button in the header bar.

Select one of these links to open the BPMN editor.

Creating a diagram

Note:All process pages are created in the BlueSpice default namespace Process.

To create the diagram:

1. Enter a process name.

   

   New process dialog.

2. Click Done. The BPMN editor opens. At this point, the diagram contains a start event. You cannot save the diagram until the diagram meets the minimum requirements for saving.

Before continuing with the diagram, let's look at the functionality of the BPMN editor.

Features of the editor

The editor includes the following elements:

The BPMN editor

Functionality of the BPMN editor

Element	Functionality	Description
1	Cancel	Leaves the edit mode without saving any changes.
2	Center diagram	Centers the diagram on the page in view mode.
3	Save changes	Saves the diagram and any wiki pages that need to be created.
4	Toolbar	Contains all commands for editing a diagram.
5	Start event	The start event is already added to the diagram. You still need to add the required label.
6	Toggle linting overlays	Shows errors and warnings. You need to click this button if your diagram cannot be saved.
7	bpmn.io info	Link to the bpmn.io website. Unless you are interested in the technical background of the editor, you can ignore this button.

Adding the diagram shapes

Each diagram needs a start event and an end event. There are many additional useful elements to create a meaningful business process diagram.

The main elements of a BPMN diagram are:

• events (such as the start or end event),
• activities (mainly different types of tasks), and
• gateways (decision points between different paths).

Info about the shapes:If you are not familiar with BPMN, you can refer to the Camunda BPMN 2.0 Symbol Reference.

Note that not all symbols are integrated in the BlueSpice BPMN editor. For example, it is not possible to add sub-processes at this time.

The most basic diagram you can save has a start event with a label and a connected end event with a label.

this diagram can be saved

To add a shape, click the predecessor shape. Select a symbol to append the next shape.

appending a shape

NoteA diagram with at least a missing label will throw an error and the Save-button will remain disabled.

Types of shapes

From the toolbar, you can drag-and-drop the shapes onto the diagram. You can see the name of a shape by hovering over it:

available shapes

Shapes overview

Shape	Description
Start event	Acts as a process trigger; indicated by a single narrow border, and can only be Catch, so is shown with an open (outline) icon. Note: An Event is represented with a circle and denotes something that happens (compared with an activity, which is something that is done). Icons within the circle denote the type of event (e.g., an envelope representing a message, or a clock representing time). Events are also classified as Catching (for example, if catching an incoming message starts a process) or Throwing (such as throwing a completion message when a process ends).
Immediate/boundary event	An event that occurs in the middle of the process between activities (represented by a thin double line). For example, a task could flow to an event that throws a message across to another pool, where a subsequent event waits to catch the response before continuing.
End event	Represents the result of a process; indicated by a single thick or bold border, and can only Throw, so is shown with a solid icon.
Gateway	A gateway is represented with a diamond shape and determines forking and merging of paths, depending on the conditions expressed.
Task	A task represents a single unit of work that is not or cannot be broken down to a further level of business process detail. It is referred to as an atomic activity. A task is the lowest level activity illustrated on a process diagram. A set of tasks may represent a high-level procedure.
Data object reference	Data objects may represent for example documents used in a process, both in physical and digital form. They look like a page with folded top right corner. They are generally available as long as the process instance is live.
Data store reference	To store information in a more permanent way you need Data Stores. They are commonly used to represent IT systems and applications, but also plain old manila folders or archive would be suitable. You can show how certain steps of a process use the data (either Data Objects or Data Stores) by using a Data Association arrow (dotted line with arrowhead). They are NOT a part of the process flow.
Pool / participant	A pool represents major participants in a process, typically separating different organisations. A pool contains one or more lanes (like a real swimming pool). A pool can be open (i.e., showing internal detail) when it is depicted as a large rectangle showing one or more lanes, or collapsed (i.e., hiding internal detail) when it is depicted as an empty rectangle stretching the width or height of the diagram.
Group	A Group is a so-called Artifact and represented with a rounded-corner rectangle and dashed lines. The group is used to group different activities but does not affect the flow in the diagram. It is purely a visual element.

​

​See also: https://en.wikipedia.org/wiki/BusinessProcess_Model_and_Notation#Elements

Shape actions

​When a shape is active, it shows its associated possible commands.

shape commands

Shape actions

Action	Description
Append end event	Adds an end event with a connector after the shape.
Append gateway	Adds a gateway with a connector after the shape.
Append task	Adds a task with a connector after the shape.
Append intermediate/boundary event	Adds an intermediate/boundary event with a connector after the shape.
Add text annotation	Adds an annotation to the shape. The annotation line and bounding box can be resized and repositioned.
Change element	Allows to set a more specific shape type.
Delete	Deletes the shape.
Set color	Sets the fill color of the shape. For line objects, the outline is colored.
Connect to other element	Adds a connector to an existing shape. It cannot be used if no endpoint for the connection exists.

Toolbar

From the toolbar, you can drag-and-drop the shapes onto the diagram. You can see the name of a tool by hovering over it:

available tools

Tools overview

Tool	Description
Hand tool	When activated, tyou can freely navigate the canvas without accidently moving elements under the cursor.
Lasso tool	When activated, you can select multiple shapes at the same time. Objects are only included in the selection if the entire object is part of the selection. Hold the Shift-key to add or remove individal objects.
Create/remove space tool	When activated, you can add or remove space horizontally or vertically. If the results of the actions are not as intended, you can press Ctrl+Z multiple times to undo the changes.
Global connect tool	When activated, you can connect a shape with a distant shape. The tool does not stay activated. If you want to use it again, you need to select it again.

Saving the diagram

ImportantAll diagrams are saved and maintained in the "Process" namespace.

You can embed a diagram in any wiki page.

When your diagram is complete, you can save it. You cannot save if one or more of the following issues exist:

• Not every shape has a label
• The start or end event is missing

To find the issues, click on the linting button at the bottom of the diagram. It will highlight the problems in the diagram. For example, a missing end event can trigger multiple errors:

errors before saving

After correcting the errors, you can save the diagram. The save-dialog will ask if you want to create all description pages. You do not have to do this or you can do this at a later time.

Unique label requirements

The label of an event or a task is used to create its description pages. Therefore, each of these shapes requires a unique label.

Unique label requirements for gateways  -v5.1.1

Starting with Bluespice 5.1.1, this requirement is not applied to gateways and in general to shapes that do not produce wiki pages. Therefore, it is possible to use yes/no gateway labels multiple times in a diagram.

Renaming a shape

To rename the label for a shape, double-click the shape and change the label. If a shape with the same name already exists, the system automatically creates a unique name for the shape by appending a number. When you rename a shape, the associated page is also renamed (if the page already existed previously).

Creating the wiki pages

If you decide to describe your shapes in more detail with individual wiki pages, you need to activate the checkbox in the save dialog:

creating description pages

The next dialog lists all pages that were created.

confirmation page

Important!Description pages are only created for start and end events and for the different "task" types (e.g., User task, Script task,...). The type "Call activity" (also listed under task types) does not produce a description page.

The colored outlines of the shapes of the diagram now indicate that the shapes are interactive and link to the description pages:

interactive diagram

Clicking on any such shape opens its wiki page:

elements of a shape description page

Elements of a description page

Element	Functionality	Description
1	Breadcrumb	Shows the location path of the description page (as subpage of the process page).
2	Incoming connections	Label for the connections that precede this step.
3	Outgoing connections	Label for the connections that follow this step.
4	Page flow	Links to the preceding and succeeding description pages.
5	BPMN task description	Placeholder template that indicates that a custom description can be added below the connections info. To replace the template with a real description, you can simply switch into page editing mode like any other wiki page. If you add content to this page, the placeholder template is no longer needed and you can simply remove it from the page.

Embedding a process diagram in a wiki page

BPMN diagrams cannot be created on a wiki page itself, but you can embed a diagram by using the related Content droplet.

On any wiki page, open the Content droplets dialog in the visual editor toolbar.

Content droplets menu item

​Search for the term "process":

content droplet "Process"

​Select the droplet and click Insert. Provide the name of the process and click Save:

droplet inspector

If the toggle-switch to show the toolbar is activated, a select menu above the diagram is displayed. It allows to:

BPMN toolbar

• Go to the diagram page: The diagram can only be edited directly in the process namespace.
• Download diagram as SVG: You can save a copy of the diagram locally in SVG-format.
• Center diagram: If you have a large diagram that requires repositioning on the page while viewing it, it can be reset to show the beginning of the diagram from top left again.
• Show raw XML: Switches to the XML source of the diagram.
• Show diagram: Switches back to the diagram after viewing the raw XML.

Special considerations

• Page names of process pages:
  • The length of page titles for wiki pages is limited to approximately 255 characters. In extreme cases, this can cause a memory error when creating activity pages. For example, if the process name itself is very long and an activity with a long name is located in a swim lane with a long name.
  • Slashes in activity names are not permitted, as they are used to create the subpage path.
• Expandable sub-processes are not possible (although a call activity can be created).
• Wiki pages are only created for the standard activity. When switching to a special activity (e.g., a manual activity), no page is created.