Difference between revisions of "MIRC Pipelines"

From MircWiki
Jump to navigation Jump to search
 
(51 intermediate revisions by the same user not shown)
Line 1: Line 1:
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.
  
This article describes the pipelines and pipeline stages 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 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.
  
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.
+
==The CTP config.xml File==
 
+
The configuration of a TFS site is contained in the <b><tt>CTP/config.xml</tt></b> 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.  
==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]].
 
 
 
===MircFileStorageService===
 
The MircFileStorageService stores objects in the MIRC file cabinets file cabinets. It can be configured to use an element in a DICOM object to determine whether to store the object in a specific user's private file cabinet or in the shared file cabinet. The configuration element for the MircFileStorageService is:
 
 
 
<pre>
 
        <StorageService
 
            name="MircFileStorageService"
 
            class="mirc.stages.MircFileStorageService"
 
            fsNameTag="00120010"
 
            quarantine="quarantines/FileService/MircFileStorageService"
 
            root="roots/FileService/MircFileStorageService"/>
 
</pre>
 
 
 
where:
 
*<b>name</b> is any text to be used as a label on configuration and status pages.
 
*<b>root</b> is the root directory used by the stage for internal work.
 
*<b>fsNameTag</b> 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 theuse 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.
 
*<b>quarantine</b> is a directory in which the StorageService is to quarantine objects that cannot be stored.
 
  
===MircDocumentStorageService===
+
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]].
The MircDocumentStorageService stores objects in MIRCdocuments, grouped either by patient or by study. 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:
 
  
......................... done to here ..............................
+
A graphical editor for the <b><tt>config.xml</tt></b> file is planned, but for now, if you wish to reconfigure the pipelines, you must edit the file with a text editor.
<pre>
 
        <StorageService
 
            name="MircFileStorageService"
 
            class="mirc.stages.MircFileStorageService"
 
            fsNameTag="00120010"
 
            quarantine="quarantines/FileService/MircFileStorageService"
 
            root="roots/FileService/MircFileStorageService"/>
 
</pre>
 
 
 
where:
 
*<b>name</b> is any text to be used as a label on configuration and status pages.
 
*<b>root</b> is the root directory used by the stage for internal work.
 
*<b>fsNameTag</b> 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 theuse 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.
 
*<b>quarantine</b> is a directory in which the StorageService is to quarantine objects that cannot be stored.
 
 
 
==The CTP config.xml File==
 
Pipelines are defined in the <b><tt>CTP/config.xml</tt></b> 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.
 
 
   
 
   
 
:<em>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]].</em>
 
:<em>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]].</em>
  
The standard MIRC <b><tt>config.xml</tt></b> file is shown below:
+
The default TFS <b><tt>config.xml</tt></b> file is shown below:
  
 
<pre>
 
<pre>
<Configuration>
+
<Configuration log="yes">
 
     <Server port="80"/>
 
     <Server port="80"/>
 
     <Plugin
 
     <Plugin
Line 62: Line 22:
 
         root="mircsite"/>
 
         root="mircsite"/>
 
     <Pipeline name="File Service Pipeline">
 
     <Pipeline name="File Service Pipeline">
         <ImportService
+
         <DicomImportService
 
             calledAETTag="00120010"
 
             calledAETTag="00120010"
 
             class="org.rsna.ctp.stdstages.DicomImportService"
 
             class="org.rsna.ctp.stdstages.DicomImportService"
Line 70: Line 30:
 
             quarantine="quarantines/FileService/DicomImportService"
 
             quarantine="quarantines/FileService/DicomImportService"
 
             root="roots/FileService/DicomImportService"/>
 
             root="roots/FileService/DicomImportService"/>
         <Anonymizer
+
         <DicomAnonymizer
 
             class="org.rsna.ctp.stdstages.DicomAnonymizer"
 
             class="org.rsna.ctp.stdstages.DicomAnonymizer"
 +
            id="FileServiceAnonymizer"
 
             lookupTable="scripts/lookup-table.properties"
 
             lookupTable="scripts/lookup-table.properties"
 
             name="File Service DicomAnonymizer"
 
             name="File Service DicomAnonymizer"
 
             quarantine="quarantines/FileService/DicomAnonymizer"
 
             quarantine="quarantines/FileService/DicomAnonymizer"
 
             root="roots/FileService/DicomAnonymizer"
 
             root="roots/FileService/DicomAnonymizer"
             script="scripts/FileService/MircFileServiceAnonymizer.script"/>
+
             script="scripts/MircFileServiceAnonymizer.script"/>
         <StorageService
+
         <MircFileStorageService
 
             class="mirc.stages.MircFileStorageService"
 
             class="mirc.stages.MircFileStorageService"
 
             fsNameTag="00120010"
 
             fsNameTag="00120010"
Line 85: Line 46:
 
     </Pipeline>
 
     </Pipeline>
 
     <Pipeline name="DICOM Service Pipeline">
 
     <Pipeline name="DICOM Service Pipeline">
         <ImportService
+
         <DicomImportService
 +
            calledAETTag="00120010"
 +
            callingAETTag="00120020"
 
             class="org.rsna.ctp.stdstages.DicomImportService"
 
             class="org.rsna.ctp.stdstages.DicomImportService"
 
             logConnections="rejected"
 
             logConnections="rejected"
Line 92: Line 55:
 
             quarantine="quarantines/DicomService/DicomImportService"
 
             quarantine="quarantines/DicomService/DicomImportService"
 
             root="roots/DicomService/DicomImportService"/>
 
             root="roots/DicomService/DicomImportService"/>
         <Anonymizer
+
         <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"
 
             class="org.rsna.ctp.stdstages.DicomAnonymizer"
 
             lookupTable="scripts/lookup-table.properties"
 
             lookupTable="scripts/lookup-table.properties"
             name="DICOM Service DicomAnonymizer"
+
             name="DicomAnonymizer"
 
             quarantine="quarantines/DicomService/DicomAnonymizer"
 
             quarantine="quarantines/DicomService/DicomAnonymizer"
 
             root="roots/DicomService/DicomAnonymizer"
 
             root="roots/DicomService/DicomAnonymizer"
 
             script="scripts/DicomServiceAnonymizer.script"/>
 
             script="scripts/DicomServiceAnonymizer.script"/>
        <StorageService
 
            class="mirc.stages.MircDocumentStorageService"
 
            name="MircDocumentStorageService"
 
            ssid="ss1"
 
            quarantine="quarantines/DicomService/MircDocumentStorageService"
 
            root="roots/DicomService/MircDocumentStorageService"/>
 
 
     </Pipeline>
 
     </Pipeline>
 
     <Pipeline name="TCE Service Pipeline">
 
     <Pipeline name="TCE Service Pipeline">
         <ImportService
+
         <DicomImportService
 +
            calledAETTag="00120010"
 
             class="org.rsna.ctp.stdstages.DicomImportService"
 
             class="org.rsna.ctp.stdstages.DicomImportService"
 
             logConnections="rejected"
 
             logConnections="rejected"
             name="TCE Service DicomImportService"
+
             name="DicomImportService"
 
             port="1083"
 
             port="1083"
 
             quarantine="quarantines/TCEService/DicomImportService"
 
             quarantine="quarantines/TCEService/DicomImportService"
 
             root="roots/TCEService/DicomImportService"/>
 
             root="roots/TCEService/DicomImportService"/>
         <ImportService
+
         <HttpImportService
 
             class="org.rsna.ctp.stdstages.HttpImportService"
 
             class="org.rsna.ctp.stdstages.HttpImportService"
 
             logConnections="rejected"
 
             logConnections="rejected"
             name="TCE Service HttpImportService"
+
             name="HttpImportService"
 
             port="1084"
 
             port="1084"
 
             quarantine="quarantines/TCEService/HttpImportService"
 
             quarantine="quarantines/TCEService/HttpImportService"
 
             root="roots/TCEService/HttpImportService"/>
 
             root="roots/TCEService/HttpImportService"/>
         <StorageService
+
         <TCEStorageService
 +
            anonymize="yes"
 
             class="mirc.stages.TCEStorageService"
 
             class="mirc.stages.TCEStorageService"
 
             name="TCEStorageService"
 
             name="TCEStorageService"
 +
            quarantine="quarantines/TCEService/TCEStorageService"
 +
            root="roots/TCEService/TCEStorageService"
 +
            script="scripts/TCEServiceAnonymizer.script"
 
             ssid="ss1"
 
             ssid="ss1"
             anonymize="yes"
+
             ssidTag="00120010"/>
            script="scripts/TCEServiceAnonymizer.script"
 
            quarantine="quarantines/TCEService/TCEStorageService"
 
            root="roots/TCEService/TCEStorageService"/>
 
 
     </Pipeline>
 
     </Pipeline>
 
</Configuration>
 
</Configuration>
 
</pre>
 
</pre>
 
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.
 
 
 
==The MIRC Plug-in==
 
==The MIRC Plug-in==
The <b><tt>root</tt></b> attribute of the MIRC <b><tt>Plugin</tt></b> 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 <b><tt>CTP</tt></b> directory. You can change this attribute to point to any directory visible to the system. If you move it outside the <b><tt>CTP</tt></b> directory tree, however, you must include an absolute path to the desired directory. In the <b><tt>config.xml</tt></b> file, relative paths are always relative to the <b><tt>CTP</tt></b> directory.
+
The <b><tt>root</tt></b> attribute of the MIRC <b><tt>Plugin</tt></b> 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 <b><tt>CTP</tt></b> directory. You can change this attribute to point to any directory visible to the system. If you move it outside the <b><tt>CTP</tt></b> directory tree, however, you must specify the root as an absolute path to the desired directory. In the <b><tt>config.xml</tt></b> file, relative paths are always relative to the <b><tt>CTP</tt></b> directory.
  
==The File Service Pipeline==
+
==The MIRC Pipeline Stages==
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.
+
This section describes the MIRC-specific pipeline stages that connect received objects to the teaching file system. These are supplied by the <b><tt>MIRC.jar</tt></b> 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]].
  
The <b><tt>port</tt></b> attribute of the <b><tt>ImportService</tt></b> element specifies the port on which the SCP listens for connections. You may change it to any unused port on your system.
+
===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:
  
The <b><tt>calledAETTag</tt></b> attribute of the <b><tt>ImportService</tt></b> 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 <b><tt>admin</tt></b>, that name will be stored in the element identified by the <b><tt>calledAETTag</tt></b> attribute. This makes the value available to subsequent stages, as described below. The default value of the <b><tt>calledAETTag</tt></b> attribute is an element in the group 0012, the group reserved for clinical trials data. See the description of the <b><tt>fsNameTag</tt></b> attribute, below, for more information on how the Called AET is used.
+
<pre>
 +
        <MircFileStorageService
 +
            name="MircFileStorageService"
 +
            class="mirc.stages.MircFileStorageService"
 +
            fsNameTag="00120010"
 +
            quarantine="quarantines/FileService/MircFileStorageService"
 +
            root="roots/FileService/MircFileStorageService"/>
 +
</pre>
  
The <b><tt>Anonymizer</tt></b> 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.
+
where:
 +
*<b>name</b> is any text to be used as a label on configuration and status pages.
 +
*<b>root</b> is the root directory used by the stage for internal work. The root directory must be unique.
 +
*<b>fsNameTag</b> 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.
 +
*<b>quarantine</b> is a directory in which the StorageService is to quarantine objects that cannot be stored.
  
The <b><tt>fsNameTag</tt></b> attribute of the <b><tt>StorageService</tt></b> 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.
+
===MircDocumentStorageService===
 +
The MircDocumentStorageService stores objects in MIRCdocuments, grouped either by patient or by study. This pipeline stage is used in the TFS DICOM Service.  
  
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.
+
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:
  
==The DICOM Service Pipeline==
+
<pre>
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.
+
        <MircDocumentStorageService
 +
            class="mirc.stages.MircDocumentStorageService"
 +
            name="MircDocumentStorageService"
 +
            ssid="ss1"
 +
            ssidTag="00120010"
 +
            caseTag="StudyInstanceUID"
 +
            templateName="DicomServiceTemplate.xml"
 +
            quarantine="quarantines/DicomService/MircDocumentStorageService"
 +
            root="roots/DicomService/MircDocumentStorageService"/>
 +
</pre>
  
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.
+
where:
 
+
*<b>name</b> is any text to be used as a label on configuration and status pages.
The <b><tt>port</tt></b> attribute of the <b><tt>ImportService</tt></b> element specifies the port on which the SCP listens for connections. You may change it to any unused port on your system.
+
*<b>root</b> is the root directory used by the stage for internal work. The root directory must be unique.
 
+
*<b>ssid</b> is the identifier of the default library in which to store MIRCdocuments.
The <b><tt>Anonymizer</tt></b> 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.
+
*<b>ssidTag</b> 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 <b>ssid</b> attribute.
 
+
*<b>caseTag</b> is an optional DICOM element specifying the a location in the DicomObject to use to group objects into MIRCdocuments. The default value is <b>StudyInstanceUID</b>. In some workflows, <b>PatientID</b> may be useful.
The <b><tt>ssid</tt></b> attribute of the <b><tt>StorageService</tt></b> 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.
+
*<b>templateName</b> 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 <b>DicomServiceTemplate.xml</b>.
 
+
*<b>quarantine</b> is a directory in which the StorageService is to quarantine objects that cannot be stored.
==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 <b><tt>ImportService</tt></b> 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 <b><tt>port</tt></b> attributes of the two <b><tt>ImportService</tt></b> 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 <b><tt>anonymize</tt></b> attribute to <b>no</b>.
 
:<em>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.</em>
 
 
 
The <b><tt>ssid</tt></b> attribute of the <b><tt>StorageService</tt></b> 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.
 
 
 
==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 <b><tt>root</tt></b> attributes must be unique, and <b><tt>port</tt></b> 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 <b>not</b> have multiple MIRC <b><tt>Plugin</tt></b> elements in a single CTP configuration.
+
===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.  
  
==Advanced Configuration==
+
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:
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.
 
 
 
===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:
 
  
 
<pre>
 
<pre>
    <Pipeline name="DICOM Service Pipeline">
+
         <TCEStorageService
        <ImportService
+
             class="mirc.stages.TCEStorageService"
            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"
 
             name="MircDocumentStorageService"
 
             ssid="ss1"
 
             ssid="ss1"
             ssidTag="00120030"
+
             ssidTag="00120010"
 +
            autocreate="no"
 +
            anonymize="no"
 +
            script="ScriptFileName"
 +
            lookupTable="LookupTableFileName"
 
             quarantine="quarantines/DicomService/MircDocumentStorageService"
 
             quarantine="quarantines/DicomService/MircDocumentStorageService"
 
             root="roots/DicomService/MircDocumentStorageService"/>
 
             root="roots/DicomService/MircDocumentStorageService"/>
    </Pipeline>
 
 
</pre>
 
</pre>
  
There are four subtleties in this modified DICOM Service Pipeline:
+
where:
 +
*<b>name</b> is any text to be used as a label on configuration and status pages.
 +
*<b>root</b> is the root directory used by the stage for internal work. The root directory must be unique.
 +
*<b>ssid</b> is the identifier of the default library in which to store MIRCdocuments.
 +
*<b>ssidTag</b> 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 <b>ssid</b> attribute.
 +
*<b>autocreate</b> determines whether the username specified in the TCE manifest is to be automatically created if it does not exist. The allowed values are <b>yes</b> and <b>no</b>. The default is <b>no</b>.
 +
*<b>anonymize</b> determines whether DicomObjects are to be anonymized. The allowed values are <b>yes</b> and <b>no</b>. The default is <b>no</b>.
 +
*<b>script</b> specifies the path to the script for the DicomAnonymizer. If <b>anonymize</b> is set to <b>yes</b>, this attribute is required; otherwise, it is ignored.
 +
*<b>lookupTable</b> specifies the path to the lookup table used by the DicomAnonymizer. This attribute is optional.  If <b>anonymize</b> is set to <b>yes</b> and this attribute is missing, the anonymizer doesn't provide the lookup table function.
 +
*<b>quarantine</b> is a directory in which the StorageService is to quarantine objects that cannot be stored.
 +
 
 +
==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 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 <b><tt>port</tt></b> attribute of the <b><tt>DicomImportService</tt></b> 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 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 <b><tt>ssidTag</tt></b> attribute specifying that the library ID of the destination library is to be taken from (0012,0030). In this case, the value of the <b><tt>ssid</tt></b> 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 (typically found in CTP/mircsite/storage/ss{n}) is configured to insert the value of (0012,0020) into the <b><tt>title</tt></b> element in the MIRCdocument as the name of the library. It also inserts the value of (0012,0010) into the <b><tt>author/name</tt></b> element to indicate the source.
 
  
In the DICOM Anonymizer Configurator, the scripts for elements (0012,0010) and (0012,0020) are <b><tt>@keep()</tt></b> and their checkboxes are checked to ensure that the anonymizer preserves their contents.
+
The <b><tt>calledAETTag</tt></b> attribute of the <b><tt>DicomImportService</tt></b> 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 <b><tt>admin</tt></b>, that name will be stored in the element identified by the <b><tt>calledAETTag</tt></b> attribute. This makes the value available to subsequent stages, as described below. The default value of the <b><tt>calledAETTag</tt></b> attribute is an element in the group 0012, the group reserved for clinical trials data. See the description of the <b><tt>fsNameTag</tt></b> attribute, below, for more information on how the Called AET is used.
  
The script for element (0012,0030) is:
+
The <b><tt>DicomAnonymizer</tt></b> 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.
  
::<b><tt>@always()@lookup(ClinicalTrialProtocolID,ssid,empty)</tt></b>
+
The <b><tt>fsNameTag</tt></b> attribute of the <b><tt>MircFileStorageService</tt></b> 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.
  
* The <b><tt>@always()</tt></b> function call is required in order to force the anonymizer to process the script when the (0012,0030) element is not present.
+
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.
* <b>ClinicalTrialProtocolID</b> is the dcm4che name of (0012,0020).
 
* <b>ssid</b> is the key name under which to lookup the value contained in the ClinicalTrialProtocolID element.
 
* <b>empty</b> 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 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 lookup table is configured with values like these:
+
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 <b><tt>caseTag</tt></b> attribute of the <b><tt>MircDocumentStorageService</tt></b> to <b><tt>StudyInstanceUID</tt></b>. See [[DICOM Service - Advanced Configuration]] for more information.
<b><tt>
 
:ssid/Bone = ss11
 
:ssid/Chest = ss16
 
</tt></b>
 
See [[The CTP DICOM Anonymizer#.40lookup.28ElementName.2CKeyType.29|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 <b><tt>port</tt></b> attribute of the <b><tt>DicomImportService</tt></b> 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 <b><tt>MircDocumentStorageService</tt></b>, which uses it to override the default TFS library in which to store the object.  
  
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 <b><tt>ssidTag</tt></b> attribute is also available in the TCEStorageService.
+
The <b><tt>DicomDecompressor</tt></b> element is required to decompress images containing encapsulated pixel data so that the <b><tt>DicomPixelAnonymizer</tt></b> element can find and blank out burned-in PHI. These stages must precede the anonymizer to make sure that the elements by which the <b><tt>DicomPixelAnonymizer</tt></b> 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.  
  
===Grouping Images in MIRCdocuments by PatientID===
+
The first <b><tt>DicomAnonymizer</tt></b> 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.
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:
+
The <b><tt>ssid</tt></b> attribute of the <b><tt>MircDocumentStorageService</tt></b> 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 <b><tt>ssidTag</tt></b> attribute.
  
<pre>
+
By default, the <b><tt>MircDocumentStorageService</tt></b> groups objects into MIRCdocuments by StudyInstanceUID, thus grouping images of a single patient examination together. To implement the patient-centric workflow, the <b><tt>caseTag</tt></b> attribute must be present and have the value <b><tt>PatientID</tt></b>.
    <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>
 
</pre>
 
  
 +
The second <b><tt>DicomAnonymizer</tt></b> 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 <b><tt>title</tt></b> element of the MIRCdocument. That PHI is only visible to TFS users who have the <b><tt>author</tt></b> role, and the PHI is automatically removed from the <b><tt>title</tt></b> element when the document is first edited.
  
 +
==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).
  
UNDER CONSTRUCTION
+
The TCE Service Pipeline has two <b><tt>ImportService</tt></b> 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 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.
+
The <b><tt>port</tt></b> attributes of the two <b><tt>ImportService</tt></b> elements specify the ports on which they listen for connections. You may change them to any unused ports on your system.
  
In the DicomAnonymizer, the script for (0012.0030) is:
+
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 <b><tt>TCEStorageService</tt></b> 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 <b><tt>TCEStorageService</tt></b>. If you want PHI in the created MIRCdocument, however, you must set the <b><tt>anonymize</tt></b> attribute to <b>no</b>.
 +
:<em>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 <b><tt>TCEStorageService</tt></b> anonymizer enabled, you get a complete anonymization, including the SOPInstanceUIDs, even if the external anonymizer did not provide it.</em>
  
::<b><tt>@always()@initials(PatientName)-@hashptid(@SITEID,PatientID,5)</tt></b>
+
The <b><tt>ssid</tt></b> attribute of the <b><tt>TCEStorageService</tt></b> 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 <b><tt>ssidTag</tt></b> 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.
  
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 <b><tt>title</tt></b> element in the template file to make it easy to identify the MIRCdocument in a list of query results.
+
==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 <b><tt>root</tt></b> attributes must be unique, and <b><tt>port</tt></b> attributes must not conflict with any other ports in use in the system, including ones in other pipeline stages.
  
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 <b><tt>temp="yes"</tt></b> 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.
+
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.
  
Note the use of the <b><tt>template</tt></b> attribute in the configuration element for the MircDocumentStorageService. The default template is <b>DicomServiceTemplate.xml</b>. By including the <b><tt>template</tt></b> 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.
+
You may <b>not</b> have multiple MIRC <b><tt>Plugin</tt></b> elements in a single CTP configuration.

Latest revision as of 19:58, 15 January 2013

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.