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:

Start event, Intermediate event and End event.

• 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