Skip to end of metadata
Go to start of metadata


Description of the plugin suitable for inclusion in documentation

Source code

Link to source code, version(s), attributions.


The following configuration parameters can be set in Config.groovy. The plugin must be enabled, and is only visible when logged in as an administrator. Data imported is available and secured as for any clinical study.

org.transmart.xnatImporterEnable = true = (location of transmart-data with env/tranSMART-ETL)


The original documentation for the plugin is available at 

Old version XNAT API documentation is now at


The example in the documentation uses a local XNAT server. Any XNAT account can access a number of public projects to learn how to define and import variables.

The eTRIKS project has the following variables which were uses for the study loaded on the test server:

 Import configuration

DescriptioneTRIKS example image data
XNAT web address
Username(any public user)
XNAT projectnameeTRIKS
TranSMART nodenameXNAT eTRIKS 


XNAT Variables

The 'Name' column is the node name used in tranSMART. The XNAT URL is the location of the data in XNAT for the given server and project. The user's password will be prompted for when loading starts and is not stored by tranSMART.

The XNAT paths come from the XML paths wiki page referenced above. Care is needed to get the correct paths as errors are only found when loading starts. tranSMART does not contact the XNAT server until the password has been prompted for and cannot make an earlier check.

Name (node in tranSMART)DataTypeDataTypeXNAT (REST) URLXNAT
Height (inches)Subjectxnat:subjectData/demographics[@xsi:type=demographicdata]/height
Weight (lbs)Subjectxnat:subjectData/demographics[@xsi:type=demographicdata]/weight
Recruitment sourceSubjectxnat:subjectData/src
ExperimentSession xnat:experimentdata/ID
ProjectSession xnat:experimentdata/project
ScanLabelSession xnat:experimentdata/label
ScanDateSession xnat:experimentdata/date
ScannerSession xnat:imageSessionData/scanner
OperatorSession xnat:imageSessionData/operator
PatientIDSession xnat:imageSessionData/dcmPatientId
PatientNameSession xnat:imageSessionData/dcmPatientName
SessionTypeSession xnat:imageSessionData/session_type
SessionModalitySession xnat:imageSessionData/modality
SessionUidSession xnat:imageSessionData/UID

Restarting an import

In the Admin tab you can click on "Configuration List" and then "Show" against any already defined, but not yet imported, XNAT study.

The data can be corrected and then "Import data" used to restart data loading.


TranSMART tried to catch and report errors from data loading. Files are stored in the XNAT import temporary directory, by default /tmp/jobs/xnattotransmartlink

In this directory you can expect to find the following files:

(project).xmlThe names and XNAT paths to be imported, as defined in the admin panel
xnat.tmmThe clinical data mapping file
xnat0.tmdOne or more clinical data files, one per visit as defined by xnat:experimentdata/visit_id
command-running.txtCommand to launch the KETTLE clinical data load, with paths defined in the server's Config.groovy file
command.outThe standard output from the KETTLE job 
load_clinical_data.logThe standard KETTLE job log file 


The configuration can be changed and reloaded if the study name is set to a new value.

Unwanted copies can be cleaned up as for any other clinical study in tranSMART.


  • No labels