Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


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 nameLong parameter nameRequired?Takes argument?Description
-u--useryesyesSpecifies 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--datayesyesThis 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--confignoyesSpecifies a YAML file as defined in Site Configuration to set site level properties.
-c--cleannonoDANGEROUS. 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.



noAdd this flag to delete all YAML files in data folder on startup. Useful to grab updated configuration YAML.
-k--insecurenonoAdd this flag to ignore SSL errors on https sites. Useful for dev/test environments.
-su--secure-usersnonoAdd 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:

  1. If necessary, the site will be initialized. The only parameter (other than initialized=true) which will be set is the site URL.
  2. If specified, the config for Site Configuration is parsed and read in.
  3. All project YAML files are parsed (see Populate Data) and:
    1. Data will be located for each file.
    2. Any user which is to be added to a project, but does not already exist, is created.
    3. Any investigator which is to be added to a project, but does not already exist, is created.
  4. Projects are created according to the data file and configured.
  5. All subjects in the projects are created, and shared, if needed.
  6. All sessions are uploaded and pipelines launched.
  7. Sharing requests on the data are issued.


-e--export-modenonoAdd 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--delaynoyesOptional delay (in milliseconds) after each session import. Useful if rapid session imports is degrading performance on the server in constrained memory situations.