DICOM Service - Advanced Configuration

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. Additional information on pipelines and the standard stages available in CTP is contained in 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 DICOM Service Template

When the DICOM Service receives an object is received for which no MIRCdocument already exists, the DICOM Service 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><g0010e0020 desc="PatientID"/>: <g0010e0010 desc="PatientName"/></title>
	<alternative-title><g0010e0020 desc="PatientID"/>: <g0010e0010 desc="PatientName"/></alternative-title>
	<author>
		<name><g0012e0020 desc="Calling AETitle"/> (draft)</name>
	</author>
	<modality></modality>
	<section heading="History">
		<p/>
	</section>
	<image-section heading="Images">
		<insert-megasave width="700"/>
	</image-section>
	<section heading="Findings">
		<p/>
	</section>
	<section heading="Diagnosis">
		<p/>
	</section>
	<section heading="DDx">
		<p/>
	</section>
	<section heading="Discussion">
		<p/>
	</section>
	<section heading="Comments">
		<threadblock id="CB-0-0" />
	</section>
	<authorization>
		<owner></owner>
		<read>author</read>
		<update>author</update>
		<export></export>
	</authorization>
	<phi>
		<pt-name><g0010e0010 desc="Patient Name"/></pt-name>
		<pt-id><g0010e0020 desc="Patient ID"/></pt-id>
	</phi>
	<publication-date/>
</MIRCdocument>

Several parts of the template merit 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, visible to standard library queries.

• 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. In this template, both are set to the same values so the document can be identified in the draft document listing whether the query results are displayed as unknowns or not.

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

When a draft document is edited and saved by an author, it is automatically renamed and it loses its draft status. Once it has been renamed, subsequent DICOM objects received for the same study will be placed into a new draft document. This allows multiple documents to be created by the DICOM Service for a single study. If the draft document feature is not desired, the temp="yes" attribute of the MIRCdocument element in the template must be removed. If that is done, the document is not renamed when an author saves it, and subsequent DICOM objects received for the study will always update the existing document.

2 The Patient-centric Workflow

In one university, the radiologists wanted to be able to send images from multiple studies of a single 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 Cases 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">
        <DicomImportService
            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"/>
        <DicomDecompressor
            class="org.rsna.ctp.stdstages.DicomDecompressor"
            name="DicomDecompressor"
            quarantine="quarantines/DicomService/DicomDecompressor"
            root="roots/DicomService/DicomDecompressor"/>
        <DicomPixelAnonymizer
            class="org.rsna.ctp.stdstages.DicomPixelAnonymizer"
            name="DicomPixelAnonymizer"
            quarantine="quarantines/DicomService/DicomPixelAnonymizer"
            root="roots/DicomService/DicomPixelAnonymizer"
            script="scripts/DicomPixelAnonymizer.script"/>
        <DicomAnonymizer
            class="org.rsna.ctp.stdstages.DicomAnonymizer"
            name="DicomAnonymizer - ForcePatientID"
            root="roots/DicomService/ForcePatientID"
            script="scripts/ForcePatientID.script"/>
        <MircDocumentStorageService
            caseTag="PatientID"
            class="mirc.stages.MircDocumentStorageService"
            name="MircDocumentStorageService"
            quarantine="quarantines/DicomService/MircDocumentStorageService"
            root="roots/DicomService/MircDocumentStorageService"
            templateName="DicomServiceTemplate.xml"
            ssid="ss1"
            ssidTag="00120010"/>
        <DicomAnonymizer
            class="org.rsna.ctp.stdstages.DicomAnonymizer"
            lookupTable="scripts/lookup-table.properties"
            name="DicomAnonymizer"
            quarantine="quarantines/DicomService/DicomAnonymizer"
            root="roots/DicomService/DicomAnonymizer"
            script="scripts/DicomServiceAnonymizer.script"/>
    </Pipeline>

Notes:

• The study date was not included in the template's title element. The rationale was that since multiple study dates would appear in the same document, the date is not meaningful. (This apparently makes sense to radiologists.) The resulting element was thus:

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

When multiple study dates appear in a document, the system automatically generates a caption for each image, indicating whether it belongs to the earliest (baseline) study or to a subsequent one. For images belonging to subsequent studies, it indicates the number of days since the baseline.

• The DicomAnonymizer stage appears after the MircDocumentStorageService stage. This makes PHI available to the template for inclusion in the title element. The MircDocumentStorageService moves a DICOM object into the MIRCdocument's directory and always passes the object in its new location to the next stage. This allows the DicomAnonymizer to remove the PHI from the object after the MircDocumentStorageService has obtained whatever information it requires.

To be clear, after the object has passed all the way down the pipe, no PHI remains in the object, but PHI does exist in the title element of the MIRCdocument.

• The MircDocumentStorageService is configured with a caseTag attribute specifying that images are to be grouped into MIRCdocuments by PatientID rather than the default, which is StudyInstanceUID. (Any DICOM element can be used to group images into MIRCdocuments, although it is hard to see any other elements providing useful groupings.)

Parenthetically, in the MircDocumentStorageService the template attribute of the MircDocumentStorageService can be used to specify a non-standard template. 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 The Study-Centric Workflow

In another university, radiologists wanted to group images into MIRCdocuments by study. The configuration for this case 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 MIRCdocuments organized by study (StudyInstanceUID).

    <Pipeline name="DICOM Service Pipeline">
        <DicomImportService
            calledAETTag="00120010"
            class="org.rsna.ctp.stdstages.DicomImportService"
            logConnections="rejected"
            name="DICOM Service DicomImportService"
            port="1082"
            quarantine="quarantines/DicomService/DicomImportService"
            root="roots/DicomService/DicomImportService"/>
        <DicomAnonymizer
            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"/>
        <MircDocumentStorageService
            class="mirc.stages.MircDocumentStorageService"
            name="DICOM Service MircDocumentStorageService"
            quarantine="quarantines/DicomService/MircDocumentStorageService"
            root="roots/DicomService/MircDocumentStorageService"
            ssid="ss1"
            ssidTag="00120010"
            caseTag="StudyInstanceUID"/>
    </Pipeline>

• In this configuration, since the DicomAnonymizer stage appears in the pipeline before the MircDocumentStorageService, no PHI remains in the object when it is used to create or modify the MIRCdocument, so neither the title element nor the alternative-title element in the MIRCdocument will contain PHI.

4 Directing Studies to Specific Libraries

In another university using the Study-centric Workflow, 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">
        <DicomImportService
            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"/>
        <DicomAnonymizer
            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"/>
        <MircDocumentStorageService
            class="mirc.stages.MircDocumentStorageService"
            name="DICOM Service 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 (located 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 even 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.

5 A Note on the DICOM Service vs. the TCE Service

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.