Open Source ERP Academy

Web Services (RESTful and SoapUI)

The purpose of this discussion is to help you learn and use iDempiere web services.

New REST Web Services (202208)

The iDempiere project has created a new REST web services tool. It is currently supported as a plugin. Here are the installation instructions:

Web Services Installation and Configuration

iDempiere web services get installed out of the box. There is no additional installation effort required. ADempiere - I recommend you purchase the ADempiere Cookbook for more details about installing web services in ADempiere. Even though iDempiere does not require that you 'install' web services, you do need to configure them. Here is a Pack In for the Web Services Security window. This pack in will give you all the records you need for the below examples. To use this file, go to your client's Pack In window (not System Admin), create a new record, attach the above zip file, and click the button. If for some reason you get errors while executing any of the below samples, make sure the Web Services Execution role has access to both the Web Service Type record (see Web Services Security window) and the Report & Process (see Role window). Please note that Report & Process is needed if you are executing a process.

Concepts

iDempiere Web Services help other applications communicate with iDempiere. They enable external applications like web stores and point of sale systems (POS) to create, read, update and delete data without human intervention. The actions can be simple like getting the ID for a given Business Partner, or the actions can be complex like creating and completing a multi-line order.

SoapUI

SoapUI is an open-source web service testing application. It makes creating your first web service call very easy. Here are the Linux commands to install SoapUI: 
wget http://sourceforge.net/projects/soapui/files/soapui/5.0.0/SoapUI-x64-5.0.0.sh
chmod +x SoapUI-x64-5.0.0.sh
./SoapUI-x64-5.0.0.sh
Note: Replace 5.0.0 with the current version.

iDempiere's Web Services Web Page

The following page will provide basic details of iDempeire's web services. It also offers a link to the WSDL that will be used later. 
http://YourURL:8080/ADInterface/services
If you used my installation script, you do not need to include port 8080. Instead, Apache will port forward for you.

Making Your First Web Service Call from SoapUI

Making your first iDempiere web services request is simple. Here are the steps:
  1. Open SoapUI.
  2. Right-click on project (top left of screen) and create a new project.
  3. Give the project a name and paste the URL of iDempiere's ModelADService WSDL
  4. Expand your new project and open the CreateData -> Request 1 file.
  5. Copy and paste the below Soap request into the Request 1 file (overwriting what currently exists)
  6. Press the play button.
  7. You should get a message back with the ID of your new business partner.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:_0="http://idempiere.org/ADInterface/1_0">
   <soapenv:Header/>
   <soapenv:Body>
      <_0:createData>
         <_0:ModelCRUDRequest>
            <_0:ModelCRUD>
               <_0:serviceType>CreateBPartner</_0:serviceType>
               <_0:TableName>C_BPartner</_0:TableName>
               <_0:RecordID>0</_0:RecordID>
               <_0:Action>Create</_0:Action>
               <!--Optional:-->
               <_0:DataRow>
                  <!--Zero or more repetitions:-->
                  <_0:field column="Value">
                     <_0:val>ChuckWS2</_0:val>
                  </_0:field>
                  <_0:field column="Name">
                     <_0:val>ChuckWS2</_0:val>
                  </_0:field>
                  <_0:field column="TaxID">
                     <_0:val></_0:val>
                  </_0:field>
                  <_0:field column="IsVendor">
                     <_0:val>Y</_0:val>
                  </_0:field>
                  <_0:field column="IsCustomer">
                     <_0:val>Y</_0:val>
                  </_0:field>
                  <_0:field column="IsTaxExempt">
                     <_0:val>Y</_0:val>
                  </_0:field>
                  <_0:field column="Name2">
                     <_0:val>Steak2</_0:val>
                  </_0:field>
                  <_0:field column="C_BP_Group_ID">
                     <_0:val>105</_0:val>
                  </_0:field>
               </_0:DataRow>
            </_0:ModelCRUD>
            <_0:ADLoginRequest>
               <_0:user>WebService</_0:user>
               <_0:pass>WebService</_0:pass>
               <_0:lang>192</_0:lang>
               <_0:ClientID>11</_0:ClientID>
               <_0:RoleID>50004</_0:RoleID>
               <_0:OrgID>11</_0:OrgID>
               <_0:WarehouseID>103</_0:WarehouseID>
               <_0:stage>0</_0:stage>
            </_0:ADLoginRequest>
         </_0:ModelCRUDRequest>
      </_0:createData>
   </soapenv:Body>
</soapenv:Envelope>

iDempiere Web Service to Call A Process

The below sample web service calls on iDempiere's Auto Allocate process. This example assumes you have packed in the above Web Service Security zip file into your client. Doing so creates the "AutoAllocate" Web Service Type record in iDempiere. The below request will perform AR allocation for the GardenWorld "Joe Block" Business Partner. 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:_0="http://idempiere.org/ADInterface/1_0">
   <soapenv:Header/>
   <soapenv:Body>
      <_0:runProcess>
         <_0:ModelRunProcessRequest>
            <_0:ModelRunProcess>
               <_0:serviceType>AutoAllocate</_0:serviceType>
               <_0:ParamValues>
                  <!--Zero or more repetitions:-->
                  <_0:field column="C_BPartner_ID">
                     <_0:val>118</_0:val>
                  </_0:field>
                  <_0:field column="APAR">
                     <_0:val>R</_0:val>
                  </_0:field>
               </_0:ParamValues>
            </_0:ModelRunProcess>
            <_0:ADLoginRequest>
               <_0:user>WebService</_0:user>
               <_0:pass>WebService</_0:pass>
               <_0:lang>en_US</_0:lang>
               <_0:ClientID>11</_0:ClientID>
               <_0:RoleID>50004</_0:RoleID>
               <_0:OrgID>11</_0:OrgID>
               <_0:WarehouseID>103</_0:WarehouseID>
               <_0:stage>0</_0:stage>
            </_0:ADLoginRequest>
         </_0:ModelRunProcessRequest>
      </_0:runProcess>
   </soapenv:Body>
</soapenv:Envelope>

Report Process with File Response

This post demonstrates how your can run a report and get the report file via the response.

iDempiere Composite Web Services

Note: the below example was created by Deepak Pansheriya. He was also the lead developer in creating the composite interface. Special thanks goes to Deepak and his team. Without him, the world would be a much darker place. The iDempiere web service composite interface allows you to make multiple iDempiere calls in the same message. Before the composite interface was available, the following bullets were the typical web service flow to create an order: As you can see, this technique is verbose and cumbersome. It requires you to write much process logic. With composite web services, you can create a single message to perform all the above steps. Here is a sample composite request - copy the contents of this file into a SoapUI request and execute it. Make sure processed the Pack In located at the top of this page.

REST Example Read Payload

{
    "ModelCRUDRequest": {
        "ModelCRUD": {
            "serviceType": "",
            "TableName": "",
            "Filter": "",
            "Action": "Read",
            "DataRow": { //optional filter by column values
                "field": [
                    {
                        "@column": "",
                        "val": ""
                    }
                ]
            }
        },
        "ADLoginRequest": {
            "user": "",
            "pass": "",
            "lang": "en_US",
            "ClientID": "",
            "RoleID": "",
            "OrgID": "",
            "WarehouseID": "",
            "stage": "9"
        }
    }
}
Here is another example in google groups discussion

Calling a Web Service from Eclipse

There are times when you need to call a someone else's web service from within iDempiere. Turning a WSDL into usable java classes is pretty easy. Use Eclipse: File=>New=>Other=>Web Sevice Client. Enter the webservice URL and eclipse will generate classes for you. Example from Jan Below is a code example for communicating with iDempiere's web services - writing in Eclipse  - provided by Evan: 
Package org.idempiere.ADInterface._1_0;

public class EvansCallWebservice 
{
   public static void main(String[] args) 
   {
      System.out.println("Hello Webservice");
      ModelCRUD modelCRUD = new ModelCRUD();
      modelCRUD.setServiceType("CreateBPartner");
      modelCRUD.setTableName("C_BPartner");
      ModelCRUDAction action = new ModelCRUDAction("Create");
      modelCRUD.setAction(action);
      ADLoginRequest aDLoginRequest = new ADLoginRequest("WebService", "WebService", "192", 11, 50004, 11, 103, 0);
      ModelCRUDRequest req = new ModelCRUDRequest(modelCRUD, aDLoginRequest);
      try 
      {
         ModelADServiceProxy prox = 
            new ModelADServiceProxy("http://erpdev.suthbros.co.uk:8080/ADInterface/services/ModelADService");
         prox.createData(req);
         StandardResponse sResponse = prox.createData(req);
      } catch (Exception e) {}

   }
}

2014-06-24 AM Introduction to Web Services Discussion

Please read the below NOTE to understand I found an issue during the video that was later resolved after the video.

Calling iDempiere Web Services from Talend ETL

Here is a Talend project that shows you examples of the above concepts. Download the file, import it as a project into Talend, and play with the examples. Please note these examples depend on the above Web Service Security pack in.

2014-06-06 AM Using Talend to call iDempiere Web Service Run Process Discussion

Calling iDempiere Web Service from a Linux Command Line

This example was provided by Carlos Ruiz via the iDempiere google group. Execute: "bash TestModelMsg.sh MsgModelRunProcess" MsgModelRunProcess 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:_0="http://idempiere.org/ADInterface/1_0">
   <soapenv:Header/>
   <soapenv:Body>
      <_0:runProcess>
         <_0:ModelRunProcessRequest>
            <_0:ModelRunProcess AD_Process_ID="111" AD_Menu_ID="0" AD_Record_ID="103" DocAction="CO">
               <_0:serviceType>ProcessInvoice</_0:serviceType>
            </_0:ModelRunProcess>
            <_0:ADLoginRequest>
               <_0:user>WebService</_0:user>
               <_0:pass>WebService</_0:pass>
               <_0:lang>en_US</_0:lang>
               <_0:ClientID>11</_0:ClientID>
               <_0:RoleID>50004</_0:RoleID>
               <_0:OrgID>11</_0:OrgID>
               <_0:WarehouseID>103</_0:WarehouseID>
               <_0:stage></_0:stage>
            </_0:ADLoginRequest>
         </_0:ModelRunProcessRequest>
      </_0:runProcess>
   </soapenv:Body>
</soapenv:Envelope>
TestModelMsg.sh 
:
if [ $# -ne 1 ]
then
    echo "Usage: $0 Message_File
    echo " i.e.: $0 MsgModelSetDocAction
    exit 1
fi
FILENAME=ModelADService.wsdl.$
wget \
    --secure-protocol=SSLv3 \
    --no-check-certificate \
    --post-file=$1 \
    --save-headers \
    https://WWW.YOURURL.COM/ADInterface/services/ModelADService \
    -O $FILENAME
ls -l $FILENAME
cat $FILENAME
echo
rm -f $FILENAME