Best practices in integration

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Best practices and implementation guidelines >

Best practices in integration

Bizagi provides a powerful integration layer follows a service-oriented architecture that supports different integration possibilities for the entire corporate solution.


In projects where there is the need to integrate the Processes with existing applications (e.g., ESB systems), Bizagi's Integration layer presents multiple integration options. It is possible to invoke Web-based services (i.e., SOAP, REST) or APIs directly from within Bizagi Processes (i.e., dlls, jars).


This section provides some guidelines and practices to create and configure efficient interfaces that do not affect the user experience and the normal execution of Processes.


Use asynchronous activities

When the time involved in an integration point's transaction is significantly extended you should use asynchronous tasks instead synchronous ones for the following reasons:


When using synchronous interfaces, as they are executed the tables that are involved are blocked until the transaction is finished.

Synchronous interfaces wait for a response from the external service before they allow the case to continue.

When using synchronous interfaces, if the answer takes too long the tables used may be blocked, affecting ALL end users.

When using synchronous interfaces if the interface fails the case will be blocked.


Asynchronous Activities have been designed especially to call external interfaces, which are mainly used for integration with existing services in other systems.


When you have Activities which invoke external services (SOAP Web services or REST services), or which use an integration component (through the Component Library), use the Asynchronous property for that Activity. In this way, you will have an Asynchronous Activity which will handle retries and other possibilities to manage transactions (for instance, delayed locks are avoided) in points of the Process where there is a significant service time (due to a possibly and presumed delay implied in a communication with external systems).


Use synchronous interfaces only if you can absolutely guarantee that the external service will respond in maximum 3 seconds. This way end users will not be affected. If not, convert your interfaces to asynchronous.




Enable show feedback in interfaces that take NO MORE than 10 seconds

Automatic tasks have a property called Show Feedback. When this property is activated, Bizagi will immediately execute the Activity through its Work Portal; a wait page will be displayed while the request is processed, notifying the completion or failure of this execution.  When this property is disabled, the Asynchronous Activity is executed by the Scheduler service later on. For the end user, the Work Portal will notify that this execution is scheduled.

When interfaces don't have feedback they are executed by the scheduler, allowing the case to move on without end users waiting for an answer.

Interfaces that take a long time to respond (like document management interfaces), feedback will make the application look slow and will cause imminent performance issues.


If you know that an interface takes a long time to process (because of its nature and the amount of processing that must be done), design the automatic activity without feedback. Hence, away from the user’s experience.


Disable show feedback when the first activity of a Multiple Sub-Process is an Automatic task

Automatic tasks have a property called Show Feedback. When this property is activated, Bizagi will immediately execute the Activity through its Work Portal; a wait page will be displayed while the request is processed, notifying the completion or failure of this execution. As the Sub-Process is multiple, the wait page of this task (feedback) cannot be displayed to the end users.


Make sure an interface has been successfully completed before the Process to continue

In scenarios where your Process is integrated with external systems and the information involved in that integration is sent to Bizagi in an asynchronous manner, it is recommended to use BPMN Events in the modeled Process.


When any external system completes a job asynchronously, such system notifies Bizagi and send back information by triggering a BPMN Event in the modeled Process. This way, there is no pending job continuously listening or asking for an update, but the external system itself can work unattached to Bizagi and notify once this has been completed.


This also applies if a customer has an integration strategy based on message queues. In this case, you should ask the customer to generate a "Broker" layer that exposes web services. This interaction must be designed and provided this using the "physical" modeling asynchronous, so that it is invoked by web service to the Broker, this receives the acknowledgment message, and then the Broker invokes Bizagi using SOA layer to perform an event:




Use the proper integration points

The point whereby an interface is invoked has a high impact in the behavior of the interface in execution. Perform a deep analysis of which is the best integration point according to the business conditions to avoid performance issues. When defining the integration points take into account:


To invoke external services from within Processes in Bizagi, it is recommended to define these integration points as BPMN Service Tasks.

They should always be configured as Asynchronous Tasks and have a timeout of 10 to 15 seconds.




Depending on the SLA committed by the client have the following options:

SLA lesser than 10 seconds: Use an automatic task to perform the integration

SLA greater than 10 seconds: This should be modeled using an asynchronous pattern. This aims to lower transaction times and forces to split the service into 2 elements:

oAsynchronous integration invoked only to send information and receive acknowledgment

oA Bizagi Event waiting for the response from the external system through Bizagi SOA layer.





As a recommended practice, integration with other systems should be carried out at the On Exit timing of activity actions.

This applies for the Web service connector, SAP connector, other connectors and component library in general.


Handle only the needed information in SOAP Web services or REST services invocations

When you have Activities which invoke external services (SOAP Web services or REST services), you should always map and update only those attributes which are strictly involved in the response.


This way and according to good practices, your external service invocation should handle (both receive and return) only the strictly required information.


Keep in mind this guideline when you need to create and publish a new Web service in an external system, so that the optimal exchange of information is considered in this design.


Tune up your interface configuration

Tune up your interfaces after a month of being in production. After this time you will have statistics that will allow you to adjust timeouts, feedback, retries and retry intervals.


Consider an ODS for reports (or BI tools integration)

The ODS feature of Bizagi (Operational Data Store) is designed to improve Automation Server's overall availability (enhances overall performance and reliability).


This means that when running heavy resource-consuming queries (those handling a really large amount of information), you should consider a replicated database to avoid affecting the performance of the transactional database (involved in daily process operations).

For instance, when integrating Bizagi's database with any reporting or BI tool, you will need to make sure that you rely on Bizagi's ODS concept to set up and use a replicated database in which reports are produced.

This way, queries done directly to that replicated database will not use the resources allocated to the transactional database (which also avoids potential locks).


Configure only one interface regardless of the number of invocations

When your SOAP Web services or REST services are invoked at different points in your processes, configure only one interface regardless of the number of service tasks invoking that same service (only one for a given Web Service URL).




What to avoid


Avoid invoking interfaces in buttons or expressions (rules)

In some cases may be necessary to invoke interfaces from buttons in Forms or rules. If this is strictly necessary take into account that:


Interfaces executed from buttons or expressions (rules) are always synchronous. Thus, use buttons to perform integrations if the SLA is lesser than 10 seconds. If the SLA is greater than 10 seconds the user should rethink the activity behavior (possibly split it) and perform the integration using asynchronous modeling.

When an interface is being executed, the tables that are involved are blocked until the transaction is finished.

Synchronous interfaces wait for a response from the external service before they allow the case to continue.

If the response takes too long the tables used may be blocked, affecting ALL end users.

If the interface fails the case will be blocked.



Use the interfaces option available On exit of Actions to invoke interfaces instead of using buttons.

Use the interfaces option available in Activity actions to invoke interfaces instead of using rules.


Avoid combining interfaces and rules

Bizagi executes expressions and interfaces in one single transaction, On exit of an activity, plus the expressions On enter of the next manual task. When expressions that are related to the interfaces execution are too complex, the performance of the interface will be affected.



Expressions related to the execution of an interfaces (On the same On exit action or On enter of the next manual task) must be very simple.


If complex expressions are needed use them On exit on the next manual task, when possible, to avoid being part of the same transaction.




Avoid combining sequential interfaces with 'show feedback' and 'not show feedback'

Combining sequential interfaces with 'show feedback' an 'not show feedback' may block the database,



For sequential interfaces select all or none with 'show feedback'.




Avoid using many retries, and avoid short retry interval

When defining a BPMN service task as an asynchronous Activity, Bizagi allows setting a number of retry attempts (retries), in case the Activity's integration actions fail to respond in a given threshold (usually, an invocation to an external service).

Therefore, in this scenario where an asynchronous Activity fails (i.e. an external application is not started, there are connectivity issues, etc) and surpasses the number of predefined retries, Bizagi offers the possibility for an administrator to review, follow-up/diagnose and manually retry such operations.

The way the parameters of asynchronous activities are configured affects directly the performance of the application.


When retries are configured think very well about the types of errors that will be received. Ask yourself: Is retrying worth it?


If errors are of the type: user does not exist in external system, or, invalid document path, it doesn't matter how much you retry, the interface will never work. Then, you have to think of some other way to solve these types of errors and avoid using retries. On the other hand if errors are of the type: system is unresponsive, or, concurrency problems, then retrying does make sense.


Ask yourself: Is 1 minute long enough for the system to recover?



Use asynchronous activities when programming retries.

Think if retrying makes sense and how long the error will take to be solved for the retry to make sense.


Avoid timeouts over 10 seconds

Interfaces that need timeouts over 10 seconds are complex interfaces that must have different handling. These interfaces may block the database until an answer is received affecting all end users.  


Slow interfaces are usually the ones connecting with Document management systems. It is common to see projects that use 30 seconds or more in timeouts, combined with 3 or 4 retries: that is 120 seconds of tables waiting for an answer and slowing the whole system down.


When the external system takes a long time to respond, Bizagi blocks the involved tables until an answer is received. This causes performance issues for all end users, damaging Bizagi's perception, when what is really happening is that an external system is not responding quickly; this is not Bizagi's fault.



Design the interfaces to be queued in the external system and then update Bizagi when the interfaces have been performed:

Indicate whether a case item had been 'queued successfully' or 'not queued' as response.

The external system must handle queues and execute instances one by one.

When the service in the external system has been finished, the external system must set an event in Bizagi to allow the process to continue.