2 Working with the Oracle Healthcare Adapter

This chapter describes the Oracle Healthcare Adapter, which enables healthcare integration components to be used in Oracle SOA Suite composites. The adapter is used in an Oracle JDeveloper environment.

This chapter includes the following topics:

2.1 Introduction to the Oracle Healthcare Adapter

The Oracle Healthcare Adapter allows you to add healthcare integration binding components to a SOA composite application to create an end-to-end process, such as sending admissions information generated by a registration application to a laboratory system. The Healthcare Adapter establishes the type of documents transmitted between a SOA composite application and external healthcare applications. You can use other SOA Suite components in your composite application, including BPEL processes, Oracle Mediator components, a variety of adapters, and so on.

2.1.1 The Healthcare Configuration Wizard

Adding a Healthcare Adapter to a composite launches the Healthcare Configuration Wizard in Oracle JDeveloper. The wizard lets you create and configure healthcare integration binding components in a SOA composite application as follows:

  • The component is used as a service (inbound) to receive messages from external systems and deliver them to SOA composite applications. Oracle SOA Suite for healthcare integration is the entry point to the SOA composite application.

  • The component is used as a reference (outbound) to send messages from the SOA composite application to external applications.

As you follow the steps in the Healthcare Configuration Wizard, you are prompted to select components, such as document definitions, which were created in Oracle SOA Suite for healthcare integration. You can also launch Oracle SOA Suite for healthcare integration from the wizard to create a document definition if the right one does not already exist.

Note:

If SSL is enabled in the middleware (the healthcare integration Web service), then the Healthcare Configuration Wizard detects the SSL port and retrieves the document definitions using the SSL connection.

2.1.2 What Happens When You Add a Healthcare Adapter to a SOA Composite

Completing the Healthcare Configuration Wizard adds a new healthcare integration service or reference to the composite application and generates the corresponding WSDL file. The WSDL file defines the schema, message, document definition, the WebLogic Managed Server, and the connection to the application server. Connecting the service or reference to Oracle BPEL processes or Oracle Mediator component makes the healthcare integration normalized message properties available to that process or component so you can further configure the healthcare application by specifying endpoints, message types, message IDs, document types, protocols, and so on.

Note:

In order to connect the composite application to a healthcare integration endpoint, you must specify a value for the hc.fromEndpoint normalized message property if a healthcare adapter is defined as a service, and you must specify a value for the hc.toEndpoint normalized message property if a healthcare adapter is defined as a reference.

2.2 How to Use Healthcare Adapters in a SOA Composite Application

To create a SOA composite application with a Healthcare Adapter, perform the following steps in the order given:

2.2.1 Create a SOA Application and Project

You can use the Healthcare Adapter to add a healthcare integration binding component to an existing JDeveloper project to enable communications between the SOA Suite and external healthcare systems. First you need to create the application and the project.

For more information about creating SOA composite applications, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Before You Begin

Before you create the application and project, review the following guidelines:

  • Do not use spaces in the name of the application.

  • Do not create applications and projects in directory paths that have spaces (for example, c:\Program Files).

  • In a UNIX operating system, it is highly recommended that you enable Unicode support by setting the LANG and LC_All environment variables to a locale with the UTF-8 character set. This enables the operating system to process any character in Unicode. SOA technologies are based on Unicode. If the operating system is configured to use non-UTF-8 encoding, SOA components may function in an unexpected way.

    To enable Unicode support in an Oracle JDeveloper design-time environment, select Tools > Preferences > Environment > Encoding > UTF-8. This setting is also applicable for runtime environments.

  • Composite and component names cannot exceed 500 characters.

  • A project deployed to the same infrastructure must have a unique name across all SOA composite applications. The uniqueness of a composite is determined by its project name. For example, do not create a project named Project1 in two different applications. During deployment, the second deployed project (composite) overwrites the first deployed project (composite).

To create a SOA application and project

  1. Start Oracle JDeveloper Studio Edition.

    Note:

    If you are starting Oracle JDeveloper for the first time, specify the location for the Java JDK.

  2. Create a new SOA composite application, as described in Table 2-1.

    Table 2-1 SOA Composite Application Creation

    If Oracle JDeveloper... Then...

    Has no applications

    For example, you are opening Oracle JDeveloper for the first time.

    In the Application Navigator in the upper left, click New Application.

    Has existing applications

    From the File main menu or the Application menu:

    1. Select New > Applications.

      The New Gallery opens, where you can select different application components to create.

    2. In the Categories tree, under the General node, select Applications. In the Items pane, select SOA Application and click OK.

    The Create SOA Application wizard appears.

  3. On the Name your application page, you can optionally change the name and location for your project. If this is your first application, from Application Template, select SOA Application. Accept the defaults for the package prefix, and click Next.

  4. On the Name your project page, you can optionally change the name and location for your SOA project. By default, Oracle JDeveloper adds the SOA project technology, the composite.xml that generates, and the necessary libraries to your model project. Click Next.

    The Project SOA Settings page of the Create SOA Application wizard appears.

  5. In the Configure SOA Settings page, click Empty Composite, and click Finish.

  6. Select Save All from the File main menu.

2.2.2 Add a Healthcare Integration Binding Component

You can add a healthcare integration binding component as an exposed service (inbound) or an external reference (outbound) to define the connection to a healthcare system.

Oracle Healthcare supports the following integrations with the Healthcare adapter:

2.2.2.1 Adding a Default (Fabric) Integration Binding Component

You can add a Fabric integration binding component by using the Healthcare Configuration Wizard.

Before you begin:

Before you add a healthcare integration binding component to an Oracle SOA project, make sure you have created the necessary components in the healthcare integration user interface. For example, make sure to create and configure any document definitions and endpoints that you will use in the project.

To add a fabric healthcare integration binding component

  1. From the Component Palette, select SOA.

  2. Scroll to Service Adapters and drag a Healthcare Adapter to either the Exposed Services or External References swim lane.

    • Drag the adapter to Exposed Services for receiving inbound messages.

    • Drag the adapter to External References for sending outbound messages.

    The Healthcare Configuration Wizard appears.

  3. On the Healthcare Configuration Wizard Welcome page, click Next.

    The Service Name page appears.

  4. Enter a name for the healthcare service and click Next as shown in Figure 2-1.

    Figure 2-1 Healthcare Configuration Wizard - Service Name Page

    Description of Figure 2-1 follows
    Description of "Figure 2-1 Healthcare Configuration Wizard - Service Name Page"

    The Healthcare Integration Type page appears.

  5. Select Default and click Next as shown in Figure 2-2.

    Figure 2-2 Healthcare Configuration Wizard - Healthcare Integration Type Page

    Description of Figure 2-2 follows
    Description of "Figure 2-2 Healthcare Configuration Wizard - Healthcare Integration Type Page"

    The Application Server Connection page appears.

  6. Do one of the following:

    • From the AppServer Connection list, select an application server connection and click Next.

    • Click New to create an application server connection. Follow the Create Application Server Connection Wizard.

    When the connection is established, the user name and host name appear along with the name of the SOA Server as shown in Figure 2-3.

    Figure 2-3 Healthcare Configuration Wizard - Application Server Connection Page

    Description of Figure 2-3 follows
    Description of "Figure 2-3 Healthcare Configuration Wizard - Application Server Connection Page"

  7. To verify the connection to the application server, click Test Healthcare, and then click OK on the dialog that appears.

  8. Click Next.

    The Operation page appears as shown in Figure 2-4.

    Figure 2-4 Healthcare Configuration Wizard - Operation Page

    Description of Figure 2-4 follows
    Description of "Figure 2-4 Healthcare Configuration Wizard - Operation Page"

  9. Select Send for outbound messages or select Receive for inbound messages.

  10. Click Next.

    The Document Definition Handling page appears.

  11. Retain the default (to import the schema from Oracle SOA Suite for healthcare integration) or select one of the options on the Advanced tab, as described in Table 2-3 and shown in Figure 2-5.

    Figure 2-5 Healthcare Configuration Wizard - Document Definition Handling Page

    Description of Figure 2-5 follows
    Description of "Figure 2-5 Healthcare Configuration Wizard - Document Definition Handling Page"

  12. Click Next.

    The Document Definition page appears.

  13. Expand the tree to select a document definition as shown in Figure 2-6.

    Figure 2-6 Healthcare Configuration Wizard - Document Definition Page

    Description of Figure 2-6 follows
    Description of "Figure 2-6 Healthcare Configuration Wizard - Document Definition Page"

    Table 2-2 describes additional options on the page.

    Table 2-2 Document Definition Page Options

    Option Description

    Search

    Enter a definition name in the empty field and click the Search icon. Partial strings are matched if you type the beginning of the definition name. Partial strings with wildcards cannot be used.

    Refresh

    Retrieves the document definition list from the healthcare integration server. Refresh after a search to see all document definitions.

    Healthcare Configuration

    Opens a browser to the Oracle SOA Suite for healthcare integration user interface, using the connection specified on the Application Server Connection page. In the healthcare integration user interface, you can create or import a document definition. After you finish those steps, return to this dialog, click Refresh, and select the new document definition.

  14. Click Next.

  15. If you selected a document definition with multiple root elements, the Root Elements page appears. Select a root element to use and click OK.

  16. Click Next and then click Finish.

2.2.2.2 Adding a JMS Integration Binding Component

You can add a Fabric integration binding component by using the Healthcare Configuration Wizard.

Before you begin:

Before you add a healthcare integration binding component to an Oracle SOA project, make sure you have created the necessary components in the healthcare integration user interface. For example, make sure to create and configure any document definitions and endpoints that you will use in the project.

To add a JMS healthcare integration binding component

  1. Repeat steps 1-3 from Section 2.2.2.1, "Adding a Default (Fabric) Integration Binding Component.".

  2. Scroll to Service Adapters and drag a Healthcare Adapter to either the Exposed Services or External References swim lane.

    • Drag the adapter to Exposed Services for receiving inbound messages.

    • Drag the adapter to External References for sending outbound messages.

    The Healthcare Configuration Wizard appears.

  3. On the Healthcare Configuration Wizard Welcome page, click Next.

    The Service Name page appears.

  4. Enter a name for the healthcare service (say hcfp_Inbound to receive inbound messages) and click Next as shown in Figure 2-7.

    Figure 2-7 Healthcare Configuration Wizard - Service Name Page

    Description of Figure 2-7 follows
    Description of "Figure 2-7 Healthcare Configuration Wizard - Service Name Page"

    The Healthcare Integration Type page appears.

  5. Select JMS and click Next as shown in Figure 2-2.

    Figure 2-8 Healthcare Configuration Wizard - Healthcare Integration Type Page

    Description of Figure 2-8 follows
    Description of "Figure 2-8 Healthcare Configuration Wizard - Healthcare Integration Type Page"

    The Application Server Connection page appears.

  6. Repeat steps 6-8 from Section 2.2.2.1, "Adding a Default (Fabric) Integration Binding Component."

  7. In the Operations page, select Send for outbound messages or select Receive for inbound messages. In this case select Receive as shown in Figure 2-9.

    Figure 2-9 Healthcare Configuration Wizard - Operation Page

    Description of Figure 2-9 follows
    Description of "Figure 2-9 Healthcare Configuration Wizard - Operation Page"

  8. Click Next.

    The Document Definition Handling page appears.

  9. Repeat steps 11-16 from Section 2.2.2.1, "Adding a Default (Fabric) Integration Binding Component."

  10. In the JMS Provider page, select Oracle Weblogic JMS from the Oracle Enterprise Messaging Service (OEMS) list and click Next as shown in Figure 2-10.

    Figure 2-10 Healthcare Configuration Wizard - JMS Provider Page

    Description of Figure 2-10 follows
    Description of "Figure 2-10 Healthcare Configuration Wizard - JMS Provider Page"

    The Service Connection page appears.

  11. Select the Application Server connection from the AppServer Connection list (or create a connection by clicking the plus icon and then using the Create Application Server Connection wizard) and click Next.

    The Consume Operation Parameters page appears.

  12. Click the Browse button to display the Select Destination dialog box.

  13. Select the required destination name from the list. In this case, select jms/b2b/B2B_IN_QUEUE (to receive inbound messages) and click OK to go back to the Consume Operation Parameters page. Note that the JNDI Name field is already populated.

  14. Click Next as shown in Figure 2-11.

    Figure 2-11 Healthcare Configuration Wizard - Consume Operations Page

    Description of Figure 2-11 follows
    Description of "Figure 2-11 Healthcare Configuration Wizard - Consume Operations Page"

    Note:

    When you select Receive in the Operation page, the Consume operation is pre-selected and the Consume Operation Parameters page is displayed.

    Likewise, when you select Send in the Operation page, the Produce operation is pre-selected and the Produce Operation Parameters page is displayed. For a Send operation, you need to select the destination of the B2B_OUT_QUEUE as shown in the following figure.

    produce op
    Description of the illustration hc_wizard1_jms6.gif

  15. Click Next and then click Finish.

2.2.2.3 Document Definition Handling in the Healthcare Configuration Wizard

The Healthcare Configuration Wizard lets you associate document definitions from Oracle SOA Suite for healthcare integration with the adapter you are creating. You can specify how the document definition is associated with the Composite and whether the schema definition (XSD) file is required for validation. Table 2-3 lists and describes the possible options for handling the document definition.

Table 2-3 Advanced Document Definition Handling Options

Option Description

Import Schema from Healthcare

Imports the schema from Oracle SOA Suite for healthcare integration. This option copies the XSD file to the project directory to make it available at runtime. If there are any dependent files, you need to copy them manually to the project, maintaining the same directory structure.

Refer Schema in HL Repository

Uses an existing metadata service (MDS) connection or allows you to create a new connection to use. Select an existing service or create a new MDS connection. If you create a new MDS connection, the MDS Connection Wizard appears so you can define a connection. This connection is needed to access the Oracle SOA Suite for healthcare integration repository. When you select a document definition, a URL is generated to link to the MDS.

The selected application server connection refers to a specific Oracle SOA Suite for healthcare integration instance. The MDS connection used by the instance must match the selected MDS connection to avoid inconsistent document definitions.

When referring to a schema in an Oracle SOA Suite for healthcare integration repository, an MDS connection is required only for referring to a schema in a remote MDS, but not if the schema is referred to within the local shared MDS repository.

Browse Resource Schema

Browse for a schema using the SOA Resource Browser. Selecting this option and clicking the Browse Schema icon opens the Type Chooser dialog. Expand the tree, select a type, and return to the Document Definition Handling page.

Opaque

Handles any type of data (for example, positional flat file) when the content is passed through in base-64 encoding. You do not need to specify a schema.

anyType

Handles any type of XML data. You do not need to specify a schema.

2.2.3 Add Service Components

Once you create the SOA application and project, you can add the service components that implement the business logic and processing rules for the application.

To add service components to a project

  1. From the Component Palette, select SOA.

  2. From the Service Components list, drag a component into the designer.

    Figure 2-12 shows a BPEL process just added to the designer.

    Figure 2-12 BPEL Process in a Composite Application

    Description of Figure 2-12 follows
    Description of "Figure 2-12 BPEL Process in a Composite Application"

    A dialog specific to the selected service component appears. Table 2-4 describes the available dialogs.

    Table 2-4 Starting Service Component Editors

    Dragging This Service Component... Invokes The...

    BPEL Process

    Create BPEL Process dialog to create a BPEL process that integrates a series of business activities and services into an end-to-end process flow.

    Business Rule

    Create Business Rules dialog to create a business decision based on rules.

    Human Task

    Create Human Task dialog to create a workflow that describes the tasks for users or groups to perform as part of an end-to-end business process flow.

    Mediator

    Create Mediator dialog to define services that perform message and event routing, filtering, and transformations.

  3. Configure the settings for the service component. For help with a service component dialog, click Help or press F1.

  4. When configuring the component, define any of the normalized message properties listed in Table 2-5. hc.fromEndpoint and hc.toEndpoint must be defined and must correspond to endpoints defined in the healthcare integration user interface.

    Table 2-5 Healthcare Integration Normalized Message Properties

    hc.documentDefinitionName

    The name of the document definition. For example, ADT_A03_def.

    hc.documentProtocolName

    The name of the protocol associated with the document definition. For example, HL7.

    hc.documentProtocolVersion

    The version of the above protocol associated with the document definition. For example, 2.3.1 for an HL7 document.

    hc.documentTypeName

    The document type associated with the document definition. For example, ADT_A03 for an HL7 document.

    hc.fromEndpoint

    The name of the endpoint for the sending application. This name is defined in the endpoint configuration in the healthcare integration user interface.

    hc.messageId

    A unique message ID.

    hc.messageType

    The message type value can be one of the following options:

    • 1 (indicates a request)

    • 2 (indicates a response)

    • 9 (indicates a functional acknowledgment)

    hc.replyToMessageId

    The message ID to which the sending message replies.

    hc.toEndpoint

    The name of the endpoint for the receiving application. This name is defined in the endpoint configuration in the healthcare integration user interface.

  5. When you are done configuring the settings, click OK.

  6. Select Save All from the File main menu.

    See Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite for more information about adding service components.