DICOM Service - Advanced Configuration

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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

3 The Study-Centric Workflow

An alternative 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>

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 when it is used to create or modify the MIRCdocument, so neither title will actually contain PHI. In other use cases discussed below, this will not be true.

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

............................................not done yet....................................

5 Directing Studies to Specific Libraries

In another 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:

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

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