Web Services First Steps

Note (Release 14+): The SOAP Web Services bundle (org.idempiere.webservice) has been removed from iDempiere core and is now distributed as a separate optional plugin. Install it via the Extension Manager from this repository if your implementation requires SOAP. See the Migration Notes for upgrade instructions. Implementations using only the REST API are unaffected.

---

I started to experiment with Web Services and iDempiere but I could not find a good introduction, so I documented the steps I took to get into it. Here you can see how to create a simple read-only Web Service to retrieve Business Partner details to get you started.

Pre-requisites

Before you start, make sure that the web services plugin is installed and active (which should be the case with a standard iDempiere installation) by browsing to:

 http://localhost:8080/ADInterface/services

The server name is localhost if you installed iDempiere locally, otherwise replace localhost with the name of your server if not.

You should see a page showing two kinds of SOAP services and their methods, namely CompositeService and ModelADService, as well as a RESTful service:

(Note that the name of the server has been edited out in the example above, hence the blank spaces.)

Standard SOAP web services are described by a Web Service Definition Language (WSDL) file which you can see in the links above on the right. For example, the WSDL file for the Model Oriented Service Interface is:

 http://localhost:8080/ADInterface/services/ModelADService?wsdl

You use the Web Service by posting a SOAP request to the URL. The SOAP request is a WSDL file of XML statements that describes the location of the service and the data to be passed in messages for particular operations.

Create the Web Service to access iDempiere

The first step to use a Web Service in iDempiere is to create an entry in the Application Dictionary and configure it with the name of the table that contains the data and the roles that have access to the service, amongst other things.

For this example, log in as SuperUser/GardenAdmin to create a web service to query a list of Business Partners, as follows:

• Open the window Web Service Security
• Create a new entry to describe the Web Service with the following:
  • Search Key: TestWebservices (the Search Key is important because it is the name that you use in your request)
  • Name: TestWebservices (the same as the Search Key in this example, but you can be more creative)
  • Web Service: Model Oriented Web Services (this is easier to start with than a Composite service)
  • Web Service Method: Model Oriented Web Services_Query Data (choose from the dropdown list)
  • Table: C_BPartner_Business Partner (choose from the dropdown list)
• Save the entry

In the Web Service Parameters Tab below, add two parameters:

• Parameter Name: TableName and Parameter Type: Free
• Parameter Name: RecordID and Parameter Type: Free

(Note: you can use constant values instead if you want to experiment further, such as TableName C_BPartner and RecordID 50003 for "Chemical, Inc.")

In the Web Service Field Output tab, configure the output field(s). You can add as many columns as you like but virtual columns do not work here (which may be a bug):

• Column: Name_Name

Lastly, in the Web Service Access tab add the Roles that need access to the Web Service:

• Role: GardenWorld Admin (choose from the dropdownlist)

(Note: the username and role must be specified in the WSDL file when you send the web service request.)

Create the WSDL request file

The next step is to create the WSDL file that contains the XML that describes the request. This is a text file in XML format that you will send to the SOAP Web Service as the payload of an HTTP request.

You can create it manually from the command line (see below), or you can use the SoapUI testing tool to create it if you prefer not to use the command line.

Create and send the WSDL file using SoapUI

If you prefer to use SoapUI, install it as follows:

• Download the executable from here
• Make it executable (chmod a+x)
• Run the installer

Once SoapUI has been installed:

• Start the application
• Click on the "SOAP" button in the toolbar to create a new SOAP project
• Give it a name
• Enter the link to the WSDL: http://localhost:8080/ADInterface/services/ModelADService?wsdl

Now SoapUI magically creates examples for all the methods. Remember to press the "Save All" button to save your project files. It is not done automatically.

Use the sample data in the WSDL file request.xml described in the next section to do a simple query.

I did not find an alternative to SoapUI, but you could probably write your own using this soap-ws Java library.

Create the WSDL file manually

The WSDL file is just a text file in XML format, so you can create it manually with a text editor. Create a text file request.xml in a convenient location with the following content:

 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:_0="http://idempiere.org/ADInterface/1_0">
   <soapenv:Header/>
   <soapenv:Body>
     <_0:queryData>
       <_0:ModelCRUDRequest>
         <_0:ModelCRUD>
           <_0:serviceType>TestWebservices</_0:serviceType>
           <_0:TableName>C_BPartner</_0:TableName>
         </_0:ModelCRUD>
         <_0:ADLoginRequest>
           <_0:user>SuperUser</_0:user>
           <_0:pass>System</_0:pass>
           <_0:lang>en_US</_0:lang>
           <_0:ClientID>11</_0:ClientID>
           <_0:RoleID>102</_0:RoleID>
           <_0:OrgID>11</_0:OrgID>
           <_0:WarehouseID>103</_0:WarehouseID>
           <_0:stage>0</_0:stage>
         </_0:ADLoginRequest>
       </_0:ModelCRUDRequest>
     </_0:queryData>
   </soapenv:Body>
 </soapenv:Envelope>

The query data

The WSDL query starts with the details of the Web Service that you configured above, TestWebservices in this example, and the name of the table with the data, C_BPartner.

The login data

Your web service client must be able to login, so fill the ADLoginRequest part of the WSDL file with the same credentials you enter when you log in manually. In the example above I used:

• user: Superuser
• pass: System
• ClientID: 11 (GardenWorld)
• RoleID: 102 (GardenAdmin)
• OrgID: 11 (HQ) and
• WarehouseID: 103 (HQ)
• stage: 0 (stage is not actually used, but you will get an error if you leave this out)

The ADLoginRequest looks like this:

 <_0:ADLoginRequest>
   <_0:user>SuperUser</_0:user>
   <_0:pass>System</_0:pass>
   <_0:lang>en_US</_0:lang>
   <_0:ClientID>11</_0:ClientID>
   <_0:RoleID>102</_0:RoleID>
   <_0:OrgID>11</_0:OrgID>
   <_0:WarehouseID>103</_0:WarehouseID>
   <_0:stage>0</_0:stage>
 </_0:ADLoginRequest>

Sending the Web Service Request

Web service request using curl

You can use the standard curl utility to send and receive the HTTP request. You can get curl from here if it is not already installed.

Send the HTTP request with the SOAP details in the WSDL file as follows:

 curl --header "Content-Type: text/xml; charset=utf-8" --data @request.xml http://localhost:8080/ADInterface/services/ModelADService 

The --data parameter @request.xml is the name of the XML file that describes your SOAP request (the @ symbol tells curl that the data must be read from a file).

Web service request using wget

You can also use wget to send the HTTP POST request and save the result to an XML file:

 wget http://localhost:8080/ADInterface/services/ModelADService --post-file=request.xml -O testresult.xml

You can use xmllint to format it if you want (or use any other XML formatting tool)

 xmllint --format testresult.xml

And the result is:

 <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
     <ns1:queryDataResponse xmlns:ns1="http://idempiere.org/ADInterface/1_0">
        <WindowTabData NumRows="17" TotalRows="17" StartRow="0" xmlns="http://idempiere.org/ADInterface/1_0">
           <DataSet>
              <DataRow>
                 <field column="Name">
                    <val>Chemical Product, inc</val>
                 </field>
              </DataRow>
              <DataRow>
                 <field column="Name">
                    <val>Chrome, Inc</val>
                 </field>
              </DataRow>
              <DataRow>
                 <field column="Name">
                    <val>Color, Inc</val>
                 </field>
              </DataRow>
              <DataRow>
                 <field column="Name">
                    <val>C&W Construction</val>
                 </field>
              </DataRow>
 
              ...
 
              <DataRow>
                 <field column="Name">
                    <val>Wood, Inc</val>
                 </field>
              </DataRow>
           </DataSet>
           <RowCount>17</RowCount>
           <Success>true</Success>
        </WindowTabData>
     </ns1:queryDataResponse>
  </soap:Body>
 </soap:Envelope>

If you want to add example code that you used feel free to add or link it here. :-) --TBayen (talk) 14:31, 8 August 2015 (CEST)