Introduction

Overview

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

In order to invoke SOAP operations, for an integration use case, a WSDL must be generated from a data model. It will be possible to perform operations such as:

• Selecting, inserting, updating, deleting, or counting 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

• Administrative operations to manage access to the UI or to system information

Activation and configuration

Data services are enabled by deploying the ebx-dataservices web application along with the other EBX® modules. See Java EE deployment overview for more information.

In case of specific deployment, for example using reverse-proxy mode, see URLs computing for more information.

The default method for accessing data services is over HTTP, although it is also possible to use JMS for the SOAP operations. See JMS configuration and Using JMS for more information.

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>

For more information, see Session.getTrackingInfo in the Java API.

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.

Input parameters are available on custom Java components with a session object, such as: triggers, access rules, custom web services. They are also available on data workflow operations.

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

For more information, see Session.getInputParameterValue in the Java API.

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>
  

Using JMS

It is possible to access SOAP operations using JMS instead of HTTP. The JMS architecture relies on one JMS request queue (mandatory), on one JMS failure queue (optional), and on JMS response queues, see configuration JMS. The mandatory queue is the input queue. Request messages must be put in the input queue, and response messages are put by EBX® in the replyTo queue of the JMS request. The optional queue is the failure queue which allows you to replay an input message if necessary. If the queue is set and activated in the configuration file and an exception occurs while handling a request message, this input message will be copied in the failure queue.

The relationship between a request and a response is made by copying the messageId message identifier field of the JMS request into the correlId correlation identifier field of the response.

JMS location points must be defined in the Lineage administration in order to specialize the generated WSDL. If no specific location point is given, the default value will be jms:queue:jms/EBX_QueueIn.

Security

Authentication

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

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

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

  For more information on this authentication scheme, see Directory.authenticateUserFromLoginPassword.

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

• 'Specific authentication Scheme' is based on the HTTP Request. An implementation of this method can, for example, extract a password-digest or a ticket from the HTTP request. See Directory.authenticateUserFromHttpRequest for more information.

• The 'SOAP Specific Header Authentication Scheme'.

  For more information, see Overriding the SOAP security header.

Global permissions

Global access permissions can be independently defined for the SOAP and WSDL connector accesses. For more information see Global permissions.

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:

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>

To handle this non-default header, you must implement the method: Directory.authenticateUserFromSOAPHeader.

Lookup mechanism

Because EBX® 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.

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

Monitoring

Data service events can be monitored through the log category ebx.dataServices, as declared in the EBX® main configuration file. For example, ebx.log4j.category.log.dataServices= INFO, ebxFile:dataservices.

SOAP and REST comparative

(*) See REST Toolkit for more information.

Limitations

Date, time & dateTime format

Data services only support the following date and time formats:

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.