Skip Headers
Oracle® Fusion Middleware User's Guide for Oracle B2B
11g Release 1 (11.1.1.7)

Part Number E10229-13
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

22 Enabling Web-Service-Based Message Exchange

This chapter describes how to enable Web-service-based message (typically SOAP-based) exchange between trading partners in Oracle B2B.

The chapter contains the following sections:

22.1 Introduction to Web-Service-Based Message Exchange

Oracle B2B allows you to exchange Web service (SOAP) based messages between trading partners. You can exchange messages in both inbound and outbound direction. However, currently, this support is limited to SOAP 1.1 messages over HTTP only.

The Web service feature not only enables partners to receive or send messages, but also it is layered as a protocol implementation and supports other general features such as reporting, tracking, and auditing.

Many enterprises are increasingly having a requirement to integrate their trading partners file transfer and/or message exchange using Web service (in addition to B2B-specific protocols.)

Oracle B2B support for Web services is based on the following specifications, however, implementation may differ at times:

22.2 Exchanging SOAP-Based Service Messages with Custom WSDL File

The support for SOAP-based messages is available for both inbound and outbound directions. You need to create or upload a Web Service Definition Language (WSDL) file that you can customize according to your requirement.

22.2.1 Exchanging Outbound SOAP-Based Messages

To enable exchange of outbound SOAP-based messages, you need to perform the following tasks:

Task 1   Uploading the WSDL

As the first task, you need to upload the WSDL file that is required to register a Web service to exchange messages. You can upload the WSDL in the either of the following ways:

  • Inline WSDL - a normal WSDL file where the XSD information is defined within the WSDL itself

  • A ZIP file containing a WSDL file and an XSD file

  • A ZIP file containing multiple WSDL and XSD files

To upload a WSDL:

  1. Log on to the Oracle B2B console (http://<hostname>:<port>/b2bconsole), where hostname is the name of the computer where Oracle SOA Suite is hosted and port is typically 8001 (in the case of a non-SSL connection).

  2. Click the Administration link and then click the WSDL tab.

  3. Click the + button (Add WSDL). An entry for the new WSDL gets created in the WSDL table.

  4. Specify a name for the WSDL such as Transmit_WSDL.

  5. In the WSDL section, click the Browse button to select the WSDL to be uploaded. For this example, the WSDL selected is TransmitDoc2way.wsdl. You can see the details of the WSDL is listed under the Uploaded WSDL artifact Info section as shown in Figure 22-1.

    Figure 22-1 WSDL Artifacts

    wsdl artifact
    Description of "Figure 22-1 WSDL Artifacts"

  6. Click Save and then click OK in the confirmation dialog.

Note:

after the uploaded WSDL file is referenced by any other metadata such as channels and they are deployed as a part of agreements, any update to the WSDL is disabled. After these references are inactivated, only then you can update the uploaded WSDL.

Task 2   Creating a document

The next task is to create a document for the outbound flow. Please note that currently, the only supported document type is custom.

To create a custom document:

  1. Create document definitions as specified in Section 4.2, "Creating Document Definitions." Specify:

    • Document Version - 1.0

    • Document Type - TransmitDocumentRequest

    • Document Definition - TransmitDocumentDef

  2. Select Use WSDL.

  3. Select the relevant WSDL Artifact, which in this case is Transmit_WSDL.

  4. Select the required WSDL Message, which in this case is the TransmitDocumentsRequestMessage as shown in .

    Figure 22-2 Creating Documents

    creating documents
    Description of "Figure 22-2 Creating Documents"

  5. Click Save.

Task 3   Adding the document to as a part of partner documents

The third task is to add the newly created custom document as a part of the Partner documents.

To add the document:

  1. Click the Partners link and then click the Documents tab.

  2. Click to select the remote trading partner name (GlobalChips) under the partner section.

  3. Under the Documents section on the right-hand pane, click the + button (Add Document Definition) to display the Select Document Definition window.

  4. Navigate to the required document definition and click Add to add the document definition.

  5. Click Save in the Documents tab.

    The document gets added to the list of partner documents as shown in Figure 22-3.

    Figure 22-3 Adding a Document

    adding a document
    Description of "Figure 22-3 Adding a Document"

Task 4   Creating a Trading Partner Delivery Channel

After adding the documents, you need to create a trading partner delivery channel to send messages.

To add a trading partner delivery channel:

  1. Click to select the trading partner (GlobalChips) under Partner on the left.

  2. Click the Channels tab.

  3. Click the + (Add Channel to Trading Partner) button.

  4. In the Channel section, specify a name for the channel (such as GlobalChips_Channel).

  5. Select Generic WS-1.0 from the Protocol list.

  6. In the Channel details section, in the Web Service Parameters tab:

    • Select Transmit_WSDL, the WSDL that you uploaded from WSDL Artifact from the WSDL Artifact list.

    • Select the available service (TransmitsDocumentService in this case).

      Note:

      Oracle B2B allows you to specify services, ports, and actions manually. This is useful when you want to specify additional service, port, or action beyond and over what is available as part of the selected WSDL. You can also provide string values for the preceding parameters manually. In the case of manually providing the service name, it should be in the following format, else there would be a validation error:

      {namespace}ServiceName

      The namespace must match the target namespace of the WSDL, else, the Security Policy Configuration will not be applied.

    • Select the available port (TransmitDocuments2WayPort).

    • Select the SOAP action (available from the WSDL).

    • Enter the URL where the server is listening as the Endpoint (URL), which is the URL of the GlobalChips trading partner.

    • Enter any additional HTTP headers, if required.

    • Select Omit WS Addressing Headers if you want to discard WS Addressing headers as a part of the message to be exchanged.

    • Select Omit Default SOAP Headers if you do not want Oracle B2B Web services outbound channel to send the default SOAP headers such as From, To, Doctype, and DocRevision as a part of the message.

    • Click the EM Policy Configuration Page link to access the Policy Set Summary page in Oracle Fusion Middleware Enterprise Manager Control console if you want to attach policies globally to your Web service.

      See "Creating and Managing Policy Sets" in Oracle Fusion Middleware Security and Administrator's Guide for Web Services for more information.

  7. Click Save as shown in Figure 22-4.

    Figure 22-4 Web Service Channel Details

    channel details
    Description of "Figure 22-4 Web Service Channel Details"

    Note:

    If you do not want to upload and use a custom WSDL, you can select the Use Generic SOAP check box. This should enable you to send any XML document over SOAP and you do not need to associate any WSDL in Channel/Document page. Oracle B2B provides a preseeded generic WSDL that is used when you select Use Generic SOAP.

Task 5   Creating and deploying an agreement

The last task is to create and deploy a trading partner agreement.

Refer to Chapter 6, "Creating and Deploying Trading Partner Agreements" to learn more about creating and deploying an agreement.

22.2.2 Exchanging Inbound SOAP-Based Messages

To exchange inbound SOAP-based messages, you need to perform the following tasks:

Task 1   Uploading the WSDL

This task is the same as Task 1, "Uploading the WSDL" of the outbound case.

Task 2   Creating a document for the inbound flow

This task is the same as Task 2, "Creating a document" of the outbound case.

Task 3   Adding the document to as a part of partner documents

This task is the same as Task 3, "Adding the document to as a part of partner documents" of the outbound case.

Task 4   Creating a listening channel

The next task is to create a listening channel to receive the incoming messages.

To create a listening channel:

  1. Click the Administration link and then click the Listening Channel tab.

  2. Click the + (Add Channel to Trading Partner) button.

  3. In the Listening Channel section, specify a name for the channel (such as Acme_ListeningChannel).

  4. Select Generic WS-1.0 from the Protocol list.

  5. In the Channel details section, in the Web Service Parameters tab:

    • Select Transmit_WSDL, the WSDL that you uploaded from WSDL Artifact from the WSDL Artifact list.

    • Select the available service (TransmitsDocumentService in this case).

    • Select the available port (TransmitDocuments2WayPort).

    • Enter the URL where the server is listening as the Endpoint (URL), which is the URL of the GlobalChips trading partner.

      Note that the Endpoint (URL) gets populated automatically with the URL of the partner where the server is listening.

    • Click the EM Policy Configuration Page link to access the Policy Set Summary page in Oracle Fusion Middleware Enterprise Manager Control console if you want to attach policies globally to your Web service.

    Note:

    If you want to use a standard WSDL instead of uploading and using a custom one, you can select the Use Generic SOAP check box. This enables you to send any XML document over SOAP and you do not need to associate any WSDL in Channel/Document page. Oracle B2B provides a preseeded generic WSDL that is used when you select Use Generic SOAP.

  6. Click the Channel Attributes tab and ensure that Enable Channel is selected.

  7. Click Save.

    Note:

    To ensure that the that the Web services have been registered for listening messages, access the following URL, log on by providing the user name and password, and check if the Web service is listed in the list of registered Web services:

    http:<host>:<port>/b2b/services

    You need to create users (along with their passwords) in the Oracle Weblogic Server console. Access the following link to know more about creating users in the Oracle Weblogic Server console:

    http://docs.oracle.com/cd/E23943_01/apirefs.1111/e13952/taskhelp/security/ManageUsersAndGroups.html

    The Web service is listed in the following format:

    ws/Listening_Channel_Name

    You can download the WSDL from the specific service by clicking the respective WSDL link as shown in the following graphic.

    registered Web service
    Description of the illustration bb_partnet_ws5.gif

Note:

After you create a listening channel and enable it, you cannot edit the channel to use a different WSDL. You need to delete the channel and create a new one.

22.3 Configuring wsa.action

There are various way to configure the wsa.action:

22.4 Sending Custom SOAP Headers

Oracle B2B allows you to send custom SOAP headers as a part of your outbound Web-service-based messages.

In the case of an outbound JMS channel, the sender trading partner can send multi-level custom SOAP headers as the following sample:

<CustomSOAPHeader xmlns="http://schemas.xmlsoap.org/soap/envelope/">
   <hello xmlns="http://xmlns.oracle1.com/soa1/generic/soap">
       <name xmlns="http://MY_NAME_SPACE">
         <firstname>John</firstname>
         <lastname>Doe</lastname>
       </name>
    </hello>
</CustomSOAPHeader>

In the case of an outbound fabric, the sender can send multi-level custom headers as the following sample:

<bpelx:inputProperty name="b2b.customSOAPHeaders" expression="'<CustomSOAPHeader xmlns="http://schemas.xmlsoap.org/soap/envelope/">
   <hello xmlns="http://xmlns.oracle1.com/soa1/generic/soap">
       <name xmlns="http://MY_NAME_SPACE">
         <firstname>John</firstname>
         <lastname>Doe</lastname>
       </name>
    </hello>
</CustomSOAPHeader>

22.5 Attaching Policies to Web Services

This section discusses how to attach policy sets to Web services by using the Oracle Fusion Middleware Enterprise Management Control console.

To create the UserName token policy and required credentials, you need to perform the following tasks:

Task 1   Creating Default Credentials Map and Key

The first task is to create credentials.

To create credentials:

  1. Log on to Oracle Fusion Middleware Enterprise Management Control console by accessing the following URL:

    http://<hostname>:<port>/em

    Where:

    • hostname: The name of the computer running the Oracle SOA Suite

    • port: The port number of the Admin server; typically 7001.

  2. Expand the domain name, such as soainfra, under Weblogic Domain in the Target Navigation pane.

  3. Right-click soainfra, and select Security > Credentials to display the Credentials page as displayed in Figure 22-5.

    Figure 22-5 Accessing the Credentials Page

    Description of Figure 22-5 follows
    Description of "Figure 22-5 Accessing the Credentials Page"

  4. In the Credentials page, click Create Map.

  5. In the Create Map dialog box, enter oracle.wsm.security as the map name as displayed in Figure 22-6 and click OK.

    Figure 22-6 Create Map Dialog Box

    Description of Figure 22-6 follows
    Description of "Figure 22-6 Create Map Dialog Box"

  6. Select oracle.wsm.security (the map that you created) and click Create Key to display the Create Key dialog box.

  7. In the Create Key dialog box, do the following as displayed in Figure 22-7:

    1. Enter the key name as basic.credentials in the Key field.

    2. Select Password as Type.

    3. Eneter the Admin user name, which in this case is weblogic.

    4. Enter a password in the Password field.

    5. Confirm the password that you have entered in the last step.

    6. Click OK.

    Figure 22-7 Create Key Dialog Box

    Description of Figure 22-7 follows
    Description of "Figure 22-7 Create Key Dialog Box"

Task 2   Creating and attaching outbound policy sets

The next task is to create and attach the outbound policy sets to the Web service.

To create an outbound policy set and attach it to Web services:

  1. Click the Weblogic Domain list on the domain name (soainfra) page and select Web Services > Policy Sets to display the Policy Set Summary page as displayed in Figure 22-8.

    Figure 22-8 Policy Set Summary Page

    Description of Figure 22-8 follows
    Description of "Figure 22-8 Policy Set Summary Page"

  2. In the Policy Set Summary page, click Create to display the Create Policy Set wizard.

  3. Enter the name as b2bOutboundTest, select Enabled, select Web Service Client from the Type of Resources list, and click Next as displayed in Figure 22-9.

    Figure 22-9 Create Policy Set - Enter General Information Page

    Description of Figure 22-9 follows
    Description of "Figure 22-9 Create Policy Set - Enter General Information Page"

  4. In the Enter Resource Scope page, enter the following as displayed in Figure 22-10 and click Next:

    • The domain name, such as soainfra

    • The application name, such as soainfra

    • The aplication module name, such as soainfra

    • The SOA reference or Web service client name, such as {http://www.spscommerce.com/WS/TransmitDocuments}TransmitDocumentsService

    • The port name, such as TransmitDocumentsSoapHttpPort

    Figure 22-10 Create Policy Set - Enter Resource Scope Page

    Description of Figure 22-10 follows
    Description of "Figure 22-10 Create Policy Set - Enter Resource Scope Page"

  5. In the Enter Constraint page, click Next.

  6. In the Add Policy References page, select the oracle/wss_username_token_client_policy from the Available Policies section, click Attach as displayed in Figure 22-11, and then click Next.

    Figure 22-11 Create Policy Set - Add Policy References Page

    Description of Figure 22-11 follows
    Description of "Figure 22-11 Create Policy Set - Add Policy References Page"

  7. In the Summary page, click Save to return to the Policy Set Summary page.

Task 3   Creating and attaching inbound policy sets

The final task is to create and attach inbound policy sets.

To create an inbound policy set and attach it to Web services:

  1. Repeat steps 1 and 2 from Task 2.

  2. Enter the name as b2bIutboundTest, select Enabled, select Web Service Endpoint from the Type of Resources list, and click Next as displayed in Figure 22-12.

    Figure 22-12 Create Policy Set - Enter General Information Page

    Description of Figure 22-12 follows
    Description of "Figure 22-12 Create Policy Set - Enter General Information Page"

  3. In the Enter Resource Scope page, enter the following as displayed in Figure 22-13 and click Next:

    • The domain name, such as soainfra

    • The application name, such as soainfra

    • The aplication module name, such as soainfra

    • The SOA reference or Web service client name, such as {http://www.spscommerce.com/WS/TransmitDocuments}TransmitDocumentsService

    • The port name, such as TransmitDocumentsSoapHttpPort

    Figure 22-13 Create Policy Set - Enter Resource Scope Page

    Description of Figure 22-13 follows
    Description of "Figure 22-13 Create Policy Set - Enter Resource Scope Page"

  4. In the Enter Constraint page, click Next.

  5. In the Add Policy References page, select the oracle/wss_username_token_service_policy from the Available Policies section, click Attach, and then click Next.

  6. In the Summary page, click Save to return to the Policy Set Summary page.

22.6 Identifying Trading Partner at Runtime

At runtime, you can identify the trading partner from which the message is received on the basis of various transport headers.

You can identify a trading partner by using the following information (listed in order of priority):

22.7 Sample Request-Reply Scenarios

This section discusses the synchronized request-reply scenarios when using a Web service or the Generic SOAP.

The section contains:

22.7.1 Outbound Synchronization: Composite

In the case of outbound synchronization with a composite:

  • Web Service: Relies on the composite to decide whether the synchronization is one-way, or if the request/reply pattern is used. If soapAction is provided, it is used only to overwrite the HTTP soapAction headers.

    Resubmission of a synchronized request/reply message needs to be done from the composite. If any such message is resubmitted from the Oracle B2B console, it is be treated as a one-way message.

  • Generic SOAP: Relies on the composite to decide one-way or request/reply operation. The channel configuration (None/Sync) does not take effect.

22.7.2 Inbound Synchronization: Composite

In the case of inbound synchronization with a composite:

  • Web Service: Uses soapAction from the HTTP header to decide whether it is a one-way or request/reply operation specified by the WSDL. If soapAction is not defined in the WSDL, then Oracle B2B falls back to the Channel configuration. In the case of a non-responsive payload, an error is reported for request/reply.

  • Generic SOAP: Depends on the Channel configuration (None/Sync). In the case of a non-responsive payload, an error is reported for request/reply.

22.7.3 Outbound Synchronization: JMS Queues

In the case of outbound synchronization with a JMS queue:

  • Web Service: Uses soapAction (provided from backend or configured in the listening channel) to decide whether it is a one-way or request/reply operation specified by the WSDL. If soapAction cannot be located in the WSDL, Oracle B2B defaults to the Channel configuration. Reply is sent to the backend by using the inbound agreement configuration.

  • Generic SOAP: Depends on the Channel configuration (None/Sync). If no reply comes back for Sync case, Oracle B2B reports an error. Reply is sent to the backend by using inbound agreement configuration.

22.7.4 Inbound Synchronization: JMS Queues

  • Web Service: Uses soapAction from the HTTP header to decide whether it is a one-way or request/reply operation specified by the WSDL. If soapAction is not defined in the WSDL, Oracle B2B falls back to the Channel configuration (None/Sync). In the case of Sync, a reply needs to be generated in a Oracle B2B callout to be sent as response back to the trading partner.

    If the incoming request has WS-Addressing enabled, then the response message sends the ws-addressing mandatory headers.

  • Generic SOAP: Depends on the Channel configuration (None/Sync). In case of Sync, a reply needs to be generated in a Oracle B2B callout to be sent as response back to the trading partner.