This documentation is for XNAT versions 1.6.0 - 1.6.5. You can find the latest documentation for XNAT 1.7 at https://xnat.org/documentation
There are a couple different update methodologies you can pursue:
Previous versions of XNAT required that all customizations be placed into the projects folder under your XNAT builder folder. This documentation said that you should copy that folder over from your existing XNAT builder into the projects of your new XNAT builder when upgrading. This step has changed and is documented in more detail below.
Follow the steps in the installation guide to complete the installation. If you've made modifications to your projects directory, perform the following steps after Step 4 in the installation guide.
If you haven't written custom code for XNAT, or your only customizations are in xnat/projects:
Run the deployments/project/sql/project-update.sql database update script. For a project named 'xnat':
If you've modified the services.properties file–for example, to add an LDAP authentication repository–you should compare your version of this file with the updated version. The primary concern is not values that are different–those would mostly be due to configuration-specific differences–but properties that have been added to the core XNAT development version that won't be present in your customized copy of services.properties. You will need to merge any changes between the two files into your deployed XNAT web application.
If you've customized xnat_builder (assuming you forked it at some point in the past):
Another option: Use
pgdump to duplicate your database, and upgrade using that copied database. This will allow you to leave your old site up and running until you are comfortable that your upgrade was successful. To do this, you should modify the database connection parameters in build.properties after you copy it to the new installation.
If you've built your upgraded XNAT in a different folder from your previous version and use the standard pipeline engine installed under the xnat_builder folder, or if you've installed your upgraded pipeline engine in a folder separate from your xnat_builder but in different folder from your previous version, you need to make sure you change the configured location of your pipeline in your upgraded XNAT installation before running any pipelines, including archiving new sessions, which implicitly invokes the auto-run pipeline:
If you don't make this change, you may see all kinds of weird errors, including failing to generate snapshots of your newly archived sessions, verbose messages in error logs, etc.
Migrating the projects folder is the "traditional" (for lack of a better term) method of carrying over customizations from one version to the next. This is problematic, though, since things that have changed in the meantime may not be updated in the projects folder, meaning that you'll be getting old code instead of the new release.
Optimally, you'd manage this by having all of your customization code in modules. If you already have all of your XNAT customizations in modules, you can simply delete the projects and deployments folders and re-run setup and update (this ordering is necessary since update generates the SQL script to update database based on any changes in the data-type schema). This generates your projects and deployments folders again on the setup and creates your database migration script on the the update. Both scripts will process any modules you have in the specified module repo folder.
If you don't have all of your XNAT customization code in modules, you can keep your existing projects folder and copy over only those files that are part of your own customizations. This may be easier said than done, especially if you've worked on lots of little bits of code over a period of years. In that case, you can perform a diff of your projects folder with a vanilla XNAT projects folder from your previous release. To get the vanilla projects folder for this purpose, you could download, for example, the 188.8.131.52 builder from:
Run setup on this without the deploy flag set to true (i.e. just bin/setup.sh). You should be able then to diff your projects folder with the newly generated one and get a good idea of what's changed.
If you are upgrading, you should run the deployments/project/sql/project-update.sql script before running the scan-time migration script.
If you have made any customizations, either in xnat_builder or in your own projects, and any of your customized files use scan time, you should modify those files manually. Scan time was previously stored in:
No other modalities had a scan time attribute. The replacement is for these separate scan times is xnat:imageScanData/startTime . To migrate the old scan time attributes to use the new start time attribute, we've provided a migration script that only needs to be run once when migrating from a pre-1.6 database. To perform this migration:
psql -U postgres -d xnat -f scan_time_update.sql
On This Page:
General upgrade walkthrough (from 2010 XNAT Workshop)