Skip to end of metadata
Go to start of metadata

 

1.         Overview

Compiere web-services are based on Compiere Data Dictionary. They provide a unified mechanism to create, update and retrieve data from any Table definition. The advantage of having the web service based on the dictionary is that the users can make changes to the column definitions in the dictionary, and these changes are immediately visible to the Web services without any code change. This functionality was introduced to Compiere in version 3.4.

In order to take advantage of these Web Services, Users of this document should be familiar with Compiere Data Dictionary.

1.1       Data Dictionary

The following are the steps that users generally perform in the data dictionary:

1.     Create Table and Column definition. Use Reference Types to setup each column

2.     Create Window, Tab and field definition. Each Tab is linked to a table and fields are linked to a column.

The Tab definition serves as a way to access table data. Similarly, web services provide another way to access the same Table data. So, whatever operations that can be performed in a Window-Tab can also be performed by the Web Service.
For example, to define a Sales Order in Compiere window, user would first go to the Sales Order window and enter the Order information. Then, the user would then proceed to the Order Line tab and enter Order Line information. The same operations can be performed via web services by invoking a Create on the Order Tab and another Create on the Order Line Tab.

2.       Security

 Compiere REST services are authenticated using a Secret Key. A secret key will be generated for each user. A User will sign a request using the Secret Key, and pass the generated Signature as a part of the Request. The Compiere Server will accept this Signature and authenticate the user-request. The request will be processed only if the user is validated. An Invalid User is returned an error with 401 Response Code.
The security mechanism is similar to the one Amazon uses for its RESTful Services.

2.1       Security Setup

The secret key for a User is specified in the User window as shown in the screen below. The user would need to hit the "Generate User Key" button to populate the User key field. Using the user key, a webservice request can now be made to the Compiere application.

Note: The generated user key is stored after encoding it in Base64. So when generating the signature, you must first decode the user key in Base64, and then use the algorithm. This step may not be available in all libraries (e.g. Amazon javascript libraries).

3.         Calling Web Services

 

The following code shows how to call the Compiere web-services by passing in the User ID, Secret Key and other mandatory parameters. The example shows a GET operation being performed on the Order table. $Compiere_Home/lib/Websevices-client.jar is required by the client-code to sign the request.

3.1       Code Sample 1

                   

        

The above example can be modified by the user by changing the urlString, host and port to point to the appropriate Compiere instance. Users would also need to pass the Organization, Tenant, Role and Warehouse parameters as they are mandatory to perform any operation in Compiere.

3.2       Getting Data from Compiere Web Services

To get data, user can make a GET request by passing in the Table Name as a part of the request. Code Sample 1 shows that the user is passing Order in the urlString apps/Rest/Order where Order is the Table Name. Similarly, the urlString apps/Rest/Business%20Partner will retrieve all the Business Partners in the System.

The response string contains the XML of the Table Name. The XML being returned can be described at a high level as follows:











3.2.1  Additional Parameter for Get

  1. showDetails = Y: By default, the xml being returned will contain all the columns for the table. So, in the above example a call to Order would return the Order information with the Order header, Date, Business Partner ID, etc. To get the de-normalized information for the ID columns, the user will need to pass a parameter such as "showDetails=Y".
    NOTE: showDetails=Y will return more information in the XML and hence should not be used while retrieving large data.
  2.  Restrict Result Set: Users can pass additional parameters in the request to restrict the result dataset. These parameters should correspond to the Column names in the table.
    Eg: By adding an extra parameter: params.put("Business Partner","Joe Block"); the GET would return just the Orders (Sales and Purchase) for business partner Joe Block. To get just the Sales Orders, user can pass additional parameter like: params.put("Sales%20Transaction","Y"); to return just the Sales Order.
  3. Date Range search: By default, the user parameters are treated as AND with parameter value being EQUAL TO. But users can also perform a BETWEEN type search with parameter values being > and < by passing the parameter in following format.
    Eg: To perform a Search on Orders between Jan 2002 and March 2002, users can pass the following parameters.
    params.put("searchParameter1""Date Ordered");params.put("searchValue1""01/01/2002");params.put("operator1"">");params.put("searchParameter2""Date Ordered");params.put("searchValue2""03/01/2002");params.put("operator2""<");
  4. Help: There is a Help option provided that will show the format of the data being retrieved. To use this, the request needs to contain a Help parameter. 
    Eg: params.put("Help""Y");will return the structure of XML document for Order.
    NOTE: Help option is useful if user wishes to perform a Create or Update, and wants to know the format in which he/she needs to submit the XML document.

3.3       Creating Data from Compiere Web Services

In order to create data in the dictionary, user needs to submit an XML document as a payload along with the request. The structure for the payload XML document can be described at a high level as follows:








The dictionary definition for each column dictates the values for each column. Eg. If the column is a lookup, the user can specify either:
a. The value element specified as tags OR

b. The info element specified as tags

Similarly, for Date columns user can specify the Value tag with the Date value. The format used for dates is the one derived from Compiere Language date formats.

Code Sample 2 described below shows how to create a new Business Partner

3.3.1  Code Sample 2

The file being referenced is /Compiere2/businessPartnerCreate.xml.It contains the actual data for Business Partner, which looks like this:

 

The above XML describes a Business Partner called "Test WebService Business Partner 001" belonging to C_BP_Group_ID (i.e Business Partner Group) "Standard Customers". The C_BP_Group_ID is specified as "Table Direct" in the dictionary. So, user can specify the Value instead of the Info. This can be done by specifying <C_BP_Group_ID> <Value>103</Value><C_BP_Group_ID>.
Similarly, Name is a Text field, so User can only specify the Value (and not the Info).

3.4       Updating Data from Web Services

Updates in the data dictionary are very similar to create where the XML payload is specified as a part of the request. The only differences are:

-         In Code Sample 2, Post would have an Action of Update instead of Create.
// Make a post request with action="Update"
org.compiere.gwt.ws.jaxb.QueryResponse qr = c.makeRequest(post, "Update", params, org.compiere.gwt.ws.jaxb.QueryResponse.class);

-         The payload xml needs to contain the key column to identify the record being updated.

3.5 Examples

3.5.1 Create an Order with an Order Line and Complete the Order

This is a 3-step process where user user would need to:

 Step 1. Create an Order i.e. perform a "Create" action on "Order" object. The following is a sample XML that creates an Order for customer "Joe Block"






Step 2: Create an Order Line by performing a "Create" action on "Order%20Line" object. The following XML sample shows how to create an Order Line for the Order created in Step 1. NOTE: The Order is referenced using the tag <C_Order_ID>, which contains the Order Id. Alternately, the user can reference the Order using the <Info> tag instead of <Value>. Eg:  <Info>80003_03/11/2009</Info>






Step 3: Complete the Order by performing an "Update" action on the "Order" object. The following XML sample shows how to complete the Order created in Step 1 above. In this case, the process associated with "Complete" process is executed when the Order is Completed.







3.5.2  Create a Business Partner with a Location

Step 1: Create a business partner by performing a "Create" action on the "Business%20Partner" object. The following XML sample shows the creation of a standard business partner called "John Doe"

 Step 2: Create a business partner location by performing a "Create" action on the "Partner%20Location" object. The following XML sample shows the creation of a location with the address field.






4.   Known Issues

1. XML files created using Windows notepad can contain BOM (byte-order mark) characters which cannot be parsed by Java. Workaround is to use some other editor to save the file in UTF-8 without BOM mode.

Labels
  • None
  1. Oct 20, 2009

    I think there is an error in this document

    apps/Rest/Business%20Order 

    should read

    apps/Rest/Business%20Partner

    1. Nov 12, 2009

      It should indeed be apps/Rest/Business%20Partner. I have corrected it for now. Thanks for pointing it out!

  2. Dec 04, 2009

    I don't understand why we have to give the NAME of the column to filter a result set ? Why don't we use the Column Name it self.

    The name can be change anytime ?!.. A third developper don't know wich name has been set for a column.

    EG:

    "Use Business%20Partner" => 1000000

    We should use "C_BPartner_ID" => 1000000

    1. Dec 05, 2009

      Vincent,

       When you go to the table definitions window in Compiere, you will use "Name" in the Column page. For example if I want to find all the locations for a business partner, I'd do the following

      http://localhost:8080/apps/Rest/Partner+Location?Action=query&operator1=%3D&searchParameter1=Business+Partner&searchValue1=Joe+Block

      (note: I left out the rest of the request uri )

      It took me a couple tries to figure out what the correct search value was as this documentation is not very complete, but it does use the Name as the parameter, that part I do know. I'm guessing the values depend on the type of the column( string, table, search, etc ). The documentation should be more clear.

  3. Dec 04, 2009

    You say that the Rest is based on the Windows-Tab-Field Definition.

    What about if a Table has more than 1 Window associated to it ? Which definition will be use ?

     EG : if I create a second window for Sales Order and display only few field. How may I access to this window ?

    Or to acess to Purchase Order window ?

  4. Dec 05, 2009

    Vincent,

     The parameters are based on the table. According to the docs

    "These parameters should correspond to the Column names in the table."

     The portion you read was just giving an example saying that whatever operations you can do in a window can be done in web services.

    "So, whatever operations that can be performed in a Window-Tab can also be performed by the Web Service."

    I am implementing web services now and using the Name field from the Table window.