View source | Discuss this page | Page history | Printable version   

Module:Openbravo Business API

Contents

Introduction

This module provides the Openbravo Business API. It contains the basic definition of common Business API entities which can be extended by other modules. Besides, it provides different mechanisms for importing and exporting information from those entities.

Business API Entity Mapping

Bulbgraph.png   Before starting reading this section, we recommend to take a look at the External Integration Infrastructure User Guide.

The definition of the standard Business API entities is present in the Entity Mapping window. These definitions can be modified and/or extended with custom modules as any other entity mapping definition.


EntityMappingRetailAPI.png


The export mappings (From Openbravo to External System integration direction) allows to define export filters which can be created under the Export Filters subtab.

Each of the records present in this tab will result in a new filter of the entity export endpoint. In addition, a default filter "byID" is automatically added for each export entity. Note that the definition of the byID filter is not displayed in this tab.


RetailApiExportFilters.png


The export filters require the following information:

RetailApiExportFilterDetail.png

If an export filter uses parameters, the metadata information of each parameters should be added in the Export Filter Parameters tab:

ExportFilterParameter.png

Business API Web Services

The Business API module provides a set of Web Services that can be used to either import or export records of each of the entities previously mapped in the Entity Mapping window for the Openbravo Business API system type, as explained in the previous section.

Open API Specification

The specification of the Business API Web Services can be seen and tested with this live environment.

Asynchronous Import

The import of elements through any of the available Business API import web services is done in an asynchronous way using EDL. This web services usually return the ID of the EDL request in charge of the import task.

Bulbgraph.png   It is required to configure the JSON Based Import EDL process in the EDL Configuration to make use of the Business API import web services.

The Status Web Service allows to check the status of that kind of EDL requests in order to know whether the import process has (successfully) ended or not. This service can be invoked through a GET request to the following URL:

https://<openbravo_url>/ws/org.openbravo.api.StatusService?id=<edl_request_id>

Postman Collection

The Business API module includes an up-to-date Postman collection with several request examples for the different entities. See here. It is recommended that those modules that extends the Business API provide their own Postman collection because it is a very good way of depicting how the API must be consumed.

Business API Data Load Process

This process is another option to import elements in Openbravo through the Business API infrastructure.The importing is done in an asynchronous way using EDL. We can select this option as alternative to Business API Web Services.

Data Load Window

Business API Data Load Process is used in the Business API Data Load Window with only two mandatory fields to be filled.


RetailAPIDataLoadWindow.png


The mandatory fields to be filled are:

Bulbgraph.png   Modifying the limit of the file size could put the server down due to an out of memory error. We need to take care changing the preference and be sure that we do not cause out of memory error or performance problems. Check the perfomance analysis done to have more info about this

How to support new import formats

We are able to import JSON files for all Entities by default thanks to DefaultJSONImportFileHandler class. In case we need to handle a different file type for an Entity, we can implement a new ImportFileHandler class.

The ImportFileHandler interface provides a way of transforming raw data supplied in a given input stream to a stream of JSON objects so that the data can be handled by the Business API import infrastructure.

Classes that implement this interface should declare the EntityMappingId and FileExtension qualifiers to define the entity mapping and the file extension that they can handle. We also need to implement the abstract method getData and we can override getPriority method. See below more info about the class to be implemented.

 
import org.openbravo.api.file.FileExtension;
import org.openbravo.api.file.ImportFileHandler;
import org.openbravo.service.external.integration.mapping.EntityMappingId;
 
/**
 * Annotation to associate a Java component to an entity mapping through its ID
 */
@EntityMappingId("78328CA91BBD4BD6A4FD94E9DDE7F4EE")
/**
 * Annotation to associate a Java component to file extension to import the file data
 */
@FileExtension("txt")
public class ExampleImportFileHandler implements ImportFileHandler {
 
  /**
   * Gets an stream of JSON objects from the data retrieved through the given InputStream
   * 
   * @param rawData
   *          an InputStreamwith the raw data to be imported
   * @param entityID
   *          the id of the Entity to be imported
   * @return a Stream of JSONObject generated from the data provided in the given InputStream
   * @throws IOException
   *           if an I/O error happens while retrieving the data
   */
  public Stream<JSONObject> getData(InputStream rawData, String entityID) throws IOException {
    // implement with the logic to generate the stream
  }
 
  /**
   * @return an integer representing the priority of this ImportFileHandler. It is used to select
   *         the most priority handler in case there exists several that can handle imports for the
   *         same entity and the same file extension. In that case, the one with the lowest priority
   *         will be taken.
   */
  @Override
  public default int getPriority() {
    return 100;
  }
}

In the above example we implement the support for txt files for the Openbravo Business API entity whose ID is 78328CA91BBD4BD6A4FD94E9DDE7F4EE.

Bulbgraph.png   There is a BaseCSVImportFileHandler class which can be extended and can be used for CSV type files but ONLY for plain entities (not nested objects inside the main object). We must test properly the ImportFileHandler created and ensure that entities are properly imported.

Push API

Starting from version 1.0.200 the Openbravo Business API module allows to define Business API events. See here for additional information.

Process to change the Business API

The main goal of this project is to provide a business, functionally-relevant webservice-based API that customers can use to integrate their systems with Openbravo.

In order to achieve this goal, the API should remain reasonably stable over different releases so that customers can update Openbravo without fear of breaking their integrations.

That said, sometimes it is unavoidable to make changes. The way these changes should happen is the following:

The API changes documentation can be found here.

Business API Extensions

The Openbravo Business API can be extended by either including new properties to the common Business API entities or by creating brand new entity definitions. In this section we present some of the existing standard extensions.

Retail API

The Retail API extension adds some new retail specific properties into the common mappings and provides new entities like Assortment.

Migrating from versions previous to 2.0.0

Before version 2.0.0 the Retail API module also contained all the infrastructure that now is present in the Openbravo Business API module. If you are updating from a version previous to that one, you must ensure that also the following modules are installed:

  1. Openbravo Business API
  2. Open API

Together with this, the former web service address keeps working for backwards compatibility but it is strongly recommended to use the new addresses that are referred here.

Retail API for Giftcards

The Retail API for Giftcards is an extension of the Retail API module that provides the ability of both import and export the Giftcard entity.

Apart from making possible to import gift cards with the standard .json format, it also provides the ability of importing Giftcards through .csv files. See here to know more about importing data through files.

Related Resources

Retrieved from "http://wiki.openbravo.com/wiki/Module:Openbravo_Business_API"

This page has been accessed 3,452 times. This page was last modified on 5 June 2023, at 06:16. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.