Oracle® Fusion Middleware

Healthcare Integration User's Guide for Oracle SOA Suite

11g Release 1 (11.1.1.7)

E23486-04

May 2013

Documentation for developers that describes how to create and configure Oracle SOA Suite for healthcare integration applications that map and transmit information between disparate healthcare systems. This document also describes how to monitor and manage deployed Oracle Healthcare applications.

Oracle Fusion Middleware Healthcare Integration User's Guide for Oracle SOA Suite, 11g Release 1 (11.1.1.7)

E23486-04

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Primary Author: Oracle Corporation

Contributing Author: Oracle Corporation

Contributor:  Oracle SOA Suite and Oracle Healthcare development, product management, and quality assurance teams

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Contents

Preface

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

What's New in This Guide for Release 11.1.1.7

1 Getting Started with Oracle SOA Suite for Healthcare Integration

- 1.1 Introduction to Oracle SOA Suite for Healthcare Integration

- 1.1.1 Oracle SOA Suite for Healthcare Integration Components

- 1.1.2 Management and Monitoring Tools

- 1.1.3 Oracle SOA Suite and Healthcare Integration

- 1.1.4 Oracle SOA Suite for Healthcare Integration Metadata

- 1.1.5 Security

- 1.2 What You Need to Get Started with Oracle SOA Suite for Healthcare Integration

- 1.3 Logging in to Oracle SOA Suite for Healthcare Integration

- 1.3.1 Finding Port Information

- 1.4 Using the Oracle SOA Suite for Healthcare Integration User Interface

- 1.4.1 Designer

- 1.4.1.1 Configuring Documents

- 1.4.1.2 Configuring Endpoints

- 1.4.1.3 Configuring Callouts

- 1.4.1.4 Configuring Mapsets

- 1.4.1.5 Configuring Internal Delivery Channels

- 1.4.1.6 Setting runtime and User Interface Properties

- 1.4.1.7 Managing Repository Data

- 1.4.1.8 Configuring Alerts and Contacts

- 1.4.2 Dashboards

- 1.4.3 Reports

- 1.5 Accessibility Options

- 1.5.1 Enabling Accessibility Features in Oracle B2B

2 Working with the Oracle Healthcare Adapter

- 2.1 Introduction to the Oracle Healthcare Adapter

- 2.1.1 The Healthcare Configuration Wizard

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

- 2.2 How to Use Healthcare Adapters in a SOA Composite Application

- 2.2.1 Create a SOA Application and Project

- 2.2.2 Add a Healthcare Integration Binding Component

- 2.2.2.1 Adding a Default (Fabric) Integration Binding Component

- 2.2.2.2 Adding a JMS Integration Binding Component

- 2.2.2.3 Document Definition Handling in the Healthcare Configuration Wizard

- 2.2.3 Add Service Components

3 Working with Document Types and Protocols

- 3.1 Introduction to Document Protocols

- 3.1.1 What You May Need to Know About the Document Hierarchy

- 3.2 Using the Custom Document Protocol

- 3.2.1 What You May Need to Know About Custom Document Version Parameters

- 3.2.2 What You May Need to Know About Custom Document Definition Parameters

- 3.2.2.1 How to Configure the XPath Expression for a Custom XML Document

- 3.3 Using the HL7 Document Protocol

- 3.3.1 What You May Need to Know About HL7 Document Version Parameters

- 3.3.2 What You May Need to Know About HL7 Document Type Parameters

- 3.3.3 What You May Need to Know About HL7 Document Definition Parameters

- 3.3.4 What You May Need to Know About Using HL7

- 3.4 Creating Document Definitions

- 3.5 Deleting a Document Definition

4 Working with Endpoints

- 4.1 Introduction to Endpoints

- 4.2 Creating Endpoints

- 4.2.1 Configuring Channels in an Endpoint with Single-Directional Protocols

- 4.3 Associating an Endpoint with a Document

- 4.4 Enabling Sequencing for an MLLP Endpoint

- 4.5 Deleting an Endpoint

- 4.6 Working with the Endpoint Window

5 Working with Callouts

- 5.1 Introduction to Callouts

- 5.1.1 Creating a Callout Library JAR File

- 5.2 Types of Callouts

- 5.2.1 Transport Callouts

- 5.2.2 Document Callouts

- 5.3 Creating a Callout

- 5.4 Including a Callout in an Endpoint

6 Working with Mapsets

- 6.1 Introduction to Mapsets

- 6.1.1 About Mapsets

- 6.1.2 Predefined and Custom Mapsets

- 6.2 Creating a Map File

- 6.3 Using Mapsets in the Oracle B2B Console

- 6.3.1 Creating a Mapset in the Oracle B2B Console

- 6.3.2 Associating a Mapset with a Trading Partner Agreement

- 6.3.3 Deleting a Mapset in the Oracle B2B Console

- 6.4 Using Mapsets in Oracle SOA Suite for Healthcare Integration

- 6.4.1 Creating a Mapset in the Healthcare Integration User Interface

- 6.4.2 Associating a Mapset with an Endpoint

- 6.4.3 Deleting a Mapset in the Healthcare Integration User Interface

7 Working with Internal Delivery Channels

- 7.1 Introduction to Internal Delivery Channels

- 7.2 Creating Internal Delivery Channels

- 7.3 Enabling an Internal Delivery Channel

- 7.4 Deleting an Internal Delivery Channel

- 7.5 Correlating Messages Using JMS Queues

8 Working with Dashboards

- 8.1 Introduction to Dashboards

- 8.2 Working with System Dashboard

- 8.2.1 Viewing System Data by Using Different Sections of the System Dashboard

- 8.3 Creating and Configuring Dashboards

- 8.3.1 Creating a Dashboard

- 8.3.2 Selecting a Default Dashboard

- 8.3.3 Configuring an Existing Dashboard

- 8.3.4 Refreshing a Dashboard and Setting the Auto-Refresh Rate

- 8.3.5 Deleting a Dashboard

- 8.4 Viewing Information in Dashboards

- 8.4.1 Viewing Endpoint Summary Information in a Dashboard

- 8.4.2 Viewing Detailed Endpoint Information in a Dashboard

- 8.4.3 Configuring an Endpoint from a Dashboard

- 8.5 Working with Sequenced Messages

- 8.6 Viewing Endpoint Error Messages

9 Working with Reports

- 9.1 Introduction to Reports

- 9.1.1 About the Message Report Filter Customizers

- 9.1.2 About Resubmitting Messages

- 9.1.3 Important Note About Clustered Environments

- 9.2 Creating and Configuring Reports

- 9.2.1 Creating Business Message Reports

- 9.2.2 Creating Wire Message Reports

- 9.2.3 Creating Application Message Reports

- 9.2.4 Specifying a Default Report

- 9.2.5 Configuring Reports

- 9.2.6 Refreshing a Report and Setting the Auto-Refresh Rate

- 9.2.7 Deleting Reports

- 9.3 Viewing Reports and Report Information

- 9.3.1 Viewing a Business Message Instance

- 9.3.2 Viewing a Wire Message

- 9.3.3 Viewing an Application Message

- 9.3.4 Viewing the Flow Trace in Oracle Enterprise Manager

- 9.3.5 Viewing Overview Information for Multiple Messages

- 9.4 Working with Reports for Unassociated Messages

- 9.4.1 Working with Unassociated Wire Messages

- 9.4.1.1 Creating Unassociated Wire Message Reports

- 9.4.1.2 Viewing an Unassociated Wire Message

- 9.4.2 Working with Unassociated Application Messages

- 9.4.2.1 Creating Unassociated Application Message Reports

- 9.4.2.2 Viewing an Unassociated Application Message

- 9.5 Working with Error Messages

- 9.5.1 Viewing an Error Message

- 9.5.2 Resubmitting Messages

- 9.6 Purging Messages from the Repository

10 Configuring Alerts and Contacts

- 10.1 Overview of Alerts and Contacts

- 10.2 Configuring Contacts and Alerts

- 10.2.1 Deploying the SMPP Driver for SMS Notifications

- 10.2.2 Configuring Workflow Notification Properties

- 10.2.3 Configuring Oracle User Messaging Service

- 10.2.4 Defining Alerts and Contacts

- 10.3 Viewing the Alerts Assigned to a Contact

- 10.4 Removing Contacts

- 10.5 Viewing a History of Alerts Sent

11 Viewing the Healthcare User Audit Trail

- 11.1 Introduction to the Audit Trail

- 11.1.1 Oracle SOA Suite for Healthcare Integration Auditing Options

- 11.1.2 Using Filter Conditions for Auditing

- 11.2 Configuring the Healthcare Integration Audit Trail

- 11.3 Viewing User Audit Logs

12 Managing the Repository

- 12.1 Introduction to the Oracle SOA Suite for Healthcare Integration Repository

- 12.1.1 Repository Maintenance

- 12.1.2 What Occurs During the Import or Export Process

- 12.1.3 About the Exported File

- 12.1.4 What Occurs During the Purging Process

- 12.1.5 Purging Control Numbers

- 12.2 Importing and Exporting the Design-Time Repository

- 12.3 Purging Repository Data

13 Configuring System Settings

- 13.1 Configuring the Runtime Settings

- 13.2 Configuring the User Interface Settings

14 Provisioning Users

- 14.1 Creating Users

- 14.2 Adding Users

- 14.3 Editing, Viewing, and Deleting User Provisioning

- 14.4 Provisioning Users for Payload Viewing

- 14.5 Reverting User Provisioning Changes

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

- 15.1 Introduction to Web-Service-Based Message Exchange

- 15.2 Exchanging SOAP-Based Service Messages with Custom WSDL

- 15.2.1 Exchanging Outbound SOAP-Based Messages

- 15.2.2 Exchanging Inbound SOAP-Based Messages

- 15.3 Sending Custom SOAP Headers

- 15.4 Sample Request-Reply Scenarios

- 15.4.1 Outbound Synchronization: Composite

- 15.4.2 Inbound Synchronization: Composite

- 15.4.3 Outbound Synchronization: JMS Queues

- 15.4.4 Inbound Synchronization: JMS Queues

16 Oracle Healthcare Command-Line Tools

- 16.1 Prerequisites for Running the Command-line Tools

- 16.2 Purging Data

- 16.3 Importing Data

- 16.4 Exporting Data

- 16.5 Batching Operations

- 16.6 Resubmitting a Message

- 16.7 Scheduling Endpoint Downtime

- 16.8 Updating Endpoints

- 16.9 Deleting Endpoints

A Back-End Applications Interface

- A.1 Mapping SCA Normalized Message Properties

- A.2 Normalized Message Properties

B Creating Endpoints with Different Transport Protocols

- B.1 Creating Bidirectional Endpoints

- B.1.1 Creating an MLLP 1.0 Endpoint

- B.1.2 Creating an MLLP 2.0 Endpoint

- B.1.3 Creating a Generic TCP Endpoint

- B.1.4 Creating an HLLP Endpoint

- B.2 Creating Single-Directional Endpoints

- B.2.1 Creating a File Endpoint

- B.2.2 Creating an FTP Endpoint

- B.2.3 Creating an JMS Endpoint

- B.2.3.1 Retrieving Document Information from JMS Headers

- B.2.4 Creating an SFTP Endpoint

C Managing Message Sequencing

- C.1 Overview of Sequenced Message Management

- C.2 Java Methods for Managing Sequenced Messages

- C.2.1 Listing Endpoints With States

- C.2.2 Listing Pending Sequenced Messages

- C.2.3 Discarding Messages

- C.2.4 Reprocessing a Message

- C.2.5 Pausing and Resuming and Endpoint

- C.3 Command-Line Tools for Managing Sequenced Messages

- C.3.1 Prerequisites for Running Command-Line Tools

- C.3.2 Listing Endpoints With States

- C.3.3 Listing Pending Sequenced Messages

- C.3.4 Discarding Messages

- C.3.5 Reprocessing Messages

- C.3.6 Pausing and Resuming an Endpoint

D Implementing MLLP with High Availability

- D.1 Introduction to Healthcare Integration High Availability

- D.1.1 High Availability Processing

- D.1.2 Front-End Failover

- D.1.3 Notion of Active

- D.1.4 Unit of Order (UOO)

- D.1.5 External Dependencies

- D.1.6 Additional Resources

- D.2 Enabling MLLP High Availability in Oracle SOA Suite for Healthcare Integration

E Batching HL7 Messages

- E.1 Introduction to HL7 Message Batching

- E.1.1 Batching with File Header (FHS)

- E.1.2 Batching with Batch Header (BHS)

- E.1.3 Batching with Message Header (MSH)

- E.1.4 Sending Functional Acknowledgments When Batching

- E.1.5 Standard Mode of Batching

- E.1.6 Custom Mode of Batching

- E.1.7 Commandline Tools for Batching

F Configuration for Functional Acknowledgment 999

- F.1 Introduction

- F.2 Function Acknowledgement 999: Use Cases

- F.2.1 Use Case 1

- F.2.2 Use Case 2

- F.2.3 Use Case 3

G Audit Reference for Oracle SOA Suite for Healthcare Integration

- G.1 About Custom and Standard Audit Reports

- G.2 Audit Events in Oracle SOA Suite for Healthcare Integration

Index

Preface

This guide describes how to use Oracle SOA Suite for healthcare integration.

Audience

Oracle Fusion Middleware Healthcare Integration User's Guide for Oracle SOA Suite is intended for healthcare organizations that need to exchange healthcare data, and want to design, deploy, monitor, and manage healthcare integration applications.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Related Documents

For information about Oracle SOA Suite products, see the following:

- Oracle Fusion Middleware User's Guide for Oracle B2B

- Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite

- Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite

- Oracle Fusion Middleware Installation Guide for Oracle SOA Suite and Oracle Business Process Management Suite

- Oracle Fusion Middleware User's Guide for Technology Adapters

- Oracle Fusion Middleware Performance and Tuning Guide

For information about the Java API documentation (Javadoc), see the following:

- Oracle Fusion Middleware B2B Callout Java API Reference

- Oracle Fusion Middleware B2B Instance Message Java API Reference

Conventions

The following text conventions are used in this document:

Convention

Meaning

boldface

Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace

Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

What's New in This Guide for Release 11.1.1.7

This guide has been updated in several ways. The following table lists the sections that have been added or changed.

For a list of known issues (release notes), see the "Known Issues for Oracle SOA Products and Oracle AIA Foundation Pack" at http://www.oracle.com/technetwork/middleware/docs/soa-aiafp-knownissuesindex-364630.html.

Sections

Changes Made

February 2013

May 2013

Chapter 1, "Getting Started with Oracle SOA Suite for Healthcare Integration"

Bug fixes

X

Chapter 4, "Working with Endpoints"

Bug fixes

X

Chapter 8 Working with Dashboards

Section 8.1, "Introduction to Dashboards"

Section updated to include the different modes of viewing a dashboard.

X

Section 8.2, "Working with System Dashboard"

Section added on working with the System Dashboard.

X

Chapter 9 Working with Reports

Section 9.1, "Introduction to Reports"

Section updated to describe the different Healthcare-specific reports.

X

Section 9.4, "Working with Reports for Unassociated Messages"

Section added to describe the various reports for unassociated messages

X

Chapter 14, "Provisioning Users"

Chapter added to describe the basic security provided by Oracle Healthcare by using the concept of user provisioning.

X

Chapter 15, "Enabling Web-Service-Based Message Exchange in Oracle Healthcare"

Chapter added to describe Web service based message exchange in Oracle Healthcare.

X

Chapter 16, "Oracle Healthcare Command-Line Tools"

Chapter added to cover the different command-line tools provided by Oracle Healthcare.

X

Appendix G, "Audit Reference for Oracle SOA Suite for Healthcare Integration"

Appendix added to cover the audit reference in Oracle Healthcare.

X

1 Getting Started with Oracle SOA Suite for Healthcare Integration

This chapter provides an overview of the Oracle SOA Suite for healthcare integration, which provides a Web-based user interface for creating applications to transmit and transform data between various healthcare systems. The user interface also provides monitoring and management capabilities for the messages shared between those systems.

This chapter contains the following topics:

- Section 1.1, "Introduction to Oracle SOA Suite for Healthcare Integration"

- Section 1.2, "What You Need to Get Started with Oracle SOA Suite for Healthcare Integration"

- Section 1.3, "Logging in to Oracle SOA Suite for Healthcare Integration"

- Section 1.4, "Using the Oracle SOA Suite for Healthcare Integration User Interface"

- Section 1.5, "Accessibility Options"

1.1 Introduction to Oracle SOA Suite for Healthcare Integration

Oracle SOA Suite for healthcare integration utilizes several features of Oracle SOA Suite to help you design, create, and manage applications that process healthcare data. Oracle SOA Suite for healthcare integration includes a Web-based user interface where you can create and configure healthcare integration applications, as well as monitor and manage the messages processed through those applications. You can also use the Oracle Document Editor to create and configure document definitions, which define message structures. The Oracle SOA Suite for healthcare integration user interface provides additional features, such as support for additional messaging protocols and the ability to create and manage endpoints, manage documents, create mapsets, and create Java callouts.

1.1.1 Oracle SOA Suite for Healthcare Integration Components

A healthcare integration application includes several components that define how messages are received, processed, and transmitted. The components that make up a healthcare integration application include the following. Document definitions and endpoints are required components for a healthcare integration application.

- Document Definitions: Use document definitions to define the structure of the messages that are used in a healthcare transaction. Predefined templates are provided for HL7 messages when you install the Oracle Document Editor. Document definitions are categorized by protocol, version, and type.

- Endpoints: An endpoint brings together all of the above components for one external system. The endpoint defines whether messages are being sent or received by Oracle SOA Suite for healthcare integration, the transport protocol, acknowledgment handling, and whether messages are validated or translated. Endpoints are associated with document definitions and, optionally, internal delivery channels, callouts, mapsets, and SOA Suite composite applications.

- Mapsets: Use mapsets to define the transformation from one native format to another, bypassing the step of translating to XML and back. For example, a mapset can map fields from a HIPAA 4010 document directly to a HIPAA 5010 document. A mapset includes source and target document definitions, and a file that defines the mapping.

- Callouts: Use callouts to incorporate your own Java code into a healthcare integration application.

- Internal Delivery Channels: Use internal delivery channels when you want the healthcare integration application to receive messages from or send messages to a JMS topic or queue.

1.1.2 Management and Monitoring Tools

Once you create and deploy a healthcare integration application, you can monitor and manage the messages processed through the application using the Oracle SOA Suite for healthcare integration Web-based user interface. The reporting feature allows you to view a list of messages processed and then to drill deeper into message content, protocol information, and so on. You can also resubmit messages or configure automatic retries, configure partner downtimes, and purge selected messages from the metadata repository.

The dashboard feature allows you to view a summary of messages sent for each running endpoint. You can also drill down deeper to view the volume of messages sent, received and errored for the specified time period. This information is further categorized by document type. You can create custom dashboards and reports based on a variety of criteria. Several default reports are already provided for you.

1.1.3 Oracle SOA Suite and Healthcare Integration

Oracle SOA Suite for healthcare integration provides SOA features and components that extend business processes to healthcare systems. When Oracle SOA Suite for healthcare integration is used in a SOA composite application, you can model an end-to-end business process integration.

Oracle SOA Suite provides a complete set of service infrastructure components for designing, deploying, and managing composite applications. The multiple technology components of a composite application share common capabilities, including a single deployment and management model and tooling, end-to-end security, and unified metadata management.

In a SOA implementation, Oracle SOA Suite for healthcare integration functions as a binding component, with network protocols and services that enable message sending and receiving. As a service (inbound), the SOA composite application receives messages from Oracle SOA Suite for healthcare integration. As a reference (outbound), the SOA composite application passes a message to Oracle SOA Suite for healthcare integration, which in turn sends the message to external systems.

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

1.1.4 Oracle SOA Suite for Healthcare Integration Metadata

Oracle SOA Suite for healthcare integration instance data is stored and managed within the SOAINFRA schema of your database. Metadata for design-time and configuration is stored and managed through Metadata Services (MDS), available in Oracle Fusion Middleware. For more information about MDS, see Oracle Fusion Middleware Administrator's Guide

Due to the storage of healthcare integration data in the metadata repository, it is possible that the tablespace will become full. If this occurs, increase the size of the tablespace. Increasing the size of the redo log file also helps to improve performance when importing large configurations. A larger log file requires more space but reduces the need for applications to retry the operation.

1.1.5 Security

Security for Oracle SOA Suite for healthcare integration is handled through Oracle WebLogic Server. You can create user accounts in WebLogic Server for people who need to view and modify components in Oracle SOA Suite for healthcare integration and then provision those accounts using the Oracle SOA Suite for healthcare integration console. In order to have edit privileges on the healthcare integration user interface, users must be granted either the Administrator or Monitor role in Oracle SOA Suite for healthcare integration.

1.2 What You Need to Get Started with Oracle SOA Suite for Healthcare Integration

After installing Oracle SOA Suite, you need to perform the following postinstallation tasks before working with Oracle SOA Suite for healthcare integration:

1. Open a command prompt and set the following environment variables:

setenv ANT_HOME <Middleware_HOME>/modules/org.apache.ant_1.7.1/
setenv PATH=$ANT_HOME/bin:$PATH
setenv JAVA_HOME <Middleware_HOME>/<jrockit_install_directory>
setenv PATH=$JAVA_HOME/bin:$PATH

2. Download the Healthcare library (ofm_healthcare_lib_generic_11.1.1.7.0_disk1_1of1.zip) from Oracle Technology Network (OTN) or eDelivery that contains:

- StdMultiSetupInstOracle.exe for Windows

- StdMultiSetupInstOracle.tar.gz for other operating systems

Based on the operating system, copy the library to the following location

<Middleware_HOME>/<SOA_HOME>/soa/thirdparty/healthcare/stdlibrary/

3. In a command prompt, run the following commands:

cd <Middleware_HOME>/<SOA_HOME>/bin
ant -f ant-soahc-postinstall.xml

4. Enter the following details when prompted by the ant command to complete the postinstallation process:

- Weblogic server user-name (default weblogic)

- Weblogic server password

- Weblogic server hostname (default localhost)

- Admin Server Port (default 7001)

- Managed Server Port (default 8001)

- Admin Server Name (default AdminServer)

- Weblogic Server deploy target (default soa_server1)

- Weblogic Server platform (default linux64)

- Database type (default oracle)

- Database URL

- SOA Schema username

- SOA Schema password

5. Restart both the Admin Server and the Managed Server.

In addition to performing the postinstallation tasks, you need to install:

- Oracle Document Editor

- Oracle JDeveloper

Use the standards-based templates of Oracle Document Editor to create guideline files. Then, use Healthcare Adapter binding component in Oracle JDeveloper to create and then deploy a healthcare composite, as shown in Figure 1-1.

Figure 1-1 Oracle JDeveloper: A SOA Composite Application with a Healthcare Binding Component

See the following for more information:

- Oracle Fusion Middleware Installation Guide for Oracle SOA Suite and Oracle Business Process Management Suite for information on installing Oracle SOA Suite for healthcare integration as part of Oracle SOA Suite

- Oracle Document Editor Help menu

- Oracle JDeveloper Help menu

- Chapter 2, "Working with the Oracle Healthcare Adapter"

1.3 Logging in to Oracle SOA Suite for Healthcare Integration

These instructions assume that you have installed Oracle SOA Suite, which includes Oracle SOA Suite for healthcare integration. See Oracle Fusion Middleware Installation Guide for Oracle SOA Suite and Oracle Business Process Management Suite for more information.

Use a supported Web browser:

- Mozilla Firefox 2.0, 3.0 and 3.5 or later

- Apple Safari 3.2, 4.0, and 5.0

- Google Chrome 1.0 or later

- Microsoft Internet Explorer 8 and 9 (with Compatibility View turned off)

To log on to Oracle SOA Suite for healthcare integration:

1. Open a supported Web browser and go to:

http://host_name:port_number/healthcare

where:

- host_name is the name of the host on which Oracle SOA Suite is installed. (In a cluster environment, the host_name can be the front end load balancer.)

- port_number is the port number used by the Managed Server to listen for regular HTTP (non-SSL) or HTTPS (SSL) connections. (In a cluster environment, the port_number can be the router port.)
See Section 1.3.1, "Finding Port Information," for more information.

- /healthcare accesses the healthcare integration user interface.

2. On the log-in page, enter the following:

For This Field...

Do...

Username

Enter the default administrator user name.

Password

Use the administrator password from your Oracle Fusion Middleware 11g installation.

3. Click Login.

1.3.1 Finding Port Information

You can find port number information in the following ways:

- From Oracle WebLogic Server Administration Console:

1. Log on to the console.

2. In the Domain Structure pane, shown in Figure 1-2, expand Environment and click Servers.

Figure 1-2 Domain Structure Nodes in Oracle WebLogic Server Administration Console

3. Note the Listen Port column for your server.

- Or from MW_HOME/user_projects/domains/your_domain_name/config/config.xml

<server>
<name>soa_server1</name>
<ssl>
<name>soa_server1</name>
<listen-port>8002</listen-port>
</ssl>
<machine>LocalMachine</machine>
<listen-port>8001</listen-port>
<listen-address/>
</server>

1.4 Using the Oracle SOA Suite for Healthcare Integration User Interface

Healthcare activities are grouped as follows:

- Designer

- Dashboards

- Reports

1.4.1 Designer

Use the Configuration subtab of the Designer tab, shown in Figure 1-3, to configure document protocols, endpoints, callouts, mapsets, and the Administration subtab to modify runtime and user interface settings and internal delivery channel settings, and to import, export, and purge metadata.

Figure 1-3 Designer Tab

1.4.1.1 Configuring Documents

Using the Document Protocol folder in the Configuration tab, you can create, modify, or delete document protocols, document protocol version, document type, and document definition as shown in Figure 1-4. These document definitions can later be associated with endpoints.

Figure 1-4 The Document Protocol Folder

Note:

You can create documents with Oracle Document Editor, or you can use a pre-seeded export zip file that contains already created document definitions by using the Import/Export feature available in the Administration tab.

See Chapter 3, "Working with Document Types and Protocols" for more information on documents and document protocols.

1.4.1.2 Configuring Endpoints

Endpoints are locations from where messages are sent or received. An endpoint can be a URL, folders, or path, among others. You can use the Endpoints folder in the Configuration tab to create, modify, or delete endpoints, as well as associate an endpoint with document definitions.

Figure 1-5 displays a sample endpoint.

Figure 1-5 Sample Endpoint

See Chapter 4, "Working with Endpoints" for more information on endpoints.

1.4.1.3 Configuring Callouts

Callouts are used for customizing message processing. For example, callouts can be used to update a message or convert the message format of a remote endpoint to another format. You can use the Callout folder in the Configuration tab to create, modify, or delete callouts.

Figure 1-6 displays a sample callout.

Figure 1-6 Sample Callout

See Chapter 5, "Working with Callouts" for more information on callouts.

1.4.1.4 Configuring Mapsets

Mapsets enable you to directly transform one native data format to another native format. You can use the Mapset folder in the Configuration tab to create, modify, or delete mapsets.

Figure 1-7 displays a sample mapset.

Figure 1-7 Sample Mapset

See Chapter 6, "Working with Mapsets" for more information on mapsets.

1.4.1.5 Configuring Internal Delivery Channels

An internal delivery channel defines how a message is delivered from Oracle SOA Suite for healthcare integration to a JMS topic or queue to make it available to internal healthcare systems, or how a message that was sent to a topic or queue from an external system is delivered to Oracle SOA Suite for healthcare integration. It defines the connection information, the transport protocol, and so on. You can use the Internal Delivery Channel on the Administration tab to create and configure internal delivery channels.

Figure 1-8 displays a sample internal delivery channel.

Figure 1-8 Sample Internal Delivery Channel

See Chapter 7, "Working with Internal Delivery Channels" for more information on internal delivery channels.

1.4.1.6 Setting runtime and User Interface Properties

Oracle SOA Suite for healthcare integration enables you to modify runtime and user interface properties. Use the Runtime and UI icons available under the Settings folder in the Administration tab for modifying these properties:

- runtime settings: Double-click the Runtime icon to display the Runtime Settings page, where you can modify runtime parameters related to functional acknowledgment, large payloads, callout directory names, and dispatcher counts.
Figure 1-9 displays the Runtime Settings page.

Figure 1-9 The Runtime Settings Page

- User Interface settings: Double-click the UI icon to display the User Interface Settings page where you can specify the following:

- Time slider periods: Enables you to select up to nine time slider periods to be made available for Time Range selection in the Dashboard Summary page

- Dashboard Summary settings: Enables you to specify historical time range to show statistics for Dashboards, number of columns to use in the endpoint status grid, and auto-refresh interval (in seconds) for the Dashboard Summary view

- Endpoint settings: Enables you to specify display style for Document Type statistics (Gauge or Table), number of columns to use in Gauges grid, and auto-refresh interval (in seconds) for the Endpoint Detailed view of the Dashboard

- Reports settings: Enables you to specify auto-refresh interval (in seconds) for reports, number of rows per page to be shown in the Reports Result table, and display of message payload

Figure 1-10 displays a sample User Interface Settings page.

Figure 1-10 The User Interface Settings Page

See Chapter 13, "Configuring System Settings" for more information on runtime and user-interface settings.

1.4.1.7 Managing Repository Data

The Repository Management page allows you to export Oracle SOA Suite for healthcare integration repository data and to import other exported files, such as document definitions, mapsets, or other healthcare-related repository data. You can also purge design-time and runtime metadata.

Figure 1-11 Repository Management Page

See Chapter 12, "Managing the Repository" for more information on managing the Oracle SOA Suite for healthcare integration repository.

1.4.1.8 Configuring Alerts and Contacts

The Alerts and Contacts page allows you to define a list of contacts and then associate each contact with the events of which they should be notified. An alert can be sent for a variety of runtime and design-time events.

Figure 1-12 Alerts and Contacts Page

See Chapter 10, "Configuring Alerts and Contacts" for more information on managing alerts and contacts.

1.4.2 Dashboards

Clicking the Dashboards tab displays the Dashboards page. When you open the Dashboards page for the first time, the following options are displayed as shown in Figure 1-13:

- Set Up Default Dashboard to Show Whenever Tab Is Selected: Specify the dashboard name that will be displayed as a default when you open the Dashboards page

- Open or Edit Existing Dashboards: Open or edit available dashboards

- Create Dashboard: Create a new dashboard

- Delete Existing Dashboards: Delete a dashboard

Figure 1-13 The Dashboard Page

Subsequent access to the Dashboards page displays the default dashboard page that you have specified earlier. On this page, you can see all the endpoints associated with a particular dashboard. In addition, the page enables you to specify whether to show all endpoints regardless of their state, number of columns in which the endpoints are displayed, and auto-refresh interval for the dashboard. The page also provides a Dashboard Editor button that enables you to modify the dashboard name, as well as select the required endpoints for the dashboard from a list of available endpoints.

Each endpoint provides options that enable you to view the endpoint properties and also to configure the endpoint. Moving the mouse cursor over the information icon of a particular endpoint displays the endpoint properties. When you click the Configure This Endpoint icon, which is located next to the information icon, you are redirected to the relevant endpoint edit page.

You can click the icon on upper right corner of the endpoint window to view the details.

Figure 1-14 displays a sample Dashboard page.

Figure 1-14 Sample Dashboard

See Chapter 8, "Working with Dashboards" for more information on dashboards.

1.4.3 Reports

Clicking the Reports tab displays the Reports page. The Reports page lists all the different types of inbound and outbound messages (wire, business, and application) pertaining to all the endpoints. In addition, the page enables you to:

- Navigate through the available messages

- Specify the number of messages to be displayed per page

- Open a message filter editor to create business message report filters

- Specify auto-refresh interval

When you click a message from the list the lower pane displays all the different message types for the selected message, which are Wire Message, Business Message, and Application Message. Clicking each of the message type displays the details.

Figure 1-15 displays a sample report containing a list of the messages, message type details, and the Business Message Report Editor.

Figure 1-15 Sample Report

See Chapter 9, "Working with Reports" for more information on reports.

1.5 Accessibility Options

This section describes accessibility options available with Oracle B2B.

1.5.1 Enabling Accessibility Features in Oracle B2B

Oracle B2B provides the screen reader option, which enables your screen reader to access and read all components of the application.

To enable screen reader:

1. Click the Enable screen reader mode link in the top right corner.

2. The following confirmation message appears: This will enable screen reader mode for the current session. Do you want to continue?

3. Click Yes to confirm.

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:

- Section 2.1, "Introduction to the Oracle Healthcare Adapter"

- Section 2.2, "How to Use Healthcare Adapters in a SOA Composite Application"

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:

- Create and enable the healthcare integration endpoints (described inChapter 4, "Working with Endpoints.")

- Section 2.2.1, "Create a SOA Application and Project"

- Section 2.2.3, "Add Service Components"

- Section 2.2.2, "Add a Healthcare Integration Binding Component"

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:

- Section 2.2.2.1, "Adding a Default (Fabric) Integration Binding Component"

- Section 2.2.2.2, "Adding a JMS Integration Binding Component"

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

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

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

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

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

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

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

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

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

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

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

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.

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

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.

3 Working with Document Types and Protocols

This chapter provides information about the document protocols and message types supported by Oracle SOA Suite for healthcare integration, and describes how to work with document definitions in the healthcare integration user interface.

This chapter contains the following topics:

- Section 3.1, "Introduction to Document Protocols"

- Section 3.2, "Using the Custom Document Protocol"

- Section 3.3, "Using the HL7 Document Protocol"

- Section 3.4, "Creating Document Definitions"

- Section 3.5, "Deleting a Document Definition"

3.1 Introduction to Document Protocols

Oracle SOA Suite for healthcare integration supports the following document protocols:

- Custom

- HL7 V2.x

Figure 3-1 displays the document protocols supported in Oracle SOA Suite for healthcare integration.

Figure 3-1 Oracle SOA Suite for healthcare integration Document Protocols

As part of the document definition, you provide the document guideline files, which are typically created in Oracle Document Editor. (For Custom documents, you cannot use Oracle Document Editor and validation of documents is also not possible.) If validation is enabled, then, at runtime, the payload must conform to the document definition file type you use.

3.1.1 What You May Need to Know About the Document Hierarchy

You can think of a document protocol as a hierarchy, as shown in Figure 3-2.

Figure 3-2 Document Hierarchy

A document protocol can consist of multiple document protocol versions. A document protocol version can consist of multiple document types. A document type can consist of multiple document definitions. Typically, you start with one document definition and customize it for different endpoints.

Figure 3-3 shows a document protocol hierarchy as it applies to HL7 V2.3.1.

Figure 3-3 HL7 V2.3.1 Document Hierarchy

In the Oracle SOA Suite for healthcare integration user interface, as you create a document definition, the document protocol hierarchy is reflected in the definition:

DocumentProtocol—Version—DocumentType—DocumentDefinitionName

Example 3-1 shows the hierarchy reflected in the definition for an HL7 document.

Example 3-1 Document Definition Name for an HL7 Document

Document protocol: HL7

Document protocol version: 2.3.1

Document type: ADT_A01

Document definition: ADT_A01_def

The resulting document definition is:

HL7-2.3.1-ADT_A01-ADT_A01_def

3.2 Using the Custom Document Protocol

Oracle SOA Suite for healthcare integration supports custom document protocols to create documents needed for proprietary transactions. With XML messages, you have the advantage of schema enforcement (XSDs).

With non-XML messages, you can create endpoints for specific message types.

When creating a Custom document, you specify rules to identify the incoming document. For XML documents, specify an XPath expression or an XPath expression and a value, which is the expected result of the expression.

For non-XML documents such as a flat file, you can specify Identification Start Position, End Position, and Identification Value.

3.2.1 What You May Need to Know About Custom Document Version Parameters

No parameters need to be set when you create the document version for a Custom document.

3.2.2 What You May Need to Know About Custom Document Definition Parameters

When you create a Custom document definition (see Section 3.4, "Creating Document Definitions" for more information on creating document definitions), select the identification type—XML or Flat, and set parameters in the tabbed areas. Figure 3-4 shows the document definition parameters for an XML-type Custom document.

Figure 3-4 Document Definition Parameters for an XML-Type Custom Document

Figure 3-5 shows the document definition parameters for a flat-file Custom document.

Figure 3-5 Document Definition Parameters for a Flat-FIle Custom Document

Table 3-1 describes the document definition parameters for a Custom document.

Table 3-1 Document Definition Parameters for a Custom Document

Parameter

Description

XML Tab

(Available if XML is selected from Identification Type)

Identification Expression (XPath)

Locates a node in the XML payload

Identification Value

Provides the value to match in the node identified by the Identification Expression. If the values match, then the document is successfully identified. If the value is left blank, then Oracle SOA Suite for healthcare integration checks for the existence of the node and the document is successfully identified.

DTD/XSD NamespaceConversion

Select from None, Both, Inbound, or Outbound.

Routing Tab

-

Document Routing ID

Sets the consumer name to the back-end application

XPath Tab

See Section 3.2.2.1, "How to Configure the XPath Expression for a Custom XML Document."

XPath Name1

The XML XPath name for retrieving the value from the payload

XPath Expression1

The XML XPath expression for retrieving the value from the payload.

XPath Name2

The XML XPath name for retrieving the value from the payload.

XPath Expression2

The XML XPath expression for retrieving the value from the payload.

XPath Name3

The XML XPath name for retrieving the value from the payload.

XPath Expression3

The XML XPath expression for retrieving the value from the payload.

Correlation Tab

-

Correlation From XPath Name

The name of the correlation property for initiating the correlation.

Correlation From XPath Expression

The XML XPath for retrieving the value from the payload to initiate the correlation.

Correlation To XPath Name

The name of the correlation property for the correlation.

Correlation To XPath Expression

The XML XPath for retrieving the value from the payload for the correlation.

Flat Tab

-

Identification Start Position

Used in combination with the end position to retrieve a value from the payload between the start and end positions

Identification End Position

Used in combination with the start position to retrieve a value from the payload between the start and end positions

Identification Value

A value between the start and end positions

Apps Tab

-

Document

The name of the internal application document.

Action

A sub-classification within the document.

XSLTFile

The name of the XSLT file.

3.2.2.1 How to Configure the XPath Expression for a Custom XML Document

The XPath expression identifies a Custom XML document. You configure the XPath expression when you specify the document type parameters.

The options when configuring an XPath expression are as follows:

- Option 1: Specify the XPath and the Matching Value

- Option 2: Check for the Existence of a Node

- Option 3: Check the Value of an Attribute

3.2.2.1.1 Option 1: Specify the XPath and the Matching Value

Assume that the transaction ID is 12345. Set the parameters as follows:

Field

Value

Identification Value

12345

Identification Expression

//*[local-name() = 'TransactionID']/text()

Oracle SOA Suite for healthcare integration compares the value of Identification Expression in the payload to the value specified in Identification Value. If the values match, then the document is identified successfully and the corresponding document type and document protocol version are used to identify the endpoint. Example 3-2 shows an excerpt of the XML payload for this option.

Example 3-2 Specify the XPath and the Matching Value

<?xml version="1.0" encoding="UTF-8" ?>
<Message xmlns:ns1="http://www.example1.org" xmlns:ns2="http://www.example2.org"
xmlns="http://www.example3.org"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns="http://www.example4.org">
<MessageHeader>
<Source>201944019</Source>
<Destination>205704856</Destination>
<TransactionID>123456</TransactionID>
<Version>1-0-0</Version>
</MessageHeader>
<Body>
<ns:Case xsi:schemaLocation="http://www.example4.org" ns1:caseCategoryID="1">
<ns1:OfficialProvisionNumber>String</ns1:OfficialProvisionNumber>
</ns:Case>
</Body>
</Message>

3.2.2.1.2 Option 2: Check for the Existence of a Node

Assume that you are checking for the existence of a node called registerCommand. Set the parameters as follows:

Field

Value

Identification Value

Leave blank.

Identification Expression

/*[local-name()='envelope']/body/transaction/command/*[local-name()='registerCommand']

When the Identification Value field is left blank, Oracle SOA Suite for healthcare integration checks for the node identified in Identification Expression. If a node in the payload matches, then the document is identified successfully. Example 3-3 shows an excerpt of the XML payload for this option.

Example 3-3 Check for the Existence of a Node

<uccnet:envelope xmins:eanucc="http://www.ean-ucc.org/schemas/1.3/eanucc"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:uccnet="http://www.uccnet.org/schemas/2.2/uccnet"
communicationVersion="2.2"
xsi:schemaLocation="http://www.uccnet.org/schemas/2.2/uccnet
http://www.testregistry.net/xmlschema/uccnet/2.2/Envelope.xsd">
<messageHeader>
<messageIdentifier>
<value>791:1_EB3CDC749A1F2BABE03014906CC4605A</value>
</messageIdentifier>
<userId>oraclesupXSD</userId>
<representingParty>
<gin>0060974050142</gin>
</representingParty>
</messageHeader>
<body>
<transaction>
<entityIdentification>
<uniqueCreatorIdentification>856</uniqueCreatorIdentification>
<globalLocationNumber>
<gin>0060974050142</gin>
</globalLocationNumber>
</entityIdentification>
<command>
<uccnet:registerCommand>
<registerCommandHeader type="ADD" />
</uccnet:registerCommand>
</command>
</transaction>
</body>
</uccnet:envelope>

3.2.2.1.3 Option 3: Check the Value of an Attribute

Assume that the value of the country attribute is US. Set the parameters as follows:

Field

Value

Identification Value

US

Identification Expression

//*/@country

Oracle SOA Suite for healthcare integration compares the value of the country attribute to the value set for Identification Value. If the values match, then the document is identified successfully. Example 3-4 shows an excerpt of the XML payload for this option.

Example 3-4 Check the Value of an Attribute

<?xml version="1.0" encoding="windows-1252" ?>
<MyAddress country="US" xmlns="http://www.example.org"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="PO.xsd">
<name>B2B Buyer</name>
<street>100 Oracle Parkway</street>
<city>Redwood City</city>
<state>CA</state>
<zip>94065</zip>
</MyAddress>

3.3 Using the HL7 Document Protocol

Oracle SOA Suite for healthcare integration implements the Health Level 7 (HL7) version 2.x to exchange documents containing health care information using the Generic exchange or MLLP exchange. When using HL7, the standard Oracle SOA Suite for healthcare integration features, such as validation, translation, automatic generation of outbound envelope headers, and acknowledgments, are available.

For information about the organization that created and maintains the HL7 standards, go to

http://www.hl7.org

3.3.1 What You May Need to Know About HL7 Document Version Parameters

When you create an HL7 document version, you can set various parameters. Figure 3-6 shows document version parameters for an HL7 document.

Figure 3-6 Document Version Parameters for an HL7 Document

Table 3-2 describes the document version parameters for an HL7 document.

Table 3-2 Document Version Parameters for an HL7 Document

Parameter

Description

Message Header Tab

-

Security

In some applications of HL7, this field is used to implement security features.

Processing ID

MSH.11 - This field is used to decide whether to process the message as defined in HL7 Application (level 7) processing rules. The first component defines whether the message is part of a production, training, or debugging system (refer to HL7 table 0103 - Processing ID for valid values). The second component defines whether the message is part of an archival process or an initial load (refer to HL7 table 0207 - Processing mode for valid values). This allows different priorities to be given to different processing modes.

Accept Acknowledgement Type

Sets the conditions under which application acknowledgments are required to be returned in response to the message. The value AL (always) is supplied.

Oracle SOA Suite for healthcare integration checks the payload (MSH.15) of an incoming message to see if an ACK has to be generated. In some HL7 Systems, MSH.15 is not sent in the payload at all and it is expected that an ACK is still sent.

Application Acknowledgment Type

MSH.16. The value AL (always) is supplied.

Country Code

Sets the country of origin for the message. The value US is supplied.

Character Set

Sets the character set for the entire message. The value ASCII is supplied.

Internationalization Code Identifier

MSH.19

Internationalization Code Text

MSH.19

Internationalization Coding System Name

MSH.19

Internationalization Code Alternate Identifier

MSH.19

Internationalization Code Alternate Text

MSH.19

Internationalization Code Alternate Coding System Name

MSH.19

International Version Identifier

MSH.12

International Version ID Text

MSH.12

International Version ID Coding System Name

MSH.12

International Version ID Alternate Identifier

MSH.12

International Version ID Alternate Text

MSH.12

International Version ID Alternate Coding System Name

MSH.12

Batch Header Tab

-

Create Batch Header

Select the box to create batch headers.

Batch Header Ecs File

Use the Browse button to find an ecs file to override the standard file. If not provided, the provided default file is used.

Batch Security

BHS.8

Batch Date

BHS.7. The system date-time stamp is supplied (#SystemDateTime(CCYYMMDDHHMM)#).

File Header Tab

-

Create File Header

Select the check box to create file headers.

File Header Ecs File

Use the Browse button to find an ecs file to override the standard file. If not provided, the provided default file is used.

File Security

FHS.8

File Date

FHS.7. The system date-time stamp is supplied (#SystemDateTime(CCYYMMDDHHMM)#).

Delimiters Tab

Click Select Hexadecimal Characters next to any of the delimiter fields to provide values.

Element Delimiter

A single character that follows the segment identifier and separates each data element in a segment except the last. The value 0x7c is supplied.

Escape Character

The value 0x5c is supplied.

Repeating Separator

A service character used to separate adjacent occurrences of a repeating data element, or to separate multiple occurrences of a field.The value 0x7e is supplied.

Segment Delimiter

A syntax character indicating the end of a segment (a logical grouping of data fields) within a message. The value 0x0d is supplied.

Subcomponent Delimiter

The value 0x26 is supplied.

Subelement Delimiter

The value 0x5e is supplied.

Miscellaneous Tab

-

Ignore Envelope Parameters

Use this option to provide a list of envelope elements, separated by commas, to be ignored during look-up validation. For an HL7 agreement, the possible values include MessageSendingApp, MessageReceivingApp, MessageSendingFacility, and MessageReceivingFacility.

Ack Mode

Select this option to specify whether to send a single acknowledgment or multiple acknowledgments for inbound batched HL7 messages.

3.3.2 What You May Need to Know About HL7 Document Type Parameters

When you create an HL7 document type, you can set various parameters. Figure 3-7 shows the document type parameters for an HL7 document.

Figure 3-7 Document Type Parameters for an HL7 Document

Table 3-3 describes the document type parameters for an HL7 document.

Table 3-3 Document Type Parameters for an HL7 Document

Parameter

Description

Transaction Tab

-

HL7 Generic ACK

If selected, Oracle SOA Suite for healthcare integration sends a generic ACK.

Map ACK Control ID

Select to enable mapping the MSH.10 of the business message to the MSH.10 of the acknowledgment.

Note: This Map ACK Control ID parameter is for the functional ACK.

Accept Acknowledgement

A functional acknowledgment is generated when MSH.15 has no value. Select None to take no action. Acknowledgment generation is dependent on the value in MSH.15 of the business message. Select AL (always) to generate the acknowledgment under any conditions. Select ER (error/reject) to generate the acknowledgment when the message errors or is rejected. Select SU (successful completion) to generate the acknowledgment when the message is successfully processed.

3.3.3 What You May Need to Know About HL7 Document Definition Parameters

When you create an HL7 document definition (see Section 3.4, "Creating Document Definitions" for more information on creating document definitions), you can set various parameters. Figure 3-8 shows document definition parameters for an HL7 document.

Figure 3-8 Document Definition Parameters for an HL7 Document

Table 3-4 describes the document definition parameters for an HL7 document.

Table 3-4 Document Definition Parameters for an HL7 Document

Parameter

Description

Transaction Tab

-

*Transaction Set ecs File

Use the Browse button to find the ecs file.

Routing Tab

-

Document Routing ID

Sets the consumer name to the back-end application

XPath Tab

-See Section 3.2.2.1, "How to Configure the XPath Expression for a Custom XML Document," for more information.

XPath Name1

The XML XPath name for retrieving the value from the payload

XPath Expression1

The XML XPath expression for retrieving the value from the payload

XPath Name2

The XML XPath name for retrieving the value from the payload

XPath Expression2

The XML XPath expression for retrieving the value from the payload

XPath Name3

The XML XPath name for retrieving the value from the payload

XPath Expression3

The XML XPath expression for retrieving the value from the payload

Correlation Tab

-

Correlation From XPath Name

The name of the correlation property for initiating the correlation.

Correlation From XPath Expression

The XML XPath for retrieving the value from the payload to initiate the correlation.

Correlation To XPath Name

The name of the correlation property for the correlation.

Correlation To XPath Expression

The XML XPath for retrieving the value from the payload for the correlation.

Apps Tab

-

Document

The name of the internal application document.

Action

A sub-classification within the document.

XSLTFile

The name of the XSLT file.

3.3.4 What You May Need to Know About Using HL7

No business message is produced for an HL7 immediate acknowledgment (transport-level acknowledgment).

Negative acknowledgment messages indicating errors in an HL7 exchange may be truncated because of the 80-character length limitation in HL7 versions 2.1 through 2.5.

3.4 Creating Document Definitions

A document definition specifies the document protocol—the document protocol version and document type—that is used to validate the message. The document definition can be an ECS file, in the case of HL7 messages, or an XSD/DTD, in the case of XML messages.

The same document definition is used by participating endpoints in a transaction. It must adhere to the standards for document protocols, protocol versions, and document types.

Note:

To ensure that the document definition conforms to standards, you can use Oracle Document Editor to create the document guideline files and then use the Oracle SOA Suite for healthcare integration user interface to import those files when creating the document definition.

After creating transaction set files by using Oracle Document Editor, you use the Oracle SOA Suite for healthcare integration user interface to create the document definition and import the transaction set files.

Note:

The document version, document type, and document definition are not editable after they are created. You must delete the specific document element (version, type, or definition) and create a new one. Updating the document elements after creation can lead to metadata inconsistency, metadata validation issues, and runtime errors.

To create a document definition:

1. Log on to Oracle SOA Suite for healthcare integration. The Oracle SOA Suite for healthcare integration user interface opens with the Configuration tab selected.

2. In the left-hand navigation panel, expand Document Protocol. This displays the list of supported protocols, which are Custom and HL 7 V2.x.

3. Select one of the document protocols, for example HL7, as shown in Figure 3-9, and click the Create button. This displays the Create Document Version window.

Note:

You can also right-click the document protocol name and select Create from the shortcut menu.

Figure 3-9 Selecting a Document Protocol

Note:

In the Create Document Protocol Version dialog box, enter a protocol version name, for example, 2.3.1.

4. Enter the document protocol version name in the Name field.

5. Specify the document version parameters as applicable, and click OK.
The version is used for document identification and can be case sensitive. Use a fixed syntax that conforms to the protocol standards.

Figure 3-10 shows the document protocol version page for an HL7 V2.3.1 document.

Figure 3-10 Entering Document Protocol Version Information

For parameter descriptions, see Table 3-2, "Document Version Parameters for an HL7 Document".

6. Click the newly created Version name, and then click the Create button to display the Create Document Type window. Alternatively, you can right-click the version name and select Create from the shortcut menu.

7. Enter a document type name, specify document type parameters as applicable, and then click OK.
Figure 3-11 shows the document type parameters page for an HL7 V2.3.1 document.

Figure 3-11 Entering Document Type Parameter Information

For document type parameter descriptions, see Table 3-3, "Document Type Parameters for an HL7 Document".

8. With the new document type name selected, click Create to display the Create Document Definition window.

9. Enter a document definition name and do the following:

1. Browse for an optional definition (XSD) file for any of the document protocols.

2. Browse for the required transaction set ECS file for HL7 or positional flat file.

3. Specify document definition parameters as applicable and click OK.

Figure 3-12 shows the document definition parameters page for an HL7 V2.3.1 document.

Figure 3-12 Entering Document Definition Parameter Information

For definition parameter descriptions, see the following:

- Table 3-1, "Document Definition Parameters for a Custom Document"

- Table 3-4, "Document Definition Parameters for an HL7 Document"

Note:

You can also use the post install script, install the standard library, and import hl7 doctypes file to create a document tree in Healthcare console.

3.5 Deleting a Document Definition

To delete a document definition, select the document definition name and click Delete. Alternatively, you can select the definition name, right-click, and select Delete from the shortcut menu.

4 Working with Endpoints

This chapter describes the concept of an endpoint in Oracle SOA Suite for healthcare integration, and provides instructions for creating and configuring endpoints for healthcare integration applications.

This chapter contains the following topics:

- Section 4.1, "Introduction to Endpoints"

- Section 4.2, "Creating Endpoints"

- Section 4.3, "Associating an Endpoint with a Document"

- Section 4.4, "Enabling Sequencing for an MLLP Endpoint"

- Section 4.5, "Deleting an Endpoint"

- Section 4.6, "Working with the Endpoint Window"

4.1 Introduction to Endpoints

In Oracle SOA Suite for healthcare integration, endpoints are communication channels from where predefined documents are sent or received. Endpoints define how documents are exchanged with an external system, specifying the location, transport protocol, documents to be exchanged, and other configuration parameters. An endpoint can be a URL, folders, or path, among others. Based on the direction of the message, an endpoint can be inbound, outbound, or both. For example, when Oracle SOA Suite for healthcare integration reads from a directory, the directory is the inbound endpoint. Conversely, when Oracle SOA Suite for healthcare integration writes to or sends messages to a directory, the directory is the outbound endpoint. Also, an MLLP endpoint can be used both for receiving and sending messages.

For Oracle SOA Suite for healthcare integration, you need to associate an endpoint with document definitions and enable the endpoint to be able to start sending and receiving messages.

Figure 4-1 displays a sample endpoint, which is yet to be associated with a document definition.

Figure 4-1 Oracle SOA Suite for healthcare integration Sample Endpoint

4.2 Creating Endpoints

The Oracle SOA Suite for healthcare integration user interface provides an Endpoints page where you can create and configure endpoints. This procedure describes how to create endpoints using the interface.

You can create endpoints both for bidirectional (MLLP) and single-directional (FILE, JMS) transport protocols. Bidirectional protocols enables you to send or receive response messages or functional acknowledgements (FAs) by using the same endpoint. However, single-directional protocols need to be configured to send and receive documents; only then you can send or receive messages or FAs per endpoint.

To create endpoints with bidirectional transport protocol (MLLP):

1. Log on to the Oracle SOA Suite for healthcare integration user interface.

2. In the Configuration tab under the Design tab, click the Endpoint folder and then click the Create icon as shown in Figure 4-2.

Figure 4-2 Create Endpoint Icon

3. In the Create window, enter the following and click OK, as shown in Figure 4-3:

- Name: Name of the endpoint.

- Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select MLLP10.

- Connection Mode: Server or Client. If the endpoint is configured as server, Oracle SOA Suite for healthcare integration engine starts listening on a port and waits for a client to connect to it. In general, the server connection mode is for inbound case. When configured as client, the engine connects to hostname and port of a remote computer or device. In general, this is for an outbound case.

Note:

Oracle Healthcare supports multiple client connections for a single server channel. So, multiple clients can connect to the same server and exchange data and receive FAs.

If the message is passed to the backend application, then the message can be sent in the following ways:

- Oracle Healthcare passes the endpoint details to the backend application using dynamic IP address, and te application populates the same values back into outbound dynamic IP header. Oracle Healthcare makes use of this dynamic IP header to pick the correct connection.

- Clients can set the replytoMsgId property in the properties of the acknowledgement or response message and then connection details can be fetched from the request message.

- Host Name: In case of an MLLP Server endpoint, it should be name or IP address of the computer hosting Oracle SOA Suite, and in the case of an MLLP Client endpoint, it should be the remote host name or device name. Typically, this should be localhost. However, Host name can also be the name of the remote host or device.

- Port: Port number should be more than 500. If the connection mode is set to Server, then the port must be a valid TCP port number. If the connection mode is set to Client, then the port must be the same as the port used on the MLLP server.

This creates the endpoint and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

Figure 4-3 Specifying Endpoint Parameters

To create endpoints with single-directional transport protocol (FILE):

1. Log on to the Oracle SOA Suite for healthcare integration user interface.

2. In the Configuration tab under the Design tab, click the Endpoint folder and then click the Create icon.

3. In the Create window, enter the following and click OK, as shown in Figure 4-4:

- Name: Name of the endpoint.

- Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select FILE.

- Direction: Inbound or Outbound based on your requirement. If the endpoint is configured as inbound, then it can receive response messages or FAs from other endpoints. Conversely, if the endpoint is configured as outbound, it can send messages or FAs.

- Folder Name: An absolute directory path is recommended and this folder does not contain the inbound or outbound messages or FAs. Inbound messages are expected in this folder, and outbound messages or FAs need to be delivered here.

This creates the endpoint and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

Figure 4-4 Specifying Endpoint Parameters

Note:

Once a single-directional endpoint (inbound/outbound) is created, then it can be edited later to add inbound or outbound configuration by clicking the Configure link.

Note:

See Appendix B, "Creating Endpoints with Different Transport Protocols" for more information on creating endpoints with different transport protocols.

4.2.1 Configuring Channels in an Endpoint with Single-Directional Protocols

When a bidirectional transport protocol (such as MLLP) is used to create an endpoint, the endpoint can handle both request and reply (inbound and outbound) or ACK. However, in the case of a single-directional transport protocol (such as File or FTP), typically, you can only configure either the inbound or the outbound channel, but not both together.

Oracle SOA Suite for healthcare integration, in the case of single-directional protocols, allows you to configure two communication channels (one for sending and one for receiving messages) as a single entity (endpoint) for management and monitoring. This concept allows you to enable or disable, view the supported documents, and display related monitoring data (message counts and actual messages) for the related channels at the same time.

Using this feature, when you use a single-directional transport protocol, you need to configure only one channel. The configuration for the other channel (for the reverse direction) is optional. The Oracle SOA Suite for healthcare integration console, in this case, displays that one channel has been configured to send or receive messages, but the other channel has not been configured yet as shown in Figure 4-5.

Figure 4-5 Undefined Secondary Channel

You can configure the other channel by clicking the Configure link in the undefined channel section, as shown in Figure 4-6, and providing the required channel details in the configuration dialog box.

Figure 4-6 Defining the Secondary Channel

The transport protocol and other settings are defined per channel. You can use different single-directional transport protocols for the two channels. For example, the one channel can use FTP, whereas the other channel can use File. The only requirement is that both the protocols used should be single directional.

Once you have defined both the communication channels and associated documents with the channels (see Section 4.3, "Associating an Endpoint with a Document"), the endpoint appears as Figure 4-7.

Figure 4-7 Single-Directional Endpoint with Both Channels Configured

You can edit the configuration of either of the channels if required. You can also delete the configuration of either of the channels by using the Delete links in the relevant channel section.

4.3 Associating an Endpoint with a Document

Once you have created an endpoint, you need to associate it with a document to enable the endpoint to send or receive messages. You can configure an endpoint to send or receive messages or both.

To associate a bidirectional endpoint with a document:

1. Open the required endpoint.

2. Configure the endpoint to send or receive messages:

1. In the Send or Receive section of the endpoint, click the + icon to display the Document selection window.

2. Select the required document definition from available document hierarchy, for example, ADT_A04_def. The document definition gets associated with the endpoint. You can specify whether you require functional acknowledgment, validation, or translation of the endpoint as well as required internal delivery channel, transport or agreement level callouts, and mapsets.

Note:

you can also drag-and-drop the document definition to the Send or Receive section.

Figure 4-8 displays an endpoint associated with a document definition.

Figure 4-8 Associating an Endpoint with Document Definitions

Note:

For FA, Functional ACK, Validation, Translation, Retry Interval, and Reattempt Count are disabled.

3. Select any of the following document configuration options:

Option

Description

Functional ACK

Select to enable the functional acknowledgment for success or error criterion

Validation

Select to enable validation of the document against the configured ECS file

Translation

Select to enable the translation of XML to native format and vice-versa

4. If any of the following have been defined for the endpoint, select them from the appropriate field: Internal Channel, Document Callout, Mapset, or Composite. For more information, see Chapter 6 Creating and Deploying Trading Partner Agreements in Oracle Fusion Middleware User's Guide for Oracle B2B.

Note:

Selecting the composite name and JMS internal delivery channel name are optional for an inbound document. Oracle Healthcare can support only one composite for a specific document definition. If multiple composites are available, the result is unpredictable because Oracle Healthcare sends messages to the one that is first registered to Oracle Healthcare during runtime.

3. Select the Enabled check box and click Apply to enable the endpoint for sending and receiving messages.The Apply operation sometimes could take about 30 to 60 seconds. This is due to the XSD/ECS creation and metadata validation.

Note:

After making any changes to an endpoint, you can right-click the endpoint name in the left-side panel and click Refresh to update the endpoint.

Note:

You can enable or disable an endpoint by selecting or deselecting the Enabled check box and clicking the Apply button.

Associating a single-directional endpoint with a document

To associate a single-directional endpoint, such as File, the procedure is similar to that of a bidirectional endpoint. However, there are a few differences:

- When creating the endpoint, based on the direction that you have selected, the Oracle SOA Suite for healthcare integration console opens the configuration option for that particular direction.

- Once you follow the other steps listed in associating a bidirectional endpoint with a document, the endpoint gets attached to a document as shown in Figure 4-9.

Figure 4-9 Associating a Single-directional Endpoint with a Document

- If when creating the endpoint, you have specified the direction of the endpoint as inbound, you can define the outbound configuration for the endpoint on the same page by using the Configure link. This feature helps in tying two related single-directional endpoints (one for sending and one for receiving messages) as a single entity for better management and monitoring.

Note:

You can disassociate a document from an endpoint by selecting the specific document entry in the Documents section and then by clicking the Delete (X) button.

4.4 Enabling Sequencing for an MLLP Endpoint

After you associate a document with an endpoint, the following options are available for configuring the endpoint:

- Acknowledgement (ACK) Mode: Select Sync, Async, or None for the mode in which the endpoint receives messages.

- Retry Interval: The interval between each attempt to retry message delivery.

- Reattempt Count: The number of times to retry message delivery.

- Transport Callout: The transport callout to be invoked after receiving or before sending any message. A callout can be selected only after the callout is created.

- Transport Protocol: Click the Transport Details button to customize the transport protocol parameters as shown in the following graphic.

If HL7 messages over MLLP 1.0 are required to be sent in such a way that the next message is sent only after receiving a positive ACK for the current message, then the sequencing mode of MLLP 1.0 can be set to OnetoOne sequencing.

When associating an MLLP 1.0 endpoint with a document, you can select from the following sequencing modes for outbound messages from the Advanced tab of the Transport Protocol Parameters dialog box:

- None: Messages are dispatched in sequence without waiting for an ACK

- OneToOne (Default): Messages are sent in a sequenced manner, but the ACKs are not expected to carry the Control Numbers (the correlation is done without checking the control number in the ACK). In case of a negative ACK, the message sending is retried until either a positive ACK is received or the retry count is exhausted (at which point, the message goes into an error state.)

- OneToOneMapping: Messages are sent in a sequenced manner, but the ACKs must carry the Control Numbers for proper correlation. Control Number is used to correlate a ACK with the sent message.

Figure 4-10 displays the available sequencing modes for outbound messages.

Figure 4-10 Outbound Message Sequencing Modes

Note:

The value selected for the Discard HL7 ACK check box indicates if the ACK payload is persisted or not. This is applicable only in the case of Immediate Acknowledgements or Discard Acknowledgement cases. Deselecting the check box reduces the I/O load at the database layer due to persistence of payloads.

For more information on transport protocols and their corresponding exchange protocols, see Table 5-3 Transport Protocol Parameters and Table 5-5 Exchange Protocol Parameters in the Chapter 5 Configuring Trading Partners in Oracle Fusion Middleware User's Guide for Oracle B2B.

For a single-directional endpoint:

- When you click the Transport Details button, the Transport Protocol Parameters dialog box that appears, is prompts for a set of parameters that are different from the bidirectional endpoint. Figure 4-11 displays the Transport Protocol parameters dialog box for a single-directional endpoint.

Figure 4-11 The Transport Protocol Parameters Dialog Box

For more information on transport protocols, see Table 5-3 Transport Protocol Parameters in the Chapter 5 Configuring Trading Partners in Oracle Fusion Middleware User's Guide for Oracle B2B.

4.5 Deleting an Endpoint

To delete an endpoint, log on to the Oracle SOA Suite for healthcare integration user interface. In the Configuration tab under the Design tab, select the endpoint name and click the Delete icon. You can also right-click the endpoint name and click Delete from the shortcut menu.

Note:

An enabled endpoint cannot be deleted. you need to disable the endpoint before deleting it.

4.6 Working with the Endpoint Window

You can use open the Endpoint window to view a list of existing endpoints. In addition, using the endpoint window, you can create, modify or delete endpoints. You can also perform bulk modification or deletion using this window by selecting all or the required endpoints and then performing the operation of your choice.

To access the Endpoint window:

1. Log on to the Oracle SOA Suite for healthcare integration user interface.

2. In the Configuration tab under the Design tab, double-click the Endpoint folder.

Figure 4-12 displays the Endpoint window.

Figure 4-12 The Endpoint Window

5 Working with Callouts

This chapter describes how to create and use Java callouts in Oracle SOA Suite for healthcare integration. Java callouts transform the formats of messages exchanged between the host and remote endpoints. You can use callouts to invoke an XSLT style sheet and any Java program in general.

This chapter contains the following topics:

- Section 5.1, "Introduction to Callouts"

- Section 5.2, "Types of Callouts"

- Section 5.3, "Creating a Callout"

- Section 5.4, "Including a Callout in an Endpoint"

5.1 Introduction to Callouts

Callouts are used in environments in which a host endpoint does not use the same message format as the remote trading partner. In addition, callouts are used to customize header information in messages.

5.1.1 Creating a Callout Library JAR File

If the callout JAR file provided with Oracle SOA Suite for healthcare integration is not sufficient for your needs, you can create your own callout JAR file outside of Oracle SOA Suite for healthcare integration, following the standards described in the Oracle Fusion Middleware B2B Callout Java API Reference. You can specify the directory location of this external JAR file in the Callout Directory field that you can access from the Runtime link under Settings in the Administration tab of the Oracle SOA Suite for healthcare integration user interface as shown in Figure 5-1. It is recommended that you create an external JAR file for your callouts; do not bundle your callouts with b2b.jar.

Figure 5-1 Specifying the Callout Directory

Note:

MySampleCallout is a restricted keyword and should not be used. It is already packaged into b2b.jar.

5.2 Types of Callouts

Oracle SOA Suite for healthcare integration provides two types of callouts:

- Transport Callouts

- Document Callouts

5.2.1 Transport Callouts

A transport callout is associated with an endpoint. For the inbound message, Oracle SOA Suite for healthcare integration invokes the transport callout immediately after it receives a message from the remote endpoint. For the outbound message, Oracle SOA Suite for healthcare integration invokes the transport callout immediately before it sends a message to the remote endpoint. Transport callouts can be selected in the endpoint configuration, as shown in Figure 5-2, and can be used with any supported protocol such as generic TCP and MLLP 1.0.

Figure 5-2 Transport Callouts

You can use transport callouts to extract transport custom headers for inbound messages and set transport headers for outbound messages. Example 5-1 shows how to set and get the CUSTOM_HEADER property in the callout.

Example 5-1 Setting and Getting the CUSTOM_HEADER Property

import java.util.*;
import oracle.tip.b2b.callout.*;
import oracle.tip.b2b.callout.exception.*;

public class SampleCallout implements Callout {
public void execute(CalloutContext context,List input,List output)
throws CalloutDomainException, CalloutSystemException {
try {
CalloutMessage cmIn = (CalloutMessage)input.get(0);
String s =cmIn.getBodyAsString();

//for getting the CUSTOM_HEADER
Properties params =  (Properties)cmIn.getParameters();
String customHeader = (String)params.get("CUSTOM_HEADER");

//for setting the CUSTOM_HEADER
CalloutMessage cmOut = new CalloutMessage(s);
cmOut.setParameter("CUSTOM_HEADER", "your_value");
output.add(cmOut);

} catch (Exception e) {
throw new CalloutDomainException(e);
}
}
}

See "Using a Transport Callout to Extract Custom Headers" in Oracle Fusion Middleware User's Guide for Oracle B2B for more information.

Transport callouts are created from the Configuration tab under Designer, as described in Section 5.3, "Creating a Callout." All transport callouts appear both in the Transport Callout list and in the Document Callout list in an endpoint page; therefore, it is available for selection. To avoid confusion, when you create a transport callout, provide a name that indicates its type so that you do not select it from the Document Callout list.

5.2.2 Document Callouts

Document callouts are used to enable communication between endpoints that do not use the same message format. For example, a remote endpoint sends a HL7 2.3.1 XML-formatted message to a host endpoint. The host endpoint uses HL7 2.5 XML-formatted messages.

To enable communication between these two different formats, you create two callouts, as follows:

- One callout, callout_inbound, for example, transforms the remote message into a format understood by the host endpoint. The host endpoint, in turn, responds to the request message with a order acceptance message in HL7 2.5 XML format.

- The other callout, callout_outbound, for example, transforms the HL7 2.5 XML format back into an HL7 2.3.1 XML-formatted message for the remote endpoint.

These two callouts are then associated with the two endpoints, as follows:

- Associate callout_outbound in the endpoint for the outbound message, which is, the endpoint for the initiating message request.

- Associate callout_inbound in the endpoint for the inbound message, which is, the endpoint for the responding message acceptance.

Because a document definition is a component of an endpoint, a callout is associated with a specific document definition.

This example depicts a simple association of one callout to one endpoint. In reality, however, the same callout can be included in many different endpoints by changing the value of one or more callout parameters. See Figure 5-4 for where you add parameters and see Table 5-2 for a list of parameter attributes.

5.3 Creating a Callout

To create a callout, provide callout details—the library name and the implementation class name—and callout parameters, as shown in Figure 5-4.

Note:

To create a callout from an external callout library JAR file, see Section 5.1.1, "Creating a Callout Library JAR File."

Figure 5-3 Creating a Callout

To create a callout:

1. Log on to the Oracle SOA Suite for healthcare integration user interface.

2. Click the Designer tab, Configuration, and then Callout.

3. Click the Create icon (the plus sign) to display the Create Callout dialog box.

4. Enter a name for the callout.
(You may want to indicate if you are creating a transport callout in the name.)

5. Enter callout details, as described in Table 5-1.

6. Click OK.

Table 5-1 lists the callout details that you provide.

Table 5-1 Callout Details

Field

Description

JAR file name

Select the library name that contains the callout implementation classes.

Note: If you specify one or more of your own callout JAR files, you must specify the directory location. Use the Runtime link under Settings from the Administration link. The directory location for the default b2b.jar file included with Oracle Healthcare does not need to be specified.

The callout library must be manually migrated from one environment to another. The Oracle SOA Suite for healthcare integration export/import feature does not migrate the callout library JAR.

Implementation Class

Select the implementation class name.

Note: Oracle SOA Suite for healthcare integration includes a predefined class file named XSLTCalloutImpl that you can use for XML-to-XML transformations.

Note:

You cannot delete a callout that is included in an endpoint.

After creating the callout, you can configure it by specifying the timeout value and optional parameters as shown in Figure 5-4.

Figure 5-4 Configuring Callouts

Callout parameters are similar in concept to global variables to which you can assign local values that are applicable only to a specific callout use. Or, you can create a callout parameter and assign it a default value that is applicable to all callout uses. Changes to callout parameters for an existing callout affect all endpoints that use that callout.

Table 5-2 lists the optional callout parameter attributes.

Table 5-2 Callout Parameter Attributes

Field

Description

Name

Enter a parameter name.

Type

Select from Integer, Float, String, Boolean, or Date types. The format for the Date type is MM/DD/YYYY.

Note: Changing a type can invalidate the parameter default value.

Value

Enter a value. If Encrypted is set to True, then this value is encrypted.

Mandatory

Select True or False.

Encrypted

Select True or False.

Description

Enter an optional description.

After you create a callout, it is available to include in an endpoint. See Section 5.4, "Including a Callout in an Endpoint," for more information. If you change a callout after it is deployed with an endpoint, a server restart is required.

5.4 Including a Callout in an Endpoint

After you create a callout, it is available to include in an endpoint.

To include a callout in an endpoint:

1. From the Configuration tab, double-click an endpoint to open it.

2. Depending on the type of message (inbound or outbound), select the callout name from the Document Callout list under the Send or Receive section. as shown in Figure 5-5.

Figure 5-5 Associating a Callout with an Endpoint

3. Click Apply.

6 Working with Mapsets

This chapter describes how to work with mapsets in Oracle SOA Suite for healthcare integration. When the messages in your source and target systems are defined by different document definitions and you need to map the data from one message to another, you can use a mapset to define the mapping logic.

This chapter includes the following topics:

- Section 6.1, "Introduction to Mapsets"

- Section 6.2, "Creating a Map File"

- Section 6.3, "Using Mapsets in the Oracle B2B Console"

- Section 6.4, "Using Mapsets in Oracle SOA Suite for Healthcare Integration"

6.1 Introduction to Mapsets

Mapsets provide data transformation for cases where it is better to map a native data format to a native data format instead of the standard translation of mapping native formatting to XML, XML to XML, and then XML back to native formatting. You can use mapsets when you need to map data between messages that are defined by different document definitions. For example, you might have a system that sends messages in HL7 2.3.1 format, but a receiving system needs the data in HL7 2.5 format. Or you might need to transform HIPAA 4010 messages to HIPAA 5010 and back again.

A mapset includes a predefined or user-defined map file and two document definitions. The map file defines how data is converted from one format to the other. Currently, the Oracle SOA Suite healthcare integration user interface supports mapping different versions of HL7 messages to each other. The Oracle B2B Console supports mappings for different HIPAA X12 messages to each other, as well as different versions of HL7 to each other.

Note:

Currently, using mapsets to transform HL7 2.x messages to HL7 v3.0 is not supported, but this can be achieved using the XSLT mapper in Oracle JDeveloper.

6.1.1 About Mapsets

When you create a mapset, you associate a map file, a source document definition, and target document definition within one mapset. A mapset groups the definitions and mapping together into one unit that can be reused in multiple Oracle B2B or healthcare integration applications. Each mapset uses two different document definitions, and these definitions need to be created in the design-time repository in order to create the mapset. Mapsets give you the option of using the default document definitions provided for each protocol or customized definitions that you have created or modified.

When you create a mapset in Oracle SOA Suite for healthcare integration, you associate it with the appropriate endpoints to incorporate the mapping logic into healthcare integration projects. When you create a mapset in Oracle B2B, you associate it with trading partner agreements. When you associate a mapset with an endpoint or agreement, you can only select an mapset whose document definitions and message flow match that of the endpoint or agreement.

6.1.2 Predefined and Custom Mapsets

In Oracle SOA Suite for healthcare integration, you have the option of creating your own custom mapsets using the MapBuilder feature of the Oracle Document Editor or purchasing predefined map files provided by Edifecs. The prebuilt maps include maps for the Health Insurance Portability and Accountability Act (HIPAA); for example, to transform HIPAA 4010 messages to HIPAA 5010 messages.

6.2 Creating a Map File

Before you can create a mapset in either the Oracle SOA Suite for healthcare integration user interface or the Oracle B2B Console, you need to have a map file that defines the mapping between the two types of document definitions. Edifecs provides some predefined map files that you can use, or you can create the files using the MapBuilder component of the Oracle Document Editor.

Note:

You can download the Oracle Document Editor from the installation package for Oracle SOA Suite for healthcare integration.

For more information, see "Creating Guideline Files" in Oracle Fusion Middleware User's Guide for Oracle B2B.

6.3 Using Mapsets in the Oracle B2B Console

Use the Oracle B2B Console to create mapsets when you are mapping a data standard other than HL7 or when you want to use the features of Oracle B2B instead of the healthcare integration features. You can use this feature to map HIPAA 4010 message types to HIPAA 5010, for example. You can use Oracle B2B for mapping HL7 messages, but it is recommended you use Oracle SOA Suite for healthcare integration instead.

Perform the following steps to incorporate a mapset into an Oracle B2B trading partner agreement:

- 0, "Creating a Mapset in the Oracle B2B Console"

- 0, "Associating a Mapset with a Trading Partner Agreement"

- 0, "Deleting a Mapset in the Oracle B2B Console"

6.3.1 Creating a Mapset in the Oracle B2B Console

Before you begin this step, make sure the map file is available on the computer from which you are accessing the Oracle B2B Console, and that the required document definitions are already created in Oracle B2B for both of the standards you are mapping. The mapset cannot be created without these three components.

For more information about working with document definitions in Oracle B2B, see "Using Document Protocols" in Oracle Fusion Middleware User's Guide for Oracle B2B.

To create a mapset

1. On the Oracle B2B Console, click Administration and then click the Mapset tab.

Figure 6-1 Mapset Page of the Oracle B2B Console

2. On the Mapset page, click Add Mapset (the plus icon).
A new row appears in the Mapset list.

3. In the new row, enter a name and a brief description of the new mapset.

4. Next to the Map File Location field, click Browse.

5. Browse to the location of your map file, select the file, and then click Open.
The map file you selected is loaded, and the Source Document Definition and Target Document Definition fields are populated with the appropriate document definitions for the mapping.

Figure 6-2 Mapset Defined in the Oracle B2B Console

Note:

If the document definitions do not already exist in Oracle B2B, this step will fail.

6. Click Save and then click OK on the confirmation dialog that appears.

6.3.2 Associating a Mapset with a Trading Partner Agreement

You associate a mapset with a trading partner agreement in order to incorporate the mapping into the B2B processing logic. For information and instructions on working with trading partner agreements, see "Creating and Deploying Trading Partner Agreements" in Oracle Fusion Middleware User's Guide for Oracle B2B.

Before You Begin:

Make sure all required B2B components have been created and configured as described in Oracle Fusion Middleware User's Guide for Oracle B2B. At a minimum, this includes document definitions, trading partners, and the mapset.

To associate a mapset with a trading partner agreement

1. On the Oracle B2B Console, select Partners in the upper right.
The Partner page appears.

2. In the Partner panel on the left, select the name of the remote trading partner, and then click the Create New Agreement icon in the Agreement panel.
The Agreement page appears.

3. Deselect Translate.

Note:

If Translation is selected, it is ignored when used in conjunction with a mapset in the endpoint. The mapset performs the data transformation and translation is not needed.

4. Select the trading partner and document definition for the agreement. For the document definition, select the native format that will be exchanged with the trading partner.

5. Click in the Mapset field and select the mapset you created for this agreement.

Figure 6-3 Mapset Page in Oracle B2B

Note:

When using mapsets, whether the selected document definition is the source or target in the mapset depends on the direction of the message flow in the agreement. The above image shows an outbound message, so the selected document definition (HIPAA 5010 837) is the target document definition in the mapset, which maps HIPAA 4010 837 message to HIPAA 5010 837 messages.

6. To view information about the selected mapset, click Mapset Details.
A dialog appears with summary information for the mapset.

Figure 6-4 Mapset Details Dialog

7. Configure the agreement as described in "Creating and Deploying Trading Partner Agreements" in Oracle Fusion Middleware User's Guide for Oracle B2B.

8. When you are done configuring the agreement, click Save and then click OK on the confirmation dialog that appears.

9. To validate the agreement, click Validate.

10. When you are ready to deploy the agreement to the application server, click Deploy.

6.3.3 Deleting a Mapset in the Oracle B2B Console

Only mapsets that are not currently being used in an agreement can be deleted.

To delete a mapset in the Oracle B2B Console

1. On the Oracle B2B Console, click Administration and then click the Mapset tab.

2. On the Mapset page, select the row containing the mapset to delete.

3. Click Delete Mapset (the X icon) above the Mapset table and then click Yes on the Confirm Delete dialog.

4. Click OK on the confirmation dialog.

6.4 Using Mapsets in Oracle SOA Suite for Healthcare Integration

Use the Oracle SOA Suite for healthcare integration user interface when you want to map different HL7 standards to one another in a healthcare integration project.

Perform the following steps to incorporate a mapset into an Oracle B2B trading partner agreement:

- 0, "Creating a Mapset in the Healthcare Integration User Interface"

- 0, "Associating a Mapset with an Endpoint"

- 0, "Deleting a Mapset in the Healthcare Integration User Interface"

6.4.1 Creating a Mapset in the Healthcare Integration User Interface

Before you begin, make sure the map file is available on the computer from which you are accessing the healthcare integration user interface, and that the required document definitions are already created in Oracle SOA Suite for healthcare integration for both of the standards you are mapping. The mapset cannot be created without these three components.

For information about creating document definitions in Oracle SOA Suite for healthcare integration, see Chapter 3, "Working with Document Types and Protocols."

To create a mapset

1. On the Oracle SOA Suite for healthcare integration user interface, click the Designer tab and then click the Configuration tab.

2. In the navigation panel on the left, select Mapset and then click Create Mapset (the plus icon).
The Create Mapset dialog appears.

3. Enter a unique name and a brief description of the mapset, and then click OK.

Figure 6-5 Create Mapset Dialog

The Mapset page appears.

4. Click Browse next to the Mapset File Location field, and then browse to and select the map file to use.
The file is validated and if the corresponding document definitions are found, information about the document protocols, versions, and types are populated in the lower portion of the page. The default source and target definition files are automatically populated for you.

Figure 6-6 Mapset Page on the Healthcare Integration User Interface

5. If you do not want to use the default version of the document definition files, do the following to override the default file selection:

1. Next to the Document Definition field you want to override (Source or Target), click Browse.

2. On the Document dialog, expand the Document Protocol tree until you see the document definition to use.

3. Select the overriding document definition, and then click OK.

6. On the Mapset page, click Apply and then click OK on the confirmation dialog that appears.

6.4.2 Associating a Mapset with an Endpoint

Once you create a mapset, you need to associate it with an endpoint to include the mapping logic in the process.

To associate a mapset with an endpoint

1. On the Oracle SOA Suite for healthcare integration user interface, click the Designer tab and then click the Configuration tab.

2. In the navigation panel on the left, expand Endpoint and double-click the endpoint you want to associate with the mapset.

3. In the row of the document type you want to map, deselect Translation.

Note:

If Translation is selected, it is ignored when used in conjunction with a mapset in the endpoint. The mapset performs the data transformation and translation is not needed.

4. In the same row, click in the Mapset field to the far right of the table, and select the mapset to use.

Figure 6-7 Mapset Selected for an Endpoint

5. Click Apply, and then click OK on the confirmation dialog that appears.

6.4.3 Deleting a Mapset in the Healthcare Integration User Interface

To delete a mapset, select the mapset in the Configuration tree and click Delete in the toolbar. You can also right-click the mapset and then select Delete.

7 Working with Internal Delivery Channels

This chapter describes how to use internal delivery channels in Oracle SOA Suite for healthcare integration. Internal delivery channels are used for communicating with backend applications, such as receiving messages from or sending them to a JMS topic or queue in a healthcare integration application.

This chapter includes the following topics:

- Section 7.1, "Introduction to Internal Delivery Channels"

- Section 7.2, "Creating Internal Delivery Channels"

- Section 7.3, "Enabling an Internal Delivery Channel"

- Section 7.4, "Deleting an Internal Delivery Channel"

- Section 7.5, "Correlating Messages Using JMS Queues"

7.1 Introduction to Internal Delivery Channels

An internal delivery channel defines how a message received from an external system (endpoint) is delivered from Oracle SOA Suite for healthcare integration to backend applications, such as JMS topics and queues, or how a message that was sent from a backend system is received by Oracle SOA Suite for healthcare integration for delivery to an external system. It defines the connection information, the transport protocol, acknowledgments, and so on. When you create an internal delivery channel, that channel is available to all endpoints. This avoids having to create a unique internal delivery channel for each endpoint.

7.2 Creating Internal Delivery Channels

If you need to send messages to an internal delivery channel, create a "send to" internal delivery channel to associate with the endpoint. If you need to receive messages from an internal delivery channel, create a "receive from" internal delivery channel.

To create an internal delivery channel

1. On the Oracle SOA Suite for healthcare integration user interface, select the Designer tab and then the Administration tab.

2. Do one of the following:

- To create an internal delivery channel for sending messages to a JMS or queue, right-click Send to Internal and then click Create.

- To create an internal delivery channel for receiving messages from a JMS or queue, right-click Receive From Internal and then click Create.

The Create dialog appears.

Figure 7-1 Create Dialog for Internal Delivery Channel (Send to)

3. On the Create dialog, fill in the following fields:

Table 7-1 New Internal Delivery Channel Properties (Send to)

Property

Description

Name

A unique name for the delivery channel.

Transport Protocol

The connection protocol for the internal delivery channel. JMS is the supported protocol

Destination Name

The JNDI name of the topic or queue to which Oracle SOA Suite for healthcare integration will send messages.

Connection Factory

The JNDI location or Java class name for the connection factory, such as jms/b2b/B2BQueueConnectionFactory.

4. Click OK.
The new internal delivery channel is added to the Administration tree under Send to Internal, and the new channel appears on the Internal Delivery Channel page.

Figure 7-2 Internal Delivery Channel Page

5. On the main Internal Delivery Channel page, you can modify any of the fields listed in Table 7-1 (except Transport Protocol).

Note:

The fields in the upper portion of the Internal Delivery Channel page (Acknowledgement Mode, Retry Interval, and Reattempt Count), are not currently used for internal delivery channels.

6. To modify the transport protocol connection settings, do the following:

1. On the main Internal Channel Delivery page, click Transport Protocol.

2. On the Transport Protocol Parameters dialog, click the Basic tab, and modify any of the properties listed in Table 7-2.

Table 7-2 Internal Delivery Channel Transport Protocol Basic Parameters

Parameter

Description

Destination name

The JNDI name of the topic or queue to which Oracle SOA Suite for healthcare integrationwill send messages.

Connection Factory

The JNDI location or Java class name for the connection factory, such as jms/b2b/B2BQueueConnectionFactory.

Is Topic

An indicator of whether the destination is a topic or a queue. Select this option if the destination is a topic.

Polling Interval

The length of time in minutes between polling attempts for messages.

3. On the Transport Protocol Parameters dialog, click the Advanced tab, and modify any of the properties listed in Table 7-3.

Table 7-3 Internal Delivery Channel Transport Protocol Advanced Parameters

Parameter

Description

Message Type

Select one of the following JMS message type options: BYTES, TEXT, or MAP.

Is Map Payload Alone

An indicator of whether the payload is sent alone as part of a JMS message of the type javax.jms.MapMessage.

Use JMS id

An indicator of whether to use the JMS message ID as the healthcare integration message ID. This facilitates correlation at the JMS level.

Destination Provider

JNDI properties that are required to connect to the target server. Use a semicolon (;) as the separator for key/value pairs. This is for enabling Oracle SOA Suite for healthcare integration to connect to JMS queues or topics available on remote servers.

User name

The user name to connect to the target server. This value is optional for JMS because Oracle SOA Suite for healthcare integration can use the configured JNDI data sources to connect to queues.

Password (and Retype Password)

The password for the above user name.

Subscriber id

An indicator of whether the JMS subscriber ID is required when JMS is communicating with a topic.

Sequencing

An indicator of whether messages need to be delivered in sequence. Select this check box for sequential delivery. This option only applies to WebLogic Server JMS (it uses the Unit-of-Order feature of WebLogic Server JMS).

7. When you are done making changes to the transport protocol, click OK on the Transport Protocol Parameters dialog.

8. When you are done making changes to the internal delivery channel, click Apply on the Internal Delivery Channel page.

7.3 Enabling an Internal Delivery Channel

Before you can use an internal delivery channel in an Oracle SOA Suite for healthcare integration project, you need to enable it. To enable it, double-click the internal delivery channel to open the Internal Delivery Channel page, and then select the Enabled option.

7.4 Deleting an Internal Delivery Channel

To delete an internal delivery channel, select the channel in the Administration tree and click Delete in the toolbar. You can also right-click the internal delivery channel and then select Delete.

7.5 Correlating Messages Using JMS Queues

You can correlate inbound and outbound messages using JMS queues, by setting A2A=true in the JMS header.

If the message ID (MSG_ID) is provided from a back end application, then MSG_ID is set to JMS Correlation ID in the healthcare integration output, otherwise the JMS Message ID is set to JMS Correlation ID in the healthcare integration output.

8 Working with Dashboards

This chapter describes Oracle SOA Suite for healthcare integration dashboards, which display endpoint-level status and volume metrics on instance data. This includes endpoint status, message counts, sequencing information, and error messages.

This chapter includes the following topics:

- Section 8.1, "Introduction to Dashboards"

- Section 8.2, "Working with System Dashboard"

- Section 8.3, "Creating and Configuring Dashboards"

- Section 8.4, "Viewing Information in Dashboards"

- Section 8.5, "Working with Sequenced Messages"

- Section 8.6, "Viewing Endpoint Error Messages"

8.1 Introduction to Dashboards

Oracle SOA Suite for healthcare integration dashboards display information about the current health of the endpoints in a healthcare integration application. You can create and configure multiple dashboards as needed to monitor the status and volume metrics for the endpoints you have defined.

The Dashboards tab reflects changes that occur in the runtime repository, such as purging runtime instance data, new messages processed, and new error messages. You can display data for various time periods, and you can manually refresh the data in real time or set the dashboard to automatically refresh at set intervals. The available time periods are configurable in the UI settings on the Administration tab.

When you first open a dashboard, based on the View Mode options, Compact and Normal, a summary of all the endpoints included in the dashboard appears. For each endpoint, you can view more detailed information about not only the status and message volume but also about the endpoint's configuration. Figure 8-1 shows endpoint summaries in the Normal mode on the Dashboard page.

Figure 8-1 Endpoint Summaries on the Dashboard

You can click the Compact option to view the Dashboard in the compact mode where only a small box filled with a color corresponding to the status and name of each endpoint. You can also adjust the width of the compact boxes to fit as many as you can. The Time Range can also be iconified to save space and it automatically reappears when you do a mouseover over the Time Range slider icon. The Show Customizer toggle button always appears on the dashboard regardless of whether the Customizer is open or not.

Figure 8-2 shows the Dashboard page in the compact mode.

Figure 8-2 Dashboard Page - Compact Mode

8.2 Working with System Dashboard

The Oracle Healthcare console provides a feature called the System Dashboard that displays a global view of status of the healthcare setup. This includes a overall view of the endpoints and internal delivery channels for the purpose of monitoring. The System Dashboard enables you to view a list of enabled as well as disabled endpoints and the ports to which these endpoints listen, if applicable. In addition, the dashboard displays the message counts. The System Dashboard also allows you to group or sort endpoints by transport protocol, outbound and inbound, or both.

Using the System Dashboard, you can view the deployed healthcare composites, which is important because internal delivery channels and composites represent the internal side of the system overview. You can also enable or disable endpoints and channels by using the System dashboard. Sections on message statistics and overall recent error list completes the System Dashboard.

You can view the System Dashboard by first clicking the plus icon in the upper right corner of the Dashboard tab, and then clicking System Dashboard.

Figure 8-3 displays a sample System Dashboard.

Figure 8-3 A Sample System Dashboard

8.2.1 Viewing System Data by Using Different Sections of the System Dashboard

Using the sections of the System Dashboard, you can view different types of system data pertaining to the a Oracle Healthcare instance.

Table 8-1 lists the different sections of the System Dashboard.

Table 8-1 Sections of the System Dashboard

Section Name

Description

Slider

The time slider at top of the System Dashboard page allows you to select time intervals for which data is collected for the graphs and tables of the dashboard.

Slide the point from to select the required time interval.

Refresh

The Refresh component at the top right corner of the dashboard allows you user to either manually refresh the page or set the interval for auto-refresh.

To enable auto-refresh, click the down arrow adjacent to the Refresh icon, select the Auto-Refresh check box, and specify the interval for auto-refresh (in seconds.)

Most Active Documents

This graph displays the most active document definitions (maximum of three document definitions at a time) and how many messages are associated with each document definition.

Most Active Endpoints

This graph displays the most active endpoints (maximum of three endpoints at a time) and how many messages are associated with each endpoint.

Recent Error Trend

This graph displays the number of errors in the specific Oracle Healthcare setup mapped against the time at which the errors occurred.

Endpoints Table

The Endpoints table displays a list of all endpoints in the Oracle Healthcare system along with the status, transport protocols, message counts, and queue counts associated with each of the endpoints.

You can perform the following actions in this table:

- Click the View button to configure the number of columns (Name, Status, Transport Protocol, and so on) that you want to show in the table (by clicking View > Columns and the required option) or detach the Endpoints table from the System Dashboard to a new window (by clicking View > Detach.)

- Select multiple endpoints, and enable or disable them by clicking the Enable or Disable buttons.

- Click the Detach button to detach the Endpoints table from the System Dashboard to a new window.

- Filter an existing endpoint by specifying a string containing some letters of the endpoint name in the Search field.

- Click an endpoint name to open a dashboard tab that displays the details for that endpoint.

- Click the message count of either Inbound or Outbound messages to open a Report tab that displays all the relevant messages.

- Sort the endpoints based on any of the column headers.

Internal Delivery Channels Table

The Internal Delivery Channels table displays a list of all the internal delivery channels in the Oracle Healthcare system along with the status, transport protocols, and delivery associated with each of the channels. Here, the channels are listed with values true or false in the Delivery column differentiating them as either Internal Delivery channels (Delivery column shows true) or Internal Listening channels (Delivery column shows false).

In this table, you can perform actions similar to the ones that you can perform in the Endpoints table.

Composites Table

The Composites table displays a list of Oracle Healthcare related composites that have been deployed in the Oracle Weblogic Server along with the status of the composites

Click the View button to configure the number of columns to be displayed in the table or to detach the Composites window .

8.3 Creating and Configuring Dashboards

Using the Dashboards tools, you can create dashboards for any combination of endpoints you have defined. You can configure the layout of the Dashboard page, specify a refresh rate, and change the endpoints for an existing dashboard.

8.3.1 Creating a Dashboard

You can create multiple dashboards in Oracle SOA Suite for healthcare integration for a single endpoint or combinations of multiple endpoints.

Note:

Whenever there are any Endpoints defined, a standard dashboard called All Endpoints is available that includes all the defined endpoints. You cannot modify and save changes to this standard dashboard.

To create a dashboard

1. On the Oracle SOA Suite for healthcare integration user interface, click the Dashboards tab.
The main Dashboards page appears.

Figure 8-4 Main Dashboards Page

2. Click the plus icon in the upper right, and select Create Dashboard.
The Create Dashboard dialog appears.

Figure 8-5 Create Dashboard Dialog

3. Enter a unique name and a description for the dashboard.

4. Under Available Endpoints, select the endpoints you want to include on the dashboard and then click the right arrow icon.
The selected endpoints appear in the Dashboard Endpoints list.

Figure 8-6 Create Dashboard Dialog with Endpoints Selected

5. Select the required Endpoint View Mode.

6. Click Create.
The new dashboard appears with summary information displayed for each endpoint about the messages processed in the past 24 hours.

8.3.2 Selecting a Default Dashboard

Once you create dashboards you can select one that automatically appears when you click the Dashboards tab. This is the default dashboard. If you do not specify a default dashboard, you can select from the list of existing dashboards when you open the Dashboards page. If you do select a default dashboard, this dashboard appears every time you open the Dashboards page.

To select a default dashboard

1. On the Oracle SOA Suite for healthcare integration user interface, click the Dashboards tab.

2. Click the down arrow next to the Selected Dashboard field, and select the dashboard that you want to make default.

Figure 8-7 Default Dashboard Selected on the Main Dashboards Page

3. Click Apply.
The selected dashboard appears. The next time you log in and select the Dashboards tab, this dashboard will automatically appear.

8.3.3 Configuring an Existing Dashboard

Once you create a dashboard, you can change the endpoints for which information is displayed, how the information appears on the dashboard, and the type of information that appears.

To configure an existing dashboard

1. If the dashboard you want to modify is not already displayed, click the plus icon in the upper right of the main Dashboards page and select the dashboard to configure.

2. When the dashboard displays, click Show Customizer.
The customizer appears on the right side of the dashboard.

Figure 8-8 Endpoint Dashboard Customizer

3. Do any of the following:

- Change the name or description of the dashboard.

- Add an endpoint by selecting it in the Available Endpoint section and clicking the right-facing arrow.

- Remove an endpoint by selecting it in the Dashboard Endpoints section and clicking the left-facing arrow.

- Reorder the endpoints by selecting an endpoint to move and clicking the up and down arrows to the right of the customizer.

4. When you are done with your changes, click Apply and then click Hide to close the customizer.

Tip:

If you do not see your changes in the dashboard after you close the customizer, click the Refresh icon.

5. To undo the changes you made, click Revert.

6. To limit the types of messages displayed on the dashboard, click the down arrow next to the Show field, and select one of the following options:

- All: Shows all types of messages.

- Running: Shows all running endpoints. Idle, disabled, and errored endpoints are not shown.

- Errors: Shows only error messages.

- Disabled: Shows only disabled endpoints.

Figure 8-9 Show Field on the Dashboards Page

7. To change the layout of the endpoints on the dashboard, change the number of columns displayed in the Columns field.

Note:

If you change the number of columns to display for a dashboard, the new value is not persisted when you logout and log back in again.

8.3.4 Refreshing a Dashboard and Setting the Auto-Refresh Rate

You can manually refresh the dashboard at any time, but you can also specify that the dashboard be automatically updated at set intervals.

To refresh a dashboard and set the auto-refresh rate

1. If the dashboard you want to modify is not already displayed, click the plus icon in the upper right of the main Dashboards page and select the dashboard to configure.

2. To refresh the dashboard, click the Refresh icon in the upper right.

3. To enable the auto-refresh option, do the following:

1. Click the down arrow to the right of the Refresh icon.

2. Specify the time interval in seconds to wait between automatically refreshing the dashboard, and then select Auto-Refresh.

3. To disable automatic refreshing, deselect the Auto-Refresh check box.

8.3.5 Deleting a Dashboard

You can delete any of the dashboards you create. Use caution when deleting dashboards. This action is irreversible.

To delete a dashboard

1. From the main Dashboards page, click the plus icon in the upper right and select Delete Dashboards.
The Delete Dashboard dialog appears.

Figure 8-10 Delete Dashboards Dialog

2. In the dashboards list, select the check box next to the dashboards you want to delete.

3. Click Delete Selected Dashboards.
The selected dashboards are deleted immediately.

8.4 Viewing Information in Dashboards

Dashboards display a variety of information. You start out viewing a summary of all the endpoints in the dashboard. This view gives you a quick picture of the status of each endpoint, the number of messages they are processing, and whether there were any errors. It also shows you when the last messages were sent or received, and when the last error occurred. This information can provide clues about which endpoints might require more detailed monitoring.

You can also view more detailed information for each endpoint, including the rate at which messages are being processed, the average message size, the number of messages sent or received, the number of errors, and any error messages. You can also access the Endpoints page directly from the dashboard so you can modify the configuration of an endpoint if needed.

8.4.1 Viewing Endpoint Summary Information in a Dashboard

A dashboard has multiple views and you can drill down from each view to get a higher level of detail about a specific endpoint, error, or message.

To view endpoint summary information

1. On the main Dashboards page, click the plus icon and then select the dashboard to view. For each endpoint, you can view the following information:

Figure 8-11 Endpoint Summary on a Dashboard

- Status: The current status of the endpoint, such as Running, Idle, Disabled, or Errors.

- Messages Sent: The number of messages sent by the endpoint in the specified time period.

- Messages Received: The number of messages received by the endpoint in the specified time period.

- Errors: The number of messages with errors for the endpoint in the given time period.

- Last Sent: The date and time the last message was sent from the endpoint.

- Last Received: The date and time the last message was received from the endpoint.

- Last Error: The date and time of the last error for the endpoint.

2. To change the time period for which the dashboard displays information, slide the pointer up or down on the time scale on the left of the page.

Figure 8-12 Sliding Timescale for Dashboard Information

3. To view the properties for a specific endpoint, click or hover over the information icon for that endpoint. (Clicking opens a pop-up window with the information; hovering only shows the information while the cursor is over the information icon.)
The Endpoint Properties dialog appears, where you can view the endpoints protocol, connection, polling, timeout, and sequencing properties.

Figure 8-13 Endpoint Properties Dialog, Accessed from a Dashboard

If the endpoint defines both inbound and outbound processing, the properties dialog has two tabs, one that displays properties for inbound and one that displays properties for outbound. If the statuses of the inbound and outbound are different, additional information about the status appears on the properties dialog.

Figure 8-14 Endpoint Properties Dialog for a Bidirectional Endpoint

For more information about endpoint properties, see Chapter 4, "Working with Endpoints.".

8.4.2 Viewing Detailed Endpoint Information in a Dashboard

From any endpoint summary view, you can drill down into more information for a specific endpoint, such as the message processing rate, the message volume broken down by message type (sent, received, or error), and the average message size. Additional information is available for errors.

To view detailed endpoint information

1. Display the dashboard you want to view on the Dashboards page.

2. For a specific endpoint, click Show More Endpoint Details (the icon on the far right in the endpoint box).
The Endpoint Details page appears.

Figure 8-15 Endpoint Details Page on a Dashboard

3. To change the time period for the displayed data, move the slider to the left or right on the timescale at the top of the page.

4. You can view the volume metrics for the endpoint as a gauge (shown above) or in tabular format. Select either Gauge or Table next to Display.
Both the gauge and the table show the following information:

- The document type.

- The number of messages received per second.

- The total number of message processed in the specified time period.

- The average size of each message.

5. Scroll down to view a graph showing the volume of sent, received, and error messages.

Figure 8-16 Graphical Representation of Message Volume

6. Scroll below the graph to view information about sequenced message processing.

Figure 8-17 Sequenced Messages Section of the Dashboard

Tip:

If you do not have the sequencing targets configured, you cannot view information about sequencing on the dashboard. For information on configuring sequencing, see Section 4.4, "Enabling Sequencing for an MLLP Endpoint."

7. Scroll to the bottom of the page to view error messages for the displayed endpoint.

8. To view a report of the messages processed, click the eyeglass icon either in the gauge or on the table. You can also view a report by clicking the eyeglass icon in the Message Processing Overview for Last 24 Hours box. Both actions open a new tab showing the report.

Figure 8-18 Endpoint Report Accessed from a Dashboard

For more information about reports and the information displayed, see Chapter 9, "Working with Reports."

8.4.3 Configuring an Endpoint from a Dashboard

The dashboard lets you access the endpoint configuration pages directly so you can view and edit the endpoint properties.

To configure an endpoint from a dashboard

1. Display the dashboard you want to view on the Dashboards page.

2. In the box for the endpoint you want to configure, click Configure This Endpoint (the wrench icon).
The Endpoint page appears.

3. Modify any of the endpoint values, as described in "Working with Endpoints."

Note:

This takes you out of the dashboard pages. To return to the dashboard you were viewing, click the Dashboards tab.

8.5 Working with Sequenced Messages

The Sequenced Messages section of an endpoint dashboard provides information about the health of the sequenced message queue. In this section, you can view information about the messages that are pending in the sequenced message queue. If there is no information in this section, then sequenced messages are processing successfully. If messages are backed up, you can view the necessary information and take steps to unblock the queue.

The information you can view for the queue includes the number of messages in the queue, the time a message was sequenced, the time elapsed since sequencing was initiated for the message, the sequence state, the message processing state, and the document type. There is also an indicator of the overall delivery status for the queue. Possible statuses are:

- Paused: Indicated by a red traffic light, this means that sequencing has been manually paused or blocked when the message at the front of the queue has encountered a transport error.

- Slow: Indicated by a yellow traffic light, this means that the elapsed time for the message at the front of the queue has exceeded the Slow Threshold for Sequencing property in the UI Settings.

- Running: Indicated by a green traffic light, this indicates that sequenced messages are being processed normally.

Messages can get backed up in the queue due to sequencing errors, message errors, or message processing delays. The Sequenced Messages section gives you the information you need to correct these problems. You can view information about messages in the queue to determine the cause of the stoppage. Once you find the source, you can reprocess errored messages or discard messages from the queue.

To work with sequenced messages

1. Display the dashboard you want to view on the Dashboards page.

2. For a specific endpoint, click Click to show Maximized Endpoint Details (the icon on the far right in the endpoint box).
The Maximized Endpoint Details page appears.

3. Scroll down to the Sequenced Messages section.
If there are messages waiting in the sequencing queue, you can view them here.

Figure 8-19 Sequenced Messages Section of the Endpoint Dashboard

4. The waiting messages appear as a carousel of note boxes. Click through the boxes or use the slider underneath the messages to view information about each message.

5. To view a report of any of the messages, click the eyeglass icon in the upper right of that message's box.
The report page appears for the selected message.

Figure 8-20 Message Report Accessed from the Sequenced Messages Section

6. When sequencing is blocked by a message, you can do any of the following:

- View the message report, as shown above, and use the Purge or Resubmit functions of the reports page to handle the message.

- In the Sequenced Message section, reprocess an errored message by clicking the Reprocess an Errored Message icon in the upper right of the message box.

- In the Sequenced Messages section, discard the blocked message by clicking the Discard Message icon in the upper right of the message box. Discarding a message only removes it from the sequenced message queue, and does not remove it from the instance data shown in the reports.

7. To pause sequenced message processing, click the Pause button in the upper right of the Sequenced Messages section.

8. To resume sequenced message processing, click the Resume button in the upper right of the Sequenced Messages section.

8.6 Viewing Endpoint Error Messages

When a message for a specific endpoint generates an error, you can access information about the error from the Dashboards page.

Note:

When a transport error occurs in an endpoint, the status bar for the endpoint changes to red and the status changes to Errors. This does not indicate an error in the business message processing, which is described in the following procedure, though message processing errors can include transport errors as well. Message processing errors are indicated by the number in the Error field of the endpoint summary.

Figure 8-21 Endpoint Summary with Errors

To view endpoint error messages

1. On the endpoint summary dashboard page, click Show More Endpoint Details for the endpoint that shows messages with errors.

2. On the endpoint details page, scroll to the bottom of the page to view the list of error messages.

Figure 8-22 Endpoint Error Messages List

3. To view a report of the error, click the eyeglass icon to the right of the message ID.
The Reports page appears, as shown below.

Figure 8-23 Endpoint Error Message Report

4. To view more details about the error, collapse the upper portion of the window by clicking the up arrow beneath the message list or click Pin Current Message Details Into a New Tab to open the details in a new tab.
The business message details appear.

Figure 8-24 Business Message Details

For more information about reports and the information displayed, see Chapter 9, "Working with Reports."

5. In the flow diagram, click the red X icon that indicates where the error occurred. The Error Details appear below the diagram.

Figure 8-25 Endpoint Transport Error Details

9 Working with Reports

This chapter describes the reporting features of Oracle SOA Suite for healthcare integration. The configurable reports display the real-time status of message processing through the healthcare integration application based on the criteria you specify.

This chapter includes the following topics:

- Section 9.1, "Introduction to Reports"

- Section 9.2, "Creating and Configuring Reports"

- Section 9.3, "Viewing Reports and Report Information"

- Section 9.4, "Working with Reports for Unassociated Messages"

- Section 9.5, "Working with Error Messages"

- Section 9.6, "Purging Messages from the Repository"

9.1 Introduction to Reports

The Reports page of the Oracle SOA Suite for healthcare integration user interface lets you view the status of the messages being processing through Oracle Healthcare components in real-time. You can view all messages, or you can narrow down the messages displayed by a variety of criteria, including endpoints, date ranges, document information, and payload fields.

Several reports are predefined on the Oracle Healthcare user interface. These are Wire Message report, Unassociated Wire Message report, Business Message report, Application Message report, and Unassociated Application Message report. You can create additional reports based on more specific criteria to narrow down the types of messages displayed.

Each report is divided into four sections:

- A report configuration bar

- The message list

- A graphical depiction of the message flow

- Message details for the selected message

If you select multiple messages from the report, a summary of information for the selected messages appears in place of the flow diagram.

Oracle Healthcare provides a set of predefined reports based on the following report types that you can access by clicking the plus icon on the top right corner of the Reports home page:

- General Business Message reports: Lists all the Business Messages that have been exchanged from the beginning or in a give time range. You can customize these reports by using the Message Report Filter Customizer.

- General Application Message reports: Lists all the Application Messages that have been exchanged. You can customize the report by using the Message Report Filter Customizer.

- General Wire Message reports: Lists all the Wire Messages that have been exchanged. You can customize the report by using the Message Report Filter Customizer.

- Unassociated Application Message reports: Lists all the Application Message reports that display Application Messages without any associated Business Messages. You can customize these reports by using the Message Report Filter Customizer.

- Unassociated Wire Message reports: Lists all the Wire Message reports that display Wire Messages without any associated Business Messages. You can customize these reports by using the Message Report Filter Customizer.

See Section 9.4, "Working with Reports for Unassociated Messages" for more information on Unassociated Message reports.

The customized reports are displayed in the Oracle Healthcare console under their respective report types as shown in Figure 9-1.

Figure 9-1 Types of Reports

Figure 9-2 shows an example of a General Business Message report as displayed in the Reports tab.

Figure 9-2 Reports Page Showing a Predefined Business Message Report

Figure 9-3 shows an example of a General Wire Message report as displayed in the Reports tab.

Figure 9-3 Reports Page Showing a Predefined Wire Message Report

Figure 9-4 shows an example of a General Application Message report as displayed in the Reports tab.

Figure 9-4 Reports Page Showing a Predefined Application Message Report

In the message list, each message is marked with an icon that provides processing information about the message. An envelope icon indicates normal processing; a green arrowhead over the envelope indicates the message was resubmitted; and a red square with an "X" over the envelope indicates an error.

9.1.1 About the Message Report Filter Customizers

You use the three Message Report Filter Editors (Wire, Business, and Application) to create reports and to edit existing reports. The report editors allow you to define a wide variety of criteria for the messages that are displayed in the report, including a time range, endpoint, protocol, state, message status, and document definition information. You can also use advanced options, which include correlation fields, SOA composite fields, message IDs, and so on.

Figure 9-5 displays a sample Business Message Report Customizer.

Figure 9-5 Business Message Report Filter Customizer

For most filters, you need to select an operator that specifies how to evaluate the value you specify for the filter. You can also specify whether or not the search is case-sensitive. Most filters support the following operators to act against the value you specify: Any, Equals, Like, Not Equal, or Not like. For the Like and Not Like operators, you can use SQL wildcard characters in the value. SQL wildcard characters include:

- % (percent): Represents zero or more unknown characters

- _ (underscore): Represents a single character

- [charlist]: A list of characters; the unknown value is any character in the list

- [^charlist] or [!charlist]: A list of characters; the unknown value is not a character in the list

For most string-based criteria, you can specify whether or not the search should be case sensitive by selecting or deselecting Ignore case next to the field. Use the links next to Filter Conditions to move between sections in the filter conditions list.

9.1.2 About Resubmitting Messages

When messaging errors are internal to Oracle SOA Suite for healthcare integration, you can correct the problem and resend the message. For example, if a message is sent to an endpoint that is not configured correctly, correct the error and use the resubmit feature for application messages or wire messages.

Resubmitting an application message for an outbound message clones the message, assigns the new message a status of RESUBMITTED, and attempts to deliver the clone. In addition, the RESUBMIT_COUNT of the original application message is incremented by 1. The RESUBMIT_REF_TO of the cloned message is set to the ID of the original application message as well. If the resubmitted application message is part of the batch message, the state of the associated wire message is set to RESUBMITTED as well. Resubmitting this type of message is helpful when the document configuration is not as per requirement and the message must be restructured with updated settings.

Resubmitting an application message for an inbound message sets the status of the message to RESUBMITTED and attempts to deliver the message again to the back-end application. Resubmitting this type of message is useful when the back-end application is down and the delivery must be retried.

Resubmitting a wire message for an outbound message sets the status of the message to RESUBMITTED and attempts to redeliver only the previously processed message. There is no repackaging or other message transformation. This is helpful when the problem was with the delivery endpoint (for example, the receiver's server is down and unable to receive the message).

Resubmitting a wire message for an inbound message clones the wire message, assigns the new message a status of RESUBMITTED, and attempts to deliver the message. In addition, the RESUBMIT_COUNT of the original wire message is incremented by 1. The RESUBMIT_REF_TO of the cloned message is set to the ID of the original wire message as well. The message statuses of the business and application messages are also set to RESUBMITTED. The functional acknowledgment is not returned to the remote endpoint even though the endpoint expects it. This is useful when the document settings are not correct and the message must be translated and validated again.

9.1.3 Important Note About Clustered Environments

In a clustered environment, if system time stamps are not synchronized for all nodes in the cluster, you might see message time stamps that look incorrect, but are not. For example, given an unsynchronized, multi-node cluster, if an outbound message is received on one node, but the reply is sent from another node, it is possible for a report to show message receipt at 4 a.m., but an acknowledgment sent at 3:55 a.m.

9.2 Creating and Configuring Reports

Oracle SOA Suite for healthcare integration provides several predefined reports for you to get started with. These reports are filtered only by a time range that you can configure under Designer > Administration > Settings > UI > Reports > Time Range. See Section 13.2, "Configuring the User Interface Settings" for more details. You can create additional reports that further filter messages by criteria such as endpoint, message ID, document properties, composite properties, transport protocol properties, and key payload fields. You can also use the predefined reports as a basis, and either modify them or save them as new reports.

9.2.1 Creating Business Message Reports

Although you have a predefined Business Message report, you can create additional reports to meet your specific requirements.

To create a Business Message report

1. On the Oracle SOA Suite for healthcare integration user interface, click the Reports tab.
The Reports Welcome page appears when there are no opened reports.

Figure 9-6 Reports Welcome Page

2. Click the plus icon in the upper right, and select Create Report.

3. On the Create Message Report dialog, enter a name for the report, select General Business Message Reports from the Report Type list, and click Create as shown in Figure 9-7.

Figure 9-7 Create Message Report

The report appears with the Message Report Filter Customizer displayed.

4. On the Message Report Filter Customizer, enter any of the filter criteria described in Table 9-1.

Note:

When a Wire/Business/Application Message Report is first created (or cloned by doing a Save As New), no search is automatically done when the report is first opened. You need to explicitly click the Search button.

Use the links next to Filter Conditions to quickly move between the different sections in the filter conditions list.

Note:

Multiple conditional operators are supported for most string criteria. For more information about using Any, Equals, Like, Not Equal, or Not Like, see Section 9.1.1, "About the Message Report Filter Customizers."

Table 9-1 Business Message Report Customizer Options

Filter

Description

Name

The name of the report.

Description

A brief description of the report.

Match

An indicator of whether the search criteria are joined by an AND or OR operator. Select Match all of the following conditions to use AND; select Match any of the following condition to use OR.

Message ID (Business)

The business message ID of the message to display. Select the operator and then enter an appropriate value for a message ID.

Any

Does not narrow the report by any date range, and displays messages from all dates and times.

Last

Narrows the report down to a range of most recent dates or times. For example, you can select the past 12 hours, past five days, or past two weeks. Slide the pointer on the sliding scale to select a time range. You can modify the Enabled Time Slider Periods under UI Settings.

Range

Narrows the report down to the range of dates you specify. In the From or To field, or in both fields, provide a date and time in the format shown (MM/DD/YYYY HH:MM:SS AM/PM) or click the Select Date and Time icon to select a date and specify the time.

To search for all messages after a specific date, only enter a date for the From field. To search for all messages earlier than a specific date, only enter a date in the To field. To search for all messages within a range of dates, enter dates in both the From and To fields. To exclude a specific time range, enter the first date in the range to exclude in the To field and enter the last date in the range to exclude in the From field. You must select the Match any of the following conditions indicator to use this excluded range. The search returns all messages received.

For both the from and to dates, select Inclusive to include the specified dates in the search, or deselect Exclusive to exclude those dates from the search.

Direction

The direction of the messages to display. Select from Any, Equals, or Not Equals, and then click in the field on the right to select a direction (inbound or outbound) from the list

Endpoint

The endpoint from where the messages are received or to which the messages are delivered. Select the operator and then enter the name of a defined endpoint.

State

The state of the messages to display. Select from Any, Equals, or Not Equals, and then click in the field on the right to select one or more message states from the list.

Document

The following three fields specify document properties. These three fields control what is shown in the Document Type column in the reports table. For any of these fields, select Ignore case if you do not want the search to be case sensitive.

- Protocol

The document protocol of the messages to display. Select the operator and then enter the document protocol. For HL7 messages, enter HL7.

- Version

The document protocol version of the messages to display. Select the operator and then enter the version. For example, for HL7 2.6 messages, enter 2.6.

- Type

The document protocol type of the messages to display. Select the operator and then enter the version. For example, for HL7 ADT_A04 messages, enter ADT_A04.

Payload Key Fields

Name and value pairs that narrow the search down by the contents of a field in a message. For each field name you enter, enter a corresponding value for the field. For any of the names or values, select the operator.

These fields can only be used if they are defined on the XPath page for the document definition. For Name fields, enter the name specified on the XPath page, which represents a field in the message. For Value fields, enter the expected value of the corresponding field.

When you create your document definitions, you can specify up to three fields in the message as payload key fields. These fields are defined by a unique name and an XPath expression that locates the field in the message. For example, you might name a field LastName and specify the XPath expression for the last name field in the PID segment of an HL7 A03 message. You can similarly define correlation fields for a document definition.

If you have defined either correlation fields or payload key fields for a document definition, then you can use these fields as filters for business message reports. In the filter editor, these filters are defined by name and value pairs. You use the unique name you gave the field when you created the document definition, and then specify what the value should be for that field in the messages you want to include on the report.

Document

- Document Definition

The document definition used by the messages to display. Select the operator and then enter the name of a defined document definition.

- Interchange Control Number

A unique identifier for the interchange. This number is used to track messages, to find duplicate or missing transmissions, or to find messages that are out of sequence.

- Group Control Number

A unique identifier for the group. This number is used for auditing, to find duplicate or missing groups, or to find groups that are out of sequence.This number is referenced by the functional acknowledgment.

- Transaction Set Control Number

A unique identifier for the transaction set. The functional acknowledgment references this number for transaction set acknowledgment.

Composite

- Transport Protocol Name

The name of the transport protocol used by the Oracle SOA composite application.

- Transport Protocol Version

The version of the transport protocol used by the Oracle SOA composite application

- ECID

The execution context ID. The ECID enables end-to-end message tracking.

- Composite Instance ID

The Oracle SOA composite instance ID.

- Composite Name

The name of the Oracle SOA composite application in Oracle JDeveloper.

- Service Name

The name of the healthcare integration service binding component in the Oracle SOA composite application.

- Reference Name

The name of the healthcare integration reference binding component in the Oracle SOA composite application.

- Domain Name

The name of the WebLogic domain on which the Oracle SOA composite application is deployed.

- Composite Version

The version of the Oracle SOA composite application in Oracle JDeveloper.

Correlation

- Correlation From XPath Name

The name of the correlation field for initiating the correlation This and the remaining correlation fields can only be used if they are defined on the Correlation page for the document definition. For usage information, see Payload Key Fields in Table 9-1.

- Correlation From XPath Value

The value of the above field.

- Correlation To XPath Name

The name of the second field for the correlation.

- Correlation To XPath Value

The value of the above field.

Error

- Error Code

The error code for error message to display on the report.

- Error Text

The text of an error message to display on the report.

Message

- Application Message ID

The unique identifier for the application message to display in the report.

- Protocol Message ID

The unique protocol message identifier for messages displayed in the report.

- Native Message Size

The size of the original message prior to being translated. Select from Any, Equals, Not Equal, Less than, Less than or equals, Greater than, or Greater than or equals, and provide a numerical value.

- Translated Message Size

The size of the message after it is translated. Select from Any, Equals, Not Equal, Less than, Less than or equals, Greater than, or Greater than or equals, and provide a numerical value.

5. To revert any unsaved changes you made to the report filters, click Revert.

6. When you are done specifying report filters, do any of the following:

- To test your filter criteria, click Search, and then click the Show/Hide Filter toggle button.

- To save the changes you made to the filter criteria for the report, click Save.

Note:

You cannot save changes made to the standard reports (such as General Business Message Report). You can only click the Save As New button that is enabled only when the name of the report has been changed from its standard form.

Figure 9-8 displays a custom Business Message Report, which lists all the Business Messages exchanged by In_Patient_Admission endpoint in the last 24 hours.

Figure 9-8 A Custom Business Message Report

You can sort the messages based on any of the report columns by clicking the column headers.

9.2.2 Creating Wire Message Reports

Apart from the predefined Wire Message reports, you can create customized Wire Message reports that covers Wire Messages coming from and going to an external endpoint. Most Wire Messages have associated Business Messages, which is reflected in the Message Flow diagram in the report.

To create a Wire Message report

1. Perform Steps 1 and 2 from Section 9.2.1, "Creating Business Message Reports."

2. On the Create Message Report dialog, enter a name for the report, select General Wire Message Reports from the Report Type list, and click Create.
The report appears with the Message Report Filter Customizer displayed as shown in Figure 9-9.

Figure 9-9 Wire Message Report Filter Customizer

3. On the Message Report Filter Customizer, enter any of the filter criteria described in Table 9-2.

Note:

Multiple conditional operators are supported for most string criteria. For more information about using Any, Equals, Like, Not Equal, or Not Like, see Section 9.1.1, "About the Message Report Filter Customizers."

Table 9-2 Wire Message Report Filter Customizer Options

Filter

Description

Name

The name of the report.

Description

A brief description of the report.

ID

The Wire Message ID of the message to display. Select the operator and then enter all or part of a message ID.

Any

Does not narrow the report by any date range, and displays messages from all dates and times.

Last

Narrows the report down to a range of most recent dates or times. For example, you can select the past 12 hours, past five days, or past two weeks. Slide the pointer on the sliding scale to select a time range.

Range

Narrows the report down to the range of dates you specify. In the From or To field, or in both fields, provide a date and time in the format shown (MM/DD/YYYY HH:MM:SS AM/PM) or click the Select Date and Time icon to select a date and specify the time.

To search for all messages after a specific date, only enter a date for the From field. To search for all messages earlier than a specific date, only enter a date in the To field. To search for all messages within a range of dates, enter dates in both the From and To fields. To exclude a specific time range, enter the first date in the range to exclude in the To field and enter the last date in the range to exclude in the From field. You must select the Match any of the following conditions indicator to use this excluded range. The search returns all messages received.

For both the from and to dates, select Inclusive to include the specified dates in the search, or deselect Exclusive to exclude those dates from the search.

Direction

The direction of the messages to display. Select from Any, Equals, or Not Equal, and then click in the field on the right to select a direction (inbound or outbound) from the list

Transport Protocol

The transport protocol of the messages to display. Select from Any, Equals, Like, Not equal, or Not like, and then enter the name of a defined transport protocol. Select Ignore case if you do not want the search to be case sensitive.

Transport Protocol Version

The transport protocol version of the messages to display. Select from Any, Equals, Like, Not equal, or Not like, and then enter the name of a defined transport protocol version. Select Ignore case if you do not want the search to be case sensitive.

URL

The TCP endpoint URL of the messages to display. Select from Any, Equals, Like, Not equal, or Not like, and then enter a defined URL value. Select Ignore case if you do not want the search to be case sensitive.

State

The state of the messages to display. Select from Any, Equals, Like, Not equal, or Not like, and then click in the field on the right to select one or more message states from the list.

Message Size (bytes)

The size of the messages (in bytes) to display. Select from Any, Equals, Not equal, Less than, Less than or equals, or Greater than, or Greater than or equals, and then enter a defined message size.

Resubmit Count

The number times a message (to be displayed) has been resubmitted. Select from Any, Equals, Not equal, Less than, Less than or equals, or Greater than, or Greater than or equals, and then enter a defined count.

Last Resubmitted Date

The date when a message (to be displayed) was last resubmitted. Select from the Any, Last, or Range options.

4. To revert any unsaved changes you made to the report filters, click Revert.

5. When you are done specifying report filters, do any of the following:

- To test your filter criteria, click Search, and then click the Show/Hide Filter toggle button.

- To save the changes you made to the filter criteria for the report, click Save As New.

Figure 9-10 displays a custom Wire Message Report, which lists all the inbound Wire Messages in the last 24 hours.

Figure 9-10 A Custom Wire Message Report

You can sort the messages based on any of the report columns by clicking the column headers.

9.2.3 Creating Application Message Reports

Apart from the predefined Application Message reports, you can create customized Application Message reports that covers Application Message going to or coming from the Fabric/Composite layer. Most Application Messages coming into Oracle Healthcare runtime result in corresponding Business Messages, which is reflected in the Message Flow diagram in the report.

To create a Wire Message report

1. Perform Steps 1 and 2 from Section 9.2.1, "Creating Business Message Reports."

2. On the Create Message Report dialog, enter a name for the report, select General Application Message Reports from the Report Type list, and click Create.
The report appears with the Message Report Filter Customizer displayed as shown in Figure 9-11.

Figure 9-11 Application Message Report Filter Customizer

3. On the Message Report Filter Customizer, enter any of the filter criteria described in Table 9-3.

Note:

Multiple conditional operators are supported for most string criteria. For more information about using Any, Equals, Like, Not Equal, or Not Like, see Section 9.1.1, "About the Message Report Filter Customizers."

Table 9-3 Application Message Report Filter Customizer Options

Filter

Description

Name

The name of the report.

Description

A brief description of the report.

ID

The Wire Message ID of the message to display. Select the operator and then enter all or part of a message ID.

Any

Does not narrow the report by any date range, and displays messages from all dates and times.

Last

Narrows the report down to a range of most recent dates or times. For example, you can select the past 12 hours, past five days, or past two weeks. Slide the pointer on the sliding scale to select a time range.

Range

Narrows the report down to the range of dates you specify. In the From or To field, or in both fields, provide a date and time in the format shown (MM/DD/YYYY HH:MM:SS AM/PM) or click the Select Date and Time icon to select a date and specify the time.

To search for all messages after a specific date, only enter a date for the From field. To search for all messages earlier than a specific date, only enter a date in the To field. To search for all messages within a range of dates, enter dates in both the From and To fields. To exclude a specific time range, enter the first date in the range to exclude in the To field and enter the last date in the range to exclude in the From field. You must select the Match any of the following conditions indicator to use this excluded range. The search returns all messages received.

For both the from and to dates, select Inclusive to include the specified dates in the search, or deselect Exclusive to exclude those dates from the search.

Direction

The direction of the messages to display. Select from Any, Equals, or Not Equal, and then click in the field on the right to select a direction (inbound or outbound) from the list

State

The state of the messages to display. Select from Any, Equals, Like, Not equal, or Not like, and then click in the field on the right to select one or more message states from the list.

Message Size (bytes)

The size of the messages (in bytes) to display. Select from Any, Equals, Not equal, Less than, Less than or equals, or Greater than, or Greater than or equals, and then enter a defined message size.

Document

- Protocol

The document protocol of the messages to display. Select the operator and then enter the document protocol. For HL7 messages, enter HL7.

- Version

The document protocol version of the messages to display. Select the operator and then enter the version. For example, for HL7 2.6 messages, enter 2.6.

- Type

The document protocol type of the messages to display. Select the operator and then enter the version. For example, for HL7 ADT_A04 messages, enter ADT_A04.

- Document Definition

The document definition used by the messages to display. Select the operator and then enter the name of a defined document definition.

Composite

- ECID

The execution context ID. The ECID enables end-to-end message tracking.

- Domain Name

The name of the WebLogic domain on which the Oracle SOA composite application is deployed.

- Composite Name

The name of the Oracle SOA composite application in Oracle JDeveloper.

- Composite Version

The version of the Oracle SOA composite application in Oracle JDeveloper.

- Composite Instance ID

The Oracle SOA composite instance ID.

- Service Name

The name of the healthcare integration service binding component in the Oracle SOA composite application.

- Reference Name

The name of the Oracle Healthcare reference binding component in the Oracle SOA composite application.

Resubmit Count

The number times a message (to be displayed) has been resubmitted. Select from Any, Equals, Not equal, Less than, Less than or equals, or Greater than, or Greater than or equals, and then enter a defined count.

Last Resubmitted Date

The date when a message (to be displayed) was last resubmitted. Select from the Any, Last, or Range options.

4. To revert any unsaved changes you made to the report filters, click Revert.

5. When you are done specifying report filters, do any of the following:

- To test your filter criteria, click Search, and then click the Show/Hide Filter toggle button.

- To save the changes you made to the filter criteria for the report, click Save AS New.

Figure 9-12 displays a custom Application Message Report, which lists all the Application Messages exchanged in the last 24 hours having status as Complete.

Figure 9-12 A Custom Application Message Report

You can sort the messages based on any of the report columns by clicking the column headers.

9.2.4 Specifying a Default Report

You can select one report that automatically appears when you click the Reports tab. This is the default report.

To specify a default report

1. On the Oracle SOA Suite for healthcare integration user interface, click the Reports tab. The Reports Welcome page appears when there are no opened reports.

2. Click the down arrow next to the Selected Report field, and select the report that you want to make default.

3. Click Apply.
The selected report appears. The next time you select the Reports tab, this report will automatically appear.

9.2.5 Configuring Reports

Once you create a report, you can use the Message Report Filter Customizer to modify the filter criteria for the report. You can also create a report using an existing report as a template.

To configure a report

1. With the report you want to configure displayed on the Reports tab, click Show Filter.
The Message Report Filter Customizer appears.

Figure 9-13 Message Report Filter Customizer

2. Modify any of the filters described in Table 9-1, Table 9-2, or Table 9-3 based on the report type.

3. To revert any unsaved changes you made to the report filters, click Revert.

4. When you are done specifying report filters, do any of the following:

- To test your filter criteria, click Search, and then click the Show/Hide Filter toggle button.

- To save the changes you made to the filter criteria for the report, click Save As New.

9.2.6 Refreshing a Report and Setting the Auto-Refresh Rate

You can manually refresh the displayed report at any time, but you can also specify that the report be automatically updated at set intervals. Note that the auto-refresh rate is only activated and configured for the current session. If you close and then re-open a report, the auto-refresh option is disabled.

To refresh a reports and set the auto-refresh rate

1. If the report you want to monitor is not already displayed, click the plus icon in the upper right of the main Reports page and select the report to configure.

2. To refresh the report, click the Refresh icon in the upper right.

3. To enable the auto-refresh option, do the following:

1. Click the down arrow to the right of the Refresh icon in the report toolbar.

2. Specify the time interval in seconds to wait between automatically refreshing the report, and then select the Auto-Refresh check box.

3. To disable automatic refreshing, deselect the Auto-Refresh check box.

9.2.7 Deleting Reports

You can delete any of the user-created reports if you have the Administrator role. You can also delete any of the predefined reports, but use caution when doing this because this action is irreversible.

To delete a report

1. From the main Reports page, click the plus icon in the upper right and select Delete Reports.
The Delete Business Message Reports dialog appears.

Figure 9-14 Delete Business Message Reports Dialog

2. By default, only the user-created reports appear in the list. To include predefined reports, select Include Standard Group. This only pertains to standard reports imported from previous versions of the Oracle Healthcare console such as All, Last 24 Hours, Last 2 Weeks, and so on.

3. In the reports list, select the check box next to the reports you want to delete.

4. Click Delete Selected Reports or click Cancel to close the dialog box without deleting any reports.

9.3 Viewing Reports and Report Information

When you first open a report, a list of messages matching the report criteria appears on the Reports tab. This list shows summary information for each message including the following:

- Message ID

- Created Date and Time

- Direction

- Endpoint

- State

- Document Type

You can select any of the messages in the list to view more detailed information and you can view a summary of multiple messages, as described in the following:

- "Viewing a Business Message Instance"

- "Viewing a Wire Message"

- "Viewing an Application Message"

- "Viewing the Flow Trace in Oracle Enterprise Manager"

- "Viewing Overview Information for Multiple Messages"

If you do not have permissions to view the document type of a message, certain details are hidden from view. The option to download information is disabled unless you have the required permissions.

9.3.1 Viewing a Business Message Instance

Business Messages include instance information for a document protocol, including the endpoint name, the message direction, the message ID, the state, the transport protocol and document protocol, and message details.

To view a business message instance

1. Display a report on the Reports page.

2. In the messages list, select the message for which you want to view instance data.
The message flow diagram appears below the message list as shown in Figure 9-15.

Figure 9-15 Business Message Flow

3. To view the message details in a larger area, click Business Message in the message flow diagram and then click the Collapse Pane icon beneath the message list. You can also click Pin Current Message Details Into a New Tab to open a new page containing the detailed information.
The message details appear as shown in Figure 9-16.

Figure 9-16 Business Message Details

4. Expand or collapse sections of the business message by clicking the arrow icon next to the section you want to expand or collapse.

5. To download information, click Download As XML or Download as Text in the section you want to download.

Note:

This option is not available in all sections.

6. If you collapsed the message list pane, click Restore Pane above the message flow diagram to return to the message list.

9.3.2 Viewing a Wire Message

Wire messages are the native format of data sent into or out from an endpoint. Wire message details include message IDs, communication and protocol information (such as the transport binding and header details), payload message content, packed message content, and security information.

To view a wire message

1. Display a report on the Reports page.

2. In the messages list, select the message for which you want to view instance data.
The message flow diagram appears below the message list as shown in Figure 9-17.

Figure 9-17 Wire Message Flow

3. To view the message details in a larger area, click Wire Message in the message flow diagram and then click the Collapse Pane icon beneath the message list. You can also click Pin Current Message Details Into a New Tab to open a new page containing the detailed information.
The message details appear as shown in Figure 9-18.

Figure 9-18 Wire Message Details

4. Expand or collapse sections of the Wire Message by clicking the arrow icon next to the section you want to expand or collapse.

5. To download information, click Download As XML or Download as Text in the section you want to download.

Note:

This option is not available in all sections.

6. If you collapsed the message list pane, click Restore Pane above the message flow diagram to return to the message list.

9.3.3 Viewing an Application Message

Application messages provide information related to the SOA composite if a back-end composite application sent or received the message, including the composite name, version, instance ID, and so on.

To view an application message

1. Display a report on the Reports page.

2. In the messages list, select the message for which you want to view instance data.
The message flow diagram appears below the message list as shown in Figure 9-19.

Figure 9-19 Application Message Flow

3. To view the message details in a larger area, click Application Message in the message flow diagram and then click the Collapse Pane icon beneath the message list. You can also click Pin Current Message Details Into a New Tab to open a new page containing the detailed information.
The message details appear as shown in Figure 9-20.

Figure 9-20 Application Message Details

4. Expand or collapse sections of the application message by clicking the arrow icon next to the section you want to expand or collapse.

5. To download information, click Download As XML or Download as Text in the section you want to download.

Note:

This option is not available in all sections.

6. If you collapsed the message list pane, click Restore Pane above the message flow diagram to return to the message list.

9.3.4 Viewing the Flow Trace in Oracle Enterprise Manager

Oracle Healthcare reports provide links for each message to the flow trace of the composite in Oracle Enterprise Manager. Clicking the link automatically opens Oracle Enterprise Manager to the correct Flow Trace page.

To view the flow trace in Oracle Enterprise Manager

1. Display a report on the Reports page.

2. In the messages list, select the message for which you want to view the flow trace.
The message flow diagram appears below the message list.

Figure 9-21 Oracle Healthcare Message Flow

3. Click Composite in the message flow diagram.
The Login page of Oracle Enterprise Manager opens in a separate browser tab or window.

4. Enter your login information for Oracle Enterprise Manager and then click Login.
The flow trace appears for the selected message as shown in Figure 9-22.

Figure 9-22 Message Flow Trace in Oracle Enterprise Manager

9.3.5 Viewing Overview Information for Multiple Messages

You can view a summary of information for multiple selected messages in the messages list of a report. This gives you a quick view of all selected messages, including the number of messages processed, the number of endpoints and document types used, the number of errors, the number of processed messages, and so on.

To see an overview of multiple messages

1. Display a report on the Reports page.

2. In the messages list, select the messages for which you want to view summary data by clicking the first message that you want to delete, press Shift, and then click the last message of the desired range.
An overview of the selected messages appears beneath the list as shown in Figure 9-23.

Figure 9-23 Multiple Messages Selected for a Report

3. From here you can purge or resubmit the selected messages.
For more information, see "To resubmit multiple messages" or "To purge messages from the repository".

9.4 Working with Reports for Unassociated Messages

Sometimes, Wire Messages and Application Messages may not have any associated Business Messages. These messages are categorized as unassociated messages and can be viewed in Unassociated Wire Message reports and Unassociated Application Message reports.

9.4.1 Working with Unassociated Wire Messages

A burst of incoming messages from an external endpoint results in over-burdening the Oracle Healthcare runtime processing capability. These messages then gets temporarily backlogged and marked as PROCESSING. As a result of which, these Wire Messages do not have any associated Business Messages. Immediate ACKs generated by an inbound HL7 MLLP endpoint also results in Wire Messages without any associated Business Messages.

9.4.1.1 Creating Unassociated Wire Message Reports

You can create an Unassociated Wire Message report in a way similar to creating General Wire Message reports.

To create an unassociated wire message report

1. Perform Steps 1 and 2 from Section 9.2.1, "Creating Business Message Reports."

2. On the Create Message Report dialog, enter a name for the report, select Unassociated Wire Message Reports from the Report Type list, and click Create.
The report appears with the Message Report Filter Customizer displayed.

3. On the Message Report Filter Customizer, enter any of the filter criteria described in Table 9-2.

Note:

Multiple conditional operators are supported for most string criteria. For more information about using Any, Equals, Like, Not Equal, or Not Like, see Section 9.1.1, "About the Message Report Filter Customizers."

4. To revert any unsaved changes you made to the report filters, click Revert.

5. When you are done specifying report filters, do any of the following:

- To test your filter criteria, click Search, and then click the Show/Hide Filter toggle button.

- To save the changes you made to the filter criteria for the report, click Save.

Figure 9-24 displays an Unassociated Wire Message Report, which lists all the outbound unassociated Wire Messages in the last 24 hours.

Figure 9-24 An Unassociated Wire Message Report

You can sort the messages based on any of the report columns by clicking the column headers.

9.4.1.2 Viewing an Unassociated Wire Message

You can view an unassociated Wire Message from an Unassociated Wire Message report.

To view a wire message

1. Display an unassociated Wire Message report on the Reports page.

2. In the messages list, select the message for which you want to view instance data.
The message flow diagram appears below the message list as shown in Figure 9-25.

Figure 9-25 Unassociated Wire Message Flow

Note:

The unavailable Business or Application Message icons are rendered as disabled in the message flow.

3. To view the message details in a larger area, click Wire Message in the message flow diagram and then click the Collapse Pane icon beneath the message list. You can also click Pin Current Message Details Into a New Tab to open a new page containing the detailed information.

4. Expand or collapse sections of the unassociated Wire Message by clicking the arrow icon next to the section you want to expand or collapse.

5. To download information, click Download As XML or Download as Text in the section you want to download. However, because the message does not have any associated Business Message, Payload does not contain any data.

Note:

This option is not available in all sections.

6. If you collapsed the message list pane, click Restore Pane above the message flow diagram to return to the message list.

9.4.2 Working with Unassociated Application Messages

A burst of Application Messages emitted by Fabric/Composite layer results in over-burdening the Oracle Healthcare runtime processing capacity. These messages then gets temporarily backlogged and marked as PROCESSING. As a result of which, these Application Messages do not have any associating Business Messages. Severe errors encountered by an outbound message from Fabric/Composite layer also results in Application messages without associated Business Messages.

9.4.2.1 Creating Unassociated Application Message Reports

You can create an Unassociated Application Message report in a way similar to creating General Application Message reports.

To create an unassociated application message report

1. Perform Steps 1 and 2 from Section 9.2.1, "Creating Business Message Reports."

2. On the Create Message Report dialog, enter a name for the report, select Unassociated Application Message Reports from the Report Type list, and click Create.
The report appears with the Message Report Filter Customizer displayed.

3. On the Message Report Filter Customizer, enter any of the filter criteria described in Table 9-3.

Note:

Multiple conditional operators are supported for most string criteria. For more information about using Any, Equals, Like, Not Equal, or Not Like, see Section 9.1.1, "About the Message Report Filter Customizers."

4. To revert any unsaved changes you made to the report filters, click Revert.

5. When you are done specifying report filters, do any of the following:

- To test your filter criteria, click Search, and then click the Show/Hide Filter toggle button.

- To save the changes you made to the filter criteria for the report, click Save.

You can sort the messages based on any of the report columns by clicking the column headers.

9.4.2.2 Viewing an Unassociated Application Message

You can view an unassociated Application Message from an Unassociated Application Message report.

To view an application message

1. Display an unassociated Application Message report on the Reports page.

2. In the messages list, select the message for which you want to view instance data.
The message flow diagram appears below the message list as shown in.

Note:

The unavailable Business Message icon is rendered as disabled in the message flow.

3. To view the message details in a larger area, click Application Message in the message flow diagram and then click the Collapse Pane icon beneath the message list. You can also click Pin Current Message Details Into a New Tab to open a new page containing the detailed information.

4. Expand or collapse sections of the unassociated Wire Message by clicking the arrow icon next to the section you want to expand or collapse.

5. To download information, click Download As XML or Download as Text in the section you want to download. However, because the message does not have any associated Business Message, Payload does not contain any data.

Note:

This option is not available in all sections.

6. If you collapsed the message list pane, click Restore Pane above the message flow diagram to return to the message list.

9.5 Working with Error Messages

If processing for a message results in an error, the message appears in the message list with a red box over the icon. You can select error message to view additional information about the error.

9.5.1 Viewing an Error Message

This report provides information related to errors in message processing, including the error message, code, severity, level, and description.

To view an error message

1. Review the messages list to find messages with errors, as indicated by an error icon or a state of MSG_ERROR as shown in Figure 9-26.

Figure 9-26 Error Message in Messages List

2. When you find an error message to view, select the message.
The message flow diagram changes to display where the error occurred as shown in Figure 9-27.

Figure 9-27 Message Flow Diagram With an Error

3. Click the error icon in the message flow diagram.
The error message details appear beneath the diagram as shown in Figure 9-28.

Figure 9-28 Error Message Details

9.5.2 Resubmitting Messages

You can resubmit Wire and Application Messages from the Reports tab. When a message transaction contains an error, use the reporting features to determine the nature of the error and correct it. Once the issue is fixed, resubmit the message. You can resubmit messages one at a time or in a group.

To resubmit a message

1. In the messages list for the displayed report, select the message you want to resubmit.

2. Do one of the following:

- Select Resubmit, and then select Associated Application Message or Associated Wire Message.

- Right-click the selected message and use the context menu items.

- In the message flow diagram, right-click either Wire Message or Application Message, and then select Resubmit Wire Message or Resubmit Application Message.

3. On the confirmation dialog that appears, click OK.
The error icon on the message in the messages list changes to a green arrow to indicate the message was resubmitted.

To resubmit multiple messages

1. In the messages list for the displayed report, select the messages you want to resubmit.
A summary of information about the selected messages appears beneath the messages list as shown in Figure 9-29.

Figure 9-29 Multiple Messages Selected on the Reports Page

2. In the yellow bar above the Selection Overview, click Resubmit, and then select Associated Application Message or Associated Wire Message. You can also use the Resubmit menu on the toolbar or right-click the selected message and use the context menu items.

3. On the confirmation dialog that appears, click OK.

9.6 Purging Messages from the Repository

You can purge messages that you no longer want to store in the healthcare integration repository. If a message you purge is part of a batch process, all messages in the batch are also deleted.

You can purge messages one at a time or as a group.

To purge messages from the repository

1. In the messages list of the displayed report, select the message or messages you want to remove.

2. Click Purge.

3. On the confirmation dialog that appears, click Yes.

Note:

When you a Business Message, the corresponding entry in the Sequence Manager table also gets deleted.

10 Configuring Alerts and Contacts

This chapter describes how to define alert notifications and contacts in Oracle SOA Suite for healthcare integration. You can specify that certain people are alerted by email or text (SMS) when certain healthcare-related runtime or design-time events occur.

This chapter includes the following topics:

- Section 10.1, "Overview of Alerts and Contacts"

- Section 10.2, "Configuring Contacts and Alerts"

- Section 10.3, "Viewing the Alerts Assigned to a Contact"

- Section 10.4, "Removing Contacts"

10.1 Overview of Alerts and Contacts

In healthcare integration, administrators and support personnel need to know when certain events occur, such as changes to the healthcare configuration or errors that affect processing. Oracle SOA Suite for healthcare integration addresses this by allowing you to define contact information and associate each contact with specific events for which alerts are generated. For example, if an error occurs during message processing or delivery, an email or text alert can be sent to the appropriate people so the issue can be handled immediately.

The alert notification feature for healthcare integration works in conjunction with the built-in notification framework of Oracle User Messaging Service (UMS) and Oracle SOA Suite human workflow services.

10.2 Configuring Contacts and Alerts

Contacts and alerts are configured using the Oracle WebLogic Administration Console, Oracle Enterprise Manager, and the healthcare integration user interface. You configure the email server and sender address information, as well as enable all notifications, from Oracle Enterprise Manager. You define the individual contacts and subscribe them to alerts using the healthcare integration user interface.

Configuring contacts and alerts involves the following steps:

- Section 10.2.1, "Deploying the SMPP Driver for SMS Notifications"

- Section 10.2.2, "Configuring Workflow Notification Properties"

- Section 10.2.3, "Configuring Oracle User Messaging Service"

- Section 10.2.4, "Defining Alerts and Contacts"

For information about configuring User Messaging Service, see "Configuring Oracle User Messaging Service" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite.

10.2.1 Deploying the SMPP Driver for SMS Notifications

If you are using SMS (text) notifications, you need to specify the target servers for the SMPP driver for the User Messaging Service. Perform this task on the Oracle WebLogic Administration Console.

To deploy the SMPP driver

1. In a web browser, launch Oracle WebLogic Administration Console and log in. The URL is:

http://hostname:port_number/console

The hostname is the name of the computer on which WebLogic Server resides, and the port number is the port on which WebLogic Server listens (by default, 7001).

2. In the Domain Structure navigator, click Deployments.

3. In the Deployments list that appears, select usermessagingdriver-smpp.
The Settings for usermessagingdriver-smpp page appears.

4. Click the Targets tab.
The Target Assignments list appears.

Figure 10-1 Targets Tab for usermessagingdriver-smpp Settings

5. In the Target Assignments table, click the check box next to Component to select all driver components, and then click Change Targets.
The Change Targets Assistant appears.

Figure 10-2 Target Deployments for usermessagingdriver-smpp

6. Select the SOA Manager Server you are using for healthcare integration, and then click Yes.
Confirmation messages appear at the top of the page letting you know whether the targets were changed successfully.

10.2.2 Configuring Workflow Notification Properties

Workflow notification properties enable the notification feature for all notification types, and also define email addresses for the sending email account for the notifications.

To configure the workflow notification properties

1. In a web browser, launch Oracle Enterprise Manager and log in. The URL is:

http://hostname:port_number/em

The hostname is the name of the computer on which WebLogic Server resides, and the port number is the port on which WebLogic Server listens (by default, 7001).

2. In the left navigation panel, expand SOA and select soa-infra.

3. On the soa-infra page, click the SOA Infrastructure menu, point to SOA Administration, and select Workflow Config.

4. On the Workflow Notification Properties page, set the Notification Mode to All.

5. In the Notification Service section, configure the following email addresses:

- Email: From Address -- The email address from which you want to send email notifications.

- Email: Actionable Address -- The email address for actionable incoming messages. This is not required.

- Email: Reply To Address -- The email address to include in the Reply To field of the outgoing email notification header.

Figure 10-3 SOA Infrastructure Workflow Notification Properties

6. Click Apply, and then click Yes on the confirmation dialog.

Note:

Whenever you add a document definition to an endpoint, the backend process of Oracle SOA Suite for healthcare integration deploys the document. So, an email is sent for the document deployment, and no notification is sent for the document addition.

10.2.3 Configuring Oracle User Messaging Service

Oracle UMS provides the underlying infrastructure for notifications. In order to use email notifications, you need to configure email driver information for the UMS; in order to use SMS (text) notifications, you need to configure SMPP driver information.

To configure Oracle User Messaging Service

Note:

For more information about this task and the properties you can configure, see "Configuring Oracle User Messaging Service" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite.

1. In the left navigation panel of Oracle Enterprise Manager, expand User Messaging Service.

2. Right-click usermessagingdriver-email and select Email Driver Properties.

Figure 10-4 Email Driver Properties Page for UMS

3. Configure the email driver properties for your email server.

4. After you configure the email properties, right-click usermessagingdriver-smpp under User Messaging Service in the left navigation pain

5. Select SMPP Driver Properties.

6. Configure the SMPP driver properties.

7. After you configure all the workflow and email driver properties, restart the server to load all the changes.

10.2.4 Defining Alerts and Contacts

In the healthcare integration user interface, you can define contacts and then subscribe each contact to multiple alerts for different types of events. The events that can generate an alert are listed in Table 10-1.

To define alerts and contacts

1. In a web browser, launch the Oracle SOA Suite for healthcare integration user interface. The URL is:

http://host_name:port_number/healthcare

The hostname is the name of the computer on which the WebLogic Managed Server resides; and port number is the port number on which the Managed Server listens.

2. Under the Designer tab, click the Administration tab and then double-click Alerts and Contacts.

Figure 10-5 Alerts and Contacts Page

3. In the Contacts section, click Add a Contact (the plus icon in the upper right).

4. Enter the following information:

- Type: Select the type of alert to send. Choose from Email or Texting (SMS).

- Value: The email address or text number to which alerts should be sent. Make sure the type of value you enter here corresponds to the type you selected.

5. Repeat the previous two steps for each contact your need to add.

Figure 10-6 Texting and email Contacts

6. Click Apply to save the contact information.

7. In the Events section on the right, select the Enabled check box for all events for which you want to send alerts.

8. To subscribe contacts to events, do one of the following:

- For each contact you create, drag and drop the contact from the contacts list into one or more of the enabled events listed on the right side. Table 10-1 lists and describes each event for which you can configure alerts.

- Click Add an Alert for this Event next to the event name, and then select a contact from the drop down list that appears in the event section.

Figure 10-7 Alert Events With Contacts Assigned

Each time an event occurs, the specified message type (email or text) is sent to the contacts listed for that event.

Tip:

Due to the length of some runtime error messages, you might want to avoid subscribing text (SMS) contacts to runtime events.

Table 10-1 Healthcare Integration Alert Events

Event

Description

Runtime Error

Triggers an alert when an error occurs during inbound or outbound message processing, delivery to endpoints, or delivery to internal delivery channels.

Endpoint Error

Triggers an alert when an error occurs in the endpoint transport layer; for example, the TCP/IP server port is already in use.

Endpoint Configuration

Triggers an alert when changes are made to an endpoint's configuration, including enabling and disabling an endpoint.

Endpoint Document Usage Change

Triggers an alert when changes are made for a document definition associated with an endpoint.

Repository Import and Export

Triggers an alert when data is imported into or exported from the healthcare integration repository.

Runtime Settings Modification

Triggers an alert when changes are made to the any of the runtime properties listed on the Runtime Settings page.

Purge Events

Triggers an alert when:

- The runtime data is purged with Purge Control Number selected or deselected under Repository Management in the Administration tab.

- The runtime data is purged from the commandline with the purgecontrolnumber option set to true.

10.3 Viewing the Alerts Assigned to a Contact

You can view all of the alerts that are assigned to a specific contact from the Contacts list on the Alerts and Contacts page.

To view alerts for a contact

1. Under the Designer tab of the healthcare integration user interface, click the Administration tab and then double-click Alerts and Contacts.

2. In the Contacts list, click the arrowhead icon to the left of the contact whose alert information you want to view.
A list of alert subscriptions appears.

Figure 10-8 Alert Subscriptions for a Contact

3. When you are done viewing the alerts, click the contact's arrowhead again to close the alert subscriptions list.

10.4 Removing Contacts

Once you create a contact, you can remove it from the contact list if it is no longer needed. If a contact no longer needs to receive alerts for an event, you can unsubscribe the contact from that event.

To Remove a Contact

1. Under the Designer tab of the healthcare integration user interface, click the Administration tab and then double-click Alerts and Contacts.

2. In the Contacts list, select the contact to delete, and then click Delete Currently Selected Contact (the red X in the upper right of the Contacts list).

3. If the contact is subscribed to any alerts, a confirmation dialog appears. Click OK to remove the contact.
The contact is removed from the Contacts list and is also removed from any events to which it was subscribed.

To Unsubscribe a Contact from an Alert

1. Under the Designer tab of the healthcare integration user interface, click the Administration tab and then double-click Alerts and Contacts.

2. Select the contact in the event list from which you want to remove the contact.

3. Click Delete Currently Selected Alert (the red X in the upper right of the event list.).
The contact is removed from the list.

10.5 Viewing a History of Alerts Sent

You can view a history of the alerts that have been sent to each contact from the Oracle Enterprise Manager Human Workflow Engine pages.

To view a history of alerts sent

1. In a web browser, launch Oracle Enterprise Manager and log in. The URL is:

http://hostname:port_number/em

The hostname is the name of the computer on which WebLogic Server resides, and the port number is the port on which WebLogic Server listens (by default, 7001).

2. In the left navigation panel, expand SOA and select soa-infra.

3. On the soa-infra page, click the SOA Infrastructure menu, point to Service Engines, and select Human Workflow.

4. On the Human Workflow Engine page, click the Notification Management tab.

11 Viewing the Healthcare User Audit Trail

This chapter describes how to enable and configure an audit trail of user activity for healthcare integration components and applications. Oracle SOA Suite for healthcare integration uses Oracle's Common Audit Framework to log user activity against healthcare integration components.

This chapter contains the following topics:

- Section 11.1, "Introduction to the Audit Trail"

- Section 11.2, "Configuring the Healthcare Integration Audit Trail"

- Section 11.3, "Viewing User Audit Logs"

11.1 Introduction to the Audit Trail

The Oracle auditing framework collects and stores information about events affecting configured components, providing an audit log of activity for those components to help support your compliance requirements. Auditing for each SOA Suite component is defined by an audit policy that defines which components and which activities are captured in the audit log. You can configure the audit policy to only capture the information you need and ignore the rest. This is done on the Audit Policy page of Oracle Enterprise Manager. See "Managing Audit Policies" in the Oracle Fusion Middleware Application Security Guide for more information.

The set of auditable events for each application and component is defined by the audit policy and differs between each application. When you expand the list of events for a component, only those events that can be audited for that component appear in the list. For each event, you can further specify whether to only log successful attempts or failed attempts (currently Oracle SOA Suite for healthcare integration only logs successful attempts).

When you configure auditing, you can select from the following audit levels:

- Low: This option selects a subset of events from all auditable components in the audit policy list, including a subset of Oracle SOA Suite for healthcare integration events. It does not allow custom filters to be created.

- Medium: This option selects a larger subset of events from all auditable components in the audit policy list, including all Oracle SOA Suite for healthcare integration events. It does not allow custom filters to be created.

- Custom: This options lets you select only those components, events, and conditions that you want to audit. This is the recommended level for Oracle SOA Suite for healthcare integration. You need to select this level in the Oracle Enterprise Manager console to enable Oracle Healthcare auditing.

You can also specify a list of users whose activity is audited regardless of the actions performed or the component used. Auditing occurs for these users no matter what audit level or filters are defined.

For more information about audit policies, see Configuring and Managing Auditing in the Oracle Fusion Middleware Application Security Guide.

11.1.1 Oracle SOA Suite for Healthcare Integration Auditing Options

The components and events available for auditing are listed on the Audit Policy page of Oracle Enterprise Manager (Weblogic domain > Security > Audit Policy). To view or configure the these options, select Oracle SOA Suite for healthcare integration from the Audit Component Name list, Custom from the Audit Level list, and click the check boxes adjacent to the events.

Figure 11-1 Healthcare Integration Components on the Audit Policy Page

Note:

Currently only the SUCCESS events are audited. You should not select FAILURE events.

Currently, the following components and events are supported for audit in Oracle SOA Suite for healthcare integration (note that additional events appear in the list, but they are not currently logged):

- User Session

- User Login

- User Logout

- Endpoint Management

- Enable Endpoint

- Disable Endpoint

- Document Management

- Resubmit Message

- Purge Message

- Read Payload

11.1.2 Using Filter Conditions for Auditing

For each event, you can define filters for the success condition. Filters use rule-based expressions that are based on the attributes of the event. For most Oracle SOA Suite for healthcare integration user access auditing, you can use the following attributes in your filter expressions:

- Host ID

- Host Network Address

- Initiator

- Client IP Address

- Resource

- Domain Name

Expressions can include AND and OR operators, as well as a variety of comparison functions, such as equals, starts with, contains, does not equal, and so on.

11.2 Configuring the Healthcare Integration Audit Trail

You configure audit policies in Oracle Enterprise Manager by selecting the events or components to include in the audit log. Currently, Oracle B2B components and events are not included in the audit trail.

There are two default configurations, Low and Medium audit levels, that select a predefined subset of components or events. These are not recommended for Oracle SOA Suite for healthcare integration because they affect all auditable components, not just the components of Oracle SOA Suite for healthcare integration. Selecting either of these options can result in extraneous audit entries and unnecessarily large audit logs. Additionally, these two options do not allow you to define any filters.

The following instructions apply to custom-level audit policy configuration.

To configure auditing for healthcare integration

1. Login to Oracle Enterprise Manager.

2. In the navigation panel on the left, expand WebLogic Domain and then right-click the name of the domain for which you want to enable user auditing.

3. In the context menu that appears, point to Security and then select Audit Policy.

Figure 11-2 Security Context Menu for a WebLogic Domain

4. In the Audit Level field, select Custom.
Check boxes appear in the Select for Audit column so you can select which healthcare integration components and events to audit.

5. Click event categories such as User Session to display the list of events pertaining to that category below.

6. Do any of the following:

- To enable auditing for all Oracle SOA Suite for healthcare integration components and events, click the Audit All Events button.

- To enable auditing for all events for a specific component, click the check box in the Select for Audit column next to the component name.
For example, to audit all actions taken against endpoints, select the check box for Endpoint Management.

Figure 11-3 Endpoint Management Component With All Events Selected

- To enable auditing of a specific event for a component, expand the component and select the check box in the Enable Audit column next to the event name under that component.

7. To define a filter for a success condition, select Enable Audit for the success condition, and then click its Edit Filter icon. Define the filter on the dialog that appears, and then click OK.
For more information about filters, see Section 11.1.2, "Using Filter Conditions for Auditing" and the online help available from the Edit Filter dialog. Note that filters can only be defined for success conditions at this time.

8. To specify a list of users whose activity is always audited regardless of the component configuration, enter a list of user accounts in the Users to Always Audit section. Separate the account names with commas.

9. When you are done configuring auditing, click Apply.

10. Restart the server in order for the changes to take effect.

11.3 Viewing User Audit Logs

When an event triggers an audit log entry, the event information is written to the audit log file. The audit log captures the following information. Depending on the type of event that triggered the entry, several of these fields might be empty.

- Date and time

- Initiator of the event

- Event type

- Event status

- Message text (indicating what occurred)

- ECID

- RID

- Context fields

- Session ID

- Target component type

- Application name

- Event category

- Thread ID

- Failure code

- Remote IP address

- Target

- Resource

- Roles

- Authentication method

- Reason

You can view the audit log file directly. It is written to the following location:

fmw_home/user_projects/domains/domain_name/servers/managed_server_name/logs/auditlogs/SOA-HCFP/audit.log

12 Managing the Repository

This chapter describes the healthcare integration metadata repository and provides instructions for managing the stored data. Design-time and instance data for the Oracle SOA Suite for healthcare integration are stored in a metadata repository, and you can import data, export data, and purge metadata or instance data.

This chapter includes the following topics:

- Section 12.1, "Introduction to the Oracle SOA Suite for Healthcare Integration Repository"

- Section 12.2, "Importing and Exporting the Design-Time Repository"

- Section 12.3, "Purging Repository Data"

12.1 Introduction to the Oracle SOA Suite for Healthcare Integration Repository

Oracle SOA Suite for healthcare integration instance data is stored and managed within the SOAINFRA schema of your database. Metadata for design-time and configuration is stored and managed through Metadata Services (MDS), available in Oracle Fusion Middleware. For more information about MDS, see the Oracle Fusion Middleware Administrator's Guide.

12.1.1 Repository Maintenance

The healthcare integration user interface provides features to help you manage the repository data, which include importing repository data, exporting the full repository, purging design-time metadata, and purging instance data. You can import objects such as document definitions, map files, endpoints, an exported repository, and so on.

Design-time metadata includes endpoints, document definitions, internal delivery channels, and mapsets. Instance metadata is the information that is created during runtime when messages are processed. In addition to being able to purge these two types of data on the Repository Management page, you can also purge messages on the Reports page.

Use caution when using the import and purge features. During an import, you might overwrite existing data, and purging data removes the data permanently.

12.1.2 What Occurs During the Import or Export Process

Exporting a file exports the full healthcare integration metadata repository and creates a ZIP file containing the exported data. When you import a file, all of the objects in the export file is copied, which can include documents, endpoints, callouts, mapsets, and so on. If you choose to replace existing metadata during an import procedure, any existing metadata with the same name as metadata in the export file will be overwritten by the information being imported.

Note that library JAR files used by Java callouts are not copied during an import or export procedure.

When you export the design-time repository, continue to make changes to the repository contents in the healthcare integration user interface, and later import the exported file (the contents of which are now older), then updates occur as follows:

- If Replace Existing Metadata is not checked during import, then any new data that was created or modified in the healthcare integration user interface after the file was exported is left untouched.

- If Replace Existing Metadata is checked during import, then the existing metadata is replaced with the ZIP file metadata.

If an import fails, then the changes are rolled back and the design-time repository remains unchanged. A message appears indicating that the import was unsuccessful.

12.1.3 About the Exported File

Design-time repository contents that are exported to a file represent a copy of the current data. This file is no longer accessible for changes from the healthcare integration user interface until it is imported back into Oracle SOA Suite for healthcare integration. Do not manually edit exported files.

12.1.4 What Occurs During the Purging Process

You can purge both design-time metadata and instance data. Design-time metadata includes document definitions, endpoints, callouts, mapsets, and internal delivery channels. When you purge this data, predefined data that is part of the installation is not purged. After you perform a successful purge of design-time metadata, you are logged out of the healthcare integration user interface so you need to log back in. You cannot purge design-time metadata if there are active endpoints.

Instance data is generated during runtime when messages are processed. Instance, or runtime, data contains the business messages and message-related data. Specific instance data can be purged from the Reports page. See "Working with Reports" for more information.

Purging is useful for:

- Managing disk space and improving performance

- Removing repositories on a test system

12.1.5 Purging Control Numbers

When you purge instance data, you can optionally purge control number information. Control numbers are used in HL7 message standards. Oracle SOA Suite for healthcare integration keeps track of control numbers for inbound and outbound messages. For outbound messages, the control numbers are generated in a sequence from an internal control number table. Because purging instance data and control numbers resets the sequence (the control number table is reset), an outbound message after a purge may have the same control number as a message before the purge. If this is undesirable, do not purge control numbers.

12.2 Importing and Exporting the Design-Time Repository

Oracle SOA Suite for healthcare integration design-time data can be exported and saved to a ZIP file. The ZIP file can be imported back into Oracle SOA Suite for healthcare integration so the data is available in the healthcare integration user interface. This is useful when migrating data from a test environment to a production environment.

Caution:

Do not manually edit exported files. This could make the data unstable once it is imported back in.

Figure 12-1 shows the Repository Management tab, where you import and export design-time data.

Figure 12-1 Repository Management Page

When you import metadata, the updates to your existing repository are incremental unless you select the Replace Existing Metadata option. To delete all existing data before importing metadata, use the Purge Design Metadata button.

Caution:

Complete export operations without interruption or idle time. Leaving the browser idle for more than a few minutes during export operations can cause file corruption.

To import repository metadata

1. Make sure the metadata repository ZIP file you want to import is available to your local system.

2. On the healthcare integration user interface, click the Designer tab and then click the Administration tab.

3. Click Repository Management.

4. In the Import section, click Browse to find the metadata repository ZIP file.
If you are importing a ZIP file that contains multiple ZIP files within it, you must unzip the containing file and import each ZIP file separately.

5. To overwrite the current metadata in the Metadata Service (MDS) repository, select Replace Existing Metadata
If this option is not selected, only new data is copied to the MDS repository.

6. Click Import.
Depending on the size of the design-time repository contents, this process might take some time.

To export repository metadata

Caution:

Do not manually edit exported files.

1. On the healthcare integration user interface, click the Designer tab and then click the Administration tab.

2. Click Repository Management.

3. Click Export.
A dialog appears giving you the status of the export file generation.

4. Click Continue.

5. On the dialog that appears, select Save File and then click OK.
The default file name is MDS_EXPORT_DD_MM_YYYY.zip.

6. Specify a name for the export file or accept the default name, browse to and select the a folder for the file, and then click Save.

Note:

Design time import and export can also be done using a commandline tool.

12.3 Purging Repository Data

Use the purge function to manage disk space and improve performance, and to remove test data from the repository.

To purge repository data

1. On the healthcare integration user interface, click the Designer tab and then click the Administration tab.

2. Click Repository Management.

3. Do one of the following:

- To purge design-time metadata, such as endpoints, internal delivery channels, mapsets, callouts, and document definitions, click Purge Design Metadata.

Note:

This button is disabled if there are active endpoints in the healthcare integration repository. In this case, you need to disable any active endpoints and return to this page to purge design-time data.

- To purge all runtime instance data (that is, all messages), click Purge Instance Data. If you want to remove control numbers with this data, select Purge Control Number before clicking Purge Instance Data.

4. Click OK on the confirmation dialog.

Note:

Purging repository data can also be done using a commandline tool.

13 Configuring System Settings

This chapter describes how to configure the appearance of the healthcare integration user interface and how to configure runtime processing for healthcare integration applications.

This chapter includes the following topics:

- Section 13.1, "Configuring the Runtime Settings"

- Section 13.2, "Configuring the User Interface Settings"

13.1 Configuring the Runtime Settings

Runtime settings control how Oracle SOA Suite for healthcare integration handles certain functions, like sequencing, functional acknowledgments, batch processing, Oracle BAM enablement, default queues, and so on.

Runtime settings are shared between Oracle SOA Suite for healthcare integration and Oracle B2B; changing the settings for one also changes the settings for the other. Oracle B2B settings in Oracle Enterprise Manager also apply to Oracle SOA Suite for healthcare integration. For more information about Oracle B2B settings in Oracle Enterprise Manager, see "Configuring Oracle B2B" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

Figure 13-1 Runtime Settings

To configure the runtime settings

1. On the Oracle SOA Suite for healthcare integration user interface, click the Designer tab and then click the Administration tab.

2. Expand Settings and then select Runtime.

3. Modify the value of any of the properties listed in Table 13-1.

4. Do one of the following:

- To save your changes, click Apply.

- To change the settings back to their previous values, click Revert.

Table 13-1 Runtime Configuration Settings

Field

Description

Acknowledgment

Functional Ack Handled Automatically

An indicator of whether Oracle SOA Suite for healthcare integration automatically generates the functional acknowledgment (FA) for inbound HL7 messages. Select this option to automatically generate the FA; inbound FA messages are consumed when this option is selected.

Deselect this property if you do not want to automatically generate the FA document. The backend application (middleware) must generate the FA and provide it to Oracle SOA Suite for healthcare integration as an outbound message. When this property is deselected, inbound FA documents are passed back to the backend application.

If the document does not require an FA (as indicated by the endpoint-level setting), then this property is ignored. This property is selected by default.

If the FA is marked as expected in an endpoint, then the message is placed into the MSG_WAIT_FA state and the backend application is expected to generate the FA and push it to Oracle SOA Suite for healthcare integration as an outbound message back to the partner.

When Functional Ack Handled Automatically is not selected, Notify Inbound Functional Acks must also be deselected in order for the inbound FA to be sent to the backend application. If Notify Inbound Functional Acks is selected and Functional Ack Handled Automatically is deselected, the incoming functional acknowledgment generates only a notification and the FA document itself is not sent back to the backend application.

The following limitations apply when generating the FA from the backend application:

- The FA is correlated with the original message based on the ReferToMsgID value set in the enqueue properties. The FA is correlated based on control numbers also.

- If the FA indicates that there was an error in the received message, the status of the correlated message is not updated to indicate an error. The correlated message is updated to MSG_COMPLETE.

These limitations are not present when the FA is generated by Oracle SOA Suite for healthcare integration (that is, when this property is selected).

Functional Ack Internal Properties

An indicator of whether to generate the internal properties structure in the functional acknowledgment using the original message internal properties.

By default, this property is deselected, which means that the functional acknowledgment uses the original message-internal properties.

Notify Inbound Functional Acks

An indicator of whether Oracle SOA Suite for healthcare integration sends an acknowledgment notification to the application when a functional acknowledgment is received. Select this property to send the acknowledgment notification.

When Functional Ack Handled Automatically is not selected, Notify Inbound Functional Acks must also not be selected in order for the inbound FA to be sent to the backend application. If Notify Inbound Functional Acks is selected and Functional Ack Handled Automatically is not selected, the incoming functional acknowledgment generates only a notification and the FA document itself is not sent back to the back-end application.

Miscellaneous

Auto Stack Handler

An indicator of whether the stack handler for MLLP processes the stacked messages in automatic mode. Select this property to process in automatic mode. By default, this property is selected.

Log Payload

An indicator of whether to log the payload in a diagnostic log. When this property is selected, the payload is logged, but this also depends on the log level setting. Error messages are logged by default. Payload logging is useful for diagnostic purposes, but may be undesirable for security reasons. By default, this property is not selected.

Note: You need to set the log-level setting in the Enterprise Management console to TRACE to be able to log payloads. The available log-level settings are TRACE, NOTIFICATION, INCIDENT_ERROR, ERROR, and WARNING.

Exception Queue

A JMS internal delivery channel for the host to use as the exception queue. Exception notifications are sent to the queue name you specify here. A null value for this parameter means that exceptions are sent to the AQ queue (IP_IN_QUEUE).

Generic Message Type

An indicator of whether Oracle SOA Suite for healthcare integration should ignore the HL7 trigger event. By default, this property is not selected.

Outbound Dispatcher Count

The number of dispatchers used for handling the outbound messages. This is used in message sequencing.

Inbound Dispatcher Count

The number of dispatchers used for handling the inbound messages. This is used in message sequencing.

Auto Stack Handler Interval

The time interval in seconds for the stack handler to process the stacked messages. Enter comma-separated values for the intervals.

Partial Batch Commit Size

The number of records to be committed when there is a large number of business messages for a message exchange.

Enable BAM

An indicator of whether to send runtime information to Oracle BAM. For more information, see "Monitoring Instance Message Data With Oracle BAM" in the Oracle Fusion Middleware User's Guide for Oracle B2B.

BAM Polling Interval

The polling interval in minutes for Oracle BAM. This is ignored if Oracle BAM is not enabled.

Ignore Correlation

An indicator of whether to ignore correlation errors when an acknowledgment is received and correlation fails. Acknowledgments are correlated to the actual business message of the sender. If the correlation fails, an exception is generated and the acknowledgment processing stops. To ignore the correlation in this case and continue processing the acknowledgment, select this property. By default, this property is not selected.

Non Purgeable

Note: The nonpurgeable parameters retain their values even after metadata repository is purged.

Callout Directory

The directory for the callout JAR file location (if you do not use the default callout). The callout directory path cannot end with a forward or backward slash (/ or \).

The default file location, /MyCalloutDir, is retained after purging the metadata repository.

Performance

Large Payload Size

The large payload size, in bytes. The default value is 2,000,000 (2MG).

Large Payload Directory

The directory to store large payloads. The default directory is /tmp. For Windows-based systems, change the directory to an appropriate directory, such as C:\temp.

13.2 Configuring the User Interface Settings

User interface settings control the appearance of the reports and dashboards on the healthcare integration user interface.

Figure 13-2 User Interface Settings

To configure the time slider periods for reports and dashboards

This procedure changes the values listed on the time sliders that are used on the Reports and Dashboard pages. You can select up to nine different time periods for the sliders.

Figure 13-3 Time Slider in the Reports Filter Panel

1. On the Oracle SOA Suite for healthcare integration user interface, click the Designer tab and then click the Administration tab.

2. Expand Settings and then select UI.

3. In the Enabled Time Slider Periods section, select the time periods you want the sliders to display.
You can select up to nine periods, so be sure to deselect time periods you do not need to make room for the ones you want to display. As you change your selections, you can see the changes to the dashboard summary slider on the right.

4. To restore the time period selections to the default, click Restore Defaults.

5. When you are done making changes, click Apply to save your changes.

To configure reports

You can configure certain display attributes for the Reports page, such as how many records to display, how often to auto-refresh, and payload display.

1. On the Oracle SOA Suite for healthcare integration user interface, click the Designer tab and then click the Administration tab.

2. Expand Settings and then select UI.

3. Change the value of any of the properties described in Table 13-2.

Table 13-2 Configuration Properties for Reports

Property

Description

Auto-Refresh Interval (secs)

The length of time (in seconds) the browser should wait between automatically refreshing information in a report.

Page Size

The number of messages to display on each page of a report.

Show Payload

An indicator of whether to display the message payload regardless of user permissions. Select Yes to display the payload; otherwise select No.

Payload Display Size (bytes)

The maximum number of bytes of each message payload to display. If a payload is larger than the number of bytes specified, none of the payload is shown.

4. When you are done making changes, click Apply to save your changes.

To configure the default time period for the dashboard summary

This procedure changes the default time period for the information shown on the Dashboard Summary pages. For example, if you select 5 Days, when you open a dashboard you will see a summary of the past five days for the selected endpoints; if you select Week, you will see a summary of the past week.

1. On the Oracle SOA Suite for healthcare integration user interface, click the Designer tab and then click the Administration tab.

2. Expand Settings and then select UI.

3. In the Dashboard Summary section, move the pointer on the slider to the time period you want to use as the default for the Dashboard Summary pages.

4. When you are done making changes, click Apply to save your changes.

To configure endpoint details on the dashboard

You can configure the appearance of the Endpoint Details page of a dashboard. This is the page that appears when you click the Endpoint Details icon for an endpoint on the Dashboard Summary page.

1. On the Oracle SOA Suite for healthcare integration user interface, click the Designer tab and then click the Administration tab.

2. Expand Settings and then select UI.

3. Change the value of any of the properties described in Table 13-3.

Table 13-3 Configuration Properties for Endpoint Details

Property

Description

Number of Gauge Columns

The number of message type gauges to display in each row of the Document Type Processed section.

Auto-Refresh Interval (secs)

The length of time (in seconds) the browser should wait between automatically refreshing endpoint details in a dashboard.

Document Type Display

An indicator of whether to display document type information in gauge format or in table format. Examples of each format are shown in Figure 13-4 and Figure 13-5.

Slow Threshold for Sequencing (secs)

The number of seconds that a sequence message can wait in the queue before processing is considered slow. Once processing is considered slow, the status appears as yellow on the Endpoint Details page of a dashboard.

Figure 13-4 Document Type Information in Gauge Format

Figure 13-5 Document Type Information in Table Format

4. When you are done making changes, click Apply to save your changes.

14 Provisioning Users

This chapter discusses how to provision users by providing them roles using the Oracle Healthcare console.

The chapter contains the following topics:

- Section 14.1, "Creating Users"

- Section 14.2, "Adding Users"

- Section 14.3, "Editing, Viewing, and Deleting User Provisioning"

14.1 Creating Users

The Oracle Healthcare administrator (the default login username-password combination) can add additional users (registered users in the Weblogic default store) by using the Oracle Healthcare console. These users can log in to Oracle Healthcare and only view endpoint.

The following roles are available:

- Administrator role—Provides access to all Oracle Healthcare functionality

- Monitor role—Provides read access to reporting and metrics functionality only (use of the Reports link)

Users with the administrator role can access all Oracle Healthcare functions. Users with the monitor role have only read access to reports.

You can create users by using the Identity Store (in the Oracle Weblogic Server console), and then you can provision those users with specific roles in the console.

See "Task 1 Create a New User in the Identity Store" in the "Adding Trading Partner Users" in Oracle Fusion Middleware User's Guide for Oracle B2B for more information on creating users.

14.2 Adding Users

After you have created the registered users in the Oracle Weblogic Server console, you can add users to Oracle Healthcare by using the User Provisioning link under Administration in the Designer tab.

Note:

Due to security concerns, only registered users belonging to the WebLogic Administrators group are allowed to access the User Provisioning functionality in the Oracle Healthcare console. The User Provisioning link is not available for other users.

To add and provision a user:

1. Log on to the Oracle SOA Suite for healthcare integration console.

2. In the Designer tab, click Administration and then double-click User Provisioning on the left-hand panel.

3. In the User Provisioning pane on the right, click Add New User Provisioning for Healthcare UI (+ icon) under the Users table. This adds a blank row in the table.

4. Click the new row to select it.

5. Clear the existing prompt in the Name field and to select or provision a registered user, do one of the following:

- Type the first few characters (case-insensitive by default) of the registered user name, and either click the Browse button (the magnifying glass icon) or press the Tab key.
If there is only one match, it is automatically selected and the user name is populated in the Name field. If there are zero or more than one match, then the Choose Registered User to Provision for Access to Healthcare UI dialog box is displayed where you can refine the search, select one of the results, or both. Figure 14-1 displays the Choose Registered User to Provision for Access to Healthcare UI dialog box.

Figure 14-1 Selecting Users from a List of All Matching Users

- In case you are not sure about the user name that you want to select, click Browse or press Tab to display the Choose Registered User to Provision for Access to Healthcare UI dialog box that lists all the users available for provisioning as displayed in Figure 14-2.

Figure 14-2 Displaying a List of All Registered Users

If the required user name is not listed in the dialog box, start typing the first few characters of the registered user name in the Name field of the dialog box, and the results table will be automatically populated accordingly. Select the Ignore Case check box if you need to perform a case-insensitive search. You can also clear the input field and press Tab to browse all available users for provisioning.

Note:

Once you have selected a registered user, the Description field is automatically populated with the description that you have provided for the user in the WebLogic Administration Console. You cannot modify the description in the Oracle Healthcare console.

Note:

If you try to search for a user that is a part of the Oracle Weblogic Administrator group in the Choose Registered User to Provision for Access to Healthcare UI dialog box, an error message is displayed stating that users belonging to the Weblogic Administrators group do not need to be provisioned, as displayed in the following graphic.

6. Select the role that you want to grant to the user from the Role list. The available values are Administrator and Monitor as shown in Figure 14-3.

Figure 14-3 Selecting the Role for the User

By default, all new users added are initially provisioned for the Monitor role in the Oracle Healthcare console, unless the user belongs to the WebLogic Administrators group, in which case the user will not be available for provisioning (already added to the Administrators group).

Based on the role selected for the user, the user icon changes as shown in Figure 14-4.

Figure 14-4 Changing User Icon

7. Click Apply to save the changes and complete the user provisioning.

Note:

After you have provisioned all the registered users for the Oracle Healthcare console, if you click Add New User Provisioning for Healthcare UI (+ icon), the following window stating that no more users are available for provisioning is displayed.

14.3 Editing, Viewing, and Deleting User Provisioning

You can edit, delete, and view user provisioning by using the Oracle Healthcare console.

To edit an existing user provisioning:

1. Log on to the Oracle SOA Suite for healthcare integration console.

2. In the Designer tab, click Administration and then User Provisioning on the left-hand panel.

3. Click the required user row in the Users table. This enables the Role list for editing.

4. Select the required role from the Role list.

To view user details:

1. Log on to the Oracle SOA Suite for healthcare integration console.

2. In the Designer tab, click Administration and then User Provisioning on the left-hand panel.

3. Click the Expand (down arrowhead) icon to the left of the required user in the Users table to display the user details as shown in Figure 14-5.

Figure 14-5 Viewing User Details

Note:

The user details are fetched from the Oracle WebLogic Security Realm that you have used when creating the user.

To delete an existing user provisioning:

1. Log on to the Oracle SOA Suite for healthcare integration console.

2. In the Designer tab, click Administration and then User Provisioning on the left-hand panel.

3. Click the corresponding row for the required user name in the Users table and click the Delete Selected User Provisioning (X) icon. No confirmation is required, because you can easily revert the deletion.

Note:

Deleting a user provisioning deletes the provisioning for the registered user's access to Oracle Healthcare console only; it does not delete the user from the default Oracle WebLogic Security Realm.

14.4 Provisioning Users for Payload Viewing

Oracle Healthcare user provisioning for payload viewing adheres to the following principles:

- Users who belong to WLS Administrators group can always view any document type payload and do not need any provisioning in the Oracle Healthcare console.

- Users who have been provisioned for Oracle Healthcare Administrator or Monitor role with no specific document type provisioning, can view all document type payloads.

- Users who have the Oracle Healthcare Administrator or Monitor role with Foot 1 specific document type provisioning can only view those particular document type payloads.

14.5 Reverting User Provisioning Changes

You can revert changes made to the user provisioning in Oracle Healthcare console by clicking the Revert button at the top right of the User Provisioning pane.

Footnote Legend

Footnote 1: Please refer to the Oracle Healthcare Known Issues at http://www.oracle.com/technetwork/middleware/docs/aiasoarelnotesps6-1866030.html#hcfp for more information.

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

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

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

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

- 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

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.

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.

16 Oracle Healthcare Command-Line Tools

This chapter describes the Oracle Healthcare command-line tools that are available for a number of tasks such as purging data, importing and exporting data, batching operations, updating and deleting endpoints, and so on.

This chapter contains the following topics:

- Section 16.1, "Prerequisites for Running the Command-line Tools"

- Section 16.2, "Purging Data"

- Section 16.3, "Importing Data"

- Section 16.4, "Exporting Data"

- Section 16.5, "Batching Operations"

- Section 16.6, "Resubmitting a Message"

- Section 16.7, "Scheduling Endpoint Downtime"

- Section 16.8, "Updating Endpoints"

- Section 16.9, "Deleting Endpoints"

16.1 Prerequisites for Running the Command-line Tools

Do the following before using the command-line tools:

1. Set the ORACLE_HOME, ANT_HOME, and JAVA_HOME environment variables.
ORACLE_HOME is set to your Oracle SOA Suite install in the Oracle Fusion Middleware installation directory. For example if the default shell is CSH:

setenv ORACLE_HOME <Oracle SOA install directory>
setenv ANT_HOME $ORACLE_HOME/../modules/org.apache.ant_1.7.1
set JAVA_HOME $ORACLE_HOME/<jdk install directory>

2. Create jndi.properties.

cd $ORACLE_HOME/bin
ant -f ant-hcfp-util.xml hcfpcreate-prop

3. Edit the jndi.properties file to include the weblogic password.

Notes:

1. Command-line tools are for administrator use only. No security or permission checks are performed to prevent the logged-in user from purging, importing, or exporting data.

2. After running any command-line tool, you should gain log on to the Oracle Healthcare console. The Oracle Healthcare console caches some metadata and any command-line action which may have updated the metadata could lead to invalid cached data. Therefore, it is advisable to always re-login into the Oracle Healthcare console after using command-line operations.

3. All of the command-line tools can be run without any JNDI credentials. To restrict the command-line tools from anonymous use, provide the following information in the jndi.properties file:

java.naming.security.principal=weblogic
java.naming.security.credentials=weblogic_password

Note:

For any Oracle Healthcare command-line utility, by default, the ANT run shows BUILD SUCCESSFUL and system code 0 (zero) is returned even in the case of client or server side error. In case you want the ANT run to FAIL for each client or server side error, then you need to set exitonerror parameter to true.

You can do this in either of the following two ways:

- Specify -Dexitonerror=true on ANT command line

ant -f ant-hcfp-util.xml b2bpurge -Dagreement=<AGR_NAME> -Dmode=DT -Dexitonerror=true

- Setting the exitonerror parameter as global setting:
Create a properties file called ant_general.properties with the value exitonerror=true in the directory where ant-hcfp-util.xml is present ($ORACLE_HOME/bin).

With this configuration, for all client or server errors, all ANT commands will fail with the message BUILD FAILED and the system exit code will be set to -1.

16.2 Purging Data

This utility is used to purge design and runtime data from the Oracle Healthcare repository. This utility also provides the archiving feature by default. If Archive is set to YES, then the an initial setup is required.

To do initial setup:

1. On the machine running the database, create a directory in which to dump the archive file. For example:

mkdir /tmp/archive

2. Grant permissions to this directory so that the database process can write to it.

chmod 777 /tmp/archive

3. Log in to the database as sysdba.

sqlplus / as sysdba

4. Set up the HCFP_EXPORT_DIR.

SQL> create or replace DIRECTORY HCFP_EXPORT_DIR as '/tmp/archive'

5. If your SOA schema user is hcfp_soainfra, the user needs to be granted permission for the export.

SQL> grant read, write on directory HCFP_EXPORT_DIR to hcfp_soainfra;
SQL> grant exp_full_database  to hcfp_soainfra;

The following utility purges both design-time and runtime data and resets the environment to the installation time.

ant -f ant-hcfp-util.xml hcfppurge

Table 16-1 lists the options for this utility.

Table 16-1 Options for hcfppurge utility

Option

Description

Domain

Required

mode

Specifies purging design-time or runtime data (see Note below).

Runtime options: msgstate/start/end/purgecontrolnumber

Design-time options: host

DT
RT

Yes

msgState

Deletes messages with the specified message state. Used for runtime data.

MSG_COMPLETE
MSG_ERROR
MSG_WAIT_TRANSMIT
MSG_WAIT_FA
MSG_WAIT_BATCH

No. If msgstate is present, then start and end must be used.

purgecontrolnumber

Deletes control numbers. Used for runtime data.

true

false (default)

No

fromdate

Deletes all messages, which created on or after this date.

Date format

dd/mm/yyyy hh:mm AM/PM

No

todate

Deletes all messages, which created on or before this date.

Date format

dd/mm/yyyy hh:mm AM/PM

No

direction

Direction of the message

No

msgtype

Type of the message

No

archive

Should archive

Default value is true

archivename

File name of archived file

No

Note:

When only -Dmode=RT -Dtp=endpoint_name options are used, this option deletes all records matching endpoint name with SenderName or in Receiver Name.

Example 16-1 Removes Design-Time Data

ant -f ant-hcfp-util.xml hcfppurge -Dmode=DT

Example 16-2 Purges runtime Data

ant -f ant-hcfp-util.xml hcfppurge -Dmode=RT -Darchive=false

Example 16-3 Purges runtime Data, Including Control Numbers

ant -f ant-hcfp-util.xml hcfppurge -Dmode=RT -Dpurgecontrolnumber=true

Example 16-4 Purges Messages with the Specified State Between the Specified Dates

ant -f ant-hcfp-util.xml hcfppurge -Dmode=RT -Dfromdate="01/02/2009 12:00 AM" -Dtodate="10/02/2009 12:00 AM" -Dmsgstate=MSG_COMPLETE -Darchive-false

Note:

When using archivename the value must be a unique file name. An existing file name used with archivename throws an exception.

16.3 Importing Data

Note:

No security or permission checks are performed to prevent the logged-in user from importing data.

The hcfpimport utility imports the Oracle Healthcare metadata ZIP file to the repository. Basic validation is performed, but it is not a complete validation as with deployment validation. No data is overwritten unless you use the overwrite option.

The following usage imports data from tmp/export.zip to a location on the same server without overwriting.

ant -f ant-hcfp-util.xml hcfpimport -Dlocalfile=true -Dexportfile="/tmp/export.zip"

Table 16-2 lists the options for this utility.

Table 16-2 Options for hcfpimport utility

Option

Description

Domain

Required

exportfile

Location of the export (ZIP) file

-

Yes

overwrite

Overwrites the existing business elements. For example, an existing endpoint with the same endpoint name as an endpoint in the import file is replaced if this option is set to true.

true

false (default)

No

localfile

If the export file location exists on the server, then set this option to true to improve performance. The export file must be on the server on which Oracle Healthcare is running.

true

false (default)

No

active

Enable all the endpoints after import

true

false (default)

No

16.4 Exporting Data

The hcfpexport utility exports metadata from the Oracle Healthcare repository. If no options are specified, then the entire repository is exported.

Note:

No security or permission checks are performed to prevent the logged-in user from exporting data.

The following usage exports the entire repository (without policy details) to /tmp/export.zip if no other options are specified.

ant -f ant-hcfp-util.xml hcfpexport

Table 16-3 lists the options for this utility.

Table 16-3 Options for hcfpexport utility

Option

Description

Domain

Required

exportfile

Location of the ZIP file where the exported data is stored

/tmp/export.zip (default)

No

endpoint

Name of the endpoint

No

policies

Set to true to export the entire repository with user and role details, which is needed for the policy store. A warning is displayed to remind you to export the policy store also.

true

false (default)

No

localfile

Set to true for improved performance if the export file is on the same computer as Oracle Healthcare.

true

false (default)

No

Example 16-5 Exports entire repository with policy details to /tmp/export.zip

ant -f ant-hcfp-util.xml hcfpexport -Dexportfile="/tmp/export.zip" -Dpolicies=true

Example 16-6 Exports entire repository w/o details to /tmp/exportinserver.zip on same server

ant -f ant-hcfp-util.xml hcfpexport -Dexportfile="/tmp/exportinserver.zip" -Dlocalfile=true

Example 16-7 Exports the Endpoint Admission to /tmp/export.zip

ant -f ant-hcfp-util.xml hcfpexport -Dexportfile="/tmp/export.zip" -Dendpoint=Admission

16.5 Batching Operations

The command line hcfpbatch utility enables you to create and delete batches, based on various criteria. This is an ANT-based command, and provides the flexibility to selectively set the criteria to create batches.

The usage is as follows:

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=<EndpointName> -Dbatchtime=<batchTriggerTime> -Dbatchname=<batchName> -Ddocument=<documentProtocolName> -Ddocrevision=<docRevision> -Ddoctype=<docType> -Disrepetitive=<true|false>

Table 16-4 lists the options for this utility.

Table 16-4 Options for hcfpbatch utility

Option

Description

Domain

Required

endpoint

Endpoint name.

Specify the endpoint name.

YesFoot 1

batchname

Batch name.

Specify a name for the batch.

Yes

batchtime

Batch trigger time.

The trigger time can be a cron String or the date in
dd/MM/yyyy HH:mm AM/PM format.

Yes

document

Document Protocol name.

Valid values:
EDI_EDIFACT, EDI_X12

Yes

docrevision

Document revision.

-

Yes

doctype

Document type.

-

Yes

isrepetitive

To enable repetitive batching when batch is created using cron string.

Valid values: true or false

No

mode

Mode

Set to deletebatch to delete the batch.

No

Footnote 1 To create a batch the endpoint, batchtime, batchname, document, docrevision, doctype options are required, to delete a batch only the mode and batchname options are required.

Note:

While creating a cron job for the commandline operation, you need to follow the cron syntax.

Example 16-8 Creates a batch operation

This command creates a batch operation with FileEndpoint for the X12/4010/850 document that is executed in a repetitive mode for the given cron String.

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=FileEndpoint -Dbatchtime="0 4850 11 7 5 ? 2010" -Dbatchname=batch1234 -Ddocument=EDI_X12 -Ddocrevision=4010 -Ddoctype=850 -Disrepetitive=true

Example 16-9 Creates batches for multiple document types

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=FileEndpoint -Dbatchtime="0 58 11 7 5 ? 2010" -Dbatchname=batch1234 -Ddocument=EDI_X12 -Ddocrevision=4010 -Ddoctype=850,997

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=FileEndpoint -Dbatchtime="07/05/2010 11:45 AM" -Dbatchname=batch1234 -Ddocument=X12 -Ddocrevision=4010 -Ddoctype=850,997

Example 16-10 Deletes a batch operation

ant -f ant-hcfp-util.xml hcfpbatch -Dmode=deletebatch -Dbatchname=batch1234

Example 16-11 Using special characters in batchtime option

If the value for the batchtime contains special characters such as * or #, then the character must be escaped using double quotation marks.

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=FileEndpoint -Dbatchtime='0 5,10,15,20,25,30,35,40,45,50,55,59 "*" "*" "*" ? 2010' -Dbatchname=batch1234 -Ddocument=EDI_X12 -Ddocrevision=4010 -Ddoctype="850,855" -Disrepetitive=true

16.6 Resubmitting a Message

The following utility resubmits an application message or a wire message for a selected business message.

ant -f ant-hcfp-util.xml hcfpresubmit

Note:

The resubmit functionality for payload rectification will only work for Outbound Message for AppMessage only. This is not valid for inbound cases.

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Dmsgid=12345 -Dpayloadpath=/scratch/<username>/fmwhome/AS11gR1SOA/bin/3a4_req.xml

Table 16-5 lists the options for this utility.

Table 16-5 Options for hcfpresubmit utility

Option

Description

Domain

Required

direction

The direction of the message

INBOUND

OUTBOUND

No

msgsource

The message source

APPMSG (Default)

WIREMSG

Yes

msgid

The message ID

Can be multiple message IDs separated by comma

doctype

Document Type

msgstate

Message State

fromdate

The sendTimestamp of the message

Date format to be provided within Double Quotes

dd-mm-yyyy hh:mm AM/PM

Note: This cannot be a future date.

todate

The sendTimestamp of the message

Date format to be provided within Double Quotes

dd-mm-yyyy hh:mm AM/PM

Note: todate should be greater than fromdate. You can provide both the dates.

payloadpath

This option is applicable for outbound application message resubmission, by providing the rectified file path.

Example 16-12 Resubmits an Outbound Message with Message ID 12345

ant -f ant-hcfp-util.xml hcfpresubmit -Ddirection=OUTBOUND -Dmsgsource=APPMSG -Dmsgid=12345\

Other Examples

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Ddoctype=850

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Dfromdate="29/11/2009 5:40 AM" -Dtodate="30/11/2009 7:39 AM"

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=WIREMSG -Dmsgstate=MSG_ERROR

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Dfromdate="29/11/2009 5:40 AM" -Dtodate="30/11/2009 7:39 AM" -Ddirection=OUTBOUND

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Dfromdate="29/11/2009 5:40 AM" -Dtodate="30/11/2009 7:39 AM" -Ddirection=INBOUND

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Dmsgid=12345 -Dpayloadpath="/tmp/850.xml"

16.7 Scheduling Endpoint Downtime

Various Endpoint parties schedule their downtimes for different reasons and notify their partners about the downtime. During a downtime, parties sending the messages might not reach the destination. Scheduling the Endpoint downtime ensures that the messages are not delivered during that period, yet the messages are processed by Oracle Healthcare so that the messages are ready for delivery when the Endpoint party comes up after the downtime.

The following utility schedules downtime for an endpoint.

ant -f ant-hcfp-util.xml hcfpschedule

Table 16-6 lists the options for this utility.

Table 16-6 Options for hcfpschedule utility

Option

Description

Domain

Required

mode

Indicates if the script will schedule or unschedule a downtime.

schedule (default)

unschedule

Yes

schedulename

A descriptive name for the scheduled downtime

-

Yes

endpoint

Endpoint name

-

Yes

(except in unschedule mode)

fromdate

The date and time at which to begin the downtime.

Date format to be provided within Double Quotes

dd/mm/yyyy hh:mm AM/PM

No

todate

The date and time at which to end the downtime.

Date format to be provided within Double Quotes

dd/mm/yyyy hh:mm AM/PM

No

extend

Extends a previously created schedule.

true

No

The following are examples of scheduling endpoint downtime using the hcfpschedule utility. The command does not need to be in a single line.

Example 16-13 Schedules endpoint downtime for all channels of GlobalChips from "14/05/2010 00:14 AM" to "14/05/2010 00:17 AM"

ant -f ant-hcfp-util.xml hcfpschedule
-Dendpoint="GlobalChips"
-Dfromdate="14/05/2010 00:14 AM"
-Dtodate="14/05/2010 00:17 AM"
-Dschedulename= "Maintenance"

Example 16-14 Un-schedules the scheduled event

ant -f ant-hcfp-util.xml hcfpschedule
-Dmode=unschedule
-Dschedulename="Maintenance"

16.8 Updating Endpoints

The following utility enables you to change an endpoint from active to inactive state or vice-versa:

ant -f ant-hcfp-util.xml hcfpupdateendpoint

Table 16-7 lists the options for this utility.

Table 16-7 Options for hcfpupdateendpoint utility

Option

Description

Domain

Required

endpoint

The name of the endpoint

Specify the endpoint name

Yes

active

To make the endpoint active

true

false

Yes

Example 16-15 Updates an endpoint from the inactive to active state

ant -f ant-hcfp-util.xml hcfpupdateendpoint -Dendpoint=FileEndpoint -Dactive=true

16.9 Deleting Endpoints

The following utility deletes an endpoint.

ant -f ant-hcfp-util.xml hcfpdeleteendpoint

Table 16-8 Options for hcfpdeleteendpoint utility

Option

Description

Domain

Required

endpoint

The name of the endpoint

Specify the endpoint name

Yes

Example 16-16 Deletes an endpoint from the inactive to active state

ant -f ant-hcfp-util.xml hcfpdeleteendpoint -Dendpoint=FileEndpoint

A Back-End Applications Interface

This appendix lists the message properties supported by Oracle SOA Suite for healthcare integration.

The appendix contains the following topics:

- Section A.1, "Mapping SCA Normalized Message Properties"

- Section A.2, "Normalized Message Properties"

A.1 Mapping SCA Normalized Message Properties

Table A-1 maps the SCA normalized message properties to the JMS adapter properties.

Table A-1 Healthcare IP_MESSAGE_TYPE to AS11 SCA Normalized Message Property Mapping

SCA

JMS

hc.messageId

MSG_ID

hc.replyToMessageId

INREPLYTO_MSG_ID

hc.fromEndpoint

FROM_ENDPOINT

hc.toEndpoint

TO_ENDPOINT

hc.action

ACTION_NAME

hc.documentTypeName

DOCTYPE_NAME

hc.documentProtocolVersion

DOCTYPE_REVISION

hc.documentProtocolName

-

hc.documentDefinitionName

-

hc.messageType

MSG_TYPE

hc.conversationId

-

A.2 Normalized Message Properties

Header manipulation and propagation are key business integration messaging requirements. Like other SOA components such as Oracle BPEL Process Manager, Oracle Mediator, and Oracle JCA, Oracle SOA Suite for healthcare integration relies on header support to solve integration needs. For example, you can preserve a file name from the source directory to the target directory by propagating it through message headers.

Normalized messages have two parts, properties and payload. Typically, properties are name-value pairs of scalar types. To fit the existing complex headers into properties, properties are flattened into scalar types.

Table A-2 lists the predetermined properties of a normalized message for Oracle SOA Suite for healthcare integration.

Table A-2 Properties for Oracle SOA Suite for healthcare integration

Property Name

Propagable (Yes/No)

Direction (Inbound /Outbound)

Data Type

Range of Valid Values

Description

hc.conversationId

No

Both

String

-

The ID used to relate the message to the message response

hc.documentDefinitionName

No

Both

String

-

The document definition

hc.documentProtocolName

No

Both

String

-

The document protocol

hc.documentProtocolVersion

No

Both

String

-

The document version

hc.documentTypeName

No

Both

String

-

The document type, for example, 850 for an EDI X12 document

hc.fromEndpoint

No

Both

String

-

The trading partner identifier of the sender, for example, the name, such as Acme, or a DUNS number

hc.messageId

No

Both

String

-

A unique message ID, not directly related to ECID. (ECID information is stored in the B2B AppMessage table.)

hc.messageType

No

Both

String

-

Message type values are:

- Request = 1

- Response = 2

- Functional Ack = 9

hc.replyToMessageId

No

Both

String

-

The message ID to which the sending message is replying

hc.toEndpoint

No

Both

String

-

The trading partner identifier of the receiver, for example, the name, such as Acme, or a DUNS number.

B Creating Endpoints with Different Transport Protocols

The appendix covers how to create endpoints with different bidirectional and single-directional transport protocols.

Oracle SOA Suite for healthcare integration enables you to create endpoints with different bidirectional and single-directional transport protocols.

B.1 Creating Bidirectional Endpoints

The supported bidirectional protocols are MLLP 1.0, MLLP 2.0, Generic TCP, and HLLP.

B.1.1 Creating an MLLP 1.0 Endpoint

This section covers how to create a bidirectional endpoint with the MLLP 1.0 transport protocol.

To create an endpoint with the MLLP 1.0 transport protocol:

1. Log on to the Oracle SOA Suite for healthcare integration user interface.

2. In the Configuration tab under the Design tab, click the Endpoint folder and then click the Create icon as shown in Figure B-1.

Figure B-1 Create Endpoint Icon

3. In the Create window, enter the following and click OK, as shown in Figure B-2:

- Name: Name of the endpoint.

- Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select MLLP10.

- Connection Mode: Server or Client. If the endpoint is configured as server, Oracle SOA Suite for healthcare integration engine starts listening on a port and waits for a client to connect to it. In general, the server connection mode is for inbound case. When configured as client, the engine connects to hostname and port of a remote computer or device. In general, this is for an outbound case.

- Host Name: In case of an MLLP 1.0 Server endpoint, it should be name or IP address of the computer hosting Oracle SOA Suite, and in the case of an MLLP Client endpoint, it should be the remote host name or device name. Typically, this should be localhost. However, Host name can also be the name of the remote host or device.

- Port: port number should be more than 500. If the connection mode is set to Server, then the port must be a valid TCP port number. If the connection mode is set to Client, then the port must be the same as the port used on the MLLP server.

This creates the endpoint, and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

Figure B-2 Specifying MLLP 1.0 Endpoint Parameters

B.1.2 Creating an MLLP 2.0 Endpoint

This section covers how to create a bidirectional endpoint with the MLLP 2.0 transport protocol.

To create an endpoint with the MLLP 2.0 transport protocol:

1. Repeat Steps 1 and 2 from Section B.1.1, "Creating an MLLP 1.0 Endpoint."

2. In the Create window, enter the following and click OK, as shown in Figure B-3:

- Name: Name of the endpoint.

- Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select MLLP20.

- Connection Mode: Server or Client. If the endpoint is configured as server, Oracle SOA Suite for healthcare integration engine starts listening on a port and waits for a client to connect to it. In general, the server connection mode is for inbound case. When configured as client, the engine connects to hostname and port of a remote computer or device. In general, this is for an outbound case.

- Host Name: In case of an MLLP 2.0 Server endpoint, it should be name or IP address of the computer hosting Oracle SOA Suite, and in the case of an MLLP 2.0 Client endpoint, it should be the remote host name or device name. Typically, this should be localhost. However, Host name can also be the name of the remote host or device.

- Port: A valid TCP port number ranging between 1 and 999999.

This creates the endpoint, and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

Figure B-3 Specifying MLLP 2.0 Endpoint Parameters

Note:

On the endpoint page, ensure that:

- The Acknowledgement Mode is set to Sync.

- In the Transport Protocol Parameters dialog box (displays when you click the Transport Details button), the Permanent Connection check box is selected in the Connection tab.

The reason is that MLLP 2.0 is not supported for Transient connection and for Asynchronous ACK.

B.1.3 Creating a Generic TCP Endpoint

This section covers how to create a bidirectional endpoint with the Generic TCP transport protocol.

To create an endpoint with the Generic TCP transport protocol:

1. Repeat Steps 1 and 2 from Section B.1.1, "Creating an MLLP 1.0 Endpoint."

2. In the Create window, enter the following and click OK, as shown in Figure B-4:

- Name: Name of the endpoint.

- Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select GENERIC TCP.

- Connection Mode: Server or Client. If the endpoint is configured as server, Oracle SOA Suite for healthcare integration engine starts listening on a port and waits for a client to connect to it. In general, the server connection mode is for inbound case. When configured as client, the engine connects to hostname and port of a remote computer or device. In general, this is for an outbound case.

- Host Name: In case of an Generic TCP Server endpoint, it should be name or IP address of the computer hosting Oracle SOA Suite, and in the case of an Generic TCP Client endpoint, it should be the remote host name or device name. Typically, this should be localhost. However, Host name can also be the name of the remote host or device.

- Port: A valid TCP port number ranging between 1 and 999999.

This creates the endpoint, and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

Figure B-4 Specifying Generic TCP Endpoint Parameters

B.1.4 Creating an HLLP Endpoint

HLLP exchange protocol is a variation of the lower layer protocol. It is advanced form of MLLP Exchange Plug-in. It allows error detection and validation of HL7 messages. This protocol is based on TCP transport protocol. This section covers how to create a bidirectional endpoint with the HLLP protocol.

To create an endpoint with the HLLP protocol:

1. Repeat Steps 1 and 2 from Section B.1.1, "Creating an MLLP 1.0 Endpoint."

2. In the Create window, enter the following and click OK, as shown in Figure B-5:

- Name: Name of the endpoint.

- Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select HLLP.

- Connection Mode: Server or Client. If the endpoint is configured as server, Oracle SOA Suite for healthcare integration engine starts listening on a port and waits for a client to connect to it. In general, the server connection mode is for inbound case. When configured as client, the engine connects to hostname and port of a remote computer or device. In general, this is for an outbound case.

- Host Name: In case of an HLLP Server endpoint, it should be name or IP address of the computer hosting Oracle SOA Suite, and in the case of an HLLP Client endpoint, it should be the remote host name or device name. Typically, this should be localhost. However, Host name can also be the name of the remote host or device.

- Port: A valid HLLP port number ranging between 1024 and 65535.

Note:

You need to enable sequencing in the case of HLLP endpoints.

This creates the endpoint, and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

Figure B-5 Specifying HLLP Endpoint Parameters

B.2 Creating Single-Directional Endpoints

The supported single-directional protocols are File, FTP, JMS, and SFTP.

B.2.1 Creating a File Endpoint

This section covers how to create a single-directional endpoint with the File transport protocol.

The File transport enables files to be picked up from a shared file directory.

To create an endpoint with the FILE protocol:

1. Repeat Steps 1 and 2 from Section B.1.1, "Creating an MLLP 1.0 Endpoint."

2. In the Create window, enter the following and click OK, as shown in Figure B-6:

- Name: Name of the endpoint.

- Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select FILE.

- Direction: Inbound or Outbound based on your requirement. If the endpoint is configured as inbound, then it can receive response messages or FAs from other endpoints. Conversely, if the endpoint is configured as outbound, it can send messages or FAs.

- Folder Name: An absolute directory path is recommended. Inbound messages are expected in this folder and outbound messages or FAs need to be delivered here.

This creates the endpoint, and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

Figure B-6 Specifying File Endpoint Parameters

Note:

Once a single-directional transport endpoint (inbound/outbound) is created, then it can be edited later to add inbound or outbound configuration by clicking the Configure link.

B.2.2 Creating an FTP Endpoint

This section covers how to create a single-directional endpoint with the FTP transport protocol.

FTP enables files to be passed with FTP between applications. FTP runs on default port 21.

To create an endpoint with the FTP protocol:

1. Repeat Steps 1 and 2 from Section B.1.1, "Creating an MLLP 1.0 Endpoint."

2. In the Create window, enter the following and click OK, as shown in Figure B-7.

- Name: Name of the endpoint.

- Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select FTP.

- Direction: Inbound or Outbound based on your requirement. If the endpoint is configured as inbound, then it can receive response messages or FAs from other endpoints. Conversely, if the endpoint is configured as outbound, it can send messages or FAs.

- Host name: The name of the host computer.

- Folder Name: An absolute directory path is recommended. Inbound messages are expected in this folder and outbound messages or FAs need to be delivered here.

- User name: The user name (login name) to connect to the target server.

This creates the endpoint, and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

Figure B-7 Specifying FTP Endpoint Parameters

B.2.3 Creating an JMS Endpoint

This section covers how to create a single-directional endpoint with the JMS transport protocol.

JMS enables applications to send and receive messages to and from the queues and topics administered by any Java Message Service (JMS) provider, including Oracle WebLogic JMS and non-Oracle providers such as MQSeries JMS (IBM). If a user name and password are not provided, the local JNDI is used, including in a clustered environment, provided that the destinations are distributed.

To create an endpoint with the JMS protocol:

1. Repeat Steps 1 and 2 from Section B.1.1, "Creating an MLLP 1.0 Endpoint."

2. In the Create window, enter the following and click OK, as shown in Figure B-8.

- Name: Name of the endpoint.

- Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select JMS.

- Direction: Inbound or Outbound based on your requirement. If the endpoint is configured as inbound, then it can receive response messages or FAs from other endpoints. Conversely, if the endpoint is configured as outbound, it can send messages or FAs.

- Destination name: The JNDI name of the JMS queue or topic.

- Connection factory: The JNDI name of the connection factory such as jms/b2b/B2BQueueConnectionFactory.

This creates the endpoint, and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

Figure B-8 Specifying JMS Endpoint Parameters

B.2.3.1 Retrieving Document Information from JMS Headers

Oracle Healthcare supports retrieving of document information such as DOC_TYPE and DOC_REVISION from JMS headers in the following order:

- If these values are found in JMS headers, then Oracle Healthcare uses these values to identify a document.

- If these values are not found in JMS headers, then Oracle Healthcare uses the payload to identify these values.

Note:

The default MSG_TYPE in the case of JMS endpoints are considered as Request. In addition, you can identify the 997 or Acknowledgement messages from DOC_TYPE. So, if you want to pass messages with type other than 997, Acknowledgement, or Request, you need to explicitly pass MSG_TYPE as part of JMS headers.

B.2.4 Creating an SFTP Endpoint

This section covers how to create a single-directional endpoint with the SFTP transport protocol.

SFTP enables files to be passed using SSH FTP. SFTP runs on default port 22, which can be changed to another port.

To create an endpoint with the SFTP protocol:

1. Repeat Steps 1 and 2 from Section B.1.1, "Creating an MLLP 1.0 Endpoint."

2. In the Create window, enter the following and click OK, as shown in Figure B-9.

- Name: Name of the endpoint.

- Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select SFTP.

- Direction: Inbound or Outbound based on your requirement. If the endpoint is configured as inbound, then it can receive response messages or FAs from other endpoints. Conversely, if the endpoint is configured as outbound, it can send messages or FAs.

- Host name: The name of the host computer.

- Port number: A valid SFTP port number within the range of 1 to 999999. The default value is 22.

- Path: The absolute directory path where messages are sent from or received.

- User name: The user name (login name) to connect to the target server.

This creates the endpoint, and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

Figure B-9 Specifying SFTP Endpoint Parameters

C Managing Message Sequencing

This appendix provides information about the command-line and Java-based tools provided by Oracle SOA Suite for healthcare integration to monitor and manage message sequencing. You can use these functions in custom clients.

This appendix includes the following topics:

- Section C.1, "Overview of Sequenced Message Management"

- Section C.2, "Java Methods for Managing Sequenced Messages"

- Section C.3, "Command-Line Tools for Managing Sequenced Messages"

C.1 Overview of Sequenced Message Management

Messages processed through Oracle SOA Suite for healthcare integration are sequenced through the B2B sequence manager. The message sequencing information is stored in the B2B_SEQUENCE_MANAGER database table in order to preserve the correct order of messages. At times, the process of sequencing messages needs to be managed. For example, if a message in an endpoint becomes stacked and cannot be processed, it can block all other messages for that endpoint from being processed. In this case, manual intervention is needed in order to remove or resubmit the message and restart sequencing.

Using the tools provided with Oracle SOA Suite for healthcare integration to monitor and manage message sequencing, you can do the following:

- View all endpoints along with their current state

- View messages by state, endpoint, or a combination of both

- Discard messages by state, endpoint, message ID, or state and endpoint

- Resubmit messages that had errors

- Pause and resume message sequencing for an endpoint.

Note:

You can view the sequenced messages in the Oracle SOA Suite for healthcare integration console. See Section 8.5, "Working with Sequenced Messages" for more details.

C.2 Java Methods for Managing Sequenced Messages

You can use the Java methods provided for sequence message management to create your own clients to monitor and manage the messages in the B2B_SEQUENCE_MANAGER table.

To use the Java methods, create an instance of SequenceManagerUtility using the jndi.properties file as a parameter. For example:

private static Properties getProperties(String s) throws IOException {
Properties properties;
FileInputStream fileinputstream = new FileInputStream(s);
properties = new Properties();
properties.load(fileinputstream);
return properties;             }

SequenceManagerUtility seqUtil = new SequenceManagerUtility(getProperties("/tmp/jndi.properties"));

seqUtil.listSequenceTargets();

For information on creating the jndi.properties file, see Section C.3.1, "Prerequisites for Running Command-Line Tools."

C.2.1 Listing Endpoints With States

You can generate a report that lists the messages that are pending in the sequence table with a specific state and for a specific endpoint. The resulting report includes the message IDs and the corresponding state for each.

The syntax of this method is:

public java.util.List<java.lang.String> listSequenceTargets()
throws java.lang.Exception

C.2.2 Listing Pending Sequenced Messages

You can generate a report of pending sequenced messages based on the state and endpoint of the messages, based solely on the state, or based solely on the endpoint. This command lists the messages that are pending in the sequence table based on the options you specify. The resulting report includes the message IDs and the corresponding state for each. There are four methods you can use to list sequenced messages, depending on the criteria you want to use.

Listing Pending Sequenced Messages Based on State and Endpoint

The syntax of this method is:

public java.util.List<java.lang.String> getSequenceMessagesByTargetAndState(java.lang.String target, java.lang.String state)
throws java.lang.Exception

Parameter

Description

target

The name (or the IP address and port number) for the endpoint for which you want to list messages. For example:

seqUtil.getSequenceMessagesByTargetAndState("TCP://111.34.121.22:2025","STACKED")

state

The state of the messages to include in the report. Specify one of the following states:

- PROCESSED: Message processing is complete and is pending for delivery.

- STACKED: An error has occurred preventing the message from processing.

- PAUSED: The endpoint is paused.

Listing Pending Sequenced Messages Based on State

The syntax of this method is:

public java.util.List<java.lang.String> getSequenceMessagesByTarget(java.lang.String state)
throws java.lang.Exception

Parameter

Description

state

The state of the messages to include in the report. Specify one of the following states:

- PROCESSED: Message processing is complete and is pending for delivery.

- STACKED: An error has occurred preventing the message from processing.

- PAUSED: The endpoint is paused.

Listing Pending Sequenced Messages Based on Endpoint

The syntax of this method is:

public java.util.List<java.lang.String> getSequenceMessagesByTarget(java.lang.String target)
throws java.lang.Exception

Parameter

Description

target

The name (or IP address and port number) for the endpoint for which you want to list messages.

C.2.3 Discarding Messages

You can delete sequenced messages from the B2B_SEQUENCE_MANAGER table based on the following criteria combinations:

- State and endpoint of the messages

- State of the messages

- Endpoint of the messages

- Endpoint direction (for endpoint pairs with both inbound and outbound)

- Message ID

- First message only for an endpoint

The discard methods let you manage the messages in the B2B_SEQUENCE_MANAGER table. This is useful in cases where a message is stacked and is blocking other messages from being processed or when there is an issue with a specific message that means it should not be processed sequentially.

Note:

Discarding messages from the sequence manager table does not delete any of the business messages.

Discarding Sequenced Messages Based on State and Endpoint

The syntax of this method is:

public java.util.List<java.lang.String> discardSequencedMessageByStateAnDendpoint(java.lang.String target, java.lang.String state) throws java.lang.Exception

Or:

public java.util.List<java.lang.String> discardSequencedMessageByStateAnDendpoint(java.lang.String target, java.lang.String state, java.lang.String direction) throws java.lang.Exception

Parameter

Description

target

The name (or IP address and port number) for the endpoint associated with the messages to delete.

state

The state of the messages to delete. Specify one of the following states:

- PROCESSED: Message processing is complete and is pending for delivery.

- STACKED: An error has occurred preventing the message from processing.

- PAUSED: The endpoint is paused.

direction

The direction of the messages in the endpoint pair for which you want to discard messages. Specify INBOUND or OUTBOUND. Only use this option if you are deleting messages for one direction of an endpoint pair.

Discarding Sequenced Messages Based on State

The syntax of this method is:

public java.util.List<java.lang.String> discardSequencedMessageByState(java.lang.String state)
throws java.lang.Exception

Parameter

Description

state

The state of the messages to discard. Specify one of the following states:

- PROCESSED: Message processing is complete and is pending for delivery.

- STACKED: An error has occurred preventing the message from processing.

- PAUSED: The endpoint is paused.

Discarding Sequenced Messages Based on Endpoint

The syntax of this method is:

public java.util.List<java.lang.String> discardSequencedMessageByTarget(java.lang.String target)
throws java.lang.Exception

Or:

public java.util.List<java.lang.String> discardSequencedMessageByTarget(java.lang.String target, java.lang.String direction)
throws java.lang.Exception

Parameter

Description

target

The name (or IP address and port number) of the endpoint for which you want to discard messages.

direction

The direction of the messages in the endpoint pair for which you want to discard messages. Specify INBOUND or OUTBOUND. Only use this option if you are deleting messages for one direction of an endpoint pair.

Discarding Sequenced Messages Based on Message ID

The syntax of this method is:

public java.util.List<java.lang.String> discardSequencedMessageByMessageId(java.lang.String msgId)
throws java.lang.Exception

Parameter

Description

msgId

The message ID of the message you want to discard.

Discarding the First Message for an Endpoint

The syntax of this method is:

public java.util.List<java.lang.String> discardFirstSequemceMessageByTarget(java.lang.String target)
throws java.lang.Exception

Parameter

Description

target

The name (or IP address and port number) of the endpoint for which you want to discard the first message.

C.2.4 Reprocessing a Message

Reprocessing messages is a useful option to make sure messages are processed in sequence after there is an issue with an endpoint (for example, if the endpoint goes down and then resumes processing).

The syntax of this method is:

public boolean processSequenceMessageByMessageId(java.lang.String messageId)
throws java.lang.Exception

Parameter

Description

messageId

The message ID of the message to reprocess.

C.2.5 Pausing and Resuming and Endpoint

There may be times when sequence message processing needs to be paused for a specific endpoint, such as when an external system fails. In this case, the endpoint can be paused until the system is restored. Once the system is restored, you can resume processing for the endpoint. For endpoint pairs, you can pause or resume the endpoint for both inbound and outbound, only for inbound, or only for outbound.

Pausing an Endpoint

The syntax of this method is:

public boolean pauseSequenceTarget(java.lang.String target)
throws java.lang.Exception

Or:

public boolean pauseSequenceTarget(java.lang.String target, java.lang.String direction)
throws java.lang.Exception

Parameter

Description

target

The name (or IP address and port number) for the endpoint you want to pause.

direction

The direction of the messages in the endpoint pair you want to pause. Specify INBOUND or OUTBOUND. Only use this option if you are pausing one direction of an endpoint pair.

Resuming an Endpoint

The syntax of this method is:

public boolean resumeSequenceTarget(java.lang.String target)
throws java.lang.Exception

Or:

public boolean resumeSequenceTarget(java.lang.String target, java.lang.String direction)
throws java.lang.Exception

Parameter

Description

target

The name (or IP address and port number) for the endpoint you want to resume

direction

The direction of the messages in the endpoint pair you want to resume. Specify INBOUND or OUTBOUND. Only use this option if you are resuming one direction of an endpoint pair.

C.3 Command-Line Tools for Managing Sequenced Messages

The command-line tools are run using Apache ant. These tools are for administrator use only. No security or permission checks are performed to prevent the logged-in user from viewing or discarding data.

C.3.1 Prerequisites for Running Command-Line Tools

Before you can run the command-line tools, you need to make sure your environment is configured correctly. Do the following before running any commands:

1. Set the ORACLE_HOME, ANT_HOME, and JAVA_HOME environment variables.
ORACLE_HOME is your Oracle Fusion Middleware installation directory. For example:

set ORACLE_HOME=C:\oracle\Middleware
set ANT_HOME=%ORACLE_HOME%\modules\org.apache.ant_1.7.1
set JAVA_HOME=%ORACLE_HOME%\jdk160_18

2. Create the jndi.properties file.

cd $ORACLE_HOME\Oracle_SOA\bin
ant -f ant-hcfp-util.xml b2bcreate-prop

3. Edit the jndi.properties file to include the weblogic password.

Notes:

- After running any command-line tool, restart the healthcare integration user interface or B2B Console. This is because the interfaces cache some metadata and any command-line action that updated the metadata could lead to invalid cached data.

- All of the command-line tools can be run without any JNDI credentials. To restrict the command-line tools from anonymous use, enter the following information in the jndi.properties file:

java.naming.security.principal=weblogic
java.naming.security.credentials=weblogic_password

C.3.2 Listing Endpoints With States

You can generate a report that lists all the endpoints and their respective states to help you determine the health of each endpoint.

The syntax of this command is:

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=listTargets

Option

Description

-Dmode

The mode in which to run the command. For this purpose, set this option to listTargets.

C.3.3 Listing Pending Sequenced Messages

You can generate a report of pending sequenced messages based on the state and endpoint of the messages, based solely on the state, or based solely on the endpoint. This command lists the messages that are pending in the sequence table based on the options you specify. The resulting report includes the message IDs and the corresponding state for each.

The syntax of this command is:

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=command_mode -Dstate=message_state -Dendpoint=endpoint_name

Option

Description

-Dmode

The mode in which to run the command. For this purpose, set this option to report.

-Dstate

The state of the message to include in the report. Specify one of the following states:

- PROCESSED: Message processing is complete and is pending for delivery.

- STACKED: An error has occurred preventing the message from processing.

- PAUSED: The endpoint is paused.

To generate a report with all states, do not use this option when running the command.

-Dendpoint

The name (or IP address and port number) of the endpoint for which you want to list messages. To generate a report for all targets, do not use this option when running the command.

Example C-1 Listing Sequenced Messages Based on State and Endpoint

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=report -Dstate=STACKED -Dendpoint=Pharmacy01

Example C-2 Listing Sequenced Messages Based on State Only

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=report -Dstate=PROCESSED

Example C-3 Listing Sequenced Messages Based on Endpoint Only

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=report -Dendpoint=Pharmacy01

C.3.4 Discarding Messages

You can delete sequenced messages from the SEQUENCE_MANAGER database table based on the following criteria combinations:

- State and endpoint of the messages

- State of the messages

- Endpoint of the messages

- Message ID

- First message only for an endpoint

Discard mode lets you manage the messages in the B2B_SEQUENCE_MANAGER table. This is useful in cases where a message is stacked and is blocking other messages from being processed or when there is an issue with a specific message that means it should not be processed sequentially.

Note:

Discarding messages from the sequence manager table does not delete any of the business messages.

The syntax of this command is:

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=command_mode -Dstate=message_state -Dendpoint=endpoint_name -Dmsgid=message_id

Option

Description

-Dmode

The mode in which to run the command. For discarding messages, set this option to discard. If you are discarding only the first message in an endpoint, set this option to discardFirst and only specify the endpoint.

-Dstate

The state of the messages to discard. Specify one of the following states:

- PROCESSED: Message processing is complete and is pending for delivery.

- STACKED: An error has occurred preventing the message from processing.

- PAUSED: The endpoint is paused.

To discard messages of all states, do not use this option when running the command.

-Dendpoint

The name (or IP address and port number) of the endpoint for which you want to list messages. To discard messages for all targets, do not use this option when running the command.

-Dmsgid

The message ID of a specific message to delete. When you use this option, you only need to specify the mode and not the target or state.

Example C-4 Discarding Sequenced Messages Based on State and Endpoint

This example deletes all messages from the sequence manager for the Pharmacy01 endpoint with a state of PROCESSED.

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=discard -Dendpoint=Pharmacy01 -Dstate=PROCESSED

Example C-5 Discarding Sequenced Messages Based on State

This example deletes all messages from the sequence manager with a state of PROCESSED.

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=discard -Dstate=PROCESSED

Example C-6 Discarding Sequenced Messages Based on Endpoint

This example deletes all messages from the sequence manager for the Pharmacy01 endpoint.

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=discard -Dendpoint=Pharmacy01

Example C-7 Discarding the First Sequence Message of an Endpoint

This example deletes the first message for the Pharmacy 01 endpoint from the sequence manager.

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=discardFirst -Dendpoint=Pharmacy01

Example C-8 Discarding Sequenced Messages Based on Message ID

This example deletes a single message from the sequence manager, as specified by the message ID.

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=discard -Dmsgid=OAE851ED131B3D6103A00000152F97E9

C.3.5 Reprocessing Messages

You can reprocess sequenced messages by using the hcfpsequencemanager utility.

The syntax of this command is:

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=command_mode -Dmsgid=message_id

Option

Description

-Dmode

The mode in which to run the command. For this purpose, set this option to reprocess.

-Dmsgid

The message ID of a specific message to reprocess. When you use this option, you only need to specify the mode and not the target or state.

Example C-9 Reprocessing a Message

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=reprocess -Dmsgid=32797717

C.3.6 Pausing and Resuming an Endpoint

There may be times when sequence message processing needs to be paused for a specific endpoint, such as when an external system fails. In this case, the endpoint can be paused until the system is restored. Once the system is restored, you can resume processing for the endpoint.

The syntax of this command is:

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=command_mode -Dendpoint=endpoint_name

Option

Description

-Dmode

The mode in which to run the command. For this purpose, set this option to pause or resume.

-Dendpoint

The name (or IP address and port number) for the endpoint you want to pause.

Example C-10 Pausing an Endpoint

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=pause -Dendpoint=Pharmacy01

Example C-11 Resuming an Endpoint

ant -f ant-hcfp-util.xml hcfpsequencemanager -Dmode=resume -Dendpoint=Pharmacy01

D Implementing MLLP with High Availability

This appendix describes how to implement Oracle SOA Suite for healthcare integration applications when using the Minimal Lower Layer Protocol (MLLP) in a high availability environment.

This appendix contains the following topics:

- Section D.1, "Introduction to Healthcare Integration High Availability"

- Section D.2, "Enabling MLLP High Availability in Oracle SOA Suite for Healthcare Integration"

D.1 Introduction to Healthcare Integration High Availability

High availability for Oracle SOA Suite for healthcare integration is handled through the high availability features of WebLogic Server, Oracle database, and Oracle SOA Suite. You can configure Oracle SOA Suite for healthcare integration for high availability by adding Oracle B2B properties in Oracle Enterprise Manager. These properties enable high availability for healthcare integration projects and specify timeout and heartbeat intervals for the servers in the cluster.

All features currently supported for MLLP in Oracle SOA Suite for healthcare integration are also supported in a high availability environment, including message sequencing.

D.1.1 High Availability Processing

In a clustered environment, the first healthcare integration instance to start up and initialize is the instance that handles MLLP traffic. When the instance handling MLLP traffic fails, an inactive instance in the cluster becomes active and takes over the responsibility of handling MLLP traffic within the configured timeout period. All in-flight messages from the failed instance are recovered since message processing is transactional for healthcare integration. This ensures that no messages are lost during failover.

If the instance that fails becomes completely disabled, the second and now active instance continues to pick up messages from and send messages to an outbound distributed queue created specifically for high availability processing. If the initial instance becomes available again, the second instance continues to handle MLLP traffic.

D.1.2 Front-End Failover

A load balancer is used as a failover device in case the active node in the cluster fails. This is required for inbound MLLP traffic when Oracle SOA Suite for healthcare integration is implemented in a clustered environment. The endpoints and external systems use the IP address of the load balancer as the destination connection. This means that all the connections are established in one active node, and message processing is performed across all nodes in the cluster. The load balancer can be configured to distribute the messages evenly among the healthcare integration instances, but only the designated active instance will establish connections. Using cookie-based or active-persistent connections in the load balancer might cause unexpected behavior in the MLLP server. Oracle recommends defaulting to non-persistent connections and verifying the load balancer documentation for persistence settings to eliminate connection losses.

D.1.3 Notion of Active

The "Active" server is the only server in the cluster that can send or receive messages from an endpoint using MLLP. However, the message processing is done by all servers in the cluster. For example, in the outbound case, messages are prepared to be sent by all the servers in the cluster, but the actual sending is restricted to only the active server. It is the same in the inbound case.

D.1.4 Unit of Order (UOO)

This is an Oracle Weblogic server feature for JMS queues. In the default configuration, all messages belonging to the same UOO are "tied" to a specific server. UOO is used to sequence messages within JMS in the Oracle Weblogic server. So, if UOO is being used, the JMS queue to which the UOO is "tied" has to be active to receive messages. This is achieved by using the "Whole Server" migration.

Note:

In an HA environment, when UOO is used, Server Migration needs to be enabled.

D.1.5 External Dependencies

Oracle SOA Suite for healthcare integration relies on the following components:

- Oracle SOA database for messages and message state persistence

- Metadata Services (MDS) repository for instance metadata

D.1.6 Additional Resources

For more information about configuring Oracle SOA Suite for high availability, see the following:

- "Enterprise Deployment Overview" in Oracle Fusion Middleware Enterprise Deployment Guide for Oracle SOA Suite

- Oracle Fusion Middleware High Availability Guide

D.2 Enabling MLLP High Availability in Oracle SOA Suite for Healthcare Integration

To enable Oracle SOA Suite for healthcare integration, you need to define certain B2B properties in Oracle Enterprise Manager. These properties enable high availability for healthcare integration and define timeout and ping intervals for the servers.

To enable MLLP high availability for healthcare integration

1. Log on to Oracle Enterprise Manager.
The URL is http://hostname:port/em

where hostname is the name of the computer on which WebLogic Server is running and port is the port number on which WebLogic Server is listening.

2. In the left navigation panel, expand the SOA node and select soa-infra.

3. Click the SOA Infrastructure menu, point to SOA Administration and then select B2B Server Properties.

Figure D-1 SOA Infrastructure Menu on Enterprise Manager

4. On the B2B Server Properties page, click More B2B Configuration Properties.
The System MBean Browser page appears.

5. Click the Operations tab and then click addProperty.

Figure D-2 System MBean Browser Operations Page

6. In the Value column of the Parameters table, enter b2b.HAInstance in the key row and enter true in the value row.

Figure D-3 Adding the b2b.HAInstance Property

7. Click Invoke.
The new property is saved.

8. Using the above steps, create a new property named b2b.MLLP_HA_Mode and set the value to true.

9. You can define the following optional properties. If these are not defined, the default values are used.

Property

Description

b2b.HAMaxElapsedTimeout

The length of time in minutes before the next active instance takes over responsibility for MLLP traffic after the original instance fails. The default value is 2 minutes; 2 is also the minimum value allowed.

b2b.HAHeartBeatPing

The time interval in minutes between pings to determine whether the servers are alive. The default interval is 1 minute; 1 is also the minimum value allowed.

b2b.transportDispatcherThreadCount

The number of MLLP dispatcher threads to use in high availability mode. This is only used for non-sequenced messages, and is used in conjunction with a JMS resource.

b2b.transportDispatcherThreadSleepTime

The length of time (in milliseconds) after which an MLLP dispatcher thread will sleep after message processing.

b2b.MaxTimeinAcquiredState

The length in time in (minutes) that a message is in ACQUIRED state during failover after which it resumes processing.

b2b.AcquiredStatePollingInterval

The length in time in minutes before a message in the ACQUIRED state is polled again.

b2b.SingleTransactionAtInbound

In the case of an inbound MLLP HA, if the server crashes after wire message has been committed to the database but before the event gets enqueued to Event Queue, it is perpetually stuck in the Sequence Manager table and is not processed. This blocks the inbound message flow in the sequencing case.

Set the b2b.SingleTransactionAtInbound to true only in the case of MLLP HA to enable the JMS and database commit to take place in a single transaction. It is suitable only for the MLLP case where only one inbound message is received at a time.

10. When you are done adding properties, click Return.

11. After you define high availability properties, you can view them on the Attributes tab. To view the properties, click the Attributes tab and then click Properties. Expand the Element nodes in the Value table to see the property names and values.

Figure D-4 High Availability Properties in Enterprise Manager

E Batching HL7 Messages

This appendix provides information on implementing HL7 Batching in Oracle SOA Suite for healthcare integration. Batching allows a batch number of messages to be sent in a single file using an envelope consisting of File and Batch headers. An example would be the Batch of Detailed Financial Transactions (DFTs) sent from an ancillary system (such as laboratory, radiology, pharmacy, and so on) to a financial system.

Using the Healthcare console, you can also specify the number of records to be committed when there is a large number of business messages for a message exchange by using the Partial Batch Commit Size field in the Administration tab under Settings > Runtime > Miscellaneous.

This appendix contains the following topics:

- Section E.1, "Introduction to HL7 Message Batching"

E.1 Introduction to HL7 Message Batching

You can batch HL7 messages based on:

- Batch with File header (FHS)

- Batch with Batch header (BHS)

- Batch with both FHS & BHS

- Batch with only Message header (MSH)

You can batch HL7 messages in two ways:

- Standard Mode: Using HL7 batching protocol

- Custom Mode

E.1.1 Batching with File Header (FHS)

You can configure a default FHS using the Oracle SOA Suite for healthcare integration console.

To configure a default FHS:

1. Log on to the Oracle SOA Suite for healthcare integration console.

2. IN the Designer tab, click the Configuration tab, and then expand Document Protocol > HL7> Document Version.

3. Double-click the Document Version to display the Document Version window on the right-hand pane.

4. Click the File Header tab and then select the Create File Header check box.

5. Provide the required parameter values in the available fields.
See Table 3-2 in Section 3.3.1, "What You May Need to Know About HL7 Document Version Parameters" for more information on the File Header parameters.

6. Click Apply.

Note:

You can create and customize custom File Header ecs files by using Oracle Document Editor, and you can use the same to overwrite the default FHS.

E.1.2 Batching with Batch Header (BHS)

You can configure a default BHS using the Oracle SOA Suite for healthcare integration console.

To configure a default BHS:

1. Repeat Steps 1-3 from Section E.1.1, "Batching with File Header (FHS)."

2. Click the Batch Header tab and then select the Create Batch Header check box.

3. Provide the required parameter values in the available fields.
See Table 3-2 in Section 3.3.1, "What You May Need to Know About HL7 Document Version Parameters" for more information on the Batch Header parameters.

4. Click Apply.

Note:

You can create and customize custom Batch Header ecs files by using Oracle Document Editor, and you can use the same to overwrite the default FHS.

E.1.3 Batching with Message Header (MSH)

In the case of batching MSHs, you can batch all the MSHs separated by a custom delimiter. You can configure this delimiter in the outbound endpoint in the case of Outbound message, and in the listening channel in the case of Inbound message.

See Table 3-2 in Section 3.3.1, "What You May Need to Know About HL7 Document Version Parameters" for more information on the Message Header parameters.

E.1.4 Sending Functional Acknowledgments When Batching

When batching messages using the Oracle SOA Suite for healthcare integration console, you can send Functional Acknowledgement to the endpoints partner in the following ways:

- Single message (Single)

- One Functional Acknowledgement message for every inbound business message (Multiple)

You can specify the Functional Acknowledgement options by using the Ack Mode list in the Miscellaneous tab in the Document Version window as shown in Figure E-1.

Figure E-1 Specifying Functional Acknowledgment Options

You can also send Acknowledgement based on MSH 15 element. MSH 15 can have values such as:

- AL - always

- ER - Error or rejected conditions only

- NE - Never

- SU - successful completion only

Note:

All batched messages are acknowledged in the response batch. An acknowledgment batch may contain acknowledgment messages only for those messages that have errors.

Note:

- Currently, HL7 batching is supported for a single document over Generic File and Generic FTP protocols.

- Message sequencing and batching do not work simultaneously.

E.1.5 Standard Mode of Batching

You use the HL7 batching protocol in the standard mode of batching.

In this mode, multiple messages are placed in a single file by utilizing the HL7 standard batch protocol (FHS and BHS). A typical HL7 batch file structure looks like the following:

[FHS](file header segment)
{--- BATCH begin
[BHS](batch header segment)
{ [--- MESSAGE  begin
MSH   (zero or more HL7 messages)
....
....--- messages may be of same type or different type
....
] }--- MESSAGE end
[BTS](batch trailer segment)
}--- Batch end
[FTS](file trailer segment)

E.1.6 Custom Mode of Batching

In this mode, multiple messages will put into a single file without utilizing above mentioned HL7 standard batch protocol (FHS and BHS), instead utilizing some other custom format as shown below:

MSH
....
....
## --- message separator
MSH
....
....
## --- message separator
MSH
....
....
....

In custom mode, inbound messages are de-batched based on the message separator. The message separator for inbound custom message is derived from the incoming message itself. So no additional configuration is required.

You can specify custom delimiters for de-batching using the Oracle SOA Suite for healthcare integration console.

To specify custom delimiters:

1. Log on to the Oracle SOA Suite for healthcare integration console.

2. Open the required endpoint (File or FTP).

3. Click the Transport Details button to display the Transport Protocol Parameters dialog box.

4. Click the Format tab, specify the custom delimiter in the Message Splitter field, and click OK to close the dialog box as shown in Figure E-2.

Figure E-2 Specifying Custom Delimiter

5. Click Apply to save the changes made to the endpoint.

Note:

You need to ensure that the message separator string should not appear in message payload, otherwise you may see some unexpected errors.

E.1.7 Commandline Tools for Batching

This sections discusses the commandline tools that are available for batching.

Table E-1 lists the parameters of the batching commandline.

Table E-1 Parameters for Batching Commandline

Parameter Name

Description

Domain

Required

endpoint

Name of the endpoint

-

Yes

batchname

Name for the batch

-

Yes

batchtime

The batch trigger time

A cron String or the date in dd/MM/yyyy HH:mm AM/PM format

Yes

document

The document protocol name

Valid values: EDI_EDIFACT, EDI_X12

Yes

docrevision

The document revision number

-

Yes

doctype

The document tyoe name

-

Yes

isrepetitive

To enable repetitive batching when batch is created using the cron string

true|false (default)

No

mode

The batch mode

Set to deletebatch to delete the batch

No

Examples:

To create a batch operation with FileEndpoint for the ADT_A01 document that is executed in a repetitive mode for the given cron String:

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=FileEndpoint -Dbatchtime="0 4850 11 7 5 ? 2010"-Dbatchname=batch1234 -Ddocument=HL7 -Ddocrevision=2.3.1 -Ddoctype=ADT_A01 -Disrepetitive=true

To create batches for multiple document types:

ant -f ant-hcfp-util.xml hcfbatch -Dendpoint=FileEndpoint -Dbatchtime="0 58 11 7 5 ? 2010"-Dbatchname=batch1234 -Ddocument=HL7 -Ddocrevision=2.3.1 -Ddoctype=ADT_A01

or

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=FileEndpoint -Dbatchtime="07/05/2010 11:45 AM"-Dbatchname=batch1234 -Ddocument=HL7 -Ddocrevision=2.3.1 -Ddoctype=ADYT_A01

To delete a batch operation:

ant -f ant-hcfp-util.xml hcfpbatch -Dmode=deletebatch -Dbatchname=batch1234

If the value for the batchtime contains special characters such as * or # then the character must be escaped using double quotation marks:

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=FileEndpoint -Dbatchtime='0 5,10,15,20,25,30,35,40,45,50,55,59"" "" "*" ? 2010' -Dbatchname=batch1234 -Ddocument=HL7 -Ddocrevision=2.3.1 -Ddoctype="ADT_A01" -Disrepetitive=true

F Configuration for Functional Acknowledgment 999

This appendix provides information about the configuration of Oracle SOA Suite for healthcare integration applications to use the document type 999 Functional Acknowledgment (FA).

This appendix has the following topics:

- Section F.1, "Introduction"

- Section F.2, "Function Acknowledgement 999: Use Cases"

F.1 Introduction

Oracle Fusion Middleware B2B supports document type 999 Functional Acknowledgment (FA), which is used mostly by HIPAA professionals. By default, the document type configuration for FA is 997. However, you can override the default by specifying document type 999 as the FA. In addition, the document protocol version is not attached to the version of the incoming message, which means that you can send 999 v5010x231 for incoming message 837 v5010x223A1.

F.2 Function Acknowledgement 999: Use Cases

If you use X12 as the document protocol, the default Functional Acknowledgment document type is 997. In case of 997, the version for 997 Acknowledgment is the same as the version of the incoming message. During design time in Oracle B2B console, you can override the default 997 FA or the version, or both in the Document Type Parameters page by using the following parameters:

- Functional Acknowledgment Transaction and

- Functional Acknowledgment Transaction Version

The rest of the configuration, such as Document Definition, Delivery Channel, and Trading Partner Agreement is the same as 997.

The following use cases discusses the configuration for FA 999 and 997:

- Use Case 1

- Use Case 2

- Use Case 3

F.2.1 Use Case 1

If you need to use 999 as the FA but want to keep the version the same as the version of the incoming message, then you need to set only the Functional Acknowledgment Transaction to 999 and leave the Functional Acknowledgment Transaction Version blank.

F.2.2 Use Case 2

If you need to use 999 as the FA and also want to keep the version different from the version of the incoming message, then you need to set both Functional Acknowledgment Transaction and Functional Acknowledgment Transaction Version parameters. For example, you need to set Functional Acknowledgment Transaction to 999 and Functional Acknowledgment Transaction Version to 5010X231.

F.2.3 Use Case 3

If you need to use 997 as the FA, but want to keep the version different from the version of the incoming message, you need to set Functional Acknowledgment Transaction to 997 and Functional Acknowledgment Transaction Version to 5010. (assuming that the incoming message version is 4010). However, this use case is not very common.

Figure F-1 shows the configuration for Functional Acknowledgment Transaction and Functional Acknowledgment Transaction Version.

Figure F-1 Configuration for Functional Acknowledgment Transaction

G Audit Reference for Oracle SOA Suite for Healthcare Integration

This appendix provides reference information for auditing in Oracle SOA Suite for Healthcare Integration.

This appendix contains these sections:

- Section G.1, "About Custom and Standard Audit Reports"

- Section G.2, "Audit Events in Oracle SOA Suite for Healthcare Integration"

G.1 About Custom and Standard Audit Reports

The Common Audit Framework in Oracle Fusion Middleware provides a set of standard reports based on your audit records. It also enables you to modify the standard reports and create your own custom audit reports.

This appendix provides details about events that can be audited in Oracle SOA Suite for Healthcare Integration. Use this information to understand the structure of each event record to develop custom reports.

The following documents provide more information to help you write custom reports:

- Attributes of Audit Reports in Oracle Business Intelligence Publisher in the Oracle Fusion Middleware Application Security Guide

- Customizing Audit Reports in the Oracle Fusion Middleware Application Security Guide

The following documents provide additional information about how to configure auditing and view standard reports:

- Configuring auditing for Oracle SOA Suite for Healthcare Integration - See

- List of events audited for Oracle SOA Suite for Healthcare Integration - See

G.2 Audit Events in Oracle SOA Suite for Healthcare Integration

Table G-1 lists the audit events and their attributes:

Table G-1 Oracle SOA Suite for Healthcare Integration Audit Events

Event Category

Event

Attributes used by Event

UserSession

UserLogin

Date, Time, Initiator, EventType, EventStatus, MessageText, ECID, RID, ContextFields, SessionId, TargetComponentType, EventCategory, ThreadId, FailureCode, RemoteIP, Resource, AuthenticationMethod, Reason

UserLogout

Date, Time, Initiator, EventType, EventStatus, MessageText, ECID, RID, ContextFields, SessionId, TargetComponentType, EventCategory, ThreadId, FailureCode, RemoteIP, Resource, AuthenticationMethod, Reason

EndpointManagement

EnableEndpoint

Date, Time, Initiator, EventType, EventStatus, MessageText, ECID, RID, ContextFields, SessionId, TargetComponentType, EventCategory, ThreadId, FailureCode, RemoteIP, Resource, AuthenticationMethod, Reason

DisableEndpoint

Date, Time, Initiator, EventType, EventStatus, MessageText, ECID, RID, ContextFields, SessionId, TargetComponentType, EventCategory, ThreadId, FailureCode, RemoteIP, Resource, AuthenticationMethod, Reason

DocumentManagement

ResubmitMessage

Date, Time, Initiator, EventType, EventStatus, MessageText, ECID, RID, ContextFields, SessionId, TargetComponentType, EventCategory, ThreadId, FailureCode, RemoteIP, Resource, AuthenticationMethod, Reason

PurgeMessage

Date, Time, Initiator, EventType, EventStatus, MessageText, ECID, RID, ContextFields, SessionId, TargetComponentType, EventCategory, ThreadId, FailureCode, RemoteIP, Resource, AuthenticationMethod, Reason

ReadPayload

Date, Time, Initiator, EventType, EventStatus, MessageText, ECID, RID, ContextFields, SessionId, TargetComponentType, EventCategory, ThreadId, FailureCode, RemoteIP, Resource, AuthenticationMethod, Reason

Configuration

Import

Date, Time, Initiator, EventType, EventStatus, MessageText, ECID, RID, ContextFields, SessionId, TargetComponentType, EventCategory, ThreadId, FailureCode, RemoteIP, Resource, AuthenticationMethod, Reason

Export

Date, Time, Initiator, EventType, EventStatus, MessageText, ECID, RID, ContextFields, SessionId, TargetComponentType, EventCategory, ThreadId, FailureCode, RemoteIP, Resource, AuthenticationMethod, Reason

Index
A  B  C  D  E  F  G  H  I  J  L  M  N  O  P  Q  R  S  T  U  W  X

A

Accept Acknowledgement parameter, 3.3.2

Accept Acknowledgement Type parameter, 3.3.1

Ack Mode parameter, 3.3.1

Acknowledgement Mode parameter, 4.4, 7.2

Action parameter, 3.2.2, 3.3.3

Administration tab, 1.4.1.5, 1.4.1.6, 1.4.1.7, 1.4.1.8

administrator role, 14.1

anyType option, 2.2.2.3

Apple Safari, 1.3

Application Acknowledgment Type parameter, 3.3.1

application message instance, 9.3.3

Application Message report filter, 9.2.1

Application Server Connection page, 2.2.2.1

audit levels, 11.1

audit log, 11.3

auditing

about, 11.1

configuring, 11.2

filter conditions, 11.1.2

healthcare UI activities, 11.1.1

auditing user access

about, 11.1

auto-refresh, 8.3.4, 9.2.6 Auto-Refresh Interval (secs) parameter, 13.2, 13.2

B

B2B IP_MESSAGE_TYPE, A.1

Batch Date parameter, 3.3.1

Batch Header Ecs File parameter, 3.3.1

Batch Security parameter, 3.3.1

binding component, 1.1.3

binding components, 2.1.1

creating, 2.2.2

BPEL Process, 2.2.3 Browse Resource Schema option, 2.2.2.3 browsers, supported, 1.3 business message details, 8.6 business message instance, 9.3.1 Business Message Report Filter Editor, 9.2.5 Business Reports Filter Editor, 9.1.1 Business Rule, 2.2.3

C

Callout Directory parameter, 5.3

callouts

about, 1.1.1

creating, 5.3

creating a library JAR file, 5.1.1

defining callout JAR file library location, 5.3

definition, 5.1

implementation class, 5.3

in an endpoint, 5.4

library name, 5.3

overview, 1.4.1.3

parameter attributes, 5.3

predefined XSLTCalloutImpl class file, 5.3

transport, 5.2.1

channels, 1.4.1.5

about, 1.1.1

creating, 7.2

deleting, 7.4

enabling, 7.3

Character Set parameter, 3.3.1 command line tools

hcfpexport, 16.4

hcfpimport, 16.3

hcfppurge, 16.2

introduction, 16

prerequisites for running, 16.1

Composite Instance ID report filter, 9.2.1, 9.2.3 Composite Name report filter, 9.2.1, 9.2.3 Composite Version report filter, 9.2.1, 9.2.3 composites, 2.1 Configuration tab, 1.4.1.1, 1.4.1.2, 1.4.1.3, 1.4.1.4 Connection Factory parameter, 7.2, 7.2 Connection factory parameter, B.2.3 Connection Mode parameter, 4.2, B.1.1, B.1.2, B.1.3, B.1.4 control numbers

purging, 12.1.5

correlation, 7.5 correlation fields, 9.2.1 Correlation From XPath Expression parameter, 3.2.2, 3.3.3 Correlation From XPath Name parameter, 3.2.2, 3.3.3 Correlation From XPath Name report filter, 9.2.1 Correlation From XPath Value report filter, 9.2.1 Correlation To XPath Expression parameter, 3.2.2, 3.3.3 Correlation To XPath Name parameter, 3.2.2, 3.3.3 Correlation To XPath Name report filter, 9.2.1 Correlation To XPath Value report filter, 9.2.1 Country Code parameter, 3.3.1 Create Batch Header parameter, 3.3.1 Create File Header parameter, 3.3.1 creating

dashboards, 8.3.1

internal delivery channels, 7.2

reports, 9.2.1

custom document protocols, 3.2

configuring XPath expressions, 3.2.2.1

D

dashboard

configuring time sliders, 13.2

dashboard editor, 1.4.2 Dashboard tab, 1.4.2 dashboards

about, 8.1

auto-refresh, 8.3.4

configuring, 8.3.3

configuring endpoint details, 13.2

creating, 8.3.1

default, 8.3.2

default time period, 13.2

deleting, 8.3.5

endpoint details, 8.4.2

endpoint summaries, 8.4.1

overview, 1.4.2

refreshing, 8.3.4

summary settings, 1.4.1.6

time sliders, 1.4.1.6

viewing, 8.4

data transformation, 6.1 database, transaction log, 1.1.4 deleting

dashboards, 8.3.5

document definitions, 3.5

endpoints, 4.5

internal delivery channels, 7.4

mapsets, 6.3.3, 6.4.3

reports, 9.2.7

delivery channels, 1.4.1.5

creating, 7.2

deleting, 7.4

enabling, 7.3

delivery channels, internal

about, 1.1.1

Description report filter, 9.2.1, 9.2.2, 9.2.3 Designer tab, 1.4.1 design-time data, 1.4.1.7, 1.4.1.8 design-time metadata, 12.1.1 design-time repository

export file, 12.1.3

exporting, 12.2

Destination Name parameter, 7.2, 7.2 Destination Provider parameter, 7.2 Direction parameter, 4.2, B.2.1 Direction report filter, 9.2.1, 9.2.2, 9.2.3 Document Definition Handling page, 2.2.2.1, 2.2.2.3 Document Definition Handling page, options, 2.2.2.1 Document Definition page, 2.2.2.1 Document Definition report filter, 9.2.1, 9.2.3 document definitions, 3.1.1, 3.4

about, 1.1.1

adding to an endpoint, 4.3

creating, 3.4

definition, 3.4

deleting, 3.5

document hierarchy, 3.1.1 Document parameter, 3.2.2, 3.3.3 document protocol folder, 1.4.1.1 Document Protocol report filter, 9.2.1, 9.2.3 document protocol versions, 3.1.1, 3.4 document protocols, 3.1, 3.4

custom, 3.2

HL7, 3.1.1, 3.3

proprietary transactions, 3.2

Document Routing ID parameter, 3.3.3 Document Type Display parameter, 13.2 Document Type report filter, 9.2.1, 9.2.3 document types, 3.1.1, 3.4 Document Version report filter, 9.2.1, 9.2.3 Domain Name report filter, 9.2.1, 9.2.3 DTD/XSD NamespaceConversion parameter, 3.2.2

E

ECID report filter, 9.2.1, 9.2.3

Element Delimiter parameter, 3.3.1

endpoint details

on dashboards, 8.4.2

Endpoint report filter, 9.2.1, 9.2.2 endpoint summaries

on dashboards, 8.4.1

endpoints

about, 1.1.1, 4.1

adding callouts, 5.4

and mapsets, 6.4.2

associating with document definitions, 4.3

creating, 4.2, 4.2

error messages, 8.6

overview, 1.4.1.2

settings, 1.4.1.6

Enterprise Manager, 9.3.4 Error Code report filter, 9.2.1 error messages

for endpoints, 8.6

viewing, 9.5.1

error messages on reports, 9.5 Error Text report filter, 9.2.1 Escape Character parameter, 3.3.1 export file, 12.1.3, 12.2 exporting, 1.4.1.7, 1.4.1.8, 12.1.2

data, 16.4

export file, 12.1.3, 12.1.3, 12.2

metadata, 12.2, 12.2

restrictions, 12.2

F

File Date parameter, 3.3.1

File Header Ecs File parameter, 3.3.1

File Security parameter, 3.3.1

filter conditions, 11.1.2

filter editor, 9.1.1

Folder Name parameter, 4.2, B.2.1, B.2.2, B.2.4

Functional Ack Handled by B2B parameter, 13.1

Functional Ack Internal Properties parameter, 13.1

functional acknowledgment, 13.1

G

getting started, 1.2

Google Chrome, 1.3

Group Control Number report filter, 9.2.1

H

hcfpexport command line tool, 16.4

hcfpimport command line tool, 16.3

hcfppurge command line tool, 16.2

Health Level 7 (HL7), 3.1, 3.3, 6.4

definition, 3.3

immediate acknowledgment, 3.3.4

negative acknowledgment messages, 3.3.4

healthcare adapter, 2.1.2

about, 2.1

Healthcare Adapter, in the Component Palette, 2.2.2.1, 2.2.2.2 healthcare binding components

creating, 2.2.2

Healthcare Configuration Wizard

about, 2.1.1

Application Server Connection page, 2.2.2.1

Document Definition Handling page, 2.2.2.1, 2.2.2.3

Document Definition Handling page, options, 2.2.2.1

Document Definition page, 2.2.2.1

Operation page, 2.2.2.1, 2.2.2.2

Service Name page, 2.2.2.1, 2.2.2.2

Test Healthcare, 2.2.2.1

Healthcare Configuration, on Document Definition page, 2.2.2.1 healthcare integration repository, 12.1 HIPAA, 6.1, 6.3 HL7, 3.1, 3.3 HL7 Generic ACK parameter, 3.3.2 HL7 V2.3.1

document hierarchy, 3.1.1

Host Name parameter, 4.2, B.1.1, B.1.2, B.1.3, B.1.4 Human Task, 2.2.3

I

Identification End Position parameter, 3.2.2

Identification Expression (XPath) parameter, 3.2.2

Identification Expression parameter, 3.2.2.1.1, 3.2.2.1.2, 3.2.2.1.3

Identification Start Position parameter, 3.2.2

Identification Value parameter, 3.2.2, 3.2.2, 3.2.2.1.1, 3.2.2.1.2, 3.2.2.1.3

Ignore Envelope Parameters parameter, 3.3.1

immediate acknowledgment, 3.3.4

Import Schema from Healthcare option, 2.2.2.3

importing, 1.4.1.7, 1.4.1.8, 12.1.1, 12.1.2

data, 16.3

metadata, 12.2

installing, 1.2 instance data, 12.1.1 Interchange Control Number report filter, 9.2.1 internal delivery channels, 1.4.1.5

about, 1.1.1, 7.1

creating, 7.2

deleting, 7.4

enabling, 7.3

International Version ID Alternate Coding System Name parameter, 3.3.1 International Version ID Alternate Identifier parameter, 3.3.1 International Version ID Alternate Text parameter, 3.3.1 International Version ID Coding System Name parameter, 3.3.1 International Version ID Text parameter, 3.3.1 International Version Identifier parameter, 3.3.1 Internationalization Code Alternate Coding System Name parameter, 3.3.1 Internationalization Code Alternate Identifier parameter, 3.3.1 Internationalization Code Alternate Text parameter, 3.3.1 Internationalization Code Identifier parameter, 3.3.1 Internationalization Code Text parameter, 3.3.1 Internationalization Coding System Name parameter, 3.3.1 Internet Explorer, 1.3 Is Map Payload Alone parameter, 7.2 Is Topic parameter, 7.2

J

JAR file, for callouts, 5.1.1

Java code

adding, 1.1.1

JMS queues, 1.1.1, 1.4.1.5, 7.1 JMS topics, 1.1.1, 1.4.1.5, 7.1

L

log

database, 1.1.4

logging in, 1.3

M

management

tools, 1.1.2

Map ACK Control ID parameter, 3.3.2 mapsets

about, 1.1.1, 6.1

deleting, 6.3.3, 6.4.3

HIPAA, 6.3

HL7, 6.4

in Oracle B2B, 6.3

mapfiles, 6.2

on healthcare integration UI, 6.4

overview, 1.4.1.4

Match report filter, 9.2.1 MDS, 1.1.4, 2.2.2.3, 12.1 Mediator, 2.2.3 Message ID (Business) report filter, 9.2.1, 9.2.2, 9.2.3 Message Type parameter, 7.2 messages

purging, 9.6

resubmitting, 9.5.2

messages, resubmitting, 9.1.2 metadata, 1.4.1.7, 1.4.1.8

about, 1.1.4

exporting, 12.1.2, 12.2

importing, 12.1.2, 12.2

in SOA Suite, 1.1.3

purging, 12.3

Metadata Services, 1.1.4, 2.2.2.3 metadata services, 12.1 Microsoft Internet Explorer, 1.3 monitor role, 14.1 monitoring

tools, 1.1.2

Mozilla Firefox, 1.3 MSH.11, 3.3.1 MSH.15, 3.3.1 MSH.16, 3.3.1

N

Name parameter, 7.2

Name report filter, 9.2.1, 9.2.2, 9.2.3

Native Message Size report filter, 9.2.1

normalized message properties, A.2

mapping IP_MESSAGE_TYPE to, A.1

Number of Gauge Columns parameter, 13.2

O

Opaque option, 2.2.2.3

Operation page, 2.2.2.1, 2.2.2.2

Oracle Document Editor, 1.1, 1.2, 1.4.1.1, 3.1

document definitions, 3.4

Oracle Healthcare

command line tools, 16

Oracle JDeveloper, 1.2 Oracle SOA Suite, 1.1.3 Oracle SOA Suite for healthcare integration

about, 1.1

P

Page Size parameter, 13.2

Password parameter, 7.2

Payload Display Size (bytes) parameter, 13.2

Payload Key Fields, 9.2.1

payload key fields, 9.2.1

Polling Interval parameter, 7.2

port information, 1.3.1

port numbers, 1.3

Port parameter, 4.2, B.1.1, B.1.2, B.1.3, B.1.4

Processing ID parameter, 3.3.1

proprietary transactions, 3.2

Protocol Message ID report filter, 9.2.1

protocols

custom, 3.2

HL7, 3.1.1, 3.3

Purge Control Number, 12.3 Purge Design Metadata, 12.3 Purge Instance Data, 12.3 purging, 1.4.1.7, 1.4.1.8, 12.1.1, 12.3

about, 12.1.4

control numbers, 12.1.5

data, 16.2

purging messages, 9.6

Q

queues, 1.1.1, 1.4.1.5, 7.1

R

Reattempt Count parameter, 4.4, 7.2

Receive From Internal, 7.2

Refer Schema in HL Repository option, 2.2.2.3

reference, 1.1.3

Reference Name report filter, 9.2.1, 9.2.3

Refresh, on Document Definition page, 2.2.2.1

Repeating Separator parameter, 3.3.1

Replace Existing Metadata option, 12.1.2, 12.2

reports

about, 9.1

application message instance, 9.3.3

auto-refresh, 9.2.6

business message instance, 9.3.1

configuring, 9.2.5

configuring display attributes, 13.2

configuring time sliders, 13.2

creating, 9.2.1

default, 9.2.4

deleting, 9.2.7

overview, 1.4.3

refreshing, 9.2.6

settings, 1.4.1.6

wire message instance, 9.3.2

Reports tab, 1.4.3 repository, for healthcare integration, 12.1 requirements, 1.2 resubmitting messages, 9.1.2, 9.5.2 Retry Interval parameter, 4.4, 7.2 Retype Password parameter, 7.2 roles

administrator role, 14.1

monitor role, 14.1

runtime data, 1.4.1.7, 1.4.1.8 runtime properties, 1.4.1.6 runtime settings

about, 13.1

configuring, 13.1

S

SCA normalized message properties, A.1

Search, on Document Definition page, 2.2.2.1

Security parameter, 3.3.1

Segment Delimiter parameter, 3.3.1

Send to Internal, 7.2

Sequencing parameter, 7.2

service, 1.1.3

service components

about, 2.2.3

Service Name page, 2.2.2.1, 2.2.2.2 Service Name report filter, 9.2.1, 9.2.3 services, 2.1.1 Show Dashboard Editor, 8.3.3 Show field for dashboards, 8.3.3 Show More Endpoint Details, 8.4.2, 8.5 Show Payload parameter, 13.2 SOA application

creating, 2.2.1

restrictions, 2.2.1

SOA composites, 2.1 SOAINFRA database schema, 1.1.4 State report filter, 9.2.1, 9.2.2, 9.2.3 Subcomponent Delimiter parameter, 3.3.1 Subelement Delimiter parameter, 3.3.1 Subscriber id parameter, 7.2

T

Test Healthcare, 2.2.2.1

time sliders, 1.4.1.6

configuring, 13.2

topics, 1.1.1, 1.4.1.5, 7.1 trading partner agreement, 6.3.2 transaction log

database, 1.1.4

Transaction Set Control Number report filter, 9.2.1 Transaction Set ecs File parameter, 3.3.3 transformation mapping, 1.1.1 transforming data, 6.1 Translated Message Size report filter, 9.2.1 Transport Callout parameter, 4.4 transport callouts, 5.2.1 Transport Protocol Name report filter, 9.2.1 Transport Protocol parameter, 4.2, 4.2, 4.4, 7.2, B.1.1, B.1.2, B.1.3, B.1.4, B.2.1, B.2.2, B.2.3, B.2.4 Transport Protocol parameters, 7.2 Transport Protocol Version report filter, 9.2.1

U

Unicode support, 2.2.1, 2.2.1

URL, 1.3

Use JMS id parameter, 7.2

user access auditing, 11.1.2

audit log, 11.3

configuring, 11.2

healthcare UI activities, 11.1.1

user interface

about, 1.4

logging in, 1.3

main page, 1.3

settings, 1.4.1.6

URL, 1.3

user interface settings, 1.4.1.6

configuring, 13.2

User name parameter, 7.2

W

web browsers, supported, 1.3

web services, 2.1.1

wire message instance, 9.3.2

X

XPath Expression1 parameter, 3.2.2, 3.3.3

XPath Expression2 parameter, 3.2.2, 3.3.3

XPath Expression3 parameter, 3.2.2, 3.3.3

XPath expressions, custom documents, 3.2.2.1

XPath Name1 parameter, 3.2.2, 3.3.3

XPath Name2 parameter, 3.2.2, 3.3.3

XPath Name3 parameter, 3.2.2, 3.3.3

XSLTCalloutImpl class file, 5.3

XSLTFile parameter, 3.2.2, 3.3.3

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2014, Oracle and/or its affiliates. All rights reserved.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.