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



Curious to know more about this topic?

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

Also worth reading

Apigee Scope Validation using OpenAPI Specification

In API security and management, we often use a lot of different security mechanisms to protect the requested resource behind the API Gateway. One of these mechanisms is the validation of scopes to authorize a client on a specific sub-resource of the API. Most of

Read More »

Integrating with TIBCO CLOUD

Our experts Glenn, Jason, Jurgen, and Kevin dedicated an i8c FastTrack Day to examining the TIBCO iPaaS offering. Check out their Research & Development day report to learn what they uncovered. 👇  TIBCO CLOUD™ The TIBCO Cloud™ Integration enterprise integration platform-as-a-service (iPaaS) provides self-service integration

Read More »