Documenting integration flows with BPMN

There's no standard approach to document an integration flows. One can make screenshots of the created flow. Or show the source code of the integration flow. Understanding this documentation requires proper knowledge of the tooling. And it is specific to the specific tool, particularly annoying when an company uses multiple integration products.

Therefore a good approach is to create the documentation of the integration flows in BPMN (Business Process Model and Notation). So everyone can read and understand the documentation.

BPMN is a graphical representation for business processes but can be well leveraged for message flows as well. BPMN is a standard notation and can be created with different tools (for example Bizagi, IBM Process Designer, …). A model consists of different symbols that are linked by lines and arrows. In BPMN there are four groups of symbols:

Event

An event has a circle as symbol. When something happens (like a message is received or an error is caught) the event will be triggered. There are three different events possible in BPMN:

Start event, Intermediate event and End event.

Activity
The symbol of an activity is a rounded-corner rectangle and describes the kind of work which must be done. It is also possible to make a subflow using an activity. The sublow makes the documentation more readable for large integration flows.

Gateway

A gateway is represented with a diamond shape and determines forking and merging of paths.

Connections

All the above symbols must be connected with some lines (with an arrow). There are three different connection types in the BPMN standard:

• A Sequence Flow is represented with a solid line with arrowhead, and shows in which order the activities are performed.
• An Association is represented with a dotted line. It is used to associate an Artifact or text to a Flow Object.
• A Message Flow is represented with a dashed line, an open circle at the start, and an open arrowhead at the end. It tells us what messages flow across different pools.

These are the most used symbols of a BPMN flow.

When you know the different symbols, you can create documentation. Most of the time the integration flow is easy to document. This because you can copy the integration flow in the BPMN tool. For example when you have a flow like:

The BPMN looks like:

Start event -> activity (or subflow) -> end event. In the subflow of the BPMN you can create a detailed view of the compute node. People that must know the details, can view in the subflow for it.

Author: Jimmy