Defining Project Metadata Modification

Before the upload applet sends DICOM data to XNAT, it looks for a metadata modification script for that project. If such a script exists, the applet applies the defined modifications to the files before sending. This is a customizable, project-specific mechanism for regularizing header fields, removing PHI, setting custom fields, or any other automated modification of the DICOM and/or XNAT metadata for the session to be uploaded.

Obsolete documentation alert!

The following paragraph describes setting a DICOM metadata modification (DicomEdit) script for earlier XNAT versions. The current method for setting DicomEdit scripts uses the XNAT configuration service. This page will be updated when that documentation is found or created (with luck, very soon).

Uploading a metadata modification script

There is no web application interface for defining, viewing, or modifying metadata modification scripts. All operations must be performed using the REST interface. The form of the URL for DICOM metadata modification scripts is:


For example, the following command line would use curl to upload the modification script from the local file ./my-project.das to the XNAT project "MyProject", using the XNAT username "xnatuser" and password "password":

curl -X PUT -u xnatuser:password '' --data-binary @my-project.das

DICOM metadata modification syntax

The metadata modification scripts language is essentially the same language as is used for DicomBrowser ( anonymization scripts (, with a few extensions.

Session variables

A session variable is a name representing a value in the metadata modification script. Session variables may be assigned an initial value; the user may be allowed to modify this value before the script is applied.

Several session variables are predefined by the upload applet, including project, the name of the project into which the session will be placed; subject, the subject label; and session, the session label. project and subject should not be modified, as they are set by the user's selections in the upload applet, but they may be used to assign DICOM attributes or other variables. One common use of a metadata modification script is to pick a sensible default session name, as in this example script:

session := "\{0\}_\{1\}" subject, (0008,0020)

If the subject label is "Subject001" and the Study Date (0008,0020) is "20110518", then the resulting initial session label will be "Subject001_20110518". This value that will be presented to the user in the "Enter session details" page; the user may either accept this default value or edit the label value.

If the study to be uploaded includes PET data, the upload applet will define the session variable tracer; a pulldown menu will be provided for the user to select the tracer used. The XNAT field xnat:petSessionData/tracer is assigned to the value of tracer when the session is uploaded. A metadata modification script may assign a value to tracer to set which value is initially selected in the pulldown menu:

*tracer := "FDG"*

The upload applet also defines a session variable named modalityLabel. This is a hidden variable; i.e., it does not appear on the "Enter session details" page and thus cannot be modified by the user. It normally contains the DICOM abbreviation for the modality (e.g, "MR", "CT", "XA") unless the session includes PET data, in which case it is set equal to the final value of tracer.

Custom session variables can be defined in a metadata modification script. A valid variable name begins with a letter or underscore, followed by any number of letters, numbers or digits. The folllowing are valid variable names: foo, _baz, n42; while these are invalid: 42n, foo?, b.z. .

The simplest way to define a session variable is simply to assign it in the script:

PatientID := (0010,0020)
(0010,0020) := PatientID

This seemingly circular pair of statements does an interesting thing: it adds a new PatientID field to the "Enter session details" page, sets the initial value of that field to the original value of Patient ID (0010,0020), and then, when the data are uploaded, changes (0010,0020) to the value of the PatientID field (which may have been modified by the user).

Session variables can be exported to XNAT metadata fields using the export command: 

visit := (0008,0050)
export visit "xnat:experimentData/visit_id"

The statements above define a new session variable (and text field on the "Enter session details") named visit, with initial value taken from Accession Number (0008,0050), and sets the XNAT session field visit_id to the final value of visit.

If a session variable should not be edited by the uploading user, it can be made hidden: 

visit := (0008,0050)
describe visit hidden
export visit "xnat:experimentData/visit_id"

In this case, the session variable visit is assigned the value of Accession Number, and its value is exported to the XNAT session field visit_id, but visit is not made visible (or editable) to the user on the "Enter session details" page.


The metadata modification script language includes several predefined functions. All functions share the same syntax:

function-name[argument1, argument2, ...]

A function call can be used anywhere a value can be used in a metadata modification script: on the right hand side of an assignment, or as an argument to a function. The predefined functions are:

Function name Arguments Description
format format, value1, value2, ... Formats the given values using the provided format string, using the same syntax as java.text.MessageFormat.
getURL URL Retrieves the content of the resource at the provided URL, as a string.
lowercase string Converts all uppercase characters in the argument to lowercase.
makeSessionLabel format Generates a unique XNAT session label based on the provided format; the character # in the format string will be assigned an incrementing index until a unique label is found. Multiple # characters together make a zero-padded, multiple-digit index (e.g., ### produces indices like 001, 002, ...). See the example below.
match value, pattern, index Matches the given value against the given pattern and returns the content of the matching group with the given index. This is roughly equivalent to java.util.regex.Pattern.compile(pattern).matcher(value).group(index).
replace string, target, replacement Replaces all occurrences of target in the given string with replacement, similar to the java.lang.String function of the same name.
substring string, start, end Returns a substring of string beginning at the start index and extending to the character at index end-1, similar to the java.lang.String function of the same name.

Example: Building an indexed session label and visit number

The script excerpt below creates a unique, indexed session label, extracts a visit ID from that label, and assigns the visit ID in the appropriate XNAT field:

session := makeSessionLabel[format["{0}_v##_{1}", subject, modalityLabel]]
visit := match[session, ".*_(v[0-9]+)_.*", 1]
describe visit hidden
export visit "xnat:experimentData/visit_id"

If subject is "Subject001" and the modality is MR, this script builds an indexed label as follows: the format statement in the first line builds the string "Subject001_v##_MR", which is passed as a format argument to makeSessionLabel. makeSessionLabel replaces the ## characters in the format string with zero-padded integers, and increments the index until a unique session label is found. In this case, makeSessionLabel will first try the label "Subject001_v00_MR"; if this session label already exists in the specified project, the index will be incremented to try "Subject001_v01_MR". The process will repeat until an unused label is found, which will be the initial value of session.

The variable visit takes as its initial value the visit index part of the session label (including the leading v). Note that this uses the final value of session, not the initial value, so if the user modifies the session label, the initial value of visit will change accordingly. (Because visit is hidden in this case, it does not appear on the "Enter session details" page, and the only way the user can change the visit id is implicitly, by editing the session label.)