# Configuration Properties Reference

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.exam`p`le` 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](https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html) 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.&#x20;

## General Properties

### Application Server&#x20;

| 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](http://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.

<table><thead><tr><th>Property</th><th width="150.33333333333331">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>server.ssl.enabled</code></td><td><code>false</code></td><td>Set to <code>true</code> to enable SSL.</td></tr><tr><td><code>server.ssl.key-store-type</code></td><td>n/a</td><td>Set the keystore type to use to store certificates. This should be set to <code>PKCS12</code>.</td></tr><tr><td><code>server.ssl.key-alias</code></td><td>n/a</td><td>Alias of the keystore you created.</td></tr><tr><td><code>server.ssl.key-store</code></td><td>n/a</td><td>File name of the keystore.</td></tr><tr><td><code>server.ssl.key-store-password</code></td><td>n/a</td><td>Password given when creating the keystore.</td></tr></tbody></table>

### Electronic Laboratory Notebook

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

<table><thead><tr><th width="254">Property</th><th width="138.33333333333331">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>notebook.mode</code></td><td><code>none</code></td><td><strong>Deprecated</strong>. Sets the notebook software to be used, if needed. Options are <code>none</code> and <code>benchling</code>.</td></tr></tbody></table>

### File Storage

<table><thead><tr><th width="275">Property</th><th width="147.33333333333331">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>storage.mode</code></td><td><code>local</code></td><td><strong>Deprecated</strong>. Sets the file system or cloud storage service to be used for storing study files. Options are <code>local</code> and <code>egnyte</code>.</td></tr><tr><td><code>storage.use-existing</code></td><td><code>false</code></td><td>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 <code>false</code>, an exception will be thrown when trying to create a folder that already exists. Should only be set to <code>true</code> for development or staging applications.</td></tr><tr><td><code>storage.temp-dir</code></td><td><code>/tmp</code></td><td>Directory used by the application for storing temp files. This is primarily used as a landing area for uploaded files.</td></tr><tr><td><code>storage.local-dir</code></td><td><code>/tmp</code></td><td>When <code>storage.mode</code> is set to <code>local</code>, this property will specify the directory on the local filesystem to be used as the root folder for storing study files.</td></tr></tbody></table>

### Study Metadata

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

### 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.

<table><thead><tr><th width="218">Property</th><th width="130.33333333333331">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>events.mode</code></td><td><code>local</code></td><td>Sets the event dispatcher/handler mode. Options are <code>local</code> and <code>eventbridge</code>.</td></tr></tbody></table>

### Search

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

<table><thead><tr><th width="218">Property</th><th width="145.33333333333331">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>search.mode</code></td><td>n/a</td><td>Sets the power-search mode. In v1.0 and above, the only supported option is <code>opensearch</code> . In earlier versions, the only option is <code>elasticsearch</code>. This feature is disabled by default.</td></tr></tbody></table>

## **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](/documentation/integrations/egnyte.md), but these parameters are still usable in older versions of Study Tracker.

<table><thead><tr><th>Property</th><th width="130.33333333333331">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>egnyte.tenant-name</code></td><td>n/a</td><td>The name of your Egnyte tenant, as it appears in your tenant URL. For example, if your tenant is accessed at <code>https://myorg.egnyte.com</code>, then your tenant name would be <code>myorg</code>.</td></tr><tr><td><code>egnyte.api-token</code></td><td>n/a</td><td>API token used to authenticate request</td></tr><tr><td><code>egnyte.root-path</code></td><td>n/a</td><td>Root directory within the Egnyte filesystem that will be used for storing study files. Eg. <code>Shared/General/StudyTracker</code></td></tr><tr><td><code>egnyte.qps</code></td><td>1</td><td>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.</td></tr></tbody></table>

### 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.

<table><thead><tr><th width="279">Property</th><th width="126.33333333333331">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>aws.access-key-id</code></td><td>n/a</td><td>Access key of the account you would like to connect to AWS with.</td></tr><tr><td><code>aws.secret-access-key</code></td><td>n/a</td><td>Secret key to authenticate the user account.</td></tr><tr><td><code>aws.region</code></td><td>n/a</td><td><em>Required when using AWS service integrations.</em> AWS region you would like to connect to.</td></tr></tbody></table>

#### **EventBridge**

<table><thead><tr><th>Property</th><th width="131.33333333333331">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>aws.eventbridge.bus-name</code></td><td>n/a</td><td>Name of the EventBridge bus you would like to receive Study Tracker events. Required when <code>events.mode</code> is set to <code>eventbridge</code>.</td></tr></tbody></table>

#### S3

<table><thead><tr><th width="253">Property</th><th width="157.33333333333331">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>aws.s3.default-study-location</code></td><td>n/a</td><td><strong>Deprecated</strong>. Sets the default bucket to use for study storage.</td></tr></tbody></table>

### Benchling

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

### Okta

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

### OpenSearch

<table><thead><tr><th>Property</th><th width="153.33333333333331">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>opensearch.host</code></td><td>n/a</td><td>Hostname of the Elasticsearch server.</td></tr><tr><td><code>opensearch.port</code></td><td>n/a</td><td>Port of the Elasticsearch server.</td></tr><tr><td><code>opensearch.use-ssl</code></td><td><code>false</code></td><td>Set to <code>true</code> if your Elasticsearch connections requires SSL be enabled.</td></tr><tr><td><code>opensearch.username</code></td><td>n/a</td><td>Username to use for Elasticsearch authentication.</td></tr><tr><td><code>opensearch.password</code></td><td>n/a</td><td>Password to use for Elasticsearch authentication.</td></tr><tr><td><code>opensearch.connection-timeout</code></td><td>60000</td><td>Host connection timeout (milliseconds).</td></tr><tr><td><code>opensearch.socket-timeout</code></td><td>50000</td><td>Host socket timeout (milliseconds).</td></tr></tbody></table>

### ElasticSearch

**Deprecated**. As of v1.0, ElasticSearch is no longer supported.

<table><thead><tr><th>Property</th><th width="153.33333333333331">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>elasticsearch.host</code></td><td>n/a</td><td>Hostname of the Elasticsearch server.</td></tr><tr><td><code>elasticsearch.port</code></td><td>n/a</td><td>Port of the Elasticsearch server.</td></tr><tr><td><code>elasticsearch.use-ssl</code></td><td><code>false</code></td><td>Set to <code>true</code> if your Elasticsearch connections requires SSL be enabled.</td></tr><tr><td><code>elasticsearch.username</code></td><td>n/a</td><td>Username to use for Elasticsearch authentication.</td></tr><tr><td><code>elasticsearch.password</code></td><td>n/a</td><td>Password to use for Elasticsearch authentication.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://study-tracker.gitbook.io/documentation/installation-and-configuration/configuration-properties-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.