Page tree
Skip to end of metadata
Go to start of metadata

This section controls how XNAT manages incoming data. Depending on what kind of data you will be managing in your XNAT instance, how fast it will be uploaded, and what security precautions you need to take, you will want to change these settings accordingly.

Configuring the Session Builder 

The process of receiving DICOM files from a PACS or scanner and transforming those files into an MR Session object in XNAT – and applying anonymization or series filter scripts to weed out PHI – can be a complex one.

PACS systems can be connected to XNAT, but the connection is a rudimentary one. Notably, PACS systems do not provide a heads up of any incoming scan files, nor do they communicate any kind of file manifest when they start sending scan files to XNAT. Therefore, once a transmission from PACS to XNAT starts, XNAT must keep checking to see if the PACS is still sending. XNAT has to judge for itself when a session upload is complete before it starts building the session object out of the files it has. 

If additional scans are uploaded after XNAT begins building a session, XNAT will act as though these additional scans are part of a new session.

These settings allow the XNAT Administrator to configure that "wait and see" behavior. 


SettingProperty NameDescription
Received File User

This is the user account used for any operations performed on incoming data, such as performing an anonymization script. The user account must be a site administrator and must be a user that is able to log in (i.e. not disabled). By default this is set to 'admin'.

Session Idle Check Interval

This controls how often the system checks to see if any incoming DICOM sessions in the prearchive have been idle for longer than the configured session idle time. This value should be specified in milliseconds and defaults to 60,000 ms or one minute.

Setting this to a longer time interval will mean that there will be more variation in the amount of time a session will sit idle before XNAT attempts to build the session document (this time period will always be greater than the session idle time and less than the sum of the session idle time and the session idle check interval). Setting the session idle check interval to a shorter time period will make the session document get built at closer to the session idle time, but may unnecessarily burden your system by constantly checking this.

Session Idle Time

This tells the system how long a DICOM session should sit idle—that is, with no new data added to the session—before attempting to build a session document from the DICOM data. This value is specified in minutes and defaults to 5 minutes.

Setting it to a longer time will decrease the chances that XNAT builds a session document for an incompletely uploaded session (and thinks the rest of the data is a new session), but will also mean that you will have to wait longer before uploaded sessions are in Ready state. You should set this value based on how continuously you expect the data to be transmitted to XNAT so that the idle time is always longer than breaks in the transmission of a single session.

Reload Prearchive Database On Start-up?


This controls whether the prearchive database is rebuilt when your XNAT server restarts. This can help keep your system in sync with the data in prearchive, but can add to system load at start-up, especially on systems that handle a lot of incoming data.

Site-wide config properties can be accessed via REST at /xapi/siteConfig/values/{property-name}.

Site-wide config properties can be access programmatically in Velocity via $siteConfig.{property-name}.


Setting the Site-wide Anonymization Script

This Admin panel controls a site-wide setting. Anonymization scripts can also be configured on a project-by-project basis. 


SettingProperty NameDescription

Enable Site-wide Anonymization Script?


This controls whether the site-wide anonymization script should be enabled. Site-wide anonymization is enabled by default.

Note that if the site-wide anonymization is enabled, even with an empty script, it will add a deidentification method status entry to DICOM headers. To allow DICOM files to be imported without any changes, disable site-wide anonymization. 

Edit Anonymization Script

This is the site-wide anonymization script applied to all incoming and archiving DICOM resources. Uses for site-wide anonymization include clearing specific headers, changing values of some headers, clearing private tags, and setting some of the values based on inputs (such as project, subject, session, or visit). This site-wide script can also be supplemented by anonymization operations specified at the project level. The script must conform to DicomEdit format. To change the script, simply edit the text in the text box and click 'Save' when you're happy with it. See How to Write an Anonymization Script.

Anonymization Scripts from XNAT 1.6.5 and earlier will not be compatible with XNAT 1.7.0, 1.7.1, 1.7.2, because they are based on DicomEdit 4.2. Using older scripts will cause session archive actions to fail.  

XNAT 1.7.0 through 1.7.2 uses DicomEdit 6.0. See: DicomEdit: "Migration to version 6.0 scripts"

XNAT 1.7.3+ can handle both DicomEdit 6.1 and 4.2. New scripts should use DicomEdit 6.1 See: DicomEdit: "Migration to version 6.1 scripts"

Setting the Site-wide Series Import Filter

A series import filter can be set up to control specifically which kinds of scan files you want to receive in XNAT in a transfer from a PACS or DICOM AE, or via any of XNAT's image uploaders. 

With series import filters, you can direct XNAT to prevent certain data from ever entering your archive. One very important reason to do this might be that your are uploading clinical images to a research project. Clinical images often contain "burned-in PHI," meaning that the image itself (as opposed to the DICOM headers) contains PHI such as Patient Name, Patient ID, etc. You might find this information in an actual image or possibly scanned documents that are also part of the session. In the case of burned-in PHI, determining ways to identify these types of images is a bit of an art. Although DICOM fields exist to flag the presence of PHI in the image, they aren't often used. We've found that over time, you can build up a list of DICOM headers to do automated removal of about 90% of the suspects, but if you are doing public release of data, a final human check is really required.

This Admin panel controls a site-wide setting. Series import filters can also be configured on a project-by-project basis. 



SettingProperty NameDescription
Enable Site-wide Series Import Filter?

This controls whether the series import filter should be enabled. It is disabled by default.

Filter Mode

If you choose to have a site-wide series import filter, your filter can be of these three types:

  • "whitelist": only DICOM series with a series description that matches one of series filter patterns will be considered.
  • "blacklist":all DICOM series will be considered except for series that have one of the specified series filter patterns. 
  • "modality map": lets you specify boolean expressions in JavaScript that can use DICOM header values from incoming DICOM objects to decide the appropriate modality for the destination session.
Edit Series Import Filter

The series filters can be written as exact string matches, but also can be regular expressions. The regular expressions are evaluated using the Java regular expression syntax. These expressions are case-insensitive, i.e. the string "SAG LOCALIZER" will also match "Sag Localizer". Each filter should be on its own line. For example, you might have a blacklist that looks like this:


To change the series import filter, simply edit the text until you get it the way you want it and then click 'Save'.

Define Site-wide Pet Tracers

This is the site-wide list of PET tracers. List entries should be separated by whitespace. This list can also be replaced at the project level. When users upload PET Sessions using the Image Session Uploader, they can select a tracer from this list and that value will be stored as a session modifier. 

Property Name: sitewidePetTracers

Define Site-wide Handling of PET-MR Sessions

This controls whether data generated by PET-MR scanners are created as a single PET/MR imaging session, created as a single PET imaging session, or separated into PET and MR sessions. To change this simply select your desired option and click 'Save'. If no option is selected, it will default to creating a single PET/MR imaging session rather than separating them.

 Property Name: sitewidePetMr