Reference

The SHRINE Webclient uses a JSON formatted file for client side settings for help file locations, help urls and obfuscation settings, this document will focus on obfuscation. The configuration file is located at the root html directory and will look something like the image below:





Supported Data Types


Basic: Booleans, and Strings, and Integers

For example:

isQueryable = true

setSizeObfuscation = false

shrineDatabaseType = "mysql"

adapterLockoutAttemptsThreshold = 42


Durations

Durations in older parts of the code are specified as a block containing a single numeric property with a name of either milliseconds, seconds, minutes, hours, or days.  For example :

maxSignatureAge { days = 5 }

maxQueryWaitTime { minutes = 0.5 }

In 1.23 we will convert all of these blocks to a format that matches Typesafe Config and Scala Durations

maxSignatureAge = "5 days"

maxQueryWaitTime = "30 seconds"

 

Endpoints

Endpoints are URLs with parameters, specified as blocks with the following properties:

For example:

crcEndpoint { url = "http://example.com/i2b2" }

crcEndpoint {
  url = "http://example.com/i2b2"
  acceptAllCerts = true
  timeout { minutes = 1 }
}

 

Credentials

Credentials are specified as blocks with the following properties:

For example:

sheriffCredentials {
  username = "sheriffUsername"
  password = "sheriffPassword"
}

fooCredentials {
  domain = "shrine"
  username = "foo"
  password = "bar"
}

 

i2b2 Hive Credentials

i2b2 hive credentials for use with a CRC or other i2b2 cell are specified as blocks with the following properties:

For example:

hiveCredentials {
  domain = "HarvardDemo"
  username = "demo"
  password = "demouser"
  crcProjectId = "Demo"
  ontProjectId = "SHRINE"
}

 

Keystore Parameters

Keystore parameters are expressed using a block with the following properties:

For example:

keystore {
  file = "shrine.keystore"
  password = "changethisplease"
  privateKeyAlias = "test-cert"
  keyStoreType = "PKCS12"
  caCertAliases = [shrine-ca, some-other-ca]
}

 

SHRINE Proxy

The SHRINE proxy is configured by a block with a single property, timeout, a duration.  Timeout specifies the amount of time the proxy should wait for a response from the url being proxied.  The default is to wait forever.

For example:

proxy {
  timeout {
    minutes = 5
  }
}

 

Shrine.conf Example

An example shrine.conf can be found here:

https://open.med.harvard.edu/stash/projects/SHRINE/repos/shrine/browse/commons/config/src/test/resources/shrine.conf

 

Shrine.conf Property Reference

 

Adapter Config

If a node is an adapter, add an adapter block to shrine.conf:

adapter {
  create = true 
  ...
}
Adapter Config Property Reference

For example:

 adapter {
    crcEndpoint {
      url = "http://services.i2b2.org/i2b2/rest/QueryToolService/"
      acceptAllCerts = true
      timeout {
        seconds = 1
      }
    }
    
    setSizeObfuscation = true
    
    adapterLockoutAttemptsThreshold = 10

    adapterMappingsFileName = "AdapterMappings.xml"
    
    maxSignatureAge {
      minutes = 5
    }
  }

 

Hub (Broadcaster) Config

If a node is a hub (broadcaster), add a hub block to shrine.conf:

hub {
  create = true
  ...
}
Hub Config Property Reference

For example:

 hub {
    create = true
    maxQueryWaitTime {
      minutes = 4.5
    }
    
    downstreamNodes {
      "some hospital" = "http://example.com/foo"
      CHB = "http://example.com/chb"
      PHS = "http://example.com/phs"
    }
    
    shouldQuerySelf = true
  }

 

Query Entry Point Config

If a node is an entry point—a node that can receive queries from a web UI and perform them on the network—add a queryEntryPoint block to shrine.conf:

queryEntryPoint {
  create = true
  ...
}
Query Entry Point Config Reference
Authentication types

Note: the "ecommons" and "pm" authentication schemes will use the i2b2 PM described by the shrine.pmEndpoint property.

Authorization types

Note: the "hms-steward" authorization type is compatible ONLY with the "ecommons" authentication type.

For example:

 queryEntryPoint {

   authenticationType = "pm"

   authorizationType = "shrine-steward"

// BEGIN properties for hms-steward
//   sheriffEndpoint {
//      url = "http://localhost:8080/shrine-hms-authorization/queryAuthorization"
//      acceptAllCerts = true
//      timeout {
//        seconds = 1
//      }
//    }
//    
//    sheriffCredentials {
//      username = "sheriffUsername"
//      password = "sheriffPassword"
//    }
// END properties for hms-steward
 
// BEGIN properties for shrine-steward
      shrineSteward {
        qepUserName = "qep" // name of user the steward will submit queries as
        qepPassword = "trustme"
        stewardBaseUrl = "https://localhost:6443" // typically hostname+port of Tomcat server running steward.war
      }
// END properties for shrine-steward
    
    includeAggregateResults = false
    
    maxQueryWaitTime {
      minutes = 5
    }
    
    broadcasterServiceEndpoint {
      url = "http://example.com/shrine/rest/broadcaster/broadcast"
      acceptAllCerts = true
      timeout {
        seconds = 1
      }
    }
    
    attachSigningCert = true
 }

Breakdown Result Output Types Config

As of Shrine 1.18.0+, it is required to specify the names of result types corresponding to breakdown queries.  There names must match the names of result output types defined in the i2b2 DB of every node on your Shrine network.  For example, on a network comprised of nodes backed by i2b2 demo VMs, add this to shrine.conf:

 

shrine {
  ...
 
  breakdownResultOutputTypes {
    PATIENT_AGE_COUNT_XML {
      description = "Age patient breakdown"
    }
      
    PATIENT_RACE_COUNT_XML {
      description = "Race patient breakdown"
    }
 
    PATIENT_VITALSTATUS_COUNT_XML {
      description = "Vital Status patient breakdown"
    }
 
    PATIENT_GENDER_COUNT_XML {
      description = "Gender patient breakdown"
    }
  }
 
  ...
}

 

the format is

breakdownResultOutputTypes {
  <breakdown-result-output-type-name 0> {
    description = <string human-readable-description 0>
  }
  ...
  <breakdown-result-output-type-name N> {
      description = <string human-readable-description N>
  }
}

 

note that shrine.breakdownResultOutputTypes can contain 0 or more child elements.

 

Since this breakdown result output type information will be shared by many nodes on a network, it's also possible to define it in its own file, breakdowns.conf, which can be shared among sites without revealing URLs or credentials.  That file should contain only the enclosing shrine { ... } block and the breakdownResultOutputTypes {... } block, like

shrine {
  breakdownResultOutputTypes {
    PATIENT_AGE_COUNT_XML {
      description = "Age patient breakdown"
    }
      
    PATIENT_RACE_COUNT_XML {
      description = "Race patient breakdown"
    }
 
    PATIENT_VITALSTATUS_COUNT_XML {
      description = "Vital Status patient breakdown"
    }
 
    PATIENT_GENDER_COUNT_XML {
      description = "Gender patient breakdown"
    }
  }
}

If breakdowns.conf is present and no shrine.breakdownResultOutputTypes block is defined in shrine.conf, values from breakdowns.conf will be used.