Push API

Contents 1 Introduction 2 Event 2.1 Business API Event 3 Event Subscriptions 3.1 Subscribing to Business API Events 4 How to Trigger Business API Events 4.1 Single Record Events 4.2 Multiple Record Events 4.2.1 Multiple Record Event Triggering Background Process 4.3 Event Triggering Flow 5 Standard Business API Events 6 Read Only Pool Configuration For Business API 6.1 Preference 6.2 Manual Selection

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.

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.

Event

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

The definition of the event requires the following information:

• Search key: Identifies the event univocally and must start with the DB prefix of the module where it will be created.
• Name: Used to give a self-descriptive name to the event.
• Description: An optional text describing the event.
• Event Type: Defines the way event types are generated and how they can be consumed.

Business API Event

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

• Entity Mapping: a combo which allows us to select one of the From Openbravo to External System records from the Openbravo Business API entity mappings. This entity mapping will be used to generate the information that will be managed by the event. Is important to take into account that the selected entity must have a property mapping for the organization column as it will be used to determine which subscriptions are affected by this event. This property mapping must be defined with the following properties:
  • Openbravo Property Path: organization
  • Property Mapping Class: EntityPropertyMapping
  • Referenced Entity Mapping: an entity mapping that provides the organization ID, like the standard Organizaton mapping.

• Organization Tree Direction: a list that allows us to determine which subscriptions should be taken into account when triggering this event. Given the organization in the event payload, the subscriptions with an organization present in the tree hierarchy direction chosen in this field will be taken into account. The three possible values are:
  • Ancestors
  • Descendants
  • Natural Tree (Ancestors and Descendants)

• Record Selection Type: defines how the records affected by the event are selected. The possible values are:
  • By Single Record ID: a single record identified by a given ID is exported with the event.
  • By Multiple Record Filter: a Business API export filter is applied to retrieve multiple records that are exported as part of the event.

• Filter: the export filter linked to the selected Entity Mapping that is used to retrieve the records of the event. It is only available if the Record Selection Type is By Multiple Record Filter.

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.

The definition of an event subscription requires the following information:

• Organization: The organization linked to the subscription.
• Event: Event associated with the subscription.

Subscribing to Business API Events

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

• External System: An existing external system where the payload information of the event is going to be sent (pushed).

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:

• Ancestors : The payload information will be sent in case the organization in the payload is the same or is an ancestor of the organization of the subscription.
• Descendants : The payload information will be sent in case the organization in the payload is the same or is a descendant of the organization of the subscription.
• Natural Tree (Ancestors and Descendants) : The payload information will be sent in case the organization in the payload is the same or is ancestor or descendant of the organization of the subscription.

Following the example of the pictures above:

• The organization tree direction of the event is Natural Tree (Ancestors and Descendants)
• The event subscription organization is North East Zone

The organization tree is as follows:

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:

• Organization in the payload is The White Valley Group: EVENT IS PUSHED
• Organization in the payload is White Valley Spain S.A: EVENT IS PUSHED
• Organization in the payload is Vall Blanca Store: EVENT IS PUSHED
• Organization in the payload is The White Valley Franchise: EVENT IS NOT PUSHED
• Organization in the payload is South West Zone: EVENT IS NOT PUSHED

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:

• event: The search key that identifies the event
• recordId: The identifier of the record whose information is going to be used to generate the event payload

 
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:

• event: The search key that identifies the multiple record event
• params: A Map<String, Object> with the names (map keys) and values (map values) of the export filter

 
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.

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:

• Trigger all events except some: Check the Trigger All Events field and add in the the Events to Integrate subtab the events that should be excluded (if any) by checking the Is Excluded field.
• Trigger some specific events: Leave the Trigger All Events field unchecked and add in the Events to Integrate subtab the events that should be included, leaving the Is Excluded field unchecked.

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:

• External System Type: Openbravo Business API
• Start Integration From Time: the desired initial date and time for the lastUpdated parameter

Event Triggering Flow

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.

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
API_PurchaseOrderBook	By Single Record ID	Triggered when a purchase order is booked	org.openbravo.api
API_StockTransactionC	Multiple Record Event Triggering Background Process	Warehouse transactions related to customers. It is associated to goods shipments to customers (in negative) and returns from customers (in positive)	org.openbravo.api
API_StockTransactionI	Multiple Record Event Triggering Background Process	Warehouse transactions related to inventory counts	org.openbravo.api
API_StockTransactionM	Multiple Record Event Triggering Background Process	Warehouse transactions related to goods movements. They include internal movements inside the warehouse or movements between two warehouses. Referenced Inventory movements are also included here.	org.openbravo.api
API_StockTransactionV	Multiple Record Event Triggering Background Process	Warehouse transactions related to vendors. It is associated to goods receipts from vendors (in positive) and returns to vendors (in negative)	org.openbravo.api
AWOAPI_StockTransactionC	Multiple Record Event Triggering Background Process	Warehouse transactions created by AWO related to customers registered since the datetime passed as parameter. It is associated to goods shipments to customers (in negative) and returns from customers (in positive)	org.openbravo.warehouse.advancedwarehouseoperations.api
AWOAPI_StockTransactionI	Multiple Record Event Triggering Background Process	Warehouse transactions created by AWO related to inventory counts registered since the datetime passed as parameter.	org.openbravo.warehouse.advancedwarehouseoperations.api
AWOAPI_StockTransactionM	Multiple Record Event Triggering Background Process	Warehouse transactions created by AWO related to goods movements registered since the datetime passed as parameter. They include internal movements inside the warehouse or movements between two warehouses or Referenced Inventory movements	org.openbravo.warehouse.advancedwarehouseoperations.api
AWOAPI_StockTransactionV	Multiple Record Event Triggering Background Process	Warehouse transactions created by AWO related to vendors registered since the datetime passed as parameter. It is associated to goods receipts from vendors (in positive) and returns to vendors (in negative)	org.openbravo.warehouse.advancedwarehouseoperations.api
OBDOAPI_UpdateDOStatus	By Single Record ID	Triggered when a distribution order changes its status	org.openbravo.distributionorder.api
OBDOAPI_UpdateDOStatusOutsideAPI	By Single Record ID	Triggered when a distribution order changes its status from the application, excluding any trigger done by the API	org.openbravo.distributionorder.api
OBDOAPI_UpdateDOQuantities	By Single Record ID	Triggered when a goods movement updates the distribution order's issued/received quanties	org.openbravo.distributionorder.api
OBDOAPI_StockTrMLinkedToDO	Multiple Record Event Triggering Background Process	Warehouse transactions related to goods movements linked to distribution order.	org.openbravo.distributionorder.api
OBDOAPI_StockTrMNotLinkedToDO	Multiple Record Event Triggering Background Process	Warehouse transactions related to goods movements not linked to distribution order.	org.openbravo.distributionorder.api
API_GoodsReceipt	By Single Record ID	Triggered when a goods recipt is completed.	org.openbravo.api
API_GoodsShipment	By Single Record ID	Triggered when a goods shipment is completed.	org.openbravo.api
API_ReturnToVendorShipment	By Single Record ID	Triggered when a return to vendor shipment is completed.	org.openbravo.api
API_ReturnMaterialReceipt	By Single Record ID	Triggered when a return naterial receipt is completed.	org.openbravo.api
API_ShipmentInOut	By Single Record ID	Is a generic event. Triggered when a goods receipt, goods shipment, return material receipt or return to vendor shipment is completed. Wihtout distinguishing the type of documment.	org.openbravo.api

Read Only Pool Configuration For Business API

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

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:

• Export Web Service
• Business API events

Preference

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

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.

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.

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.