The DICOM Service Configurator
The DICOM Service Configurator provides a user interface for setting the parameters in the trial.xml file. It also provides access to the DICOM Anonymizer Configurator. The DICOM Service Configurator is accessed by clicking the Update Configuration button in the DICOM Service column on the storage service's admin page.
1 Top-level Parameters
At the top of the DICOM Service Configurator window is a small table containing parameters that apply to all the components of the DICOM Service.
If you want the DICOM Service to start automatically whenever the MIRC site is started, set the Autostart value to yes.
If you want all transmissions to be logged in the trial/logs directory under the root of the storage service, set the Log value to yes. Some trials require logs of all transmissions, so carefully consider this choice. The log is a comma-separated values file which can be opened with a spreadsheet program. If you are operating this DICOM service as an automatic teaching file generator, you probably should set this parameter to no.
If you want duplicate images (images with the same SOP Instance UIDs) to update previous versions, making the last image received the only one stored and referenced in the MIRCdocument, set the Allow overwrite value to yes. This is the way most trials are operated. If you want imageswith duplicate SOP Instance UIDs to be saved and individually referenced, set the value to no.
The DICOM Service has one DICOM Anonymizer, which can be invoked by the DICOM Import Service and the Database Export Service. To configure the DICOM Anonymizer, click the Update the Anonymizer button. The process of configuring the anonymizer is described in The MIRC DICOM Anonymizer.
2 Central Remapper
In trials which use the central remapping feature of the DICOM Service and the FieldCenter application, the parameters are configured in the second table on the page. The remapper, whether local or central, uses a cipher to encrypt the PHI which is stored in its database. The remapper has a default encryption key which is normally used when the network on which the MIRC site is run is secure. This only provides security against casual access to the data. To use the default key, blank the External key file field. To specify a separate key and secure it against access, the absolute path (e.g., X:\keyfile.storage) to a key file is inserted in the field as described in The Remapper Encryption Key.
The UID root field specifies the UID root to be assigned to all remapped UIDs by the uid anonymizer function of the FieldCenter application that calls the central remapper.
The Base date field specifies the base date to be used in the offsetdate function.
The last four parameters of the table specify the parameters to be used in the ptid function.
3 DICOM Import Service
The DICOM Import Service is typically used for MIRCdocument generation for images received from local modalities. The two main applications are research dataset acquisition and teaching file creation. It is also possible to use this service for participation in a clinical trial where the principal investigator site is elsewhere on the internet, but the FieldCenter application is much more suited for this purpose and you are encouraged to use that application instead.
The third table on the page provides fields for specification of the Application Entity Title and port or the DICOM Storage SCP built into the DICOM Import Service. The AE Title and port should be unique on the system, so if you are running DICOM Services on multiple storage services on the computer, make sure that all the SCPs have unique values for both parameters.
The third table also allows you to enable or disable the DICOM anonymizer. This anonymizer only applies to objects received via the DICOM prototol from local modalities or PACS. Generally, in a MIRC site serving as the principal investigator's image receiver, images enter the system via the HTTP protocol from sites running the FieldCenter application at image acquisition sites on the internet. Thus, the setting of this parameter will not affect those images, which are typically anonymized by the FieldCenter application before transmission. For applications where images are obtained locally for research datasets or teaching files, the setting of this parameter is very important because it determines whether PHI is retained in images stored by the storage service.
4 DICOM Export Service
Images which are received by the HTTP Import Service can be automatically forwarded (after anonymization, if enabled) to one or more destinations via the DICOM protocol. The DICOM Export Service has two operating modes:
- auto - images are forwarded immediately after reception (and possible anonymization).
- QC - images are not forwarded until a user with administration privileges on the storage service reviews the MIRCdocument and clicks the To DICOM SCP button on the document.
The table below the Mode field provides fields to define the AE Titles and ports of the DICOM Storage SCPs to which images are to be transmitted. Each destination must be given a one-word name which is unique within the storage service. This name is used for a subdirectory of the trial/dicom-export directory. These subdirectories serve as queues for images being sent to the various destinations.
Each time the configurator parameters are saved by clicking the Update trial.xml button at the bottom of the page, the updated page is redisplayed with a new blank line in this table, allowing additional destinations to be entered. To remove a destination, blank its parameters in the table and save the page.
5 HTTP Import Service
The HTTP Import Service is typically used for receiving images and other objects from FieldCenter applications located at image acquisition sites in clinical trials.
The current implementation does not support anonymization of objects received by the HTTP Import Service, so the Anonymizer enabled field is not used at present. Since the FieldCenter application performs anonymization before transmission, there is no need for this function in a clinical trial.
The IP Address table provides fields for specification of the IP addresses of sites which are authorized to send images into the trial. Connections from all other IP addresses are rejected. Entries in the table must be numeric IP addresses, not domain names. If an asterisk appears in any field in the table, the HTTP Import Service accepts all connections. This feature is only useful if all image acquisition sites in a trial have fixed IP addresses. If any site's address cannot be predicted, then you must accept connections from all IP addresses.
Each time the configurator parameters are saved by clicking the Update trial.xml button at the bottom of the page, the updated page is redisplayed with a new blank line in this table, allowing additional destinations to be entered. To remove a destination, blank its parameters in the table and save the page.
6 HTTP Export Service
Images which are received by the DICOM Import Service can be automatically forwarded (after anonymization, if enabled) to one or more destinations via the HTTP protocol. This is a rarely used feature since the DICOM Import Service is rarely used for clinical trials. The table provides fields for specification of the URLs of destinations to which images are to be transmitted, with each destination being given a one-word name which is unique within the storage service. This name is used for a subdirectory of the trial/http-export directory. These subdirectories serve as queues for images being sent to the various destinations. The HTTP Export Service supports both the HTTP and HTTPS (secure sockets layer) protocols, the latter providing additional security for transmission.
Each time the configurator parameters are saved by clicking the Update trial.xml button at the bottom of the page, the updated page is redisplayed with a new blank line in this table, allowing additional destinations to be entered. To remove a destination, blank its parameters in the table and save the page.
7 Database Export Service
The DICOM Service can be interfaced to an external database by developing a Java class called a DatabaseAdapter and connecting it to the Database Export Service. The development process is described in Implementing an External Database Interface for MIRC Clinical Trials.
The Database Export Service has three operating modes:
- auto - images are forwarded to the DatabaseAdapter immediately after reception (and possible anonymization).
- QC - images are not forwarded until a user with administration privileges on the storage service reviews the MIRCdocument and clicks the To Database button on the document.
- disabled - nothing is forwarded to the DatabaseAdapter.
When enabled, all images are forwarded to the DatabaseAdapter, whether they were received by the DICOM Import Service or the HTTP Import Service.
The Anonymizer enabled field allows for anonymization of the images after submission to the DatabaseAdapter. This allows the database to receive data from the objects as they were received and then remove any necessary information. The purpose of this feature is illustrated in this scenario:
- Images at image acquisition sites are anonymized by the FieldCenter application.
- For use in the database, the anonymizer at each FieldCenter site inserts provenance information into DICOM elements in each image before forwarding it to the principal investigator's HTTP Import Service for the trial.
- The HTTP Import Service processes the images, creating MIRCdocuments as necessary, and queuing them for Database Export Service.
- The Database Export Service forwards each image in turn to the DatabaseAdapter, which extracts the provenance information plus whatever other data is required and updates the external database.
- After processing by the Database Adapter, the Database Export Service runs the anonymizer, which is configured to remove the provenance information from the image referenced by the MIRCdocument, thereby hiding the origin of the image from viewers of the MIRCdocument.
The Sleep interval (ms) field specifies the length of time between checks of the queue. The default value is fine for normal operation. If you have concerns about the connection load on your database, you can change the value as necessary.
The Database class name field specifies the full name of the DatabaseAdapter class, including package information, e.g., edu.myuniversity.mytrial.TheDatabaseAdapter.
8 Saving Changes
Changes in the parameters on the DICOM Service Configurator page are not saved until the Update trial.xml button at the bottom of the page is clicked.