MIRC Pipelines

From MircWiki
Jump to navigation Jump to search

This article describes the pipelines used in the CTP MIRC plug-in to implement various DICOM and HTTP functions. 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 asynchronous 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

Pipelines are defined in the CTP/config.xml file. 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.

A graphical editor for this file is planned, but for now, if you wish to reconfigure the pipelines, you must edit the file with a text editor. If you choose to do so, you may wish to refer to the CTP article that describes all the standard stages, CTP-The RSNA Clinical Trial Processor.

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 standard MIRC config.xml file is shown below: 

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

The meanings of all the attributes, except for the three StorageService elements, are described in the article referenced above. In this article the intent is to describe the flexibility you have in configuring this file.

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 include an absolute path to the desired directory. In the config.xml file, relative paths are always relative to the CTP directory.

3 The File Service Pipeline

The File Service Pipeline provides a DICOM Storage SCP to receive images from DICOM Storage SCUs, anonymize them, and store them in the File Service's file cabinets.

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

The calledAETTag attribute of the ImportService 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.

the Anonymizer 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 element. Note, however, that removing the anonymizer will result in PHI remaining in the objects, and if they are subsequently inserted into teaching file cases, such PHI will be visible to users.

The fsNameTag attribute of the StorageService 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 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.

4 The DICOM Service Pipeline

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

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

The Anonymizer element provides a DICOM anonymizer initially configured to use the DICOM Supplement 142 Basic De-identification Profile. As noted above, you can edit the anonymizer scripts through the Admin menu on the MIRC main page. If you choose to remove this element, the warnings noted above also apply.

The ssid attribute of the StorageService element specifies the ID of the MIRC storage service library in which to store the MIRCdocument created to contain the object. The MircDocumentStorageService groups objects into MIRCdocuments by StudyInstanceUID, thus grouping images of a single patient examination together.

5 The TCE Service Pipeline

The TCE Service Pipeline implements the Export Receiver actor defined in the IHE TCE Integration Profile. 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. HIPAA privacy regulations require that SOPInstanceUIDs be modified. To maintain the linkage between the UIDs in the manifest and the UIDs in the instances, the 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 StorageService element specifies the ID of the MIRC storage service library in which to store the MIRCdocument created to contain the objects identified in the manifest.

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

7 Advanced Configuration

The pipeline stages used in the pipelines above have special features that can be useful in certain situations. This section presents example use cases from two universities to illustrate how some of the features were used in a real-world situation.

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

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

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/DicomImportService2"
            root="roots/DicomService/DicomImportService"/>
        <Anonymizer
            class="org.rsna.ctp.stdstages.DicomAnonymizer"
            lookupTable="scripts/lookup-table.properties"
            name="DICOM Service DicomAnonymizer"
            quarantine="quarantines/DicomService/DicomAnonymizer2"
            root="roots/DicomService/DicomAnonymizer"
            script="scripts/DicomServiceAnonymizer2.script"/>
        <StorageService
            class="mirc.stages.MircDocumentStorageService"
            name="MircDocumentStorageService"
            ssid="ss1"
            ssidTag="00120020"
            caseTag="PatientID"
            template="PatientID-template.xml"
            quarantine="quarantines/DicomService/MircDocumentStorageService"
            root="roots/DicomService/MircDocumentStorageService"/>
    </Pipeline>

In this case, no mapping of Called AE Title into library IDs was required because the PACS was configured to use the library IDs as the Called AE Titles. Thus, the @lookup function referenced in the previous use case was not used.

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.

Retrieved from "http://mircwiki.rsna.org/index.php?title=MIRC_Pipelines&oldid=6215"