This chapter provides information about using the Oracle B2B Web Services such as Outbound web service and Translation Web service. It also discusses how to secure the Web services.
The chapter includes the following sections:
Oracle B2B exposes web services to retrieve the document details in Oracle JDeveloper. These are partner-facing web services, where the user can send messages to Oracle B2B. Similarly, Oracle B2B provides a web service exposed to the back end to receive the messages, and process and send to partner, based on the agreements deployed in Oracle B2B.
To use the Oracle B2B web services, create a web service proxy in your application in Oracle JDeveloper. The Web Services Description Language (WSDL) files for the web services are available at the following URLs on the system where Oracle B2B is installed.
http://host_name:port_number/b2b/services/
A URL suffixed with just a URL pattern of Servlet entered in the Web browser, without any URI, provides the list of WSDLs available for download (with no security restrictions).
Oracle B2B provides the following web service APIs:
Outbound Web Service API provides a built-in internal listening channel. See Using the Outbound Web Service for more information.
Translation Web Service API is exposed to translate the native payload, such as HL7, EDI, to XML format. See Using the Translation Web Service for more information.
Query API helps to retrieve the configured details in Oracle B2B. See Using the Query API for more information.
Security For Oracle B2B Web Services
Oracle Web Services Manager allows integrating various types of policies without impacting the runtime and flow of the web service, and it provides security of service infrastructure. Signing, encryption/decryption, authentication, authorization, auditing, and reporting will be provided by this tool kit. Hence, this web service implementation will not address the details of security, signing, and encryption. Web service methods hold the business logic instead of security details. Based on the policy enforced in Oracle Weblogic Server console, the web service client must attach security details with the web services port.
The Outbound Web Service is exposed as a built-in internal listening channel, and messages are enqueued to this service. Based on the details and headers in soap:body
, agreement identification is done and the message are routed to the partner.
The following SOAP headers are used to pass information required to find a trading partner agreement in the case of B2B web services:
<To xmlns="http://com.oracle.b2b/soap">SCDHHS</To> <DocVersion xmlns="http://com.oracle.b2b/soap">5010X222A1</DocVersion> <From xmlns="http://com.oracle.b2b/soap">ProfessionalClaims837SOAP</From> <DocType xmlns="http://com.oracle.b2b/soap">837</DocType>
Table 22-1, Table 22-2, and Table 22-3 describe the Outbound Web Service request, response and fault notification message parameters.
Table 22-1 Outbound Web Service Request Parameters
Header | Data Type | Description | Required |
---|---|---|---|
from |
String |
Host name or identification value |
No |
to |
String |
Trading Partner name or identification value |
Yes |
@type |
String Example: |
Identification type |
No |
documentProtocolVersion |
String Example: |
Document type version |
Yes* |
documentTypeName |
String Example: |
Document type name |
Yes* |
action |
String Example: |
ebMS action name |
Yes * |
service |
String Example: |
ebMS service name |
Yes * |
serviceType |
String Example: Default: |
ebMS service type |
Yes * |
messageId |
String Example: |
Message ID given in this parameter is used to create |
No |
replyToMessageId |
String Example: |
Holds the message ID of which message this reply goes to, along with the collaboration ID. |
No |
messageType |
String Examples: INVALID (0) REQ (1) RESP (2) ACK (3) IN_BAND_EXCEPTION (4) OUT_OF_BAND_EXCEPTION (5 STATUS_REQ (6) STATUS_RESP (7) PULL (8) FUNCTIONAL_ACK (9) BATCH_REQ (10) OTHER (99) PING (11) PONG (12) TA1(13) |
Type of the message |
No |
encoding |
String Example: Default: |
Encoding format |
No |
payload |
Xsd:anyType |
Holds the payload |
Yes |
attachment |
Xsd:anyType |
Attachment, if any |
No |
*Either documentProtocolVersion
and documentTypeName
must be present, or action
, service
, and serviceType
must be present. A custom generic case only requires action
and not the others.
Table 22-2 Outbound Web Service Response Parameters
Header | Data Type | Description | Required |
---|---|---|---|
isTransmitted |
Boolean |
If |
Yes |
Table 22-3 Outbound Web Service Fault Message Parameters
Header | Data Type | Description |
---|---|---|
ExceptionMessage |
String |
If a fault is found, the Exception Stack Trace is transmitted. |
The Translation Web Service translates the XML payload, such as HL7, EDI, to native format as well as translates the native documents to XML.
Note:
If a non-EDI XML is sent, then the translated content contains the same payload as it is, provided the agreement matches in Oracle B2B server.
If the EDI XML is sent for translation, and the document is involved as part of a batch, then the translated response will not translate the payload.
Note:
Translation Web service requests are not differentiated from other outbound requests in reporting and metrics.
Note:
The TranslateService
Web service has been deprecated.
This service translates a given XML payload to the native document. Translation is possible in two levels, complete envelope or just the transaction set alone.
This translation produces a complete native document including the envelope headers such as ISA and GS for X12.
It is an EDI - X12 envelope along with payload and is not a separate parameter. Make sure that the transactionSetOnly
element is set to false
for the complete envelope use case.
Prerequisites:
Valid deployed outbound agreement
Trading Partner name, document type name, document protocol version and payload are mandatory for the service invocation
Supported protocols:
EDI X12
This translation produces a transaction set only in the resultant native content without Interchange and Group header and trailer segments.
Prerequisites:
The service expects the document type and revision to be configured in Oracle B2B.
The transactionSetOnly
element should be set to true
and the Trading Partner name should not be part of service invocation request.
The elements, transactionSetOnly
, documentTypeName
, documentProtocolVersion
, and payload
are mandatory for the service invocation.
Supported protocol:
EDI X12
This service translates a given native document to XML. It can translate either a complete native document or just the transaction set alone.
The service translates a complete native document including the Interchange and Group header and trailer segments to XML.
Prerequisites:
Valid deployed inbound agreement
Trading Partner name and payload are mandatory for the service invocation
Supported protocols:
EDI X12
EDI EDIFACT
HL7
This service produces the XML content for a given transaction set (ST to SE).
The prerequisites and supported protocol are the same as that of "XMLToNativeService".
Table 22-4 describes the Translation Web Service message parameters.
Table 22-4 Translation Web Service Parameters
Header | Data Type | Description | Required |
---|---|---|---|
transactionSetOnly |
Boolean |
If translation is done only for the transaction set; If |
- |
TPName |
String Example: |
Trading partner name |
- |
documentTypeName |
String Example: |
Document type name |
Yes |
documentProtocolVersion |
String Example: |
Document protocol version |
Yes |
encoding |
String Example: |
Type of encoding |
- |
payload |
String |
The actual payload |
Yes |
FAonError |
String Example: |
If it is |
- |
Additional Header |
- |
- |
- |
HeaderName |
String Example: xsd:string |
Any additional header name |
Yes |
HeaderValue |
String Example: xsd:string |
Any additional header value |
Yes |
ElementDelimiters |
String |
- |
- |
Segment |
String Example: |
The segment delimiter |
- |
Element |
String |
The element delimiter |
- |
Subelement |
String |
The subelement delimiter |
- |
ReplacementCharacter |
String |
Replacement character |
- |
RepeatingSeparator |
String |
Repeating separator |
- |
The Query API retrieves the configured details from Oracle B2B, and share them with applications.
Before initiating a message transmission from applications, a health check request is made for the given parameters. This check finds if any configurations exist, and how many are active. If no configuration is found, the application can stop message flow in its layer with the message "no configuration found in B2B."
The following APIs are provided:
Is Trading Partner Agreement Setup
returns true if agreement found for the given inputs. See Is Trading Partner Agreement Setup Parameters for parameter details.
Get Trading Partner Agreement Information
returns agreement details. See Get Trading Partner Agreement Information Parameters for parameter details.
Table 22-5, Table 22-6, and Table 22-7 describe the Trading Partner Agreement Setup message parameters.
Table 22-5 Is Trading Partner Agreement Setup Request Parameters
Header | Data Type | Description | Required |
---|---|---|---|
from |
String |
Host name or identification value |
No |
to |
String |
Trading Partner name or identification value |
No |
@type |
String Example: |
Identification type |
No |
Table 22-6 Is Trading Partner Agreement Setup Response Parameters
Header | Data Type | Description | Required |
---|---|---|---|
MatchedTPACount |
integer |
Number of Agreements present in an active state in the Oracle 2B Repository |
Yes |
Table 22-7 Is Trading Partner Agreement Setup Fault Message Parameters
Header | Data Type | Description |
---|---|---|
ExceptionMessage |
String |
If a fault is found, the Exception Stack Trace is transmitted. |
Table 22-8, Table 22-9, and Table 22-10 describe the Trading Partner Agreement Information message parameters.
Table 22-8 Get Trading Partner Agreement Information Request Parameters
Header | Data Type | Description | Required |
---|---|---|---|
from |
String |
Host name or identification value |
No |
to |
String |
Trading Partner name or identification value |
No |
@type |
String Example: |
Identification type |
No |
document |
String Example: |
Name of the internal application document or AIA EBO to be sent out |
No |
action |
String Example: |
A sub-classification which identifies the specific interaction with the Trading Partner |
No |
Table 22-9 Get Trading Partner Agreement Information Response Parameters
Header | Data Type | Description | Required |
---|---|---|---|
AgreementID |
String |
Unique Agreement ID of the matching agreement |
Yes |
B2BDocumentDef |
String |
Document definition in Oracle B2B used for creating the Oracle B2B document type |
Yes |
B2BDocumentType |
String |
Document type defined in Oracle B2B for the requested application document and action |
Yes |
B2BDocumentRevision |
String |
Document revision defined in Oracle B2B for the requested application document and action |
Yes |
B2BDocumentProtocol |
String |
Document Protocol name defined in Oracle B2B for the requested application document and action |
Yes |
Direction |
String |
Document direction |
Yes |
XSLTFile |
String |
XSLT file to be used by the AIA layer to generate the Oracle B2B TP document |
No |
DCName |
String |
Delivery Channel associated with the Trading Partner Agreement |
Yes |
ExchangeProtocol |
String |
Type of transport protocol to exchange messages with trading partner |
Yes |
SyncMode |
True/False |
True is Request Response; false is one-way |
Optional for FTP and SMTP; required for HTTP/WS. |
Table 22-10 Get Trading Partner Agreement Information Fault Message Parameters
Header | Data Type | Description |
---|---|---|
ExceptionMessage |
String |
If a fault is found, the Exception Stack Trace is transmitted. |
Web services exposed in B2B must be secured to hide the configuration details from intruders. The Oracle Web Services Manager policy approach provides the facility to secure the web services based on your requirements.
Web services endpoints are registered dynamically and programmatically using the oracle.webservices.provider.ProviderConfig.addService(...)
API. Because these endpoints are not displayed in Oracle Enterprise Manager Fusion Middleware Control Console, Oracle B2B maintains the life cycle of Web services and their policies.
Limitations
There is no way to control the policy only for the particular endpoint. Whatever the policy specified, it is applicable for all the endpoints.
Removing already specified policy URI by clearing the Webservice Policy field does not work. You must enter some string in the field, such as "none".
No metrics are displayed for Oracle B2B Web service usage in Oracle Enterprise Manager Fusion Middleware Control Console.
To specify a policy and attach it to the web services endpoints:
Example 22-1 Examples
Example 1: Enter the following URI in Webservice Policy to apply security policy oracle/wss_username_token_service_policy
.
oracle/wss_username_token_service_policy
Example 2: Enter the following XML in Webservice Policy, which applies Security and RM policy.
<policy><policy-references><policy-reference uri="oracle/wss_username_token_ service_policy" category="security"/><policy-reference uri="oracle/wsrm11_policy" category="wsrm"/></policy-references></policy>