Home > References

EBX.Platform Data Services

 

Concepts and architecture

The Data Services module allows any external software to interact with Master Data by using the Web Services standard WSDL (Web Services Description Language). This module generates WSDL dynamically from the XML Schema that describes the structure of the Master Data. Then, through generated WSDL, the Web Service consumer is able to:

• Select record(s)
• Insert record(s)
• Update record(s)
• Delete a record
• Count record(s)
• Get changes between branches or versions [Beta Version subject to some evolution]

Other operations on the repository level are available:

• Create a branch
• Create a version
• Merge a branch
• Validate a branch or a version

 

Installation

Data Services are enabled by deploying the web application ebx-dataservices like other EBX.Platform web applications.

 

WSDL Documents

WSDL is got through the main page of the web application. You access to this main page with the URL:

http://ebx-server-hostname/ebx-dataservices/

Two kinds of WSDL are available:

• WSDL to handle the repository.
  
  
  
• WSDL to handle Master Data.
  
  
  
  
  

  It is mandatory to define the branch and the adaptation instance from which the WSDL has to be generated.
  The structure of messages in WSDL will match to the XML Schema structure of the target adaptation instance in the target branch.
  

After choosing a WSDL, a popup window will be opened for saving it on your hard-drive.

 

Note: These WSDL are not stored so as to be always accurate even if the XML Schema of the adaptation changes. It is up to the consumers to store those WSDL. The publication in a registry such as UDDI is not done by the module either.

 

SOAP Interactions

 

Messages encoding

All input messages have to be in UTF-8 exclusively. All output messages are in UTF-8.

 

Web Service Security

Authentication is mandatory. Three modes are available:

• A simple authentication based on the specification Web Services Security UsernameToken Profile 1.0.
  Only the mode PasswordText is supported. This is done with the following SOAP header defined in the WSDL:
  
  <SOAP-ENV:Header>
  <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext">
      <wsse:UsernameToken>
        <wsse:Username>user</wsse:Username>
        <wsse:Password  Type="wsse:PasswordText">password</wsse:Password>
      </wsse:UsernameToken>
  </wsse:Security>
  </SOAP-ENV:Header>
• A specific authentication based on HTTP Request and the call to method Directory.authenticateUserFromHttpRequest. This requires to override the implementation of this method (for example, it can extract a password-digest or a ticket from HTTP request).
• The standard HTTP Basic Authentication base 64 encoded through the HTTP-Header "Authorization" as described in RFC 2324.
  If the user agent wishes to send the userid "Aladdin" and password "open sesame", it would use the following header field: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

The authentication process is as follows: Web Service connector tries first to authenticate by using HTTP Request, then the HTTP Header "Authorization", and then by looking for a WSSE header.

 

Tracking information

 

Depending on the operations, it is possible to specifies an optional SOAP Header such as:

For more information, see: Session.getTrackingInfo().

 

Exceptions handling

Exceptions are rethrown to the consumer through the soap:fault element and within a standard exception such as:

 

Operations on Master Data

 

Select, Delete, Count requests

with:

Element	Description	Required
branch	Name of the branch to whom belongs the instance.	True. Exclusive with version tag
version	Name of the branch to whom belongs the instance.	True. Exclusive with branch tag
instance	Name of the adaptation in which the table to query is.	True
predicate	XPath predicate defines the records on which the request is applied. If empty all records will be taken. Except for deletion in which case it is mandatory.	false (true for deletion)
occultIfInherit	Only for deletion. Occults record if it is in inherit mode. Default value is false.	false

 

Update, Insert requests

with elements above and:

Element	Description	Required
updateOrInsert	Only for updates, if true and if the record does not exist, it creates the record.	false
data	Contains the record to update or insert. In the previous sample, it will insert a record into table TableName at path XX.	true

The following table summarizes the behavior of insert and update operations when an element of a record is not present in the SOAP request.

Mode	Element	Behavior
Insert	Not present	Value not set. If element corresponds to a terminal node it inherits from parent adaptation or default value defined in schema. If element is under terminal and the container is a Java Bean it will have the default Java Bean value.
Insert	Present but empty: <element />	Value set to null.
Update	Not present	Value not changed if element is a terminal node. If element is under a terminal element, the value is set to null.
Update	Present but empty: <element />	Value set to null.

 

Get changes request [Beta Version subject to some evolution]

with elements above and:

Element	Description	Required
compareWithBranch	The branch to compare with.	false
compareWithVersion	The version to compare with. Must be exclusive with compareWithBranch.	false

Note : if neither compareWithBranch nor compareWithVersion are present, the comparison will be made with its parent:

• if current home is a branch, the comparison is made with its initial version (this corresponds to all changes made in the branch);
• if current home is a version, the comparison is made with its parent branch (this corresponds to all changes made in the parent branch since the current version has been created);
• this returns an exception if current home is 'Reference' branch.

 

Delete, Update responses

with:

status:

00 indicates that the operation has been executed successfully.

Insert response

with:

status:	00 indicates that the operation has been executed successfully.
predicate:	Predicate matching the primary key of the record inserted. When several records are inserted, the predicates follow the declaration's order of the records in the input message.

 

Select response

 

Count response

 

Get changes response [Beta Version subject to some evolution]

 

Operations on Repository

Validate branch operation:

Validate an instance operation :

Create branch operation:

Create version operation:

Merge branch operation:

With:

Element	Description	Required
branch	Target branch on which the operation is applied. When empty, reference branch is taken.	True
versionName	Version name to create. If empty it will be filled on server-side.	False
childBranchName	Branch child name to create. If empty it will be filled on server-side.	False
ensureActivation	Defines if validation must also check that this instance is activated.	True

Known limitations

 

Date, time & dateTime format

Supported formats are:

Type	Format	Example
xs:date	yyyy-MM-dd	2007-12-31
xs:time	HH:mm:ss or HH:mm:ss.SSS	11:55:00
xs:dateTime	yyyy-MM-ddTHH:mm:ss or yyyy-MM-ddTHH:mm:ss.SSS	2007-12-31T11:55:00

 

Home > References