MIRC Administrator's Manual

This article describes the administration of a MIRC site running the RSNA MIRC implementation, with the exception of those features specifically used by clinical trials, which are described in a separate article.

The RSNA MIRC implementation is based on the Apache Tomcat servlet container. A servlet container can be thought of as a web server that knows how to run Java programs called servlets. A group of related servlets is called a webapp. The RSNA MIRC implementation is essentially a collection of webapps, one for the query service, one for each storage service installed on the server, one for a file service, and one for server-level administration functions.

1 Installation

The current official release version is T28. Installation instructions can be found at http://mirc.rsna.org/mircstorage/documents/T28/MIRCdocument.xml.

The current beta version of T29, which is recommended for all users, can be downloaded at http://mirc.rsna.org/T29/MIRCsite-installer.jar. To upgrade, follow the T27 installation instructions, but use the T29 installer for the MIRC software part of the installation.

2 Query Service Administration

2.1 System-level Modes

There are two operating modes which cannot be changed during operation of the system:

• the system mode
• the addressing mode

Both modes are defined in the Query Service's configuration file, which is located in Tomcat/webapps/mirc/mirc.xml. At the top of the file is a DOCTYPE declaration containing several entities:

<!DOCTYPE mirc [
    <!ENTITY mode "rad">
    <!ENTITY sitename "P4">
    <!ENTITY addresstype "dynamic">
    <!ENTITY siteurl "http://192.168.0.96:8080">
    <!ENTITY queryurl "&siteurl;/mirc">
    <!ENTITY storageurl "&siteurl;/mircstorage">
    <!ENTITY mircforum "http://forums.rsna.org/forumdisplay.php?forumid=9">
    <!ENTITY mircdocs "http://mircwiki.rsna.org">
    <!ENTITY radlex "http://mirc.rsna.org/radlex/service">
    <!ENTITY tcusersclass "org.rsna.mircsite.util.TomcatUsersXmlFileImpl">
    <!ENTITY acctenb "yes">
    <!ENTITY defroles "QS-user,FS-user,SS-user,SS-author">
    <!ENTITY gpenb "yes">
    <!ENTITY version "T29alpha"> ]>

2.1.1 Setting the System Mode

The system mode is defined by the mode entity. The currently supported modes are:

• rad: radiology
• vet: veterinary medicine

The choice of system mode configures the enumerated values for sexes, races, species, and breeds. These parameters, among many others, are stored in Tomcat/webapps/mirc/enumerated-values.xml.

The software is preconfigured for rad mode. To change to vet mode, it is necessary to edit the mirc.xml file with a text editor and change the value of the mode entity.

If operating in vet mode and the list of species provided in that file does not match those seen at your institution, you can change the values by editing the enumerated-values.xml file. You can also add or change the enumerated values of other elements as well, but you should recognize that changes that you make to your site are only known to your site, and if you want to participate in a larger community, queries for unique enumerated values are unlikely to be successful outside your site.

2.1.2 Setting the Addressing Mode

The IP address for a MIRC site can be chosen when the MIRC software is initially installed. The installer does not provide an option to change the address or the means by which it is obtained when the software is upgraded. When a server is moved on the network, it may be necessary to reconfigure the IP address after installation.

2.1.2.1 Dynamic vs. Static IP Addressing

The MIRC software must know its IP address in order to handle queries and document accesses properly. The Query Service configuration file contains two parameters which together determine either the IP address itself or the way the address is obtained. In no case does the value of the IP address actually affect the IP address of the host machine; it only affects the IP addresses used for communication between services on the site and those returned to users in query results.

The way the MIRC software obtains the IP address is determined by the addresstype entity. The entity can have two possible values, dynamic or static. If the value is dynamic, the software obtains the IP address from the operating system when Tomcat starts. In most cases, this is the preferred method, whether the host computer has a fixed IP address or obtains its address from a DHCP server. If the host system contains multiple network adapters, however, the service may not obtain the address of the desired adapter, so static addressing is required.

If the value of the addresstype entity is static, the software obtains the IP address from the siteurl entity. The siteurl entity can contain a numeric IP address or a domain name address.

If dynamic addressing is used, the IP address specified in the siteurl entity must be numeric; otherwise, the method which obtains the IP address from the operating system will refuse to overwrite it.

During the initial installation, the installer asks the administrator to choose the type of addressing. During upgrades, however, there is no option to change it.

2.1.2.2 Reconfiguring the IP Address

To change the IP addressing method after installation of the system, change the value of the addresstype entity using a text editor. If static addressing is employed, put the static IP address of the host in the value of the siteurl entity.

Important: The protocol and port fields in the siteurl entity are always used, even in the case of dynamic addressing, so they must be set correctly in all cases.

If an alphabetic value is inserted in the IP address field of the siteurl entity, the system will use that value for addressing and not obtain an IP address from the operating system, even if dynamic addressing is selected.

2.1.3 Restarting the System

After changing the system mode or the addressing mode, it is necessary to restart Tomcat in order to force the init methods of the MIRC servlets to run and reload the new enumerated values and/or IP address.

2.2 Setting the Authentication Requirements

The Query Service receives connections on two URLs:

• [siteurl]/mirc/auth authenticates the user (forces a challenge for the user's credentials).
• [siteurl]/mirc/query does not authenticate the user.

To authenticate yourself to the query service, you must log in to the Tomcat instance running the Query Service. This can be done by accessing the query page on the /query/auth URL or by clicking the Login button on the query page.

To be authenticated on the query service, you must have the QS-user role. When you upgrade, the installer will offer to add that role to the admin account, but for other users, you will have to add it manually with the User Role Manager.

If you use a redirector in the Tomcat/webapps/ROOT directory to point to the Query Service, and if you want to force authentication when users go to that URL, you have to edit the index.html page and change the URL in the redirection element.

When the query service receives a query request, it determines whether the user is authenticated. If the user is authenticated, then when it submits the query to a storage service it passes the user's credentials (name and password) on that storage service as part of the query. This allows the storage service to determine which query results to return. The query service obtains the credentials from an object called a passport. A passport is managed by the passport's owner (the user) via the User Account Manager. A passport consists of a collection of visas, one for each server known to the query service. This allows a user of one query service to manage his credentials for many storage services - even ones on other servers - in one place.

When the query service sends a query to a storage service, it only includes credentials if the user has created a visa for the destination server; otherwise, the query is submitted with no credentials and the storage service behaves as if the user is not authenticated. The behavior of a storage service in response to a query depends on the mode in which the storage service is operated. The possible modes are described below.

2.3 The Case of the Day

The Case of the Day feature is provided by the Query Service as a separate collection of news servlets in the webapp. To make a MIRCdocument the Case of the Day, log in as an administrator and view the document normally, then click the Case of the Day button in the table at the bottom of the document (or at the bottom of the Document tab).

The news servlets maintain a list of the last 10 documents identified as the Case of the Day. This list is available through the RSS feed which is part of the news system.

The latest Case of the Day can always be accessed by clicking the image in the lower left corner of the query page.

2.4 Customization

The mirc.xml file can be customized to provide a unique header, footer, and disclaimer for the query page. Three elements are provided. Their contents must be well-formed HTML.

• The pageheader element can be be used to display the institution's logo, special instructions, or any other desired information at the top of the query page.
• The pagefooter element can be replaced with any well-formed HTML to display contents at the bottom of the query page. The default contents of the pagefooter element display the version of the MIRC site software.
• The disclaimer element can be used to display additional contents, typically a legal disclaimer, at the lower left of the query page.

The contents of the pageheader, pagefooter, and disclaimer elements are preserved during an upgrade.

2.5 Adding Storage Services to the List

Additional storage services can be added to the list on the query page by adding server elements to the mirc.xml file. Storage services are added near the bottom of the file as in this example, which shows one local storage service, plus the RSNA site:

  <server address="&siteurl;/storage/service">
    P4 Storage Service
  </server>
  <server address="http://mirc.rsna.org/mircstorage/service">
    The RSNA MIRC Site
  </server>

By convention, each server element consists of three lines, the server tag, the storage service name, and the end tag. All server elements must be well-formed XML. The address attribute must be a fully-qualified URL pointing to the storage service. The text value of the element is the name displayed in the storage service list on the query page.

The first server element is automatically selected when the query page is loaded. It is typically the primary storage service on the same site as the query service. The RSNA site is typically the second storage service in the list, but the administrator has complete control over the order and contents of the list.

3 Controlling Users and Groups

Starting with Release T29, MIRC includes a User Account Manager that, when enabled by the administrator on the Query Service Admin page, allows users to create groups (and even accounts).

3.1 User Accounts

To gain access to more than the basic MIRC features, a user must have an account on the MIRC site. An account consists of a username and a password plus a list of permissions, which are called roles. Certain features require that the user possess a specific role related to the feature. For example:

• To be authenticated on a MIRC Storage Service, the user must possess the Storage Service's user role.
• To be allowed to submit a document to a MIRC Storage Service's Submit Service or Zip Service, the user must possess the Storage Service's author role.
• To be allowed to create a document on a MIRC Storage Service's Author Service, the user must possess the Storage Service's author role.
• To be allowed to make a document public on a MIRC Storage Service, the user must possess the Storage Service's publisher role.
• To be allowed to access a MIRC site's File Service, the user must possess the File Service's user role. (This is a separate role from the one for a Storage Service.)

Roles are granted to users by the MIRC site administrator.

3.2 Groups

Groups are implemented as Tomcat roles, but users can think of them as special groups of users. Groups are created by users via the User Account Manager.

The idea behind groups is that a user creates a group with a name and password and then tells the name and password to the people that he wants to join. They then go to their individual User Account Managers and join the group by entering the name and password in the proper fields.

When a user authors a document which he wants group members to be able to view, he sets the read permission to include the group name. The group name can also be used to grant the group edit and export privileges on the document.

3.3 The User Role Manager

The User Role Manager, which can only be accessed by an administrator, has been changed so that it only manages:

• the creation of new users
• the removal of old users
• the administrative roles

Administrative roles are those that confer access to servlets or to MIRC behavior (like the publisher role and the various admin roles for Storage Services and the File Service).

3.4 The User Account Manager

The behavior of the User Account Manager depends on the mode of the Query Service, on whether or not the user is authenticated, and on whether the user is a Tomcat administrator (admin).

To manage account and group creation, go to the query page, click the Login button and log in to an admin account. Then click the My Account button. The resulting page will contain several sections, each described by a little text telling you what to do. You can:

• change your password on the server;
• create visas for yourself;
• resign from any or all groups;
• join a group (if you know its name and password);
• create a group, giving it a name and a password;
• control whether account creation and/or group creation are enabled on the site;
• define the administrative roles that are granted to users who create their own accounts.

The last two items are only displayed if the user is a Tomcat administrator. Other items are displayed if the system is configured to allow them to be used.

If you enable account creation, you allow non-authenticated users to create accounts on your system. You should carefully consider whether you want to do that. If you enable account creation, you must specify the administrative roles that new accounts are to be granted when they are created. Users don't have control over these roles. A typical set of roles on a site which allows users to view and author documents on one of the storage services would be the user and author roles for the File Service and the Storage Service to which you want to restrict the user (typically QS-user, FS-user, SS-user and SS-author). If you want to have a separate Storage Service for users who create their own accounts, then when you install the Storage Service, you should give it a unique prefix, for example XX, and then set the administrative roles for new users to be QS-user, FS-user, XX-user and XX-author. Note that since there is only one Query Service and one File Service on a MIRC site, you will always assign the QS-user and FS-user roles, no matter what the prefix is for the storage service.

Group creation is independent of account creation and is separately enabled. Thus, you can disable account creation while still allowing group creation.

Visas are not automatically created. You must use the User Account Manager to create the ones you want. The User Account Manager does, however, preset the values for the storage services on the same server as the query service, so the first time you go to the User Account Manager and click the Submit button, the visa for those services will be created.

4 Storage Service Administration

4.1 The storage.xml File

Each storage service is a separate web application (webapp). The principal configuration parameters are contained in the storage.xml file, which is located in the root directory of the storage service (Tomcat/webapps/[SSName], where [SSName] is the one-word name that you chose for the storage service when you installed it).

At the top of the file is a DOCTYPE declaration similar to the one at the top of the mirc.xml file:

<!DOCTYPE storage [
   <!ENTITY siteurl         "http://192.168.0.98:8080">
   <!ENTITY servletname     "mircstorage">
   <!ENTITY docauthoring    "yes">
   <!ENTITY authorindex     "yes">
   <!ENTITY docsubmission   "yes">
   <!ENTITY maxsize         "100">
   <!ENTITY autoindex       "yes">
   <!ENTITY zipsubmission   "yes">
   <!ENTITY zipmaxsize      "100">
   <!ENTITY zipautoindex    "yes">
   <!ENTITY philog          "yes">
   <!ENTITY philogexport    "no">
   <!ENTITY philogexporturl "">
   <!ENTITY dicomenable     "no">
   <!ENTITY tceenable       "no">
   <!ENTITY tagline         "">
   <!ENTITY sitename        "Storage Service">
   <!ENTITY querymode	    "open">
   <!ENTITY version         "00"> ]>

With the exception of siteurl and servletname, all the entities can be changed using the Storage Service Configurator.

To change the IP addressing mode, it is necessary to edit the file with a normal text editor and change the value of the siteurl entity as described in the Query Service section.

You should not change the value of the servletname entity unless you are under the care of a software engineer.

With the exception of the Author Service templates, described below, you should not change the text of the rest of the file.

4.2 The siteindex.xml File

The storage service maintains a list of its active documents in a file described in a separate article. When the Storage Service starts, it builds an index from the contents of the documents listed in this file.

See also Data Mining the MIRC Index.

4.3 The MIRCdocument.xsl and MIRCdocument.css Files

The MIRCdocument.xsl file is an XSL program that renders MIRCdocuments as HTML when a user requests the document. The mechanism of XSL transformation used by the MIRC XML Server is described in Data Mining the MIRC Index. The MIRCdocument.xsl file can be slightly customized, but any changes made to it are lost during an upgrade, so it is important to keep a copy of any modifications.

One customizable feature is the presentation of the buttons generated by text-caption elements. The default is to generate plain text buttons for Next, Previous, Show Caption, and Hide Caption. The program can, if desired, use images for the buttons. This is controlled by the param name="input-type" element near the top of the MIRCdocument.xsl file. The allowed values are:

• button - use plain text buttons
• image - use the following images from the storage service's buttons directory:
  • back.png
  • showcaption.png
  • hidecaption.png
  • forward.png

A default set of images is provided in the software. If you overwrite these images with your own, they will be lost during an upgrade.

The MIRCdocument.css file contains styles used by MIRCdocument.xsl. Typical customizations of this file are:

• changing background colors
• changing the spacing of paragraphs

Changes to this file are also lost during an upgrade.

4.4 The Admin Service

Each Storage Service has a separate Admin Service which is used to control all its subordinate services. The Admin Service is accessed by selecting the Storage Service in the list on the query page and clicking the Admin Service button. The resulting page contains a set of buttons as shown below, and an area in which various functions display their results.

Error creating thumbnail: Unable to save thumbnail to destination

The following is a brief summary of the buttons' functions:

• Left Column
  • Status - displays the key parameter settings
  • List Input Queue - displays the list of documents that have been requested to be made public by users who do not have the publisher role. Documents only enter the queue if autoindexing is not enabled on the Storage Service.
  • File Service Admin - a convenience link to the Admin Service of the File Service.
• Storage Service Column
  • Update Configuration - links to the Storage Service Configurator, providing access to most of the Storage Service configuration parameters.
  • List Index - lists the documents currently in the index, with links allowing them to be viewed, deleted, or edited.
  • Reload Index - forces the Storage Service to reload its index from the siteindex.xml file.
  • Rebuild Index - creates a new siteindex.xml file by walking the directory tree under the documents directory and finding all the MIRCdocuments.
  • Save Index - saves the current index in saved-index-file.xml in the root directory of the Storage Service.
• TCE Service Column
  • Update Configuration - links to the TCE Service Configurator, providing access to its DICOM Service parameters.
  • Start/Restart - starts the TCE Service's DICOM Service.
  • Show Log - displays the Storage Service's circular buffer of log entries from all its DICOM Services.
  • Clear Log - clears the circular log buffer.
• DICOM Service Column
  • Update Configuration - links to the DICOM Service Configurator, providing access to the parameters used in clinical trials.
  • Start/Restart - starts the DICOM Service.
  • Show Log - displays the Storage Service's circular buffer of log entries from all its DICOM Services. This button does the same thing as the corresponding button in the TCE Service column.
  • Clear Log - clears the circular log buffer. This button does the same thing as the corresponding button in the TCE Service column.
• Tomcat Column
  • User Role Manager - a convenience link to the MIRC User Role Manager servlet.
  • Controller - a convenience link to the MIRC Controller servlet.
  • Log Viewer - a convenience link to the Log Viewer servlet.

Error creating thumbnail: Unable to save thumbnail to destination

4.4.1 The Storage Service Configurator

The Storage Service is configured using the Storage Service Configurator. To display the configurator, click the Update Configuration button in the Storage Service column. Configuration changes do not become effective until you click the Update storage.xml button at the bottom of the page.

Most of the parameters in the configurator are discussed in sections related to the services to which they apply. The others are discussed below.

4.4.1.1 Query Mode

The storage service can be configured to operate in one of two query modes:

• open sets the service to return all results that match a query, regardless of whether the user is authorized to see the documents themselves. This is the default mode.
• restricted sets the service to return only those results that match a query and for which the user is authorized to view the documents.

In restricted mode, if a user is not authenticated in the query, the storage service only returns results for public documents.

4.4.1.2 Site Name

The Site Name field contains the name of the Storage Service that is displayed on the various admin pages. This field does not affect the name that is displayed on the query page.

4.4.1.3 Tag Line

The Tag Line is the text that is displayed under the name of the Storage Service in the list of query results.

4.4.1.4 Deleted Documents Timeout

When a document is deleted from the Storage Service's documents directory, the entire subdirectory for the document is moved to the deleted-documents directory. To simplify the management of the deleted-documents directory, the Storage Service has a garbage collector that automatically removes subdirectories older than a specified age. Set the timeout in the Deleted Documents Timeout (days) field. A typical value is 14 days. If the timeout is set to zero, the garbage collector is disabled and files remain in the deleted-documents directory until they are manually deleted. The garbage collector runs when the server starts and once a day thereafter.

The easiest way to recover a document that has been deleted is to manually drag its subfolder from the deleted-documents directory back to the documents directory and then click the Rebuild Index button on the storage service's admin page.

4.4.1.5 JPEG Quality Setting

When an image is added to a MIRCdocument, a browser-viewable JPEG image is created, if necessary, for presentation when the document is viewed. The JPEG Quality Setting parameter defines the degree of compression and therefore the quality of the resulting image. A setting of 100 produces an image with no quality loss. A typical good-quality setting is about 75. A low value produces high compression and relatively low quality. Between a setting 25 and 90, the file size for a typical MR image approximately triples. A negative quality setting causes the system to use the default quality parameter built into the Sun JPEGImageEncoder.

4.4.1.6 PHI Logging

Storage Services have the ability to log accesses to MIRCdocuments that contain protected health information. Two kinds of logging are supported:

• PHI Access Log Enabled determines whether the Storage Service logs PHI accesses in a local log file contained in the access-logs subdirectory of the root of the Storage Service. This log is a simple text file.
• PHI Access Log Export Enabled determines whether the Storage Service logs PHI accesses to an external logging system on the network. The log message is transmitted as an XML string to a URL identified by the PHI Access Log Export URL field.

4.5 Author Service

The Author Service allows users to create and store MIRCdocuments through their browsers. Each Storage Service has its own Author Service. The Author Service is configured using the Storage Service Configurator. To display the configurator, click the Update Configuration button in the Storage Service column. Configuration changes do not become effective until you click the Update storage.xml button at the bottom of the page.

You can control whether the Author Service is enabled on the Storage Service. To set the enable field, select yes in the Author Service Enabled field.

You can also control whether documents created by the Author Service are automatically indexed.

• If autoindexing is enabled, all documents, whether public or private, that are created by the Author Service are indexed without modification.
• If autoindexing is not enabled, only documents submitted by users with the publisher role are indexed without modification. All other documents, if public, are made private before indexing. This prevents users who are not authorized to publish documents from doing so.

Most sites do not operate in autoindexing mode. To set the autoindexing mode, select yes in the Author Service Autoindex field.

4.5.1 Author Service Templates

The Author Service uses template files to provide starting points for users to begin authoring new MIRCdocuments. A set of standard templates is included with the software release. These are overwritten when the software is upgraded, so you should not modify them. You may create templates to meet your own requirements as described in MIRC Templates.

Author Service templates are stored in the storage service's templates directory These templates must be made known to the system before users can access them. To do so, edit the storage.xml file with a text editor and look for the part of the file containing the current templates. Each template is represented by three lines in the form:

    <template name="templates/doc-template-mstf2.xml">
      Simple Teaching File Template
    </template>

The name attribute contains the path from the root directory of the storage service to the template file. The text value of the element is the name of the template that is displayed for the user in the selection box on the Author Service's welcome page. To add new template to the list, add the element for the new template anywhere in the list, making sure not to insert it in the middle of another template element. After making such a change, you should open the file with a validating browser like Internet Explorer to verify that the file is well-formed. If you create a non-well-formed file, all storage service functions will stop working.

4.6 New Document Service

The New Document Service is a special author service for the creation of a new document which may be shared with any groups of which the user is a member. Documents created by the New Document Service may be edited by the standard Author Service.

Each Storage Service has its own New Document Service. The New Document Service allows the user to include files from the client computer in the new document that is created. The New Document Service shares configuration parameters with the Author Service and the Submit Service:

• The New Document Service is enabled by enabling the Author Service as described above.
• The maximum submission size allowed is the same as that set for the Submit Service as described below.

The New Document Service has its own template.xml file that controls the format of the document that is created from the form submitted by the user. The file is located in the Tomcat/webapps/[storageservice]/newdoc directory. For more information about templates, see MIRC Templates.

4.7 Submit Service

The Submit Service receives zip files containing MIRCdocuments and their locally referenced files and stores them. Each Storage Service has its own Submit Service. The Submit Service is configured using the Storage Service Configurator. To display the configurator, click the Update Configuration button in the Storage Service column. Configuration changes do not become effective until you click the Update storage.xml button at the bottom of the page.

You can control whether the Submit Service is enabled on the Storage Service. To set the enable field, select yes in the Submit Service Enabled field.

You can also control whether documents created by the Submit Service are automatically indexed.

• If autoindexing is enabled, all documents, whether public or private, that are received by the Submit Service are indexed without modification.
• If autoindexing is not enabled, only documents submitted by users with the publisher role are indexed without modification. All other documents, if public, are made private before indexing. This prevents users who are not authorized to publish documents from doing so.

Most personal sites operate in autoindexing mode; most shared sites do not. To set the autoindexing mode, select yes in the Submit Service Autoindex field.

You can also control the maximum size of any submission. On initial installation, the default is set to 100MB. To change the size, edit the Maximum Submission Size (MB) field.

4.8 Zip Service

The Zip Service is a special kind of Submit Service that receives zip files containing collections of files and produces MIRCdocuments from their contents. Each Storage Service has its own Zip Service. On initial installation, the Zip Service includes a default template which is located in Tomcat/webapps/[storageservice]/submit/template.xml. If you wish to adapt the default template for your site, you can edit that file with any text editor. See MIRC Templates for information on templates.

The Zip Service is configured using the Storage Service Configurator. To display the configurator, click the Update Configuration button in the Storage Service column. Configuration changes do not become effective until you click the Update storage.xml button at the bottom of the page.

You can control whether the Zip Service is enabled on the Storage Service. To set the enable field, select yes in the Zip Service Enabled field.

You can also control whether documents created by the Zip Service are automatically indexed.

• If autoindexing is enabled, all documents, whether public or private, that are created by the Zip Service are indexed without modification.
• If autoindexing is not enabled, only documents submitted by users with the publisher role are indexed without modification. All other documents, if public, are made private before indexing. This prevents users who are not authorized to publish documents from doing so.

Most personal sites operate in autoindexing mode; most shared sites do not. To set the autoindexing mode, select yes in the Zip Service Autoindex field.

See The Zip Service User's Manual for more information.

4.9 TCE Service

Error creating thumbnail: Unable to save thumbnail to destination

The TCE Service is a special kind of Submit Service that receives DICOM transfers in accordance with the IHE Teaching Files and Clinical Trials Export (TCE) Integration Profile and produces MIRCdocuments. Each Storage Service has its own TCE Service. On initial installation, it includes a template which is located in Tomcat/webapps/[storageservice]/tce/template.xml. If you wish to adapt the default template for your site, you can edit that file with any text editor. See MIRC Templates for information on templates.

The TCE Service is configured using the Storage Service Configurator. To display the configurator, click the Update Configuration button in the Storage Service column. Configuration changes do not become effective until you click the Update storage.xml button at the bottom of the page.

You can control whether the TCE Service is enabled on the Storage Service. To set the enable field, select yes in the TCE Service Enabled field.

The TCE Service implements the IHE TCE Export Receiver actor. As described in the IHE TCE Integration Profile, it receives objects from the IHE TCE Export Manager actor. The RSNA MIRC project has implemented an open-source TCE Export Manager in a separate development. See The MIRC TCE Export Manager for more information.

The TCE Service contains its own DICOM Service for receiving transmissions from the Export Manager. You can control the DICOM parameters using the TCE Service Configurator, which is accessed by clicking the Update Configuration button in the TCE Service column on the Storage Service's admin page:

• autostart - determines whether the service is automatically started when Tomcat starts.
• Store AE Title - sets the application entity title for the TCE Service's DICOM Service. It should be unique in the entire MIRC environment.
• Store Port - sets the port on which the DICOM Service listens for associations.

Changes to these parameters are not recorded until the Update tce.xml button is clicked.

To start the DICOM Service, or to restart it after changes have been made to its parameters, you must click the Start/Restart button in the TCE Service column on the admin page.

4.10 DICOM Service

The DICOM Service is a collection of subcomponents that are intended for use in clinical trials. It includes an automatic MIRCdocument generator that groups DICOM objects into documents on the basis of their Stydy Instance UIDs. This DICOM Service is separate from the ones in the File Service and the TCE Service.

Some sites use the DICOM Service as a simple kind of TCE Service for teaching file applications. While this has worked satisfactorily, it is better to use the TCE Service for this purpose if your PACS supports the IHE TCE Integration Profile as an Export Selector or Export Manager.

For complete documentation on the DICOM Service, see the Clinical Trial Administrator's Manual.

5 File Service Administration

This section describes how to configure the File Service. The File Service provides personal file cabinets and a shared file cabinet that has a DICOM Storage SCP for receiving DICOM objects from modalities, workstations, and PACS.

5.1 Controlling Access to the File Service

Each authenticated user who has the FS-user role is provided a personal file cabinet which only that user can access. In addition, all authenticated users with the FS-user role can access the shared file cabinet. Only users with the FS-admin role can access the File Service Admin page and configure the File Service.

5.2 Accessing the File Service Admin Page

To access the admin service, go to the query page for the site, select the Storage Service in the list at the top of the query pane, and click the Admin Service button on the right side of the window.

On the Admin page, click the File Service Admin button. The result will be a page as shown below.

Error creating thumbnail: Unable to save thumbnail to destination

5.3 Configuring the DICOM Service

The File Service has its own DICOM Service which receives DICOM objects, optionally anonymizes them, and places them in the shared file cabinet.

To change the Application Entity Title or port of the DICOM SCP, change the values on the Admin page. These values must not conflict with those of other DICOM SCPs running on the MIRC site. Each Storage Service also has a DICOM SCP. The default values provided with the installation do not collide with one another, but if you make changes or if you have multiple Storage Services running on the system, care is necessary. The AE Title and port for each Storage Service’s DICOM Service is shown on the Storage Service’s admin page.

If you want the DICOM Service to start automatically when the MIRC site is initialized, select yes in the Autostart field.

After changing the configuration of the DICOM Service, you must first click the Update fileservice.xml button to save the changes, and then click the Start/restart the DICOM Service button to make the DICOM Service recognize them.

5.4 Configuring the Anonymizer

The DICOM Service has its own copy of the MIRC Anonymizer and its own copy of the anonymization scripts. This allows each DICOM Service to anonymize according to its own specific rules. The Anonymizer Configurator is accessed by clicking the Update the Anonymizer button. The configuration and operation of the Anonymizer Configurator is described in a separate article.

To enable the anonymizer, select yes in the Anonymizer Enabled field.

Important Note: If the anonymizer is not enabled, DICOM objects will be placed in the shared file cabinet without modification. Accesses to objects in the shared file cabinet are not logged because it is not possible to know whether an object in a file cabinet contains PHI (since it may have been anonymized before it was sent). The scripts provided with the standard installation anonymize an image in a reasonable and practical way, but some institutions have more stringent rules than others, and it is prudent to review the scripts to ensure that they meet your requirements.

5.5 Configuring the Garbage Collector

To simplify the management of the shared file cabinet, the File Service has a garbage collector that automatically removes files older than a specified age. Set the timeout in the Shared File Cabinet Timeout (hours) field. A typical value is 48 hours. If the timeout is set to zero, the garbage collector is disabled and files remain in the shared file cabinet until they are manually deleted. The garbage collector runs when the server starts and once an hour thereafter.

5.6 Saving Configuration Changes

To save the changes you have made to the configuration, click the Update fileservice.xml button. Changes do not become effective until they are saved.

Anonymizer script changes are saved on the Anonymizer Configurator and do not require a separate button click on the Admin page.

5.7 Starting the DICOM Service

If the Autostart field contains yes, the DICOM Service is started when Tomcat starts and the MIRC site is initialized. If the Autostart field does not contain yes, you can start the DICOM Service by clicking the Start/Restart the DICOM Service button.

Caution: Whenever you make changes to the DICOM Service configuration, you must save those changes by clicking the Update fileservice.xml button before you start or restart the DICOM Service; otherwise, the changes will be lost. If you change the AE Title or port, you must restart the DICOM Service after saving the changes to cause the SCP to reload its parameters.

5.8 Managing the Shared File Cabinet

Users who do not possess the FS-admin role are allowed to delete any files in their personal file cabinet, but only those files in the shared file cabinet that they added to it. Users who possess the FS-admin role can any delete files from the shared file cabinet.

The DICOM service does not assign an owner to the files it places in the shared file cabinet. Thus, only the administrator or the garbage collector can delete those files.

5.9 Limiting Uploaded File Types

MIRC sites that are open to the public are subject to attacks if malicious files are uploaded as part of submitted documents. MIRC provides a mechanism to limit the file extensions which it accepts in uploads through the Submit Service, the New Document Service, the Zip Service, and the File Service. This feature is disabled when the system is initially installed.

This feature can be enabled by creating a file named FileTypes.properties in the Tomcat/shared/classes directory. In this file, list the extensions of all the files which are to be accepted. Each file extension must begin with a period. Note: Tomcat must be restarted after changes are made to this file.

If this feature is enabled, at least the following extensiions should be included in the FileTypes.properties file:

• .avi
• .dcm
• .gif
• .jpg
• .jpeg
• .mp3
• .mpeg
• .png
• .tif
• .tiff
• .xml
• .zip

6 System-Level Services

There are several system-level servlets that are a convenience for administrators. They can be accessed through the admin page of any Storage Service.

6.1 Log Viewer

The Log Viewer provides browser access to the log files in Tomcat/logs. Only log files with non-zero sizes are listed, and the listing is in reverse chronological order, making it easy to find current logs.

6.2 Controller

The Controller is a servlet that lists key system parameters and provides access to logging levels and garbage collector parameters. Generally, it is not necessary to change any parameter, but it can be useful in tracing error conditions and memory limitations.

7 Appendix: MIRC URL Index

This section indexes all the URLs recognized by a MIRC site. In the listing below, the following notations are used:

• All URLs are assumed to begin with the value of the siteurl entity in the query service's mirc.xml file. For brevity, this part of the URL is not shown.
• [SSName] refers to the name of a storage service.
• [path] refers to a path.
• [filename] refers to the name of a file.
• [username] refers to the account name for a user.
• [text] refers to any text.
• [n] refers to a numeric value.
• Text not in square brackets is a fixed part of the URL.

7.1 Query Service URLs

• /mirc/query - the non-authenticated query service
• /mirc/auth - the authenticated query service
• /mirc/news - get the current news item (Case of the Day)
• /mirc/news/add?link=...&title=...&description=...&image=... - add an item to the news listing
• /mirc/news/remove?link=... - remove an item from the news listing
• /mirc/news/listing - get HTML code referencing the current news item (for inclusion on a web page)
• /mirc/news/news.rss - the RSS news feed

7.2 Storage Service URLs

• /[SSName]/storage/service - query.
• /[SSName]/submit/doc - submit a MIRCdocument to the Submit Service.
• /[SSName]/submit/zip - submit a zip file to the Zip Service.

• /[SSName]/import/doc - submit a file to the HTTP Import Service (POST).
• /[SSName]/import/ping - request a response from the Http Import Service (POST).
• /[SSName]/update/sw/[filename]?lastModified=[n] - retrieve a file from the software distribution directory in the Update Service (GET).
• /[SSName]/update/[filename]?lastModified=[n] - retrieve a file from the user's account in the Update Service (GET).
• /[SSName]/update/[filename]?lastModified=[n] - store a file in the user's account in the Update Service (POST).
• /[SSName]/remap - central remapper request.

• /[SSName]/author/publish?doc=[path]/[filename] - make a document public.
• /[SSName]/author/delete?doc=[path]/[filename] - delete a document.
• /[SSName]/author/service - get the template selection form (GET).
• /[SSName]/author/service - submit the template selection form (POST).
• /[SSName]/author/submit?docname=[path]/[filename]&doctext=[text]&activetab=[n] - submit a new document.
• /[SSName]/author/submit?docname=[path]/[filename]&doctext=[text]&activetab=[n] - update an existing document (POST).
• /[SSName]/author/update?doc=[path]/[filename] - open an existing document for editing (GET).

• /[SSName]/newdoc - get the New Document creation form (GET).
• /[SSName]/newdoc - create a New Document (POST).

• /[SSName]/admin/service - the Admin Service page.
• /[SSName]/admin/service?rebuild - rebuild the index.
• /[SSName]/admin/service?listindex - list the index.
• /[SSName]/admin/service?listqueue - list the input queue.
• /[SSName]/admin/service?deleteindexentry-[path]/[filename] - delete a document.
• /[SSName]/admin/service?acceptqueueentry=[path]/[filename] - index a document that is in the input queue.
• /[SSName]/admin/service?publishqueueentry=[path]/[filename] - publish a document that is in the input queue.
• /[SSName]/admin/service?start - start or restart the DICOM Service SCP.
• /[SSName]/admin/service?tcestart - start or restart the TCE Service SCP.
• /[SSName]/admin/service?log - display the contents of the log buffer.
• /[SSName]/admin/service?clear - clear the log buffer.
• /[SSName]/admin/service?reload - reload the index from the siteindex.xml file.
• /[SSName]/admin/service?save - save the current index as saved-index-file.xml.

• /[SSName]/admin/ssconfig - the Storage Service Configurator.
• /[SSName]/admin/tsconfig - the DICOM Service Configurator.
• /[SSName]/admin/tceconfig - the TCE Service Configurator.

• /[SSName]/login - the Login servlet.

• /[SSName]/[path]/[filename] - retrieve a file, using the default XSL transformation if the file is an XML file.
• /[SSName]/[path]/[filename]?xsl - retrieve a file with no XSL processing.
• /[SSName]/[path]/[filename]?xsl=[filename.xsl] - retrieve a file, using the specified XSL transformation if the file is an XML file.
• /[SSName]/[path]/[filename]?zip - retrieve a zip file containing the MIRCdocument and all its local references.
• /[SSName]/[path]/[filename]?zip&ext=[extension] - retrieve a zip file containing the MIRCdocument and all its local references, with the extension of the zip file being specified by the value of the ext parameter.
• /[SSName]/[path]/[filename]?zip=phi - retrieve a zip file containing the non-anonymized DICOM objects stored in the MIRCdocument's research dataset phi directory.
• /[SSName]/[path]/[filename]?zip=no-phi - retrieve a zip file containing the anonymized DICOM objects stored in the MIRCdocument's research dataset no-phi directory.
• /[SSName]/[path]/[filename]?dicom-export - export the DICOM objects referenced by the MIRCdocument to all the DICOM Storage SCPs configured in the Storage Service's trial/trial.xml file.
• /[SSName]/[path]/[filename]?database-export - export the DICOM objects referenced by the MIRCdocument to the external database interface configured in the Storage Service's trial/trial.xml file.

7.3 File Service URLs

Certain File Service URLs can contain a query string listing a set of filenames separated by pipe characters, in the form:
     ?list=[filename1]|[filename2]|...|[filenameN]
In the listing below, this is abbreviated by ?list=.

• /file/service - the personal file cabinet of the authenticated user
• /file/service/tome?list= - copy files from the shared file cabinet to the user's file cabinet
• /file/service/users/[username]/files/[filename] - a file in a user's file cabinet
• /file/service/users/[username]/icons/[filename] - an icon file in a user's file cabinet
• /file/service/add - add a file to the user's file cabinet
• /file/service/save?path=[SSName]/[path]/[filename] - save all the images from a document in the user's file cabinet
• /file/service/delete?list= - delete files from the user's file cabinet
• /file/service/export?list= - export files from the user's file cabinet as a zip file
• /file/service/update?text=...&list= - update the keywords text of files in the user's file cabinet
• /file/service/dicom?list= - display a DICOM element listing of the first file in the list, from the user's file cabinet
• /file/service/dept - the shared file cabinet
• /file/service/todept?list= - copy files from the user's file cabinet to the shared file cabinet
• /file/service/dept/files/[filename] - a file in the shared file cabinet
• /file/service/dept/icons/[filename] - an icon file in the shared file cabinet
• /file/service/dept/add - add a file to the shared file cabinet
• /file/service/dept/delete?list= - delete files from the shared file cabinet
• /file/service/dept/export?list= - export files from the shared file cabinet as a zip file
• /file/service/dept/update?text=...&list= - update the keywords text of files in the shared file cabinet
• /file/service/dept/dicom?list= - display a DICOM element listing of the first file in the list, from the shared file cabinet
• /file/service/common/[filename] - a standard icon file

7.4 Admin URLs

• /mircadmin/controller - the controller servlet
• /mircadmin/logviewer - the log viewer servlet
• /mircadmin/logviewer/[filename] - display a specific log file
• /mircadmin/users - the user role manager servlet
• /mircadmin/user - the user account manager servlet

8 Appendix: System Block Diagram

Error creating thumbnail: Unable to save thumbnail to destination