../E10229-13.mobi />

21 Using the Oracle B2B Web Services

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 contains the following topics:

21.1 Introduction to Oracle B2B Web Services

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:

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.

21.2 Using the Outbound Web Service

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.

Table 21-1, Table 21-2, and Table 21-3 describe the Outbound Web Service request, response and fault notification message parameters.

Table 21-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: DUNS

Identification type

No

documentProtocolVersion

String

Example: 4010

Document type version

Yes Foot 1 

documentTypeName

String

Example: 850

Document type name

action

String

Example: PurchaseOrder

ebMS action name

service

String

Example: OrderProcessing

ebMS service name

serviceType

String

Example: string

Default: string

ebMS service type

messageId

String

Message ID given in this parameter is used to create APP_Message.

No

replyToMessageId

String

Example:
<reply_msgID>:collaborationID

Holds the message ID of which message this reply goes to, along with the collaboration ID.

No

messageType

String

Type of the message

No

encoding

String

Example: ISO-8859-1

Default: UTF-8

Encoding format

No

payload

Xsd:anyType

Holds the payload

Yes

attachment

Xsd:anyType

Attachment, if any

No


Footnote 1 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 21-2 Outbound Web Service Response Parameters

Header Data Type Description Required

isTransmitted

Boolean

If true, the message was successfully transmitted; otherwise false.

Yes


Table 21-3 Outbound Web Service Fault Message Parameters

Header Data Type Description

ExceptionMessage

String

If a fault is found, the Exception Stack Trace is transmitted.


21.3 Using the Translation Web Service

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.

21.3.1 XMLToNativeService

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.

21.3.1.1 Complete Envelope

This translation produces a complete native document.

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

  • EDI EDIFACT

  • HL7

21.3.1.2 Transaction Set Alone

This translation produces a transaction set only in the resultant native content.

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

21.3.2 NativeToXMLService

This service translates a given native document to XML. It can translate either a complete native document or just the transaction set alone.

21.3.2.1 Complete Envelope

The service translates a complete native document 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

21.3.2.2 Transaction Set Alone

This service produces the XML content for a given transaction set.

The prerequisites and supported protocol are the same as that of "XMLToNativeService".

21.3.3 Translation Web Service Parameters

Table 21-4 describes the Translation Web Service message parameters.

Table 21-4 Translation Web Serice Parameters

Header Data Type Description Required

transactionSetOnly

Boolean

If translation is done only for the transaction set

 

TPName

String

Trading partner name

 

documentTypeName

String

Document type name

Yes

documentProtocolVersion

String

Document protocol version

Yes

encoding

String

Type of encoding

 

payload

String

The actual payload

Yes

FAonError

String

If FA will be sent in case of error only

 

Additional Header

     

HeaderName

String

Any additional header name

Yes

HeaderValue

String

Any additional header value

Yes

ElementDelimiters

String

   

Segment

String

The segment delimiter

 

Element

String

The element delimiter

 

Subelement

String

The subelement delimiter

 

ReplacementCharacter

String

Replacement character

 

RepeatingSeparator

String

Repeatingt separator

 

21.4 Using the Query API

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:

21.4.1 Is Trading Partner Agreement Setup Parameters

Table 21-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: DUNS

Identification type

No

document

String

Example: Sales Order

Name of the internal application document or AIA EBO to be sent out

Yes

action

String

Example: Update

A sub-classification which identifies the specific interaction with the Trading Partner

Yes


Table 21-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 21-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.


21.4.2 Get Trading Partner Agreement Information Parameters

Table 21-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: DUNS

Identification type

No

document

String

Example: Sales Order

Name of the internal application document or AIA EBO to be sent out

No

action

String

Example: Update

A sub-classification which identifies the specific interaction with the Trading Partner

No


Table 21-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

DocumentProtocol 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


Table 21-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.


21.5 Securing Oracle B2B Web Services

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 lifecycle of Web services and their policies.

To specify a policy and attach it to the web services endpoints:

  1. In Oracle B2B Console, go to Administration>Configuration tab.

  2. Enter the appropriate value in the Webservice Policy field in the Non Purgeable section.

    Enter either the Oracle Web Services Manager policy URI to secure just the endpoints, or enter the whole <policy> tag to uptake RM, Addressing, and Logging. See the examples below.

    See "What Oracle WSM Security Policies Are Available?" in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server for a listing of available Oracle WSM policies.

  3. Click Save.

    Based on the policy attached here, WSDL URL will start publishing/describing the policy details which need to be used while creating the proxy client for this service.

    No restart of B2B is required to uptake the policy changes.

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> 

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.