Web Services First Steps

I started to experiment with Web Services and iDempiere and I found no good introduction. So I want want to document which steps I did to get into it.

Preconditions

At first you have to be sure that the webservices plugin is installed and active. That should be the case in a standard iDempiere installation. The simplest test is to use http://localhost:8080/ADInterface/services and see if you get an answer. That should open a page that describes the two kinds of webservices and their methods.

Standard webservices describe themselves as a so-called wsdl file. You can see a link to the wsdl files at the right. For example http://localhost:8080/ADInterface/services/ModelADService?wsdl is the wsdl file for the Model Oriented Service Interface.

Create a request file with SoapUI

To start a web request I need a file that describes my request. For my first steps it was the easiest way to use SoapUI (http://www.soapui.org) to create that.

I pressed the "SOAP" button in the toolbar to create a new SOAP project. Then I set a name and gave the link to the wsdl file (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 yet an alternative to SoapUI to create the example files. If you need that 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)