Cloud Software Group, Inc. EBX®
Documentation > Developer Guide > SOAP data services
Navigation mode Documentation > 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:

- 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

##### Note

See SOAP and REST comparative.

## Activation and configuration

Data services are enabled by deploying the `ebx-dataservices` web application along with the other EBX® modules. See Jakarta EE deployment 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 the content. 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==

- 'Bearer Authentication Scheme' method works with bearer tokens that may be issued from a third party provider.

      > Authorization: bearer <accessToken>

  For more information on this authentication scheme, see Bearer authentication configuration.

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

##### See also

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

##### See also

- Configuring the EBX® logs
- TIBCO EBX® main configuration file

## SOAP and REST comparative

Operations | SOAP | REST
--- | --- | ---
Data |  |
Select metamodel |  | X
Select or count records (with filter and/or view publication) | X | X
Select records with association values (first level) | X |
Select business objects |  | X
Update or delete records (with filter and/or view publication) |  | X
Selector for possible enumeration values (with filter) |  | X
Prepare for creation or duplication |  | 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 |
Generate service contract | WSDL | OpenAPI
Views |  |
Look up published table views |  | X
Datasets |  |
Select dataset information |  | X
Select root or child datasets |  | X
Dataspaces |  |
Select dataspace or snapshot information |  | X
Select root or children dataspaces, or select snapshots |  | X
Create, close, merge a dataspace | X | X
Create, close a snapshot | X | X
Validate a dataspace or a snapshot | X |
Validate a dataset | X |
Locking, unlocking a dataspace | X | 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
Staging API |  | X
Health operations |  | X
Other |  |
Develop custom services from the Java API (*) |  | X
Generate custom service contracts (*) |  | OpenAPI

(*) 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