CTP Configuration for Study Distribution
This article describes how the 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.
1 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.
2 The Configuration File
The configuration of a CTP instance is specified by an XML file called config.xml located in the same directory as the program. See the 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.
<Configuration>
<Server port="1080" />
<Pipeline name="Main Pipeline">
<DicomImportService
name="stage name"
class="org.rsna.ctp.stdstages.DicomImportService"
root="roots/dicom-import"
port="104" />
<DicomAnonymizer
name="Anonymizer"
class="org.rsna.ctp.stdstages.DicomAnonymizer"
root="roots/anonymizer"
script="roots/anonymizer/scripts/da.script"
quarantine="quarantines/anonymizer" />
<FileStorageService
name="Storage"
class="org.rsna.ctp.stdstages.FileStorageService"
root="storage"
timeDepth="0"
fs-name-tag="00080020"
port="80"
require-authentication="yes"
quarantine="quarantines/storage" />
</Pipeline>
</Configuration>
2.1 Server
The configuration file places the CTP admin web server on port 1080. 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.
2.2 DicomImportService
The configuration file puts the DicomImportService on the standard well-known DICOM port, (104). The DicomImportService accepts all Application Entity Titles, so when configuring the transmitting systems (modalities or PACS), any AE Title can be used.
2.3 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 @initials 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.
2.4 FileStorageService
The root 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 storage 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 port attribute. The value, 80, assumes that this will be the most convenient port for users.
The require-authentication 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 auto-create-user 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 User Manager servlet on the main admin web server to create and manage accounts at any time.
3 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.
<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>
3.1 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.
3.2 FileStorageService
It is important that the FileStorageService's return-stored-file attribute be set to yes 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 type attribute is set to day. 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 day setting, the next higher directory will not grow too large for efficient searching.
3.2.1 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.
4 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.
<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>
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 D:/storage/__default directory.
5 Advanced Configuration
This section briefly notes two other points which may be of interest in special cases.
5.1 Importing from a File Tree
CTP is designed to be 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 org.rsna.ctp.pipeline.ImportService and org.rsna.ctp.pipeline.AbstractPipelineStage for more information.
5.2 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 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 org.rsna.ctp.pipeline.Processor and org.rsna.ctp.pipeline.AbstractPipelineStage for more information.