EBX5

Documentation > Reference Manual > Integration > Data services

Navigation modeDocumentation > Reference Manual > Integration > Data services

Introduction

Section contents

Overview of data services
Interactions
Data services security
SOAP and RESTful comparative
Limitations
- Date, time & dateTime format
- SOAP naming convention

Overview of data services

Data services allow external systems to interact with the data governed in the EBX5 repository using the SOAP/Web Services Description Language (WSDL) standards or using RESTful.

In order to invoke SOAP operations, for an integration use case, a WSDL must be generated from a data model. To invoke RESTful operations, for integration, mobile and web interface use cases, it is not mandatory to generate an interface, the request response is self-descriptive, the syntax is described in the chapter RESTful operations. It will be possible to perform operations such as:

Selecting, inserting, updating, deleting, or counting records
Selecting or counting history records
Selecting dataset values
Getting the differences on a table between dataspaces or snapshots, or between two datasets based on the same data model
Getting the credentials of records

Other generic WSDLs can be generated and allow performing operations such as:

Creating, merging, or closing a dataspace
Creating or closing a snapshot
Validating a dataset, dataspace, or a snapshot
Starting, resuming or ending a data workflow

Note

See SOAP and RESTful comparative.

Interactions

Input and output message encoding

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

Tracking information

Depending on the data services operation being called, it may be possible to specify session tracking information.

Example for a SOAP operation, the request header contains:

<SOAP-ENV:Header> 
	<!-- optional security header here --> 
	<m:session xmlns:m="urn:ebx-schemas:dataservices_1.0"> 
		<trackingInformation>String</trackingInformation> 
	</m:session> 
</SOAP-ENV:Header>

Example for a RESTful operation, the JSON request contains:

{
	"procedureContext": // JSON Object (optional)
	{
  		"trackingInformation": "String" // JSON String (optional)
	}, ...
}

Session parameters

Depending on the data services operation being called, it is possible to specify session input parameters. They are defined in the request body.

Example for a SOAP operation, the optional request header contains:

<SOAP-ENV:Header>
	<!-- optional security header here -->
	<m:session xmlns:m="urn:ebx-schemas:dataservices_1.0">
		<!-- optional trackingInformation header here --> 
		<inputParameters>
			<parameter>
				<name>String</name>
				<value>String</value>
			</parameter>
			<!-- for some other parameters, copy complex
			     element 'parameter' -->
		</inputParameters>
	</m:session>
</SOAP-ENV:Header>

Example for a RESTful operation, the JSON request contains:

{
	"procedureContext": // JSON Object (optional)
	{
  		"trackingInformation": "String", // JSON String (optional)
  		"inputParameters": // JSON Array (optional)
  		[
  			// JSON Object for each parameter
  			{
  				"name" : "String" // JSON String (required)
  				"value" : "String" // JSON String (optional)
  			},
  			...
  		]
	}, ...
}

Exception handling

In case of unexpected server error upon execution of:

A SOAP operation, a SOAP exception response is returned to the caller via the soap:Fault element. For example:

<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.XX.YY.ZZ.AA.BB(AA.java:44) at
				com.orchestranetworks.XX.YY.ZZ.CC.DD(CC.java:40) ...
			</description>
		</m:StandardException>
	</detail>
</soapenv:Fault>

A RESTful operation, a JSON exception response is returned to the caller. For example:

{
  "code": 999, // JSON Number, HTTP status code
  "errors": [
  	{
  		"severity": "...",     // JSON String, severity (optional)
  		"rowIndex": 999,       // JSON Number, request row index (optional)
  		"message": "...",      // JSON String, message
  		"details": "...",      // JSON String, URL (optional)
  		"pathInRecord": "...", // JSON String, Path in record (optional)
  		"pathInDataset": "..." // JSON String, Path in dataset (optional)
  	}
  ]
}

The response contains an HTTP status code and a table of errors. The severity of each error is specified by a character, with one of the possible values (F: fatal, E: error, W: warning, I: information).

Data services security

Authentication

Authentication is mandatory. Several authentication methods are available and described below. The descriptions are ordered by priority (EBX5 applies the highest priority authentication method first).

'Token Authentication Scheme' method is based on the HTTP-Header Authorization, as described in RFC 2324.
Tracking information and Session parameters must be defined during the token creation, otherwise a 400 (Bad request) error is returned.
For more information on this authentication scheme, see Token authentication operations.

'Basic Authentication Scheme' method is based on the HTTP-Header Authorization in base 64 encoding, as described in RFC 2324.

If the user agent wishes to send the userid "Alibaba" and password "open sesame",
it will use the following header field:
> Authorization: Basic QWxpYmFiYTpvcGVuIHNlc2FtZQ==

'Standard Authentication Scheme' is based on the HTTP Request. User and password are extracted from request parameters. For more information on request parameters, see Request parameters section.

The 'SOAP Security Header Authentication Scheme' method is based on the Web Services Security UsernameToken Profile 1.0 specification.

By default, the type 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>String</wsse:Username>
			<wsse:Password Type="wsse:PasswordText">String</wsse:Password>
		</wsse:UsernameToken>
	</wsse:Security>
</SOAP-ENV:Header>

Note

Only available for SOAP operations.

The 'SOAP Specific Header Authentication Scheme'.
For more information, see Overriding the SOAP security header.
The 'REST Forward Authentication Scheme' method is based on the HTTP Request and reuses the current authenticated session.
Tracking information or Session parameters are retrieved from the session and must not be defined on the request, otherwise a 400 (Bad request) error is returned.

Note

Only available for the RESTful operations.

Overriding the SOAP security header

It is possible to override the default WSS header in order to define another security authentication mechanism. Such an override is taken into account for both HTTP and JMS. To define and override, use the 'SOAP Header Security declaration' configuration settings under Administration > Lineage, which includes the following fields:

Schema location	The URI of the Security XML Schema to import into the WSDL.
Target namespace	The target namespace of elements in the schema.
Namespace prefix	The prefix for the target namespace.
Message name	The message name to use in the WSDL.
Root element name	The root element name of the security header. The name must be the same as the one declared in the schema.
wsdl:part element name	The name of the `wsdl:part` of the message.

The purpose of overriding the default security header is to change the declaration of the WSDL message matching the security header so that it contains the following:

<wsdl:definitions ... xmlns:MyPrefix="MyTargetNameSpace" ...
  ...
  <xs:schema ...>
    <xs:import namespace="MyTargetNameSpace" schemaLocation="MySchemaURI"/>
    ...
  </xs:schema>
  ...
  <wsdl:message name="MySecurityMessage">
    <wsdl:part name="MyPartElementName" element="MyPrefix:MySecurityRootElement"/>
  </wsdl:message>
  ...
  <wsdl:operation name="...">
    <soap:operation soapAction="..." style="document"/>
    <wsdl:input>
      <soap:body use="literal"/>
      <soap:header message="impl:MySecurityMessage" part="MyPartElementName" use="literal"/>
  ...
  </wsdl:operation>
</wsdl:definitions>

The corresponding XML Schema header declaration would be as follows:

<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="MyNameSpace"
		xmlns:MyPrefix="MyNameSpace">
  <element name="MySecurityRootElement" type="MyPrefix:SpecificSecurity"/>
  <complexType name="SpecificSecurity">
    <sequence>
      <element name="AuthToken" type="string"/>
    </sequence>
  </complexType>
</schema>

A SOAP message using the XML schema and configuration above would have the following header:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Header>
    <m:MySecurityRootElement xmlns:m="MyNameSpace">
      <AuthToken>String</AuthToken>
    </m:MySecurityRootElement>
    ...
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    ...
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Note

Only available for SOAP operations.

Lookup mechanism

Because EBX5 offers several authentication methods, a lookup mechanism based on conditions was set to know which method should be applied for a given request. The method application conditions are evaluated according to the authentication scheme priority. If the conditions are not satisfied, the server evaluates the next method. The following table presents the available authentication methods for each supported protocol and their application conditions. They are ordered from the highest priority to the lowest.

Operation / Protocol	Authentication methods and application conditions
SOAP / JMS	SOAP Security Header The SOAP request is received over the JMS protocol. The SOAP header content must contains a `Security` element. SOAP Specific Header The SOAP request is received over the JMS protocol. The SOAP header content must not contain a `Security` element.
SOAP / HTTP	Basic The HTTP request must hold an `Authorization` header. `Authorization` header value must start with the word `Basic`. No `login` is provided in the URL parameters. Standard The HTTP request must not hold an `Authorization` header. A `login` and a `password` are provided in the URL parameters. SOAP Security Header The SOAP header content must contain a `Security` element. The HTTP request must not hold an `Authorization` header. No `login` is provided in the URL parameters. SOAP Specific Header The SOAP header content must not contain a `Security` element. The HTTP request must not hold an `Authorization` header. No `login` is provided in the URL parameters.
WSDL / HTTP	Basic The HTTP request must not hold an `Authorization` header. `Authorization` header value must start with the word `Basic`. No `login` is provided in the URL parameters. Standard The HTTP request must not hold an `Authorization` header. A `login` and a `password` are provided in the URL parameters.
REST / HTTP	Token The HTTP request must hold an `Authorization` header. `Authorization` header value must start with the word `EBX`. No `login` is provided in the URL parameters. Basic The HTTP request must hold an `Authorization` header. `Authorization` header value must start with the word `Basic`. No `login` is provided in the URL parameters. Standard The HTTP request must not hold an `Authorization` header. A `login` and a `password` are provided in the URL parameters. Rest forward The HTTP request must not contain an `Authorization` header. No `login` is provided in the URL parameters. An `onwbpID` URL parameter and a session cookie must be provided in the HTTP request.

In case of multiple authentication methods present in the same request, EBX5 will return an HTTP code 401 Unauthorized.

SOAP and RESTful comparative

Operations	SOAP	REST
Data
Select or count records (with filter and/or view publication)	X	X
Selector for possible enumeration values (with filter)		X
Insert, update or delete records	X	X
Select or count history records (with filter and/or view publication)		X
Select node values from dataset	X	X
Update node value from dataset		X
Get table or dataset changes between dataspaces or snapshots	X
Get credentials for records	X
Dataspaces
Create, close, merge a dataspace	X
Create, close a snapshot	X
Validate a dataspace or a snapshot	X
Validate a dataset	X
Locking a dataspace	X
Workflow
Start, resume or end a workflow	X

Limitations

Date, time & dateTime format

Data services only support the following date and time formats:

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

SOAP naming convention

Due to the naming convention of the data service operations, each table defined within a data model must have a unique name for the WSDL generation.

Documentation > Reference Manual > Integration > Data services

EBX5 Version 5.8.1 [1067]. Copyright © Orchestra Networks 2000-2017. 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.

Introduction

Section contents

Overview of data services

Note

Interactions

Input and output message encoding

Tracking information

Session parameters

Exception handling

See also

Data services security

Authentication

Note

Note

Overriding the SOAP security header

Note

Lookup mechanism

SOAP and RESTful comparative

Limitations

Date, time & dateTime format

SOAP naming convention