MIRC Pipelines

This article describes the pipelines and pipeline stages used in the CTP MIRC plug-in to implement the File Service, the DICOM Service, and the TCE Service. It is intended for administrators configuring or upgrading their systems. This article does not apply to the Tomcat MIRC version.

MIRC is implemented as a plug-in to CTP. Most of the functionality is provided through servlets that the plug-in inserts into the CTP servlet container, but certain functions are deployed as CTP pipelines. A CTP pipeline is a sequence of processing steps called pipeline stages. Pipelines start with one or more ImportServices that receive data objects from outside the program and queue them for processing by subsequent stages.

1 The CTP config.xml File

The configuration of a TFS site is contained in the CTP/config.xml file. The configuration contains the specification of the server, any plug-ins, and the pipelines. Pipelines are sequences of stages that run asynchronously, processing data objects that are received from external sources (typically a PACS, a workstation, or a modality). A default configuration is provided when the system is first installed. Subsequent upgrades do overwrite this file. Thus, changes to this file will not be lost.

This section describes the standard TFS configuration. A complete description of the configuration of a system running under CTP, including all the pipeline stages not described above, is contained in CTP-The RSNA Clinical Trial Processor.

A graphical editor for the config.xml file is planned, but for now, if you wish to reconfigure the pipelines, you must edit the file with a text editor.

Editing an XML file must be done carefully to keep it well-formed. If you are not familiar with XML, this article may be helpful, XML Primer.

The default TFS config.xml file is shown below:

<Configuration log="yes">
    <Server port="80"/>
    <Plugin
        class="mirc.MIRC"
        name="MIRC Site"
        root="mircsite"/>
    <Pipeline name="File Service Pipeline">
        <DicomImportService
            calledAETTag="00120010"
            class="org.rsna.ctp.stdstages.DicomImportService"
            logConnections="rejected"
            name="File Service DicomImportService"
            port="1081"
            quarantine="quarantines/FileService/DicomImportService"
            root="roots/FileService/DicomImportService"/>
        <DicomAnonymizer
            class="org.rsna.ctp.stdstages.DicomAnonymizer"
            id="FileServiceAnonymizer"
            lookupTable="scripts/lookup-table.properties"
            name="File Service DicomAnonymizer"
            quarantine="quarantines/FileService/DicomAnonymizer"
            root="roots/FileService/DicomAnonymizer"
            script="scripts/MircFileServiceAnonymizer.script"/>
        <MircFileStorageService
            class="mirc.stages.MircFileStorageService"
            fsNameTag="00120010"
            name="MircFileStorageService"
            quarantine="quarantines/FileService/MircFileStorageService"
            root="roots/FileService/MircFileStorageService"/>
    </Pipeline>
    <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>
    <Pipeline name="TCE Service Pipeline">
        <DicomImportService
            calledAETTag="00120010"
            class="org.rsna.ctp.stdstages.DicomImportService"
            logConnections="rejected"
            name="DicomImportService"
            port="1083"
            quarantine="quarantines/TCEService/DicomImportService"
            root="roots/TCEService/DicomImportService"/>
        <HttpImportService
            class="org.rsna.ctp.stdstages.HttpImportService"
            logConnections="rejected"
            name="HttpImportService"
            port="1084"
            quarantine="quarantines/TCEService/HttpImportService"
            root="roots/TCEService/HttpImportService"/>
        <TCEStorageService
            anonymize="yes"
            class="mirc.stages.TCEStorageService"
            name="TCEStorageService"
            quarantine="quarantines/TCEService/TCEStorageService"
            root="roots/TCEService/TCEStorageService"
            script="scripts/TCEServiceAnonymizer.script"
            ssid="ss1"
            ssidTag="00120010"/>
    </Pipeline>
</Configuration>

2 The MIRC Plug-in

The root attribute of the MIRC Plugin element specifies the root directory under which the entire MIRC site is located. This is the parent directory, for example, of all the storage libraries that contain teaching file cases. The default configuration places this directory under the CTP directory. You can change this attribute to point to any directory visible to the system. If you move it outside the CTP directory tree, however, you must specify the root as an absolute path to the desired directory. In the config.xml file, relative paths are always relative to the CTP directory.

3 The MIRC Pipeline Stages

This section describes the MIRC-specific pipeline stages that connect received objects to the teaching file system. These are supplied by the MIRC.jar module. They included in the configuration along with standard pipeline stages that are built into CTP. The standard pipeline stages are described in CTP-The RSNA Clinical Trial Processor.

3.1 MircFileStorageService

The MircFileStorageService stores objects in the MIRC file cabinets. This pipeline stage is used in the TFS File Service. The configuration element for the MircFileStorageService is:

        <MircFileStorageService
            name="MircFileStorageService"
            class="mirc.stages.MircFileStorageService"
            fsNameTag="00120010"
            quarantine="quarantines/FileService/MircFileStorageService"
            root="roots/FileService/MircFileStorageService"/>

where:

• name is any text to be used as a label on configuration and status pages.
• root is the root directory used by the stage for internal work. The root directory must be unique.
• fsNameTag is an optional DICOM element, specified in hex with no comma separating the group and element numbers, which is used to specify the name of the user in whose personal file cabinet the object is to be stored. If the attribute is missing from the configuration or if the specified element is missing from the received object, or if the contents of the specified element are not a known MIRC username, the object is stored in the shared file cabinet.
• quarantine is a directory in which the StorageService is to quarantine objects that cannot be stored.

3.2 MircDocumentStorageService

The MircDocumentStorageService stores objects in MIRCdocuments, grouped either by patient or by study. This pipeline stage is used in the TFS DICOM Service.

When it cannot find an existing MIRCdocument into which to store an object, it creates a new MIRCdocument from a template. Templates are described in MIRC Templates. The configuration element for the MircDocumentStorageService is:

        <MircDocumentStorageService
            class="mirc.stages.MircDocumentStorageService"
            name="MircDocumentStorageService"
            ssid="ss1"
            ssidTag="00120010"
            caseTag="StudyInstanceUID"
            templateName="DicomServiceTemplate.xml"
            quarantine="quarantines/DicomService/MircDocumentStorageService"
            root="roots/DicomService/MircDocumentStorageService"/>

where:

• name is any text to be used as a label on configuration and status pages.
• root is the root directory used by the stage for internal work. The root directory must be unique.
• ssid is the identifier of the default library in which to store MIRCdocuments.
• ssidTag is an optional DICOM element specifying a location in the DicomObject from which to take the identifier of the library in which to store MIRCdocuments. If a DicomObject contains the element and if the element contains a valid library identifier, it supersedes the value in the ssid attribute.
• caseTag is an optional DICOM element specifying the a location in the DicomObject to use to group objects into MIRCdocuments. The default value is StudyInstanceUID. In some workflows, PatientID may be useful.
• templateName is an optional attribute containing the name of the file to be used as the template for the construction of MIRCdocuments. The default value is DicomServiceTemplate.xml.
• quarantine is a directory in which the StorageService is to quarantine objects that cannot be stored.

3.3 TCEStorageService

The TCEStorageService implements the Export Manager and Export Receiver actors specified in the IHE Teaching Files and Clinical Trials (TCE) integration profile. It stores objects in MIRCdocuments, grouped as specified in the TCE manifest. This pipeline stage is used in the TFS TCE Service.

When it cannot find an existing MIRCdocument into which to store an object, it creates a new MIRCdocument from a template. Templates are described in MIRC Templates. The configuration element for the TCEStorageService is:

        <TCEStorageService
            class="mirc.stages.TCEStorageService"
            name="MircDocumentStorageService"
            ssid="ss1"
            ssidTag="00120010"
            autocreate="no"
            anonymize="no"
            script="ScriptFileName"
            lookupTable="LookupTableFileName"
            quarantine="quarantines/DicomService/MircDocumentStorageService"
            root="roots/DicomService/MircDocumentStorageService"/>

where:

• name is any text to be used as a label on configuration and status pages.
• root is the root directory used by the stage for internal work. The root directory must be unique.
• ssid is the identifier of the default library in which to store MIRCdocuments.
• ssidTag is an optional DICOM element specifying a location in the DicomObject from which to take the identifier of the library in which to store MIRCdocuments. If a DicomObject contains the element and if the element contains a valid library identifier, it supersedes the value in the ssid attribute.
• autocreate determines whether the username specified in the TCE manifest is to be automatically created if it does not exist. The allowed values are yes and no. The default is no.
• anonymize determines whether DicomObjects are to be anonymized. The allowed values are yes and no. The default is no.
• script specifies the path to the script for the DicomAnonymizer. If anonymize is set to yes, this attribute is required; otherwise, it is ignored.
• lookupTable specifies the path to the lookup table used by the DicomAnonymizer. This attribute is optional. If anonymize is set to yes and this attribute is missing, the anonymizer doesn't provide the lookup table function.
• quarantine is a directory in which the StorageService is to quarantine objects that cannot be stored.

4 The File Service Pipeline

The File Service Pipeline provides a sequence of stages to receive DICOM objects, anonymize them, and store them in the File Service's file cabinets.

The port attribute of the DicomImportService element specifies the port on which the DICOM Storage SCP listens for connections. You may change it to any unused port on your system.

The calledAETTag attribute of the DicomImportService element specifies a DICOM element tag in which to store the Called Application Entity Title (AET). This is used to provide a way for the sending application to specify a username for the file cabinet. For example, if the DICOM association includes the Called AET admin, that name will be stored in the element identified by the calledAETTag attribute. This makes the value available to subsequent stages, as described below. The default value of the calledAETTag attribute is an element in the group 0012, the group reserved for clinical trials data. See the description of the fsNameTag attribute, below, for more information on how the Called AET is used.

The DicomAnonymizer element provides a DICOM anonymizer initially configured to use the DICOM Supplement 142 Basic De-identification Profile. The anonymizer script can be edited graphically through the Admin menu on the MIRC main page. See The CTP DICOM Anonymizer and The CTP DICOM Anonymizer Configurator for more information. If you do not want to anonymize objects received for storage in the file cabinets, you can remove this stage. Note, however, that removing the anonymizer will result in PHI remaining in the objects, and if they are subsequently accessed, either directly or by being inserted into a MIRCdocument and then displayed, that PHI will be visible to users.

The fsNameTag attribute of the MircFileStorageService element specifies a DICOM element from which to obtain a username. If the element exists in the object received by the stage, and if the value of the element corresponds to a MIRC user's username, the StorageService places the object in the user's file cabinet. If the element is missing or if it's value does not correspond to a MIRC user, then the object is placed in the Shared File Cabinet.

If you decide to change the location in which the Called AET is stored, you must change it in both the ImportService and StorageService stages; otherwise, all objects will go to the Shared File Cabinet.

5 The DICOM Service Pipeline

The DICOM Service Pipeline provides a sequence of stages to receive images from DICOM Storage SCUs, anonymize them, and store them in MIRCdocuments in one of the TFS storage service libraries.

The pipeline shown implements the patient-centric workflow, in which objects are grouped into MIRCdocuments by PatientID. An alternative, study-centric workflow, grouping images by StudyInstanceUID, can also be implemented by setting the caseTag attribute of the MircDocumentStorageService to StudyInstanceUID. See DICOM Service - Advanced Configuration for more information.

The port attribute of the DicomImportService element specifies the port on which the SCP listens for connections. You may change it to any unused port on your system. The Called AE Title is stored in received objects in DICOM element (0012,0010). This makes the value available to the MircDocumentStorageService, which uses it to override the default TFS library in which to store the object.

The DicomDecompressor element is required to decompress images containing encapsulated pixel data so that the DicomPixelAnonymizer element can find and blank out burned-in PHI. These stages must precede the anonymizer to make sure that the elements by which the DicomPixelAnonymizer identifies the object type are available. If no images containing burned-in PHI are to be processed, these two stages can be removed from the pipeline.

The first DicomAnonymizer element provides a DICOM anonymizer initially configured to use the DICOM Supplement 142 Basic De-identification Profile, but with a modification that preserves the PatientName and PatientID elements. The reason for preserving those elements in this stage is to make them available for the title element of the MIRCdocument, making it easy to find the document in the list of draft documents on the query page.

The ssid attribute of the MircDocumentStorageService element specifies the ID of the default TFS storage service library in which to store the MIRCdocument created to contain the object. This value is overridden with the value contained in (0012,0010), as specified in the ssidTag attribute.

By default, the MircDocumentStorageService groups objects into MIRCdocuments by StudyInstanceUID, thus grouping images of a single patient examination together. To implement the patient-centric workflow, the caseTag attribute must be present and have the value PatientID.

The second DicomAnonymizer element removes the PatientName and PatientID elements from the object, thus rendering it fully anonymized. At this point, the only PHI is contained in the title element of the MIRCdocument. That PHI is only visible to TFS users who have the author role, and the PHI is automatically removed from the title element when the document is first edited.

6 The TCE Service Pipeline

The TCE Service Pipeline implements the Export Receiver actor defined in the IHE TCE Integration Profile, including support for the Additional Teaching File Information (ATFI) object. This implementation provides several extensions to the profile, including the ability to parse the Key Object Description element in the manifest to obtain information not provided in the profile, and the ability to accept a manifest as an XML MIRCdocument template. Neither of these extensions require action on the part of MIRC site administrators. The function of the pipeline is to receive objects and to group them into teaching file cases as defined by a manifest supplied with the objects by the sending system (typically a PACS workstation).

The TCE Service Pipeline has two ImportService elements, one for reception of DICOM objects via the DICOM protocol, and one for the reception of both DICOM and XML objects via the HTTP protocol.

The port attributes of the two ImportService elements specify the ports on which they listen for connections. You may change them to any unused ports on your system.

Note that there is no anonymizer stage included in the pipeline. The TCE profile specifies that the anonymization has occurred in the Export Manager before the objects are received by the Export Receiver. As a convenience, an optional anonymization facility is provided in the TCEStorageService to remove the requirement for an Export Manager in situations where the MIRC site and the Export Selector are both on the same network where PHI is not at risk. The default configuration enables this anonymizer. Even if an Export Manager is providing the anonymization externally, there is no harm in anonymizing a second time in the TCEStorageService. If you want PHI in the created MIRCdocument, however, you must set the anonymize attribute to no.

A brief aside on anonymizers in the context of the TCE profile: The TCE manifest contains a sequence element listing the SOPInstanceUIDs of the instances to be included in the MIRCdocument. The safe harbor method defined in the HIPAA privacy regulations requires that SOPInstanceUIDs be modified. To maintain the linkage between the UIDs in the manifest and the UIDs in the instances, an anonymizer must be able to process sequence items. Some anonymizers do not have that capability and therefore do not modify the SOPInstanceUIDs. By leaving the TCEStorageService anonymizer enabled, you get a complete anonymization, including the SOPInstanceUIDs, even if the external anonymizer did not provide it.

The ssid attribute of the TCEStorageService element specifies the ID of the default TFS storage service library in which to store the MIRCdocument created to contain the objects identified in the manifest. The ssidTag attribute overrides the default value. As in the DICOM Service Pipeline, the TCE Service Pipeline uses DICOM element (0012,0010) to contain the library ID.

7 Adding Pipelines

If you wish to provide multiple DICOM Service or TCE Service Pipelines to feed other MIRC storage service libraries, you can duplicate the ones above and then change all the appropriate attributes. Note that root attributes must be unique, and port attributes must not conflict with any other ports in use in the system, including ones in other pipeline stages.

In principle, you can duplicate the File Service Pipeline, but it doesn't make sense to do so, since there is only one File Service in a MIRC site.

You may not have multiple MIRC Plugin elements in a single CTP configuration.