Custom Installation

Learn how to use the installer

TIES TCRN Node Installation Plan

Contents

Introduction

This TIES TCRN Node Installation Plan sets forth the process, methods, and procedures that can be used by an institution when establishing a public and private node sufficient to join the network. This is intended to be used in multi-user production installations of TIES. If you are interested in evaluating TIES or anticipate a single user only, the TIES Virtual Machine might be better suited to your needs.

Getting Help

If you are having trouble getting through the installation, you can get help from the TIES team through two main avenues.

Purpose and Scope

This plan is intended to augment instructions found on the TIES TCRN website, embedded in the TIES TCRN Installer, and presented in the TIES Quality Assurance Plan.   This plan provides a high level starting point for the Providing Organization’s Administrator who is responsible for:

  • obtaining a license to join the TCRN network
  • installing the node
  • designating Organizational Founding Users
  • establishing rudimentary Quality Assurance Studies while acting as delegate to Founders

Team

Only the Administrator will exercise this plan. However, it is necessary that a Researcher, and Honest Broker be designated. Real user data must be entered into the system so that the basic functionality of data preparation and search can be tested in the initial rudimentary Quality Assurance process.

Role Responsibility Skills
Admin Responsible for obtaining a license, installing and performing rudimentary QA. The TIES Provider Admin must be able to create new Users and Studies, assign Users to Studies, and sanction requests from external studies to access local data and tissue. It is assumed the Admin will accomplish all the tasks in this Plan.   Nevertheless, it is important that a Researcher and Honest Broker be designated.
Researcher Individual designated as one of the first Primary Investigators at the Providing Organization. This Researcher will have typically authored the original license request and will have been integral in the business plan to join TCRN.
Honest Broker Individual designated as one of the first Honest Brokers at the Providing Organization. May be a Tissue Bank manager, or LIS Data Management Supervisor.

 

Process

Node initiation proceeds in a sequence of steps. The next step does not begin until the previous step is completed and accepted.

Step 1: Register and Obtain a TIES Node license

REQUEST LICENSE When approved you will receive an email with your license code.   You will need this license code when registering your node with the network after installation.   See Step 5 below.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Step 2: Prepare Registration and QA information

Prepare the user information profiles for your Organization, designating yourself as Admin as well as an initial Primary Investigator (Researcher) and an initial Honest Broker. You will need the following information.

Field Example
Organization Name Great Cancer Institute
Organization Abbreviated Name GCI
Organization Street Address Elm St
Organization City Buffalo
Organization State NY
Organization Zip 14263
Organization Country USA
Admin First Name John
Admin Last Name Doe
Admin User Name johnd
Admin Email johnd@gci.edu
Admin Phone 9999999999
Admin Fax 9999999999

The same set of fields entered for the Admin is needed later for Researcher and Honest Broker.   Now is a good time to gather and log this information.

Field Example
Researcher First Name Jack
Researcher Last Name Doe
Researcher User Name jackd
Researcher Email jackd@gci.edu
Researcher Phone 7168453051
Researcher Fax 999999999
Honest Broker First Name Jane
Honest Broker Last Name Doe
Honest Broker User Name janed
Honest Broker Email janed@gci.edu
Honest Broker Phone 9999999999
Honest Broker Fax 9999999999

Step 3: Prepare Hardware and Software

  • Obtain and set up the required hardware configuration for the TIES node server. See these suggested hardware configurations for some tips.
  • Set up a domain name for your server that can be used to access the TIES application server on Port 80 (e.g., tiesnode.<institution>.edu).
  • If you plan on sharing data with other institutions in the TCRN, you will have to make the server accessible from outside your institution’s firewall on port 80.
  • Make sure the latest version of Java 7 is installed on your TIES node server. (NOTE: The TIES pipeline uses the Gate library and will not run properly in Java 1.8)
  • Install MySQL 5.7.21 (Download Here) Server. Create a user with admin rights on all schemas beginning with ‘ties_‘. (save this username/password for connecting to database in later step)

Step 4: Run the installer

  1. Log into the TIES application server. You should run the installation from the server.
  2. Download the installer archive from http://ties.dbmi.pitt.edu/download. Unzip into a temporary folder and run the batch file included in the archive.LINUX USERS: If you want to use standard HTTP ports (80,90) for your node, you must install as ‘root’. installation welcome
  3. Specify installation folder. Preferably use folder names with no spaces and in 8.3 format. For example, E:\ties. You can leave the JMS Server URL field blank. installation folder
  4. Select the “Install a new node” option. install new node
  5. Specify the internal and external IP address or domain name of the server. The external IP address or domain name is used when accessing the server from outside the institution firewall. installer IP
  6. Use your existing MySQL installation, that was preinstalled in step 3. Entering in the URL, username, and password.                     
  7. Verify the installation parameters and click [Begin Installation].installation parameters

Step 5: Register with the Hub

Once the installation of the software is complete, you will be prompted to register your node with the TCRN central hub server. Fill in the form with accurate details. These must match your TCRN license key details for the registration to be accepted. LINUX USERS: At the end of successful registration, you will be notified that Tomcat Windows Services could not be installed. This is normal for Linux installations. You will have to set up Tomcat startup daemons yourself. installer registration

Step 6: Set up Tomcat Services to run under user account

Change the TIES tomcatPub and TIES tomcatPvt services that have been installed in your Windows Services panel to log on with the user account that was used to install the TIES system. LINUX USERS: You will have to setup Tomcat startup daemons yourself.

Step 7: Log in to your Organization via the Test Data Network

Even though you will be working exclusively on your Local Organization, your access will now be coordinated via the TCRN Hub server.   Access the TIES Client here. At installation time your Provider Node is automatically populated with a number of test reports.   Begin by searching for these.   Before searching, you need to establish a quality assurance study using your Admin privileges. login network login role

Step 8: Change your temporary password

In step 5 you may recall that a temporary password was granted.   All new Administrators are given the same temporary password, “TIESPassword”.   When logging in the first time you will be asked to change your temporary password to a high strength personal password. If you see an error during this step, please make sure you completed Step 6.

Step 9: Create New Users for Researcher and Honest Broker

Select the New User toolbar button. Fill in the information for your designated Researcher. Repeat the process for your designated Honest Broker. create user Take note of the username and auto-generated Password (here soar5cys). You will need to enter this information when acting as the Researcher and Honest Broker delegate.

Step 10: Create an Admin Level QA protocol.

Set it to a meaningful name since this study will be used into the future.   Use Data Only, Never Expires, Report Types Allowed equals Pathology. create study

Step 11: Add Researcher and Honest Broker to the Admin QA Protocol

Select the study you just created. select study Add the users you just created to the Study in their designated roles. add user

Step 12: Representing Researcher – Search for DeIdentified Reports

Still working in the test network, login as your Researcher using the temporary password.   Change the password, remembering it for later.   A good idea might be to consistently just add one letter to the original auto-generated password.   Click “Pathology” in the reports type search criteria and return.   The standard test corpus is 2500 documents all of which are Pathology.   The query payload should match this number.     Check a single document result to verify that most of the system is working. researcher search

Step 13: Representing Honest Broker – Search for Identified Reports

Still working in the test network, login as your HonestBroker using the temporary password.   Change the password, remembering it for later. You will need to be inside your Organizational Intranet to see reports.   But after issuing a query you should see reports that contain identified patient health information and contain no run message of the DeIdentifier.   Since this is test data the names of the patients will be fictitious (e.g., John and Jane Doe).

Step 14: Load and process your first batch of documents into Production

If all went well with your installation, you should have a series of background processes running that represent individual phases of the TIES ETL process (see Loading Your Data). Specifically, you will have a process for:

  • HL7Loader
  • DeIdentifier
  • Concept Coder
  • Indexer

These processes are designed to run automatically on system startup but may not be running right after the installation. You can start them from the Windows Services window on Windows installations. On Linux installations, services are not installed by default. They poll for a change of state, do their work, and then sleep for a predefined period.   Change of state usually indicates that there are documents ready to be worked upon. Configure Deidentifier Before you start processing your data, you may need to configure DeidPipeController. By default it is set up to use the DeID software. If you do not have DeID or do not have it installed in C:\Progra~1\DeID (typically when you have it installed in “Program Files (x86)” folder on newer Windows installations), you may need to change the configuration file. You have an option to use different De-identifiers with TIES. The DeidPipe configuration file is located here: <TIES_INSTALL>/Pipelines/DeidipeController/classes/config/caTIES.properties Load your first HL7 file We assume your AP LIMS can output Pathology Report data in HL7 format.   Separate a small but representative initial set of HL7 records into a separate file.   Then copy this file into the HL7Loader input directory. The default location for this directory is here in the installation footprint. HL7 directory It is set in <TIES_INSTALL>/Pipelines/HL7ImportPipeController/classes/config/caTIES.properties. Look for the attribute value pairs associated with the HL7ImportPipeController. caties.hl7importer.directory.home = C:/ties/HL7 caties.hl7importer.document.type = PATHOLOGY caties.hl7importer.sleepsize = 300000 caties.hl7importer.ethnicity.cfg = config/EthnicityConfig.txt caties.hl7importer.gender.cfg = config/GenderConfig.txt caties.hl7importer.race.cfg = config/RaceConfig.txt #Uncomment following line to tag all incoming reports with the specified tags. #Tags cannot contain spaces or colons in their name. #caties.hl7importer.tag = testtag Once the HL7Loader pipe is complete it will write the HL7 file into the processed directory.

Step 15: Test your Production Data by repeating steps 6 through 12 on the Production Network

A small HL7 document of around 2,500 reports should move through the process very quickly.   Wait fifteen minutes to a half hour and try to query the production network just as you previously did on the test.

Step 16: Mark password for Reset and forward account information to Researcher and Honest Broker

This is standard TIES procedure after you add a new user. The only difference here is that you have used these accounts to benchmark the installation process. This was necessary because TIES requires each study to have a Primary Investigator (Researcher) and an Honest Broker. We also discourage the use of fictitious user information polluting the production database. Thus the temporary delegation is one means to an end. Another solution might be to assign yourself as Administrator the additional roles of Researcher and Honest Broker and make two Studies to exercise the public and private data search and order set construction.   When the actual Researcher and Honest Broker log in for the first time, they will be asked to change their passwords.

Step 17: Optional Configuring DeIDCorp for Deidentification

If you have purchased a license to use the DeID Corporations DeIdentification software (http://www.de-id.com/), you should complete the following steps to get it configured correctly:

1. Install the deID software, this should be installed in the Windows directory \Program Files (x86)\DeID or \Program Files\DeID
2. Set (or change) the Windows PATH environment variable to use Windows 8 character naming convention for long filenames (i.e., dir /x). For example, if you installed the software in C:\Program Files (x86)\DeID set this to C:/PROGRA~2/DeID
a. This MUST be set in this way to allow the DeidPipeController to find the appropriate dynamic libraries


3. Go to the \ties\pipelines\DeidPipeController\classes\config directory and edit the caTIES.properties, peform the following
a. Make sure the caties.deid.classname points to the CaTIES_DeIDCorporationDeIdentifier
i. caties.deid.classname = edu.upmc.opi.caBIG.caTIES.server.deid.DeIDCorporation.CaTIES_DeIDCorporationDeIdentifier
b. Change the caties.deid.home to point to the location of the deID installed software
i. caties.deid.home = C:/PROGRA~2/DeID

4. Start the TIES DeidPipeController v5 service under Windows Services

Troubleshooting

If no reports are found, it is likely that the data transformation was clogged in one of the pipes.   To troubleshoot this situation there are a number of techniques and tools available.

What if my tomcat service can be reached from local computer but  inaccessible to the outside world?

Try adding tomcat.exe to the Windows firewall’s exception list. If it still does not work, you might need to contact the network people at your institution.

Are Pipe Processors installed and running?

First check to see if the pipeline processors are installed and running.   In Windows this can be accomplished via Control Panel -> All Control Panels -> Administrative Services -> Services. pipeline processors All TIES sevice names are prefixed with “TIES.”   They should be started by the user who installed TIES initially (the Administrator).

Did The HL7ImportPipeController process the initial HL7 file?

It should have been moved to the processed sub directory.

Have Document.ApplicationStatus and IdentifiedDocument.ApplicationStatus been set to IDLING?

The TIES acquisition phase is governed by a two MySQL relational databases.   Check the status of ties_private.IDENT_DOCUMENT and ties_public.DOCUMENT to see that all Documents are present and in APPLICATION_STATUS = IDLING.   You may use either the command line interface of MySQL, download the MySQL Workbench Visual Editor or use any available RDBMS tool like Squirrel. select application_status, count(*) from document group by application_status; State Transition for the ETL process should be as follows:

Pipeline State
HL7Loader “LOADING”
DeIdentifier “DEIDENTIFYING”
Coder “CODING”
Indexer “INDEXING”
Finished “IDLING”

If the application_status of some documents never make it to IDLING there is typically an error in the process. Use log files and TIES support staff to help solve the issue.

Are the Pipeline Log files clear of errors and indicative of successful runs?

Each Pipeline has two log files in <TIES INSTALL PATH>/pipelines/<PipeName>/logs/service.log and <TIES INSTALL PATH>/pipelines/<PipeName>/logs/wrapper.log Check these for diagnostics of a good run as well as any Java stack traces indicative of a failed run.

Does the Production Index contain files? The Indexer Pipeline builds a Lucene Index at the designated area.

This index should be a non empty directory of binary files.

Fixes

If it is determined that the production data transformation and load has failed you should:

  1. Examine start up account for the Windows Services
    • If you are unable to see the windows services running then, go to each tomcat\bin directories (tomcatPub and tomcatPvt) and run: service install <your service>    e.g., tomcatPub\bin\service install TIES-Public
  2. Examine the parameters in the caties.properties file in each pipeline footprint
  3. Forward error messages and captured stack traces to TIES Support Staff

 

Still having issues? See Troubleshooting for general troubleshooting help.