MIRC Pipelines

From MircWiki
Jump to navigation Jump to search

THIS ARTICLE IS UNDER CONSTRUCTION

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 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 plug-in and 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.

1.1 MircFileStorageService

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

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

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

        <StorageService
            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 is present 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.

1.3 TCEStorageService

The TCEStorageService implements 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: 

        <StorageService
            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 is present 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 manifeest 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.

2 The CTP config.xml File

The configuration of a TFS site is contained in a file. The configuration contains the specification of the server, any plug-ins, and the pipelines. Pipelines are aequences of stages that run asynchronously, processing data objects that are received from external sources (typically a PACS, a workstation, or a modality). The configuration is 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.

This section describes the TFS configuration. A complete description of the configuration of a system running under CTP is described 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>
    <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
            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>
    <Pipeline name="TCE Service Pipeline">
        <ImportService
            calledAETTag="00120010"
            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.

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

4 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. See the description of the fsNameTag attribute, below, for more information on how the Called AET is used.

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

5 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 pipeline shown implements the standard workflow, in which objects are grouped into MIRCdocuments by StudyInstanceUID. An alternative, patient-centric workflow, grouping images by patient, can also be implemented by reconfiguring the pipeline as described in a separate article.

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 DICOM Anonymizer link 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. By default, the MircDocumentStorageService groups objects into MIRCdocuments by StudyInstanceUID, thus grouping images of a single patient examination together.

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

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.

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

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

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


UNDER CONSTRUCTION

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=6235"