Home > References

EBX.Platform Data Services

Concepts and architecture
Installation
WSDL Documents
SOAP Interactions
Operations on Master Data
Monitoring
Operations on Repository
Known limitations
- Date, time & dateTime format

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 record(s)
Count record(s)
Get changes between branches or versions

Other operations on the repository level are available:

Create a branch
Close a branch
Create a version
Close a version
Merge a branch
Validate a branch or a version
Validate an instance
Start a workflow process instance
End a workflow process instance

Installation

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

WSDL Documents

WSDL is obtained through the main page of the web application. You access this main page by 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 the XML Schema structure of the target adaptation instance in the target branch.

Then, the tables to be exposed have to be selected:

At last, the user selects the operations to expose on the tables:

After choosing a WSDL, a popup window will open, allowing to save the WSDL file onto your hard-drive.

Note: These WSDL files 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 into a registry such as UDDI is not handled 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 will use the following header field: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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

Tracking information

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

<SOAP-ENV:Header>

   <!-- security header may be there --> 

   <m:session xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

     <trackingInformation>String</trackingInformation> 

   </m:session>

</SOAP-ENV:Header>

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:

<soapenv:Fault>

  <faultcode>soapenv:java.lang.IllegalArgumentException</faultcode> 

  <faultstring/>

  <faultactor>admin</faultactor> 

  <detail>

  <m:StandardException xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

    <code>java.lang.IllegalArgumentException</code> 

    <label/>

    <description>java.lang.IllegalArgumentException: Parent home not found

    at com.orchestranetworks.XXX.YYY.ZZZ.AAA.BBB(AAAA.java:44)

    at com.orchestranetworks.XXX.YYY.ZZZ.CCC.DDD(CCC.java:40)

    ... 

    </description>

  </m:StandardException> 

  </detail>

</soapenv:Fault>

Operations on Master Data

Select, Delete, Count requests

<m:{select,count,delete}_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

   <branch>String</branch> 

   <version>String</version> 

   <instance>String</instance> 

   <predicate>String</predicate> 

</m:{select,count,delete}_{TableName}>

with:

Element	Description	Required
branch	The name of the branch to which the instance belongs.	True. Exclusive with version tag
version	The name of the branch to which the instance belongs.	True. Exclusive with branch tag
instance	The name of the adaptation which contains the table to query.	True
predicate	XPath predicate defines the records on which the request is applied. If empty, all records will be retrieved. Except for deletion, in which case this field is mandatory.	false (true for deletion)
occultIfInherit	Only for deletion. Occults the record if it is in inherit mode. Default value is false.	false
includesTechnicalData	Only for select. The response will contain technical data if true. See also the optimistic locking section. Each returned record will contain additional attributes for this technical information, for instance: `...<table ebxd:lastTime="2010-06-28T10:10:31.046" ebxd:lastUser="Uadmin" ebxd:uuid="9E7D0530-828C-11DF-B733-0012D01B6E76">...` .	false
checkNotChangedSinceLastTime	Only for deletion. Timestamp to be used to be sure the record has not been modified since last read. See also the optimistic locking section.	false

Update, Insert requests

<m:{update,insert}_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

   <branch>String</branch> 

   <version>String</version> 

   <instance>String</instance> 

   <updateOrInsert>true</updateOrInsert> 

   <data>

     <XX>

      <TableName>

       <a>String</a> 

       <b>String</b> 

       <c>String</c> 

       <d>String</d> 

       ... 

      </TableName>

     </XX>

   </data>

</m:{update,insert}_{TableName}>

with:

Element	Description	Required
updateOrInsert	Only available for `update` operation. If true and if the record does not exist, it creates the record.	false
data	Contains the records to be inserted or updated. The whole operation is equivalent to an XML import. The concrete operations to be performed regarding the data content are specified in the section Import Behaviour .	true

See also the optimistic locking section.

Get changes request

<m:getChanges_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

   <branch>String</branch> 

   <version>String</version> 

   <instance>String</instance> 

   <compareWithBranch>String</compareWithBranch> 

   <compareWithVersion>String</compareWithVersion> 

</m:getChanges_{TableName}>

with:

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 the current home is a branch, the comparison is made with its initial version (this corresponds to all changes made in the branch);
if the 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

<{delete,update}_{TableName}Response> 

   <status>00</status> 

</{delete,update}_{TableName}Response>

with:

status:

00 indicates that the operation has been executed successfully.

Insert response

<m:insert_{TableName}Response xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

   <status>00</status> 

   <inserted>

    <predicate>col1=192</predicate> 

   </inserted>

</m:insert_{TableName}Response>

with:

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

Select response

<select_{TableName}Response> 

 <XX> 

   <TableName>

    <a>key1</a> 

    <b>valueb</b> 

        <c>1</c> 

        <d>1</d> 

   </TableName>

  </XX>

</select_{TableName}Response>

See also the optimistic locking section.

Count response

<count_{TableName}Response> 

  <count>7</count> 

</count_{TableName}Response>

Get changes response

<m:getChanges_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

   <inserted>

      <XX>

         <YY> 

            <TableName> 

               <string>String</string>

               <boolean>true</boolean>

               <dateTime>2001-12-17T09:30:47.000</dateTime> 

               ...

            </TableName> 

            <TableName> 

               <string>Sztrizaang</string>

               <boolean>true</boolean>

               <dateTime>2001-12-17T09:30:47.000</dateTime> 

               ...

            </TableName> 

         </YY> 

      </XX>

   </inserted>

   <updated>

      <changes>

         <change predicate="string='s'"> 

            <path>/integer</path>

            <path>/date</path>

         </change> 

         <change predicate="string='Sztrizng'"> 

            <path>/date</path>

            <path>/name</path>

         </change> 

      </changes>

      <data>

         <XX> 

            <YY> 

               <TableName> 

                  <string>s</string>

                  <boolean>true</boolean>

                  <dateTime>2001-12-17T09:30:47.000</dateTime> 

                  <time>20:01:01.000</time>

                  <date>1967-08-13</date>

                  <name>Name</name>

                  <integer>0</integer>

                  ...

               </TableName> 

               <TableName> 

                  <string>Sztrizng</string>

                  <boolean>true</boolean>

                  <dateTime>2001-12-17T09:30:47.000</dateTime> 

                  <time>20:01:01.000</time>

                  <date>1967-08-13</date>

                  <name>Name</name>

                  <integer>0</integer>

                  ...

               </TableName> 

            </YY> 

         </XX> 

      </data>

   </updated>

   <deleted>

      <predicate>string='a'</predicate> 

      <predicate>string='b'</predicate> 

   </deleted>

</m:getChanges_{TableName}>

Optimistic locking

To prevent an update or a delete operation on a previously read record that may meanwhile have been changed, an optimistic locking mechanism is provided.

In the select request, it is possible to ask for technical information by adding the element includesTechnicalData:

<m:select_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

   <branch>String</branch> 

   <version>String</version> 

   <instance>String</instance> 

   <predicate>String</predicate> 

   <includesTechnicalData>true</includesTechnicalData> 
	
</m:select_{TableName}>

The value of the lastTime attribute can then be used in the update request: the update will be cancelled if the record has been changed since the specified time. The attribute lastTime has to be added on the record we want to update.

<m:update_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

   <branch>String</branch> 

   <version>String</version> 

   <instance>String</instance> 

   <updateOrInsert>true</updateOrInsert> 

   <data>

     <XX>

      <TableName ebxd:lastTime="2010-06-28T10:10:31.046">

       <a>String</a> 

       <b>String</b> 

       <c>String</c> 

       <d>String</d> 

       ... 

      </TableName>

     </XX>

   </data>

</m:update_{TableName}>

The value of the lastTime attribute can also be used to prevent deletion on a modified record:

<m:delete_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

   <branch>String</branch> 

   <version>String</version> 

   <instance>String</instance> 

   <predicate>String</predicate> 

   <checkNotChangedSinceLastTime>2010-06-28T10:10:31.046</checkNotChangedSinceLastTime> 
	
</m:delete_{TableName}>

The element checkNotChangedSinceLastTime can be used for one and only one record by request. It means that if the predicate returns more than one record, the request will fail if the element checkNotChangedSinceLastTime is set.

Monitoring

The Data Services events can be monitored through the log category ebx.dataServices, to be declared in ebx.properties such as: ebx.log4j.category.log.dataServices= INFO, ebxFile:dataservices

Operations on Repository

Validate branch operation:

<m:validate xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

  <branch>String</branch> 

</m:validate>

Validate an instance operation:

<m:validateInstance xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

  <branch>String</branch> 

  <version>String</version> 

  <instance>String</instance> 

  <ensureActivation>true</ensureActivation> 

</m:validateInstance>

Create branch operation:

<m:createBranch xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

   <branch>String</branch> 

   <childBranchName>String</childBranchName> 

</m:createBranch>

Create version operation:

<m:createVersion xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

   <branch>String</branch> 

   <versionName>String</versionName> 

</m:createVersion>

Merge branch operation:

<m:mergeBranch xmlns:m="urn:ebx-schemas:dataservices_1.0"> 

   <branch>String</branch> 

</m:mergeBranch>

With:

Element	Description	Required
branch	Target branch on which the operation is applied. When empty, the reference branch is chosen.	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

Copyright © Orchestra Networks 2000-2010. All rights reserved.
Trademarks and brand names referred to in this web site relating to organizations
other than Orchestra Networks are the property of those organizations
and Orchestra Networks makes no claims to such property.