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.
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.
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
- 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.
- 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.
- 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", "<");
- 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.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.