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:

• Introduction to Web-Service-Based Message Exchange

• Exchanging SOAP-Based Service Messages with Custom WSDL

• Sending Custom SOAP Headers

• 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 must 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 must perform the following tasks:

• Uploading the WSDL

• Creating a document

• Creating an endpoint

• Attaching security policies

15.2.1.1 Uploading the WSDL

As the first task, you must 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 + button (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. In the case of a Zipped WSDL, select the Zip file and then select the root WSDL.
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.

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

15.2.1.3 Creating an endpoint

After you have created the custom document, you must 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 + button (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 Uploading the WSDL.

   Note:

   If you do not want to upload and use a custom WSDL, you can select the Use Generic SOAP list. This should enable you to send any XML document over SOAP. Oracle SOA Suite for healthcare integration provides a pre-seeded 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:

    After 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) button 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. You can also drag-and-drop the document definition to the Document To Send box.
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 Oracle 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. If the payload has to be validated against a WSDL or schema then enable the validation. 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.1.4 Attaching security policies

After you create an endpoint, you can attach security policies to it. Attaching security policies at the endpoint level rather than Global Policy Attachment (GPA) using the Oracle Enterprise Manager Fusion Middleware Control console enables you to maintain security policies at the Oracle Healthcare level locally.

By attaching policies locally, you can ensure that:

• Every endpoint has its own policy metadata

• Policies can be enabled or disabled along with endpoints

• Policies can be deleted along with endpoints

To attach security policies locally to an endpoint:

1. Open the endpoint that you created in Creating an endpoint.
2. On the endpoint page, click the Show Policy Configuration button on the top right-hand corner. The Policy Configuration section appears.
3. From the list of available Web services policies under Available Policies, select the policy that you want to attach to the endpoint. You can select multiple policies by pressing the Control key and clicking the policy names.
4. Click Attach to attach the selected policy or policies to the endpoint. You can click the Attach All button to attach all the available policies to the endpoint as shown in Figure 15-6.

   Figure 15-6 Attaching Security Policies

   
   Description of "Figure 15-6 Attaching Security Policies"

   Note:

   Some policies are contradictory to each other. If you try to attach such contradictory policies together to an endpoint, you get an error.

5. Click the Save button.

15.2.2 Exchanging Inbound SOAP-Based Messages

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

• Uploading the WSDL

• Creating a document for the inbound flow

• Creating an endpoint for inbound message exchange

• Attaching security policies for inbound message exchange

15.2.2.1 Uploading the WSDL

This task is the same as Uploading the WSDL of the outbound case.

15.2.2.2 Creating a document for the inbound flow

This task is the same as Creating a document of the outbound case.

15.2.2.3 Creating an endpoint for inbound message exchange

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

This task is similar to 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.

15.2.2.4 Attaching security policies for inbound message exchange

After you have created an endpoint, you can attach security policies to it. This task is similar to Attaching security policies of the outbound case.

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 must 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 GUID-A00054FF-2C82-491B-93EE-427CAD65C2AE-default.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:

• Outbound Synchronization: Composite

• Inbound Synchronization: Composite

• Outbound Synchronization: JMS Queues

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