TIBCO EBX®
Documentation > Developer Guide > SOAP data services
Navigation modeDocumentation > Developer Guide > SOAP data services

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:

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

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.

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.

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

Exception handling

In case of unexpected server error upon execution of:

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

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:

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>

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

Note

Only available for SOAP operations.

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.

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.

Specific

  • The HTTP request must not satisfy the conditions of the previous authentication methods.

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.

Specific

  • The HTTP request must not satisfy the conditions of the previous authentication methods.

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

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

Refresh a replication unit

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

Administration

Manage the default directory content 'Users', 'Roles'... tables.

X

X

Open, close the user interface

X

X

Select, insert, update, delete operations for administration dataset

X

Select the system information

X

X

Other

Develop web services from the Java API

X (*)

(*) See REST Toolkit for more information.

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 > Developer Guide > SOAP data services