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.

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 server dramatically and to reduce the number of parallel threads 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/..."
        defaultString="UNKNOWN"
        whitespaceReplacement="_"/>

• cacheSize specifies the maximum number of files to combine into a single zip file for transmission to the XNAT server.
• structure is an optional sequence of directory names specifying the hierarchy of the storage tree in the zip file. Directories in the sequence are separated by slashes. Each directory name in the sequence can consist of text and/or DICOM tags. If a directory name in the sequence includes one or more DICOM tags, the values of the corresponding elements in the current DICOM object are substituted in the directory name for the tags. See the notes below for more details and examples of directory structures. If this attribute is missing, all files are stored in the root directory of the zip file.
• 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 the text to be used to replace sequences of whitespace characters in the directory path and filename constructed from the structure attribute.

Notes

1. In directory names, 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.