Projects:Retail/POS JSON Web Services

Contents 1 Introduction 2 Testing JSON Web Services 3 Executing HQL queries 3.1 Equivalence with JSON REST Web services 3.2 Retrieving only selected fields 3.3 Predefined filters 3.4 Parameters 4 Executing Processes 5 Using the HTTP method GET instead of POST 6 Executing several HQL queries and Processes

Introduction

The POS JSON Web Services are a collection of JSON Web Services for Openbravo focused to provide access to data and business logic for Point of Sale terminals. Althought its focus on the Openbravo POS Terminal Client, these web services are generic and can be used for other clients or integration processes.

The POS JSON Web Services are based on the JSON REST Web Services. All the generic sections in that document like, Login and Security, Error result, Conversion from and to JSON, are common in both implementations.

Testing JSON Web Services

To test JSON Web Services there are multiple options that provide an easy way to execute JSON Web Services. In this document we use the Advanced REST client Application that runs on top of the Google Chrome web browser and can be installed from the Chrome Web Store.

The Advanced REST client application offers a convenient way of testing and executing the POS JSON Web Services, Allowing to execute, inspect the JSON results properly formated, save requests, etc.

Executing HQL queries

The POS JSON Web service allows to execute HQL queries to retreive data from Openbravo entities. The Web service is located in /org.openbravo.service.retail.posterminal.jsonrest context, and queries are writen in JSON format and use the HTTP method POST. The first example shown is to execute a simple HQL query that retrieves a list of Business Partners filtered by one simple criteria:

{"query" : "from BusinessPartner where customer = true and $readableCriteria"}

This query shows all business partners that are marked as customers and that can be read by the Openbravo role that is executing the web service. It means the business partner records listed belongs to a readable entity and organization and are marked as active.

Equivalence with JSON REST Web services

In order to provide homogeneity between both JSON Webservices provided by Openbravo the format of the result in JSON REST Web services and POS JSON Web services is the same. As an example the result of the JSON REST Web service request:

http://localhost:8080/openbravo/org.openbravo.service.json.jsonrest/BusinessPartner?_where=customer=true

Returns the same result as the request:

http://localhost:8080/openbravo/org.openbravo.service.retail.posterminal.jsonrest?content={%22query%22%20:%20%22from%20BusinessPartner%20where%20customer%20=%20true%20and%20$readableCriteria%22}

Retrieving only selected fields

In the previous HQL query examples we requested all fields of one entity. If you want to request only some fields of the entity you can add a SELECT clause to the HQL query.

{"query" : "select name as name, searchKey as searchKey, uPCEAN as uPCEAN, productCategory.name as productCategory from Product where sale = true and $readableCriteria"}

If an alias is used for select fields, it will be used to identify the field in the JSON return object. Otherwise an index will be used.

Predefined filters

In the previous sample queries we have been using the predefined filter $readableCriteria. There are other predefined filters available to use in POS JSON Web services:

• $clientCriteria: filters by readable entities
• $orgCriteria: filters by readable organizations
• $activeCriteria: filters by active records
• $readableCriteria It is a combination of the three previous criterias. It filters by readable entities, organizations and active records.

Parameters

You can add parameters to queries. These parameters can come with a type, where the type can be one of the following values: string, hashedstring, encryptedstring, long, float, bigdecimal, boolean, binary, datetime, date or time.

{
"query" : "from Product where $readableCriteria and productCategory.name = :categoryName",
"parameters" : {"categoryName" : {"value" : "Biológicas", "type" : "string"}}
}

Or without a type. In this case the type is infered based on the value provided: string for JSON string or null values, bigdecimal for numbers and boolean for booleans. In the following example the parameter is considered as string.

{
"query" : "from Product where $readableCriteria and productCategory.name = :categoryName",
"parameters" : {"categoryName" : "Biológicas"}
}

Executing Processes

The POS JSON Web Service can also execute PL/SQL processes defined in the Reports and Processes window. The following example processes a sales order in draft status:

{"process" : "C_Order Post", record="FF80818133651D2B013365436E90001A"}

And returns the following result

{
  "response": {
    "status": 0,
    "result": 1,
    "record": "FF80818133651D2B013365436E90001A",
    "message": "Shipment nº AS/20 created , Invoice Nº FV/10 created"
  }
}

Using the HTTP method GET instead of POST

Other option to execute HQL queries and processes is using the HTTP method GET and using the parameter content for the content. The content must be properly encoded. For example the following GET request:

http://localhost:8080/openbravo/org.openbravo.service.retail.posterminal.jsonrest?content={%22query%22%20:%20%22from%20BusinessPartner%20where%20customer%20=%20true%20and%20$readableCriteria%22}

Is equivalent with a POST request with content:

{"query" : "from BusinessPartner where customer = true and $readableCriteria"}

Executing several HQL queries and Processes

The POS JSON Web Service can execute several HQL queries and processes in a single request. To do this just write one JSON array that contains all the HQL queries and processes you want to execute. The result will be a JSON array with each result. For example:

[
{"query" : "from BusinessPartner where customer = true and $readableCriteria"},
{"query" : "from Product where sale = true and productCategory.name = 'Biológicas' and $readableCriteria"}
]