DICOM Service - Advanced Configuration

UNDER CONSTRUCTION

This article describes some of the more advanced configuration possibilities with the TFS DICOM Service. The article is intended for administrators and IT staff. A prerequisite for understanding this article is MIRC Pipelines. You may also wish to refer to CTP-The RSNA Clinical Trial Processor. People unfamiliar with XML terminology may also wish to read XML Primer.

The article is organized as a set of use cases. Administrators whose use cases correspond exactly to the ones presented here can treat the article as a cookbook, but the ideas in these use cases can be combined to achieve other results as well.

1 The Standard DICOM Service Configuration

The default DICOM Service configuration is shown below. It receives DICOM objects and remembers the Called AE Title supplied by the sender by storing it in an element in the object before passing it down the pipe. It anonymizes the objects to remove PHI, and then inserts the them into case documents (MIRCdocuments) organized by study (StudyInstanceUID).

    <Pipeline name="DICOM Service Pipeline">
        <ImportService
            calledAETTag="00120010"
            class="org.rsna.ctp.stdstages.DicomImportService"
            logConnections="rejected"
            name="DICOM Service DicomImportService"
            port="1082"
            quarantine="quarantines/DicomService/DicomImportService"
            root="roots/DicomService/DicomImportService"/>
        <Anonymizer
            class="org.rsna.ctp.stdstages.DicomAnonymizer"
            lookupTable="scripts/lookup-table.properties"
            name="DICOM Service DicomAnonymizer"
            quarantine="quarantines/DicomService/DicomAnonymizer"
            root="roots/DicomService/DicomAnonymizer"
            script="scripts/DicomServiceAnonymizer.script"/>
        <StorageService
            class="mirc.stages.MircDocumentStorageService"
            name="MircDocumentStorageService"
            quarantine="quarantines/DicomService/MircDocumentStorageService"
            root="roots/DicomService/MircDocumentStorageService"
            ssid="ss1"
            ssidTag="00120010"
            caseTag="StudyInstanceUID"/>
    </Pipeline>

When an object is received for which no MIRCdocument already exists, the MircDocumentStorageService creates a new MIRCdocument to encapsulate it. MIRCdocuments are created from a template file. The default template file is DicomServiceTemplate.xml. This file is located in the TFS library's root directory (typically CTP/mircsite/storage/ss{n}. The default template is shown below.

<?xml version="1.0" encoding="UTF-8"?>

<MIRCdocument display="mstf" first-tab="2" temp="yes">

	<title><g0008e0020 desc="StudyDate"/> <g0010e0020 desc="PatientID"/> <g0010e0010 desc="PatientName"/></title>

	<alternative-title><g0008e0020 desc="StudyDate"/> <g0008e0060 desc="Modality"/> Study</alternative-title>

	<author>
		<name><g0012e0020 desc="Calling AETitle"/> (draft)</name>
	</author>

	<category>
		<g0008e0060 desc="Modality"/>
	</category>

	<section heading="History">
		<p/>
	</section>

	<section heading="Findings">
		<p/>
	</section>

	<section heading="Diagnosis">
		<p/>
	</section>

	<section heading="DDx">
		<p/>
	</section>

	<section heading="Discussion">
		<p/>
	</section>

	<image-section heading="Images">
		<insert-megasave width="700"/>
	</image-section>

	<authorization>
		<owner></owner>
		<read>author</read>
		<update>author</update>
		<export>author</export>
	</authorization>

</MIRCdocument>

Several parts of the template bear special attention.

• The temp="yes" attribute of the MIRCdocument element constructs the MIRCdocument as a draft document. Draft documents are not visible to standard library queries. Instead, they are listed by clicking the Draft Cases link in the left pane of the main query page. This link is only visible to authenticated users who have the author role. The administrator can set libraries to delete draft documents automatically after a specified number of days. The system default is to keep draft documents forever. When an author views a draft document, opens it in the editor, and saves it, the document loses its draft status and becomes a completed case this is visible to standard

• The title and alternative-title elements provide two different titles, one for use when the document is viewed as a known and one for use when the document is viewed as an unknown. The title element contains the patient name and ID, while the alternative-title element does not. Since the DicomAnonymizer stage appears in the default pipeline before the MircDocumentStorageService, however, no PHI remains in the object, so neither title will contain PHI. In other use cases discussed below, this will not be true.

• The authorization element does not assign an owner of the document. The first author who views the document, opens it in the editor, and saves it, automatically becomes the owner unless he assigns ownership to someone else.

• The authorization element grants any user with the author role the permission to view, edit, and export the document.

For more information on how templates are used in the system, see MIRC Templates. See also the Template Elements section of The MIRCdocument Schema.

2 Grouping Images in MIRCdocuments by PatientID

In another university, the radiologists wanted to be able to send images from multiple studies of a patient to the same MIRCdocument. They wanted the title of the created MIRCdocument to contain the actual patient name and ID, both of which are PHI. They also wanted the MIRCdocuments not to be visible through normal queries, but instead appear in the Draft Documents query only. They wanted draft documents to be deleted after two days, unless the documents were viewed, edited, and saved, in which case they became completed documents and visible to normal queries.

This is the DICOM Service Pipeline that implements this patient-centric workflow:

    <Pipeline name="DICOM Service Pipeline">
        <ImportService
            calledAETTag="00120010"
            callingAETTag="00120020"
            class="org.rsna.ctp.stdstages.DicomImportService"
            logConnections="rejected"
            name="DICOM Service DicomImportService"
            port="1082"
            quarantine="quarantines/DicomService/DicomImportService"
            root="roots/DicomService/DicomImportService"/>
        <StorageService
            class="mirc.stages.MircDocumentStorageService"
            name="MircDocumentStorageService"
            quarantine="quarantines/DicomService/MircDocumentStorageService"
            root="roots/DicomService/MircDocumentStorageService"
            ssid="ss1"
            ssidTag="00120010"
            caseTag="PatientID"/>
        <Anonymizer
            class="org.rsna.ctp.stdstages.DicomAnonymizer"
            lookupTable="scripts/lookup-table.properties"
            name="DICOM Service DicomAnonymizer"
            quarantine="quarantines/DicomService/DicomAnonymizer"
            root="roots/DicomService/DicomAnonymizer"
            script="scripts/DicomServiceAnonymizer.script"/>
    </Pipeline>

The MircDocumentStorageService was configured with a caseTag attribute specifying that images are to be grouped into MIRCdocuments by PatientID rather than the default, which is StudyInstanceUID. The value of the caseTag attribute can be specified as either a DICOM element tag (e.g. "00100011") or the dcm4che name of an element (e.g. "PatientID" or "StudyInstanceUID"). Any element can be used to group images, although it is hard to see any other elements providing useful groupings. In special situations, however, one could construct a special element in the anonymizer, combining values from multiple other elements and then reference that element in the caseTag, providing groupings that would not otherwise be available.

In the DicomAnonymizer, the script for (0012.0030) is:

@always()@initials(PatientName)-@hashptid(@SITEID,PatientID,5)

This stores a value consisting of the patient's initials, a dash, and five characters of the hashed value of the patient ID. This element is referenced in the title element in the template file to make it easy to identify the MIRCdocument in a list of query results.

In this university, MIRCdocuments created by the DICOM Service are given a temporary status that is automatically removed when an author updates the document and saves it. This is done by includiing the temp="yes" attribute in the root element of the template file. This causes the documents created by the DICOM Service to be indexed as temporary and listed in the "Temporary Documents" collection.

Note the use of the template attribute in the configuration element for the MircDocumentStorageService. The default template is DicomServiceTemplate.xml. By including the template attribute you can have multiple DICOM Service pipelines in the system, with each having its own template. The template must be stored in the root directory of the library (CTP/mircsite/storage/ss{n}). Each library must have its own copy of the template. The first time a document is created in a library, the default template is copied into place if the specified file cannot be found. That file can then be modified without it being overwritten by the system in the future.

3 Directing Studies to Specific Libraries

In one university, there are about 40 PACS workstations distributed around the Radiology department. To simplify access to MIRCdocuments for the radiologists in the various subspecialties, the TFS site is configured with one library for each subspecialty. A single DICOM Service Pipeline is configured to receive DICOM transmissions from the workstations and direct the MIRCdocuments it creates to libraries identified by information contained in the DICOM transmissions. The MIRCdocuments are required to contain a field identifying the workstation that transmitted the images, the date and time the images were received, and the name of the library ("Bone", "Chest", etc.). The images are required to be de-identified before being inserted into the MIRCdocument.

This is the DICOM Service Pipeline:

    <Pipeline name="DICOM Service Pipeline">
        <ImportService
            callingAETTag="00120010"
            calledAETTag="00120020"
            class="org.rsna.ctp.stdstages.DicomImportService"
            logConnections="rejected"
            name="DICOM Service DicomImportService"
            port="1082"
            quarantine="quarantines/DicomService/DicomImportService"
            root="roots/DicomService/DicomImportService"/>
        <Anonymizer
            class="org.rsna.ctp.stdstages.DicomAnonymizer"
            lookupTable="scripts/lookup-table.properties"
            name="DICOM Service DicomAnonymizer"
            quarantine="quarantines/DicomService/DicomAnonymizer"
            root="roots/DicomService/DicomAnonymizer"
            script="scripts/DicomServiceAnonymizer.script"/>
        <StorageService
            class="mirc.stages.MircDocumentStorageService"
            name="MircDocumentStorageService"
            ssid="ss1"
            ssidTag="00120030"
            quarantine="quarantines/DicomService/MircDocumentStorageService"
            root="roots/DicomService/MircDocumentStorageService"/>
    </Pipeline>

There are four subtleties in this modified DICOM Service Pipeline:

1. The DicomImportService is configured to store the Calling and Called AE Titles in (0012,0010) and (0012,0020), respectively. The workstations are configured with selectable destinations, one for each TFS library. The name of the destination library (e.g., "Bone") is used as the Called AE Title. The identifier of the workstation (e.g., "AW21") is used as the Calling AE Title.
2. The lookup table in the DicomAnonymizer is configured to map the value in (0012,0020) into the library ID (e.g., "ss16") corresponding to the Called AE Title and store it in (0012,0030). The anonymizer script also performs all the other de-identification required.
3. The MircDocumentStorageService is configured with an ssidTag attribute specifying that the library ID of the destination library is to be taken from (0012,0030). In this case, the value of the ssid attribute is used as the default library if the value found in (0012,0030) is not a valid library ID.
4. The DicomServiceTemplate.xml file located in each TFS library (typically found in CTP/mircsite/storage/ss{n}) is configured to insert the value of (0012,0020) into the title element in the MIRCdocument as the name of the library. It also inserts the value of (0012,0010) into the author/name element to indicate the source.

In the DICOM Anonymizer Configurator, the scripts for elements (0012,0010) and (0012,0020) are @keep() and their checkboxes are checked to ensure that the anonymizer preserves their contents.

The script for element (0012,0030) is:

@always()@lookup(ClinicalTrialProtocolID,ssid,empty)

• The @always() function call is required in order to force the anonymizer to process the script when the (0012,0030) element is not present.
• ClinicalTrialProtocolID is the dcm4che name of (0012,0020).
• ssid is the key name under which to lookup the value contained in the ClinicalTrialProtocolID element.
• empty tells the anonymizer that if a mapping is not found for the value in the ClinicalTrialProtocolID element, it should insert an empty element for (0012,0030).

See The CTP DICOM Anonymizer and The CTP DICOM Anonymizer Configurator for more information on configuring anonymizer scripts.

The lookup table is configured with values like these:

ssid/Bone = ss11

ssid/Chest = ss16

See the lookup function for more information on configuring lookup tables. Note that the three-argument form of the lookup function is used in this case to ensure that objects are not quarantined if the Called AE Title does not appear in the lookup table. When building small lookup tables, the use of the Lookup Table Editor is recommended, as it automatically formats the text properly.

The pipeline described here is a straight-forward way to create MIRCdocuments very quickly. With the system configured in this way, a user at a workstation selects images and a library destination, and a MIRCdocument containing the images appears automatically in TFS in the specified library.

The DICOM Service does not have the flexibility found in the TCE Service since the PACS workstation has no way to provide anything more than the images for the document, and all the data that is inserted into the MIRCdocument must come from the image objects (or SR objects, if any are transmitted). For PACS that have implemented the TCE Export Selector actor, the TCE Service is a more capable approach. The same capability for selecting the destination library ID from an element, using the ssidTag attribute is also available in the TCEStorageService.