View source for CTP Configuration for Study Distribution

This article describes how the [[CTP-The RSNA Clinical Trial Processor |CTP application]] can be configured to distribute patient studies to referring physicians and researchers. The intended audience for this article is system administrators. There are several articles on CTP on the RSNA MIRC wiki. All would be useful references when reading this article.
 
==An Example Use Case==
Many hospitals distribute digital examinations to referring physicians by producing DICOM CDs. The cost and time to produce and distribute these CDs, along with the lack of standardization of the software viewers for them, has limited their acceptance by referring physicians.

This section describes a CTP configuration with these features:
*Studies are transmitted from modalities or PACS via the DICOM protocol.
*Studies are partially anonymized to remove unnecessary PHI (though not all PHI).
*Studies are stored.
*A user account is automatically created, if necessary, for the patient when a study is received.
*Patients can view their studies at a web browser.
*Patients can download and/or delete their studies.
*Patients can make their images available to their physicians, either by providing their credentials to their physicians or by granting their physicians guest access to their studies.
*Administrators can grant physicians guest access to a patient's studies on behalf of the patient.
*The system can automatically remove studies older than a specified age.

==The Configuration File==
The configuration of a CTP instance is specified by an XML file called <tt><b>config.xml</b></tt> located in the same directory as the program. See the [[CTP-The RSNA Clinical Trial Processor |main wiki article]] for details on how CTP processes data objects and all the standard pipeline stages that are available. This section describes only those standard stages which are necessary to implement this application, and only those attributes which are required to provide the necessary features.
<pre>
<Configuration>

   <Server port="1080" />

   <Pipeline name="Pipeline">

        <DicomImportService 
            name="DICOM Import Service"
            class="org.rsna.ctp.stdstages.DicomImportService"
            root="roots/dicom-import" 
            port="104" />

        <DicomAnonymizer
            name="DICOM Anonymizer"
            class="org.rsna.ctp.stdstages.DicomAnonymizer"
            root="roots/anonymizer"
            script="roots/anonymizer/scripts/da.script"
            quarantine="quarantines/anonymizer" />

        <FileStorageService
            name="File Storage Service"
            class="org.rsna.ctp.stdstages.FileStorageService"
            root="storage"
            timeDepth="0"
            fs-name-tag="00080020"
            auto-create-user="yes"
            port="80"
            require-authentication="yes"
            quarantine="quarantines/storage" />

    </Pipeline>

</Configuration>
</pre>

====Server====
The configuration file places the CTP admin web server on port <b>1080</b>. This web server is used by administrators to monitor the status of the system. The choice of 1080 rather than the standard port 80 is made to preserve port 80 for the FileStorageService's web server.

====DicomImportService====
The configuration file puts the DicomImportService on the standard well-known DICOM port, (<b>104</b>). The DicomImportService accepts all Application Entity Titles, so when configuring the transmitting systems (modalities or PACS), any AE Title can be used.

====DicomAnonymizer====
This stage is included in the pipeline to allow unnecessary PHI to be removed before storage. An example of what might be done is to replace the patient's name with his initials (using the <b>@initials</b> function. The DicomAnonymizer provides many functions. See [[The CTP DICOM Anonymizer]] for the excruciating details. If anonymization is not required, this stage can be removed from the configuration file.

====FileStorageService====
The <b>root</b> attribute can point to any location where the FileStorageService can build its directory structure. It is shown in the configuration above as a relative path from the CTP directory (the directory in which the CTP application runs) to the <b>storage</b> directory. An absolute path may be specified instead, and that path can be on a shared drive on another computer if so desired.

The FileStorageService web server is enabled in this configuration by specifying a <b>port</b> attribute. The value, <b>80</b>, assumes that this will be the most convenient port for users.

The <b>require-authentication</b> attribute is required to ensure that only authorized users can view studies. More information on access to studies is contained in [[The CTP FileStorageService Access Mechanism]]. 

The <b>auto-create-user</b> attribute is included so that the system will create user accounts for users as their studies are received. This is only an administrative convenience. Administrators can use the <b>User Manager</b> servlet on the main admin web server to create and manage accounts at any time.

==A Slightly More Complex Configuration File==
The example configuration shown below assumes that the anonymized data objects received by the HttpImportService contain provenance information which must be removed from the stored objects after the information has been passed to the NCIA database.
<pre>
<Configuration>

   <Server port="1080" />

   <Pipeline name="Main Pipeline">

        <ImportService 
            name="HTTP Import"
            class="org.rsna.ctp.stdstages.HttpImportService"
            root="roots/http-import" 
            port="7777"
            ssl="yes"
            acceptDicomObjects="yes"
            acceptXmlObjects="yes"
            acceptZipObjects="yes"
            acceptFileObjects="yes"
            quarantine="quarantines/http-import" />

        <StorageService
            name="Storage"
            id="storage"
            class="org.rsna.ctp.stdstages.FileStorageService"
            root="D:/storage" 
            type="day"
            port="80"
            return-stored-file="yes"
            quarantine="quarantines/storage" />

        <ExportService
            name="Database Export"
            class="org.rsna.ctp.stdstages.DatabaseExportService"
            adapter-class="org.rsna.ctp.stdstages.database.DatabaseAdapter"
            file-storage-service-id="storage"
            root="roots/database-export"
            quarantine="quarantines/database-export" />

        <Processor
            name="DICOM Provenance Remover"
            class="org.rsna.ctp.stdstages.DicomAnonymizer"
            root="roots/provenance-remover" 
            script="roots/provenance-remover/dicom-anonymizer.script
            quarantine="quarantines/provenance-remover" />

        <Processor
            name="XML Provenance Remover"
            class="org.rsna.ctp.stdstages.XmlAnonymizer"
            root="roots/provenance-remover" 
            script="roots/provenance-remover/xml-anonymizer.script
            quarantine="quarantines/provenance-remover" />

    </Pipeline>
</Configuration>
</pre>

===Commentary===
The commentary in the previous section applies to this configuration as well, but it is important to note several points about the Anonymizer stages.

===FileStorageService===
It is important that the FileStorageService's <b>return-stored-file</b> attribute be set to <b>yes</b> in order that the object received by the Anonymizer stages point to the stored file. This allows the Anonymizer stages to anonymize the object in place in the FileStorageService. If the FileStorageService did not return the stored file, then an Anonymizer would anonymize the object in the HttpImportService queue, leaving the non-anonymized version in the FileStorageService.

Note that the <b>type</b> attribute is set to <b>day</b>. This stores each day's received studies in a separate directory under a year directory. This is an appropriate setting for all uses, but it is especially important when many studies are to be inserted at once. By using the <b>day</b> setting, the next higher directory will not grow too large for efficient searching.

====Anonymizer====
CTP actually contains three types of anonymizers (DICOM, XML, and Zip), each configured as a separate Processor stage with its own script file.

Note that the Anonymizer appears after the DatabaseExportService. This ensures that the database gets a copy of the object containing the provenance information.

When CTP starts, it looks for the script files in the specified locations, and if they are not present, example files are copied into place. The CTP admin web server includes a special servlet for editing DICOM anonymizer scripts. It also includes a servlet for editing all other script types, including those for the ZML and Zip anonymizers as well as the DICOM, XML, and Zip filters). See [[The MIRC XML Anonymizer]] for information on configuring the anonymizers for XmlObjects and the manifests in ZipObjects. The DICOM anonymizer is described in [[The CTP DICOM Anonymizer]].

==A Simple Configuration File for Development Testing==
The example configuration shown below would be a good starting point for testing the development of an NCIA DatabaseAdapter. It uses HTTP to receive data objects so it supports all data object types. It does not use SSL for communication. To pass objects to the HttpImportService, one could use a tool like the MIRC FileSender application.
<pre>
<Configuration>

   <Server port="1080" />

   <Pipeline name="Main Pipeline">

        <ImportService 
            name="HTTP Import"
            class="org.rsna.ctp.stdstages.HttpImportService"
            root="roots/http-import" 
            port="7777"
            acceptDicomObjects="yes"
            acceptXmlObjects="yes"
            acceptZipObjects="yes"
            acceptFileObjects="yes"
            quarantine="quarantines/http-import" />

        <StorageService
            name="Storage"
            id="storage"
            class="org.rsna.ctp.stdstages.FileStorageService"
            root="D:/storage" 
            port="80"
            return-stored-file="yes"
            quarantine="quarantines/storage" />

        <ExportService
            name="Database Export"
            class="org.rsna.ctp.stdstages.DatabaseExportService"
            adapter-class="org.rsna.ctp.stdstages.database.DatabaseAdapter"
            file-storage-service-id="storage"
            root="roots/database-export"
            quarantine="quarantines/database-export" />

    </Pipeline>
</Configuration>
</pre>

When testing, one would use FileSender to send data files to port 7777 with the HTTP protocol (not SSL). After sending some files, the CTP log could be accessed with a browser on port 1080, and the stored objects could be accessed on port 80. Note that the FileStorageService is configured to have a flat structure, so each study will appear in its own child directory of the <b>D:/storage/__default</b> directory.

==Advanced Configuration==
This section briefly notes two other points which may be of interest in special cases.

===Importing from a File Tree===
CTP is designed to be [http://mircwiki.rsna.org/index.php?title=MIRC_Clinical_Trial_Processor#Extending_ClinicalTrialProcessor extended]. One possible extension, which might be useful in capturing the contents of a large archive for the NCIA database, would be an ImportService which would walk a directory tree and supply objects to its pipeline. See the CTP Javadocs for <b>org.rsna.ctp.pipeline.ImportService</b> and <b>org.rsna.ctp.pipeline.AbstractPipelineStage</b> for more information.

===Preprocessing===
There are three other pipeline stages which might be of use in filtering out data objects which are inappropriate for inclusion in the database. They are:
*org.rsna.ctp.stdstages.DicomFilter
*org.rsna.ctp.stdstages.XmlFilter
*org.rsna.ctp.stdstages.ZipFilter

These stages are described in the [[CTP-The_RSNA_Clinical_Trial_Processor|main article]] on CTP.

If preprocessing is desired which goes beyond the capabilities of the filters' script languages, it is possible to create a special-purpose preprocessing stage. See the CTP Javadocs for <b>org.rsna.ctp.pipeline.Processor</b> and <b>org.rsna.ctp.pipeline.AbstractPipelineStage</b> for more information.