Upgrading to Version 1.0

Steps to prepare your Study Tracker instance for upgrade

Study Tracker version 1.0 brings a number of dependency changes that require updates to your existing instance before updating to the latest version. If you are launching a new Study Tracker instance starting from version 1.0 or later, you can skip this document.

Java and Maven

Compiling Study Tracker from source now requires Java JDK 17 or higher. Study Tracker's source code repository now includes packaged Maven Wrapper binaries that you can use to build the project on either Unix or Windows based environments.

./mvnw clean package -DskipTests

ElasticSearch and OpenSearch

Since ElasticSearch ended open source distribution of its platform after version 7.10, it has become difficult to maintain support for it while keeping other dependent libraries up-to-date. In order to keep Study Tracker's codebase modern and secure, we've dropped support for ElasticSearch in version 1.0 in favor of OpenSearch, an open source fork of ElasticSearch. This means that in order to continue using Study Tracker's Search functionality, you will be required to switch to OpenSearch as the search data source.

Thankfully, making the switch is easy. Since Study Tracker rebuilds its search index every time you start the application, no data migration is necessary. Once you have created a new OpenSearch database instance and created a user with read/write access, simply update your application.properties file from the previous format:

search.mode=elasticsearch
elasticsearch.host=
elasticsearch.port=
elasticsearch.use-ssl=
elasticsearch.username=
elasticsearch.password=

...to the new format:

search.mode=opensearch
opensearch.host=
opensearch.port=
opensearch.use-ssl=
opensearch.username=
opensearch.password=

Okta and Entra ID Single Sign-on

The underlying libraries that support SAML single sign-on have been updated to support more identity providers, such as Microsoft Entra ID. While no changes need to be made on the Study Tracker side to continue support of existing Okta integrations, a small update needs to be made on the Okta side to ensure continued support.

In the Okta admin dashboard, open up your Study Tracker application, go the the General settings and click Edit. Here is what the old configuration looked like:

Okta app config pre-v1.0

Change the Single sign-on URL suffix for your domain from /saml/SSO to /login/saml2/sso/okta

Okta app configuration in v1.0 and beyond

Save your application and then test sign-in.

If you find Study Tracker fails to start after an upgrade that included an older Java Key Store (JKS), you may need to recreate it.