XNAT Populate is a groovy project to push data into an XNAT (XNAT 1.7 required!) instance. It's Its main uses would be to push a lot of data into an XNAT if the data can be organized according to the desired YAML structure, or to populate a demo/sandbox server with a variety of data. The script uses groovy with dependencies managed by Grape, so the only prerequisite is a recent groovy installation. Then, simply invoke it on the command line by:
The script has the following parameters:
|Short parameter name||Long parameter name||Required?||Takes argument?||Description|
|-u||--user||yes||yes||Specifies the XNAT user to upload data. For full functionality, the user should be an admin, but this is not strictly required to use only parts of the features.|
The password for the user specified above.
The site URL for your XNAT instance to populate.
|-d||--data||yes||yes||This specifies a text file which defines the data to upload (separated by newlines). See Populate Data for more information about available data. Alternatively, instead of specifying a file, you can enter a comma-separated list of projects here.|
|-g||--config||no||yes||Specifies a YAML file as defined in Site Configuration to set site level properties.|
|-c||--clean||no||no||DANGEROUS. Add this flag to delete preexisting XNAT projects matching the data list. Don't use in production. Also, always back up your data just in case something goes wrong.|
Semi-dangerous. Add this flag to clear out the data folder on startup. Useful to grab updated copies of data.
|no||Add this flag to delete all YAML files in data folder on startup. Useful to grab updated configuration YAML.|
|-k||--insecure||no||no||Add this flag to ignore SSL errors on https sites. Useful for dev/test environments.|
|-su||--secure-users||no||no||Add this flag to only add existing XNAT users to created projects. Users that are specified in project configurations will not be created (to prevent insecure user accounts).|
As a general overview, this is the order in which the script modifies the XNAT instance after obtaining (if necessary) the data:
- If necessary, the site will be initialized. The only parameter (other than initialized=true) which will be set is the site URL.
- If specified, the config for Site Configuration is parsed and read in.
- All project YAML files are parsed (see Populate Data) and:
- Data will be located for each file.
- Any user which is to be added to a project, but does not already exist, is created.
- Any investigator which is to be added to a project, but does not already exist, is created.
- Projects are created according to the data file and configured.
- All subjects in the projects are created, and shared, if needed.
- All sessions are uploaded and pipelines launched.
- Sharing requests on the data are issued.
|-e||--export-mode||no||no||Add this flag to use XNAT Populate to export data *from* your XNAT to the local file system in a format that it can understand (can then be used to send to a different XNAT).|
|-w||--delay||no||yes||Optional delay (in milliseconds) after each session import. Useful if rapid session imports is degrading performance on the server in constrained memory situations.|