Adempiere Web Services

From ADempiere ERP Wiki

Jump to: navigation, search

Contents

Repository

Currently the project is in the adempiere svn repository located at branches/3E_WebServices

The idea is to integrate this project in future to adempiere stable version.

Team

  • Carlos Ruiz - coordinator, developer, designer, tester
  • Developers, testers, designers, sponsors welcome

Acknowledgments

How to install and test

Currently this project is not integrated in stable.

In order to test it you must follow this steps:

  1. Run the scripts provided in 3E_WebServices/migration according to your database
    1. WS001_WebServices.sql - creates the tables and windows to define the web service security as shown in Adempiere Web Services Security
    2. WS002_WebServicesDefinition.sql - creates the definition of the currently supported web services and methods
    3. WS003_WebServicesConfigGardenWorldSample.sql - create role, user and two sample tests for testing web services with GardenWorld
    4. WS004_WebServicesFixDict.sql - fix a dictionary problem from WS001 script
  1. Download the latest release of ADInterface from sourceforge.net here
    1. Or follow the direct link: 3E_WebServices_20100713_360lts.tgz
  2. Go to your adempiere installation home, i.e. cd $ADEMPIERE_HOME
  3. Stop the app server (RUN_Server2Stop)
  4. Uncompress the downloaded file, i.e. tar xvzf DIR_DOWNLOAD/3E_WebServices_20100713_360lts.tgz
    1. Warning, this will overwrite build.xml and lib/adempiereAll.xml - be careful in case you have modified these files
  5. RUN_setup
  6. Start the app server (RUN_Server2)
  7. Test if the webservices are installed navigating to the address http://your_server:your_port/ADInterface/services/ADService?wsdl
    1. i.e. supposing you installed in localhost using port 80 as web: http://localhost:80/ADInterface/services/ADService?wsdl


NOTE: All test have been done in a patched 342s version. 20100713 version tested in a patched 360lts version.

How to test with Windows Mobile

Review this link Webservices_Windows_Mobile

Development Guide

You can find instructions about how to add datatypes and/or web services in the repository file Notes/HowToAddNewWebService.txt

Test Scripts

soapUI

Tested the model webservices using soapUI tool. Excellent tool - the tests are working ok.

You can find test project for soapui in svn repository AdempiereWebServices-soapui-project.xml

In order to use it you need to change the protocol, hostname and port according to what you want to test ( search the https://localhost:8443 string and replace it properly with your installation protocol://host:port )

Shell script testing

You can find some scripts to test (using wget) in the repository directory testScripts

Oracle pl/sql testing

Warning: obsolete test case, the message needs to be upgraded to the new web service definition

There is also a sample of a pl/sql function that calls modelSetDocAction in the repository file Notes/HowToCallWebServiceFromOraclePLSQL.txt

Eclipse testing

I tried testing with Eclipse Ganymede JEE version.

Running from Web perspective, you can try Run -> Launch the Web Services Explorer

The web services are properly discovered using the WSDL button and entering the URL of the server wsdl described above.

Unfortunately the web services can't be tested from eclipse. It seems eclipse is not supporting the rpc style of web services, it's sending the message formatted as document style.

Web Services

Model Oriented Web Services (ModelADService)

WSDL: ModelADService.wsdl

Model oriented web services have a different approach to run things on Adempiere. They need login data on each request, open a session, execute the operation and close the session. They are not intended to replicate the UI functionality, but to allow executing common operations in Adempiere.

All these web services need login data:

  • ADLoginRequest (user, pass, lang, ClientID, RoleID, OrgID, WarehouseID, stage) - note stage is not used here

All these web services receive a serviceType parameter. This is configured in the security layer explained in Adempiere Web Services Security. The parameters are checked (and modified if necessary) against the definition of the serviceType.

Configuration and Security

Model web services are highly generic - so they need an additional security layer in order to ensure the server security is not compromised.

If you want to learn more about how to configure web services and security in Adempiere dictionary please read here: Adempiere Web Services Security

setDocAction

This web service is intended to trigger a change in document action, i.e. complete a material receipt, prepare a purchase order, void an invoice, etc.

WARNING! - This web service complete documents not via workflow, so it jump over any approval step considered in document workflow. To complete documents using workflow it's better to use the runProcess web service.

Parameters:

  • serviceType
  • tableName
  • recordID
  • docAction

Returns:

  • StandardResponse (Error Message, IsError flag, RecordID)

Process:

  • Login and create session (it returns proper message if it can't login)
  • Get the record given the tableName and recordID (it must be a document table, it must have an associated Model class implementing DocAction interface)
  • Call the method corresponding with the newDocStatus (i.e. prepareIt, completeIt, voidIt, etc)
  • Returns any message, and flag the IsError flag accordingly

runProcess

This web service is intended to run a process, or raise a process that starts a document workflow.

Parameters:

  • serviceType
  • AD_Process_ID
  • AD_Menu_ID - not used
  • AD_Record_ID
  • DocAction (used if the process is a document workflow)
  • ParamValues (optional, set of DataRow)

Returns:

  • RunProcessResponse (Error, Summary, LogInfo, Data, IsError, IsReport, ReportFormat)

Process:

  • Login and create session (it returns proper message if it can't login)
  • If the process is a document workflow, set DocAction according to the parameter
  • Executes the process pointed by AD_Process_ID
  • Fill the return message and return accordingly to what the process must return

getList

This web service is intended to get data from a list (reference list or reference table)

Parameters:

  • serviceType
  • AD_Reference_ID
  • Filter - optional

Returns:

  • WindowTabData (DataSet -> DataRow array -> DataField array -> pair of Column and Value)

Process:

  • Login and create session (it returns proper message if it can't login)
  • Get the list table, columns, where and order by
  • Apply the filter
  • Fill the return message with values of the allowed output columns

createData

This web service is intended to create one record on a table. The table and allowed input columns must be configured in the serviceType.

Parameters:

  • serviceType
  • TableName
  • RecordID - not used here
  • Filter - not used here
  • Action - must be Create
  • DataRow (DataField array of Column+Value pairs)

Returns:

  • StandardResponse (Error Message, IsError flag, RecordID)

Process:

  • Login and create session (it returns proper message if it can't login)
  • Create a new record on the desired table
  • Set the columns
  • Invoke the adempiere persistence engine to save the row (this implies calling automatically before/after triggers and model validators)
  • If successful, fill the RecordID of the response
  • Returns any message, and flag the IsError flag accordingly

updateData

This web service is intended to modify one record on a table (accessed by ID). The table and allowed input columns must be configured in the serviceType.

Parameters:

  • serviceType
  • TableName
  • RecordID - required
  • Filter - not used here
  • Action - must be Update
  • DataRow (DataField array of Column+Value pairs)

Returns:

  • StandardResponse (Error Message, IsError flag, RecordID)

Process:

  • Login and create session (it returns proper message if it can't login)
  • Read the record from the desired table using the recordID
  • Set the columns
  • Invoke the adempiere persistence engine to save the row (this implies calling automatically before/after triggers and model validators)
  • If successful, fill the RecordID of the response
  • Returns any message, and flag the IsError flag accordingly

deleteData

This web service is intended to delete one record from a table. The table must be configured in the serviceType.

Parameters:

  • serviceType
  • TableName
  • RecordID - required
  • Filter - not used here
  • Action - must be Delete
  • DataRow - not used here

Returns:

  • StandardResponse (Error Message, IsError flag, RecordID)

Process:

  • Login and create session (it returns proper message if it can't login)
  • Read the record from the desired table using the recordID
  • Invoke the adempiere persistence engine to delete the row (this implies calling automatically before/after triggers and model validators)
  • Returns any message, and flag the IsError flag accordingly

readData

This web service is intended to return values from one record on a table (accessed by ID). The table and allowed output columns must be configured in the serviceType.

Parameters:

  • serviceType
  • TableName
  • RecordID - required
  • Filter - not used here
  • Action - must be Read
  • DataRow - not used here

Returns:

  • WindowTabData (DataSet -> DataRow array -> DataField array -> pair of Column and Value) - just one record

Process:

  • Login and create session (it returns proper message if it can't login)
  • Read the record from the desired table using the recordID
  • Fill the return message with values of the allowed output columns

queryData

This web service is intended to query records on a table (accessed by conditions on columns and filter). The table, allowed input columns (conditions) and allowed output columns must be configured in the serviceType.

Parameters:

  • serviceType
  • TableName
  • RecordID - not used here
  • Filter
  • Action - must be Read
  • DataRow - to define the conditions of columns

Returns:

  • WindowTabData (DataSet -> DataRow array -> DataField array -> pair of Column and Value) - zero, one or several records

Process:

  • Login and create session (it returns proper message if it can't login)
  • Query the records from the desired table using the conditions on columns and filter (and applying the access security defined for role)
  • Fill the return message with values of the allowed output columns

UI Oriented Web Services - ADClient.exe (ADService)

WSDL: ADService.wsdl

WARNING: These web services are very generic and still not configured a security layer, in the sample data and migration scripts these web services are closed, opening these web services can represent a security hole (i.e. a user could get the SuperUser password)

3E developed lots of UI oriented web services, and they're ready to use and test with their ADClient tool that you can download here ADClient_0.7.6.zip. In order to test, you will need to activate the web service ADService (not recommended in production).

According to the instructions on their page you must download ADClient package (2 mb), unzip it in choosen dir, edit ADClient.ini file and set up service host (or leave it unchanged for localhost) and run ADClient.exe.

These web services are oriented to UI, this is, they create a session and environment to work as if you were in Adempiere swing client. You can open windows, navigate data, change, remove, run processes, etc.

The UI oriented services already included are: login, isLoggedIn, getADMenu, saveLocation, setDocAction, getLookupData, updateDataRow, getDataRow, ignoreDataRow, addNewDataRow, getProcessParams, getLocation, runProcess, getLookupSearchData, getVersion, saveDataRow, deleteDataRow, getDocAction, getADWindow, refreshDataRow, getWindowTabData

Web Services eCommerce Integration

In order to allow integration with other eCommerce packages i.e. Online Store or POS, a common set of Web Service Type have been identified to handling the exchange of data between ADempiere and the external systems.

This document is currently in development...

Openbravo POS integration web services

In order to allow integration with Openbravo POS there is a Proof of Concept with the web services ExternalSales and WebService.

The Openbravo POS messaging is using RPC/Encoding, currently xfire doesn't support that, so for the testings I needed to modify some openbravo classes to read/write RPC/Literal. It's expected that xfire will support RPC/Encoding soon, meanwhile we can test with modified POS.

This is in alpha status - still not working.

Just developed and tested the authentication, and checking how to messages are transported. Currently the message receiving arrays of orders, bpartners, products, etc. Is not implemented.

RoadMap

  • Implement a webservice that can combine all of the previous within one single login and transaction (this would need to set values on context variables, to reuse in later messages)
  • Reuse login between different calls
  • Complete Openbravo POS integration
Personal tools