View source for Clinical Trial Administrator's Manual

This article describes how to configure a MIRC storage service for clinical trials. It applies to the RSNA MIRC implementation, and it is intended for MIRC site administrators.

==Overview==
A MIRC storage service includes several components specifically oriented to clinical trials. These components, called services, work together to support a single trial. When a MIRC site must support multiple clinical trials, multiple storage services are installed, one for each trial. Generally, if one or more teaching file components are required on a site, they are also supported by separate storage services.

The key services related to clinical trials are:
* <b>DICOM Import Service</b> - a DICOM Storage SCP that receives DICOM objects (typically from modalities or PACS) using the DICOM protocol.
* <b>HTTP Import Service</b> - a service that receives DICOM, XML, or Zip objects (typically from remotely located imaging centers) using the HTTP or HTTPS protocol.
* <b>DICOM Export Service</b> - a DICOM Storage SCU that forwards DICOM objects received by the HTTP Import Service to DICOM Storage SCPs using the DICOM protocol.
* <b>HTTP Export Service</b> - a service that forwards DICOM objects received by the DICOM Import Service to HTTP Export Services (typically at other locations).
* <b>Database Export Service</b> - a service that forwards DICOM, XML, Zip, or file objects to an interface to an external database, allowing athe construction of a trial-specific database outside the scope of MIRC.

For historical reasons, these are called the <b>DICOM Service</b>, even though they support more than DICOM objects.

To facilitate the management of a multi-site trial, MIRC also includes the <b>Update Service</b>, a service that provides the clinical trial administrator control over the software and configuration files at remotely located imaging centers.

The RSNA MIRC project has developed several supporting applications and tools that cooperate in the operation of a trial. The most important of these is the <b>FieldCenter</b> application, which runs at a remotely located imaging center and automatically transmits images to the principal investigator site.

In a typical trial, the principal investigator's site is a MIRC site and each of the imaging centers run the FieldCenter application. The flow of data is depicted in the diagram below.
<center>
[[Image:ClinicalTrial1.JPG]]
</center>

The diode symbols depict firewalls at each site. The ones at the imaging centers block all inbound connections. The one at the principal investigator site blocks all inbound connections except for at least one port, shown here as the standard SSL port (8443), which is used to allow imaging centers to upload images and data files and to make connections to the MIRC site for downloading configuration files and software updates.

Typically, all transfers are done across the internet using secure sockets layer (SSL). A [[Configuring Tomcat to Support SSL|separate article]] describes how to configure Tomcat to support SSL.

The overall layout of the components in a MIRC storage service is shown below.
<center>
[[Image:StorageServiceDiagram1.JPG]].
</center>

The boxes outlined in red are the ones of primary interest in a clinical trial.

The general processing flow begins at a modality or workstation at an imaging center:
* The modality transmits one or more images to a computer running the FieldCenter application.
* The FieldCenter application receives the images via the DICOM protocol and queues them for anonymization. 
* After anonymization, the FieldCenter application queues the images for transmission to the principal investigator site via the HTTP or HTTPS protocol.
* The HTTP Import Service at the principal investigator site receives each image individually and queues it for processing by the Object Processor.
* The Object Processor parses the image and obtains its DICOM Study Instance UID.
* The Object Processor looks to see if a MIRCdocument for the Study Instance UID already exists in the storage service.
** If the MIRCdocument already exists, it opens it.
** If the MIRCdocument does not exist, it creates a new MIRCdocument by copying the <b>template.xml</b> file from the storage service's <b>trial</b> directory.
* Once it has a MIRCdocument corresponding to the Study Instance UID of the image, the Object Processor inserts the image. Note that, as described in [[MIRC Templates]], templates (which are actually MIRCdocuments) can contain template elements that instruct the insertion process how to obtain information from images or other files and place it in the document.
* After creating and/or updating the MIRCdocument for the image, the Object processor queues the image for all the destinations (if any are configured) for the DICOM Export Service.
* The Object Processor then queues the image for the Database Export Service, if enabled.
* The DICOM Export Service forwards all images in its queues to their respective DICOM Storage SCP destinations.
* The Database Export Service presents all images in its queue to the database interface, an externally developed program which does whatever its designers have designed it to do. A [[Implementing an External Database Interface for MIRC Clinical Trials|separate article]] describes the database interface in detail.

==Setting Up a Clinical Trial==
There are many ways to use MIRC in a clinical trial. This section describes the most common approach, where a multi-center trial is focused on a single principal investigator, which controls all the software and manages all the configuration files.

===Install a storage service for the trial===
Each trial must have its own storage service. To add a storage service to a MIRC site, run the installer, and on the <b>Storage Service Installation</b> page, click <b>Install</b> and follow the instructions in the sequence of dialog boxes:
* For the one-word name of the storage service, you can choose any word you wish, but it is usually best to use the name or acronyn of the trial so the storage service's URL will be both short and memorable.
* For the two- or three-character prefix, choose a prefix that is unique on the MIRC site. This will allow you to control which users can access the documents and images on the storage service.
* When asked whether documents should be indexed automatically, answer <b>yes</b>. This is secure because alll documents will be restricted to authenticated users who have the permissions granted through the unique prefix.
* Because you created a unique prefix, you will have to add the appropriate roles to the administrator's role. On the <b>Create Administrator User</b> page, click <b>Create</b> and enter your username.

===Configure the network for the trial===
If the trial is entirely within an institution and the network is secure, you can use port 8080 and not bother with setting up a Secure Sockets Layer (SSL) connection for Tomcat. For most trials, however, the data transmission will take place across the internet, and you should configure SSL on port 8443 as described in [[Configuring Tomcat to Support SSL]].

After doing that, you need to ensure that port 8443 is open for inbound connections from the internet. This must be done by the IT staff at the principal investigator's site. In some cases, the IT staff may be concerned about security problems and may want to put the server in the border router's DMZ. This will not affect the ability of the site to receive images, but it will make it impossible for the site to forward images to a PACS or workstation inside the main network. The solution to that problem is to open the necessary port from the DMZ to the main network, limiting the source to the MAC address of the server and the destination to the MAC address of the required destination workstation. 

Experience has shown that some image acquisition sites are unable to allow outbound connections on all ports. If any of the sites in the trial fall into that category, they will have to transmit to port 8080 and it will therefore be necessary to open that port to the internet on the principal investigator's site as well. (MIRC is designed not to require opening any ports for inbound connections at the image acquisition sites.)

Some trials have used virtual private networks for security. This requires more support during installation at the image acquisition sites than is usually available, but it has been shown to work.

===Create Update Service directories for the trial===
The Update Service allows the trial administrator at the principal investigator site to manage the key data files used at all the image acquisition sites. These are:
* the DICOM anonymizer script file (<b>dicom-anonymizer.properties</b>)
* the XML anonymizer script file (<b>xml-anonymizer.script</b>)
* the lookup table (<b>lookup-table.properties</b>)
* the <b>FieldCenter</b> program and its related sofware libraries

If the Update Service is enabled in the FieldCenter application at an image acquisition site, it checks the Update Service at the principal investigator site whenever it needs a configuration file (either of the anonymizer scripts or the lookup table). If the version on the principal investigator site is newer than the one on the local site, it is downloaded. This allows the trial administrator to provide configuration expertise for all the image acquisition sites without imposing on the IT staff in the field. Likewise, the sites in the field automatically update the principal investigator site whenever a local change is made to the configuration files.

The use of the Update Service is recommended not only because it simplifies the inevitable configuration work but also because it provides a backup of the key files from the field and allows the administrator to know exactly what is going on at all the sites.

To set up the Update Service, first create a user account for each image acquisition site and give it a special role name that you created when you installed the storage service. For example, if you chose the designator <b>XYZ</b>, you must give each user the <b>XYZ-update</b> role. This can be done through the User Role Manager, which is described in the [[MIRC Administrator's Manual]].

Next, go to the <b>Tomcat/webapps/[StorageServiceName]/trial</b> directory and create one directory for each site, plus one directory called <b>software</b>. In the end, the directory tree will look something like this:
*trial
**update
***software
***site1
***site2
***site3
where <b>site1</b>, <b>site2</b>, <b>site3</b>, etc. are replaced by the user names that you created for the sites.

In the software directory, you will place the FieldCenter files, once they have been created as described below.

In each site's directory, you will place the anonymizer files. Most trials do not use the XML anonymizer, and if yours does not, you will not have that file. Similarly, most trials do not use lookup tables for special remapping, and if yours does not, it will not be present as well.

===Configure the DICOM Service===
===Create the template.xml file===
When files are received from image acquisition sites, the DICOM Service automatically creates MIRCdocuments, grouping the objects by <b>Study Instance UID</b>. The MIRCdocuments are created from the <b>template.xml</b> file which is located in the storage service's <b>trial</b> directory. Templates are described in the [[MIRC Templates]] article. More detail on the elements in a template can be found in [[The MIRCdocument Schema]].

The MIRC software includes an [[MIRC_Templates#DICOM_Service_Templates | example DICOM Service template]] which can serve as a starting point for creating the template for the trial. Careful consideration should be given to all the sections in the template. The example DICOM tempate is not intended to be appropriate for any trial; it is intended only to provide examples of the kinds of data that can be made available in the MIRCdocument. The template should be carefully designed before the trial begins so that all the documents created for the trial are consistent. Special consideration should be given to several items:
* If the anonymization rules permit PHI to be contained in the images and/or the MIRCdocuments that reference them, then the template should contain the [[The_MIRCdocument_Schema#phi | <b>phi</b> element]] as in this example:
<pre>
<phi>
    <study>
        <si-uid><g0020e000D desc="Study Instance UID"/></si-uid>
        <pt-id><g0010e0020 desc="Patient ID"/></pt-id>
        <pt-name><g0010e0010 desc="Patient Name"/></pt-name>
    </study>
</phi>
</pre>
* The <b>authorization</b> element should be preconfigured to restrict access to the document to those users who have the proper roles. If the unique designator for the trial is <b>XYZ</b> and the trial administrator's user name is <b>jsmith</b>, an example of an <b>authorization</b> element would be:
<pre>
<authorization>
    <owner>jsmith</owner>
    <read>XYZ-user</read>
    <update>XYZ-author</update>
    <export>XYZ-user</export>
</authorization>
</pre>
* To enable MIRC's special export features for DICOM objects, it is best to specify the value of the <b>document-type</b> element as <b>research dataset</b> as shown in the [[MIRC_Templates#DICOM_Service_Templates | example DICOM Service template]].

===Decide on the anonymization requirements===
* remapping issues
* patient name issues
* ptid issues - remapping vs external assignment
* examples section of the anonymizer document
===Build the FieldCenter application for the trial===
* properties file - preset for the update service, destination url
===Install FieldCenter at the imaging sites===
* testing - HttpTest / proxy server issues
===Operation===
* Decipher

==The DICOM Service==
===The DICOM Import Service===
===The HTTP Import Service===
===The DICOM Export Service===
===The HTTP Export Service===
===The Database Export Service===
==The Update Service==
==The FieldCenter Application==
==The Clinical Trial Template File==