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
 | 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.
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.
The export filters require the following information:
- Name: the filter name (byID name can not be used as it is reserved)
- HQL Where Clause: a where clause to be applied on the main entity (Mapped Entity). It supports using parameters with the standard parameter notation (using :).
- Description: metadata information which is included in the Open API specification.
- Return Multiple Results: it should be marked if after applying the filter multiple results can be returned. If just a single element is returned by the filter do not check this field.
If an export filter uses parameters, the metadata information of each parameters should be added in the Export Filter Parameters tab:
- Name: the parameter name
- Type: the parameter type
- Description: the parameter description
- Example: one of the possible values that the parameter can take
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.
| | 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.
The mandatory fields to be filled are:
- Entity: The Entity to be Imported. This Entity must be defined in Entity Mapping Window with System Type Business API Connector and with Integration Direction From External System to Openbravo.
- File: The file with the data to be imported. It supports any type of file but only json can be handled by default. We can implement any kind of files to be imported. See how in the following link. There is a default limitation of 10MB for the file size. This limit can be modified by overriding the preference Maximum Process File Upload size (MB).
| | 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.
| | 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:
- First, changes should be anticipated by the developer that is doing them. However, if not, automated tests will detect most cases anyway.
- Secondly, depending on the kind of change, different actions should take place:
- If changes consist in just adding new properties to an exporting entity, they should be documented in the API changes documentation.
- If changes consist in a fundamental modification of an structural part of an exporting entity (like removal of properties, or change of the data type of a property, or changing a one-to-many relationship into one-on-one), then an API change issue should be reported and approved by Product Organisation. If finally approved, the API changes documentation should be updated to include this changed.
- If changes consist on an addition of a new, non-mandatory property in an importing entity, then these changes should be documented in the API changes documentation.
- If changes consist either on a fundamental modification of a structural part of an importing entity, or an addition of a mandatory new property to an importing entity, an API change issue should be reported and approved. If finally approved, the API changes documentation should be updated.
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:
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.