Web services

From iDempiere en
Jump to: navigation, search

This page describes the model oriented Web Service interface and gives a reference of the parameters of all the methods you can use.

See Web Services First Steps to get a beginners introduction.

There is another interface called the Composite Service that performs several requests in one transaction (see NF1.0 Web Services Improvements for more information).

SOAP Web Services

URL to the services

The SOAP Web Services plug-in is included in the base installation of iDempiere. The URL to the available SOAP Web Services on your installation can be found under:

 https://your_host:ssl_port/ADInterface/services

For example, the URL for the services exposed in a local installation of iDempiere will be:

 https://localhost:8443/ADInterface/services

Note that this example uses HTTPS for security (hence the use of the default SSL port 8443), but you can also use the less-secure HTTP port 8080 for testing purposes.

Model Oriented Web Services (ModelADService)

Login parameters

Model oriented web services have a different approach on iDempiere: they need login data for 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 iDempiere.

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

The guide to configure web services and security in Adempiere dictionary is here: Web Services Security

Available SOAP Web Services

setDocAction

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

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

Warning: the setDocAction web service does not complete documents via workflow, so it jumps over any approval steps defined in the document workflow. It's better to use the runProcess web service to complete documents using workflow.



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