Using the Prearchive

The XNAT Prearchive lives in a separate database and file system from your XNAT Archive, and does not permanently store any data. This makes it a safe place to triage scans that may contain PII and prevent them from being permanently stored in your Archive. When scans are sent to the Prearchive, you can review them to ensure that they have been properly anonymized, and that they are assigned to the proper project and subject, before moving them to the Archive.

To get to the Prearchive from anywhere in the XNAT application, go to Upload > Go To Prearchive in the top navigation.

Here's an overview of the elements of the Prearchive UI, and how to use it.

Elements of the Prearchive UI

The main screen consists of:

The list of sessions in the prearchive
The session details of the highlighted row
Filters on the session list
Actions that can be performed on selected sessions

Session List

By default the session list displays all the sessions in the Prearchive. Using the View Menu it is possible to see only the sessions that have been selected or filtered. You can also hide/show columns.

Left-clicking the column toggle table header will show a list of columns with checkboxes next to them. Selecting a column toggles its visibility. Please note that this setting is not saved, meaning that refreshing the page will cause the session table to revert to its default state.

Selecting/Unselecting a single session

Sessions must be selected to perform operations on them. Double-click a session to select it. The checkbox in the first column should now be checked. Double-clicking a checked session will uncheck it.

Selecting multiple sessions

You can highlight multiple sessions in one of two ways:

Control-click on individual rows
Highlight a range by clicking the first session, then shift-click the final session in the range.

To select those rows, click the Check button at the top of the session list. The highlighted rows should now be checked. Rows that were previously checked will remain checked. The Uncheck button will unselect any highlighted rows. The Check All and Uncheck All buttons perform these actions on all rows.

Using the View Menu

The "View" menu shows the following session subsets:

"All" shows all the sessions in the Prearchive.
"Selected" shows sessions that have been checked
"Filtered" shows sessions that match the constraints shown in the "Filters" section of the prearchive.

Reviewing Session Details

The details section of the prearchive displays the details of the currently highlighted session. You can also click the "Details" button to be taken to the session prearchive details page. This will give you a full view into the session and scan parameters, as well as DICOM headers and any potential conflict warnings from XNAT if any duplicate session data is found in the archive.

If desired, users can archive the session directly from the Prearchive Details Page. This is the recommended method if you need to remove a scan from the session before archiving.

Filtering the Session List

Filters allow you view a subset of the sessions in the prearchive based on

Project membership.
The date the sessions were uploaded.
The date the sessions were scanned.
The current status of the sessions
Subject or session label.

Filter Field	Usage
Project	The project tokenfield shows only those sessions that are part of one or more selected projects. The tokenfield is case-sensitive, and allows you to add or remove multiple project IDs to your filter.
Upload Date	This filter allows you to view all sessions that were uploaded between two provided dates. The expected date format is "`Mmm D, YYYY`" where Mmm is a three-letter abbreviation for the month, and D has no leading zero for single-digit dates.
Scan Date	This filter allows you to view all sessions that were scanned between two dates. The expected date format is "`Mmm D, YYYY`" where Mmm is a three-letter abbreviation for the month, and D has no leading zero for single-digit dates.
Status	The status filter only shows the sessions that have the selected status code. For more information on the meaning of the status code see Session Status.
Subject	The subject tokenfield shows only those sessions that are assigned to one or more selected subjects. The tokenfield is case-sensitive, and allows you to add or remove multiple subject labels to your filter.

Performing Actions on Sessions

Actions can be performed in bulk on any sessions that are selected in the session list. The operations are:

"Archive" moves the highlighted session(s) from the prearchive to the main XNAT archive.
"Review and Archive" allows you to review the details of a single session before archiving. This uses the Add New Session page template with prepopulated values for project and subject.
"Change Projects" moves the highlighted session to another project.
"Delete" removes the highlighted session from the prearchive.
"Rebuild" refreshes the session XML information.

Depending on the state of the highlighted row some of these buttons may be disabled. See Restrictions On Operations for more information.

The Prearchive allows you to reassign a session label, or reassign a session to a new project, but does not allow you to modify the intended subject for a session. If a session has been improperly assigned to a subject, it will need to be deleted from the prearchive and reuploaded.

Session Statuses in the Prearchive

A session status that is prefixed by "_" is locked. It indicates that that operation is currently occuring on the session and cannot be interrupted. For example, a status of "_ARCHIVING" indicates that the session is at this moment being moved into XNAT main archive. These sessions can only be reset (which cancels the operation) or deleted.

Status	Description
READY	Any operation can be performed on this session.
RECEIVING	This session could potentially receive more scans.
ARCHIVING	This session has been queued for archiving into the main XNAT archive.
BUILDING	This session has been queued for rebuilding.
MOVING	This session has been queued to moved to another project.
_RECEIVING	This session is locked because it is currently in the process of receiving a scan.
_ARCHIVING	This session is locked because it is currently being moved into the main XNAT archive.
_BUILDING	This session is locked because is currently parsing this sessions' metadata.
_MOVING	This session is locked because it is currently being moved to a new project.
ERROR	The session is in an unknown ERROR state.

Restrictions On Operations

Full documentation of operations and statuses can be found here: Prearchive Statuses and Permissions

Unassigned projects cannot be archived. To move an "Unassigned" project into the main XNAT archive, move it to a existing project and then archive it.
A session in an "ERROR" state can only be reset or deleted. The nature of the error could be anything from an error parsing the DICOM file (if it is DICOM) to a full filesystem. See the Reset operation for more details.
A session in the "RECEIVING" state cannot be moved to another project. Since the session is currently receiving more files we have to wait to move it.
A session in the "MOVING" state cannot be moved to another project since a move is pending on this session.
A Locked Session can only be deleted or reset.

Using the Prearchive via the XNAT API

The prearchive is now completely accessible via REST. It is possible to add/delete and modify sessions in the prearchive via REST.

Querying Sessions

The complete contents of the prearchive can be queried by issuing a GET to the following URL:

CODE

/data/prearchive

By default this will return the contents of the prearchive in following JSON format:

CODE

{{{"ResultSet":}}
{{{{{"Result":[{"timestamp":<session-timestamp>,}}
{{{{"scan_time":<session-scan-time>,}}
{{"project":<project-name>,}}
{{"status":<session-status>,}}
{{"tag":<study-instance-uid>,}}
{{"subject":<subject-name>,}}
{{"name":<session-id>,}}
{{"folderName":<session-label>,}}
{{"uploaded":<session-upload-time>,}}
{{"lastmod":<last-modified-time>,}}
{{"url":<session-uri>,}}
{{"scan_date":<scan-date-of-session>) }]...}}\}\}

For example:

CODE

{{{"ResultSet":}}
\{ {{"Result":[{"timestamp":"20110110_175746",}}
{{"scan_time":"12:45:23",}}
{{"project":"proj_33",}}
{{"status":"READY",}}
{{"tag":"1.3.12.2.1107.5.1.4.1003.30000009030914321258100000007",}}
{{"subject":"subj_10",}}
{{"name":"sess_1964478335",}}
{{"folderName":"0000101_PIB1_1",}}
{{"uploaded":"2011-01-10 17:57:46.0",}}
{{"lastmod":"2011-01-10 17:57:47.0",}}
{{"url":"/prearchive/projects/proj_33/20110110_175746/0000101_PIB1_1",}}
{{"scan_date":"2000-12-08 00:00:00.0"}]...}}\}\}

You can retrieve all sessions in particular project by issuing GET to:

CODE

/prearchive/projects/{projectID}

You can retrieve individual sessions with a GET call to:

CODE

/prearchive/projects/{projectID}/{timestamp}/{sessionLabel}

Uploading Sessions to the Prearchive

Sessions can be added to the prearchive by issuing a GET command to the following URL:

CODE

/data/services/import?PROJECT_ID={projectID}&SUBJECT_ID={subjectLabel}&EXPT_LABEL={sessionLabel}&overwrite=append&prearchive=true&inbody=true

For example the following curl command uploads the DICOM archive "test.zip" to project "testProj" under subject "testSubj":

BASH

curl -u <username>:<password> --data-binary @"test.zip" http://localhost:8080/xnat/data/services/import?PROJECT_ID=testProj&SUBJECT_ID=testSubj&EXPT_LABEL=testSess&overwrite=append&prearchive=true&inbody=true -H Content-Type:application/zip

Deleting Sessions

Sessions can be deleted by issuing a POST command to the following URL:

CODE

/data/services/prearchive/delete?src={sessionPath}&async={boolean}

Parameters:

src: enter the path to the session relative to the prearchive. For example: /prearchive/projects/{projectID}/{timestampDirectory}/{sessionLabel}
async: if "true", XNAT will wait for the operation to finish before the call returns. Set this to true for large operations.

For example, the following curl command will delete session "testSess" with timestamp "20110110_175747" from project "testProjectA":

BASH

curl -d "src=/prearchive/projects/testProjectA/20110110_175747/testSess&async=false" -u admin:admin http://localhost:8080/xnat/data/services/prearchive/delete

Moving Sessions

Sessions can be moved from one project to another within the prearchive by issuing the following POST request:

CODE

/data/services/prearchive/move?src={sessionPath}&newProject={projectID}&async={boolean}

Parameters:

src: enter the path to the session relative to the prearchive. For example: /prearchive/projects/{projectID}/{timestampDirectory}/{sessionLabel}
newProject: enter the ID of the new destination project.
async: if "true", XNAT will wait for the operation to finish before the call returns. Set this to true for large operations.

For example, the following curl command will move session "testSess" with timestamp "20110110_175747" from project "testProjectA" to "testProjectB":

BASH

curl -d "src=/prearchive/projects/testProjectA/20110110_175747/testSess&newProject=testProjB&async=false" -u admin:admin http://localhost:8080/xnat/data/services/prearchive/move

Rebuilding / Resetting Sessions

The session.xml for a session can be rebuilt using the following POST request:

CODE

/prearchive/projects/{projectID}/{timestamp}/{sessionLabel}?action=build

Parameters:

action: "Build" must be specified.

For example, the following curl command will rebuild the session.xml for session "testSess" with timestamp "20110110_175747" from project "testProjectA":

CODE

curl -d "action=build" -u admin:admin http://localhost:8080/xnat/data/prearchive/projects/testProjectA/20110110_175747/testSess

Adding Resources to Sessions

As of XNAT 1.8.4, you may add resources to the session in the prearchive using the following PUT request. These resources will be archived along with the session.

CODE

/prearchive/projects/{projectID}/{timestamp}/{sessionLabel}/resources/{label}/files/{file.ext}

Parameters:

if the file is in the request body, you will need the inbody=true query parameter

For example, the following curl commands will upload the file "info.pdf" as a session resource for session "testSess" with timestamp "20110110_175747" from project "testProjectA" in the prearchive:

CODE

curl -X PUT -F "file=@info.pdf" -u admin:admin http://localhost:8080/xnat/data/prearchive/projects/testProjectA/20110110_175747/testSess/resources/information/files
curl -X PUT -d "@info.pdf" -u admin:admin http://localhost:8080/xnat/data/prearchive/projects/testProjectA/20110110_175747/testSess/resources/information/files/info.pdf?inbody=true

Note: you should NOT upload DICOM files as a session resource, but rather under a particular scan. Uploading DICOM files to a session resource is unsupported.