Skip Headers

Oracle® Health Sciences Information Gateway Cross Community Access Installation and Configuration Guide Release 2.0.1 E37027-02 |
Home | Book List | Contents | Contact Us

| PDF · Mobi · ePub

# Oracle® Health Sciences Information Gateway

Cross Community Access Installation and Configuration Guide

Release 2.0.1

E37027-02

October 2013

This guide discusses how to install and configure the Oracle® Health Sciences Information Gateway (OHIG) Cross Community Access (XCA) Gateway.

## 1 Getting Started

This section describes the minimum hardware and software requirements for installing XCA Gateway.

### 1.1 Hardware Requirements

The following are the minimum hardware requirements for installing XCA Gateway:

- 4 GB (4096 MB) of RAM

- 12 GB of disk space

- 16 GB of disk space for 64-bit VMs

### 1.2 Software Requirements

The following are the minimum software requirements for installing XCA Gateway:

- Java 1.6 or higher

- Oracle Enterprise Linux 5.5 or higher

- Oracle Database 10+ (11g Release 1)

- Oracle GlassFish Server 2.1.1 Patch 16 or higher

- Oracle WebLogic Server 10.3.6.0 (11g Release 1)

#### 1.2.1 Configuration Requirements

- Apache Ant 1.8.2 executable in path

  `PATH=$PATH:<install_dir>/apache-ant-1.8.2/bin`

### 1.3 Downloading Oracle Health Sciences Information Gateway XCA Gateway

To download the Oracle Health Sciences Information Gateway XCA Gateway, perform the following tasks:

1. Navigate to `http://edelivery.oracle.com`.

2. Enter your Registration information, accept the Agreement Terms by selecting the check boxes, then click Continue.

3. From the Select a Product Pack drop-down menu, select Health Sciences.

4. From the Platform drop-down menu, select Linux x86.

5. Click Go.

6. Select Oracle Health Sciences Information Gateway Media Pack.

7. Click Continue.

8. Click Download for the following and save the files to your system:

   - Oracle Health Sciences Information Gateway 2.0.1 XCA Gateway

9. Extract the files to view the Oracle Health Sciences Information Gateway Cross Community Access Installation and Configuration Guide and get the compressed tar file (`*.tgz`).

## 2 Preparing Database Schemas in Linux

To prepare database schemas in Linux, perform the following:

1. Copy and unzip script files. Ensure SQL Plus is present in PATH.

   Execute the following commands:

   1. `cd <install_dir>/ohig_xca_installer/addons/xcagateway/oracle_db/`

   2. `unzip gateway_oracle_db_scripts.zip`

   3. `cd gateway_oracle_db_scripts`

2. (Optional step) If SQL Plus is not available, copy the zip file `gateway_oracle_db_scripts.zip` to the host system where SQL Plus and Bash or Sh shell are available.

   For example,

   `scp <install_dir>/ohig_xca_installer/addons/xcagateway/oracle_db/gateway_oracle_db_scripts.zip user@sql_plus_host:/tmp/`

3. Log in to the host system where you copied the zip file. Execute the following commands to unzip the file:

   1. `cd /tmp`

   2. `unzip gateway_oracle_db_scripts.zip`

   3. `cd gateway_oracle_db_scripts`

   Note:

   Update the SQL script `create_tblspc_users.sql` with your Oracle Database (DB) specific Tablespace information.

4. Run the `> bash ./create_tblspc_users.sh` script.

5. Enter database connection information and password for GATEWAY user when prompted.

6. Return to the host system where you are installing the XCA Gateway.

## 3 Running the XCA Gateway Installer

To run the XCA Gateway installer, perform the following:

1. Extract the tgz file.

2. Configure the XCA Gateway.

   XCA configuration will be split into two properties files inside the application server, IG.Properties and RG.Properties.

   The location of the properties files is `<application-server>/domains/<domain-name>/config/xca/`.

## 4 Installing the XCA Gateway

Execute the following commands to install the XCA Gateway:

- `$ tar -zxvf ohig_xca_installer.tgz`

- `$ cd ohig_xca_installer`

- `$ java -jar ohig_xca_installer.jar`

To follow prompts, refer to Appendix A: Running Oracle Health Sciences Information XCA Gateway Installer.

## 5 Configuring Initiating Gateway

### 5.1 Providing Local Home Community ID of the Initiating Gateway

Enter the following community IDs for configuring Initiating Gateway (IG):

- `localHomeCommunityId_IG` =

- `localHomeCommunityId_XCPD` =

### 5.2 Configuring the Repository for Initiating Gateway

Prerequisite: Get the repository unique ID and repository URL for retrieving document transactions.

Update the configuration file as follows:

Syntax: `RepositoryUniqueId=RepositoryURL`

For example, `#1.3.6.1.4.1.21367.13.40.39=http://<hostname>:<port>/services/xdsrepositoryb`

### 5.3 Enabling the Grouping Option with Local Document Consumer

Prerequisite to enable grouping: Get the local community registry URL for Stored Query and Repository URL for retrieving document.

Set the following `INGWGroupedWithDocumentConsumer` property to yes to enable the grouping with local document consumer:

- `INGWLocalRegistry` - Takes the value of registry URL.

- `INGWLocalRepository` - Takes the value of repository URL.

- `INGWGroupedWithDocumentConsumer` = no

For example,

- `INGWLocalRegistry` =

- `INGWLocalRepository` =

### 5.4 Configuring Responding Gateway Using Home Community ID

Prerequisite: Responding Gateway (RG) Query and retrieve endpoints.

The following is the syntax for configuring the initiating gateway for a specific home community ID. You can configure multiple responding gateways.

Configuration for query transaction:

- Syntax: `CrossGatewayQuery_homecommunityid=RespondingGatewayQueryURL`

- Syntax: `CrossGatewayRetrieve_homecommunityid=RespondingGatewayRetrieveURL`

### 5.5 Configuring Multiple Responding Gateways for Broadcasting Mode

Prerequisite: All the responding gateways query URLs and home community IDs that needs to be configured.

You can configure multiple responding gateways for the Cross Gateway Query queries by patient ID.

- `XCARespondingGateway_<count>` - This parameter takes the value of the responding gateway query URL.

  `<count>` is the variable which starts from one and can go to any number of responding gateways that you would like to configure.

- `XCARespondingGateway_<count>_HomeCommunityId` - Takes the value of the home community ID of the responding gateway.

For example, when <count> value is 1,

`XCARespondingGateway_1` =

`XCARespondingGateway_1_HomeCommunityId` =

When <count> value is 2,

`XCARespondingGateway_1` =

`XCARespondingGateway_1_HomeCommunityId` =

`XCARespondingGateway_2` =

`XCARespondingGateway_2_HomeCommunityId` =

As mentioned, `<count>` is the number of responding gateways that you plan to configure.

### 5.6 Configuring Local MPI to Initiating Gateway

Prerequisite: Local MPI PDQ Supplier endpoint.

`XCA_Local_PDQSupplier` - Takes the value of the PDQ supplier endpoint URL.

For example,

`XCA_Local_PDQSupplier =`

### 5.7 ATNA Audit Configuration

Prerequisites: Audit repository host name or IP and audit repository UDP or TLS port.

- `ApplicationName`, `sourceApplicationId`, and `sourceEnterpriseId` - Represent the system in the audit message. This can be the name of the clinic.

- `alternateUserId` - Takes the string value. Any user identifier is preferred. This parameter is used if the actual UserId is not found in the transactions.

- `ATNASyslogProtocol` - This value should be set to UDP or TLS.

To enable auditing, set Audit to `Yes`.

For example, Audit Configuration:

`auditRepositoryServer` =

`auditRepositoryPort` =

`sourceApplicationId` =

`sourceEnterpriseId` =

`alternateUserId` =

`ApplicationName` =

`ATNASyslogProtocol` =

`Audit` = no

Note:

For TLS auditing in WebLogic, ensure to start the WebLogic with the following JVM options for the keystore and truststore file:

`-Djavax.net.ssl.keyStore=<keystore file>`

`-Djavax.net.ssl.keyStorePassword=<keystore pass>`

`-Djavax.net.ssl.keyStoreType=<keystore type>`

`-Djavax.net.ssl.trustStore=<truststore file>`

`-Djavax.net.ssl.trustStorePassword=<truststore pass>`

### 5.8 Configuring Number of Threads and Timeout for Initiating Gateway

You can configure one initiating gateway for multiple responding gateways. Multiple threads ensure better performance.

- `maximumThreadCount` - Takes the value of max number of threads that you want to create.

  For example, number of threads required to send the cross gateway requests:

  `maximumThreadCount` =

Time out configurations for the requests:

- `default_timeout_sync` - Takes the value of the time out for synchronous transactions.

- `default_timeout_async` - Takes the value of the time out for asynchronous transactions.

For example,

- `default_timeout_sync` =

- `default_timeout_async` =

## 6 Configuring XCPD Initiating Gateway

### 6.1 Configuring XCPD Responding Gateway

Prerequisite: XCPD URL and Homecommunityid of the responding gateway.

- `XCPD_RespondingGW_<TargetHomeCommunityID>` - Takes the value of the responding gateway XCPD URL.

  `<TargetHomeCommunityID>` should be replaced with the homecommunity id of the responding gateway.

`XCPD_RespondingGW_TargetHomeCommunityID = XCPD Responding Gateway URL`

For example, `XCPD_RespondingGW_1.0 = http://localhost:8080/RespondingGateway_Service/XCPDRespondingGateway`

### 6.2 Configuring Sender and Receiver OIDs

The following properties take sender and receiver OID values appropriately:

- `XCPD_IG_SenderOID` =

- `XCPD_IG_RecieverOID` =

### 6.3 Patient ID Mapping Workflow

The property `PatientID_Mapping_Workflow` takes two values:

- `xca` - When the value is xca, initiating gateway does not send any XCPD request to find patient id in remote community. IG uses the same patient ID that is sent by the document consumer.

- `xcpd`: When the value is xcpd, the initiating gateway will send XCPD request to each configured responding gateway, fetch the patient ID, and uses that patient ID for the respective Cross Gateway Query Transactions.

  For example,

  `PatientID_Mapping_Workflow` =

## 7 Configuring Responding Gateway

### 7.1 Configuring Responding Gateway Local Home Community

Enter the following IDs for configuring responding gateway local home community:

- `localHomeCommunityId_RG` =

- `localHomeCommunityId_XCPD` =

### 7.2 Configuring Responding Gateway's Local Registry Repository

Prerequisite: Responding Gateway's local registry, repository URLs with repository unique ID.

- `RespondingGatewayRegistryURL` =

- `RespondingGatewayRepositoryID` =

Prerequisite: Get repository unique and repository URL for retrieving document transactions.

Update the configuration file as follows:

Syntax: `RepositoryUniqueId=RepositoryURL`

For example, `1.3.6.1.4.1.21367.13.40.39=http://<hostname>:<port>/services/xdsrepositoryb`

### 7.3 ATNA Audit Configuration

Prerequisites: Audit repository host name/IP and Audit repository UDP port.

- `ApplicationName`, `sourceApplicationId`, and `sourceEnterpriseId` - Represent the system in the audit message. This can be the name of the clinic.

- `alternateUserId` - Takes the string value. Any user identifier is preferred. This value is used if the actual UserId is not found in the transactions.

- `ATNASyslogProtocol` - This value should be set to UDP or TLS.

To enable auditing, set Audit to `Yes`.

For example, Audit Configuration:

- `auditRepositoryServer` =

- `auditRepositoryPort` =

- `sourceApplicationId` =

- `sourceEnterpriseId` =

- `alternateUserId` =

- `ApplicationName` =

- `ATNASyslogProtocol` =

- `Audit` = no

Note:

For TLS auditing in WebLogic, ensure to start the WebLogic with the following JVM options for the keystore and truststore file:

`-Djavax.net.ssl.keyStore=<keystore file>`

`-Djavax.net.ssl.keyStorePassword=<keystore pass>`

`-Djavax.net.ssl.keyStoreType=<keystore type>`

`-Djavax.net.ssl.trustStore=<truststore file>`

`-Djavax.net.ssl.trustStorePassword=<truststore pass>`

### 7.4 Timeout Configurations for the Requests

- `default_timeout_sync` - Takes the value of the time out for synchronous transactions.

- `default_timeout_async` - Takes the value of the time out for asynchronous transactions.

For example,

- `default_timeout_sync` =

- `default_timeout_async` =

### 7.5 Configuring Local MPI to Responding Gateway

Prerequisite: Local MPI PDQ Supplier endpoint.

- `XCPD_RG_PDQSupplier<count>` - Takes the value of the PDQ endpoint of the MPI.

- `XCPD_RG_PDQSupplier<count>_domainID` - Takes the value of the domain ID.

For example, IHERED, IHEBLUE, and so on.

XCPD Responding Gateway settings:

You can have multiple PDQ Suppliers to talk with.

- `XCPD_RG_PDQSupplier<count>` =

- `XCPD_RG_PDQSupplier<count>_domainID` =

`<count>` can be replaced with any number of PDQ suppliers that are planned to configure. Responding gateway can look through multiple MPI systems to search for a patient.

For example, when <count> is 1,

`XCPD_RG_PDQSupplier1` =

`XCPD_RG_PDQSupplier1_domainID` =

When <count> is 2,

`XCPD_RG_PDQSupplier1` =

`XCPD_RG_PDQSupplier1_domainID` =

`XCPD_RG_PDQSupplier2` =

`XCPD_RG_PDQSupplier2_domainID` =

### 7.6 Configuring Health Data Locator

To enable Health Data Locator, set the value of `SupportsHealthDataLocatorBelow` property in the RG.properties file to `yes`.

If the value is set to `yes`, RG responds to the XCPD request indicating that it supports patient location query.

If the value is set to `no`, RG does not support Health Data Locator.

## 8 Appendix A: Running Oracle Health Sciences Information XCA Gateway Installer

This appendix describes how to run the XCA Gateway installer. It contains the following topics:

### 8.1 XCA

#### 8.1.1 GlassFish

    $ cd <install_dir>
    $ java -jar ohig_xca_installer.jar
    Oracle HIG XCA Installer 2.0.1.0
    -- Feature
    Choose option install_feature (xcagateway, xcagateway_ig, xcagateway_rg)�
    > xcagateway
    -- Target
    Choose option install_target (glassfish, weblogic)
    > glassfish
    -- Command
    Choose option install_command (usage, version, install)
    > install
    Starting init install
    -- Glassfish install directory
    Enter glassfish_install_dir [#null]
    > /home/hiauser/SUNWappserver
    -- Glassfish domain name
    Enter glassfish_domain_name [domain1]
    >
    -- Glassfish copy ojdbc jar to domain lib ext
    Choose option glassfish_copy_ojdbc_jar_to_domain_lib_ext ([yes], no)
    >
    -- Start glassfish
    Choose option start_glassfish ([yes], no)
    >
    -- Glassfish admin username
    Enter glassfish_admin_username [admin]
    >
    -- Glassfish admin password
    Enter glassfish_admin_password [adminadmin]
    >
    -- Glassfish master password
    Enter glassfish_master_password [changeit]
    >
    -- Glassfish host
    Enter glassfish_host [localhost]
    >
    -- Glassfish admin port
    Enter glassfish_admin_port [4848]
    >
    -- Xca gateway database host
    Enter xcagateway_db_host [localhost]
    >
    -- Xca gateway database port
    Enter xcagateway_db_port [1521]
    -- Xca gateway database sid
    Enter xcagateway_db_sid [orcl]
    > orcl
    -- Xca gateway database gateway username
    Enter xcagateway_db_gateway_username [gateway]
    -- Xca gateway database gateway password
    Enter xcagateway_db_gateway_password [#null]
    -- Glassfish http port
    Enter glassfish_http_port [8080]
    >
    -- Stop glassfish
    Choose option stop_glassfish ([yes], no)
    >

#### 8.1.2 WebLogic

    $ cd <install_dir>
    $ java -jar ohig_xca_installer.jar
    Oracle HIG XCA Installer 2.0.1.0
    -- Feature
    Choose option install_feature (xcagateway, xcagateway_ig, xcagateway_rg)�
    > xcagateway
    -- Target
    Choose option install_target (glassfish, weblogic)
    > weblogic
    -- Command
    Choose option install_command (usage, version, install)
    > install
    Starting init install
    -- Start weblogic
    Choose option start_weblogic ([yes], no)
    >
    -- Weblogic install directory
    Enter weblogic_install_dir [#null]
    > /home/hiauser/Oracle/Middleware
    -- Weblogic jdk directory
    Enter weblogic_jdk_dir [/home/common/java/jdk1.6.0] based on [${install_java_home}]
    >
    -- Weblogic domain name
    Enter weblogic_domain_name [domain1]
    >
    -- Weblogic domain directory
    Enter weblogic_domain_dir [/home/hiauser/Oracle/Middleware/user_projects/domains/domain1] based on [${weblogic_install_dir}${/}user_projects${/}domains${/}${weblogic_domain_name}]
    >
    -- Weblogic admin username
    Enter weblogic_admin_username [weblogic]
    >
    -- Weblogic admin password
    Enter weblogic_admin_password [welcome1]
    >
    -- Weblogic admin protocol
    Enter weblogic_admin_protocol [t3]
    >
    -- Weblogic host
    Enter weblogic_host [localhost]
    >
    -- Weblogic admin port
    Enter weblogic_admin_port [7001]
    >
    -- Xca gateway database host
    Enter xcagateway_db_host [localhost]
    >
    -- Xca gateway database port
    Enter xcagateway_db_port [1521]
    -- Xca gateway database sid
    Enter xcagateway_db_sid [orcl]
    > orcl
    -- Xca gateway database gateway username
    Enter xcagateway_db_gateway_username [gateway]
    -- Xca gateway database gateway password
    Enter xcagateway_db_gateway_password [#null]
    >
    -- Weblogic server name
    Enter weblogic_server_name [AdminServer]
    >
    -- Stop weblogic
    Choose option stop_weblogic ([yes], no)
    >

## 9 Appendix B: XCA Endpoints

Use the endpoints in Table 1 to configure XCA clients as needed.

Table 1 XCA Transactions and Endpoint URLs

Transaction | Endpoint URL
--- | ---
Initiating Gateway Cross Gateway Query (ITI-18) | `http://<XCA_HOST>:<PORT>/InitiatingGatewayQuery_Service/XCAInitiatingGatewayQuery`
Initiating Gateway Cross Gateway Retrieve (ITI-43) | `http://<XCA_HOST>:<PORT>/InitiatingGatewayRetrieve_Service/XCAInitiatingGatewayRetrieve`
Responding Gateway Cross Gateway Query (ITI-38) | `http://<XCA_HOST>:<PORT>/RespondingGatewayQuery_Service/XCARespondingGatewayQuery`
Responding Gateway Cross Gateway Retrieve (ITI-39) | `http://<XCA_HOST>:<PORT>/RespondingGatewayRetrieve_Service/XCARespondingGatewayRetrieve`
XCPD Responding Gateway (ITI-55) | `http://<XCA_HOST>:<PORT>/RespondingGateway_Service/XCPDRespondingGateway`
Patient Location Query (ITI-56) | `http(s)://<XCA_HOST>:<PORT>/RespondingGateway_Service/XCPDRespondingGateway`
Asynchronous Registry Stored Query (ITI-18) | `http(s)://<XCA_HOST>:<PORT>/IGAsyncServices/XCAInitiatingGatewayQuery`
Asynchronous Retrieve Document Set (ITI -43) | `http(s)://<XCA_HOST>:<PORT>/IGAsyncServices/XCAInitiatingGatewayRetrieve`

## 10 Appendix C: Acronyms

This section provides a list of commonly used acronyms.

- IG - Initiating Gateway

- OHIG - Oracle Health Sciences Information Gateway

- RG - Responding Gateway

- XCA - Cross Community Access

- XCPD - Cross-Community Patient Discovery

## 11 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.

Oracle® Health Sciences Information Gateway Cross Community Access Installation and Configuration Guide, Release 2.0.1

E37027-02

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

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.