View source | Discuss this page | Page history | Printable version   
Toolbox
Main Page
Upload file
What links here
Recent changes
Help

PDF Books
Add page
Show collection (0 pages)
Collections help

Search

Push API

Warning.png   This document is still a work in progress. It may contain inaccuracies or errors.

Contents

Introduction

The new push API provides a new architecture to interact with external systems that is based on the concept of Webhooks.

With this new architecture when certain event happens either in the backend or in the POS the application will generate the payload information of the event and send it to the external systems subscribed to the event.

Pushapi1.jpg

Once the payload information of the event is received by the external system they can consume it directly or implement their own integration middlewares to translate the received data into the expected format of that system.

Bulbgraph.png   Before starting reading this guide, it is recommended to take a look at the Openbravo Business API Guide.

Event

In the Event window, accessible as system administrator, it can be defined the different events that can be triggered by the application.

Pushapi5.png

The definition of the event requires the following information:

Business API Event

Bulbgraph.png   The support for Business API events is available since version 1.0.200 of the Openbravo Business API module.

When the event type Business API is selected for an event, the following fields will be shown:

Pushapi7.png
Bulbgraph.png   See Event Subscriptions section for more information

Event Subscriptions

In addition to the definition of the event, it is also needed to include some configuration at client level with the Event Subscription window, for the organizations which we want to be affected when triggering the different events.

Pushapi4.png

The definition of an event subscription requires the following information:

Subscribing to Business API Events

While defining a subscription for a Business API event an additional field will be shown:

The criteria for deciding if the payload generated for a given Business API event subscription must be eventually sent to the selected external system is based on three values:

  1. The organization of the subscription
  2. The organization property in the payload generated for the event
  3. The organization tree criteria defined for the event in particular.

Where the organization tree direction of the Business API event can have one of the following values:

Following the example of the pictures above:

The organization tree is as follows:

Pushapi6.png

In case the organization of the generated payload for the event is an ancestor or a descendant of North East Zone, then the external system will be notified. Otherwise, the information will not be sent to the external system. For example:

Bulbgraph.png   The organization of the subscription is the only organization taken into account when resolving a subscription for a given record. Any other organization like the context organization, Process Request organization or EDL request organization are not taken into account.

How to Trigger Business API Events

For triggering events a programmatic API is available through the SynchronizationEvent class.

Single Record Events

 
void triggerEvent(event, recordId)

Where the parameters of the triggerEvent method are:

 
import org.openbravo.synchronization.event.SynchronizationEvent;
 
SynchronizationEvent.getInstance().triggerEvent("OBEBUS_ORDER", "2BAB52378379435CBE250E30730589F0");

Multiple Record Events

The API for triggering "multiple record" events is slightly different from the previous one as we need to provide the parameters of the export filter used by the event:

 
void triggerEvent(event, params)

Where the parameters of the triggerEvent method are:

 
import org.openbravo.synchronization.event.SynchronizationEvent;
 
SynchronizationEvent.getInstance().triggerEvent("OBEBUS_MULTI_ORDER", Map.of("param1","1","param2", 2));

Multiple Record Event Triggering Background Process

Multiple record events are specially designed to cover the case of certain events that only happen at database level, i.e., cannot be directly detected from the java code.

This kind of events are useful in combination with a background process that periodically polls from the database to extract the information of those events in case they have happened.

For this reason, an out of the box background process named Multiple Record Event Triggering Process is provided by default which allows to schedule the triggering of the events that are linked to an export filter with a single date time parameter named lastUpdated. The events that match this criteria can be scheduled automatically in the Process Request window.

Pr.png

Note that this process allows to trigger all the events that matches the mentioned criteria or specify a subset of them. This can be done in two ways:

Ei.png
Bulbgraph.png   The Trigger All Events field and the Event to Integrate subtab of the Process Request window are only used for the Multiple Record Event Triggering process and they are ignored by default for the rest of the processes that are scheduled in this window.
Bulbgraph.png   In case a different criteria for selecting the multiple records events is needed or in case additional filter parameters values should be provided, then the Multiple Record Event Triggering process cannot be directly used but it is ready to be extended with a new process that would cover this specific needs.

The first time the background process is executed, the lastUpdated parameter takes a default value old enough to ensure that all the records matching the filter of the event are retrieved. In case it is desired to trigger the event starting from a specific date, this date can be set by using the Initialize Entity Synchronization Table process with the following parameters:

InitializeEntitySynchronizationForAPI.png

Event Triggering Flow

Bulbgraph.png   It is required to configure the Send Business API Event EDL process in the EDL Configuration window to make this method work properly

Once an event is triggered with any of the methods explained above, the following steps are performed:

  1. Find event subscriptions: Generates a partial payload to find the organization of each record to be exported and selects the affected subscriptions, using the organization based criteria explained in the previous section.
  2. Generate payload: In case a subscription is found in the previous step, the complete payload of the event is generated by applying the entity mapping linked to the event with the record(s) whose IDs are received (the ID received as parameter for single record events, the IDs coming from the export query for multiple record events).
  3. Generate EDL request: A new EDL request is created for each subscription found in order to handle the pushing of the payload to the corresponding external system in an asynchronous way. Thus, these EDL requests can be used to check the status of each push operation. By default the Send Business API Event EDL process has a default batch size of 50 records, which means that the information is sent to the external system in batches of 50 elements.
Bulbgraph.png   Once it is determined that the event information must be pushed to the external system, it is not immediately sent to the external system. This is not a synchronous process. The information will be eventually sent when the created EDL request is processed through the import entry infrastructure, without a minimum specific SLA time guaranteed for the data delivery.
Edlr.png

Standard Business API Events

Here is a summary of some of the standard Business API events triggered by the application.


EVENT SELECTION TYPE DESCRIPTION MODULE
RETAPCO_OrderCreation By Single Record ID Triggered when a new order is created in the Web POS org.openbravo.retail.api
RETAPCO_ExternalOrderCreation By Single Record ID Triggered when a new order is created through the ExternalOrderLoader service org.openbravo.retail.api

Read Only Pool Configuration For Business API

Business API uses the infrastructure provided by the read only pool functionality.

Bulbgraph.png   For more information take a look to the Read Only Pool Guide.

This configuration will apply in case of consuming a business entity mapping with integration direction, from Openbravo to External System, when they are used in one of the following cases:

Bulbgraph.png   The read only pool is used by default in the export query fired by the multiple record events to retrieve the IDs of the event records, if configured. This is different for the single record events where the ID of the record included in the event is always retrieved with the default database pool.

Preference

Default-pool-mappings-preference.png

The preference Default DB pool used by Business API defines the database pool used by all entity mappings that support using the read-only pool. Value should be DEFAULT or RO. If this preference is not defined or contains an invalid value, entities will use the read-only pool if configured.

Manual Selection

Data-pool-mappings-selection.png

If a finer grain configuration is required, in window General Setup|Application|Data Pool Selection is possible to configure for each entity mapping which database pool to use, overriding the preference defined in Default DB pool used by Business API.

Entity-Mappings-Selection.png

The data type with which to define the entity mappings will be Business API. The Entity Mapping dropdown will show all applicable mappings. That is, entity mappings with integration direction, from Openbravo to External System.

It will also be possible to define the database pool depending on the filter used to export with an entity mapping. The Export Filter dropdown will show all the applicable filters depending on its related entity mapping.

Entity-Mappings-Filter-Selection.png

If there is not an specific pool configuration for a filter in particular, the generic pool configuration for the entity mapping (that without filter defined) will be used. And if neither exists a configuration for that entity mapping, then the pool defined by the Default DB pool used by Business API preference will be used.

Retrieved from "http://wiki.openbravo.com/wiki/Push_API"

This page has been accessed 723 times. This page was last modified on 17 May 2022, at 14:18. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.