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.

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.

3 Controlling Users and Groups

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

3.1 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.2 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.3 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.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 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 each 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.3.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.3.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.3.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.3.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.3.1.4 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 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.6 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.7 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.8 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.

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.

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 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 the news listing
• /mirc/news/remove?link=... - remove an item from the 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.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/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