Documenting integration flows with BPMN

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:


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.


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.


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


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

Working at i8c

i8c is a system integrator that strives for an informal atmosphere between its employees, who have an average age of approx 30 years old. We invest a lot of effort in the professional development of each individual, through a direct connection between the consultants and the management (no multiple layers of middle management). We are based in Kontich, near Antwerp, but our customers are mainly located in the triangle Ghent-Antwerp-Brussels and belong to the top 500 companies in Belgium (Securex, Electrabel, UCB, etc…).

Quality Assurance

i8c is committed to delivering quality services and providing customer satisfaction. That’s why we invested in the introduction of a Quality Management System, which resulted in our ISO9001:2000 certification. This guarantees that we will meet your expectations, as a reliable, efficient and mature partner for your SOA & integration projects.

i8c - ISO9001-2015