ADempiere 3.6: Building and Configuring Web Services

Exclusive offer: get 50% off this eBook here
ADempiere 3.6 Cookbook

ADempiere 3.6 Cookbook — Save 50%

Over 100 recipes for extending and customizing ADempiere beyond its standard capabilities

£22.99    £11.50
by Ajit Kumar | March 2011 | Open Source

ADempiere is one the of the leading open source ERP products in today''s business market. ADempiere offers everything you need from efficient data management, streamlining business processes, reduction in costs, and minimal complexity to make your business successful.

In this article by Ajit Kumar, author of ADempiere 3.6 Cookbook, we will cover:

  • Building Web services support
  • Configuring Web services
  • Configuring a Web service to create a record
  • Configuring a Web service to read a record

 

ADempiere 3.6 Cookbook

ADempiere 3.6 Cookbook

Over 100 recipes for extending and customizing ADempiere beyond its standard capabilities

        Read more about this book      

(For more resources on this subject, see here.)

Introduction

ADempiere has various modules and processes to provide the ERP, SCM, and CRM capability to the user. However, as ADempiere is still evolving, so are our business processes in the constant quest for efficiency and effectiveness. With this in perspective, there may be instances where an enterprise would have multiple applications, including ADempiere, sitting side-by-side and providing some specialized services to the user or complementing ADempiere's functionality. This, in most of the instances, calls for an integration of different systems. Moreover, if the enterprise uses ADempiere as its centralized system, then all other applications may have to integrate themselves with ADempiere so that they can read the common data and make their data available in it. For example, a shopping cart application needs product information. To achieve this, ADempiere provides the Web services interface. There are four types of Web service interfaces provided:

  • UI oriented Web services: Provides APIs based on ADempiere's Window, Tab, and Field constructs
  • Model oriented Web services: This provides APIs based on ADempiere's data model
  • eCommerce Integration Web services: Provides integration of external eCommerce packages, such as Online Store or POS
  • Openbravo POS integration Web services: Custom APIs provided for integration with Openbravo

Out of the listed types, model-oriented Web services will be the focus of this article. UI Web services are special services and unless you understand the ADempiere's Application Framework, it would be very difficult for any third party integrator to understand them and use them. Besides, the security layer has not been implemented yet in it, so it is not recommended for production use. Openbravo services are still at the alpha stage.

Model oriented services are built on top of ADempiere's data model and provides the following generic APIs to execute any ADempiere Web service:

  • createData: For creating one record on a table
  • readData: To return values from one record on a table
  • queryData: To query records on a table
  • getList: To get data from a list (reference list or reference table)
  • updateData: To modify one record on a table
  • deleteData: To delete one record from a table
  • runProcess: To run a process or raise a process that starts a document workflow
  • setDocAction: To trigger a change in document action, that is, complete a material receipt

In this article, we will look into the model oriented Web services and understand what it takes to consume them. Since these are generic APIs, it requires us to configure the security and our specific Web services detail in ADempiere, which will be the first thing/process we will cover to ensure our installation is built and configured for Web services.

For all the Web services execution, we will be using the soapUI (http://www.eviware.com) client. So, kindly install it on your system and keep it ready before we start. soapUI is a Web services testing tool.

Also, the APIs require various details to be specified (for example, login details, warehouse, language, and so on). With reference to the WSDL of the model-oriented Web services, keep the following detail handy, as it will be useful during the execution of the Web services.

Building Web services support

Support for Web services is not in-built into ADempiere and is also not part of the trunk (main branch) in the SVN repository. The Web services support was sponsored and the seed code was provided by 3E and the complete code resides, at the time of writing this article, in the branches\3E_WebServices folder of the ADempiere SVN repository. This recipe takes us through the steps required to build and deploy the Web services so that they can be used in conjunction with our ADempiere application.

Getting ready

To execute the steps mentioned in this recipe, we need to ensure that we have got the working and deployable version of the adempiere_360 project in Eclipse.

How to do it...

  1. Check out the https://adempiere.svn.sourceforge.net/svnroot/ adempiere/branches/3E_WebServices SVN URL in <ADEMPIERE_SVN>\ branches.
  2. Launch Eclipse.
  3. Import the newly checked out 3E_WebServices project in Eclipse.
  4. Right-click on the project and go to Properties. This will pop-up the Properties window.
  5. Click on Java Build Path. You will see the build-related details on the right-hand side.
  6. Click on the Projects tab and remove all the existing entries from the Required projects on the build path list.
  7. Add the adempiere_360 project to the Required projects on the build path and click on the OKbutton.
  8. Edit the build.xml file and make the following changes:
    • Set the Adempiere.dir property value to ${basedir}/../../tags/ adempiere360lts/lib to point it to our adempiere_360 project folder
    • Add the following to the war target before the WAR file is being created (war element):

    <copy todir="${WEBINF.dir}/lib">
    <fileset dir="${Adempiere.dir}">
    <include name="*.jar"/>
    </fileset>
    </copy>
    <copy todir="${WEBINF.dir}/classes">
    <fileset dir="${Adempiere.dir}/../bin">
    <include name="**"/>
    </fileset>
    </copy>

  9. Right-click on build.xml Run As | Ant Build| to build and create the WAR file. On a successful build, it will create the ADInterface-1.0.war file in the 3E_WebServices\dist folder. You will have to refresh your project to see this in Eclipse.
  10. Copy the ADInterface-1.0.war file to the <JBOSS_HOME>\server\ adempiere360lts\deploy folder.
  11. Go to Eclipse and go to Server view.
  12. Start the JBoss server instance where we had deployed the adempiere_360 project.
  13. Access the http://127.0.0.1:9080/ADInterface-1.0/services/ ADService?wsdl URL in the browser. This will download the UI Web services WSDL file and display it, which means the Web services have been deployed successfully.
  14. Access the http://127.0.0.1:9080/ADInterface-1.0/services/ ModelADService?wsdl URL in the browser. This will download the Model Web services WSDL file and display it, which means the Web services have been deployed.
  15. Open the URLs mentioned in step 13 and 14 in the soapUI client.
  16. Run the getVersion Web service from the UI Web services list. Upon success, you shall get the version number returned from the service, for example, 0.7.0. With this, we have verified that the installation is working fine.

Configuring Web services

Now that we can build, deploy, and test the sample login service to verify the deployment, we can configure our ADempiere instance so that we can start configuring our new Web services and run them. Here we will see what we must do in order to configure our ADempiere instance for Web services support.

Getting ready

Make sure that you have followed the steps mentioned in the Building Web services support recipe to build and deploy the Web services.

How to do it...

  1. Log in to the adempiere360 database using the adempiere/adempiere credential.
  2. Import the following SQL files from the 3E_WebServices\migration folder:
    • WS001_WebServices.sql: This creates the tables and windows to define the Web service security, as shown in ADempiere Web Services Security
    • WS002_WebServicesDefinition.sql: This creates the definition of the currently supported Web services and methods
    • WS003_WebServicesConfigGardenWorldSample.sql: This creates the role, user, and two sample tests for testing Web services with GardenWorld
    • WS004_WebServicesFixDict.sql: This is for fixing a dictionary problem from the WS001_WebServices.sql script
  3. Launch ADempiere from the adempiere_360 project and log in as SuperUser/ System with the System Administrator role.
  4. Go to the Window, Tab, and the Field window and lookup the records by entering %Web Service as the name on the Lookup Record window. You shall see the following entries:
    • Web Service Definition
    • Web Service Security

  5. Verify the Access of both the windows. Note that GardenUser has access to the Web services. We'll use it for all our Web services-related activities.

  6. Go to the Table and Column window and lookup the records by entering %Web service as the Name on the Lookup Record window. You shall see the Web services-related tables. Verify that the Data Access Level is set to Client+Organization for all the table entries. Based on this setting, the data access security will be applied.

  7. Log out and log in as GardenUser/GardenUser with the GardenWorld User role.
  8. Lookup for Web service and make sure you have the following menus existing in your Menu tree:
    • Web Service Security
    • Web Services

With this, we have verified the Web services configuration needed to configure and consume new Web services, which we will see in the subsequent recipes.

ADempiere 3.6 Cookbook Over 100 recipes for extending and customizing ADempiere beyond its standard capabilities
Published: March 2011
eBook Price: £22.99
Book Price: £36.99
See more
Select your format and quantity:
        Read more about this book      

(For more resources on this subject, see here.)

Configuring a Web service to create a record

This recipe describes the steps required to configure a Web service to create a new record in a table. It will be using the generic API, createData. We have taken an example where we would like to create a business partner in the system using the Web service.

Getting ready

Make sure that you have completed the steps mentioned in recipes 1 and 2 of this article.

How to do it...

  1. Log in to ADempiere using GardenUser/GardenUser with the GardenWorld User role.
  2. Go to the Web Service Security window.
  3. Click on the New Record and enter the following on the Web Service Type tab, as shown in the next screenshot:
    • Search Key: CreateBPartner (choose your text)
    • Name: Create BPartner (choose your text)
    • Web Service: Model Oriented Web Services
    • Web Service Method: Create Data_Model Oriented Web Services
    • Table: C_BPartner_Business Partner
    • Description: <your description of service>
    • Comment/Help: <your text>

  4. Go to Web Service Parameter and create the following parameters, as shown in the next screenshot:
    • TableName: Set this to C_BPartner
    • RecordID: The value for this will be passed from the Web service request
    • Action: Set this to Create

  5. Go to the Web Service Field Input tab and enter the following Columns, as shown in the next screenshot:
    • Value_Search Key
    • Name_Name
    • TaxID_Tax ID
    • IsVendor_Vendor
    • IsCustomer_Customer
    • IsTaxExempt_Tax exempt
    • Name2_Name 2
    • C_BP_Group_ID_Business Partner Group

  6. Go to the soapUI client and run the following SOAP request:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/
    envelope/" xmlns:adin="http://3e.pl/ADInterface">
    <soapenv:Header/>
    <soapenv:Body>
    <adin:createData>
    <adin:ModelCRUDRequest>
    <adin:ModelCRUD>
    <adin:serviceType>CreateBPartner</adin:serviceType>
    <adin:TableName>C_BPartner</adin:TableName>
    <adin:RecordID>0</adin:RecordID>
    <adin:Action>Create</adin:Action>
    <!--Optional:-->
    <adin:DataRow>
    <!--Zero or more repetitions:-->
    <adin:field column="Value">
    <adin:val>Ajit</adin:val>
    </adin:field>
    <adin:field column="Name">
    <adin:val>Ajit Kumar</adin:val>
    </adin:field>
    <adin:field column="TaxID">
    <adin:val></adin:val>
    </adin:field>
    <adin:field column="IsVendor">
    <adin:val>N</adin:val>
    </adin:field>
    <adin:field column="IsCustomer">
    <adin:val>N</adin:val>
    </adin:field>
    <adin:field column="IsTaxExempt">
    <adin:val>N</adin:val>
    </adin:field>
    <adin:field column="Name2">
    <adin:val>Walking Tree</adin:val>
    </adin:field>
    <adin:field column="C_BP_Group_ID">
    <adin:val>105</adin:val>
    </adin:field>
    </adin:DataRow>
    </adin:ModelCRUD>
    <adin:ADLoginRequest>
    <adin:user>GardenUser</adin:user>
    <adin:pass>GardenUser</adin:pass>
    <adin:lang>192</adin:lang>
    <adin:ClientID>11</adin:ClientID>
    <adin:RoleID>103</adin:RoleID>
    <adin:OrgID>11</adin:OrgID>
    <adin:WarehouseID>103</adin:WarehouseID>
    <adin:stage>0</adin:stage>
    </adin:ADLoginRequest>
    </adin:ModelCRUDRequest>
    </adin:createData>
    </soapenv:Body>
    </soapenv:Envelope>

    The following is the response you shall receive indicating that the business partner has been created in the system:

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/
    envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Body>
    <ns1:createDataResponse xmlns:ns1="http://3e.pl/
    ADInterface">
    <StandardResponse RecordID="1000002" xmlns="http://3e.pl/
    ADInterface"/>
    </ns1:createDataResponse>
    </soap:Body>
    </soap:Envelope>

  7. Go to the Business Partner window in ADempiere and verify that the details of the newly created business partner appear in it.

Configuring a Web service to read a record

Now let us look at how to configure a Web service to read the newly created business partner using the generic API—readData.

How to do it...

  1. Log in to ADempiere using GardenUser/GardenUser with the GardenWorld User role.
  2. Go to the Web Service Security window.
  3. Click on the New Record and enter the following, as shown in the next screenshot:
    • Search Key: ReadBPartner (choose your text)
    • Name: Read BPartner (choose your text)
    • Web Service: Model Oriented Web Services
    • Web Service Method: Read Data_Model Oriented Web Services
    • Table: C_BPartner_Business Partner
    • Description: <your description of service>
    • Comment/Help: <your text>

  4. Go to the Web Service Parameter tab and create the following parameters, as shown in the next screenshot:
    • TableName: Set this to C_BPartner
    • RecordID: The value for this will be passed from the Web service request. You may get the RecordID from the response of the CreateData service response, as shown in the previous recipe
    • Action: Set this to Read

  5. Go to the Web Service Field Output tab and create the following parameters as shown in the following screenshot:
    • Name_Name
    • Name2_Name 2

  6. Go to the soapUI client and run the following SOAP request:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/
    envelope/" xmlns:adin="http://3e.pl/ADInterface">

    <soapenv:Header/>

    <soapenv:Body>

    <adin:readData>

    <adin:ModelCRUDRequest>

    <adin:ModelCRUD>

    <adin:serviceType>ReadBPartner</adin:serviceType>
    <adin:TableName>C_BPartner</adin:TableName>
    <adin:RecordID>1000002</adin:RecordID>
    <adin:Action>Read</adin:Action>
    </adin:ModelCRUD>
    <adin:ADLoginRequest>
    <adin:user>GardenUser</adin:user>
    <adin:pass>GardenUser</adin:pass>
    <adin:lang>192</adin:lang>
    <adin:ClientID>11</adin:ClientID>
    <adin:RoleID>103</adin:RoleID>
    <adin:OrgID>11</adin:OrgID>
    <adin:WarehouseID>103</adin:WarehouseID>
    <adin:stage>0</adin:stage>
    </adin:ADLoginRequest>
    </adin:ModelCRUDRequest>
    </adin:readData>
    </soapenv:Body>
    </soapenv:Envelope>

    In the preceding request, 1000002 is the RecordID returned as part of the CreateBPartner service calls.
    The following shall be the response showing the record detail:

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/
    envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Body>
    <ns1:readDataResponse xmlns:ns1="http://3e.pl/ADInterface">
    <WindowTabData NumRows="1" TotalRows="1" StartRow="1"
    xmlns="http://3e.pl/ADInterface">
    <DataSet>
    <DataRow>
    <field column="Name">
    <val>Ajit Kumar</val>
    </field>
    <field column="Name2">
    <val>Walking Tree</val>
    </field>
    </DataRow>
    </DataSet>
    <RowCount>1</RowCount>
    <Success>true</Success>
    </WindowTabData>
    </ns1:readDataResponse>
    </soap:Body>
    </soap:Envelope>

Summary

In this article we took a look at building web services support and configuring web services. We also took a look at configuring a web service to create and read a record.


Further resources on this subject:


ADempiere 3.6 Cookbook Over 100 recipes for extending and customizing ADempiere beyond its standard capabilities
Published: March 2011
eBook Price: £22.99
Book Price: £36.99
See more
Select your format and quantity:

About the Author :


Ajit Kumar

Ajit Kumar started his IT career with Honeywell, Bangalore in the field of embedded systems and moved on to enterprise business applications (such as ERP) in his 13 years' career. From day one, he has been a staunch supporter and promoter of open source and believes strongly that open source is the way for a liberal, diversified, and democratic setup, such as India. He dreams, and continuously strives to ensure, that architecture, frameworks, and tools must facilitate software development at the speed of thought.

Ajit holds a Bachelor's degree in Computer Science and Engineering from the Bihar Institute of Technology, Sindri. He co-founded Walking Tree, which is based out of Hyderabad, India where he plays the role of CTO and works on fulfilling his vision.

Prior to writing this book, he worked on the following titles by Packt Publishing:

  • ADempiere 3.6 Cookbook
  • Sencha Touch Cookbook
  • Sencha MVC Architecture

Books From Packt

ADempiere 3.4 ERP Solutions
ADempiere 3.4 ERP Solutions

JSF 2.0 Cookbook
JSF 2.0 Cookbook

GlassFish Administration
GlassFish Administration

GlassFish Security
GlassFish Security

Java EE 6 with GlassFish 3 Application Server
Java EE 6 with GlassFish 3 Application Server

JBoss AS 5 Performance Tuning
JBoss AS 5 Performance Tuning

Learning Ext JS 3.2
Learning Ext JS 3.2

Yahoo! User Interface Library 2.x Cookbook
Yahoo! User Interface Library 2.x Cookbook

Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software