External System/UserGuide

Contents 1 Introduction 2 External System 2.1 HTTP External System 2.1.1 Authorization Type 3 Connectivity Check 4 Programmatic API 4.1 Backend 4.1.1 HTTP External System Send Methods 4.2 Client Side 4.2.1 HTTP External System Send Methods 4.2.2 Loading External Systems into the POS

Introduction

An external system represents an application or machine which Openbravo is able to communicate with. In the External System window we can register the configuration data required to communicate with an external system.

External System

To create a new external system configuration we have to navigate to the External System window, create a new record in the header and populate the following fields:

• Name: a descriptive name for the external system
• Protocol: the communication protocol to interact with the external system
• Description: additional explanatory text
• Active: whether the external system is ready to use (active) or not.

HTTP External System

If the selected protocol is HTTP then the HTTP subtab is displayed, allowing to configure the specific HTTP settings for the external system:

• URL: the URL of the external system
• Default Request Method: the default method used to send the HTTP requests. Note that this method can overwritten in the programmatic API used to communicate with the external system.
• Timeout: The maximum time in seconds allowed to complete an HTTP request, including the time for processing the HTTP response
• Active: whether the HTTP configuration is ready to use (active) or not
• Authorization Type: the authorization type used in the HTTP requests.

Note that it is only supported to have one active HTTP configuration per external system at a time.

Authorization Type

By default three types of authorization types are supported:

• No Auth: requests are sent without using any kind of authorization
• Basic Auth: user/password basic authorization. When it is selected two new fields are displayed which allows to enter the username and password for the authentication.
• OAuth 2.0: use of the OAuth 2.0 standard. When it is selected, three new fields are displayed which allows to insert the Client ID, the Client Secret and the authentication server URL.

Connectivity Check

Once the configuration of an external system is entered it is possible to test the connectivity with that external system by clicking on the Test button.

Programmatic API

Backend

There is a programmatic API that can be use to communicate with the configured external systems. The different types of external systems extend the ExternalSystem class which defines the API. Let's see an example of use:

  @Inject 
  private ExternalSystemProvider externalSystemProvider;
  ...
  ...
  ExternalSystem externalSystem = externalSystemProvider.getExternalSystem(externalSystemId).orElseThrow();
  CompletableFuture<ExternalSystemResponse> response = externalSystem.send(Operation.READ, "path", Map.of("queryParameters", Map.of("param", "1234")));

1. We first need to inject the ExternalSystemProvider that helps us to get the external system we want to communicate with.
2. We retrieve the external system instance with externalSystemProvider.getExternalSystem(externalSystemId), where externalSystemId is the ID of the external system configuration (C_External_System record).
3. We use the send method to send the information to the external system with an specific operation. In the example we are using the READ operation to retrieve data from the external system, the "path" url segment and a query parameter. Note that the send method returns a CompletableFuture containing the response coming from the external system.

The available send operations are:

• CREATE
• READ
• UPDATE
• DELETE

HTTP External System Send Methods

For HTTP external systems each of the operations is implemented with a different HTTP method:

• CREATE: POST
• READ: GET
• UPDATE: PUT
• DELETE: DELETE

Client Side

The external system Javascript API allows to communicate with external systems from the different mobile applications.

  // Retrieve the external system instance  
  const externalSystem = OB.App.ExternalSystem.get(externalSystemId);
  // Prepare the data and the configuration of the send operation
  const data = {p1: '1', p2 :'2'};
  const configuration = {operation: 'CREATE', path: 'myPath'};
  // Send the information to the external system
  const response = await externalSystem.send(data, configuration);

In this example we get a new external system instance from the ID of a known external system using OB.App.ExternalSystem.get. If the provided ID belongs to an external system that is unknown then the OB.App.ExternalSystem.get will throw an error.

Once we have the external system instance, we can use it to send information to the external system with the following parameters:

• data: a JS object containing the data to be sent to the external system
• configuration: additional options for the send operation. The main accepted properties are:
  • operation: one of CREATE (default), READ, UPDATE, DELETE.
  • path: optional extra path to be included to the base address of the external system

HTTP External System Send Methods

For external systems based on the HTTP - Frontend protocol a different HTTP method is used by the send method depending on the operation provided in the configuration:

• CREATE: POST
• READ: GET
• UPDATE: PUT
• DELETE: DELETE

Loading External Systems into the POS

As explained in the previous section, the known external systems for a terminal of a mobile application are kept in the externalSystems terminal property.

To be able to load the external systems into that property for the POS, the org.openbravo.retail.posterminal provides the ExternalSystemLoader interface that can be implemented to specify the external systems whose information must be loaded into the terminal. This way different modules, by following its own logic, can specify the external systems that can be referenced by its ID.

public class ExternalSystemLoaderExample implements ExternalSystemLoader {
  @Override
  public Set<String> getExternalSystems(JSONObject jsonSent) throws JSONException {
    return Set.of("externalSystemID1", "externalSystemID2");
  }
}