Configuring the HttpExportService for Connection to XNAT Servers

This article describes how to configure the CTP HttpExportService pipeline stage for efficient export to an XNAT server. The intended audience for this article is CTP administrators.

The HttpExportService configuration element has two child elements intended to invoke special features in coordination with an XNAT server. The Launcher application's Configuration tab allows the administrator to add these children and provides guidance in defining their attributes.

The xnat child element makes authentication of the transfers from the HttpExportService to the XNAT server more efficient. The element has these attributes:

    <xnat
        url="https://host:port/data/JSESSION"
        cookieName="JSESSIONID"
        password=""
        username=""/>

• url specifies the URL of the XNAT server's authentication service.
• cookieName specifies the cookie name in the set-cookie header returned by the XNAT server after a successful authentication.
• username specifies the username on the XNAT server for authentication.
• password specifies the password on the XNAT server for authentication.

Notes:

1. In the url attribute, JSESSION is the only value recognized by the current XNAT implementation. Do not change this unless the XNAT API changes.
2. In the cookieName attribute, JSESSIONID is the only value recognized by the current XNAT implementation. Do not change this unless the XNAT API changes.

When this element is present, the HttpExportService authenticates on the first transfer, obtains the session cookie, and passes that cookie back to the server on all subsequent transfers. The effect is to reduce the authentication load on the XNAT server dramatically and to reduce the number of parallel threads in the server required to handle large transfers.

The compressor child element makes the actual file transfers themselves more efficient. The element has these attributes:

    <compressor
        cacheSize="0"
        structure="dir1/dir2/dir3/.../name"
        defaultString="UNKNOWN"
        whitespaceReplacement="_"/>

• cacheSize specifies the maximum number of files to combine into a single zip file for transmission to the XNAT server. The default is zero, meaning no zip compression. A value of 100 has been found to work well.
• structure is text specifying the hierarchy of the storage tree in the zip file, ending in a file name. For XNAT transfers, the directory hierarchy is generally omitted and the attribute simply specifies the construction of the file name, resulting in all the files being stored in the root of the zip file. If a more complex structure is required, path elements are separated by slashes. Each path element in the sequence can consist of text and/or DICOM tags. If a path element in the sequence includes one or more DICOM tags, the values of the corresponding elements in the current DICOM object are substituted for the tags. See the notes below for more details and examples of structure attributes. If this attribute is missing, all files are stored in the root directory of the zip file and given the name specified by the defaultString attribute, e.g. UNKNOWN[n].dcm, where n is a number.
• defaultString specifies the text to be used when a DICOM element specified in the structure attribute is missing from a file to be transferred.
• whitespaceReplacement specifies a string used to replace whitespace, slash, or backslash characters in a directory name constructed froom the structure attribute. If this attribute is missing, the underscore character is used.

Notes:

1. In path elements, DICOM tags are hex integers, formatted in parentheses or square brackets. Tags may optionally include commas to separate the group and element numbers. Leading zeroes are good form but not required in group numbers. Leading zeroes are required in element numbers. Commas are removed before parsing tags, so (20,D) is not equivalent to (20,000D).
2. This example shows tags for PatientID/AccessionNumber/StudyInstanceUID: (0010,0020)/[00080050]/(0020,000D).
3. This example shows how text and multiple tags can be combined in a single directory name: (0010,0020)/(0020,000D) - [00080050]. In this case the PatientID is used as the top-level directory, with a subdirectory consisting of the StudyInstanceUID, a space, a hyphen, another space, and the AccessionNumber.
4. Whitespace replacement is performed on all the text of a directory name, after substitution of the DICOM element values for any tags in the name, so in the example in the previous note, the separator between the StudyInstanceUID and the AccessionNumber would actually appear in the directory name as "_-_".
5. DICOM tags in directory names can include references to elements in sequence element item datasets in the form (0040,0275)::(0040,1001). There is no limit to the number of tags in the sequence. All but the last tag must refer to SQ elements. Only the first item dataset is searched at each level.

When this element present and cacheSize is greater than zero, the compressor attempts to group as many files as are available (up to cacheSize) into a single zip file and initiates a single transfer. The compressor never waits for more files if fewer than cacheSize files are available; it just sends all that it has. The XNAT server automatically de-compresses the zip file and stores the content files.

This is an example of an HttpExportService configuration element exporting to an XNAT server:

<HttpExportService
    acceptXmlObjects="no"
    acceptZipObjects="no"
    class="org.rsna.ctp.stdstages.HttpExportService"
    name="HTTPS Export to XNAT"
    quarantine="/data/test/quarantines/dicom-export"
    root="/data/test/dicom-export"
    sendDigestHeader="yes"
    url="https://XNAT-IP-address:443/data/services/import?import-handler=DICOM-zip&inbody=true">

    <compressor
        cacheSize="100"
        defaultString="unknown"
        structure="(0010,0020).(0008,0060).(0008,0020).(0008,0030).(0020,0011).(0020,0013).(0019,10A2)"/>

    <xnat
        cookieName="JSESSIONID"
        password="aXNATPassword"
        url="https://XNAT-IP-address:443/data/JSESSION"
        username="aXNATUser"/>

</HttpExportService>