Oracle® Healthcare Translational Research

Installation Guide

Release 3.2

E86017-03

September 2017

Updated to include information for upgrading to 3.2.x patch sets.

Oracle Healthcare Translational Research Installation Guide, Release 3.2

E86017-03

Copyright © 2013, 2017, 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, then 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 about 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 unless otherwise set forth in an applicable agreement between you and Oracle. 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, except as set forth in an applicable agreement between you and Oracle.

Contents

Preface

- Documentation Accessibility

- Finding More Information

- Related Documents

1 Installation Overview

- 1.1 Supported Platforms

- 1.1.1 Database Tier

- 1.1.2 Middle Tier

- 1.2 Supported Browser

- 1.3 Technology Stack

- 1.4 Before You Begin

- 1.5 Architecture

2 Installing the Database Tier

- 2.1 Prerequisite

- 2.2 Preparing to Run the Installer

- 2.3 Installing the Database Tier

3 Installing and Configuring the Middle Tier

- 3.1 Prerequisites

- 3.2 Preparing to Run the Installer

- 3.3 Running the Installer

- 3.4 Check Log Files

- 3.5 Frequently Asked Questions

- 3.6 Updating TRC.properties File

- 3.7 How to Uninstall the OHTR Middle Tier If Needed

4 Configuring Network Data Encryption and Integrity for Oracle Servers and Clients

5 Configuring OBIEE

- 5.1 Deploying the RPD and Catalog

- 5.2 Creating OBIEE Groups and Users

- 5.2.1 Creating OBIEE Groups

- 5.2.2 Creating OBIEE Users

- 5.2.3 Mapping Default OBIEE Roles to User Groups

- 5.2.4 Deploying Help Files for OBIEE Dashboard

A Parallelization

- A.1 Degree of Parallelization

B Statistics

- B.1 Options Used

- B.2 Script to Find Tables for Statistics

Preface

This guide describes how to install Oracle Healthcare Translational Research (OHTR).

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 that have purchased support 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.

Finding More Information

Oracle Help Center

The latest user documentation for Oracle Health Sciences products is available at http://docs.oracle.com/en/industries/health-sciences/.

My Oracle Support

The latest release notes, patches and white papers are on My Oracle Support (MOS) at https://support.oracle.com. For help with using MOS, see https://docs.oracle.com/cd/E74665_01/MOSHP/toc.htm.

Related Documents

Oracle Business Intelligence Enterprise Edition Documentation

The OBIEE documentation is available at http://docs.oracle.com/middleware/12212/biee/index.html.

Oracle Healthcare Foundation

The OHF documentation is available at https://docs.oracle.com/en/industries/health-sciences/oracle-healthcare-foundation/index.html

1 Installation Overview

This chapter describes the Oracle Healthcare Translational Research (OHTR) installation requirements. It contains the following topics:

- Supported Platforms

- Supported Browser

- Technology Stack

- Before You Begin

- Architecture

1.1 Supported Platforms

The following platforms are supported.

1.1.1 Database Tier

OHTR supports all platforms supported for the Oracle Healthcare Foundation database, and the OHTR database tier should be installed on the OHF database.

1.1.2 Middle Tier

OHTR supports all platforms supported for the Oracle Healthcare Foundation middle tier.

1.2 Supported Browser

The supported browsers for OHTR is Windows Internet Explorer IE 11or later, Mozilla Firefox v17 or later, and Google Chrome v12 or later.

1.3 Technology Stack

Following is the required technology stack for OHTR:

- Oracle Healthcare Foundation; for release information see Section 1.4, "Before You Begin".

- Oracle Business Intelligence Enterprise Edition (OBIEE) 12.2.1.2

- Oracle Application Development Framework (ADF) Runtime 12.2.1.2

- Oracle WebLogic Server 12.2.1.2

- Java Development Kit (JDK) 1.8

- Python 2.X (2.6 or higher). Python 3.X is not compatible.

1.4 Before You Begin

OHTR requires the following pre-installation tasks to be completed:

1. Install Oracle Healthcare Foundation.

- For OHTR 3.2, install OHF 7.1.1.

- For OHTR 3.2.1, install OHF 7.1.2.

- For any future releases, check the release notes.

For details, see the Oracle Healthcare Foundation Installation Guide on the Oracle Help Center at

http://docs.oracle.com/health-sciences/translational-research-32/index.html

2. Install Oracle Business Intelligence 12.2.1.2 according to Oracle® Fusion Middleware Installation Guide for Oracle Business Intelligence. Create a separate middleware home with WebLogic Server 12.2.1.2 for OBIEE.

3. Make sure Oracle Fusion Middleware Infrastructure 12.2.1.2 is installed as a part of OHF middle tier (MT) installation.

4. Make sure oh_domain is created at the WebLogic middleware home domain path location.
For details, see the Oracle® Healthcare Foundation Installation Guide on the Oracle Help Center.

1.5 Architecture

OHTR consists of the following tiers:

1. Database tier that includes tables and views (to simplify creating certain patterns of queries), indexes, sequences, and PL/SQL packages. PL/SQL packages are of two types:

- Utility: For example, supporting integration between Cohort Data Mart (CDM) and Oracle Healthcare Omics (OHO).

- Data Movement: Processes data loaded into staging tables.

2. Middle tier consists of a set of ADF-based UIs deployed into WebLogic Server.

Figure 1-1 Data Flow in OHTR

2 Installing the Database Tier

This chapter describes security considerations and the installation process for the database tier. It contains the following topics:

- Section 2.1, "Prerequisite"

- Section 2.2, "Preparing to Run the Installer"

- Section 2.3, "Installing the Database Tier"

2.1 Prerequisite

Install or upgrade the Oracle Healthcare Foundation (OHF) database tier to the release required for the OHTR release you are installing or upgrading to. See the release notes for information.

The installation environment can be either:

- the database server (Exadata computing node) where the OHF database is installed

- a stand-alone Linux server that has the following additional software available:

- Python 2x (2.6.6 or later)

- Oracle 12c client with net services configured to access the OHF database

The following five database schemas are required to store OHTR objects. They are installed during the OHF database installation. Each schema and tablespace may have the default name or a name provided during OHF installation. Note these details, which you will need when you run the OHTR Installer.

- CDM - Cohort Data Mart (CDM) schema stores the clinical information that is refreshed by ETLs.

- ODB - Omics Data Bank (ODB) schema stores the omics data linked to patients as well as genetic reference data to link.

- SVC - Services schema is used by ODB loader APIs.

- ENT - The Enterprise (ENT) schema stores system-wide configuration information like product version.

- JOB_ENGINE - Job Engine (JOB) schema tracks all jobs executed and provides templates for jobs.

The following two additional database schemas are installed by the OHTR Installer. If desired, these schemas and their associated tablespaces can be created earlier in the OHF database by a DBA. If the schemas exist, the OHTR Installer uses them to store application and API objects. Otherwise it creates the tablespaces and schemas first.

- APP - Application schema, which stores information used by user interface.

- CGA - Clinical Genomics API schema, which stores objects used by query or data export API.

2.2 Preparing to Run the Installer

1. Download the OHTR installation package from the Media Pack and extract the files into a directory on the installation server.

2. Navigate to the <media_pack_location>/ folder.

3. Using the following command, unzip the OHTR_Linux-x64.zip file to the folder where you want to launch the installer:

unzip -a OHTR_Linux-x64.zip

4. Navigate to the Disk1/install folder.

5. Change the protection on files using the following command:
chmod 755 *

2.3 Installing the Database Tier

Important:
Ensure that all prerequisites (Section 2.1) have been fulfilled.

To install the OHTR database framework:

1. Start the Oracle Universal Installer (OUI) using the following command:

- If the database server is on the machine where the Installer is running, execute:
sh runInstaller.sh

- If the database server is on a different machine, execute:
sh runInstaller.sh remote_installation=true

- If you are executing the Installer on Linux, change the directory to Disk1/install and run the following command:

bash$  chmod +x unzip runInstaller runInstaller.sh

If the schema name provided here already exists in the OHF database, then that schema is used to install OHTR objects. If it does not exist, the schema will be created.

While creating the OHTR application schema, the Installer prompts for the default and temporary tablespaces for this user. If these tablespaces already exist, they are assigned to the user and quota unlimited is granted on them. Otherwise these tablespaces are created with the datafile located in the user-supplied file destinations:

Database Schema

Default Tablespace

Temporary Tablespace

APP

APP_DATA

TRC_TEMP_TS

CGA

CGA_DATA

TRC_TEMP_TS

2. The Welcome screen appears. Click Next.

3. In the Select a Product to Install screen, select the Oracle Healthcare Translational Research DB Tier 3.2.x option and click Next.

4. In the Specify Home Details screen, enter the installation home name and location, and click Next.

5. In the Verify Installation Prerequisites screen, verify if all the prerequisites are met before proceeding. Click Next.

6. In the Oracle Client Home Configuration screen, specify the Oracle client home path. The installer validates this path. Click Next.

7. In the DB Connection screen, enter values for the following fields and click Next.

- Hostname - By default, the system host name appears

- Port - By default, the port number is 1521. You can edit this field if required.

- Service name

- System user password

- Sys user password

8. In the OHF Schema Details screen, enter values for the following fields and click Next.

Note:
Make sure that the username and password is not the same for all entered schemas.

- Omics data bank schema name

- Omics data bank schema password

- Common data mart schema name

- Common data mart schema password

- Enterprise schema name

- Enterprise schema password

- Job Engine schema name

- Job Engine schema password

9. In the Service Schema Details screen, enter values for the following fields and click Next.

- Services schema name

- Services schema password

10. In the OHTR Schema Details screen, enter values for the following fields and click Next.

- OHTR application schema name

- OHTR application schema password

- Clinical Genomics API schema name

- Clinical Genomics API schema password

11. In the OHTR Tablespace Details screen, enter values for the following fields and click Next.

- Default tablespace for APP schema

- Temp tablespace for APP schema

12. In the Clinical Genomics Tablespace Details screen, enter values for the following fields and click Next.

- Default tablespace for API schema

- Temp tablespace for API schema

13. In the Database Verification screen, verify all the details.

- Click Back to make any changes.

- After verifying that all details are correct, click Install. Click Next.

14. In the Tablespace Datafile Location screen, specify the location of the tablespace data files. This is the directory on the database server where data files are created during installation. Click Next.

15. In the Summary screen, click Install.

16. When the installation is complete, the End of Installation screen appears. Review the information and click Exit.

17. At the confirmation prompt, click Yes to exit the Installer.

18. Review the generated installation log files for errors. If necessary, contact Oracle support to resolve any errors.

3 Installing and Configuring the Middle Tier

This section describes the installation and configuration steps for the middle tier. It includes the following topics:

- Section 3.1, "Prerequisites"

- Section 3.2, "Preparing to Run the Installer"

- Section 3.3, "Running the Installer"

- Section 3.4, "Check Log Files"

- Section 3.5, "Frequently Asked Questions"

- Section 3.6, "Updating TRC.properties File"

- Section 3.7, "How to Uninstall the OHTR Middle Tier If Needed"

The OHTR Middle Tier Installer installs the Clinical Genomics REST APIs and UI application. It also creates OHTR application roles in the WebLogic Server.

3.1 Prerequisites

Make sure that:

- WebLogic Server is installed on the machine.

- OHF Data model schemas are installed using OHF data model installer.

- oh_domain is created in the WebLogic Server using OHF middle tier installer.

- OHTR database schemes are installed using OHTR database installer.

3.2 Preparing to Run the Installer

1. Extract the contents of the OHTR media pack to your system.

2. Open the <media_pack_location>/folder.

3. Execute the following command to unzip the TRC Installer and extract its contents to the location where you want to launch the installer.

unzip -a <TRC_installer_file>.zip

4. Open the Disk1/install folder.

5. Change the protection on files as follows:

chmod 755 *

3.3 Running the Installer

1. Start the Oracle Universal Installer (OUI) by running the following command.

./runInstaller

The Welcome screen appears. Click Next.

2. In the Specify Inventory directory and Credentials screen, enter the path of the inventory directory and click Next.

Note:
This screen is displayed only if the Inventory Location has not already been set up through the Installer.

3. In the Select a Product to Install screen, select Oracle Healthcare Translational Research Middle Tier 3.2.x and click Next.

4. In the Specify Home Details screen, enter the location where you want to install the product. and click Next.

5. In the Install Type screen, select one and click Next:

- Yes to perform a fresh installation.

- No to upgrade your existing OHTR installation.

6. In the Verify Install Prerequisites screen, verify that all prerequisites have been completed and click Next.

7. (Fresh installation only) In the Java Home screen, specify the path where JDK has been installed. The Installer validates this path. Click Next.

8. In the Fusion Middleware Home screen, enter the path to the WebLogic middleware home.The Installer validates the path. Click Next.

9. In the AdminServer Configuration screen, enter the following details and click Next:

- Listen Address

- Listen Port

- SSL Lister Port

- Username - WebLogic administrator username

- Password - WebLogic administrator password

- Verify password

10. (Fresh installation only) In the OHTR Schema Details screen, enter the following details and click Next:

- Database host name

- Database port

- Service name

- Cohort Explorer application schema name

- Cohort Explorer application schema password

- Clinical Genomics API schema name

- Clinical Genomics API schema password

11. In the Choose Network Proxy Configuration screen, select one and click Next:

- Yes to continue with network configuration.

- No if you do not want to configure the network at this time.

Note:
During an upgrade, if you choose No, the values provided during the previous installation are retained.

12. In the Network Proxy Configuration screen, enter the following details and click Next:

- HTTPS proxy host

- HTTPS proxy port

Note:
During an upgrade, the values you enter overwrite the values provided during the previous installation.

13. In the OHTR Configurations screen, select one and click Next:

- Yes to continue with OHTR configuration.

- No if you do not want to configure OHTR at this time.

Note:
During an upgrade, if you choose No, the values provided during the previous installation are retained.

14. In the OHTR and Clinical Genomics API Configuration screen, enter the following details and click Next:

- Dalliance authority name

- Dalliance authority value

- Dalliance UCSC name

- Dalliance UCSC value

- Dalliance sequence URL value

- Dalliance genes URL name

- Dalliance genes URL value

Note:
During an upgrade, the values you enter overwrite the values provided during the previous installation.

15. In the Summary screen, verify all the details.

- Click Back to make any changes.

- After verifying that all details are correct, click Install.

16. When the installation is complete, the End of Installation screen appears. At the confirmation prompt, click Yes to exit the Installer.

3.4 Check Log Files

The installation log files are located at $ORACLE_BASE/oraInventory/logs. For example, /u01/app/oraInventory/logs. The log files are time stamped and each installation session creates a new set of log files. The following installation log files are generated while installing the OHTR middle tier:

Log File

Description

installActions<timestamp>.log

Records the installer actions and can be used to diagnose issues with the installer

oraInstall<timestamp>.out

Records the output of all the scripts run by the installer

oraInstall<timestamp>.err

Records errors from all the scripts run by the installer

If necessary, contact Oracle Support to resolve any errors. While reporting any problems that occur during middle tier installation, make sure that you include all the above log files.

3.5 Frequently Asked Questions

Preventing Wrapping of Data Type Objects

The MT installer performs the steps to prevent wrapping data type installers. To verify this configuration:

1. Log into the Administration Console.

2. In the Domain Structure tree, select Services > Data Sources.

3. On the Summary of Data Sources page, click OH-CGA-APP-DS or OH-TRC-DS.

4. Select the Connection Pool tab.

5. Scroll down and click Advanced to show the advanced connection pool options.

6. Verify if Wrap Data Types check box is not selected.

Application Running Out of Connections

- This issue can be resolved by increasing the number of connections as mentioned below.

- Better performance can be achieved by modifying the following attributes:

- Initial Capacity

- Maximum Capacity: Maximum number of connections depends on the number of users. For example, if there are10 users the suggested number of connections should always be multiplied by 10 (that is, 10 *10 = 100).

- Capacity Increment: This value depends upon the multiplication factor being used to calculate maximum capacity (as per above scenario, it is 10).

For more information, see Tuning Data Source Connection Pools available at

https://docs.oracle.com/middleware/12212/wls/JDBCA/jdbc_datasources.htm#JDBCA712

Increasing the Connection Pool Size

Perform the following steps to increase the connection pool size:

1. Log into the WebLogic console.

2. Navigate to Services > Data Sources.

3. Click the data source for which you want to increase the connection pool size.

4. Navigate to the Connection Pool tab.

5. Specify the number of connections in the attribute Maximum Capacity. Oracle recommends that you set this to at least 100.

6. For details on this configuration, click More Info… right across this attribute.

Increasing Default Row Fetch Size

For better performance, increase the default row fetch size to 100 for both the data sources.

1. Log into the WebLogic console.

2. Navigate to Services > Data Sources under oh_domain.

3. Select the data source OH-TRC-DS.

4. Navigate to Configuration > Connection pool.

5. Edit the property field oracle.jdbc.defaultRowPrefetch as shown in the following example:

user=app
oracle.jdbc.defaultRowPrefetch=100

6. Repeat steps 2 and 3 for the data source OH-CGA-APP-DS.

Increasing the Heap Size

To optimize performance, Oracle recommends that you update the heap memory and fetch size of the WebLogic server with the following values:

- Exadata
Heap Memory: 20GB, Fetch Size: 100

- Non-Exadata
Heap Memory: 8GB, Fetch Size: 100

There are different ways to increase the heap memory. For example, to change the Java Heap size for a managed server:

1. If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.

2. In the left pane of the console, expand Environment > Servers.

3. In the Servers table, click the name of the server instance you want to configure.

4. On the Configuration tab, click Server Start.

5. In the Arguments field, specify the Java option to increase the heap size. For example, Xmx1024m

6. Click Save.

7. To activate these changes, in the Change Center of the Administration Console, click Activate Changes. Not all changes take effect immediately—some require a restart.

8. After you finish, you must reboot the server to use the new heap values.

9. Use the following command to start the WebLogic server:

./startWebLogic.sh -Xms2g -Xmx4g &

3.6 Updating TRC.properties File

The TRC.properties file contains configurable values used in the user interface of the OHTR application. The TRC.properties file is uploaded in the root directory of the WebLogic Server (<FMW_HOME>/user_projects/domains/oh_domain, where FMW_HOME is the home directory of Oracle Fusion Middleware).

Following are descriptions of the file properties.

Table 3-1 Properties in TRC.properties File

Property

User Interface

Description

SF_HOME

View Record

This corresponds to the location of the file system where the result files are stored. This should correspond to TRC_ODB_PERM oracle directory object used when loading result files into the ODB schema.

This location must have the necessary permissions to ensure that the WebLogic user can access this path and read from this location.

MAX_FILE_SIZE

View Record

This corresponds to the maximum file size (in MB) that a user can download.

PT_LIST.MAX_PATIENT_ID

Cohort List

This corresponds to the maximum number of patients or subjects that can be saved in the Cohort List. The maximum value that can be provided is 1000.

GENOMIC.MAX_PATIENT_COUNT

Genomic Data Export

This corresponds to the maximum count of patients or subjects that can be selected for generating the genomic data. This is applicable for all the 3 options on selecting the patients (active query, library query and the ad-hoc patients). If the count of patients or subjects selected is more than this value, an error message is displayed when the Submit button is clicked.

GENOMIC.REPORTS_MAX_PATIENT_COUNT

Cohort Reports

This corresponds to the maximum number of patients whose data can be viewed in the reports. This applies to all options of selecting the Patients/Subjects. If the count of patients or subjects selected is more than this value, a warning message is displayed. You can either continue to plot with a large number of patients/subjects, which might impact performance or change the selected cohort for a smaller number of patients / subjects.

DEFAULT_ACTIVE_QUERY_LIMIT

Cohort Reports

This corresponds to the maximum number of patients /subjects whose data will be plotted when the patient selection mode is Active Query, but the patients/subjects have not been filtered using the Cohort Query screen. If this count is exceeded, then an error message is displayed.

MAX_SPEC_REPORT

Cohort Reports

This corresponds to the maximum number of specimens for which a sample matrix can be plotted. If the number of specimens exceeds this limit, then a warning message is shown and a summary report of genomic information is displayed.

GENOMIC.MAX_GENE_COUNT

Cohort Reports or Genomic Data Export

This corresponds to the maximum count of Gene names that can be selected for generating genomic data. This applies to the Ad-hoc list Gene selection in the screen. If the count of Genes selected is more than this value, an error message is displayed when the Submit button is clicked.

VARIANT_DISPLAY_LIMIT

View Record

This corresponds to the maximum number of records that can be retrieved from the database for displaying variant data.

DEMOGRAPHICS_DISABLED

Cohort Query

Setting this value to True will disable the Demographics criteria on the Cohort Query screen.

CONSENT_DISABLED

Cohort Query

Setting this value to True will disable the Consent criteria on the Cohort Query screen.

DIAGNOSIS_DISABLED

Cohort Query

Setting this value to True will disable the Diagnosis criteria on the Cohort Query screen.

CLINICAL_ENCOUNTER_DISABLED

Cohort Query

Setting this value to True will disable the Clinical Encounter criteria on the Cohort Query screen.

PROCEDURE_DISABLED

Cohort Query

Setting this value to True will disable the Procedure criteria on the Cohort Query screen.

MEDICATION_DISABLED

Cohort Query

Setting this value to True will disable the Medication criteria on the Cohort Query screen.

PATIENT_HISTORY_DISABLED

Cohort Query

Setting this value to True will disable the History criteria on the Cohort Query screen.

TEST_OBSERVATION_DISABLED

Cohort Query

Setting this value to True will disable the Test Or Observation criteria on the Cohort Query screen.

SPECIMEN_DISABLED

Cohort Query

Setting this value to True will disable the Specimen criteria on the Cohort Query screen.

STUDY_DISABLED

Cohort Query

Setting this value to True will disable the Study criteria on the Cohort Query screen.

RELATIVE_TIME_EVENTS_DISABLED

Cohort Query

Setting this value to True will disable the Relative Time Events criteria on the Cohort Query screen.

SEQUENCE_VARIANTS_DISABLED

Cohort Query

Setting this value to True will disable the Sequence Variants criteria on the Cohort Query screen.

COPY_NUMBER_VARIATION_DISABLED

Cohort Query

Setting this value to True will disable the Copy Number Variation criteria on the Cohort Query screen.

DALLIANCE.AUTHORITY_XX

Note: XX is a numerical value; for example 37

View Record

This is one of four property values set to configure a header for a Dalliance instance. The header provides details of the common reference tracks available for display in the instance. This property specifies the Authority suffix (of the genomic reference) for the numeric (XX) value in the property label. For example, NCBI for 36 or GRCh for 37.

Note: A new property should be present for each supported Assembly version.

DALLIANCE.UCSC_NAME_XX

Note: XX is a numerical value; for example 37

View Record

This is one of four property values for a Dalliance instance reference tracks header. It stores the UCSC assembly alias of the reference. For example hg19 for XX value 37.

Note: A new property should be present for each supported Assembly version.

DALLIANCE.SEQ_URL_XXXX

Note: XXXX is the UCSC name value in the second property instance for Dalliance.

View Record

This is one of four property values for a Dalliance instance reference tracks header. It provides the URL for a reference sequence track.

Note: A new property should be present for each supported Assembly version.

DALLIANCE.GENES_URL_XXXX

Note: XXXX is the UCSC name value in the second property instance for Dalliance.

View Record

This is one of four property values for a Dalliance instance reference tracks header. It provides the URL for a reference gene track to be displayed in Dalliance.

Note: A new property should be present for each supported Assembly version.

MICROARRAY_EXPRESSION_DISABLED

Cohort Query

Setting this value to True will disable the MicroArray Expression criteria on the Cohort Query screen.

RNA_SEQ_EXPRESSION_DISABLED

Cohort Query

Setting this value to True will disable the RNA Sequencing criteria on the Cohort Query screen.

3.7 How to Uninstall the OHTR Middle Tier If Needed

To uninstall the OHTR middle tier:

1. Log in to the WebLogic Admin Console.

2. Click Lock and Edit.

3. Select Deployments, then Control, then select the ear files to undeploy:

- OHF-TRC-App: Cohort Explorer UI Application

- OHF-CGA-App: Clinical Genomics API

4. Click Stop.

5. Select Configuration, then Install, then select the ear files and undeploy and delete them.

6. Click Activate Changes.

4 Configuring Network Data Encryption and Integrity for Oracle Servers and Clients

For information on how to configure native Oracle Net Services data encryption and integrity for Oracle Advanced Security, see Oracle Database Advanced Security Administrator's Guide 11g Release 2 at http://docs.oracle.com/cd/E11882_01/network.112/e40393/asoconfg.htm#ASOAG020.

5 Configuring OBIEE

This section describes how to set up the OBIEE server with the RPD and catalog for ad hoc reporting needs as required. It contains the following topics:

- Section 5.1, "Deploying the RPD and Catalog"

- Section 5.2, "Creating OBIEE Groups and Users"

5.1 Deploying the RPD and Catalog

To deploy the RPD and Catalog:

1. Install OBIEE 12.2.1.2.

2. While running the configuration, create a blank OBIEE domain. For details, see Configuring Oracle Business Intelligence at
https://docs.oracle.com/middleware/1221/core/BIEIG/GUID-4F0BD89A-C8BE-4851-8D0C-422779D5BC1D.htm#INSOA375

3. Navigate to the following location on the middle tier installation home:
<TRC_MTIER_HOME>/trcmt/ohf_products/OBIEE/

4. Copy RPD.zip and OracleHealthSciencesCohortExplorer.zip to the OBIEE server.

5. Extract them to a folder on the OBIEE server. This yields the RPD file and the catalog folder.

6. In the Oracle BI Administration Tool, open the extracted Oracle BI repository (OracleHealthSciencesCohortExplorer.rpd) in offline mode and configure database connections.

1. Open the Oracle BI Administration Tool using either:

<OBIEE_DOMAIN_HOME>\bitools\bin\admintool.cmd

or

admintool.sh

2. In the Oracle BI Administration Tool, from the File menu, select Open, then Offline.

3. Select OracleHealthSciencesCohortExplorer.rpd.

4. Enter the repository password to log into the OracleHealthSciencesCohortExplorer.rpd file. The default password is cohort.

Note:
Change the RPD password by selecting Change Password from the File menu. Enter the old and new passwords.

5. Click OK.

7. Modify the connection pools in the RPD:

1. In the physical layer, expand the OracleHealthScienceCohortExplorer node and double-click Connection Pool.

2. Change the following:
Data source name: Enter the TNS entry name of the OHF database instance where OHTR is installed.

User name: Provide the APP schema user name.

Password: Provide the password of the APP schema user. Confirm the new password and click OK.

3. From the File menu, select Save to save the RPD. When the "Do you wish to check global consistency" dialog box appears, click No.

8. Upload the RPD using the following command:

<OBIEE_DOMAIN_HOME>/bitools/bin/datamodel.sh uploadrpd -I <Path extracted to as mentioned in step 5>\OracleHealthSciencesCohortExplorer.rpd -SI ssi -U weblogic -P <weblogic credentials>

You are prompted for the RPD password, which is cohort.

9. Copy the contents of the catalog folder to
<OBIEE_DOMAIN_HOME>/bidata/service_instances/ssi [Service Instance Name]/metadata/content/catalog

10. Check whether tnsnames.ora is present in the location. If not, create it and add a TNS entry for the DB connection. To create the file:

<OBIEE_DOMAIN_HOME>/config/fmwconfig/bienv/core/tnsnames.ora

To add the TNS entry:

trcpdb = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = <ohfdb_server.domain>)(PORT = <PORT_NUMBER>))) (CONNECT_DATA = (SERVICE_NAME = <OHDFDB_SERVICE_NAME>)))

11. Restart the OBIEE services from the Enterprise Manager:

1. Log into the Enterprise Manager.

2. Expand the Target Navigation Menu and navigate to Business Intelligence > biinstance.

3. Click the Availability tab.

4. In the Processes tab, click Restart All. This will restart the BI Instance services.

5. Log into OBIEE.

5.2 Creating OBIEE Groups and Users

5.2.1 Creating OBIEE Groups

1. Log into the Administrator Console for the OBIEE Server at http://<obiee_server>:<admin_port>/console.
<admin_port> is the port where OBIEE WebLogic Enterprise Manager is installed.

2. Click Security Realms in the Domain Structure panel.

3. Navigate to myrealm > Users and Groups.

4. Click the Groups subtab.

5. Click New and create the following groups:

- BIServiceAdministrators

- BIContentAuthors

- BIConsumers

6. Click OK.

5.2.2 Creating OBIEE Users

Create a user having the same credentials as the application user for OHTR and add them to one of the appropriate groups created in Section 5.2.1.

1. Log into the Administrator Console for the OBIEE Server at http://<obiee_server>:<admin_port>/console.
<admin_port> is the port where OBIEE WebLogic Enterprise Manager is installed.

2. Click Security Realms in the Domain Structure panel.

3. Navigate to myrealm > Users and Groups.

4. Click New. Create the user with appropriate credentials.

5. Select the user from the list and click the Groups Tab.

6. Assign one of the user groups (created in Section 5.2.1) to the user.

Note:
The username created for OHTR and OBIEE WebLogic servers should match for access to data based on the VPD policies and other configurations.

5.2.3 Mapping Default OBIEE Roles to User Groups

1. Log into the OBIEE Enterprise Manager at http://<obiee_server>:<admin_port>/em.

2. Click the Weblogic Domain drop-down menu.

3. Select Security > Application Roles.

4. In the drop-down Application Stripe ensure obi is entered and click Search Application Roles (arrow icon). A list is displayed.

5. Select the row for BIServiceAdministrator and click Edit.

6. In the Members table, click Add. The search dialog is displayed.

7. Select Type as Group.

8. Click Principal Name > Starts With.

9. Enter BIServiceAdministrators.

10. Click the arrow button to search.

11. In the Searched Principals, select the row for BIServiceAdministrators.

12. Click OK to add the group as a member.

13. Click OK to save the changes.

14. Repeat steps 3-13 to add:

- Role BIContentAuthor to group BiContentAuthors

- Role BIConsumer to group BIConsumers

15. Log into the Analytics application
http://<OBIEE_SERVER>:<ANALYTICS_PORT>/analytics with the user created in Section 5.2.2.

Granting BIAuthors to Create New Analysis

1. Log into the Analytics application as the "weblogic" user or a user that is part of the BIServiceAdministrators group.

2. Click Administration.

3. Select Manage Privileges.

4. Locate the entry Subject Area: TRC.

5. Click the BI Service Administrator hyperlink. A dialog box is displayed.

6. Click + to search roles to be added for the BI Content Author.

7. Select the BI Content Author entry and click the arrow button to add it to the Selected Members list.

8. Check whether Set Permission to is set to Granted.

9. Click OK.

10. Ensure that the BI Content Author role is selected and click OK to reflect the changes for the Subject Area: TRC.

11. Log in as a user who is a part of the group BIContenAuthors and verify that you have access to the TRC subject area.

5.2.4 Deploying Help Files for OBIEE Dashboard

1. Copy the file <OHTR_MTIER_HOME>/ohf_products/Weblogic/TrcDashboardHelp.war to the OBIEE server location from where it can be deployed.
For example, create a folder upload in the location <OBIEE_DOMAIN_HOME>/servers/bi_server1/.

2. Log into the Administrator Console for the OBIEE Server at http://<OBIEE_SERVER>:<ADMIN_PORT>/console.

3. Navigate to the Deployments page.

4. Click Lock & Edit.

5. In the Summary of Deployments page, click Install.

6. Provide the path where TrcDashboardHelp.war is copied. For example, <OBIEE_DOMAIN_HOME>\servers\bi_server1\upload.

7. Select TrcDashboardHelp.war from the location and click Next.

8. Select Install this deployment as an application.

9. Let the scope remain Global and click Next.

10. In the Available targets for TrcDashboardHelp, select the Clusters (for example, bi_cluster) check box.

11. Click Next.

12. Retain the default options in the remaining screens and click Finish.

13. Click Activate Changes. The following message appears:
All changes have been activated. No restarts are necessary.

14. Verify that the TrcDashboardHelp application is started by navigating to Deployments > Control tab.

15. Search for the application TrcDashboardHelp.

16. If its not in the Active State, select the check box for TrcDashboardHelp and click Start > Servicing all requests.

17. Context-sensitive help in the dashboard will now be available.

A Parallelization

The Oracle database provides numerous ways to configure parallelization and this section describes the exact settings that have been tested for the best performance. Parallel settings are closely related to proper statistics described Appendix B, "Statistics".

A.1 Degree of Parallelization

The installation scripts require a parameter named MAX_PARALLEL_DEGREE to be used for installing the database tier. This parameter relies directly on the number of CPUs that the database server has and must be used carefully to match the capabilities of the database server.

This parameter is used to set the degree of parallelization on the larger tables in CDM and ODB schemas. All other tables are created with the noparallel option. This allows the optimizer to make sure that parallel operations are used with SQL statements that access the larger tables. The value used should also be used in the initialization parameters of the database described below.

Specifying a value that is too large for the capabilities of the database server will cause many waits for parallel slaves. Alternately, specifying a value too small will leave the database with unutilized resources.

The recommendations specified here must be adapted to match the loads of other applications on the database as well as concurrent users. These specifications are described for systems that have an average number of sessions connected to the database that matches the capabilities of the database. If the expected sessions are more than average, smaller values for MAX_PARALLEL_DEGREE should be used.

You must configure the parallel parameters exactly as specified in this section. Any deviation from these instructions can result in unexpected performance.

Table A-1 CPU Sizes and Max Parallel Degree

Database Server

Max Parallel Degree

Quad Core

2

Other Cores

<cpu count> / 4 (not to exceed 8)

Exadata

1/8 rack: 8, 1/4 or higher: 16

In addition to the MAX_PARALLEL_DEGREE, the installer requires initialization parameters for controlling parallel operations to be set as follows:

- parallel_adaptive_multi_user=True

- parallel_automatic_tuning=False

- parallel_degree_limit=<MAX_PARALLEL_DEGREE>

- parallel_degree_policy=LIMITED

- parallel_execution_message_size=16384

- parallel_force_local =TRUE

- parallel_min_time_threshold=AUTO

Note:

- The parallel_degree_limit should match the MAX_PARALLEL_DEGREE used to install the application.

- Set the parallel_degree_policy to LIMITED. The LIMITED policy ensures that the tables used in each SQL statement determines the number of parallel slaves used to execute the SQL.

Oracle recommends that you configure the resource manager to make sure that the database never has run-away processes that may ignore the initialization parameters. The optimizer may have situations where it tries to use more parallel slaves than specified in the initialization parameters. The resource manager is a way to ensure that the SQL statements will never exceed certain thresholds.

The following SQL script is an example that will limit a server to use no more than 16 parallel slaves for Exadata and 8 for Non-Exadata systems. This can be modified to match the MAX_PARALLEL_DEGREE of any server.

Example for Exadata

exec dbms_resource_manager.clear_pending_area();
exec dbms_resource_manager.create_pending_area();
exec dbms_resource_manager.create_plan( plan => 'LIMIT_DOP', comment => 'Limit Degree of Parallelism');
exec dbms_resource_manager.create_plan_directive(plan=> 'LIMIT_DOP',  group_or_subplan =>'OTHER_GROUPS' ,  comment => 'limits the parallelism', parallel_degree_limit_p1=> 16)
exec dbms_resource_manager.validate_pending_area();
exec dbms_resource_manager.submit_pending_area();
alter system set resource_manager_plan = 'LIMIT_DOP' sid='*';

Example for Non-Exadata

exec dbms_resource_manager.clear_pending_area();
exec dbms_resource_manager.create_pending_area();
exec dbms_resource_manager.create_plan( plan => 'LIMIT_DOP', comment => 'Limit Degree of Parallelism');
exec dbms_resource_manager.create_plan_directive(plan=> 'LIMIT_DOP',  group_or_subplan =>'OTHER_GROUPS' ,  comment => 'limits the parallelism', parallel_degree_limit_p1=> 8)
exec dbms_resource_manager.validate_pending_area();
exec dbms_resource_manager.submit_pending_area();
alter system set resource_manager_plan = 'LIMIT_DOP' sid='*';

Another important use of parallel degree is for the OHO loaders. Most SQL loaders used to load files let the user pass a parameter for degree of parallelization. Most of these loaders will create intermediate tables and set the tables to match the passed parameter. This can be used to maximize how many server resources are used.

This value can be adjusted based on the number of other sessions that use the database and also how many concurrent loaders are running. This ensures that the database is used most effectively to load data. For example, performance tests have shown that a 1/4 rack exadata is only used at about 30% loading 8 concurrent sessions for gVCF files and using a degree parameter of 4. This can be used as a guideline to adjust this value for each specific database environment.

B Statistics

To enhance performance, gather statistics on schemas CDM, ODB, ENT, APP, and CGA. If you have uneven data distribution among the schemas, you may want to contact Oracle Support for additional performance recommendations.

B.1 Options Used

Following are the options used while collecting statistics:

- Auto sample size

- Statistics collected only at object level, partition statistics are not collected

- Block sample is used to get a good spread

- Histogram considerations left for Oracle to decide

- DBMS_SCHEMA_STATS used. You may also consider DBMS_TABLE_STATS similar options used as follows:

exec dbms_stats.gather_schema_stats (ownname=> '<OWNER>', method_opt=> 'for all columns size auto', cascade=>true, block_sample => true, granularity => 'GLOBAL', estimate_percent=> dbms_stats.auto_sample_size, options => 'GATHER STALE')

Note:

- In a few cases AUTO_SAMPLE_SIZE considers 100% sample even for large tables. If the statistics are running long, consider setting proper table preferences to lower sample size considerations. Use the following command to set preferences for a specific table.
EXEC DBMS_STATS.SET_TABLE_PREFS(ownname=> '<OWNER>', tabname=>'<TABLE_NAME>', pname => 'ESTIMATE_PERCENT', pvalue => '<sample size>');

After setting proper preferences for all the large or small tables, omit the option or clause estimate_percent=> dbms_stats.auto_sample_size” from above DBMS_STATS.GATHER_SCHEMA_STATS

- Perform one successful statistics collection before using the option options => 'GATHER STALE'

B.2 Script to Find Tables for Statistics

Use the following script to find all the tables in the ODB schema that need to have statistics collected for them.

Note:
Any table that is excluded from this script should have the statistics deleted and locked if they were collected by some other step.

select table_name
from user_tables
where iot_type is null
and substr(table_name,1,9) <> 'W_EHA_STG'
and substr(table_name,-4) <> '_STG'

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2017, Oracle and/or its affiliates. All rights reserved.

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, then 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.

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.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information about 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 unless otherwise set forth in an applicable agreement between you and Oracle. 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, except as set forth in an applicable agreement between you and Oracle.

Pre-General Availability Draft Documentation Notice

If this document is in public or private pre-General Availability status:

This documentation is in pre-General Availability 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.

Private Pre-General Availability Draft Documentation Notice

If this document is in private pre-General Availability status:

The information contained in this document is for informational sharing purposes only and should be considered in your capacity as a customer advisory board member or pursuant to your pre-General Availability trial agreement only. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described in this document remains at the sole discretion of Oracle.

This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this confidential material is subject to the terms and conditions of your Oracle Master Agreement, Oracle License and Services Agreement, Oracle PartnerNetwork Agreement, Oracle distribution agreement, or other license agreement which has been executed by you and Oracle and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

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 that have purchased support 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.