3 Installing and Configuring the Middle Tier

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

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.