Web Services First Steps

I started to experiment with Web Services and iDempiere but I found no introduction, so I documented the steps I took to get into it.

Pre-requisites

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 (replace localhost with the name of your server if not).

You should see a page showing two kinds of web services and their methods (note that the name of the server has been edited out in the example below):

Standard SOAP web services are described by a 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

Creating the Web Service Request

You need an XML file that describes the request to access a SOAP Web Service. You can do 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.

Web service request using SoapUI

Install SoapUI 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. That is not done automatically.

I did not find an alternative to SoapUI to create the example files but you could probably write your own using [this soap-ws Java library].

Web service request using curl

If you understand how SOAP works it is not difficult to read the WSDL and create the XML manually. You can then use the standard curl utility to send and receive the HTTP request. You can get curl from here if it is not already installed.

Create the request file and use curl to send the HTTP request with the SOAP details:

 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

Creating the Web Service to access iDempiere

Configure the Web Service

To use a Webservice you first have to configure it. For that you log in as GardenAdmin and open the window "Web Services Security". Let us create a web service to query a list of Business Partners.

You create a new Record. The Search Key is important. That is the name that you use in your Request. Let's call it "TestWebservice". The Service you use should be "Model Oriented WebServices" (for the beginning that is the easiest to start with) and the Method can be "Query Data" for this example. As the Table you choose "C_BPartner".

In the Tab for Parameters I added two parameters:

• "TableName" as a free parameter (or with a constant value of C_BPartner)
• "RecordID" as a free parameter (or with a constant value of 50003 (that is the record id of "Chemical, Inc.") if you want to experiment further)

I am not sure if and why these parameters are needed. Especially the RecordID seems senseless for me in a query. But the wsdl says they are needed so I configured them.

In the Tab "Web Services Field Output" I configured one output field (the name). You can add as many columns as you like. Virtual columns do not work here (That may be a bug).

In the "Web Service Access" Tab I added the Role that needs Access (GardenAdmin in my example - but you should use a separate role for a production system).

Use the Web Service with a request file

You enter the Search Key String of the Configuration we just created as the ServiceType in the xml request file. Then you add the needed parameter. The xml example that SoapUI created is useful to see all possible and needed parameters. To try out the request you can click the green arrow button in the Source window of SoapUI. You see the xml result at the left. There you can see a list of Business Partners or you get an error message that (hopefully) explains what you did wrong.

My first successful request is this file:

 <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:stage>
         </_0:ADLoginRequest>
       </_0:ModelCRUDRequest>
     </_0:queryData>
   </soapenv:Body>
 </soapenv:Envelope>

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>

The Login part of the Request

Your web service client must be able to login, so in the SOAP request, fill the ADLoginRequest part with the same credentials you fill when you log in manually.

In the example above I used Client 11 (GardenWorld), Role 102 (GardenAdmin), Org 11 (HQ) and Warehouse 103 (HQ). For a real-world usage of Web Services you should use a special role (not Admin) to specify which parts of iDempiere are available for web service access.

 <_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:stage>
 </_0:ADLoginRequest>

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)