User Account Setup

This document describes the process for creating a new user account in Eureka!. In this document, $EUREKA_CONFIG refers to the Eureka! configuration directory for your platform (see Installation for details).

Create an Eureka! account

Create a data processing configuration file

The following configures Eureka! to read data from a spreadsheet. The file must be located in the $EUREKA_CONFIG/sourceconfig directory (create it if it does not exist). Inside the directory, create a file named what you want the configuration to be called in the user interface, for example, Spreadsheet, containing the following text. Replace $EUREKA_CONFIG with the configuration directory for your platform.

[edu.emory.cci.aiw.cvrg.eureka.etl.dsb.EurekaDataSourceBackend]
dataSourceBackendId=AIW
databaseName = spreadsheet
dataFileDirectoryName = spreadsheet
mimetypes = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
sampleUrl = ../docs/sample.xlsx
required = true

[org.protempa.backend.ksb.protege.LocalKnowledgeSourceBackend]
projectString = $EUREKA_CONFIG/ontologies/AIW.pprj
units = ABSOLUTE

[org.protempa.backend.asb.java.JavaAlgorithmBackend]

If you plan on using BioPortal as a knowledge source for Eureka!, the configuration file should also have the following configuration item included, before the LocalKnowledgeSourceBackend configuration (order is important):

[org.protempa.backend.ksb.bioportal.BioportalKnowledgeSourceBackend]
databaseAPI = DATASOURCE
databaseId = java:/comp/env/jdbc/BioPortalDS
ontologiesTable = bioportal

Enable processing configuration in Eureka!

The following configures the Eureka! database to allow access to a particular processing configuration from the user interface. Log into the database using the eurekabackend user, and the password chosen during installation. Issue the following SQL statement to enable the configuration in Eureka!. The USERNAME should be substituted with the username which should own the configuration. The FILENAME should be the processing file name created int he step above. Finally, the USER_ID is the id assigned to the user created in the first SQL statement below.

  insert into eurekabackend.users (id, username) values (user_seq.nextval, <USERNAME>);
  insert into eurekabackend.sourceconfigs (id, name, owner_id) values (sourceconfig_seq.nextval, "<FILENAME>", <USER_ID>);

Configure the Eureka! i2b2 loader

The following configures Eureka! to load data and metadata into your i2b2 installation. The configuration file must be located in the $EUREKA_CONFIG/destconfig directory. Inside the directory, create a file with the name of your choice containing the following XML. Replace the DB_HOST, DB_NAME, and PASSWORD placeholders with the appropriate values for your environment.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Configures the i2b2 query results handler. -->
<queryResultsHandler>
    <type>I2B2</type>
    <displayName>I2B2</displayName>
    <!-- A dictionary of properties for configuring the i2b2 query results
         handler.
    -->
    <dictionary>
        <!-- The name of the metadata table for this project as specified in
             the project's i2b2 project manager configuration. 
        -->
        <entry key="metaTableName"         value="cardiovascularregistry"/>
        <!-- The name of the root concept in the term browser. Must be the same
             as the concept name specified in the i2b2 project manager 
             configuration.
        -->
        <entry key="rootNodeName"          value="Cardiovascular Registry"/>
        <!-- Whether to truncate the data and metadata tables before loading.
             May be true or false.
        -->
        <entry key="truncateTables"        value="true"/>
        <!-- The proposition id representing a visit. -->
        <entry key="visitDimension" value="Encounter"/>
        <!-- The property of a visit proposition to use as an encounter id.
        -->
        <entry key="visitDimensionDecipheredId" value="visit_id"/>
        <!-- The dataType (see the data section below) specifying how to access
             a provider's full name.
        -->
        <entry key="providerFullName" value="providerFullName"/>
        <!-- The dataType (see the data section below) specifying how to access
             a provider's first name.
        -->
        <entry key="providerFirstName" value="providerFirstName"/>
        <!-- The dataType (see the data section below) specifying how to access
             a provider's middle name.
        -->
        <entry key="providerMiddleName" value="providerMiddleName"/>
        <!-- The dataType (see the data section below) specifying how to access
             a provider's last name.
        -->
        <entry key="providerLastName" value="providerLastName"/>
        <!-- The dataType (see the data section below) specifying how to access
             a patient's medical record number.
        -->
        <entry key="patientDimensionMRN" value="demographics_mrn"/>
        <!-- The dataType (see the data section below) specifying how to access
             a patient's gender.
        -->
        <entry key="patientDimensionGender" value="demographics_gender"/>
        <!-- The concept code prefix to use for representing patient ages.
        -->
        <entry key="ageConceptCodePrefix" value="DEM|AGE"/>
        <!-- The dataType (see the data section below) specifying how to access
             a patient's ethnicity.
        -->
        <entry key="patientDimensionEthnicity" value="demographics_ethnicity"/>
        <!-- The dataType (see the data section below) specifying how to access
             a patient's race.
        -->
        <entry key="patientDimensionRace" value="demographics_race"/>
        <!-- The dataType (see the data section below) specifying how to access
             a patient's marital status.
        -->
        <entry key="patientDimensionMaritalStatus" value="demographics_marital_status" />
        <!-- The dataType (see the data section below) specifying how to access
             a patient's language.
        -->
        <entry key="patientDimensionLanguage" value="demographics_lang" />
        <!-- The dataType (see the data section below) specifying how to access
             a patient's religion.
        -->
        <entry key="patientDimensionReligion" value="demographics_religion" />
        <!-- The dataType (see the data section below) specifying how to access
             a patient's date of birth.
        -->
        <entry key="patientDimensionBirthdate" value="demographics_dob" />
    </dictionary>

    <!-- JDBC database connection information for the data schema and the 
         metadata schema. Each of the two schema (dbschema) tags has the 
         following attributes:
            key = dataschema or metaschema.
            connect = a JDBC URL.
            user = database user name.
            passwd = database password.
    -->
    <database>
        <dbschema key="dataschema" connect="jdbc:oracle:thin:@DB_HOST:1521:DB_NAME" user="user_<USER_ID>_data" passwd="PASSWORD"/>
        <dbschema key="metaschema" connect="jdbc:oracle:thin:@DB_HOST:1521:DB_NAME" user="user_<USER_ID>_metadata" passwd="PASSWORD"/>
    </database>

    <!-- Specifies the data to load into the observation_fact table. Different
         kinds of data are specified each in a dataType tag with the following 
         attributes:
            key = an unique name for this data type.
            reference = the name of a reference from the proposition definition
                specified above in the visitDimension dictionary entry. The
                data referred-to by the reference will be loaded.
            property = the value set of the specified property will be loaded
                as facts (optional).
            start = for value set elements, specifies whether to use the start 
                or the finish of the proposition as its timestamp. Allowed
                values are "start" and "finish".
            conceptCodePrefix = specifies a concept code prefix for all facts
                specified by this data type entry (optional).
    -->
    <data>
        <!-- Specifies that propositions referred-to by a visit proposition's
             diagnosisCodes reference should be loaded.
        -->
        <dataType key="diagnoses" reference="diagnosisCodes"/>
        <dataType key="meds" reference="medicationHistory"/>
        <dataType key="labs" reference="labs" units="unitOfMeasure" />
        <dataType key="procedures" reference="procedures"/>
        <dataType key="vital" reference="vitals"/>
        <!-- Specifies that the value of every visit proposition's 
             dischargeDisposition property should be loaded.
        -->
        <dataType key="dschgDisp" property="dischargeDisposition" start="finish" />
        <dataType key="providerFullName" reference="provider" property="fullName" />
        <dataType key="providerFirstName" reference="provider" property="firstName" />
        <dataType key="providerMiddleName" reference="provider" property="middleName" />
        <dataType key="providerLastName" reference="provider" property="lastName" />
        <!-- Specifies that the value of the gender property of all 
             propositions referred-to by every visit proposition's 
             patientDetails reference should be loaded. Those facts should use 
             the corresponding visit proposition's start time as their 
             timestamp, and their concept codes will be created as 
             'DEM|SEX:<value>'.
        -->
        <dataType key="demographics_gender" reference="patientDetails" property="gender" start="start" conceptCodePrefix='DEM|SEX'/>
        <dataType key="demographics_ethnicity" reference="patientDetails" property="ethnicity"  start="start"/>
        <dataType key="demographics_race" reference="patientDetails" property="race" conceptCodePrefix="DEM|RACE" start="start"/>
        <dataType key="demographics_marital_status" reference="patientDetails" property="maritalStatus" conceptCodePrefix="DEM|MARITAL" start="start"/>
        <dataType key="demographics_lang" reference="patientDetails" property="language" conceptCodePrefix="DEM|LANGUAGE" start="start" />
        <dataType key="demographics_religion" reference="patientDetails" property="religion" start="start"/>
        <dataType key="demographics_mrn" reference="patientDetails" property="patientId"/>
        <dataType key="demographics_dob" reference="patientDetails" property="dateOfBirth"/>
        <dataType key="visit_id" property="encounterId"/>
    </data>

    <!-- Specifies the folders to display in the i2b2 term browser.

         Attributes:
            displayName = what shows up in the UI
            skipGen = skips n levels of the inverseIsA hierarchy in the AIW
                ontology.
            proposition = the id of the proposition definition representing a 
                subtree of the AIW ontology to display (unless the property 
                attribute is specified, see below).
            property = the name of a property of the proposition definition
                specified above. Causes the property's value set to be 
                displayed in the folder.
            valueType = LABORATORY_TESTS or TEXT, if the concepts in the
                folder represent either kind of data.

         Note: The folder order matters! I2b2 does not permit a concept
         to have multiple parents, but the AIW ontologies do have propositions
         with multiple parents. We work around this the following way: for 
         concepts that are a parent of a child with another parent specified in 
         an earlier folder, we make the concept appear in that folder as a 
         leaf. To use this to best effect, we recommend that standard code 
         hierarchies be listed first and that those hierarchies not implement 
         multiple inheritance or refer to each other's concepts in any way 
         (what you should normally do with i2b2). Subsequently, list folders 
         for your custom concepts, which may include parents of concepts from
         the standard code hierarchies or from an earlier custom concept 
         folder. For custom concepts that are a parent of a concept in an
         earlier folder, such variables will appear as leaves in the browser.
    -->
    <concepts>
        <!-- Creates a folder in the term browser named "CPT Codes". Its
             contents will be the "CPTCode" subtree of the AIW ontology, 
             starting at the second level of the subtree.
        -->
        <folder displayName="CPT Codes"             skipGen="1" proposition="CPTCode"/>
        <folder displayName="ICD9 Diagnostic Codes" skipGen="1" proposition="ICD9:Diagnoses"/>
        <folder displayName="ICD9 Procedure Codes"  skipGen="1" proposition="ICD9:Procedures"/>
        <folder displayName="Laboratory Tests"      skipGen="1" proposition="LAB:LabTest" valueType="LABORATORY_TESTS" />
        <!-- Creates a folder in the term browser named 
             "Discharge Disposition". Its contents will be the allowed values
             of the dischargeDisposition property of the ENcounter proposition
             definition.
        -->
        <folder displayName="Discharge Disposition" skipGen="1" proposition="Encounter" property="dischargeDisposition"/>
        <folder displayName="Medication"            skipGen="3" proposition="MED:medications"/>
        <folder displayName="Vital Signs"           skipGen="1" proposition="VitalSign"/>
        <folder displayName="Hospital Readmissions" skipGen="0" proposition="READMISSIONS:EncounterWithSubsequent30DayReadmission"/>
        <folder displayName="Hospital Readmissions" skipGen="0" proposition="READMISSIONS:SecondReadmit"/>
        <folder displayName="Hospital Readmissions" skipGen="0" proposition="READMISSIONS:FrequentFlierEncounter"/>
        <folder displayName="Hospital Readmissions" skipGen="0" proposition="READMISSIONS:Chemotherapy180DaysBeforeSurgery"/>
        <folder displayName="Hospital Readmissions" skipGen="0" proposition="READMISSIONS:Chemotherapy365DaysBeforeSurgery"/>
        <folder displayName="Hospital Readmissions" skipGen="0" proposition="READMISSIONS:Encounter90DaysEarlier"/>
        <folder displayName="Hospital Readmissions" skipGen="0" proposition="READMISSIONS:Encounter180DaysEarlier"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="DISEASEINDICATOR:MyocardialInfarction"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="READMISSIONS:SecondMI"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="DISEASEINDICATOR:UncontrolledDiabetes"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="DISEASEINDICATOR:EndStageRenalDisease"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="DISEASEINDICATOR:Obesity"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="ERATCancer"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="ERATCKD"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="ERATCOPD"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="ERATDiabetes"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="ERATHF"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="ERATHxTransplant"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="ERATPulmHyp"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="ERATStroke"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="DISEASEINDICATOR:MethicillinResistantStaphAureusEvent"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="DISEASEINDICATOR:SickleCellAnemiaEvent"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="DISEASEINDICATOR:SickleCellCrisisEvent"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="DISEASEINDICATOR:ThrombocytopeniaEvent"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="DISEASEINDICATOR:MetastasisEvent"/>
        <folder displayName="Comorbidities" skipGen="0" proposition="DISEASEINDICATOR:HypertensionEvent"/>
    </concepts>
</queryResultsHandler>

Enable i2b2 loader in Eureka!

The following will enable the i2b2 loader configuration for users in Eureka!, and enable its display in the user interface. Connect to the database using the eurekabackend user, and issue the following SQL statements. Substitute USER_ID with the id of the user inserted in the previous step where the processing configuration is enabled. The FILENAME should be the name of the file created in the previous step.

   insert into eurekabackend.destinations (id, name, owner_id) values (dest_seq.nextval, <FILENAME>, <USER_ID>);

Setup i2b2 account and project

Each user is associated with their own project. Thus, we need to create a project, a user, and assign the user to the project.

Create the corresponding i2b2 user

To create a new user in i2b2, use the administration interface located at https://your.company.com/i2b2/admin. Please replace your.company.com with the appropriate IP address or hostname of your EC2 instance.

The user name should be the same as the email field in the Eureka! user set up. For example, super.user@exmaple.com as previously used in this guide. As more users are added to the Eureka! database, the same users need to be added to i2b2. The email attribute in Eureka! will be the same as the username attribute for i2b2 user. The passwords will also be the same for both systems, because Eureka! utilizes the same hashing mechanism for storing passwords that i2b2 uses.

Create a new project in i2b2

To create a new project in i2b2, use the administration interface at https://your.company.com/i2b2/admin. Please replace your.company.com with the appropriate IP address or hostname of your EC2 instance.

The default username and password for the administrative user are i2b2 and demouser, respectively. The project should be named EurekaProject<USER_ID>, and the path set to /EurekaProject<USER_ID>.

Once the project has been created, use the adminstration interface to add the user to the database. All permissions, except for admin and editor should be set for the user.

Create data sources for the project

Configure the necessary datasources to allow i2b2 to store and retrieve information about a project’s data, metadata, and work data. This information is configured in the $JBOSS_HOME/default/server/default/deploy/eureka-project-<USER_ID>-ds.xml file. In the Amazon EC2 instance of Eureka!, $JBOSS_HOME is /opt/jboss. Replace the DB_HOST and DB_NAME placeholders with values appropriate for your environment. The PASSWORD placeholders should be replaced with the passwords chosen for the user_<USER_ID>_data, user_<USER_ID>_metadata, and user_<USER_ID>_workdata users earlier in the set up process. Also notice the jndi-name attributes of the datasources. The JNDI names are used later when updating information in the i2b2 PM schema to properly use the new datasources. The datasources are used for one specific project, which is assigned to one user. As a result, each i2b2 user will have a set of data, metadata, and workdata schemas associated.

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<!-- The data datasource -->
<local-tx-datasource>
<jndi-name>EurekaProject<USER_ID>DataDS</jndi-name>
<driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
<connection-url>jdbc:oracle:thin:@DB_HOST:1521:DB_NAME</connection-url>
<user-name>user_<USER_ID>_data</user-name>
<password>PASSWORD</password>
<idle-timeout-minutes>1</idle-timeout-minutes>
<exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter</exception-sorter-class-name>
<metadata>
<type-mapping>Oracle9i</type-mapping>
</metadata>
</local-tx-datasource>
<!-- The metadata datasource -->
<local-tx-datasource>
<jndi-name>EurekaProject<USER_ID>MetadataDS</jndi-name>
<driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
<connection-url>jdbc:oracle:thin:@DB_HOST:1521:DB_NAME</connection-url>
<user-name>user_<USER_ID>_metadata</user-name>
<password>PASSWORD</password>
</local-tx-datasource>
<!-- The workdata datasource -->
<local-tx-datasource>
<jndi-name>EurekaProject<USER_ID>WorkDS</jndi-name>
<driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
<connection-url>jdbc:oracle:thin:@DB_HOST:1521:DB_NAME</connection-url>
<user-name>user_<USER_ID>_workdata</user-name>
<password>PASSWORD</password>
</local-tx-datasource>
</datasources>

Configure i2b2 to use the new data sources

After the user and project have been created, the i2b2 database should be updated in order to allow i2b2 to locate the datasources previously created. The following SQL code will add the correct entries in the database to ensure that the newly created project uses the datasources created earlier. This will ensure that the data is retrieved and stored in the correct database schemas.

insert into i2b2hive.crc_db_lookup(
c_domain_id, c_project_path, c_owner_id, c_db_fullschema,
c_db_datasource, c_db_servertype, c_db_nicename, c_db_tooltip,
c_comment, c_entry_date, c_change_date, c_status_cd)
values(
'i2b2demo', '/EurekaProject<USER_ID>/', '@', 'user_<USER_ID>_data',
'java:EurekaProject<USER_ID>DataDS', 'ORACLE', 'EurekaProject<USER_ID>DataDS',
null, null, null, null, null);
insert into i2b2hive.ont_db_lookup(
c_domain_id, c_project_path, c_owner_id, c_db_fullschema,
c_db_datasource, c_db_servertype, c_db_nicename, c_db_tooltip,
c_comment, c_entry_date, c_change_date, c_status_cd)
values(
'i2b2demo', 'EurekaProject<USER_ID>/', '@', 'user_<USER_ID>_metadata',
'java:EurekaProject<USER_ID>MetadataDS', 'ORACLE',
'EurekaProject<USER_ID>MetadataDS', null, null, null, null, null);
insert into i2b2hive.work_db_lookup(
c_domain_id,
c_project_path, c_owner_id, c_db_fullschema, c_db_datasource,
c_db_servertype, c_db_nicename, c_db_tooltip, c_comment,
c_entry_date, c_change_date, c_status_cd)
values (
'i2b2demo', 'EurekaProject<USER_ID>/', '@', 'user_<USER_ID>_workdata',
'java:EurekaProject<USER_ID>WorkDS', 'ORACLE',
'EurekaProject<USER_ID>WorkDS', null, null, null, null, null);

Create an i2b2 metadata table for the project

The Eureka! i2b2 loader process will store the metadata for a project in a table called cardiovascularregistry. In order to allow the loader process to store this data, the table must be created before running Eureka!. The following SQL creates the table.

create table user_<USER_ID>_metadata.cardiovascularregistry (
c_hlevel decimal(22) not null,
c_fullname varchar2(700) not null,
c_name varchar2(2000) not null,
c_synonym_cd char(1) not null,
c_visualattributes char(3) not null,
c_totalnum decimal(22),
c_basecode varchar2(50),
c_metadataxml clob,
c_facttablecolumn varchar2(50) not null,
c_tablename varchar2(50) not null,
c_columnname varchar2(50) not null,
c_columndatatype varchar2(50) not null,
c_operator varchar2(10) not null,
c_dimcode varchar2(700) not null,
c_comment clob,
c_tooltip varchar2(900),
update_date timestamp not null,
download_date timestamp,
import_date timestamp,
sourcesystem_cd varchar2(50),
valuetype_cd varchar2(50));

Create i2b2 metadata table pointers for the project

The table_access table in the i2b2 metadata schema controls which tables are used when creating the metadata concept navigation tree in the user interface. The following SQL code will update the database to use the new table for metadata in the previous step.

delete from user_<USER_ID>_metadata.table_access;
insert into user_<USER_ID>_metadata.table_access (
c_table_cd, c_table_name, c_protected_access, c_hlevel,
c_fullname, c_name, c_synonym_cd, c_visualattributes,
c_totalnum, c_basecode, c_metadataxml, c_facttablecolumn,
c_dimtablename, c_columnname, c_columndatatype, c_operator,
c_dimcode, c_comment, c_tooltip, c_entry_date,
c_change_date, c_status_cd, valuetype_cd)
values (
'cardiovascularregistry', 'CardiovascularRegistry', 'N', 0,
'\CardiovascularRegistry\', 'CardiovascularRegistry', 'N',
'CA ', null, null, '<Clob>', 'concept_cd',
'concept_dimension', 'concept_path', 'T', 'LIKE',
'\CardiovascularRegistry\', '<Clob>',
'CardiovascularRegistry', null, null, null, null);

Activate the account

Finally, in the Administrator screen of Eureka!, activate the account by clicking on the Activate checkbox for the account.