Adding Sessions using the Rest API

A single REST API call can be used to simultaneously create a subject and MR session (scan). This page will walk you through how to use a bash script that calls the API to create a set of subjects and sessions in XNAT.

Data

We start with a csv file called scans.csv with subject_id, scan_id and scan_date, i.e.:

ex_01,ex_01_mr,2012-03-04
ex_02,ex_02_mr,2012-03-17
ex_03,ex_03_mr,2012-03-25

Reading the CSV

It's straightforward to loop through a CSV file in bash with the read command. If you copy the following snippet in to a text file called load.sh that sits alongside the scans.csv file you just created :

csv=scans.csv
while IFS=, read col1 col2 col3
do
  echo "read $col3"
done < $csv

and run it by typing, bash load.sh then you should see the following output:

read 2012-03-04
read 2012-03-17
read 2012-03-25

XNAT API call

The command line instruction for creating an MR Session with a particular date via the REST API, using CURL is curl -X PUT -u $user:$pass $xnat_url/data/archive/projects/$project/subjects/$subject_id/experiments/$scan_id?xsiType=xnat\:mrSessionData\&xnat\:mrSessionData/date=$scan_date.

If you are using XDC then the (very similar) equivalent instruction is ./XnatDataClient -m PUT -u $user -p $pass -r $user:$pass $xnat_url/data/archive/projects/$project/subjects/$subject_id/experiments/$scan_id?xsiType=xnat\:mrSessionData\&xnat\:mrSessionData/date=$scan_date

There is a snippet with a standalone bash script that checks for a valid url, project, credentials etc and then runs the XnatDataclient version of the script: https://issues.dpuk.org/dpuk/node/snippets/3.

There are also modular forms of these scripts that require a session_id. For a big job, modular scripts should be called from another bash script (sometimes known as a spider) that first gets a session id and then reads in data that should be uploaded to xnat and calls the modular script using it's tomcat session id.

Creating a tomcat session

The REST enpoint to get a tomcat session id is: ./XnatDataClient -u $user -p $pass -r $url/data/JSESSION. If you include the -c flag then you'll be able to check that they final line looks like HTTP status: 200 i.e. success.

Putting it all together

If we put this all together then, using snippet https://issues.dpuk.org/dpuk/node/snippets/7 we can write a spider file that reads a csv file and creates MR Sessions for each line in the csv file, assuming they dont already exist...

#!/bin/bash
url=https://central.xnat.org
csv=scans.csv
echo "Upload to: $xnat from $csv"
echo -n "XNAT username: "
read user
echo -n "XNAT password: "
read -s pass
echo
echo -n "XNAT project: "
read project
session=$(./XnatDataClient -c -u $user -p $pass -r $url/data/JSESSION)
if [[ $(echo "$session" | tail -n 1) == HTTP\ status\:\ 200 ]]; then
  session_id=$(echo "$session" | head -c 32)
  while IFS=, read col1 col2 col3 col4
  do
    ./createsessionmod.sh $url $session_id $project $col2 $col1 $col3
  done < $csv
else
  echo "Failed: unauthorised"
fi