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
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.
All input messages must be exclusively in UTF-8. All output messages are in UTF-8.
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.
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.
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>
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.
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>
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 access permissions can be independently defined for the SOAP and WSDL connector accesses. For more information see Global permissions.
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 |
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.
Only available for SOAP operations.
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 / HTTP |
|
WSDL / HTTP |
|
In case of multiple authentication methods present in the same request, EBX® will return an HTTP code 401 Unauthorized.
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.
Operations | SOAP | REST |
|---|---|---|
Data | ||
Select metadata | X | |
Select or count records (with filter and/or view publication) | X | 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 | |
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 |
Other | ||
Develop web services from the Java API | X (*) |
(*) See REST Toolkit for more information.
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 |
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.