Page History
Depending on your site's current status, not all of these steps will be necessary to follow. For example, you may skip the first major i2b2 section of these instructions if i2b2 1.7.05 is already installed. However, all users should read through and follow the SHRINE 1.19.2 section of the instructions.
The end result , however, is that you will need all of these pieces of software (i2b2, SHRINE, SHRINE Data Steward) installed and upgraded to their indicated version.
...
These instructions are based on the instructions in the general Upgrading SHRINE to 1.22.8 (from 1.20-1.21) article. You will need to follow all the instructions provided in order to upgrade to SHRINE 1.19.2 and to properly configure the new SHRINE Data Steward. If you have previously installed SHRINE 1.19.1, you will need to follow these instructions. If you have not yet installed the SHRINE Data Steward, you will need to follow these instructions.
...
The SHRINE Data Steward is typically backed by the i2b2 PM cell used by SHRINE. From the steward application's point of view, all users on the SHRINE project are considered Researchers . However(except for the Steward and QEP users!). However, there is some additional work that has to be done to the i2b2 user list to accommodate the SHRINE Data Steward.
...
The Steward application requires set of user credentials that it the application will use to submit queries through to SHRINE. It is recommended that this be a dedicated system user separate from any other account. Additionally, it will need to have the parameter "qep" defined (name: qep, value: true, type: text), which can be set in the Manage Users section of the i2b2 Admin Panel. Make sure to add this user to the SHRINE project in the i2b2 Admin Panel as well.
...
In Steward application deployments that involve topic approval, a trusted human user will have to be given permission to review proposed research topics and approve/reject them. To mark a user as such, add the "DataSteward" parameter (name: DataSteward, value: true, type: text) to that user in the Manage Users section of the i2b2 Admin Panel. Make sure to add this user to the SHRINE project in the i2b2 Admin Panel as well.
Database - Steward
The SHRINE Data Steward application uses a separate database to store its logging information, similar to how the core SHRINE application keeps its own query log.
This step should be handled by install-steward-only.sh, but instructions to manually perform it can be found below:
Note that this user is meant solely to monitor and review, and thus cannot create its own query topics! If you are both a steward and a researcher, you will need to create two separate i2b2 users.
All Other Users (Researchers)
NOTE: The current SHRINE Data Steward webclient transforms usernames to all-lowercase! As such, any i2b2 usernames that use both uppercase and lowercase letters will not be able to use the SHRINE Data Steward properly. Please make sure any users that intend to use SHRINE have a username with all lowercase letters. We apologize for any inconvenience this may cause.
Database - Steward
The SHRINE Data Steward application uses a separate database to store its logging information, similar to how the core SHRINE application keeps its own query log.
This step should be handled by install-steward-only.sh, but instructions to manually perform it can be found below:
- Create a database (typically stored in MySQL alongside the existing shrine_query_history database, but this is just a suggestion). The installer by default calls it stewardDB.
- Grant a shrine/steward-specific user full access to this database. The installer by default uses the same credentials as it does for the SHRINE query history database, but you are welcome to (and encouraged to!) change this.
- Run the appropriate schema script included with the steward application
- For MySQL, this is https://open.med.harvard.edu/svn/shrine/releases/1.19.2/code/steward/src/main/sql/mysql.ddl
- For SQL
- Create a database (typically stored in MySQL alongside the existing shrine_query_history database, but this is just a suggestion). The installer by default calls it stewardDB.
- Grant a shrine/steward-specific user full access to this database. The installer by default uses the same credentials as it does for the SHRINE query history database, but you are welcome to (and encouraged to!) change this.
- Run the appropriate schema script included with the steward application
...
In webapps/shrine-webclient/js-i2b2/cells/SHRINE/cell_config_data.js, make sure newTopicURL is and readApprovedURL are set to something like the following:
newTopicURL: "https://your.hostname.here:6443/steward/client/index.html#/topics"
Make the following change in webapps/shrine-webclient/i2b2_config_data.js:
isSHRINE: trueThe above may already be present in i2b2_config_data.js, but commented out. (there may be a /* on the previous line) If so, uncomment it. If isSHRINE is not already present, add it to the main entry in lstDomains.
shrine.conf Changes
SHRINE Data Steward Integration
In order to make SHRINE aware of the steward, you will need to change the authorizationType value and add the following shrineSteward block to the queryEntryPoint block of shrine.conf:
queryEntryPoint {
... authorizationType = "shrine-steward"
shrineSteward {
qepUserName = "qep" // name of user the steward will submit queries as
qepPassword = "qep-password"
stewardBaseUrl = "https://your.hostname.here:6443" // typically hostname+port of Tomcat server running steward.war
}
...
}The qepUserName and qepPassword properties should match the set of credentials used for the QEP user defined earlier.
Lockout Threshold for ACT
In the adapter block of shrine.conf, change adapterLockoutAttemptsThreshold to 3:
adapter {
...
adapterLockoutAttemptsThreshold = 3
...
}
Start SHRINE
, /* this URL should be accessible from the client */
readApprovedURL:"https://your.hostname.here:6443/shrine/rest/i2b2/request" /* this URL should be accessible from the SHRINE server */
Make the following change in webapps/shrine-webclient/i2b2_config_data.js:
isSHRINE: trueThe above may already be present in i2b2_config_data.js, but commented out. (there may be a /* on the previous line, as well as a */ or // on the "isSHRINE" line) If so, uncomment it. If isSHRINE is not already present, add it to the main entry in lstDomains.
shrine.conf Changes
SHRINE Data Steward Integration
In order to make SHRINE aware of the steward, you will need to change the authorizationType value and add the following shrineSteward block to the queryEntryPoint block of shrine.conf:
queryEntryPoint {
... authorizationType = "shrine-steward"
shrineSteward {
qepUserName = "qep" // name of user the steward will submit queries as
qepPassword = "qep-password"
stewardBaseUrl = "https://your.hostname.here:6443" // typically hostname+port of Tomcat server running steward.war
}
...
}The qepUserName and qepPassword properties should match the set of credentials used for the QEP user defined earlier.
Lockout Threshold for ACT
In the adapter block of shrine.conf, change adapterLockoutAttemptsThreshold to 3:
adapter {
...
adapterLockoutAttemptsThreshold = 3
...
}
Start SHRINE
The only thing left The only thing left to do at this point is start SHRINE back up. Simply do the following:
...
<versionInfo>
<shrineVersion>1.19.2</shrineVersion>
<ontologyVersion>UNKNOWN</ontologyVersion>
<adapterMappingsVersion>Unknown</adapterMappingsVersion>
<scmRevision>(not available)</scmRevision>
<scmBranch>UNKNOWN_BRANCH</scmBranch>
<buildDate>2015-06-30 18:03:57</buildDate>
</versionInfo>
Creating a Query Topic
Upon logging in to the SHRINE webclient for the first time after installation of the SHRINE Data Steward, the user should see a new dropdown list and button at the bottom of the query construction panel. This is where a user sets which query topic will be associated with their query when it enters the SHRINE system. If no topic is selected, then query execution will fail.
Initially, a user will not have any approved query topics, so they must first click on the "Request New Topic" button, which will take them to the SHRINE Data Steward webclient. Log in using the same set of credentials used to log in to the SHRINE webclient, and request a new topic from there. On this network, all query topics are automatically approved. After creating a query topic, log out and back in to the SHRINE webclient, and the recently-created topic should be available in the dropdown list at the bottom of the query construction panel.
SHRINE operation continues as normal from this point onward.
Verify SHRINE Data Steward Query Logging
After creating a query topic and logging back in to the SHRINE webclient, try selecting a topic and executing a query. The query should come back with a list of sites and patient counts (or issues) as usual. After this, verify that the SHRINE Data Steward is also logging these queries.
Check the SHRINE Data Steward client (either click on Request New Topic or go to https://your.host.here:6443/steward/client/), log in with the user you ran the query as, and then check the Query History section of the client. If you need help navigating the application, check the Help file in the upper right (also available at https://your.host.here:6443/steward/client/src/assets/img/SHRINE-Data-Steward-Help.pdf)
The recently-executed query should show up in that list, with the same query name that was entered in the SHRINE webclient. If it does not show up, verify that your configuration settings for both the SHRINE Data Steward as well as SHRINE itself match the values suggested in this documentation.
Overview
Content Tools