15 Enabling Web-Service-Based Message Exchange in Oracle Healthcare

This chapter describes how to enable Web-service-based message (typically SOAP-based) exchange between endpoints in Oracle SOA Suite for healthcare integration.

The chapter contains the following sections:

• Section 15.1, "Introduction to Web-Service-Based Message Exchange"

• Section 15.2, "Exchanging SOAP-Based Service Messages with Custom WSDL"

• Section 15.3, "Sending Custom SOAP Headers"

• Section 15.4, "Sample Request-Reply Scenarios"

15.1 Introduction to Web-Service-Based Message Exchange

Oracle Healthcare allows you to exchange Web service (SOAP) based messages between endpoints. 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 endpoints 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 endpoint file transfer and/or message exchange using Web service (in addition to Healthcare-specific protocols.)

15.2 Exchanging SOAP-Based Service Messages with Custom WSDL

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.

15.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"

• Task 2, "Creating a document"

• Task 3, "Creating an endpoint"

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 SOA Suite for healthcare integration console (http://<hostname>:<port>/healthcare), 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 Designer tab and then click the Configuration tab.

3. Click to select the WSDL folder.

4. Click the + icon (Create). The Create WSDL dialog box appears.

5. Specify a name for the WSDL such as TransmitWSDL. Ensure that the name does not contain any spaces or special characters.

6. For the Definition File field, click the Browse button to select the WSDL to be uploaded. For this example, the WSDL selected is TransmitDoc2way.wsdl. Click OK to complete the process.

   Figure 15-1 displays the newly created WSDL.

   Figure 15-1 Uploaded WSDL

   
   Description of "Figure 15-1 Uploaded WSDL"
   
   

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

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 3.4, "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 TransmitWSDL.

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

   Figure 15-2 Creating Documents

   
   Description of "Figure 15-2 Creating Documents"
   
   

5. Click Apply.

Task 3   Creating an endpoint

After you have created the custom document, you need to create an endpoint and associate the endpoint with the custom document.

To create an endpoint:

1. In the Oracle Healthcare console, click the Endpoint folder under Configuration in the Designer tab.

2. Click the + icon (Create). The Create Endpoint dialog box appears.

3. Select WS-HTTP from the Transport Protocol list.

4. Specify a name for the endpoint.

5. Select the Synchronous check box if you want to enable sending and receiving of documents by using the same connection. In this case, leave the check box as is.

6. Select Outbound from the Direction list.

7. Select the required WSDL from the WSDL list. In this case, select TransmitWSDL, which you uploaded in Task 1.

   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. Oracle SOA Suite for healthcare integration provides a preseeded generic WSDL that is used when you select Use Generic SOAP.

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

9. Select the available port (TransmitDocuments2WayPort)

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

    Note:

    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

11. Enter the URL where the server is listening in the URL field.

    The endpoint configuration should look similar to Figure 15-3.

    Figure 15-3 Creating an Endpoint

    
    Description of "Figure 15-3 Creating an Endpoint"
    
    

12. Click OK.

    Note:

    Once the uploaded WSDL is used by an endpoint, you cannot update the WSDL file any more.

13. In the TransmitOutbound page, in the Document To Send section, click the + (Add) icon to display the Document window.

14. Navigate to the required custom document definition (TransmitDocumentDef), select it, and click OK to associate the document with the endpoint.

15. Click the Transport Details button to display the Transport Protocol parameters dialog box. Here, you can:

    • 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 Healthcare Web services outbound channel to send the default SOAP headers such as To, Doctype, and DocRevision as a part of the message as shown in Figure 15-4.

    • In the Advanced tab, enter any additional SOAP headers, if required.

      Figure 15-4 Transport Protocol Parameters

      
      Description of "Figure 15-4 Transport Protocol Parameters"
      
      

    • Click OK to return to the endpoint page .

16. Select the Enabled check box and click Apply to activate the endpoint as shown in Figure 15-5.

    Figure 15-5 Configuring an Endpoint for Outbound Message Exchange

    
    Description of "Figure 15-5 Configuring an Endpoint for Outbound Message Exchange"
    
    

15.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"

• Task 2, "Creating a document for the inbound flow"

• Task 3, "Creating an endpoint for inbound message exchange"

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   Creating an endpoint for inbound message exchange

After you have created the custom document, you need to create an endpoint and associate the endpoint with the custom document.

This task is similar to Task 3, "Creating an endpoint" of the outbound case with the following differences:

• In the Create Endpoint dialog box, specify TransmitInbound as the endpoint name and select Inbound as the direction.

• In the TransmitInbound page, add the custom document in the Document To Receive section.

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/WebService

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

Description of the illustration ws_servicelist.gif

15.3 Sending Custom SOAP Headers

Oracle Healthcare 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="hc.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>

15.4 Sample Request-Reply Scenarios

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

The section contains:

• Section 15.4.1, "Outbound Synchronization: Composite"

• Section 15.4.2, "Inbound Synchronization: Composite"

• Section 15.4.3, "Outbound Synchronization: JMS Queues"

• Section 15.4.4, "Inbound Synchronization: JMS Queues"

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

15.4.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. In the case of a non-responsive payload, an error is reported for request/reply.

15.4.3 Outbound Synchronization: JMS Queues

In the case of outbound synchronization with a JMS queue:

• Web Service: In the case of custom WSDL, uses soapAction (provided from backend or configured in the endpoint) to decide whether it is a one-way or request/reply operation specified by the WSDL. Reply is sent to the backend by using the internal delivery channel configuration. In the case of a generic SOAP WSDL, the transport parameters of the endpoint decides on the one-way or request/reply operation.

15.4.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. In the case of Sync, a reply needs to be generated in a Oracle SOA Suite for healthcare integration callout to be sent to the backend. In the case of a generic SOAP WSDL, the decision is based on the transport parameters specified in the endpoint.