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 "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. 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.
• [siteurl]/mirc/query does not authenticate.

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.

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.

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;
• enter 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 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 FS-user, XX-user and XX-author. Note that since there is only one File Service on a MIRC site and its user role is FS-user, you will always assign that role 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 UAM 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 UAM and click the Submit button, the visa for those services will be created.

4 Storage Service Administration

4.2 The Storage Service Index File

The storage service maintains a list of its active documents in a file descirbed in a separate article.

4.4 Storage Service Behavior

The storage service can be configured to operate in one of two 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.

To set the mode for a storage service, go to its Admin page and set the mode field (near the top of the table).

4.4.2 Configuring the 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 must be enabled on the Storage Service's admin page. To set the enable field, click the Update Configuration button in the Storage Service column and select yes in the Submit Service Enabled field. Then click the Update storage.xml button at the bottom of the page.

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 publicly from doing so.

Most personal sites operate in autoindexing mode; most shared sites do not. To set the autoindexing mode, click the Update Configuration button in the Storage Service column and select yes in the Submit Service Autoindex field. Then click the Update storage.xml button at the bottom of the page.

4.4.3 Configuring the Zip Service

The Zip Service is a special kind of Submit Service that receives zip files and produces MIRCdocuments from their contents. Each Storage Service has its own Zip Service. A Zip Service is a fully autonomous service that requires no configuration. On initial installation, it 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.

The Zip Service must be enabled on the Storage Service's admin page. To set the enable field, click the Update Configuration button in the Storage Service column and select yes in the Zip Service Enabled field. Then click the Update storage.xml button at the bottom of the page.

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 publicly from doing so.

Most personal sites operate in autoindexing mode; most shared sites do not. To set the autoindexing mode, click the Update Configuration button in the Storage Service column and select yes in the Zip Service Autoindex field. Then click the Update storage.xml button at the bottom of the page.

References:

• The Zip Service User's Manual
• MIRC Templates

4.4.4 Configuring the TCE Service

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 from their contents. Each Storage Service has its own TCE Service. On initial installation, it includes a default 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.

The TCE Service must be enabled on the Storage Service's admin page. To set the enable field, click the Update Configuration button in the Storage Service column and select yes in the TCE Service Enabled field. Then click the Update storage.xml button at the bottom of the page.

References:

• The Zip Service User's Manual
• MIRC Templates

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 to cause the SCP to change 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.

8 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.

8.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

8.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

9 Appendix: System Block Diagram

Error creating thumbnail: Unable to save thumbnail to destination