The XNAT configurations, datasets, and machine-learning plugins underwent a number of changes as part of the process of preparing for release:
If you are installing and running XNAT 1.8 or the 1.0.0 release version of the XNAT ML plugin for the first time or on a system that didn't have the ML-BETA version of XNAT or the XNAT ML plugin installed, you don't need to do anything. This migration process only applies to users who want to preserve data created using the ML-BETA version.
The pre-release version of the XNAT ML plugin was called the XNAT Clara Plugin. If you have tables in your database with names that start with 'clara_' (e.g. clara_trainsession or clara_model), this migration process converts those to the release naming scheme.
This migration process has a couple of prerequisites:
It's strongly recommended that you first try this migration process on a copy of your database, or at least have the ability to restore your database to its original state. Once you've completed the migration process, you should only re-start your XNAT system with the release versions of the datasets and ML plugins!
We provide an SQL script to convert dataset collection resources to references. To perform this conversion:
The exact format of the psql command depends on your database configuration. Suppose you have a database named kraken running on a server located at cthulhu-db, and the username and password to access the database are armitage/arcane. You would run the migrate-collection-resources-to-references.sql like this:
$ psql --host=cthulhu-db --dbname=kraken --username=armitage --file=migrate-collection-resources-to-references.sql
You should be prompted to enter the database password for the specified user. Once you've entered the password, psql should execute the script and migrate the collections resources to references. The SQL migration script is wrapped in a database transaction, so that, if an error occurs at any point during script execution, any changes already made to the database are rolled back.
To migrate the ML-BETA Clara datatypes to the release version of ML datatypes:
As with migrating dataset collection resources, the exact format of the commands for MigrateClaraToMl.groovy and psql depends on your database configuration. The options available allow you to specify the specific parameters for your database. With the same database example–a database named kraken running on the cthulhu-db server, username and password of armitage/arcane–you would run the MigrateClaraToMl.groovy like this:
$ groovy MigrateClaraToMl.groovy --server cthulhu-db --database kraken --username armitage --password
You'll be prompted to enter the database password for the specified user. Once the script completes successfully, you can use the generated SQL script to migrate your database:
$ psql --host=cthulhu-db --dbname=kraken --username=armitage --file=migrate-clara-to-ml.sql
Again, you'll be prompted to enter the database password for the specified user.
As with the dataset collection migration script, the Clara-to-ML SQL migration script is wrapped in a database transaction, so that, if an error occurs at any point during script execution, any changes already made to the database are rolled back.
The XNAT ML-BETA release introduced some preferences that were simplified and subsequently removed in the 1.8 release. These preferences need to be removed from the database before XNAT will start properly using an ML-BETA-generated database.
We provide an SQL script to remove these entries. To perform this step:
The exact format of the psql command depends on your database configuration. Suppose you have a database named kraken running on a server located at cthulhu-db, and the username and password to access the database are armitage/arcane. You would run the update-event-service-prefs.sql like this:
$ psql --host=cthulhu-db --dbname=kraken --username=armitage --file=update-event-service-prefs.sql