icon-usingXNAT.png
Working With XNAT


Advanced Topics

[Edit Nav]


XNAT 1.5: Managing Data with the Prearchive


Main Screen


prearcMain.png
1. The list of sessions in the prearchive
2. The session details of the highlighted row
3. Filters on the session list

Session List


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

Hiding/Showing Columns



ColumnVisibility.png
Right-clicking the column toggle table header shows 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



Selecting/Unselecting a single session


To select a session double click it. The checkbox in the first column should now be checked. Double-clicking a checked session will uncheck it.

Highlight multiple sessions


Highlight multiple sessions by:
- highlighting the desired rows with the mouse while holding down the Control key.
- highlighting a range by clicking the first session, and then while holding down the Shift key and click the final session in the range.

Selecting multiple sessions

1. Highlight the desired row
2. Click the "Select" button. The highlighted rows should now be checked. Rows that were previously checked will remain checked.

Unselect multiple sessions

1. Highlight the desired row
2. Click the "Unselect" Button. The highlighted rows should now be unchecked. Rows that were previously unchecked will remain unchecked.

Select All Sessions

There is no button which supports this operation because of the potentially large number of sessions in the prearchive. You can however highlight all the rows and the click the "Select" button. This is not recommended if you have over 5000 sessions in the prearchive.

Unselect All Sessions

Click the "Unselect All" button.

Views Menu


The "Views" menu shows the following session subsets:

ViewsMenu.png

- "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.


Details


Details.png
The details section of the prearchive view the details of and perform some operations on the currently highlighted session. The operations are:
- "Archive" moves the highlighted session from the prearchive to the main XNAT archive. See Operations for more information.
- "Move" moves the highlighted session to another project. See Operations for more information.
- "Delete" removes the highlighted session from the prearchive. See Operations for more information.
- "Reset" refreshes the session information. See Operations for more information.

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

Filters


Filters.png

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

1. Project membership.
2. The date the sessions were uploaded.
3. The date the sessions were scanned.
4. The current status of the sessions
5. Subject or session label.

The above diagram, for instance, will show only sessions:
- located in "proj_69",
- uploaded between January 4th, 2011 and January 18th, 2011,
- scanned between September 1st, 2008 and October 16th 2008,
- with a "READY" status and
- with the label "sess_1510899638".

Project Filter


The project tokenfield shows only those sessions that are part of one or more selected projects. See Using the Tokenfield for more information on how to use this search.

Upload Date Filter


This filter allows you to view all sessions that were uploaded between two dates. If there are projects selected in the "Projects:" field, you will only be able to see sessions that are in those projects. See [[#Using The Date Filter|Using The Date Filter]] for more information on how to use this search.

Scan Date Filter


This filter allows you to view all sessions that were scanned between two dates. If there are projects selected in the "Projects:" field, you will only be able to see sessions that are in those projects. See [[#Using The Date Filter|Using The Date Filter]] for more information on how to use this search.

Status Filter


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/Session Filter


The subject/session tokenfield that shows only the sessions or subjects that match the given name. If there are projects selected in the "Projects:" field, you will only be able to select subjects and sessions that are in any of those projects. See Using the Tokenfield for more information on how to use this search.

Using The Date Filter


The date filter allows you view sessions that were either uploaded or scanned within a range of dates. The "From" and "To" textfields are the beginning and end of the range respectively. If the "From" textfield is left blank all sessions uploaded before the date in the "To" textfield are shown and vice versa if the "To" field is blank.

Using The Project/Subject/Session Tokenfield


The token field allows you to search the sessions by multiple values. This is best explained using examples, the sections below show how to select sessions in multiple projects but the instructions also apply to the "Subject/Session" tokenfield.

Inserting into the token field


If, for example, you had three projects, "proj_60", "proj_61", and "proj_62" and you wanted to view only the sessions in "proj_60" and "proj_61", select the "Projects:" textfield and do the following:
1. Start typing "proj_60" and select it from the drop-down list. Selecting it inserts a "proj_60" token into the textfield and narrows the session list to just those sessions in "proj_60".
TypeProj60.png

2. Start typing "proj_61" and select it from the drop-down list. Selecting it inserts a "proj_61" token into the textfield.
TypeProj61.png

3. Since there is already a "proj_60" token in the textfield the session list show sessions in both "proj_60" and "proj_61".

DisplayProj6061.png

Deleting from the token field


Now let's say that, having followed the steps in the previous section you only want to see sessions in "proj_61" just click the "X" in the "proj_61" token.

You can also accomplish the same thing using the keyboard. To do this:
1. Select the "Projects:" textfield
2. Use the left arrow key to move the cursor so that it is just after the "proj_60" token.
3. Hit the Backspace key. The "proj_60" token should now be reddened.
4. Hit the Backspace key again. The "proj_60" token should now be deleted and the session list should only show the sessions in "proj_61"

Operations



Reset


The reset operation rebuilds the session by recreating the sessions' metadata and generating a new session.xml. This is helpful if the session is in an "ERROR" state.


Move


Moves a session to another project. See Restrictions On Operations on times when this operation is disabled.

Archive


Moves a session from the prearchive to the main XNAT archive. See Restrictions On Operations on times when this operation is disabled.

Delete


Deletes a session from the prearchive.

Batch Operations



When an operation is run on multiple sessions it is run asynchronously. This means that the operation on the selected sessions is not carried out immediately but scheduled. Each sessions' status is changed to indicate that the selected operation is pending.

Locked Sessions


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.

Session Status


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


- 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.

Prearchive REST Access

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 POST to the following URL:
<xnat-url>/data/prearchive
By default this will return the contents of the prearchive in following JSON format:
{"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:
{"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:
<xnat-url>/prearchive/projects/<project-name>

And individual sessions with:
<xnat-url>/prearchive/projects/<project-name>/<timestamp>/<session-label>

Adding Sessions

Sessions can be added by issuing a GET command to the following URL:
<xnat-url>/data/files/import?project=<project-name>&subject=<subject-name>&session=<session-label>&overwrite=append&prearchive=true&inbody=true

For example the following curl command uploads the DICOM archive "test.zip" to project "testProj" under subject "testSubj":
curl -u <username>:<password> --data-binary @"test.zip" http://localhost:8080/xnat/data/files/import?project=testProj&subject=testSubj&session=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:
<xnat-url>/data/services/prearchive/delete
with the following "src" and "async" parameters in the body of the message:
src=/prearchive/projects/<project-name>/<timestamp-directory>/<session-label>
async=false

For example, the following curl command will delete session "testSess" with timestamp "20110110_175747" from project "testProjectA":
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:
<xnat-url>/data/services/prearchive/move
with the following parameters in the body:
src=/prearchive/projects/<project-name>/<timestamp>/<session-label>
newProject=<project-name>
async=false

For example, the following curl command will move session "testSess" with timestamp "20110110_175747" from project "testProjectA" to "testProjectB":
curl -d "src=/prearchive/projects/testProjectA/20110110_175747/testSess&newProject=testProjB&async=false" -u admin:admin http://localhost:8080/xnat/data/services/prearchive/move

Resetting Sessions

The session.xml for a session can be rebuilt using the following POST request:
<xnat-url>/data/prearchive/projects/<project-name>/<timestamp>/<session-label>
with the following parameter in the body:
action=build

For example, the following curl command will rebuild the session.xml for session "testSess" with timestamp "20110110_175747" from project "testProjectA":
curl -d "action=build" -u admin:admin http://localhost:8080/xnat/data/prearchive/projects/testSess/20110110_175747/testProjectA