xmigrate

A Python package to migrate projects from one XNAT to another

Getting Started

Installation

We recommend installing in a project specific virtual environment created using a environment management tool such as uv.

First, create a local clone of the repository:

git clone https://github.com/UCL-MIRSG/xmigrate.git
cd xmigrate

Then install xmigrate in editable mode using uv:

uv venv --python=3.13
source .venv/bin/activate
uv sync

Running xmigrate

First, configure xmigrate using xmigrate.toml. See xmigrate.toml.sample for an example.

Then run the migration using:

xmigrate migrate

You may want to check all the necessary datatypes have been added to the destination XNAT before running the migration with a separate command:

xmigrate check_datatypes

Since the custom forms only need to be created once rather than per project then you can run a separate command to create the custom forms:

xmigrate migrate_custom_forms

N.B. Currently, the submission object of the custom forms PUT API call is hardcoded:

current_submission =  {
            "submission": {
                "data": {
                    "zIndex": [],
                    "xnatDatatype": {
                        "label": [],
                        "value": []
                    },
                    "isThisASiteWideConfiguration": [],
                    "xnatProject": [
                        {
                            "label": [],
                            "value": []
                        }
                    ]
                }
            }
        }

If the custom forms API changes then this will also need to be changed.