Configuration Properties Reference

This document explains how to configure Study Tracker using Spring Boot-compatible .properties files.

Study Tracker users .properties files to configure the application and its integrations. The simplest way to configure your instance is to use the application.properties.example file in the source code repository as a starting point for your own application.properties file. A description of all of the available configuration properties can be found below, but Spring Boot provides a large number of other properties for customizing various aspects of your application, though it is not recommended you modify any you don't see here, unless you know what you are doing.

General Properties

Application Server

Property	Default	Description
application.host-name	localhost	Required. Used when generating absolute URLs, such as in emails. This value should be the host name only, and not include the HTTP protocol or port number. Eg. www.myapp.com
application.secret	n/a	Required. An ideally random string of 16 or more characters that will be used for seeding encryption of sensitive database records. This value should not be changed after initialization.
server.port	8080	Sets the port the application will run on. It is recommended to run the application on port 443 with SSL enabled in a production environment.

Admin User

When Study Tracker starts for the first time, an admin account is needed to be able to sign-in and start configuring the tenant. These properties are used to define that user account, but additional admins can be added after-the-fact.

Property	Default	Description
admin.email	n/a	Required. Email address to associate with the admin account.
admin.password	n/a	Required. Initial password for the admin account. This should be changed after first use.

Data Source

Study Tracker requires a connection to a PostgreSQL database. You must provide host information and user credentials for connecting to the server.

Property	Default	Description
db.username	studytracker	Database username
db.password	studytracker	Database password
db.host	localhost	Host name for your database
db.name	study-tracker	Database or schema name
db.port	5432	Database host connection port

Email

Property	Default	Description
email.host	n/a	Mail server host.
email.port	n/a	Mail server port.
email.username	n/a	User for logging into mail server.
email.password	n/a	Password for mail server.
email.smtp-auth	n/a	Set to true if mail server requires authentication.
email.smtp-start-tls	n/a	Set to true to enables TLS for SMTP connection. Recommended.
email.outgoing-email-address	Value of spring.mail.username	Email address to use as sender address in all outgoing emails.
email.protocol	smtp	Email protocol to use for sending mail.

Security and Authentication

Configures security and authentication integrations. For more details, see the section on Okta.

Property	Default	Description
sso.mode	none	Sets the single sign-on method to be used. By default, no SSO is used. Options are none and okta-saml

SSL

Set these parameters when optionally running the application with SSL enabled. For more details, see the Security page.

Property	Default	Description
server.ssl.enabled	false	Set to true to enable SSL.
server.ssl.key-store-type	n/a	Set the keystore type to use to store certificates. This should be set to PKCS12.
server.ssl.key-alias	n/a	Alias of the keystore you created.
server.ssl.key-store	n/a	File name of the keystore.
server.ssl.key-store-password	n/a	Password given when creating the keystore.

Electronic Laboratory Notebook

Configures integration with ELN services. For more information, see the section for Benchling.

Property	Default	Description
notebook.mode	none	Deprecated. Sets the notebook software to be used, if needed. Options are none and benchling.

File Storage

Property	Default	Description
storage.mode	local	Deprecated. Sets the file system or cloud storage service to be used for storing study files. Options are local and egnyte.
storage.use-existing	false	Program, assay, or study folders which already exist will be re-used if a new record with the same name is created. If set to false, an exception will be thrown when trying to create a folder that already exists. Should only be set to true for development or staging applications.
storage.temp-dir	/tmp	Directory used by the application for storing temp files. This is primarily used as a landing area for uploaded files.
storage.local-dir	/tmp	When storage.mode is set to local, this property will specify the directory on the local filesystem to be used as the root folder for storing study files.

Study Metadata

Property	Default	Description
study.default-code-prefix	ST	Default prefix for generating study codes, if one is not provided by the associated program.
study.default-external-code-prefix	EX	Default prefix for generating study codes, if one is not provided by the associated external collaborator.
study.study-code-counter-start	10001	Sets the starting value of the study code counter. For example, the first study with program code ST would have a code of ST-10001 by default.
study.external-code-counter-start	1	Sets the starting value of the study code counter. For example, the first study with collaborator code CRO would have an external code of CRO-00001 by default.
study.assay-code-counter-start	1	Sets the starting value of the assay code counter. For example, the first assay for study ST-10001 would have a code of ST-10001-001 by default.
study.study-code-min-digits	5	Sets the zero-padding length for the study code. A study counter value of 1 for program ST would get padded to ST-00001 by default.
study.external-code-min-digits	5	Sets the zero-padding length for the external study code. A study counter value of 1 for collaborator CRO would get padded to CRO-00001 by default.
study.assay-code-min-digits	3	Sets the zero-padding length for the assay code. A assay counter value of 1 for study ST-10001 would get padded to ST-10001-001 by default.

Events

Study Tracker keeps track of various study lifecycle events, which are triggered by users interacting with the system. This activity is stored within the main Study Tracker database, but is also sent externally using event dispatchers. Event listeners can be configured to trigger secondary actions and events in a way that allow customization or integrations that the core application does not support. By default, Study Tracker will dispatch events within the application environment, but it can also be configured to dispatch event externally to services such as WS EventBridge.

Property	Default	Description
events.mode	local	Sets the event dispatcher/handler mode. Options are local and eventbridge.

Search

Study Tracker has an optional power-search functionality, which can be enabled with integrating with ElasticSearch. Use these parameters to enable this feature.

Property	Default	Description
search.mode	n/a	Sets the power-search mode. Currently, the only option is elasticsearch. This feature is disabled by default.

Optional Integrations

Egnyte

Deprecated. Egnyte can be used as a file storage location in Study Tracker. The current recommended way of configuring this is within the admin dashboard, but these parameters are still usable in older versions of Study Tracker.

Property	Default	Description
egnyte.tenant-name	n/a	The name of your Egnyte tenant, as it appears in your tenant URL. For example, if your tenant is accessed at https://myorg.egnyte.com, then your tenant name would be myorg.
egnyte.api-token	n/a	API token used to authenticate request
egnyte.root-path	n/a	Root directory within the Egnyte filesystem that will be used for storing study files. Eg. Shared/General/StudyTracker
egnyte.qps	1	Maximum number of queries-per-second that are allowed by Egnyte to their REST API. Setting this value will throttle requests so that they do not exceed the allowed maximum rate.

Amazon Web Services

Study Tracker can integrate directly with AWS services, including EventBridge, using the official AWS Java SDK. In order to connect to your services, you will have to provide a developer key and secret token.

Property	Default	Description
aws.access-key-id	n/a	Access key of the account you would like to connect to AWS with.
aws.secret-access-key	n/a	Secret key to authenticate the user account.
aws.region	n/a	Required when using AWS service integrations. AWS region you would like to connect to.

EventBridge

Property	Default	Description
aws.eventbridge.bus-name	n/a	Name of the EventBridge bus you would like to receive Study Tracker events. Required when events.mode is set to eventbridge.

S3

Property	Default	Description
aws.s3.default-study-location	n/a	Deprecated. Sets the default bucket to use for study storage.

Benchling

Property	Default	Description
benchling.tenant-name	n/a	Tenant identifier used to construct your organization's tenant URL. For example, if your tenant can be found at https://myorg.benchling.com, then the value would be myorg.
benchling.api.client-id	n/a	For Benchling App API authentication, the Client ID is required.
benchling.api.client-secret	n/a	For Benchling App API authentication, the Client Secret token is required.
benchling.api.token	n/a	Deprecated. HTTP Basic-digested token used for user authentication. Can be used in place of provided username and password
benchling.api.username	n/a	Deprecated. Username to use for API user authentication.
benchling.api.password	n/a	Deprecated. Password for the provided user.
benchling.api.root-url	n/a	Deprecated. Root URL of your Benchling tenant. If the benchling.tenant-name value is provided, there is no need to provide a separate value for this.

Okta

Property	Default	Description
sso.okta.url	n/a	URL for the application, as defined in the Okta dashboard.
saml.audience	n/a	This should be the full host name of your application with the context path /saml/metadata appended to it. Eg. https://myapp.com:8443/saml/metadata
saml.idp	n/a	Identity provider ID URL generated by Okta.
saml.metadata-url	n/a	Metadata URL provided by Okta for your application.
saml.metadata-base-url	n/a	Public root URL of your application, which metadata requests will be built from. Eg. https://myapp.com:8443
saml.keystore.location	n/a	File name of the JKS keystore used to store SAML certificates.
saml.keystore.alias	n/a	Alias of the JKS keystore.
saml.keystore.password	n/a	Password for the JKS keystore.
saml.max-authentication-age	86400	Maximum acceptable age (in seconds) of the Okta authentication token. Defaults to 24 hours.

ElasticSearch

Property	Default	Description
elasticsearch.host	n/a	Hostname of the Elasticsearch server.
elasticsearch.port	n/a	Port of the Elasticsearch server.
elasticsearch.use-ssl	false	Set to true if your Elasticsearch connections requires SSL be enabled.
elasticsearch.username	n/a	Username to use for Elasticsearch authentication.
elasticsearch.password	n/a	Password to use for Elasticsearch authentication.