Web Services First Steps

I started to experiment with Web Services and iDempiere but I found no good 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

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 (apologies for the quality, I have edited out the name of my server):

Standard SOAP web services are described by a WSDL file. You can see a link to the WSDL files on the right, for example the WSDL file for the Model Oriented Service Interface is:

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

Create a request file with SoapUI

To start a web request you need a file that describes the request. Download and use SoapUI to create it:

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 creates magically 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. If you need an alternative, you should be able to write one using [soap-ws]. If you understand how SOAP works it should be not so hard to just read the WSDL and create the xml manually.

Fill the Login part of the Request

At first your web service client should be able to login. For that you have to fill the ADLoginRequest part with the same credentials you fill when you log in manually. You can use this example as a reference. 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 better use a special role (not Admin). So you can exactly adjust which parts of iDempiere are available to the network 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>

Configure a Web Service in iDempiere

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 my 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>

Use the request file from the console

My next question was: How can I do that without using the SoapUI interface? That is easy to do. The SOAP Request is a simple HTTP POST request. I use wget to send it and save the result to an xml file:

 wget http://localhost:8080/ADInterface/services/ModelADService --post-file=testrequest.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

Now I am free to create the request file with whatever tool I want or use code in a language of my choice to handle the request and the result. That is not the scope of this article. 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)