http://mircwiki.rsna.org/api.php?action=feedcontributions&user=209.242.55.28&feedformat=atomMircWiki - User contributions [en]2024-03-29T05:13:19ZUser contributionsMediaWiki 1.35.5http://mircwiki.rsna.org/index.php?title=MIRC_Administrator%27s_Manual&diff=2055MIRC Administrator's Manual2006-08-14T13:10:49Z<p>209.242.55.28: /* Author Service */</p>
<hr />
<div>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. <br />
<br />
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.<br />
<br />
==Installation==<br />
The current official release version is T28. Installation instructions can be found at http://mirc.rsna.org/mircstorage/documents/T28/MIRCdocument.xml. <br />
<br />
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.<br />
<br />
==Query Service Administration==<br />
===System-level Modes===<br />
There are two operating modes which cannot be changed during operation of the system:<br />
* the system mode<br />
* the addressing mode<br />
Both modes are defined in the Query Service's configuration file, which is located in <b>Tomcat/webapps/mirc/mirc.xml</b>. At the top of the file is a <b>DOCTYPE</b> declaration containing several entities:<br />
<pre><br />
<!DOCTYPE mirc [<br />
<!ENTITY mode "rad"><br />
<!ENTITY sitename "P4"><br />
<!ENTITY addresstype "dynamic"><br />
<!ENTITY siteurl "http://192.168.0.96:8080"><br />
<!ENTITY queryurl "&siteurl;/mirc"><br />
<!ENTITY storageurl "&siteurl;/mircstorage"><br />
<!ENTITY mircforum "http://forums.rsna.org/forumdisplay.php?forumid=9"><br />
<!ENTITY mircdocs "http://mircwiki.rsna.org"><br />
<!ENTITY radlex "http://mirc.rsna.org/radlex/service"><br />
<!ENTITY tcusersclass "org.rsna.mircsite.util.TomcatUsersXmlFileImpl"><br />
<!ENTITY acctenb "yes"><br />
<!ENTITY defroles "QS-user,FS-user,SS-user,SS-author"><br />
<!ENTITY gpenb "yes"><br />
<!ENTITY version "T29alpha"> ]><br />
</pre><br />
<br />
====Setting the System Mode====<br />
The system mode is defined by the <b>mode</b> entity. The currently supported modes are:<br />
*<b>rad</b>: radiology<br />
*<b>vet</b>: veterinary medicine<br />
The choice of system mode configures the enumerated values for sexes, races, species, and breeds. These parameters, among many others, are stored in <b>Tomcat/webapps/mirc/enumerated-values.xml</b>.<br />
<br />
The software is preconfigured for <b>rad</b> mode. To change to <b>vet</b> mode, it is necessary to edit the <b>mirc.xml</b> file with a text editor and change the value of the <b>mode</b> entity. <br />
<br />
If operating in <b>vet</b> 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 <b>enumerated-values.xml</b> 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.<br />
<br />
====Setting the Addressing Mode====<br />
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.<br />
<br />
=====Dynamic vs. Static IP Addressing=====<br />
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.<br />
<br />
The way the MIRC software obtains the IP address is determined by the <b>addresstype</b> entity. The entity can have two possible values, <b>dynamic</b> or <b>static</b>. If the value is <b>dynamic</b>, 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. <br />
<br />
If the value of the <b>addresstype</b> entity is <b>static</b>, the software obtains the IP address from the <b>siteurl</b> entity. The <b>siteurl</b> entity can contain a numeric IP address or a domain name address. <br />
<br />
If <b>dynamic</b> addressing is used, the IP address specified in the <b>siteurl</b> entity must be numeric; otherwise, the method which obtains the IP address from the operating system will refuse to overwrite it.<br />
<br />
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.<br />
<br />
=====Reconfiguring the IP Address=====<br />
To change the IP addressing method after installation of the system, change the value of the <b>addresstype</b> entity using a text editor. If static addressing is employed, put the static IP address of the host in the value of the <b>siteurl</b> entity.<br />
<br />
Important: The protocol and port fields in the <b>siteurl</b> entity are always used, even in the case of dynamic addressing, so they must be set correctly in all cases.<br />
<br />
If an alphabetic value is inserted in the IP address field of the <b>siteurl</b> 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.<br />
<br />
====Restarting the System====<br />
After changing the system mode or the addressing mode, it is necessary to restart Tomcat in order to force the <b>init</b> methods of the MIRC servlets to run and reload the new enumerated values and/or IP address.<br />
<br />
===Setting the Authentication Requirements===<br />
The Query Service receives connections on two URLs:<br />
*<b>[siteurl]/mirc/auth</b> authenticates the user (forces a challenge for the user's credentials).<br />
*<b>[siteurl]/mirc/query</b> does not authenticate the user.<br />
<br />
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 <b>/query/auth</b> URL or by clicking the <b>Login</b> button on the query page.<br />
<br />
To be authenticated on the query service, you must have the <b>QS-user</b> role. When you upgrade, the installer will offer to add that role to the <b>admin</b> account, but for other users, you will have to add it manually with the User Role Manager.<br />
<br />
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 <b>index.html</b> page and change the URL in the redirection element.<br />
<br />
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) <u>on that storage service</u> 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 <b>passport</b>. A passport is managed by the passport's owner (the user) via the User Account Manager. A passport consists of a collection of <b>visas</b>, 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.<br />
<br />
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.<br />
<br />
===The Case of the Day===<br />
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 <b>Case of the Day</b> button in the table at the bottom of the document (or at the bottom of the <b>Document</b> tab).<br />
<br />
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.<br />
<br />
The latest Case of the Day can always be accessed by clicking the image in the lower left corner of the query page.<br />
<br />
==Controlling Users and Groups==<br />
Starting with Release T29, MIRC includes a User Account Manager that, when enabled by the administrator, allows users to create groups (and even accounts). <br />
<br />
===Groups===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===The User Role Manager===<br />
The User Role Manager, which can only be accessed by an administrator, has been changed so that it only manages:<br />
* the creation of new users <br />
* the removal of old users<br />
* the administrative roles<br />
<br />
Administrative roles are those that confer access to servlets or to MIRC behavior (like the <b>publisher</b> role and the various <b>admin</b> roles for Storage Services and the File Service).<br />
<br />
===The User Account Manager===<br />
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 (<b>admin</b>).<br />
<br />
To manage account and group creation, go to the query page, click the <b>Login</b> button and log in to an <b>admin</b> account. Then click the <b>My Account</b> button. The resulting page will contain several sections, each described by a little text telling you what to do. You can:<br />
*change your password on the server;<br />
*create visas for yourself;<br />
*resign from any or all groups;<br />
*join a group (if you know its name and password);<br />
*create a group, giving it a name and a password;<br />
*control whether account creation and/or group creation are enabled on the site;<br />
*define the administrative roles that are granted to users who create their own accounts.<br />
<br />
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.<br />
<br />
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 <b>user</b> and <b>author</b> roles for the File Service and the Storage Service to which you want to restrict the user (typically <b>QS-user</b>, <b>FS-user</b>, <b>SS-user</b> and <b>SS-author</b>). 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 <b>XX</b>, and then set the administrative roles for new users to be <b>QS-user</b>, <b>FS-user</b>, <b>XX-user</b> and <b>XX-author</b>. Note that since there is only one Query Service and one File Service on a MIRC site, you will always assign the <b>QS-user</b> and <b>FS-user</b> roles, no matter what the prefix is for the storage service.<br />
<br />
Group creation is independent of account creation and is separately enabled. Thus, you can disable account creation while still allowing group creation.<br />
<br />
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 <b>Submit</b> button, the visa for those services will be created.<br />
<br />
==Storage Service Administration==<br />
===The storage.xml File===<br />
Each storage service is a separate web application (webapp). The principal configuration parameters are contained in the <b>storage.xml</b> file, which is located in the root directory of the storage service (<b>Tomcat/webapps/[SSName]</b>, where <b>[SSName]</b> is the one-word name that you chose for the storage service when you installed it). <br />
<br />
At the top of the file is a <b>DOCTYPE</b> declaration similar to the one at the top of the <b>mirc.xml</b> file:<br />
<pre><br />
<?xml version="1.0" encoding="iso-8859-1"?><br />
<br />
<!DOCTYPE storage [<br />
<!ENTITY siteurl "http://192.168.0.98:8080"><br />
<!ENTITY servletname "mircstorage"><br />
<!ENTITY docauthoring "yes"><br />
<!ENTITY authorindex "yes"><br />
<!ENTITY docsubmission "yes"><br />
<!ENTITY maxsize "100"><br />
<!ENTITY autoindex "yes"><br />
<!ENTITY zipsubmission "yes"><br />
<!ENTITY zipmaxsize "100"><br />
<!ENTITY zipautoindex "yes"><br />
<!ENTITY philog "yes"><br />
<!ENTITY philogexport "no"><br />
<!ENTITY philogexporturl ""><br />
<!ENTITY dicomenable "no"><br />
<!ENTITY tceenable "no"><br />
<!ENTITY tagline ""><br />
<!ENTITY sitename "Storage Service"><br />
<!ENTITY querymode "open"><br />
<!ENTITY version "00"> ]><br />
</pre><br />
<br />
With the exception of <b>siteurl</b> and <b>servletname</b>, all the entities can be changed using the <b>Storage Service Configurator</b>.<br />
<br />
To change the IP addressing mode, it is necessary to edit the file with a normal text editor and change the value of the <b>siteurl</b> entity as described in the Query Service section. <br />
<br />
You should not change the value of the <b>servletname</b> entity unless you are under the care of a software engineer.<br />
<br />
With the exception of the Author Service templates, described below, you should not change the text of the rest of the file.<br />
<br />
===The siteindex.xml File===<br />
The storage service maintains a list of its active documents in a file described in a [[The Storage Service Index File|separate article]]. When the Storage Service starts, it builds an index from the contents of the documents listed in this file.<br />
<br />
See also [[Data Mining the MIRC Index]].<br />
<br />
===The Admin Service===<br />
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 <b>Admin Service</b> button. The resulting page contains a set of buttons as shown below, and an area in which various functions display their results.<br />
<br />
<br />
[[Image:AdminButtons1.JPG]]<br />
<br />
<br />
The following is a brief summary of each of the buttons' functions:<br />
*Left Column<br />
**<b>Status</b> - displays the key parameter settings<br />
**<b>List Input Queue</b> - displays the list of documents that have been requested to be made public by users who do not have the <b>publisher</b> role. Documents only enter the queue if autoindexing is not enabled on the Storage Service.<br />
**<b>File Service Admin</b> - a convenience link to the Admin Service of the File Service.<br />
*Storage Service Column<br />
**<b>Update Configuration</b> - links to the Storage Service Configurator, providing access to most of the Storage Service configuration parameters.<br />
**<b>List Index</b> - lists the documents currently in the index, with links allowing them to be viewed, deleted, or edited.<br />
**<b>Reload Index</b> - forces the Storage Service to reload its index from the siteindex.xml file.<br />
**<b>Rebuild Index</b> - creates a new siteindex.xml file by walking the directory tree under the <b>documents</b> directory and finding all the MIRCdocuments.<br />
**<b>Save Index</b> - saves the current index in <b>saved-index-file.xml</b> in the root directory of the Storage Service.<br />
*TCE Service Column<br />
**<b>Update Configuration</b> - links to the TCE Service Configurator, providing access to its DICOM Service parameters.<br />
**<b>Start/Restart</b> - starts the TCE Service's DICOM Service.<br />
**<b>Show Log</b> - displays the Storage Service's circular buffer of log entries from all its DICOM Services.<br />
**<b>Clear Log</b> - clears the circular log buffer.<br />
*DICOM Service Column<br />
**<b>Update Configuration</b> - links to the DICOM Service Configurator, providing access to the parameters used in clinical trials.<br />
**<b>Start/Restart</b> - starts the DICOM Service.<br />
**<b>Show Log</b> - 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.<br />
**<b>Clear Log</b> - clears the circular log buffer. This button does the same thing as the corresponding button in the TCE Service column.<br />
*Tomcat Column<br />
**<b>User Role Manager</b> - a convenience link to the MIRC User Role Manager servlet.<br />
**<b>Controller</b> - a convenience link to the MIRC Controller servlet.<br />
**<b>Log Viewer</b> - a convenience link to the Log Viewer servlet.<br />
[[Image:SSConfigurator1.JPG|frame|]]<br />
====The Storage Service Configurator====<br />
<br />
The Storage Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
Most of the parameters in the configurator are discussed in sections related to the services to which they apply. The others are discussed below.<br />
=====Query Mode=====<br />
The storage service can be configured to operate in one of two query modes:<br />
*<b>open</b> 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.<br />
*<b>restricted</b> sets the service to return only those results that match a query and for which the user is authorized to view the documents. <br />
<br />
In <b>restricted</b> mode, if a user is not authenticated in the query, the storage service only returns results for public documents.<br />
<br />
=====Site Name=====<br />
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.<br />
<br />
=====Tag Line=====<br />
The Tag Line is the text that is displayed under the name of the Storage Service in the list of query results.<br />
<br />
=====PHI Logging=====<br />
Storage Services have the ability to log accesses to MIRCdocuments that contain protected health information. Two kinds of logging are supported:<br />
* <b>PHI Access Log Enabled</b> determines whether the Storage Service logs PHI accesses in a local log file contained in the <b>access-logs</b> subdirectory of the root of the Storage Service. This log is a simple text file.<br />
* <b>PHI Access Log Export Enabled</b> 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 <b>PHI Access Log Export URL</b> field.<br />
<br />
===Author Service===<br />
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 <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Author Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Author Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Author Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are created by the Author Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most sites do not operate in autoindexing mode. To set the autoindexing mode, select <b>yes</b> in the <b>Author Service Autoindex</b> field. <br />
====Templates====<br />
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]]. <br />
<br />
Author Service templates are stored in the storage service's <b>templates</b> directory These templates must be made known to the system before users can access them. To do so, edit the <b>storage.xml</b> 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:<br />
<pre><br />
<template name="templates/doc-template-mstf2.xml"><br />
Simple Teaching File Template<br />
</template><br />
</pre><br />
The <b>name</b> 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 <b>template</b> 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.<br />
<br />
===Submit Service===<br />
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 <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Submit Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Submit Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Submit Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are received by the Submit Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Submit Service Autoindex</b> field. <br />
<br />
You can also control the maximum size of any submission. On initial installation, the default is set to <b>100MB</b>. To change the size, edit the <b>Maximum Submission Size (MB)</b> field.<br />
<br />
===Zip Service===<br />
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 <b>Tomcat/webapps/[storageservice]/submit/template.xml</b>. 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.<br />
<br />
The Zip Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Zip Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Zip Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Zip Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are created by the Zip Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Zip Service Autoindex</b> field. <br />
<br />
See [[The Zip Service User's Manual]] for more information.<br />
<br />
===TCE Service===<br />
[[Image:TCEConfigurator1.JPG|frame|]]<br />
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 <b>Tomcat/webapps/[storageservice]/tce/template.xml</b>. 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.<br />
<br />
The TCE Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the TCE Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>TCE Service Enabled</b> field.<br />
<br />
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.<br />
<br />
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 <b>Update Configuration</b> button in the <b>TCE Service</b> column on the Storage Service's admin page:<br />
*<b>autostart</b> - determines whether the service is automatically started when Tomcat starts. <br />
*<b>Store AE Title</b> - sets the application entity title for the TCE Service's DICOM Service. It should be unique in the entire MIRC environment.<br />
*<b>Store Port</b> - sets the port on which the DICOM Service listens for associations.<br />
Changes to these parameters are not recorded until the <b>Update tce.xml</b> button is clicked.<br />
<br />
To start the DICOM Service, or to restart it after changes have been made to its parameters, you must click the <b>Start/Restart</b> button in the <b>TCE Service</b> column on the admin page.<br />
<br />
===DICOM Service===<br />
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.<br />
<br />
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.<br />
<br />
For complete documentation on the DICOM Service, see the [[Clinical Trial Administrator's Manual]].<br />
<br />
==File Service Administration==<br />
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.<br />
===Controlling Access to the File Service===<br />
Each authenticated user who has the <b>FS-user</b> role is provided a personal file cabinet which only that user can access. In addition, all authenticated users with the <b>FS-user</b> role can access the shared file cabinet. Only users with the <b>FS-admin</b> role can access the File Service Admin page and configure the File Service.<br />
===Accessing the File Service Admin Page===<br />
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 <b>Admin Service</b> button on the right side of the window.<br />
<br />
On the Admin page, click the <b>File Service Admin</b> button. The result will be a page as shown below.<br />
<br />
[[Image:FileServiceAdmin1.JPG|frame|]]<br />
<br />
===Configuring the DICOM Service===<br />
The File Service has its own DICOM Service which receives DICOM objects, optionally anonymizes them, and places them in the shared file cabinet.<br />
<br />
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.<br />
<br />
If you want the DICOM Service to start automatically when the MIRC site is initialized, select <b>yes</b> in the <b>Autostart</b> field.<br />
<br />
After changing the configuration of the DICOM Service, you must first click the <b>Update fileservice.xml</b> button to save the changes, and then click the <b>Start/restart the DICOM Service</b> button to make the DICOM Service recognize them.<br />
<br />
===Configuring the Anonymizer===<br />
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 <b>Update the Anonymizer</b> button. The configuration and operation of the Anonymizer Configurator is described in [[The_MIRC_DICOM_Anonymizer|a separate article]].<br />
<br />
To enable the anonymizer, select <b>yes</b> in the <b>Anonymizer Enabled</b> field.<br />
<br />
<b>Important Note:</b> 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.<br />
<br />
===Configuring the Garbage Collector===<br />
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 <b>Shared File Cabinet Timeout (hours)</b> 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.<br />
<br />
===Saving Configuration Changes===<br />
To save the changes you have made to the configuration, click the <b>Update fileservice.xml</b> button. Changes do not become effective until they are saved. <br />
<br />
Anonymizer script changes are saved on the Anonymizer Configurator and do not require a separate button click on the Admin page.<br />
<br />
===Starting the DICOM Service===<br />
If the Autostart field contains <b>yes</b>, the DICOM Service is started when Tomcat starts and the MIRC site is initialized. If the Autostart field does not contain <b>yes</b>, you can start the DICOM Service by clicking the <b>Start/Restart the DICOM Service</b> button.<br />
<br />
<b>Caution:</b> Whenever you make changes to the DICOM Service configuration, you must save those changes by clicking the <b>Update fileservice.xml</b> 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.<br />
<br />
===Managing the Shared File Cabinet===<br />
Users who do not possess the <b>FS-admin</b> 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 <b>FS-admin</b> role can any delete files from the shared file cabinet.<br />
<br />
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.<br />
<br />
==System-Level Services==<br />
There are several system-level servlets that are a convenience for administrators. They can be accessed through the admin page of any Storage Service.<br />
===Log Viewer===<br />
The Log Viewer provides browser access to the log files in <b>Tomcat/logs</b>. Only log files with non-zero sizes are listed, and the listing is in reverse chronological order, making it easy to find current logs.<br />
===Controller===<br />
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.<br />
<br />
==Appendix: MIRC URL Index==<br />
This section indexes all the URLs recognized by a MIRC site. In the listing below, the following notations are used:<br />
*All URLS are assumed to begin with the value of the <b>siteurl</b> entity in the query service's <b>mirc.xml</b> file. For brevity, this part of the URL is not shown.<br />
*<b>[SSName]</b> refers to the name of a storage service.<br />
*<b>[path]</b> refers to a path.<br />
*<b>[filename]</b> refers to the name of a file.<br />
*<b>[username]</b> refers to the account name for a user.<br />
*Text not in square brackets is a fixed part of the URL. <br />
<br />
===Query Service URLs===<br />
*<tt>/mirc/query</tt> - the non-authenticated query service<br />
*<tt>/mirc/auth</tt> - the authenticated query service<br />
*<tt>/mirc/news</tt> - get the current news item (Case of the Day)<br />
*<tt>/mirc/news/add?link=...&title=...&description=...&image=...</tt> - add an item to the the news listing<br />
*<tt>/mirc/news/remove?link=...</tt> - remove an item from the the news listing<br />
*<tt>/mirc/news/listing</tt> - get HTML code referencing the current news item (for inclusion on a web page)<br />
*<tt>/mirc/news/news.rss</tt> - the RSS news feed<br />
<br />
===Storage Service URLs===<br />
<br />
===File Service URLs===<br />
Certain File Service URLs can contain a query string listing a set of filenames separated by pipe characters, in the form:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><tt>?list=[filename1]|[filename2]|...|[filenameN]</tt></b><br>In the listing below, this is abbreviated by <b><tt>?list=</tt></b>.<br />
*<tt>/file/service</tt> - the personal file cabinet of the authenticated user<br />
*<tt>/file/service/tome?list=</tt> - copy files from the shared file cabinet to the user's file cabinet <br />
*<tt>/file/service/users/[username]/files/[filename]</tt> - a file in a user's file cabinet<br />
*<tt>/file/service/users/[username]/icons/[filename]</tt> - an icon file in a user's file cabinet<br />
*<tt>/file/service/add</tt> - add a file to the user's file cabinet<br />
*<tt>/file/service/delete?list=</tt> - delete files from the user's file cabinet<br />
*<tt>/file/service/export?list=</tt> - export files from the user's file cabinet as a zip file<br />
*<tt>/file/service/update?text=...&list=</tt> - update the keywords text of files in the user's file cabinet<br />
*<tt>/file/service/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the user's file cabinet<br />
*<tt>/file/service/dept</tt> - the shared file cabinet<br />
*<tt>/file/service/todept?list=</tt> - copy files from the user's file cabinet to the shared file cabinet<br />
*<tt>/file/service/dept/files/[filename]</tt> - a file in the shared file cabinet<br />
*<tt>/file/service/dept/icons/[filename]</tt> - an icon file in the shared file cabinet<br />
*<tt>/file/service/dept/add</tt> - add a file to the shared file cabinet<br />
*<tt>/file/service/dept/delete?list=</tt> - delete files from the shared file cabinet<br />
*<tt>/file/service/dept/export?list=</tt> - export files from the shared file cabinet as a zip file<br />
*<tt>/file/service/dept/update?text=...&list=</tt> - update the keywords text of files in the shared file cabinet<br />
*<tt>/file/service/dept/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the shared file cabinet<br />
*<tt>/file/service/common/[filename]</tt> - a standard icon file<br />
<br />
===Admin URLs===<br />
*<tt>/mircadmin/controller</tt> - the controller servlet<br />
*<tt>/mircadmin/logviewer</tt> - the log viewer servlet<br />
*<tt>/mircadmin/logviewer/[filename]</tt> - display a specific log file<br />
*<tt>/mircadmin/users</tt> - the user role manager servlet<br />
*<tt>/mircadmin/user</tt> - the user account manager servlet<br />
<br />
==Appendix: System Block Diagram==<br />
[[Image:RsnaMircBlockDiagram-1.GIF]]</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=MIRC_Administrator%27s_Manual&diff=2054MIRC Administrator's Manual2006-08-14T13:10:06Z<p>209.242.55.28: /* Storage Service Administration */</p>
<hr />
<div>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. <br />
<br />
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.<br />
<br />
==Installation==<br />
The current official release version is T28. Installation instructions can be found at http://mirc.rsna.org/mircstorage/documents/T28/MIRCdocument.xml. <br />
<br />
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.<br />
<br />
==Query Service Administration==<br />
===System-level Modes===<br />
There are two operating modes which cannot be changed during operation of the system:<br />
* the system mode<br />
* the addressing mode<br />
Both modes are defined in the Query Service's configuration file, which is located in <b>Tomcat/webapps/mirc/mirc.xml</b>. At the top of the file is a <b>DOCTYPE</b> declaration containing several entities:<br />
<pre><br />
<!DOCTYPE mirc [<br />
<!ENTITY mode "rad"><br />
<!ENTITY sitename "P4"><br />
<!ENTITY addresstype "dynamic"><br />
<!ENTITY siteurl "http://192.168.0.96:8080"><br />
<!ENTITY queryurl "&siteurl;/mirc"><br />
<!ENTITY storageurl "&siteurl;/mircstorage"><br />
<!ENTITY mircforum "http://forums.rsna.org/forumdisplay.php?forumid=9"><br />
<!ENTITY mircdocs "http://mircwiki.rsna.org"><br />
<!ENTITY radlex "http://mirc.rsna.org/radlex/service"><br />
<!ENTITY tcusersclass "org.rsna.mircsite.util.TomcatUsersXmlFileImpl"><br />
<!ENTITY acctenb "yes"><br />
<!ENTITY defroles "QS-user,FS-user,SS-user,SS-author"><br />
<!ENTITY gpenb "yes"><br />
<!ENTITY version "T29alpha"> ]><br />
</pre><br />
<br />
====Setting the System Mode====<br />
The system mode is defined by the <b>mode</b> entity. The currently supported modes are:<br />
*<b>rad</b>: radiology<br />
*<b>vet</b>: veterinary medicine<br />
The choice of system mode configures the enumerated values for sexes, races, species, and breeds. These parameters, among many others, are stored in <b>Tomcat/webapps/mirc/enumerated-values.xml</b>.<br />
<br />
The software is preconfigured for <b>rad</b> mode. To change to <b>vet</b> mode, it is necessary to edit the <b>mirc.xml</b> file with a text editor and change the value of the <b>mode</b> entity. <br />
<br />
If operating in <b>vet</b> 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 <b>enumerated-values.xml</b> 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.<br />
<br />
====Setting the Addressing Mode====<br />
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.<br />
<br />
=====Dynamic vs. Static IP Addressing=====<br />
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.<br />
<br />
The way the MIRC software obtains the IP address is determined by the <b>addresstype</b> entity. The entity can have two possible values, <b>dynamic</b> or <b>static</b>. If the value is <b>dynamic</b>, 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. <br />
<br />
If the value of the <b>addresstype</b> entity is <b>static</b>, the software obtains the IP address from the <b>siteurl</b> entity. The <b>siteurl</b> entity can contain a numeric IP address or a domain name address. <br />
<br />
If <b>dynamic</b> addressing is used, the IP address specified in the <b>siteurl</b> entity must be numeric; otherwise, the method which obtains the IP address from the operating system will refuse to overwrite it.<br />
<br />
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.<br />
<br />
=====Reconfiguring the IP Address=====<br />
To change the IP addressing method after installation of the system, change the value of the <b>addresstype</b> entity using a text editor. If static addressing is employed, put the static IP address of the host in the value of the <b>siteurl</b> entity.<br />
<br />
Important: The protocol and port fields in the <b>siteurl</b> entity are always used, even in the case of dynamic addressing, so they must be set correctly in all cases.<br />
<br />
If an alphabetic value is inserted in the IP address field of the <b>siteurl</b> 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.<br />
<br />
====Restarting the System====<br />
After changing the system mode or the addressing mode, it is necessary to restart Tomcat in order to force the <b>init</b> methods of the MIRC servlets to run and reload the new enumerated values and/or IP address.<br />
<br />
===Setting the Authentication Requirements===<br />
The Query Service receives connections on two URLs:<br />
*<b>[siteurl]/mirc/auth</b> authenticates the user (forces a challenge for the user's credentials).<br />
*<b>[siteurl]/mirc/query</b> does not authenticate the user.<br />
<br />
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 <b>/query/auth</b> URL or by clicking the <b>Login</b> button on the query page.<br />
<br />
To be authenticated on the query service, you must have the <b>QS-user</b> role. When you upgrade, the installer will offer to add that role to the <b>admin</b> account, but for other users, you will have to add it manually with the User Role Manager.<br />
<br />
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 <b>index.html</b> page and change the URL in the redirection element.<br />
<br />
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) <u>on that storage service</u> 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 <b>passport</b>. A passport is managed by the passport's owner (the user) via the User Account Manager. A passport consists of a collection of <b>visas</b>, 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.<br />
<br />
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.<br />
<br />
===The Case of the Day===<br />
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 <b>Case of the Day</b> button in the table at the bottom of the document (or at the bottom of the <b>Document</b> tab).<br />
<br />
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.<br />
<br />
The latest Case of the Day can always be accessed by clicking the image in the lower left corner of the query page.<br />
<br />
==Controlling Users and Groups==<br />
Starting with Release T29, MIRC includes a User Account Manager that, when enabled by the administrator, allows users to create groups (and even accounts). <br />
<br />
===Groups===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===The User Role Manager===<br />
The User Role Manager, which can only be accessed by an administrator, has been changed so that it only manages:<br />
* the creation of new users <br />
* the removal of old users<br />
* the administrative roles<br />
<br />
Administrative roles are those that confer access to servlets or to MIRC behavior (like the <b>publisher</b> role and the various <b>admin</b> roles for Storage Services and the File Service).<br />
<br />
===The User Account Manager===<br />
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 (<b>admin</b>).<br />
<br />
To manage account and group creation, go to the query page, click the <b>Login</b> button and log in to an <b>admin</b> account. Then click the <b>My Account</b> button. The resulting page will contain several sections, each described by a little text telling you what to do. You can:<br />
*change your password on the server;<br />
*create visas for yourself;<br />
*resign from any or all groups;<br />
*join a group (if you know its name and password);<br />
*create a group, giving it a name and a password;<br />
*control whether account creation and/or group creation are enabled on the site;<br />
*define the administrative roles that are granted to users who create their own accounts.<br />
<br />
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.<br />
<br />
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 <b>user</b> and <b>author</b> roles for the File Service and the Storage Service to which you want to restrict the user (typically <b>QS-user</b>, <b>FS-user</b>, <b>SS-user</b> and <b>SS-author</b>). 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 <b>XX</b>, and then set the administrative roles for new users to be <b>QS-user</b>, <b>FS-user</b>, <b>XX-user</b> and <b>XX-author</b>. Note that since there is only one Query Service and one File Service on a MIRC site, you will always assign the <b>QS-user</b> and <b>FS-user</b> roles, no matter what the prefix is for the storage service.<br />
<br />
Group creation is independent of account creation and is separately enabled. Thus, you can disable account creation while still allowing group creation.<br />
<br />
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 <b>Submit</b> button, the visa for those services will be created.<br />
<br />
==Storage Service Administration==<br />
===The storage.xml File===<br />
Each storage service is a separate web application (webapp). The principal configuration parameters are contained in the <b>storage.xml</b> file, which is located in the root directory of the storage service (<b>Tomcat/webapps/[SSName]</b>, where <b>[SSName]</b> is the one-word name that you chose for the storage service when you installed it). <br />
<br />
At the top of the file is a <b>DOCTYPE</b> declaration similar to the one at the top of the <b>mirc.xml</b> file:<br />
<pre><br />
<?xml version="1.0" encoding="iso-8859-1"?><br />
<br />
<!DOCTYPE storage [<br />
<!ENTITY siteurl "http://192.168.0.98:8080"><br />
<!ENTITY servletname "mircstorage"><br />
<!ENTITY docauthoring "yes"><br />
<!ENTITY authorindex "yes"><br />
<!ENTITY docsubmission "yes"><br />
<!ENTITY maxsize "100"><br />
<!ENTITY autoindex "yes"><br />
<!ENTITY zipsubmission "yes"><br />
<!ENTITY zipmaxsize "100"><br />
<!ENTITY zipautoindex "yes"><br />
<!ENTITY philog "yes"><br />
<!ENTITY philogexport "no"><br />
<!ENTITY philogexporturl ""><br />
<!ENTITY dicomenable "no"><br />
<!ENTITY tceenable "no"><br />
<!ENTITY tagline ""><br />
<!ENTITY sitename "Storage Service"><br />
<!ENTITY querymode "open"><br />
<!ENTITY version "00"> ]><br />
</pre><br />
<br />
With the exception of <b>siteurl</b> and <b>servletname</b>, all the entities can be changed using the <b>Storage Service Configurator</b>.<br />
<br />
To change the IP addressing mode, it is necessary to edit the file with a normal text editor and change the value of the <b>siteurl</b> entity as described in the Query Service section. <br />
<br />
You should not change the value of the <b>servletname</b> entity unless you are under the care of a software engineer.<br />
<br />
With the exception of the Author Service templates, described below, you should not change the text of the rest of the file.<br />
<br />
===The siteindex.xml File===<br />
The storage service maintains a list of its active documents in a file described in a [[The Storage Service Index File|separate article]]. When the Storage Service starts, it builds an index from the contents of the documents listed in this file.<br />
<br />
See also [[Data Mining the MIRC Index]].<br />
<br />
===The Admin Service===<br />
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 <b>Admin Service</b> button. The resulting page contains a set of buttons as shown below, and an area in which various functions display their results.<br />
<br />
<br />
[[Image:AdminButtons1.JPG]]<br />
<br />
<br />
The following is a brief summary of each of the buttons' functions:<br />
*Left Column<br />
**<b>Status</b> - displays the key parameter settings<br />
**<b>List Input Queue</b> - displays the list of documents that have been requested to be made public by users who do not have the <b>publisher</b> role. Documents only enter the queue if autoindexing is not enabled on the Storage Service.<br />
**<b>File Service Admin</b> - a convenience link to the Admin Service of the File Service.<br />
*Storage Service Column<br />
**<b>Update Configuration</b> - links to the Storage Service Configurator, providing access to most of the Storage Service configuration parameters.<br />
**<b>List Index</b> - lists the documents currently in the index, with links allowing them to be viewed, deleted, or edited.<br />
**<b>Reload Index</b> - forces the Storage Service to reload its index from the siteindex.xml file.<br />
**<b>Rebuild Index</b> - creates a new siteindex.xml file by walking the directory tree under the <b>documents</b> directory and finding all the MIRCdocuments.<br />
**<b>Save Index</b> - saves the current index in <b>saved-index-file.xml</b> in the root directory of the Storage Service.<br />
*TCE Service Column<br />
**<b>Update Configuration</b> - links to the TCE Service Configurator, providing access to its DICOM Service parameters.<br />
**<b>Start/Restart</b> - starts the TCE Service's DICOM Service.<br />
**<b>Show Log</b> - displays the Storage Service's circular buffer of log entries from all its DICOM Services.<br />
**<b>Clear Log</b> - clears the circular log buffer.<br />
*DICOM Service Column<br />
**<b>Update Configuration</b> - links to the DICOM Service Configurator, providing access to the parameters used in clinical trials.<br />
**<b>Start/Restart</b> - starts the DICOM Service.<br />
**<b>Show Log</b> - 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.<br />
**<b>Clear Log</b> - clears the circular log buffer. This button does the same thing as the corresponding button in the TCE Service column.<br />
*Tomcat Column<br />
**<b>User Role Manager</b> - a convenience link to the MIRC User Role Manager servlet.<br />
**<b>Controller</b> - a convenience link to the MIRC Controller servlet.<br />
**<b>Log Viewer</b> - a convenience link to the Log Viewer servlet.<br />
[[Image:SSConfigurator1.JPG|frame|]]<br />
====The Storage Service Configurator====<br />
<br />
The Storage Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
Most of the parameters in the configurator are discussed in sections related to the services to which they apply. The others are discussed below.<br />
=====Query Mode=====<br />
The storage service can be configured to operate in one of two query modes:<br />
*<b>open</b> 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.<br />
*<b>restricted</b> sets the service to return only those results that match a query and for which the user is authorized to view the documents. <br />
<br />
In <b>restricted</b> mode, if a user is not authenticated in the query, the storage service only returns results for public documents.<br />
<br />
=====Site Name=====<br />
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.<br />
<br />
=====Tag Line=====<br />
The Tag Line is the text that is displayed under the name of the Storage Service in the list of query results.<br />
<br />
=====PHI Logging=====<br />
Storage Services have the ability to log accesses to MIRCdocuments that contain protected health information. Two kinds of logging are supported:<br />
* <b>PHI Access Log Enabled</b> determines whether the Storage Service logs PHI accesses in a local log file contained in the <b>access-logs</b> subdirectory of the root of the Storage Service. This log is a simple text file.<br />
* <b>PHI Access Log Export Enabled</b> 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 <b>PHI Access Log Export URL</b> field.<br />
<br />
===Author Service===<br />
The Author Service allows users to create and store MIRCdocuments. Each Storage Service has its own Author Service. The Author Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Author Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Author Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Author Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are created by the Author Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most sites do not operate in autoindexing mode. To set the autoindexing mode, select <b>yes</b> in the <b>Author Service Autoindex</b> field. <br />
====Templates====<br />
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]]. <br />
<br />
Author Service templates are stored in the storage service's <b>templates</b> directory These templates must be made known to the system before users can access them. To do so, edit the <b>storage.xml</b> 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:<br />
<pre><br />
<template name="templates/doc-template-mstf2.xml"><br />
Simple Teaching File Template<br />
</template><br />
</pre><br />
The <b>name</b> 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 <b>template</b> 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.<br />
<br />
===Submit Service===<br />
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 <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Submit Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Submit Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Submit Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are received by the Submit Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Submit Service Autoindex</b> field. <br />
<br />
You can also control the maximum size of any submission. On initial installation, the default is set to <b>100MB</b>. To change the size, edit the <b>Maximum Submission Size (MB)</b> field.<br />
<br />
===Zip Service===<br />
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 <b>Tomcat/webapps/[storageservice]/submit/template.xml</b>. 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.<br />
<br />
The Zip Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Zip Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Zip Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Zip Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are created by the Zip Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Zip Service Autoindex</b> field. <br />
<br />
See [[The Zip Service User's Manual]] for more information.<br />
<br />
===TCE Service===<br />
[[Image:TCEConfigurator1.JPG|frame|]]<br />
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 <b>Tomcat/webapps/[storageservice]/tce/template.xml</b>. 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.<br />
<br />
The TCE Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the TCE Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>TCE Service Enabled</b> field.<br />
<br />
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.<br />
<br />
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 <b>Update Configuration</b> button in the <b>TCE Service</b> column on the Storage Service's admin page:<br />
*<b>autostart</b> - determines whether the service is automatically started when Tomcat starts. <br />
*<b>Store AE Title</b> - sets the application entity title for the TCE Service's DICOM Service. It should be unique in the entire MIRC environment.<br />
*<b>Store Port</b> - sets the port on which the DICOM Service listens for associations.<br />
Changes to these parameters are not recorded until the <b>Update tce.xml</b> button is clicked.<br />
<br />
To start the DICOM Service, or to restart it after changes have been made to its parameters, you must click the <b>Start/Restart</b> button in the <b>TCE Service</b> column on the admin page.<br />
<br />
===DICOM Service===<br />
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.<br />
<br />
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.<br />
<br />
For complete documentation on the DICOM Service, see the [[Clinical Trial Administrator's Manual]].<br />
<br />
==File Service Administration==<br />
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.<br />
===Controlling Access to the File Service===<br />
Each authenticated user who has the <b>FS-user</b> role is provided a personal file cabinet which only that user can access. In addition, all authenticated users with the <b>FS-user</b> role can access the shared file cabinet. Only users with the <b>FS-admin</b> role can access the File Service Admin page and configure the File Service.<br />
===Accessing the File Service Admin Page===<br />
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 <b>Admin Service</b> button on the right side of the window.<br />
<br />
On the Admin page, click the <b>File Service Admin</b> button. The result will be a page as shown below.<br />
<br />
[[Image:FileServiceAdmin1.JPG|frame|]]<br />
<br />
===Configuring the DICOM Service===<br />
The File Service has its own DICOM Service which receives DICOM objects, optionally anonymizes them, and places them in the shared file cabinet.<br />
<br />
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.<br />
<br />
If you want the DICOM Service to start automatically when the MIRC site is initialized, select <b>yes</b> in the <b>Autostart</b> field.<br />
<br />
After changing the configuration of the DICOM Service, you must first click the <b>Update fileservice.xml</b> button to save the changes, and then click the <b>Start/restart the DICOM Service</b> button to make the DICOM Service recognize them.<br />
<br />
===Configuring the Anonymizer===<br />
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 <b>Update the Anonymizer</b> button. The configuration and operation of the Anonymizer Configurator is described in [[The_MIRC_DICOM_Anonymizer|a separate article]].<br />
<br />
To enable the anonymizer, select <b>yes</b> in the <b>Anonymizer Enabled</b> field.<br />
<br />
<b>Important Note:</b> 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.<br />
<br />
===Configuring the Garbage Collector===<br />
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 <b>Shared File Cabinet Timeout (hours)</b> 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.<br />
<br />
===Saving Configuration Changes===<br />
To save the changes you have made to the configuration, click the <b>Update fileservice.xml</b> button. Changes do not become effective until they are saved. <br />
<br />
Anonymizer script changes are saved on the Anonymizer Configurator and do not require a separate button click on the Admin page.<br />
<br />
===Starting the DICOM Service===<br />
If the Autostart field contains <b>yes</b>, the DICOM Service is started when Tomcat starts and the MIRC site is initialized. If the Autostart field does not contain <b>yes</b>, you can start the DICOM Service by clicking the <b>Start/Restart the DICOM Service</b> button.<br />
<br />
<b>Caution:</b> Whenever you make changes to the DICOM Service configuration, you must save those changes by clicking the <b>Update fileservice.xml</b> 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.<br />
<br />
===Managing the Shared File Cabinet===<br />
Users who do not possess the <b>FS-admin</b> 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 <b>FS-admin</b> role can any delete files from the shared file cabinet.<br />
<br />
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.<br />
<br />
==System-Level Services==<br />
There are several system-level servlets that are a convenience for administrators. They can be accessed through the admin page of any Storage Service.<br />
===Log Viewer===<br />
The Log Viewer provides browser access to the log files in <b>Tomcat/logs</b>. Only log files with non-zero sizes are listed, and the listing is in reverse chronological order, making it easy to find current logs.<br />
===Controller===<br />
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.<br />
<br />
==Appendix: MIRC URL Index==<br />
This section indexes all the URLs recognized by a MIRC site. In the listing below, the following notations are used:<br />
*All URLS are assumed to begin with the value of the <b>siteurl</b> entity in the query service's <b>mirc.xml</b> file. For brevity, this part of the URL is not shown.<br />
*<b>[SSName]</b> refers to the name of a storage service.<br />
*<b>[path]</b> refers to a path.<br />
*<b>[filename]</b> refers to the name of a file.<br />
*<b>[username]</b> refers to the account name for a user.<br />
*Text not in square brackets is a fixed part of the URL. <br />
<br />
===Query Service URLs===<br />
*<tt>/mirc/query</tt> - the non-authenticated query service<br />
*<tt>/mirc/auth</tt> - the authenticated query service<br />
*<tt>/mirc/news</tt> - get the current news item (Case of the Day)<br />
*<tt>/mirc/news/add?link=...&title=...&description=...&image=...</tt> - add an item to the the news listing<br />
*<tt>/mirc/news/remove?link=...</tt> - remove an item from the the news listing<br />
*<tt>/mirc/news/listing</tt> - get HTML code referencing the current news item (for inclusion on a web page)<br />
*<tt>/mirc/news/news.rss</tt> - the RSS news feed<br />
<br />
===Storage Service URLs===<br />
<br />
===File Service URLs===<br />
Certain File Service URLs can contain a query string listing a set of filenames separated by pipe characters, in the form:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><tt>?list=[filename1]|[filename2]|...|[filenameN]</tt></b><br>In the listing below, this is abbreviated by <b><tt>?list=</tt></b>.<br />
*<tt>/file/service</tt> - the personal file cabinet of the authenticated user<br />
*<tt>/file/service/tome?list=</tt> - copy files from the shared file cabinet to the user's file cabinet <br />
*<tt>/file/service/users/[username]/files/[filename]</tt> - a file in a user's file cabinet<br />
*<tt>/file/service/users/[username]/icons/[filename]</tt> - an icon file in a user's file cabinet<br />
*<tt>/file/service/add</tt> - add a file to the user's file cabinet<br />
*<tt>/file/service/delete?list=</tt> - delete files from the user's file cabinet<br />
*<tt>/file/service/export?list=</tt> - export files from the user's file cabinet as a zip file<br />
*<tt>/file/service/update?text=...&list=</tt> - update the keywords text of files in the user's file cabinet<br />
*<tt>/file/service/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the user's file cabinet<br />
*<tt>/file/service/dept</tt> - the shared file cabinet<br />
*<tt>/file/service/todept?list=</tt> - copy files from the user's file cabinet to the shared file cabinet<br />
*<tt>/file/service/dept/files/[filename]</tt> - a file in the shared file cabinet<br />
*<tt>/file/service/dept/icons/[filename]</tt> - an icon file in the shared file cabinet<br />
*<tt>/file/service/dept/add</tt> - add a file to the shared file cabinet<br />
*<tt>/file/service/dept/delete?list=</tt> - delete files from the shared file cabinet<br />
*<tt>/file/service/dept/export?list=</tt> - export files from the shared file cabinet as a zip file<br />
*<tt>/file/service/dept/update?text=...&list=</tt> - update the keywords text of files in the shared file cabinet<br />
*<tt>/file/service/dept/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the shared file cabinet<br />
*<tt>/file/service/common/[filename]</tt> - a standard icon file<br />
<br />
===Admin URLs===<br />
*<tt>/mircadmin/controller</tt> - the controller servlet<br />
*<tt>/mircadmin/logviewer</tt> - the log viewer servlet<br />
*<tt>/mircadmin/logviewer/[filename]</tt> - display a specific log file<br />
*<tt>/mircadmin/users</tt> - the user role manager servlet<br />
*<tt>/mircadmin/user</tt> - the user account manager servlet<br />
<br />
==Appendix: System Block Diagram==<br />
[[Image:RsnaMircBlockDiagram-1.GIF]]</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=MIRC_Administrator%27s_Manual&diff=2053MIRC Administrator's Manual2006-08-14T12:36:26Z<p>209.242.55.28: /* The storage.xml File */</p>
<hr />
<div>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. <br />
<br />
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.<br />
<br />
==Installation==<br />
The current official release version is T28. Installation instructions can be found at http://mirc.rsna.org/mircstorage/documents/T28/MIRCdocument.xml. <br />
<br />
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.<br />
<br />
==Query Service Administration==<br />
===System-level Modes===<br />
There are two operating modes which cannot be changed during operation of the system:<br />
* the system mode<br />
* the addressing mode<br />
Both modes are defined in the Query Service's configuration file, which is located in <b>Tomcat/webapps/mirc/mirc.xml</b>. At the top of the file is a <b>DOCTYPE</b> declaration containing several entities:<br />
<pre><br />
<!DOCTYPE mirc [<br />
<!ENTITY mode "rad"><br />
<!ENTITY sitename "P4"><br />
<!ENTITY addresstype "dynamic"><br />
<!ENTITY siteurl "http://192.168.0.96:8080"><br />
<!ENTITY queryurl "&siteurl;/mirc"><br />
<!ENTITY storageurl "&siteurl;/mircstorage"><br />
<!ENTITY mircforum "http://forums.rsna.org/forumdisplay.php?forumid=9"><br />
<!ENTITY mircdocs "http://mircwiki.rsna.org"><br />
<!ENTITY radlex "http://mirc.rsna.org/radlex/service"><br />
<!ENTITY tcusersclass "org.rsna.mircsite.util.TomcatUsersXmlFileImpl"><br />
<!ENTITY acctenb "yes"><br />
<!ENTITY defroles "QS-user,FS-user,SS-user,SS-author"><br />
<!ENTITY gpenb "yes"><br />
<!ENTITY version "T29alpha"> ]><br />
</pre><br />
<br />
====Setting the System Mode====<br />
The system mode is defined by the <b>mode</b> entity. The currently supported modes are:<br />
*<b>rad</b>: radiology<br />
*<b>vet</b>: veterinary medicine<br />
The choice of system mode configures the enumerated values for sexes, races, species, and breeds. These parameters, among many others, are stored in <b>Tomcat/webapps/mirc/enumerated-values.xml</b>.<br />
<br />
The software is preconfigured for <b>rad</b> mode. To change to <b>vet</b> mode, it is necessary to edit the <b>mirc.xml</b> file with a text editor and change the value of the <b>mode</b> entity. <br />
<br />
If operating in <b>vet</b> 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 <b>enumerated-values.xml</b> 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.<br />
<br />
====Setting the Addressing Mode====<br />
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.<br />
<br />
=====Dynamic vs. Static IP Addressing=====<br />
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.<br />
<br />
The way the MIRC software obtains the IP address is determined by the <b>addresstype</b> entity. The entity can have two possible values, <b>dynamic</b> or <b>static</b>. If the value is <b>dynamic</b>, 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. <br />
<br />
If the value of the <b>addresstype</b> entity is <b>static</b>, the software obtains the IP address from the <b>siteurl</b> entity. The <b>siteurl</b> entity can contain a numeric IP address or a domain name address. <br />
<br />
If <b>dynamic</b> addressing is used, the IP address specified in the <b>siteurl</b> entity must be numeric; otherwise, the method which obtains the IP address from the operating system will refuse to overwrite it.<br />
<br />
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.<br />
<br />
=====Reconfiguring the IP Address=====<br />
To change the IP addressing method after installation of the system, change the value of the <b>addresstype</b> entity using a text editor. If static addressing is employed, put the static IP address of the host in the value of the <b>siteurl</b> entity.<br />
<br />
Important: The protocol and port fields in the <b>siteurl</b> entity are always used, even in the case of dynamic addressing, so they must be set correctly in all cases.<br />
<br />
If an alphabetic value is inserted in the IP address field of the <b>siteurl</b> 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.<br />
<br />
====Restarting the System====<br />
After changing the system mode or the addressing mode, it is necessary to restart Tomcat in order to force the <b>init</b> methods of the MIRC servlets to run and reload the new enumerated values and/or IP address.<br />
<br />
===Setting the Authentication Requirements===<br />
The Query Service receives connections on two URLs:<br />
*<b>[siteurl]/mirc/auth</b> authenticates the user (forces a challenge for the user's credentials).<br />
*<b>[siteurl]/mirc/query</b> does not authenticate the user.<br />
<br />
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 <b>/query/auth</b> URL or by clicking the <b>Login</b> button on the query page.<br />
<br />
To be authenticated on the query service, you must have the <b>QS-user</b> role. When you upgrade, the installer will offer to add that role to the <b>admin</b> account, but for other users, you will have to add it manually with the User Role Manager.<br />
<br />
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 <b>index.html</b> page and change the URL in the redirection element.<br />
<br />
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) <u>on that storage service</u> 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 <b>passport</b>. A passport is managed by the passport's owner (the user) via the User Account Manager. A passport consists of a collection of <b>visas</b>, 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.<br />
<br />
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.<br />
<br />
===The Case of the Day===<br />
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 <b>Case of the Day</b> button in the table at the bottom of the document (or at the bottom of the <b>Document</b> tab).<br />
<br />
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.<br />
<br />
The latest Case of the Day can always be accessed by clicking the image in the lower left corner of the query page.<br />
<br />
==Controlling Users and Groups==<br />
Starting with Release T29, MIRC includes a User Account Manager that, when enabled by the administrator, allows users to create groups (and even accounts). <br />
<br />
===Groups===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===The User Role Manager===<br />
The User Role Manager, which can only be accessed by an administrator, has been changed so that it only manages:<br />
* the creation of new users <br />
* the removal of old users<br />
* the administrative roles<br />
<br />
Administrative roles are those that confer access to servlets or to MIRC behavior (like the <b>publisher</b> role and the various <b>admin</b> roles for Storage Services and the File Service).<br />
<br />
===The User Account Manager===<br />
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 (<b>admin</b>).<br />
<br />
To manage account and group creation, go to the query page, click the <b>Login</b> button and log in to an <b>admin</b> account. Then click the <b>My Account</b> button. The resulting page will contain several sections, each described by a little text telling you what to do. You can:<br />
*change your password on the server;<br />
*create visas for yourself;<br />
*resign from any or all groups;<br />
*join a group (if you know its name and password);<br />
*create a group, giving it a name and a password;<br />
*control whether account creation and/or group creation are enabled on the site;<br />
*define the administrative roles that are granted to users who create their own accounts.<br />
<br />
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.<br />
<br />
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 <b>user</b> and <b>author</b> roles for the File Service and the Storage Service to which you want to restrict the user (typically <b>QS-user</b>, <b>FS-user</b>, <b>SS-user</b> and <b>SS-author</b>). 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 <b>XX</b>, and then set the administrative roles for new users to be <b>QS-user</b>, <b>FS-user</b>, <b>XX-user</b> and <b>XX-author</b>. Note that since there is only one Query Service and one File Service on a MIRC site, you will always assign the <b>QS-user</b> and <b>FS-user</b> roles, no matter what the prefix is for the storage service.<br />
<br />
Group creation is independent of account creation and is separately enabled. Thus, you can disable account creation while still allowing group creation.<br />
<br />
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 <b>Submit</b> button, the visa for those services will be created.<br />
<br />
==Storage Service Administration==<br />
===The storage.xml File===<br />
Each storage service is a separate web application (webapp). The principal configuration parameters are contained in the <b>storage.xml</b> file, which is located in the root directory of the storage service (<b>Tomcat/webapps/[SSName]</b>. The following is the complete text of the file as it is first installed:<br />
<pre><br />
<?xml version="1.0" encoding="iso-8859-1"?><br />
<br />
<!DOCTYPE storage [<br />
<!ENTITY siteurl "http://192.168.0.98:8080"><br />
<!ENTITY servletname "mircstorage"><br />
<!ENTITY docauthoring "yes"><br />
<!ENTITY authorindex "yes"><br />
<!ENTITY docsubmission "yes"><br />
<!ENTITY maxsize "100"><br />
<!ENTITY autoindex "yes"><br />
<!ENTITY zipsubmission "yes"><br />
<!ENTITY zipmaxsize "100"><br />
<!ENTITY zipautoindex "yes"><br />
<!ENTITY philog "yes"><br />
<!ENTITY philogexport "no"><br />
<!ENTITY philogexporturl ""><br />
<!ENTITY dicomenable "no"><br />
<!ENTITY tceenable "no"><br />
<!ENTITY tagline ""><br />
<!ENTITY sitename "Storage Service"><br />
<!ENTITY querymode "open"><br />
<!ENTITY version "00"> ]><br />
<br />
<!-- ***** End of the section to configure on installation ***** --><br />
<br />
<storage><br />
<br />
<service docbase="&siteurl;/&servletname;/" querymode="&querymode;"/><br />
<br />
<phi-access-log enabled="&philog;"<br />
export="&philogexport;"<br />
url="&philogexporturl;"/><br />
<br />
<tagline>&tagline;</tagline><br />
<br />
<sitename>&sitename;</sitename><br />
<br />
<submit-service><br />
<doc enabled="&docsubmission;"<br />
maxsize="&maxsize;"<br />
autoindex="&autoindex;"/><br />
<zip enabled="&zipsubmission;"<br />
maxsize="&zipmaxsize;"<br />
autoindex="&zipautoindex;"/><br />
</submit-service><br />
<br />
<author-service enabled="&docauthoring;" autoindex="&authorindex;"><br />
<pageheader><br />
<div style="width:100%; border:0"><br />
<img src="MIRCheaderbackground.jpg" /><br />
</div><br />
<div style="position:absolute;left:0;top:0;width:100%"><br />
<table width="100%" border="0"><br />
<tr><br />
<td align="right" valign="top"><br />
<font face="verdana" size="+3" color="darkslateblue"><br />
<p style="margin-top:10"><br />
<b>&sitename;</b><br />
</p><br />
</font><br />
</td><br />
<td align="right" valign="center" width="100"><br />
<p style="margin-top:5; margin-bottom=0"></p><br />
<table cellspacing="0" border="0"><br />
<tr class="row"><td class="row"><b>Version &version;</b></td></tr><br />
</table><br />
</td><br />
</tr><br />
</table><br />
</div><br />
<hr class="headerbottom" /><br />
</pageheader><br />
<br />
<template name="templates/doc-template-mstf2.xml"><br />
Simple Teaching File Template<br />
</template><br />
<template name="templates/doc-template-mstf3.xml"><br />
Simple Teaching File Template for Boards Preparation - dark background<br />
</template><br />
<template name="templates/doc-template-mstf4.xml"><br />
Simple Teaching File Template for Boards Preparation - light background<br />
</template><br />
<template name="templates/doc-template-mstf.xml"><br />
Standard Teaching File Template<br />
</template><br />
<template name="templates/doc-template-page.xml"><br />
Page-format Document Template<br />
</template><br />
<template name="templates/doc-template-tab.xml"><br />
Tab-format Document Template<br />
</template><br />
<template name="templates/doc-template-tab2.xml"><br />
Tab-format Document Template with Special Image Section<br />
</template><br />
<template name="templates/doc-template-tab3.xml"><br />
Simple Tab-format Document Template for Boards Preparation<br />
</template><br />
</author-service><br />
<br />
<dicom-service enabled="&dicomenable;"/><br />
<tce-service enabled="&tceenable;"/><br />
<br />
</storage><br />
</pre><br />
<br />
* The key parameters are configured by the installer when the software is installed. <br />
* Most of the parameters can be changed at any time using the <b>Storage Service Configurator</b>, which is described below.<br />
* The author service templates are managed as described in the Author Service section.<br />
<br />
===The siteindex.xml File===<br />
The storage service maintains a list of its active documents in a file described in a [[The Storage Service Index File|separate article]]. When the Storage Service starts, it builds an index from the contents of the documents listed in this file.<br />
<br />
See also [[Data Mining the MIRC Index]].<br />
<br />
===The Admin Service===<br />
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 <b>Admin Service</b> button. The resulting page contains a set of buttons as shown below, and an area in which various functions display their results.<br />
<br />
<br />
[[Image:AdminButtons1.JPG]]<br />
<br />
<br />
The following is a brief summary of each of the buttons' functions:<br />
*Left Column<br />
**<b>Status</b> - displays the key parameter settings<br />
**<b>List Input Queue</b> - displays the list of documents that have been requested to be made public by users who do not have the <b>publisher</b> role. Documents only enter the queue if autoindexing is not enabled on the Storage Service.<br />
**<b>File Service Admin</b> - a convenience link to the Admin Service of the File Service.<br />
*Storage Service Column<br />
**<b>Update Configuration</b> - links to the Storage Service Configurator, providing access to most of the Storage Service configuration parameters.<br />
**<b>List Index</b> - lists the documents currently in the index, with links allowing them to be viewed, deleted, or edited.<br />
**<b>Reload Index</b> - forces the Storage Service to reload its index from the siteindex.xml file.<br />
**<b>Rebuild Index</b> - creates a new siteindex.xml file by walking the directory tree under the <b>documents</b> directory and finding all the MIRCdocuments.<br />
**<b>Save Index</b> - saves the current index in <b>saved-index-file.xml</b> in the root directory of the Storage Service.<br />
*TCE Service Column<br />
**<b>Update Configuration</b> - links to the TCE Service Configurator, providing access to its DICOM Service parameters.<br />
**<b>Start/Restart</b> - starts the TCE Service's DICOM Service.<br />
**<b>Show Log</b> - displays the Storage Service's circular buffer of log entries from all its DICOM Services.<br />
**<b>Clear Log</b> - clears the circular log buffer.<br />
*DICOM Service Column<br />
**<b>Update Configuration</b> - links to the DICOM Service Configurator, providing access to the parameters used in clinical trials.<br />
**<b>Start/Restart</b> - starts the DICOM Service.<br />
**<b>Show Log</b> - 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.<br />
**<b>Clear Log</b> - clears the circular log buffer. This button does the same thing as the corresponding button in the TCE Service column.<br />
*Tomcat Column<br />
**<b>User Role Manager</b> - a convenience link to the MIRC User Role Manager servlet.<br />
**<b>Controller</b> - a convenience link to the MIRC Controller servlet.<br />
**<b>Log Viewer</b> - a convenience link to the Log Viewer servlet.<br />
[[Image:SSConfigurator1.JPG|frame|]]<br />
====The Storage Service Configurator====<br />
<br />
The Storage Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
Most of the parameters in the configurator are discussed in sections related to the services to which they apply. The others are discussed below.<br />
=====Query Mode=====<br />
The storage service can be configured to operate in one of two query modes:<br />
*<b>open</b> 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.<br />
*<b>restricted</b> sets the service to return only those results that match a query and for which the user is authorized to view the documents. <br />
<br />
In <b>restricted</b> mode, if a user is not authenticated in the query, the storage service only returns results for public documents.<br />
<br />
=====Site Name=====<br />
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.<br />
<br />
=====Tag Line=====<br />
The Tag Line is the text that is displayed under the name of the Storage Service in the list of query results.<br />
<br />
=====PHI Logging=====<br />
Storage Services have the ability to log accesses to MIRCdocuments that contain protected health information. Two kinds of logging are supported:<br />
* <b>PHI Access Log Enabled</b> determines whether the Storage Service logs PHI accesses in a local log file contained in the <b>access-logs</b> subdirectory of the root of the Storage Service. This log is a simple text file.<br />
* <b>PHI Access Log Export Enabled</b> 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 <b>PHI Access Log Export URL</b> field.<br />
<br />
===Author Service===<br />
====The Standard Templates====<br />
===Submit Service===<br />
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 <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Submit Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Submit Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Submit Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are received by the Submit Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Submit Service Autoindex</b> field. <br />
<br />
You can also control the maximum size of any submission. On initial installation, the default is set to <b>100MB</b>. To change the size, edit the <b>Maximum Submission Size (MB)</b> field.<br />
<br />
===Zip Service===<br />
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 <b>Tomcat/webapps/[storageservice]/submit/template.xml</b>. 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.<br />
<br />
The Zip Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Zip Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Zip Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Zip Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are created by the Zip Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Zip Service Autoindex</b> field. <br />
<br />
See [[The Zip Service User's Manual]] for more information.<br />
<br />
===TCE Service===<br />
[[Image:TCEConfigurator1.JPG|frame|]]<br />
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 <b>Tomcat/webapps/[storageservice]/tce/template.xml</b>. 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.<br />
<br />
The TCE Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the TCE Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>TCE Service Enabled</b> field.<br />
<br />
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.<br />
<br />
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 <b>Update Configuration</b> button in the <b>TCE Service</b> column on the Storage Service's admin page:<br />
*<b>autostart</b> - determines whether the service is automatically started when Tomcat starts. <br />
*<b>Store AE Title</b> - sets the application entity title for the TCE Service's DICOM Service. It should be unique in the entire MIRC environment.<br />
*<b>Store Port</b> - sets the port on which the DICOM Service listens for associations.<br />
Changes to these parameters are not recorded until the <b>Update tce.xml</b> button is clicked.<br />
<br />
To start the DICOM Service, or to restart it after changes have been made to its parameters, you must click the <b>Start/Restart</b> button in the <b>TCE Service</b> column on the admin page.<br />
<br />
===DICOM Service===<br />
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.<br />
<br />
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.<br />
<br />
For complete documentation on the DICOM Service, see the [[Clinical Trial Administrator's Manual]].<br />
<br />
==File Service Administration==<br />
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.<br />
===Controlling Access to the File Service===<br />
Each authenticated user who has the <b>FS-user</b> role is provided a personal file cabinet which only that user can access. In addition, all authenticated users with the <b>FS-user</b> role can access the shared file cabinet. Only users with the <b>FS-admin</b> role can access the File Service Admin page and configure the File Service.<br />
===Accessing the File Service Admin Page===<br />
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 <b>Admin Service</b> button on the right side of the window.<br />
<br />
On the Admin page, click the <b>File Service Admin</b> button. The result will be a page as shown below.<br />
<br />
[[Image:FileServiceAdmin1.JPG|frame|]]<br />
<br />
===Configuring the DICOM Service===<br />
The File Service has its own DICOM Service which receives DICOM objects, optionally anonymizes them, and places them in the shared file cabinet.<br />
<br />
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.<br />
<br />
If you want the DICOM Service to start automatically when the MIRC site is initialized, select <b>yes</b> in the <b>Autostart</b> field.<br />
<br />
After changing the configuration of the DICOM Service, you must first click the <b>Update fileservice.xml</b> button to save the changes, and then click the <b>Start/restart the DICOM Service</b> button to make the DICOM Service recognize them.<br />
<br />
===Configuring the Anonymizer===<br />
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 <b>Update the Anonymizer</b> button. The configuration and operation of the Anonymizer Configurator is described in [[The_MIRC_DICOM_Anonymizer|a separate article]].<br />
<br />
To enable the anonymizer, select <b>yes</b> in the <b>Anonymizer Enabled</b> field.<br />
<br />
<b>Important Note:</b> 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.<br />
<br />
===Configuring the Garbage Collector===<br />
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 <b>Shared File Cabinet Timeout (hours)</b> 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.<br />
<br />
===Saving Configuration Changes===<br />
To save the changes you have made to the configuration, click the <b>Update fileservice.xml</b> button. Changes do not become effective until they are saved. <br />
<br />
Anonymizer script changes are saved on the Anonymizer Configurator and do not require a separate button click on the Admin page.<br />
<br />
===Starting the DICOM Service===<br />
If the Autostart field contains <b>yes</b>, the DICOM Service is started when Tomcat starts and the MIRC site is initialized. If the Autostart field does not contain <b>yes</b>, you can start the DICOM Service by clicking the <b>Start/Restart the DICOM Service</b> button.<br />
<br />
<b>Caution:</b> Whenever you make changes to the DICOM Service configuration, you must save those changes by clicking the <b>Update fileservice.xml</b> 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.<br />
<br />
===Managing the Shared File Cabinet===<br />
Users who do not possess the <b>FS-admin</b> 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 <b>FS-admin</b> role can any delete files from the shared file cabinet.<br />
<br />
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.<br />
<br />
==System-Level Services==<br />
There are several system-level servlets that are a convenience for administrators. They can be accessed through the admin page of any Storage Service.<br />
===Log Viewer===<br />
The Log Viewer provides browser access to the log files in <b>Tomcat/logs</b>. Only log files with non-zero sizes are listed, and the listing is in reverse chronological order, making it easy to find current logs.<br />
===Controller===<br />
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.<br />
<br />
==Appendix: MIRC URL Index==<br />
This section indexes all the URLs recognized by a MIRC site. In the listing below, the following notations are used:<br />
*All URLS are assumed to begin with the value of the <b>siteurl</b> entity in the query service's <b>mirc.xml</b> file. For brevity, this part of the URL is not shown.<br />
*<b>[SSName]</b> refers to the name of a storage service.<br />
*<b>[path]</b> refers to a path.<br />
*<b>[filename]</b> refers to the name of a file.<br />
*<b>[username]</b> refers to the account name for a user.<br />
*Text not in square brackets is a fixed part of the URL. <br />
<br />
===Query Service URLs===<br />
*<tt>/mirc/query</tt> - the non-authenticated query service<br />
*<tt>/mirc/auth</tt> - the authenticated query service<br />
*<tt>/mirc/news</tt> - get the current news item (Case of the Day)<br />
*<tt>/mirc/news/add?link=...&title=...&description=...&image=...</tt> - add an item to the the news listing<br />
*<tt>/mirc/news/remove?link=...</tt> - remove an item from the the news listing<br />
*<tt>/mirc/news/listing</tt> - get HTML code referencing the current news item (for inclusion on a web page)<br />
*<tt>/mirc/news/news.rss</tt> - the RSS news feed<br />
<br />
===Storage Service URLs===<br />
<br />
===File Service URLs===<br />
Certain File Service URLs can contain a query string listing a set of filenames separated by pipe characters, in the form:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><tt>?list=[filename1]|[filename2]|...|[filenameN]</tt></b><br>In the listing below, this is abbreviated by <b><tt>?list=</tt></b>.<br />
*<tt>/file/service</tt> - the personal file cabinet of the authenticated user<br />
*<tt>/file/service/tome?list=</tt> - copy files from the shared file cabinet to the user's file cabinet <br />
*<tt>/file/service/users/[username]/files/[filename]</tt> - a file in a user's file cabinet<br />
*<tt>/file/service/users/[username]/icons/[filename]</tt> - an icon file in a user's file cabinet<br />
*<tt>/file/service/add</tt> - add a file to the user's file cabinet<br />
*<tt>/file/service/delete?list=</tt> - delete files from the user's file cabinet<br />
*<tt>/file/service/export?list=</tt> - export files from the user's file cabinet as a zip file<br />
*<tt>/file/service/update?text=...&list=</tt> - update the keywords text of files in the user's file cabinet<br />
*<tt>/file/service/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the user's file cabinet<br />
*<tt>/file/service/dept</tt> - the shared file cabinet<br />
*<tt>/file/service/todept?list=</tt> - copy files from the user's file cabinet to the shared file cabinet<br />
*<tt>/file/service/dept/files/[filename]</tt> - a file in the shared file cabinet<br />
*<tt>/file/service/dept/icons/[filename]</tt> - an icon file in the shared file cabinet<br />
*<tt>/file/service/dept/add</tt> - add a file to the shared file cabinet<br />
*<tt>/file/service/dept/delete?list=</tt> - delete files from the shared file cabinet<br />
*<tt>/file/service/dept/export?list=</tt> - export files from the shared file cabinet as a zip file<br />
*<tt>/file/service/dept/update?text=...&list=</tt> - update the keywords text of files in the shared file cabinet<br />
*<tt>/file/service/dept/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the shared file cabinet<br />
*<tt>/file/service/common/[filename]</tt> - a standard icon file<br />
<br />
===Admin URLs===<br />
*<tt>/mircadmin/controller</tt> - the controller servlet<br />
*<tt>/mircadmin/logviewer</tt> - the log viewer servlet<br />
*<tt>/mircadmin/logviewer/[filename]</tt> - display a specific log file<br />
*<tt>/mircadmin/users</tt> - the user role manager servlet<br />
*<tt>/mircadmin/user</tt> - the user account manager servlet<br />
<br />
==Appendix: System Block Diagram==<br />
[[Image:RsnaMircBlockDiagram-1.GIF]]</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=MIRC_Administrator%27s_Manual&diff=2052MIRC Administrator's Manual2006-08-14T12:25:07Z<p>209.242.55.28: /* Installation */</p>
<hr />
<div>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. <br />
<br />
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.<br />
<br />
==Installation==<br />
The current official release version is T28. Installation instructions can be found at http://mirc.rsna.org/mircstorage/documents/T28/MIRCdocument.xml. <br />
<br />
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.<br />
<br />
==Query Service Administration==<br />
===System-level Modes===<br />
There are two operating modes which cannot be changed during operation of the system:<br />
* the system mode<br />
* the addressing mode<br />
Both modes are defined in the Query Service's configuration file, which is located in <b>Tomcat/webapps/mirc/mirc.xml</b>. At the top of the file is a <b>DOCTYPE</b> declaration containing several entities:<br />
<pre><br />
<!DOCTYPE mirc [<br />
<!ENTITY mode "rad"><br />
<!ENTITY sitename "P4"><br />
<!ENTITY addresstype "dynamic"><br />
<!ENTITY siteurl "http://192.168.0.96:8080"><br />
<!ENTITY queryurl "&siteurl;/mirc"><br />
<!ENTITY storageurl "&siteurl;/mircstorage"><br />
<!ENTITY mircforum "http://forums.rsna.org/forumdisplay.php?forumid=9"><br />
<!ENTITY mircdocs "http://mircwiki.rsna.org"><br />
<!ENTITY radlex "http://mirc.rsna.org/radlex/service"><br />
<!ENTITY tcusersclass "org.rsna.mircsite.util.TomcatUsersXmlFileImpl"><br />
<!ENTITY acctenb "yes"><br />
<!ENTITY defroles "QS-user,FS-user,SS-user,SS-author"><br />
<!ENTITY gpenb "yes"><br />
<!ENTITY version "T29alpha"> ]><br />
</pre><br />
<br />
====Setting the System Mode====<br />
The system mode is defined by the <b>mode</b> entity. The currently supported modes are:<br />
*<b>rad</b>: radiology<br />
*<b>vet</b>: veterinary medicine<br />
The choice of system mode configures the enumerated values for sexes, races, species, and breeds. These parameters, among many others, are stored in <b>Tomcat/webapps/mirc/enumerated-values.xml</b>.<br />
<br />
The software is preconfigured for <b>rad</b> mode. To change to <b>vet</b> mode, it is necessary to edit the <b>mirc.xml</b> file with a text editor and change the value of the <b>mode</b> entity. <br />
<br />
If operating in <b>vet</b> 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 <b>enumerated-values.xml</b> 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.<br />
<br />
====Setting the Addressing Mode====<br />
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.<br />
<br />
=====Dynamic vs. Static IP Addressing=====<br />
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.<br />
<br />
The way the MIRC software obtains the IP address is determined by the <b>addresstype</b> entity. The entity can have two possible values, <b>dynamic</b> or <b>static</b>. If the value is <b>dynamic</b>, 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. <br />
<br />
If the value of the <b>addresstype</b> entity is <b>static</b>, the software obtains the IP address from the <b>siteurl</b> entity. The <b>siteurl</b> entity can contain a numeric IP address or a domain name address. <br />
<br />
If <b>dynamic</b> addressing is used, the IP address specified in the <b>siteurl</b> entity must be numeric; otherwise, the method which obtains the IP address from the operating system will refuse to overwrite it.<br />
<br />
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.<br />
<br />
=====Reconfiguring the IP Address=====<br />
To change the IP addressing method after installation of the system, change the value of the <b>addresstype</b> entity using a text editor. If static addressing is employed, put the static IP address of the host in the value of the <b>siteurl</b> entity.<br />
<br />
Important: The protocol and port fields in the <b>siteurl</b> entity are always used, even in the case of dynamic addressing, so they must be set correctly in all cases.<br />
<br />
If an alphabetic value is inserted in the IP address field of the <b>siteurl</b> 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.<br />
<br />
====Restarting the System====<br />
After changing the system mode or the addressing mode, it is necessary to restart Tomcat in order to force the <b>init</b> methods of the MIRC servlets to run and reload the new enumerated values and/or IP address.<br />
<br />
===Setting the Authentication Requirements===<br />
The Query Service receives connections on two URLs:<br />
*<b>[siteurl]/mirc/auth</b> authenticates the user (forces a challenge for the user's credentials).<br />
*<b>[siteurl]/mirc/query</b> does not authenticate the user.<br />
<br />
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 <b>/query/auth</b> URL or by clicking the <b>Login</b> button on the query page.<br />
<br />
To be authenticated on the query service, you must have the <b>QS-user</b> role. When you upgrade, the installer will offer to add that role to the <b>admin</b> account, but for other users, you will have to add it manually with the User Role Manager.<br />
<br />
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 <b>index.html</b> page and change the URL in the redirection element.<br />
<br />
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) <u>on that storage service</u> 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 <b>passport</b>. A passport is managed by the passport's owner (the user) via the User Account Manager. A passport consists of a collection of <b>visas</b>, 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.<br />
<br />
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.<br />
<br />
===The Case of the Day===<br />
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 <b>Case of the Day</b> button in the table at the bottom of the document (or at the bottom of the <b>Document</b> tab).<br />
<br />
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.<br />
<br />
The latest Case of the Day can always be accessed by clicking the image in the lower left corner of the query page.<br />
<br />
==Controlling Users and Groups==<br />
Starting with Release T29, MIRC includes a User Account Manager that, when enabled by the administrator, allows users to create groups (and even accounts). <br />
<br />
===Groups===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===The User Role Manager===<br />
The User Role Manager, which can only be accessed by an administrator, has been changed so that it only manages:<br />
* the creation of new users <br />
* the removal of old users<br />
* the administrative roles<br />
<br />
Administrative roles are those that confer access to servlets or to MIRC behavior (like the <b>publisher</b> role and the various <b>admin</b> roles for Storage Services and the File Service).<br />
<br />
===The User Account Manager===<br />
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 (<b>admin</b>).<br />
<br />
To manage account and group creation, go to the query page, click the <b>Login</b> button and log in to an <b>admin</b> account. Then click the <b>My Account</b> button. The resulting page will contain several sections, each described by a little text telling you what to do. You can:<br />
*change your password on the server;<br />
*create visas for yourself;<br />
*resign from any or all groups;<br />
*join a group (if you know its name and password);<br />
*create a group, giving it a name and a password;<br />
*control whether account creation and/or group creation are enabled on the site;<br />
*define the administrative roles that are granted to users who create their own accounts.<br />
<br />
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.<br />
<br />
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 <b>user</b> and <b>author</b> roles for the File Service and the Storage Service to which you want to restrict the user (typically <b>QS-user</b>, <b>FS-user</b>, <b>SS-user</b> and <b>SS-author</b>). 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 <b>XX</b>, and then set the administrative roles for new users to be <b>QS-user</b>, <b>FS-user</b>, <b>XX-user</b> and <b>XX-author</b>. Note that since there is only one Query Service and one File Service on a MIRC site, you will always assign the <b>QS-user</b> and <b>FS-user</b> roles, no matter what the prefix is for the storage service.<br />
<br />
Group creation is independent of account creation and is separately enabled. Thus, you can disable account creation while still allowing group creation.<br />
<br />
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 <b>Submit</b> button, the visa for those services will be created.<br />
<br />
==Storage Service Administration==<br />
===The storage.xml File===<br />
===The siteindex.xml File===<br />
The storage service maintains a list of its active documents in a file described in a [[The Storage Service Index File|separate article]]. When the Storage Service starts, it builds an index from the contents of the documents listed in this file.<br />
<br />
See also [[Data Mining the MIRC Index]].<br />
<br />
===The Admin Service===<br />
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 <b>Admin Service</b> button. The resulting page contains a set of buttons as shown below, and an area in which various functions display their results.<br />
<br />
<br />
[[Image:AdminButtons1.JPG]]<br />
<br />
<br />
The following is a brief summary of each of the buttons' functions:<br />
*Left Column<br />
**<b>Status</b> - displays the key parameter settings<br />
**<b>List Input Queue</b> - displays the list of documents that have been requested to be made public by users who do not have the <b>publisher</b> role. Documents only enter the queue if autoindexing is not enabled on the Storage Service.<br />
**<b>File Service Admin</b> - a convenience link to the Admin Service of the File Service.<br />
*Storage Service Column<br />
**<b>Update Configuration</b> - links to the Storage Service Configurator, providing access to most of the Storage Service configuration parameters.<br />
**<b>List Index</b> - lists the documents currently in the index, with links allowing them to be viewed, deleted, or edited.<br />
**<b>Reload Index</b> - forces the Storage Service to reload its index from the siteindex.xml file.<br />
**<b>Rebuild Index</b> - creates a new siteindex.xml file by walking the directory tree under the <b>documents</b> directory and finding all the MIRCdocuments.<br />
**<b>Save Index</b> - saves the current index in <b>saved-index-file.xml</b> in the root directory of the Storage Service.<br />
*TCE Service Column<br />
**<b>Update Configuration</b> - links to the TCE Service Configurator, providing access to its DICOM Service parameters.<br />
**<b>Start/Restart</b> - starts the TCE Service's DICOM Service.<br />
**<b>Show Log</b> - displays the Storage Service's circular buffer of log entries from all its DICOM Services.<br />
**<b>Clear Log</b> - clears the circular log buffer.<br />
*DICOM Service Column<br />
**<b>Update Configuration</b> - links to the DICOM Service Configurator, providing access to the parameters used in clinical trials.<br />
**<b>Start/Restart</b> - starts the DICOM Service.<br />
**<b>Show Log</b> - 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.<br />
**<b>Clear Log</b> - clears the circular log buffer. This button does the same thing as the corresponding button in the TCE Service column.<br />
*Tomcat Column<br />
**<b>User Role Manager</b> - a convenience link to the MIRC User Role Manager servlet.<br />
**<b>Controller</b> - a convenience link to the MIRC Controller servlet.<br />
**<b>Log Viewer</b> - a convenience link to the Log Viewer servlet.<br />
[[Image:SSConfigurator1.JPG|frame|]]<br />
====The Storage Service Configurator====<br />
<br />
The Storage Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
Most of the parameters in the configurator are discussed in sections related to the services to which they apply. The others are discussed below.<br />
=====Query Mode=====<br />
The storage service can be configured to operate in one of two query modes:<br />
*<b>open</b> 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.<br />
*<b>restricted</b> sets the service to return only those results that match a query and for which the user is authorized to view the documents. <br />
<br />
In <b>restricted</b> mode, if a user is not authenticated in the query, the storage service only returns results for public documents.<br />
<br />
=====Site Name=====<br />
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.<br />
<br />
=====Tag Line=====<br />
The Tag Line is the text that is displayed under the name of the Storage Service in the list of query results.<br />
<br />
=====PHI Logging=====<br />
Storage Services have the ability to log accesses to MIRCdocuments that contain protected health information. Two kinds of logging are supported:<br />
* <b>PHI Access Log Enabled</b> determines whether the Storage Service logs PHI accesses in a local log file contained in the <b>access-logs</b> subdirectory of the root of the Storage Service. This log is a simple text file.<br />
* <b>PHI Access Log Export Enabled</b> 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 <b>PHI Access Log Export URL</b> field.<br />
<br />
===Author Service===<br />
====The Standard Templates====<br />
===Submit Service===<br />
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 <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Submit Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Submit Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Submit Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are received by the Submit Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Submit Service Autoindex</b> field. <br />
<br />
You can also control the maximum size of any submission. On initial installation, the default is set to <b>100MB</b>. To change the size, edit the <b>Maximum Submission Size (MB)</b> field.<br />
<br />
===Zip Service===<br />
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 <b>Tomcat/webapps/[storageservice]/submit/template.xml</b>. 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.<br />
<br />
The Zip Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Zip Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Zip Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Zip Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are created by the Zip Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Zip Service Autoindex</b> field. <br />
<br />
See [[The Zip Service User's Manual]] for more information.<br />
<br />
===TCE Service===<br />
[[Image:TCEConfigurator1.JPG|frame|]]<br />
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 <b>Tomcat/webapps/[storageservice]/tce/template.xml</b>. 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.<br />
<br />
The TCE Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the TCE Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>TCE Service Enabled</b> field.<br />
<br />
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.<br />
<br />
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 <b>Update Configuration</b> button in the <b>TCE Service</b> column on the Storage Service's admin page:<br />
*<b>autostart</b> - determines whether the service is automatically started when Tomcat starts. <br />
*<b>Store AE Title</b> - sets the application entity title for the TCE Service's DICOM Service. It should be unique in the entire MIRC environment.<br />
*<b>Store Port</b> - sets the port on which the DICOM Service listens for associations.<br />
Changes to these parameters are not recorded until the <b>Update tce.xml</b> button is clicked.<br />
<br />
To start the DICOM Service, or to restart it after changes have been made to its parameters, you must click the <b>Start/Restart</b> button in the <b>TCE Service</b> column on the admin page.<br />
<br />
===DICOM Service===<br />
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.<br />
<br />
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.<br />
<br />
For complete documentation on the DICOM Service, see the [[Clinical Trial Administrator's Manual]].<br />
<br />
==File Service Administration==<br />
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.<br />
===Controlling Access to the File Service===<br />
Each authenticated user who has the <b>FS-user</b> role is provided a personal file cabinet which only that user can access. In addition, all authenticated users with the <b>FS-user</b> role can access the shared file cabinet. Only users with the <b>FS-admin</b> role can access the File Service Admin page and configure the File Service.<br />
===Accessing the File Service Admin Page===<br />
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 <b>Admin Service</b> button on the right side of the window.<br />
<br />
On the Admin page, click the <b>File Service Admin</b> button. The result will be a page as shown below.<br />
<br />
[[Image:FileServiceAdmin1.JPG|frame|]]<br />
<br />
===Configuring the DICOM Service===<br />
The File Service has its own DICOM Service which receives DICOM objects, optionally anonymizes them, and places them in the shared file cabinet.<br />
<br />
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.<br />
<br />
If you want the DICOM Service to start automatically when the MIRC site is initialized, select <b>yes</b> in the <b>Autostart</b> field.<br />
<br />
After changing the configuration of the DICOM Service, you must first click the <b>Update fileservice.xml</b> button to save the changes, and then click the <b>Start/restart the DICOM Service</b> button to make the DICOM Service recognize them.<br />
<br />
===Configuring the Anonymizer===<br />
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 <b>Update the Anonymizer</b> button. The configuration and operation of the Anonymizer Configurator is described in [[The_MIRC_DICOM_Anonymizer|a separate article]].<br />
<br />
To enable the anonymizer, select <b>yes</b> in the <b>Anonymizer Enabled</b> field.<br />
<br />
<b>Important Note:</b> 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.<br />
<br />
===Configuring the Garbage Collector===<br />
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 <b>Shared File Cabinet Timeout (hours)</b> 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.<br />
<br />
===Saving Configuration Changes===<br />
To save the changes you have made to the configuration, click the <b>Update fileservice.xml</b> button. Changes do not become effective until they are saved. <br />
<br />
Anonymizer script changes are saved on the Anonymizer Configurator and do not require a separate button click on the Admin page.<br />
<br />
===Starting the DICOM Service===<br />
If the Autostart field contains <b>yes</b>, the DICOM Service is started when Tomcat starts and the MIRC site is initialized. If the Autostart field does not contain <b>yes</b>, you can start the DICOM Service by clicking the <b>Start/Restart the DICOM Service</b> button.<br />
<br />
<b>Caution:</b> Whenever you make changes to the DICOM Service configuration, you must save those changes by clicking the <b>Update fileservice.xml</b> 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.<br />
<br />
===Managing the Shared File Cabinet===<br />
Users who do not possess the <b>FS-admin</b> 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 <b>FS-admin</b> role can any delete files from the shared file cabinet.<br />
<br />
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.<br />
<br />
==System-Level Services==<br />
There are several system-level servlets that are a convenience for administrators. They can be accessed through the admin page of any Storage Service.<br />
===Log Viewer===<br />
The Log Viewer provides browser access to the log files in <b>Tomcat/logs</b>. Only log files with non-zero sizes are listed, and the listing is in reverse chronological order, making it easy to find current logs.<br />
===Controller===<br />
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.<br />
<br />
==Appendix: MIRC URL Index==<br />
This section indexes all the URLs recognized by a MIRC site. In the listing below, the following notations are used:<br />
*All URLS are assumed to begin with the value of the <b>siteurl</b> entity in the query service's <b>mirc.xml</b> file. For brevity, this part of the URL is not shown.<br />
*<b>[SSName]</b> refers to the name of a storage service.<br />
*<b>[path]</b> refers to a path.<br />
*<b>[filename]</b> refers to the name of a file.<br />
*<b>[username]</b> refers to the account name for a user.<br />
*Text not in square brackets is a fixed part of the URL. <br />
<br />
===Query Service URLs===<br />
*<tt>/mirc/query</tt> - the non-authenticated query service<br />
*<tt>/mirc/auth</tt> - the authenticated query service<br />
*<tt>/mirc/news</tt> - get the current news item (Case of the Day)<br />
*<tt>/mirc/news/add?link=...&title=...&description=...&image=...</tt> - add an item to the the news listing<br />
*<tt>/mirc/news/remove?link=...</tt> - remove an item from the the news listing<br />
*<tt>/mirc/news/listing</tt> - get HTML code referencing the current news item (for inclusion on a web page)<br />
*<tt>/mirc/news/news.rss</tt> - the RSS news feed<br />
<br />
===Storage Service URLs===<br />
<br />
===File Service URLs===<br />
Certain File Service URLs can contain a query string listing a set of filenames separated by pipe characters, in the form:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><tt>?list=[filename1]|[filename2]|...|[filenameN]</tt></b><br>In the listing below, this is abbreviated by <b><tt>?list=</tt></b>.<br />
*<tt>/file/service</tt> - the personal file cabinet of the authenticated user<br />
*<tt>/file/service/tome?list=</tt> - copy files from the shared file cabinet to the user's file cabinet <br />
*<tt>/file/service/users/[username]/files/[filename]</tt> - a file in a user's file cabinet<br />
*<tt>/file/service/users/[username]/icons/[filename]</tt> - an icon file in a user's file cabinet<br />
*<tt>/file/service/add</tt> - add a file to the user's file cabinet<br />
*<tt>/file/service/delete?list=</tt> - delete files from the user's file cabinet<br />
*<tt>/file/service/export?list=</tt> - export files from the user's file cabinet as a zip file<br />
*<tt>/file/service/update?text=...&list=</tt> - update the keywords text of files in the user's file cabinet<br />
*<tt>/file/service/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the user's file cabinet<br />
*<tt>/file/service/dept</tt> - the shared file cabinet<br />
*<tt>/file/service/todept?list=</tt> - copy files from the user's file cabinet to the shared file cabinet<br />
*<tt>/file/service/dept/files/[filename]</tt> - a file in the shared file cabinet<br />
*<tt>/file/service/dept/icons/[filename]</tt> - an icon file in the shared file cabinet<br />
*<tt>/file/service/dept/add</tt> - add a file to the shared file cabinet<br />
*<tt>/file/service/dept/delete?list=</tt> - delete files from the shared file cabinet<br />
*<tt>/file/service/dept/export?list=</tt> - export files from the shared file cabinet as a zip file<br />
*<tt>/file/service/dept/update?text=...&list=</tt> - update the keywords text of files in the shared file cabinet<br />
*<tt>/file/service/dept/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the shared file cabinet<br />
*<tt>/file/service/common/[filename]</tt> - a standard icon file<br />
<br />
===Admin URLs===<br />
*<tt>/mircadmin/controller</tt> - the controller servlet<br />
*<tt>/mircadmin/logviewer</tt> - the log viewer servlet<br />
*<tt>/mircadmin/logviewer/[filename]</tt> - display a specific log file<br />
*<tt>/mircadmin/users</tt> - the user role manager servlet<br />
*<tt>/mircadmin/user</tt> - the user account manager servlet<br />
<br />
==Appendix: System Block Diagram==<br />
[[Image:RsnaMircBlockDiagram-1.GIF]]</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=MIRC_Administrator%27s_Manual&diff=2051MIRC Administrator's Manual2006-08-14T12:24:16Z<p>209.242.55.28: /* Installation */</p>
<hr />
<div>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. <br />
<br />
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.<br />
<br />
==Installation==<br />
The current official release version is T28. Installation instructions can be found at http://mirc.rsna.org/mircstorage/documents/T28/MIRCdocument.xml. <br />
<br />
The current beta version of T29, which is recommended for all users, can be downloaded at http://mirc.rsna.org/T29/MIRCsite-installer.jar. It is only available as a full installer. To upgrade, follow the T27 installation instructions, but use the T29 installer for the MIRC software part of the installation.<br />
<br />
==Query Service Administration==<br />
===System-level Modes===<br />
There are two operating modes which cannot be changed during operation of the system:<br />
* the system mode<br />
* the addressing mode<br />
Both modes are defined in the Query Service's configuration file, which is located in <b>Tomcat/webapps/mirc/mirc.xml</b>. At the top of the file is a <b>DOCTYPE</b> declaration containing several entities:<br />
<pre><br />
<!DOCTYPE mirc [<br />
<!ENTITY mode "rad"><br />
<!ENTITY sitename "P4"><br />
<!ENTITY addresstype "dynamic"><br />
<!ENTITY siteurl "http://192.168.0.96:8080"><br />
<!ENTITY queryurl "&siteurl;/mirc"><br />
<!ENTITY storageurl "&siteurl;/mircstorage"><br />
<!ENTITY mircforum "http://forums.rsna.org/forumdisplay.php?forumid=9"><br />
<!ENTITY mircdocs "http://mircwiki.rsna.org"><br />
<!ENTITY radlex "http://mirc.rsna.org/radlex/service"><br />
<!ENTITY tcusersclass "org.rsna.mircsite.util.TomcatUsersXmlFileImpl"><br />
<!ENTITY acctenb "yes"><br />
<!ENTITY defroles "QS-user,FS-user,SS-user,SS-author"><br />
<!ENTITY gpenb "yes"><br />
<!ENTITY version "T29alpha"> ]><br />
</pre><br />
<br />
====Setting the System Mode====<br />
The system mode is defined by the <b>mode</b> entity. The currently supported modes are:<br />
*<b>rad</b>: radiology<br />
*<b>vet</b>: veterinary medicine<br />
The choice of system mode configures the enumerated values for sexes, races, species, and breeds. These parameters, among many others, are stored in <b>Tomcat/webapps/mirc/enumerated-values.xml</b>.<br />
<br />
The software is preconfigured for <b>rad</b> mode. To change to <b>vet</b> mode, it is necessary to edit the <b>mirc.xml</b> file with a text editor and change the value of the <b>mode</b> entity. <br />
<br />
If operating in <b>vet</b> 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 <b>enumerated-values.xml</b> 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.<br />
<br />
====Setting the Addressing Mode====<br />
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.<br />
<br />
=====Dynamic vs. Static IP Addressing=====<br />
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.<br />
<br />
The way the MIRC software obtains the IP address is determined by the <b>addresstype</b> entity. The entity can have two possible values, <b>dynamic</b> or <b>static</b>. If the value is <b>dynamic</b>, 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. <br />
<br />
If the value of the <b>addresstype</b> entity is <b>static</b>, the software obtains the IP address from the <b>siteurl</b> entity. The <b>siteurl</b> entity can contain a numeric IP address or a domain name address. <br />
<br />
If <b>dynamic</b> addressing is used, the IP address specified in the <b>siteurl</b> entity must be numeric; otherwise, the method which obtains the IP address from the operating system will refuse to overwrite it.<br />
<br />
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.<br />
<br />
=====Reconfiguring the IP Address=====<br />
To change the IP addressing method after installation of the system, change the value of the <b>addresstype</b> entity using a text editor. If static addressing is employed, put the static IP address of the host in the value of the <b>siteurl</b> entity.<br />
<br />
Important: The protocol and port fields in the <b>siteurl</b> entity are always used, even in the case of dynamic addressing, so they must be set correctly in all cases.<br />
<br />
If an alphabetic value is inserted in the IP address field of the <b>siteurl</b> 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.<br />
<br />
====Restarting the System====<br />
After changing the system mode or the addressing mode, it is necessary to restart Tomcat in order to force the <b>init</b> methods of the MIRC servlets to run and reload the new enumerated values and/or IP address.<br />
<br />
===Setting the Authentication Requirements===<br />
The Query Service receives connections on two URLs:<br />
*<b>[siteurl]/mirc/auth</b> authenticates the user (forces a challenge for the user's credentials).<br />
*<b>[siteurl]/mirc/query</b> does not authenticate the user.<br />
<br />
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 <b>/query/auth</b> URL or by clicking the <b>Login</b> button on the query page.<br />
<br />
To be authenticated on the query service, you must have the <b>QS-user</b> role. When you upgrade, the installer will offer to add that role to the <b>admin</b> account, but for other users, you will have to add it manually with the User Role Manager.<br />
<br />
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 <b>index.html</b> page and change the URL in the redirection element.<br />
<br />
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) <u>on that storage service</u> 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 <b>passport</b>. A passport is managed by the passport's owner (the user) via the User Account Manager. A passport consists of a collection of <b>visas</b>, 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.<br />
<br />
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.<br />
<br />
===The Case of the Day===<br />
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 <b>Case of the Day</b> button in the table at the bottom of the document (or at the bottom of the <b>Document</b> tab).<br />
<br />
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.<br />
<br />
The latest Case of the Day can always be accessed by clicking the image in the lower left corner of the query page.<br />
<br />
==Controlling Users and Groups==<br />
Starting with Release T29, MIRC includes a User Account Manager that, when enabled by the administrator, allows users to create groups (and even accounts). <br />
<br />
===Groups===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===The User Role Manager===<br />
The User Role Manager, which can only be accessed by an administrator, has been changed so that it only manages:<br />
* the creation of new users <br />
* the removal of old users<br />
* the administrative roles<br />
<br />
Administrative roles are those that confer access to servlets or to MIRC behavior (like the <b>publisher</b> role and the various <b>admin</b> roles for Storage Services and the File Service).<br />
<br />
===The User Account Manager===<br />
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 (<b>admin</b>).<br />
<br />
To manage account and group creation, go to the query page, click the <b>Login</b> button and log in to an <b>admin</b> account. Then click the <b>My Account</b> button. The resulting page will contain several sections, each described by a little text telling you what to do. You can:<br />
*change your password on the server;<br />
*create visas for yourself;<br />
*resign from any or all groups;<br />
*join a group (if you know its name and password);<br />
*create a group, giving it a name and a password;<br />
*control whether account creation and/or group creation are enabled on the site;<br />
*define the administrative roles that are granted to users who create their own accounts.<br />
<br />
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.<br />
<br />
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 <b>user</b> and <b>author</b> roles for the File Service and the Storage Service to which you want to restrict the user (typically <b>QS-user</b>, <b>FS-user</b>, <b>SS-user</b> and <b>SS-author</b>). 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 <b>XX</b>, and then set the administrative roles for new users to be <b>QS-user</b>, <b>FS-user</b>, <b>XX-user</b> and <b>XX-author</b>. Note that since there is only one Query Service and one File Service on a MIRC site, you will always assign the <b>QS-user</b> and <b>FS-user</b> roles, no matter what the prefix is for the storage service.<br />
<br />
Group creation is independent of account creation and is separately enabled. Thus, you can disable account creation while still allowing group creation.<br />
<br />
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 <b>Submit</b> button, the visa for those services will be created.<br />
<br />
==Storage Service Administration==<br />
===The storage.xml File===<br />
===The siteindex.xml File===<br />
The storage service maintains a list of its active documents in a file described in a [[The Storage Service Index File|separate article]]. When the Storage Service starts, it builds an index from the contents of the documents listed in this file.<br />
<br />
See also [[Data Mining the MIRC Index]].<br />
<br />
===The Admin Service===<br />
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 <b>Admin Service</b> button. The resulting page contains a set of buttons as shown below, and an area in which various functions display their results.<br />
<br />
<br />
[[Image:AdminButtons1.JPG]]<br />
<br />
<br />
The following is a brief summary of each of the buttons' functions:<br />
*Left Column<br />
**<b>Status</b> - displays the key parameter settings<br />
**<b>List Input Queue</b> - displays the list of documents that have been requested to be made public by users who do not have the <b>publisher</b> role. Documents only enter the queue if autoindexing is not enabled on the Storage Service.<br />
**<b>File Service Admin</b> - a convenience link to the Admin Service of the File Service.<br />
*Storage Service Column<br />
**<b>Update Configuration</b> - links to the Storage Service Configurator, providing access to most of the Storage Service configuration parameters.<br />
**<b>List Index</b> - lists the documents currently in the index, with links allowing them to be viewed, deleted, or edited.<br />
**<b>Reload Index</b> - forces the Storage Service to reload its index from the siteindex.xml file.<br />
**<b>Rebuild Index</b> - creates a new siteindex.xml file by walking the directory tree under the <b>documents</b> directory and finding all the MIRCdocuments.<br />
**<b>Save Index</b> - saves the current index in <b>saved-index-file.xml</b> in the root directory of the Storage Service.<br />
*TCE Service Column<br />
**<b>Update Configuration</b> - links to the TCE Service Configurator, providing access to its DICOM Service parameters.<br />
**<b>Start/Restart</b> - starts the TCE Service's DICOM Service.<br />
**<b>Show Log</b> - displays the Storage Service's circular buffer of log entries from all its DICOM Services.<br />
**<b>Clear Log</b> - clears the circular log buffer.<br />
*DICOM Service Column<br />
**<b>Update Configuration</b> - links to the DICOM Service Configurator, providing access to the parameters used in clinical trials.<br />
**<b>Start/Restart</b> - starts the DICOM Service.<br />
**<b>Show Log</b> - 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.<br />
**<b>Clear Log</b> - clears the circular log buffer. This button does the same thing as the corresponding button in the TCE Service column.<br />
*Tomcat Column<br />
**<b>User Role Manager</b> - a convenience link to the MIRC User Role Manager servlet.<br />
**<b>Controller</b> - a convenience link to the MIRC Controller servlet.<br />
**<b>Log Viewer</b> - a convenience link to the Log Viewer servlet.<br />
[[Image:SSConfigurator1.JPG|frame|]]<br />
====The Storage Service Configurator====<br />
<br />
The Storage Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
Most of the parameters in the configurator are discussed in sections related to the services to which they apply. The others are discussed below.<br />
=====Query Mode=====<br />
The storage service can be configured to operate in one of two query modes:<br />
*<b>open</b> 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.<br />
*<b>restricted</b> sets the service to return only those results that match a query and for which the user is authorized to view the documents. <br />
<br />
In <b>restricted</b> mode, if a user is not authenticated in the query, the storage service only returns results for public documents.<br />
<br />
=====Site Name=====<br />
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.<br />
<br />
=====Tag Line=====<br />
The Tag Line is the text that is displayed under the name of the Storage Service in the list of query results.<br />
<br />
=====PHI Logging=====<br />
Storage Services have the ability to log accesses to MIRCdocuments that contain protected health information. Two kinds of logging are supported:<br />
* <b>PHI Access Log Enabled</b> determines whether the Storage Service logs PHI accesses in a local log file contained in the <b>access-logs</b> subdirectory of the root of the Storage Service. This log is a simple text file.<br />
* <b>PHI Access Log Export Enabled</b> 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 <b>PHI Access Log Export URL</b> field.<br />
<br />
===Author Service===<br />
====The Standard Templates====<br />
===Submit Service===<br />
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 <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Submit Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Submit Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Submit Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are received by the Submit Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Submit Service Autoindex</b> field. <br />
<br />
You can also control the maximum size of any submission. On initial installation, the default is set to <b>100MB</b>. To change the size, edit the <b>Maximum Submission Size (MB)</b> field.<br />
<br />
===Zip Service===<br />
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 <b>Tomcat/webapps/[storageservice]/submit/template.xml</b>. 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.<br />
<br />
The Zip Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Zip Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Zip Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Zip Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are created by the Zip Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Zip Service Autoindex</b> field. <br />
<br />
See [[The Zip Service User's Manual]] for more information.<br />
<br />
===TCE Service===<br />
[[Image:TCEConfigurator1.JPG|frame|]]<br />
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 <b>Tomcat/webapps/[storageservice]/tce/template.xml</b>. 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.<br />
<br />
The TCE Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the TCE Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>TCE Service Enabled</b> field.<br />
<br />
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.<br />
<br />
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 <b>Update Configuration</b> button in the <b>TCE Service</b> column on the Storage Service's admin page:<br />
*<b>autostart</b> - determines whether the service is automatically started when Tomcat starts. <br />
*<b>Store AE Title</b> - sets the application entity title for the TCE Service's DICOM Service. It should be unique in the entire MIRC environment.<br />
*<b>Store Port</b> - sets the port on which the DICOM Service listens for associations.<br />
Changes to these parameters are not recorded until the <b>Update tce.xml</b> button is clicked.<br />
<br />
To start the DICOM Service, or to restart it after changes have been made to its parameters, you must click the <b>Start/Restart</b> button in the <b>TCE Service</b> column on the admin page.<br />
<br />
===DICOM Service===<br />
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.<br />
<br />
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.<br />
<br />
For complete documentation on the DICOM Service, see the [[Clinical Trial Administrator's Manual]].<br />
<br />
==File Service Administration==<br />
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.<br />
===Controlling Access to the File Service===<br />
Each authenticated user who has the <b>FS-user</b> role is provided a personal file cabinet which only that user can access. In addition, all authenticated users with the <b>FS-user</b> role can access the shared file cabinet. Only users with the <b>FS-admin</b> role can access the File Service Admin page and configure the File Service.<br />
===Accessing the File Service Admin Page===<br />
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 <b>Admin Service</b> button on the right side of the window.<br />
<br />
On the Admin page, click the <b>File Service Admin</b> button. The result will be a page as shown below.<br />
<br />
[[Image:FileServiceAdmin1.JPG|frame|]]<br />
<br />
===Configuring the DICOM Service===<br />
The File Service has its own DICOM Service which receives DICOM objects, optionally anonymizes them, and places them in the shared file cabinet.<br />
<br />
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.<br />
<br />
If you want the DICOM Service to start automatically when the MIRC site is initialized, select <b>yes</b> in the <b>Autostart</b> field.<br />
<br />
After changing the configuration of the DICOM Service, you must first click the <b>Update fileservice.xml</b> button to save the changes, and then click the <b>Start/restart the DICOM Service</b> button to make the DICOM Service recognize them.<br />
<br />
===Configuring the Anonymizer===<br />
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 <b>Update the Anonymizer</b> button. The configuration and operation of the Anonymizer Configurator is described in [[The_MIRC_DICOM_Anonymizer|a separate article]].<br />
<br />
To enable the anonymizer, select <b>yes</b> in the <b>Anonymizer Enabled</b> field.<br />
<br />
<b>Important Note:</b> 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.<br />
<br />
===Configuring the Garbage Collector===<br />
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 <b>Shared File Cabinet Timeout (hours)</b> 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.<br />
<br />
===Saving Configuration Changes===<br />
To save the changes you have made to the configuration, click the <b>Update fileservice.xml</b> button. Changes do not become effective until they are saved. <br />
<br />
Anonymizer script changes are saved on the Anonymizer Configurator and do not require a separate button click on the Admin page.<br />
<br />
===Starting the DICOM Service===<br />
If the Autostart field contains <b>yes</b>, the DICOM Service is started when Tomcat starts and the MIRC site is initialized. If the Autostart field does not contain <b>yes</b>, you can start the DICOM Service by clicking the <b>Start/Restart the DICOM Service</b> button.<br />
<br />
<b>Caution:</b> Whenever you make changes to the DICOM Service configuration, you must save those changes by clicking the <b>Update fileservice.xml</b> 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.<br />
<br />
===Managing the Shared File Cabinet===<br />
Users who do not possess the <b>FS-admin</b> 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 <b>FS-admin</b> role can any delete files from the shared file cabinet.<br />
<br />
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.<br />
<br />
==System-Level Services==<br />
There are several system-level servlets that are a convenience for administrators. They can be accessed through the admin page of any Storage Service.<br />
===Log Viewer===<br />
The Log Viewer provides browser access to the log files in <b>Tomcat/logs</b>. Only log files with non-zero sizes are listed, and the listing is in reverse chronological order, making it easy to find current logs.<br />
===Controller===<br />
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.<br />
<br />
==Appendix: MIRC URL Index==<br />
This section indexes all the URLs recognized by a MIRC site. In the listing below, the following notations are used:<br />
*All URLS are assumed to begin with the value of the <b>siteurl</b> entity in the query service's <b>mirc.xml</b> file. For brevity, this part of the URL is not shown.<br />
*<b>[SSName]</b> refers to the name of a storage service.<br />
*<b>[path]</b> refers to a path.<br />
*<b>[filename]</b> refers to the name of a file.<br />
*<b>[username]</b> refers to the account name for a user.<br />
*Text not in square brackets is a fixed part of the URL. <br />
<br />
===Query Service URLs===<br />
*<tt>/mirc/query</tt> - the non-authenticated query service<br />
*<tt>/mirc/auth</tt> - the authenticated query service<br />
*<tt>/mirc/news</tt> - get the current news item (Case of the Day)<br />
*<tt>/mirc/news/add?link=...&title=...&description=...&image=...</tt> - add an item to the the news listing<br />
*<tt>/mirc/news/remove?link=...</tt> - remove an item from the the news listing<br />
*<tt>/mirc/news/listing</tt> - get HTML code referencing the current news item (for inclusion on a web page)<br />
*<tt>/mirc/news/news.rss</tt> - the RSS news feed<br />
<br />
===Storage Service URLs===<br />
<br />
===File Service URLs===<br />
Certain File Service URLs can contain a query string listing a set of filenames separated by pipe characters, in the form:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><tt>?list=[filename1]|[filename2]|...|[filenameN]</tt></b><br>In the listing below, this is abbreviated by <b><tt>?list=</tt></b>.<br />
*<tt>/file/service</tt> - the personal file cabinet of the authenticated user<br />
*<tt>/file/service/tome?list=</tt> - copy files from the shared file cabinet to the user's file cabinet <br />
*<tt>/file/service/users/[username]/files/[filename]</tt> - a file in a user's file cabinet<br />
*<tt>/file/service/users/[username]/icons/[filename]</tt> - an icon file in a user's file cabinet<br />
*<tt>/file/service/add</tt> - add a file to the user's file cabinet<br />
*<tt>/file/service/delete?list=</tt> - delete files from the user's file cabinet<br />
*<tt>/file/service/export?list=</tt> - export files from the user's file cabinet as a zip file<br />
*<tt>/file/service/update?text=...&list=</tt> - update the keywords text of files in the user's file cabinet<br />
*<tt>/file/service/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the user's file cabinet<br />
*<tt>/file/service/dept</tt> - the shared file cabinet<br />
*<tt>/file/service/todept?list=</tt> - copy files from the user's file cabinet to the shared file cabinet<br />
*<tt>/file/service/dept/files/[filename]</tt> - a file in the shared file cabinet<br />
*<tt>/file/service/dept/icons/[filename]</tt> - an icon file in the shared file cabinet<br />
*<tt>/file/service/dept/add</tt> - add a file to the shared file cabinet<br />
*<tt>/file/service/dept/delete?list=</tt> - delete files from the shared file cabinet<br />
*<tt>/file/service/dept/export?list=</tt> - export files from the shared file cabinet as a zip file<br />
*<tt>/file/service/dept/update?text=...&list=</tt> - update the keywords text of files in the shared file cabinet<br />
*<tt>/file/service/dept/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the shared file cabinet<br />
*<tt>/file/service/common/[filename]</tt> - a standard icon file<br />
<br />
===Admin URLs===<br />
*<tt>/mircadmin/controller</tt> - the controller servlet<br />
*<tt>/mircadmin/logviewer</tt> - the log viewer servlet<br />
*<tt>/mircadmin/logviewer/[filename]</tt> - display a specific log file<br />
*<tt>/mircadmin/users</tt> - the user role manager servlet<br />
*<tt>/mircadmin/user</tt> - the user account manager servlet<br />
<br />
==Appendix: System Block Diagram==<br />
[[Image:RsnaMircBlockDiagram-1.GIF]]</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=MIRC_Administrator%27s_Manual&diff=2048MIRC Administrator's Manual2006-08-13T14:47:11Z<p>209.242.55.28: /* Setting the Authentication Requirements */</p>
<hr />
<div>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. <br />
<br />
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.<br />
<br />
==Installation==<br />
<br />
==Query Service Administration==<br />
===System-level Modes===<br />
There are two operating modes which cannot be changed during operation of the system:<br />
* the system mode<br />
* the addressing mode<br />
Both modes are defined in the Query Service's configuration file, which is located in <b>Tomcat/webapps/mirc/mirc.xml</b>. At the top of the file is a <b>DOCTYPE</b> declaration containing several entities:<br />
<pre><br />
<!DOCTYPE mirc [<br />
<!ENTITY mode "rad"><br />
<!ENTITY sitename "P4"><br />
<!ENTITY addresstype "dynamic"><br />
<!ENTITY siteurl "http://192.168.0.96:8080"><br />
<!ENTITY queryurl "&siteurl;/mirc"><br />
<!ENTITY storageurl "&siteurl;/mircstorage"><br />
<!ENTITY mircforum "http://forums.rsna.org/forumdisplay.php?forumid=9"><br />
<!ENTITY mircdocs "http://mircwiki.rsna.org"><br />
<!ENTITY radlex "http://mirc.rsna.org/radlex/service"><br />
<!ENTITY tcusersclass "org.rsna.mircsite.util.TomcatUsersXmlFileImpl"><br />
<!ENTITY acctenb "yes"><br />
<!ENTITY defroles "QS-user,FS-user,SS-user,SS-author"><br />
<!ENTITY gpenb "yes"><br />
<!ENTITY version "T29alpha"> ]><br />
</pre><br />
<br />
====Setting the System Mode====<br />
The system mode is defined by the <b>mode</b> entity. The currently supported modes are:<br />
*<b>rad</b>: radiology<br />
*<b>vet</b>: veterinary medicine<br />
The choice of system mode configures the enumerated values for sexes, races, species, and breeds. These parameters, among many others, are stored in <b>Tomcat/webapps/mirc/enumerated-values.xml</b>.<br />
<br />
The software is preconfigured for <b>rad</b> mode. To change to <b>vet</b> mode, it is necessary to edit the <b>mirc.xml</b> file with a text editor and change the value of the <b>mode</b> entity. <br />
<br />
If operating in <b>vet</b> 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 <b>enumerated-values.xml</b> 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.<br />
<br />
====Setting the Addressing Mode====<br />
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.<br />
<br />
=====Dynamic vs. Static IP Addressing=====<br />
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.<br />
<br />
The way the MIRC software obtains the IP address is determined by the <b>addresstype</b> entity. The entity can have two possible values, <b>dynamic</b> or <b>static</b>. If the value is <b>dynamic</b>, 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. <br />
<br />
If the value of the <b>addresstype</b> entity is <b>static</b>, the software obtains the IP address from the <b>siteurl</b> entity. The <b>siteurl</b> entity can contain a numeric IP address or a domain name address. <br />
<br />
If <b>dynamic</b> addressing is used, the IP address specified in the <b>siteurl</b> entity must be numeric; otherwise, the method which obtains the IP address from the operating system will refuse to overwrite it.<br />
<br />
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.<br />
<br />
=====Reconfiguring the IP Address=====<br />
To change the IP addressing method after installation of the system, change the value of the <b>addresstype</b> entity using a text editor. If static addressing is employed, put the static IP address of the host in the value of the <b>siteurl</b> entity.<br />
<br />
Important: The protocol and port fields in the <b>siteurl</b> entity are always used, even in the case of dynamic addressing, so they must be set correctly in all cases.<br />
<br />
If an alphabetic value is inserted in the IP address field of the <b>siteurl</b> 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.<br />
<br />
====Restarting the System====<br />
After changing the system mode or the addressing mode, it is necessary to restart Tomcat in order to force the <b>init</b> methods of the MIRC servlets to run and reload the new enumerated values and/or IP address.<br />
<br />
===Setting the Authentication Requirements===<br />
The Query Service receives connections on two URLs:<br />
*<b>[siteurl]/mirc/auth</b> authenticates the user (forces a challenge for the user's credentials).<br />
*<b>[siteurl]/mirc/query</b> does not authenticate the user.<br />
<br />
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 <b>/query/auth</b> URL or by clicking the <b>Login</b> button on the query page.<br />
<br />
To be authenticated on the query service, you must have the <b>QS-user</b> role. When you upgrade, the installer will offer to add that role to the <b>admin</b> account, but for other users, you will have to add it manually with the User Role Manager.<br />
<br />
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 <b>index.html</b> page and change the URL in the redirection element.<br />
<br />
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) <u>on that storage service</u> 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 <b>passport</b>. A passport is managed by the passport's owner (the user) via the User Account Manager. A passport consists of a collection of <b>visas</b>, 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.<br />
<br />
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.<br />
<br />
===The Case of the Day===<br />
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 <b>Case of the Day</b> button in the table at the bottom of the document (or at the bottom of the <b>Document</b> tab).<br />
<br />
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.<br />
<br />
The latest Case of the Day can always be accessed by clicking the image in the lower left corner of the query page.<br />
<br />
==Controlling Users and Groups==<br />
Starting with Release T29, MIRC includes a User Account Manager that, when enabled by the administrator, allows users to create groups (and even accounts). <br />
<br />
===Groups===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===The User Role Manager===<br />
The User Role Manager, which can only be accessed by an administrator, has been changed so that it only manages:<br />
* the creation of new users <br />
* the removal of old users<br />
* the administrative roles<br />
<br />
Administrative roles are those that confer access to servlets or to MIRC behavior (like the <b>publisher</b> role and the various <b>admin</b> roles for Storage Services and the File Service).<br />
<br />
===The User Account Manager===<br />
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 (<b>admin</b>).<br />
<br />
To manage account and group creation, go to the query page, click the <b>Login</b> button and log in to an <b>admin</b> account. Then click the <b>My Account</b> button. The resulting page will contain several sections, each described by a little text telling you what to do. You can:<br />
*change your password on the server;<br />
*create visas for yourself;<br />
*resign from any or all groups;<br />
*join a group (if you know its name and password);<br />
*create a group, giving it a name and a password;<br />
*control whether account creation and/or group creation are enabled on the site;<br />
*define the administrative roles that are granted to users who create their own accounts.<br />
<br />
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.<br />
<br />
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 <b>user</b> and <b>author</b> roles for the File Service and the Storage Service to which you want to restrict the user (typically <b>QS-user</b>, <b>FS-user</b>, <b>SS-user</b> and <b>SS-author</b>). 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 <b>XX</b>, and then set the administrative roles for new users to be <b>QS-user</b>, <b>FS-user</b>, <b>XX-user</b> and <b>XX-author</b>. Note that since there is only one Query Service and one File Service on a MIRC site, you will always assign the <b>QS-user</b> and <b>FS-user</b> roles, no matter what the prefix is for the storage service.<br />
<br />
Group creation is independent of account creation and is separately enabled. Thus, you can disable account creation while still allowing group creation.<br />
<br />
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 <b>Submit</b> button, the visa for those services will be created.<br />
<br />
==Storage Service Administration==<br />
===The storage.xml File===<br />
===The siteindex.xml File===<br />
The storage service maintains a list of its active documents in a file described in a [[The Storage Service Index File|separate article]]. When the Storage Service starts, it builds an index from the contents of the documents listed in this file.<br />
<br />
See also [[Data Mining the MIRC Index]].<br />
<br />
===The Admin Service===<br />
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 <b>Admin Service</b> button. The resulting page contains a set of buttons as shown below, and an area in which various functions display their results.<br />
<br />
<br />
[[Image:AdminButtons1.JPG]]<br />
<br />
<br />
The following is a brief summary of each of the buttons' functions:<br />
*Left Column<br />
**<b>Status</b> - displays the key parameter settings<br />
**<b>List Input Queue</b> - displays the list of documents that have been requested to be made public by users who do not have the <b>publisher</b> role. Documents only enter the queue if autoindexing is not enabled on the Storage Service.<br />
**<b>File Service Admin</b> - a convenience link to the Admin Service of the File Service.<br />
*Storage Service Column<br />
**<b>Update Configuration</b> - links to the Storage Service Configurator, providing access to most of the Storage Service configuration parameters.<br />
**<b>List Index</b> - lists the documents currently in the index, with links allowing them to be viewed, deleted, or edited.<br />
**<b>Reload Index</b> - forces the Storage Service to reload its index from the siteindex.xml file.<br />
**<b>Rebuild Index</b> - creates a new siteindex.xml file by walking the directory tree under the <b>documents</b> directory and finding all the MIRCdocuments.<br />
**<b>Save Index</b> - saves the current index in <b>saved-index-file.xml</b> in the root directory of the Storage Service.<br />
*TCE Service Column<br />
**<b>Update Configuration</b> - links to the TCE Service Configurator, providing access to its DICOM Service parameters.<br />
**<b>Start/Restart</b> - starts the TCE Service's DICOM Service.<br />
**<b>Show Log</b> - displays the Storage Service's circular buffer of log entries from all its DICOM Services.<br />
**<b>Clear Log</b> - clears the circular log buffer.<br />
*DICOM Service Column<br />
**<b>Update Configuration</b> - links to the DICOM Service Configurator, providing access to the parameters used in clinical trials.<br />
**<b>Start/Restart</b> - starts the DICOM Service.<br />
**<b>Show Log</b> - 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.<br />
**<b>Clear Log</b> - clears the circular log buffer. This button does the same thing as the corresponding button in the TCE Service column.<br />
*Tomcat Column<br />
**<b>User Role Manager</b> - a convenience link to the MIRC User Role Manager servlet.<br />
**<b>Controller</b> - a convenience link to the MIRC Controller servlet.<br />
**<b>Log Viewer</b> - a convenience link to the Log Viewer servlet.<br />
[[Image:SSConfigurator1.JPG|frame|]]<br />
====The Storage Service Configurator====<br />
<br />
The Storage Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
Most of the parameters in the configurator are discussed in sections related to the services to which they apply. The others are discussed below.<br />
=====Query Mode=====<br />
The storage service can be configured to operate in one of two query modes:<br />
*<b>open</b> 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.<br />
*<b>restricted</b> sets the service to return only those results that match a query and for which the user is authorized to view the documents. <br />
<br />
In <b>restricted</b> mode, if a user is not authenticated in the query, the storage service only returns results for public documents.<br />
<br />
=====Site Name=====<br />
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.<br />
<br />
=====Tag Line=====<br />
The Tag Line is the text that is displayed under the name of the Storage Service in the list of query results.<br />
<br />
=====PHI Logging=====<br />
Storage Services have the ability to log accesses to MIRCdocuments that contain protected health information. Two kinds of logging are supported:<br />
* <b>PHI Access Log Enabled</b> determines whether the Storage Service logs PHI accesses in a local log file contained in the <b>access-logs</b> subdirectory of the root of the Storage Service. This log is a simple text file.<br />
* <b>PHI Access Log Export Enabled</b> 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 <b>PHI Access Log Export URL</b> field.<br />
<br />
===Author Service===<br />
====The Standard Templates====<br />
===Submit Service===<br />
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 <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Submit Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Submit Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Submit Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are received by the Submit Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Submit Service Autoindex</b> field. <br />
<br />
You can also control the maximum size of any submission. On initial installation, the default is set to <b>100MB</b>. To change the size, edit the <b>Maximum Submission Size (MB)</b> field.<br />
<br />
===Zip Service===<br />
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 <b>Tomcat/webapps/[storageservice]/submit/template.xml</b>. 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.<br />
<br />
The Zip Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Zip Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Zip Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Zip Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are created by the Zip Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Zip Service Autoindex</b> field. <br />
<br />
See [[The Zip Service User's Manual]] for more information.<br />
<br />
===TCE Service===<br />
[[Image:TCEConfigurator1.JPG|frame|]]<br />
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 <b>Tomcat/webapps/[storageservice]/tce/template.xml</b>. 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.<br />
<br />
The TCE Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the TCE Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>TCE Service Enabled</b> field.<br />
<br />
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.<br />
<br />
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 <b>Update Configuration</b> button in the <b>TCE Service</b> column on the Storage Service's admin page:<br />
*<b>autostart</b> - determines whether the service is automatically started when Tomcat starts. <br />
*<b>Store AE Title</b> - sets the application entity title for the TCE Service's DICOM Service. It should be unique in the entire MIRC environment.<br />
*<b>Store Port</b> - sets the port on which the DICOM Service listens for associations.<br />
Changes to these parameters are not recorded until the <b>Update tce.xml</b> button is clicked.<br />
<br />
To start the DICOM Service, or to restart it after changes have been made to its parameters, you must click the <b>Start/Restart</b> button in the <b>TCE Service</b> column on the admin page.<br />
<br />
===DICOM Service===<br />
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.<br />
<br />
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.<br />
<br />
For complete documentation on the DICOM Service, see the [[Clinical Trial Administrator's Manual]].<br />
<br />
==File Service Administration==<br />
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.<br />
===Controlling Access to the File Service===<br />
Each authenticated user who has the <b>FS-user</b> role is provided a personal file cabinet which only that user can access. In addition, all authenticated users with the <b>FS-user</b> role can access the shared file cabinet. Only users with the <b>FS-admin</b> role can access the File Service Admin page and configure the File Service.<br />
===Accessing the File Service Admin Page===<br />
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 <b>Admin Service</b> button on the right side of the window.<br />
<br />
On the Admin page, click the <b>File Service Admin</b> button. The result will be a page as shown below.<br />
<br />
[[Image:FileServiceAdmin1.JPG|frame|]]<br />
<br />
===Configuring the DICOM Service===<br />
The File Service has its own DICOM Service which receives DICOM objects, optionally anonymizes them, and places them in the shared file cabinet.<br />
<br />
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.<br />
<br />
If you want the DICOM Service to start automatically when the MIRC site is initialized, select <b>yes</b> in the <b>Autostart</b> field.<br />
<br />
After changing the configuration of the DICOM Service, you must first click the <b>Update fileservice.xml</b> button to save the changes, and then click the <b>Start/restart the DICOM Service</b> button to make the DICOM Service recognize them.<br />
<br />
===Configuring the Anonymizer===<br />
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 <b>Update the Anonymizer</b> button. The configuration and operation of the Anonymizer Configurator is described in [[The_MIRC_DICOM_Anonymizer|a separate article]].<br />
<br />
To enable the anonymizer, select <b>yes</b> in the <b>Anonymizer Enabled</b> field.<br />
<br />
<b>Important Note:</b> 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.<br />
<br />
===Configuring the Garbage Collector===<br />
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 <b>Shared File Cabinet Timeout (hours)</b> 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.<br />
<br />
===Saving Configuration Changes===<br />
To save the changes you have made to the configuration, click the <b>Update fileservice.xml</b> button. Changes do not become effective until they are saved. <br />
<br />
Anonymizer script changes are saved on the Anonymizer Configurator and do not require a separate button click on the Admin page.<br />
<br />
===Starting the DICOM Service===<br />
If the Autostart field contains <b>yes</b>, the DICOM Service is started when Tomcat starts and the MIRC site is initialized. If the Autostart field does not contain <b>yes</b>, you can start the DICOM Service by clicking the <b>Start/Restart the DICOM Service</b> button.<br />
<br />
<b>Caution:</b> Whenever you make changes to the DICOM Service configuration, you must save those changes by clicking the <b>Update fileservice.xml</b> 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.<br />
<br />
===Managing the Shared File Cabinet===<br />
Users who do not possess the <b>FS-admin</b> 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 <b>FS-admin</b> role can any delete files from the shared file cabinet.<br />
<br />
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.<br />
<br />
==System-Level Services==<br />
There are several system-level servlets that are a convenience for administrators. They can be accessed through the admin page of any Storage Service.<br />
===Log Viewer===<br />
The Log Viewer provides browser access to the log files in <b>Tomcat/logs</b>. Only log files with non-zero sizes are listed, and the listing is in reverse chronological order, making it easy to find current logs.<br />
===Controller===<br />
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.<br />
<br />
==Appendix: MIRC URL Index==<br />
This section indexes all the URLs recognized by a MIRC site. In the listing below, the following notations are used:<br />
*All URLS are assumed to begin with the value of the <b>siteurl</b> entity in the query service's <b>mirc.xml</b> file. For brevity, this part of the URL is not shown.<br />
*<b>[SSName]</b> refers to the name of a storage service.<br />
*<b>[path]</b> refers to a path.<br />
*<b>[filename]</b> refers to the name of a file.<br />
*<b>[username]</b> refers to the account name for a user.<br />
*Text not in square brackets is a fixed part of the URL. <br />
<br />
===Query Service URLs===<br />
*<tt>/mirc/query</tt> - the non-authenticated query service<br />
*<tt>/mirc/auth</tt> - the authenticated query service<br />
*<tt>/mirc/news</tt> - get the current news item (Case of the Day)<br />
*<tt>/mirc/news/add?link=...&title=...&description=...&image=...</tt> - add an item to the the news listing<br />
*<tt>/mirc/news/remove?link=...</tt> - remove an item from the the news listing<br />
*<tt>/mirc/news/listing</tt> - get HTML code referencing the current news item (for inclusion on a web page)<br />
*<tt>/mirc/news/news.rss</tt> - the RSS news feed<br />
<br />
===Storage Service URLs===<br />
<br />
===File Service URLs===<br />
Certain File Service URLs can contain a query string listing a set of filenames separated by pipe characters, in the form:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><tt>?list=[filename1]|[filename2]|...|[filenameN]</tt></b><br>In the listing below, this is abbreviated by <b><tt>?list=</tt></b>.<br />
*<tt>/file/service</tt> - the personal file cabinet of the authenticated user<br />
*<tt>/file/service/tome?list=</tt> - copy files from the shared file cabinet to the user's file cabinet <br />
*<tt>/file/service/users/[username]/files/[filename]</tt> - a file in a user's file cabinet<br />
*<tt>/file/service/users/[username]/icons/[filename]</tt> - an icon file in a user's file cabinet<br />
*<tt>/file/service/add</tt> - add a file to the user's file cabinet<br />
*<tt>/file/service/delete?list=</tt> - delete files from the user's file cabinet<br />
*<tt>/file/service/export?list=</tt> - export files from the user's file cabinet as a zip file<br />
*<tt>/file/service/update?text=...&list=</tt> - update the keywords text of files in the user's file cabinet<br />
*<tt>/file/service/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the user's file cabinet<br />
*<tt>/file/service/dept</tt> - the shared file cabinet<br />
*<tt>/file/service/todept?list=</tt> - copy files from the user's file cabinet to the shared file cabinet<br />
*<tt>/file/service/dept/files/[filename]</tt> - a file in the shared file cabinet<br />
*<tt>/file/service/dept/icons/[filename]</tt> - an icon file in the shared file cabinet<br />
*<tt>/file/service/dept/add</tt> - add a file to the shared file cabinet<br />
*<tt>/file/service/dept/delete?list=</tt> - delete files from the shared file cabinet<br />
*<tt>/file/service/dept/export?list=</tt> - export files from the shared file cabinet as a zip file<br />
*<tt>/file/service/dept/update?text=...&list=</tt> - update the keywords text of files in the shared file cabinet<br />
*<tt>/file/service/dept/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the shared file cabinet<br />
*<tt>/file/service/common/[filename]</tt> - a standard icon file<br />
<br />
===Admin URLs===<br />
*<tt>/mircadmin/controller</tt> - the controller servlet<br />
*<tt>/mircadmin/logviewer</tt> - the log viewer servlet<br />
*<tt>/mircadmin/logviewer/[filename]</tt> - display a specific log file<br />
*<tt>/mircadmin/users</tt> - the user role manager servlet<br />
*<tt>/mircadmin/user</tt> - the user account manager servlet<br />
<br />
==Appendix: System Block Diagram==<br />
[[Image:RsnaMircBlockDiagram-1.GIF]]</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=MIRC_Administrator%27s_Manual&diff=2047MIRC Administrator's Manual2006-08-13T14:45:55Z<p>209.242.55.28: /* Setting the Authentication Requirements */</p>
<hr />
<div>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. <br />
<br />
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.<br />
<br />
==Installation==<br />
<br />
==Query Service Administration==<br />
===System-level Modes===<br />
There are two operating modes which cannot be changed during operation of the system:<br />
* the system mode<br />
* the addressing mode<br />
Both modes are defined in the Query Service's configuration file, which is located in <b>Tomcat/webapps/mirc/mirc.xml</b>. At the top of the file is a <b>DOCTYPE</b> declaration containing several entities:<br />
<pre><br />
<!DOCTYPE mirc [<br />
<!ENTITY mode "rad"><br />
<!ENTITY sitename "P4"><br />
<!ENTITY addresstype "dynamic"><br />
<!ENTITY siteurl "http://192.168.0.96:8080"><br />
<!ENTITY queryurl "&siteurl;/mirc"><br />
<!ENTITY storageurl "&siteurl;/mircstorage"><br />
<!ENTITY mircforum "http://forums.rsna.org/forumdisplay.php?forumid=9"><br />
<!ENTITY mircdocs "http://mircwiki.rsna.org"><br />
<!ENTITY radlex "http://mirc.rsna.org/radlex/service"><br />
<!ENTITY tcusersclass "org.rsna.mircsite.util.TomcatUsersXmlFileImpl"><br />
<!ENTITY acctenb "yes"><br />
<!ENTITY defroles "QS-user,FS-user,SS-user,SS-author"><br />
<!ENTITY gpenb "yes"><br />
<!ENTITY version "T29alpha"> ]><br />
</pre><br />
<br />
====Setting the System Mode====<br />
The system mode is defined by the <b>mode</b> entity. The currently supported modes are:<br />
*<b>rad</b>: radiology<br />
*<b>vet</b>: veterinary medicine<br />
The choice of system mode configures the enumerated values for sexes, races, species, and breeds. These parameters, among many others, are stored in <b>Tomcat/webapps/mirc/enumerated-values.xml</b>.<br />
<br />
The software is preconfigured for <b>rad</b> mode. To change to <b>vet</b> mode, it is necessary to edit the <b>mirc.xml</b> file with a text editor and change the value of the <b>mode</b> entity. <br />
<br />
If operating in <b>vet</b> 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 <b>enumerated-values.xml</b> 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.<br />
<br />
====Setting the Addressing Mode====<br />
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.<br />
<br />
=====Dynamic vs. Static IP Addressing=====<br />
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.<br />
<br />
The way the MIRC software obtains the IP address is determined by the <b>addresstype</b> entity. The entity can have two possible values, <b>dynamic</b> or <b>static</b>. If the value is <b>dynamic</b>, 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. <br />
<br />
If the value of the <b>addresstype</b> entity is <b>static</b>, the software obtains the IP address from the <b>siteurl</b> entity. The <b>siteurl</b> entity can contain a numeric IP address or a domain name address. <br />
<br />
If <b>dynamic</b> addressing is used, the IP address specified in the <b>siteurl</b> entity must be numeric; otherwise, the method which obtains the IP address from the operating system will refuse to overwrite it.<br />
<br />
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.<br />
<br />
=====Reconfiguring the IP Address=====<br />
To change the IP addressing method after installation of the system, change the value of the <b>addresstype</b> entity using a text editor. If static addressing is employed, put the static IP address of the host in the value of the <b>siteurl</b> entity.<br />
<br />
Important: The protocol and port fields in the <b>siteurl</b> entity are always used, even in the case of dynamic addressing, so they must be set correctly in all cases.<br />
<br />
If an alphabetic value is inserted in the IP address field of the <b>siteurl</b> 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.<br />
<br />
====Restarting the System====<br />
After changing the system mode or the addressing mode, it is necessary to restart Tomcat in order to force the <b>init</b> methods of the MIRC servlets to run and reload the new enumerated values and/or IP address.<br />
<br />
===Setting the Authentication Requirements===<br />
The Query Service receives connections on two URLs:<br />
*<b>[siteurl]/mirc/auth</b> authenticates the user (forces a challenge for the user's credentials).<br />
*<b>[siteurl]/mirc/query</b> does not authenticate the user.<br />
<br />
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 <b>/query/auth</b> URL.<br />
<br />
To be authenticated on the query service, you must have the <b>QS-user</b> role. When you upgrade, the installer will offer to add that role to the <b>admin</b> account, but for other users, you will have to add it manually with the User Role Manager.<br />
<br />
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 <b>index.html</b> page and change the URL in the redirection element.<br />
<br />
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) <u>on that storage service</u> 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 <b>passport</b>. A passport is managed by the passport's owner (the user) via the User Account Manager. A passport consists of a collection of <b>visas</b>, 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.<br />
<br />
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.<br />
<br />
===The Case of the Day===<br />
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 <b>Case of the Day</b> button in the table at the bottom of the document (or at the bottom of the <b>Document</b> tab).<br />
<br />
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.<br />
<br />
The latest Case of the Day can always be accessed by clicking the image in the lower left corner of the query page.<br />
<br />
==Controlling Users and Groups==<br />
Starting with Release T29, MIRC includes a User Account Manager that, when enabled by the administrator, allows users to create groups (and even accounts). <br />
<br />
===Groups===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===The User Role Manager===<br />
The User Role Manager, which can only be accessed by an administrator, has been changed so that it only manages:<br />
* the creation of new users <br />
* the removal of old users<br />
* the administrative roles<br />
<br />
Administrative roles are those that confer access to servlets or to MIRC behavior (like the <b>publisher</b> role and the various <b>admin</b> roles for Storage Services and the File Service).<br />
<br />
===The User Account Manager===<br />
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 (<b>admin</b>).<br />
<br />
To manage account and group creation, go to the query page, click the <b>Login</b> button and log in to an <b>admin</b> account. Then click the <b>My Account</b> button. The resulting page will contain several sections, each described by a little text telling you what to do. You can:<br />
*change your password on the server;<br />
*create visas for yourself;<br />
*resign from any or all groups;<br />
*join a group (if you know its name and password);<br />
*create a group, giving it a name and a password;<br />
*control whether account creation and/or group creation are enabled on the site;<br />
*define the administrative roles that are granted to users who create their own accounts.<br />
<br />
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.<br />
<br />
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 <b>user</b> and <b>author</b> roles for the File Service and the Storage Service to which you want to restrict the user (typically <b>QS-user</b>, <b>FS-user</b>, <b>SS-user</b> and <b>SS-author</b>). 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 <b>XX</b>, and then set the administrative roles for new users to be <b>QS-user</b>, <b>FS-user</b>, <b>XX-user</b> and <b>XX-author</b>. Note that since there is only one Query Service and one File Service on a MIRC site, you will always assign the <b>QS-user</b> and <b>FS-user</b> roles, no matter what the prefix is for the storage service.<br />
<br />
Group creation is independent of account creation and is separately enabled. Thus, you can disable account creation while still allowing group creation.<br />
<br />
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 <b>Submit</b> button, the visa for those services will be created.<br />
<br />
==Storage Service Administration==<br />
===The storage.xml File===<br />
===The siteindex.xml File===<br />
The storage service maintains a list of its active documents in a file described in a [[The Storage Service Index File|separate article]]. When the Storage Service starts, it builds an index from the contents of the documents listed in this file.<br />
<br />
See also [[Data Mining the MIRC Index]].<br />
<br />
===The Admin Service===<br />
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 <b>Admin Service</b> button. The resulting page contains a set of buttons as shown below, and an area in which various functions display their results.<br />
<br />
<br />
[[Image:AdminButtons1.JPG]]<br />
<br />
<br />
The following is a brief summary of each of the buttons' functions:<br />
*Left Column<br />
**<b>Status</b> - displays the key parameter settings<br />
**<b>List Input Queue</b> - displays the list of documents that have been requested to be made public by users who do not have the <b>publisher</b> role. Documents only enter the queue if autoindexing is not enabled on the Storage Service.<br />
**<b>File Service Admin</b> - a convenience link to the Admin Service of the File Service.<br />
*Storage Service Column<br />
**<b>Update Configuration</b> - links to the Storage Service Configurator, providing access to most of the Storage Service configuration parameters.<br />
**<b>List Index</b> - lists the documents currently in the index, with links allowing them to be viewed, deleted, or edited.<br />
**<b>Reload Index</b> - forces the Storage Service to reload its index from the siteindex.xml file.<br />
**<b>Rebuild Index</b> - creates a new siteindex.xml file by walking the directory tree under the <b>documents</b> directory and finding all the MIRCdocuments.<br />
**<b>Save Index</b> - saves the current index in <b>saved-index-file.xml</b> in the root directory of the Storage Service.<br />
*TCE Service Column<br />
**<b>Update Configuration</b> - links to the TCE Service Configurator, providing access to its DICOM Service parameters.<br />
**<b>Start/Restart</b> - starts the TCE Service's DICOM Service.<br />
**<b>Show Log</b> - displays the Storage Service's circular buffer of log entries from all its DICOM Services.<br />
**<b>Clear Log</b> - clears the circular log buffer.<br />
*DICOM Service Column<br />
**<b>Update Configuration</b> - links to the DICOM Service Configurator, providing access to the parameters used in clinical trials.<br />
**<b>Start/Restart</b> - starts the DICOM Service.<br />
**<b>Show Log</b> - 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.<br />
**<b>Clear Log</b> - clears the circular log buffer. This button does the same thing as the corresponding button in the TCE Service column.<br />
*Tomcat Column<br />
**<b>User Role Manager</b> - a convenience link to the MIRC User Role Manager servlet.<br />
**<b>Controller</b> - a convenience link to the MIRC Controller servlet.<br />
**<b>Log Viewer</b> - a convenience link to the Log Viewer servlet.<br />
[[Image:SSConfigurator1.JPG|frame|]]<br />
====The Storage Service Configurator====<br />
<br />
The Storage Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
Most of the parameters in the configurator are discussed in sections related to the services to which they apply. The others are discussed below.<br />
=====Query Mode=====<br />
The storage service can be configured to operate in one of two query modes:<br />
*<b>open</b> 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.<br />
*<b>restricted</b> sets the service to return only those results that match a query and for which the user is authorized to view the documents. <br />
<br />
In <b>restricted</b> mode, if a user is not authenticated in the query, the storage service only returns results for public documents.<br />
<br />
=====Site Name=====<br />
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.<br />
<br />
=====Tag Line=====<br />
The Tag Line is the text that is displayed under the name of the Storage Service in the list of query results.<br />
<br />
=====PHI Logging=====<br />
Storage Services have the ability to log accesses to MIRCdocuments that contain protected health information. Two kinds of logging are supported:<br />
* <b>PHI Access Log Enabled</b> determines whether the Storage Service logs PHI accesses in a local log file contained in the <b>access-logs</b> subdirectory of the root of the Storage Service. This log is a simple text file.<br />
* <b>PHI Access Log Export Enabled</b> 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 <b>PHI Access Log Export URL</b> field.<br />
<br />
===Author Service===<br />
====The Standard Templates====<br />
===Submit Service===<br />
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 <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Submit Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Submit Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Submit Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are received by the Submit Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Submit Service Autoindex</b> field. <br />
<br />
You can also control the maximum size of any submission. On initial installation, the default is set to <b>100MB</b>. To change the size, edit the <b>Maximum Submission Size (MB)</b> field.<br />
<br />
===Zip Service===<br />
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 <b>Tomcat/webapps/[storageservice]/submit/template.xml</b>. 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.<br />
<br />
The Zip Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Zip Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Zip Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Zip Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are created by the Zip Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Zip Service Autoindex</b> field. <br />
<br />
See [[The Zip Service User's Manual]] for more information.<br />
<br />
===TCE Service===<br />
[[Image:TCEConfigurator1.JPG|frame|]]<br />
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 <b>Tomcat/webapps/[storageservice]/tce/template.xml</b>. 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.<br />
<br />
The TCE Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the TCE Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>TCE Service Enabled</b> field.<br />
<br />
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.<br />
<br />
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 <b>Update Configuration</b> button in the <b>TCE Service</b> column on the Storage Service's admin page:<br />
*<b>autostart</b> - determines whether the service is automatically started when Tomcat starts. <br />
*<b>Store AE Title</b> - sets the application entity title for the TCE Service's DICOM Service. It should be unique in the entire MIRC environment.<br />
*<b>Store Port</b> - sets the port on which the DICOM Service listens for associations.<br />
Changes to these parameters are not recorded until the <b>Update tce.xml</b> button is clicked.<br />
<br />
To start the DICOM Service, or to restart it after changes have been made to its parameters, you must click the <b>Start/Restart</b> button in the <b>TCE Service</b> column on the admin page.<br />
<br />
===DICOM Service===<br />
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.<br />
<br />
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.<br />
<br />
For complete documentation on the DICOM Service, see the [[Clinical Trial Administrator's Manual]].<br />
<br />
==File Service Administration==<br />
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.<br />
===Controlling Access to the File Service===<br />
Each authenticated user who has the <b>FS-user</b> role is provided a personal file cabinet which only that user can access. In addition, all authenticated users with the <b>FS-user</b> role can access the shared file cabinet. Only users with the <b>FS-admin</b> role can access the File Service Admin page and configure the File Service.<br />
===Accessing the File Service Admin Page===<br />
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 <b>Admin Service</b> button on the right side of the window.<br />
<br />
On the Admin page, click the <b>File Service Admin</b> button. The result will be a page as shown below.<br />
<br />
[[Image:FileServiceAdmin1.JPG|frame|]]<br />
<br />
===Configuring the DICOM Service===<br />
The File Service has its own DICOM Service which receives DICOM objects, optionally anonymizes them, and places them in the shared file cabinet.<br />
<br />
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.<br />
<br />
If you want the DICOM Service to start automatically when the MIRC site is initialized, select <b>yes</b> in the <b>Autostart</b> field.<br />
<br />
After changing the configuration of the DICOM Service, you must first click the <b>Update fileservice.xml</b> button to save the changes, and then click the <b>Start/restart the DICOM Service</b> button to make the DICOM Service recognize them.<br />
<br />
===Configuring the Anonymizer===<br />
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 <b>Update the Anonymizer</b> button. The configuration and operation of the Anonymizer Configurator is described in [[The_MIRC_DICOM_Anonymizer|a separate article]].<br />
<br />
To enable the anonymizer, select <b>yes</b> in the <b>Anonymizer Enabled</b> field.<br />
<br />
<b>Important Note:</b> 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.<br />
<br />
===Configuring the Garbage Collector===<br />
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 <b>Shared File Cabinet Timeout (hours)</b> 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.<br />
<br />
===Saving Configuration Changes===<br />
To save the changes you have made to the configuration, click the <b>Update fileservice.xml</b> button. Changes do not become effective until they are saved. <br />
<br />
Anonymizer script changes are saved on the Anonymizer Configurator and do not require a separate button click on the Admin page.<br />
<br />
===Starting the DICOM Service===<br />
If the Autostart field contains <b>yes</b>, the DICOM Service is started when Tomcat starts and the MIRC site is initialized. If the Autostart field does not contain <b>yes</b>, you can start the DICOM Service by clicking the <b>Start/Restart the DICOM Service</b> button.<br />
<br />
<b>Caution:</b> Whenever you make changes to the DICOM Service configuration, you must save those changes by clicking the <b>Update fileservice.xml</b> 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.<br />
<br />
===Managing the Shared File Cabinet===<br />
Users who do not possess the <b>FS-admin</b> 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 <b>FS-admin</b> role can any delete files from the shared file cabinet.<br />
<br />
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.<br />
<br />
==System-Level Services==<br />
There are several system-level servlets that are a convenience for administrators. They can be accessed through the admin page of any Storage Service.<br />
===Log Viewer===<br />
The Log Viewer provides browser access to the log files in <b>Tomcat/logs</b>. Only log files with non-zero sizes are listed, and the listing is in reverse chronological order, making it easy to find current logs.<br />
===Controller===<br />
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.<br />
<br />
==Appendix: MIRC URL Index==<br />
This section indexes all the URLs recognized by a MIRC site. In the listing below, the following notations are used:<br />
*All URLS are assumed to begin with the value of the <b>siteurl</b> entity in the query service's <b>mirc.xml</b> file. For brevity, this part of the URL is not shown.<br />
*<b>[SSName]</b> refers to the name of a storage service.<br />
*<b>[path]</b> refers to a path.<br />
*<b>[filename]</b> refers to the name of a file.<br />
*<b>[username]</b> refers to the account name for a user.<br />
*Text not in square brackets is a fixed part of the URL. <br />
<br />
===Query Service URLs===<br />
*<tt>/mirc/query</tt> - the non-authenticated query service<br />
*<tt>/mirc/auth</tt> - the authenticated query service<br />
*<tt>/mirc/news</tt> - get the current news item (Case of the Day)<br />
*<tt>/mirc/news/add?link=...&title=...&description=...&image=...</tt> - add an item to the the news listing<br />
*<tt>/mirc/news/remove?link=...</tt> - remove an item from the the news listing<br />
*<tt>/mirc/news/listing</tt> - get HTML code referencing the current news item (for inclusion on a web page)<br />
*<tt>/mirc/news/news.rss</tt> - the RSS news feed<br />
<br />
===Storage Service URLs===<br />
<br />
===File Service URLs===<br />
Certain File Service URLs can contain a query string listing a set of filenames separated by pipe characters, in the form:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><tt>?list=[filename1]|[filename2]|...|[filenameN]</tt></b><br>In the listing below, this is abbreviated by <b><tt>?list=</tt></b>.<br />
*<tt>/file/service</tt> - the personal file cabinet of the authenticated user<br />
*<tt>/file/service/tome?list=</tt> - copy files from the shared file cabinet to the user's file cabinet <br />
*<tt>/file/service/users/[username]/files/[filename]</tt> - a file in a user's file cabinet<br />
*<tt>/file/service/users/[username]/icons/[filename]</tt> - an icon file in a user's file cabinet<br />
*<tt>/file/service/add</tt> - add a file to the user's file cabinet<br />
*<tt>/file/service/delete?list=</tt> - delete files from the user's file cabinet<br />
*<tt>/file/service/export?list=</tt> - export files from the user's file cabinet as a zip file<br />
*<tt>/file/service/update?text=...&list=</tt> - update the keywords text of files in the user's file cabinet<br />
*<tt>/file/service/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the user's file cabinet<br />
*<tt>/file/service/dept</tt> - the shared file cabinet<br />
*<tt>/file/service/todept?list=</tt> - copy files from the user's file cabinet to the shared file cabinet<br />
*<tt>/file/service/dept/files/[filename]</tt> - a file in the shared file cabinet<br />
*<tt>/file/service/dept/icons/[filename]</tt> - an icon file in the shared file cabinet<br />
*<tt>/file/service/dept/add</tt> - add a file to the shared file cabinet<br />
*<tt>/file/service/dept/delete?list=</tt> - delete files from the shared file cabinet<br />
*<tt>/file/service/dept/export?list=</tt> - export files from the shared file cabinet as a zip file<br />
*<tt>/file/service/dept/update?text=...&list=</tt> - update the keywords text of files in the shared file cabinet<br />
*<tt>/file/service/dept/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the shared file cabinet<br />
*<tt>/file/service/common/[filename]</tt> - a standard icon file<br />
<br />
===Admin URLs===<br />
*<tt>/mircadmin/controller</tt> - the controller servlet<br />
*<tt>/mircadmin/logviewer</tt> - the log viewer servlet<br />
*<tt>/mircadmin/logviewer/[filename]</tt> - display a specific log file<br />
*<tt>/mircadmin/users</tt> - the user role manager servlet<br />
*<tt>/mircadmin/user</tt> - the user account manager servlet<br />
<br />
==Appendix: System Block Diagram==<br />
[[Image:RsnaMircBlockDiagram-1.GIF]]</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=MIRC_Administrator%27s_Manual&diff=2046MIRC Administrator's Manual2006-08-13T14:42:09Z<p>209.242.55.28: /* Dynamic vs. Static IP Addressing */</p>
<hr />
<div>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. <br />
<br />
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.<br />
<br />
==Installation==<br />
<br />
==Query Service Administration==<br />
===System-level Modes===<br />
There are two operating modes which cannot be changed during operation of the system:<br />
* the system mode<br />
* the addressing mode<br />
Both modes are defined in the Query Service's configuration file, which is located in <b>Tomcat/webapps/mirc/mirc.xml</b>. At the top of the file is a <b>DOCTYPE</b> declaration containing several entities:<br />
<pre><br />
<!DOCTYPE mirc [<br />
<!ENTITY mode "rad"><br />
<!ENTITY sitename "P4"><br />
<!ENTITY addresstype "dynamic"><br />
<!ENTITY siteurl "http://192.168.0.96:8080"><br />
<!ENTITY queryurl "&siteurl;/mirc"><br />
<!ENTITY storageurl "&siteurl;/mircstorage"><br />
<!ENTITY mircforum "http://forums.rsna.org/forumdisplay.php?forumid=9"><br />
<!ENTITY mircdocs "http://mircwiki.rsna.org"><br />
<!ENTITY radlex "http://mirc.rsna.org/radlex/service"><br />
<!ENTITY tcusersclass "org.rsna.mircsite.util.TomcatUsersXmlFileImpl"><br />
<!ENTITY acctenb "yes"><br />
<!ENTITY defroles "QS-user,FS-user,SS-user,SS-author"><br />
<!ENTITY gpenb "yes"><br />
<!ENTITY version "T29alpha"> ]><br />
</pre><br />
<br />
====Setting the System Mode====<br />
The system mode is defined by the <b>mode</b> entity. The currently supported modes are:<br />
*<b>rad</b>: radiology<br />
*<b>vet</b>: veterinary medicine<br />
The choice of system mode configures the enumerated values for sexes, races, species, and breeds. These parameters, among many others, are stored in <b>Tomcat/webapps/mirc/enumerated-values.xml</b>.<br />
<br />
The software is preconfigured for <b>rad</b> mode. To change to <b>vet</b> mode, it is necessary to edit the <b>mirc.xml</b> file with a text editor and change the value of the <b>mode</b> entity. <br />
<br />
If operating in <b>vet</b> 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 <b>enumerated-values.xml</b> 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.<br />
<br />
====Setting the Addressing Mode====<br />
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.<br />
<br />
=====Dynamic vs. Static IP Addressing=====<br />
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.<br />
<br />
The way the MIRC software obtains the IP address is determined by the <b>addresstype</b> entity. The entity can have two possible values, <b>dynamic</b> or <b>static</b>. If the value is <b>dynamic</b>, 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. <br />
<br />
If the value of the <b>addresstype</b> entity is <b>static</b>, the software obtains the IP address from the <b>siteurl</b> entity. The <b>siteurl</b> entity can contain a numeric IP address or a domain name address. <br />
<br />
If <b>dynamic</b> addressing is used, the IP address specified in the <b>siteurl</b> entity must be numeric; otherwise, the method which obtains the IP address from the operating system will refuse to overwrite it.<br />
<br />
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.<br />
<br />
=====Reconfiguring the IP Address=====<br />
To change the IP addressing method after installation of the system, change the value of the <b>addresstype</b> entity using a text editor. If static addressing is employed, put the static IP address of the host in the value of the <b>siteurl</b> entity.<br />
<br />
Important: The protocol and port fields in the <b>siteurl</b> entity are always used, even in the case of dynamic addressing, so they must be set correctly in all cases.<br />
<br />
If an alphabetic value is inserted in the IP address field of the <b>siteurl</b> 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.<br />
<br />
====Restarting the System====<br />
After changing the system mode or the addressing mode, it is necessary to restart Tomcat in order to force the <b>init</b> methods of the MIRC servlets to run and reload the new enumerated values and/or IP address.<br />
<br />
===Setting the Authentication Requirements===<br />
The Query Service receives connections on two URLs:<br />
*<b>[siteurl]/mirc/auth</b> authenticates.<br />
*<b>[siteurl]/mirc/query</b> does not authenticate.<br />
<br />
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 <b>/query/auth</b> URL.<br />
<br />
To be authenticated on the query service, you must have the <b>QS-user</b> role. When you upgrade, the installer will offer to add that role to the <b>admin</b> account, but for other users, you will have to add it manually with the User Role Manager.<br />
<br />
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 <b>index.html</b> page and change the URL in the redirection element.<br />
<br />
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) <u>on that storage service</u> 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 <b>passport</b>. A passport is managed by the passport's owner (the user) via the User Account Manager. A passport consists of a collection of <b>visas</b>, 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.<br />
<br />
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.<br />
<br />
===The Case of the Day===<br />
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 <b>Case of the Day</b> button in the table at the bottom of the document (or at the bottom of the <b>Document</b> tab).<br />
<br />
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.<br />
<br />
The latest Case of the Day can always be accessed by clicking the image in the lower left corner of the query page.<br />
<br />
==Controlling Users and Groups==<br />
Starting with Release T29, MIRC includes a User Account Manager that, when enabled by the administrator, allows users to create groups (and even accounts). <br />
<br />
===Groups===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===The User Role Manager===<br />
The User Role Manager, which can only be accessed by an administrator, has been changed so that it only manages:<br />
* the creation of new users <br />
* the removal of old users<br />
* the administrative roles<br />
<br />
Administrative roles are those that confer access to servlets or to MIRC behavior (like the <b>publisher</b> role and the various <b>admin</b> roles for Storage Services and the File Service).<br />
<br />
===The User Account Manager===<br />
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 (<b>admin</b>).<br />
<br />
To manage account and group creation, go to the query page, click the <b>Login</b> button and log in to an <b>admin</b> account. Then click the <b>My Account</b> button. The resulting page will contain several sections, each described by a little text telling you what to do. You can:<br />
*change your password on the server;<br />
*create visas for yourself;<br />
*resign from any or all groups;<br />
*join a group (if you know its name and password);<br />
*create a group, giving it a name and a password;<br />
*control whether account creation and/or group creation are enabled on the site;<br />
*define the administrative roles that are granted to users who create their own accounts.<br />
<br />
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.<br />
<br />
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 <b>user</b> and <b>author</b> roles for the File Service and the Storage Service to which you want to restrict the user (typically <b>QS-user</b>, <b>FS-user</b>, <b>SS-user</b> and <b>SS-author</b>). 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 <b>XX</b>, and then set the administrative roles for new users to be <b>QS-user</b>, <b>FS-user</b>, <b>XX-user</b> and <b>XX-author</b>. Note that since there is only one Query Service and one File Service on a MIRC site, you will always assign the <b>QS-user</b> and <b>FS-user</b> roles, no matter what the prefix is for the storage service.<br />
<br />
Group creation is independent of account creation and is separately enabled. Thus, you can disable account creation while still allowing group creation.<br />
<br />
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 <b>Submit</b> button, the visa for those services will be created.<br />
<br />
==Storage Service Administration==<br />
===The storage.xml File===<br />
===The siteindex.xml File===<br />
The storage service maintains a list of its active documents in a file described in a [[The Storage Service Index File|separate article]]. When the Storage Service starts, it builds an index from the contents of the documents listed in this file.<br />
<br />
See also [[Data Mining the MIRC Index]].<br />
<br />
===The Admin Service===<br />
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 <b>Admin Service</b> button. The resulting page contains a set of buttons as shown below, and an area in which various functions display their results.<br />
<br />
<br />
[[Image:AdminButtons1.JPG]]<br />
<br />
<br />
The following is a brief summary of each of the buttons' functions:<br />
*Left Column<br />
**<b>Status</b> - displays the key parameter settings<br />
**<b>List Input Queue</b> - displays the list of documents that have been requested to be made public by users who do not have the <b>publisher</b> role. Documents only enter the queue if autoindexing is not enabled on the Storage Service.<br />
**<b>File Service Admin</b> - a convenience link to the Admin Service of the File Service.<br />
*Storage Service Column<br />
**<b>Update Configuration</b> - links to the Storage Service Configurator, providing access to most of the Storage Service configuration parameters.<br />
**<b>List Index</b> - lists the documents currently in the index, with links allowing them to be viewed, deleted, or edited.<br />
**<b>Reload Index</b> - forces the Storage Service to reload its index from the siteindex.xml file.<br />
**<b>Rebuild Index</b> - creates a new siteindex.xml file by walking the directory tree under the <b>documents</b> directory and finding all the MIRCdocuments.<br />
**<b>Save Index</b> - saves the current index in <b>saved-index-file.xml</b> in the root directory of the Storage Service.<br />
*TCE Service Column<br />
**<b>Update Configuration</b> - links to the TCE Service Configurator, providing access to its DICOM Service parameters.<br />
**<b>Start/Restart</b> - starts the TCE Service's DICOM Service.<br />
**<b>Show Log</b> - displays the Storage Service's circular buffer of log entries from all its DICOM Services.<br />
**<b>Clear Log</b> - clears the circular log buffer.<br />
*DICOM Service Column<br />
**<b>Update Configuration</b> - links to the DICOM Service Configurator, providing access to the parameters used in clinical trials.<br />
**<b>Start/Restart</b> - starts the DICOM Service.<br />
**<b>Show Log</b> - 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.<br />
**<b>Clear Log</b> - clears the circular log buffer. This button does the same thing as the corresponding button in the TCE Service column.<br />
*Tomcat Column<br />
**<b>User Role Manager</b> - a convenience link to the MIRC User Role Manager servlet.<br />
**<b>Controller</b> - a convenience link to the MIRC Controller servlet.<br />
**<b>Log Viewer</b> - a convenience link to the Log Viewer servlet.<br />
[[Image:SSConfigurator1.JPG|frame|]]<br />
====The Storage Service Configurator====<br />
<br />
The Storage Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
Most of the parameters in the configurator are discussed in sections related to the services to which they apply. The others are discussed below.<br />
=====Query Mode=====<br />
The storage service can be configured to operate in one of two query modes:<br />
*<b>open</b> 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.<br />
*<b>restricted</b> sets the service to return only those results that match a query and for which the user is authorized to view the documents. <br />
<br />
In <b>restricted</b> mode, if a user is not authenticated in the query, the storage service only returns results for public documents.<br />
<br />
=====Site Name=====<br />
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.<br />
<br />
=====Tag Line=====<br />
The Tag Line is the text that is displayed under the name of the Storage Service in the list of query results.<br />
<br />
=====PHI Logging=====<br />
Storage Services have the ability to log accesses to MIRCdocuments that contain protected health information. Two kinds of logging are supported:<br />
* <b>PHI Access Log Enabled</b> determines whether the Storage Service logs PHI accesses in a local log file contained in the <b>access-logs</b> subdirectory of the root of the Storage Service. This log is a simple text file.<br />
* <b>PHI Access Log Export Enabled</b> 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 <b>PHI Access Log Export URL</b> field.<br />
<br />
===Author Service===<br />
====The Standard Templates====<br />
===Submit Service===<br />
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 <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Submit Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Submit Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Submit Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are received by the Submit Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Submit Service Autoindex</b> field. <br />
<br />
You can also control the maximum size of any submission. On initial installation, the default is set to <b>100MB</b>. To change the size, edit the <b>Maximum Submission Size (MB)</b> field.<br />
<br />
===Zip Service===<br />
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 <b>Tomcat/webapps/[storageservice]/submit/template.xml</b>. 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.<br />
<br />
The Zip Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the Zip Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>Zip Service Enabled</b> field.<br />
<br />
You can also control whether documents created by the Zip Service are automatically indexed.<br />
* If autoindexing is enabled, all documents, whether public or private, that are created by the Zip Service are indexed without modification.<br />
* If autoindexing is not enabled, only documents submitted by users with the <b>publisher</b> 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.<br />
<br />
Most personal sites operate in autoindexing mode; most shared sites do <b>not</b>. To set the autoindexing mode, select <b>yes</b> in the <b>Zip Service Autoindex</b> field. <br />
<br />
See [[The Zip Service User's Manual]] for more information.<br />
<br />
===TCE Service===<br />
[[Image:TCEConfigurator1.JPG|frame|]]<br />
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 <b>Tomcat/webapps/[storageservice]/tce/template.xml</b>. 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.<br />
<br />
The TCE Service is configured using the Storage Service Configurator. To display the configurator, click the <b>Update Configuration</b> button in the <b>Storage Service</b> column. Configuration changes do not become effective until you click the <b>Update storage.xml</b> button at the bottom of the page.<br />
<br />
You can control whether the TCE Service is enabled on the Storage Service. To set the enable field, select <b>yes</b> in the <b>TCE Service Enabled</b> field.<br />
<br />
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.<br />
<br />
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 <b>Update Configuration</b> button in the <b>TCE Service</b> column on the Storage Service's admin page:<br />
*<b>autostart</b> - determines whether the service is automatically started when Tomcat starts. <br />
*<b>Store AE Title</b> - sets the application entity title for the TCE Service's DICOM Service. It should be unique in the entire MIRC environment.<br />
*<b>Store Port</b> - sets the port on which the DICOM Service listens for associations.<br />
Changes to these parameters are not recorded until the <b>Update tce.xml</b> button is clicked.<br />
<br />
To start the DICOM Service, or to restart it after changes have been made to its parameters, you must click the <b>Start/Restart</b> button in the <b>TCE Service</b> column on the admin page.<br />
<br />
===DICOM Service===<br />
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.<br />
<br />
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.<br />
<br />
For complete documentation on the DICOM Service, see the [[Clinical Trial Administrator's Manual]].<br />
<br />
==File Service Administration==<br />
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.<br />
===Controlling Access to the File Service===<br />
Each authenticated user who has the <b>FS-user</b> role is provided a personal file cabinet which only that user can access. In addition, all authenticated users with the <b>FS-user</b> role can access the shared file cabinet. Only users with the <b>FS-admin</b> role can access the File Service Admin page and configure the File Service.<br />
===Accessing the File Service Admin Page===<br />
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 <b>Admin Service</b> button on the right side of the window.<br />
<br />
On the Admin page, click the <b>File Service Admin</b> button. The result will be a page as shown below.<br />
<br />
[[Image:FileServiceAdmin1.JPG|frame|]]<br />
<br />
===Configuring the DICOM Service===<br />
The File Service has its own DICOM Service which receives DICOM objects, optionally anonymizes them, and places them in the shared file cabinet.<br />
<br />
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.<br />
<br />
If you want the DICOM Service to start automatically when the MIRC site is initialized, select <b>yes</b> in the <b>Autostart</b> field.<br />
<br />
After changing the configuration of the DICOM Service, you must first click the <b>Update fileservice.xml</b> button to save the changes, and then click the <b>Start/restart the DICOM Service</b> button to make the DICOM Service recognize them.<br />
<br />
===Configuring the Anonymizer===<br />
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 <b>Update the Anonymizer</b> button. The configuration and operation of the Anonymizer Configurator is described in [[The_MIRC_DICOM_Anonymizer|a separate article]].<br />
<br />
To enable the anonymizer, select <b>yes</b> in the <b>Anonymizer Enabled</b> field.<br />
<br />
<b>Important Note:</b> 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.<br />
<br />
===Configuring the Garbage Collector===<br />
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 <b>Shared File Cabinet Timeout (hours)</b> 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.<br />
<br />
===Saving Configuration Changes===<br />
To save the changes you have made to the configuration, click the <b>Update fileservice.xml</b> button. Changes do not become effective until they are saved. <br />
<br />
Anonymizer script changes are saved on the Anonymizer Configurator and do not require a separate button click on the Admin page.<br />
<br />
===Starting the DICOM Service===<br />
If the Autostart field contains <b>yes</b>, the DICOM Service is started when Tomcat starts and the MIRC site is initialized. If the Autostart field does not contain <b>yes</b>, you can start the DICOM Service by clicking the <b>Start/Restart the DICOM Service</b> button.<br />
<br />
<b>Caution:</b> Whenever you make changes to the DICOM Service configuration, you must save those changes by clicking the <b>Update fileservice.xml</b> 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.<br />
<br />
===Managing the Shared File Cabinet===<br />
Users who do not possess the <b>FS-admin</b> 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 <b>FS-admin</b> role can any delete files from the shared file cabinet.<br />
<br />
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.<br />
<br />
==System-Level Services==<br />
There are several system-level servlets that are a convenience for administrators. They can be accessed through the admin page of any Storage Service.<br />
===Log Viewer===<br />
The Log Viewer provides browser access to the log files in <b>Tomcat/logs</b>. Only log files with non-zero sizes are listed, and the listing is in reverse chronological order, making it easy to find current logs.<br />
===Controller===<br />
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.<br />
<br />
==Appendix: MIRC URL Index==<br />
This section indexes all the URLs recognized by a MIRC site. In the listing below, the following notations are used:<br />
*All URLS are assumed to begin with the value of the <b>siteurl</b> entity in the query service's <b>mirc.xml</b> file. For brevity, this part of the URL is not shown.<br />
*<b>[SSName]</b> refers to the name of a storage service.<br />
*<b>[path]</b> refers to a path.<br />
*<b>[filename]</b> refers to the name of a file.<br />
*<b>[username]</b> refers to the account name for a user.<br />
*Text not in square brackets is a fixed part of the URL. <br />
<br />
===Query Service URLs===<br />
*<tt>/mirc/query</tt> - the non-authenticated query service<br />
*<tt>/mirc/auth</tt> - the authenticated query service<br />
*<tt>/mirc/news</tt> - get the current news item (Case of the Day)<br />
*<tt>/mirc/news/add?link=...&title=...&description=...&image=...</tt> - add an item to the the news listing<br />
*<tt>/mirc/news/remove?link=...</tt> - remove an item from the the news listing<br />
*<tt>/mirc/news/listing</tt> - get HTML code referencing the current news item (for inclusion on a web page)<br />
*<tt>/mirc/news/news.rss</tt> - the RSS news feed<br />
<br />
===Storage Service URLs===<br />
<br />
===File Service URLs===<br />
Certain File Service URLs can contain a query string listing a set of filenames separated by pipe characters, in the form:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b><tt>?list=[filename1]|[filename2]|...|[filenameN]</tt></b><br>In the listing below, this is abbreviated by <b><tt>?list=</tt></b>.<br />
*<tt>/file/service</tt> - the personal file cabinet of the authenticated user<br />
*<tt>/file/service/tome?list=</tt> - copy files from the shared file cabinet to the user's file cabinet <br />
*<tt>/file/service/users/[username]/files/[filename]</tt> - a file in a user's file cabinet<br />
*<tt>/file/service/users/[username]/icons/[filename]</tt> - an icon file in a user's file cabinet<br />
*<tt>/file/service/add</tt> - add a file to the user's file cabinet<br />
*<tt>/file/service/delete?list=</tt> - delete files from the user's file cabinet<br />
*<tt>/file/service/export?list=</tt> - export files from the user's file cabinet as a zip file<br />
*<tt>/file/service/update?text=...&list=</tt> - update the keywords text of files in the user's file cabinet<br />
*<tt>/file/service/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the user's file cabinet<br />
*<tt>/file/service/dept</tt> - the shared file cabinet<br />
*<tt>/file/service/todept?list=</tt> - copy files from the user's file cabinet to the shared file cabinet<br />
*<tt>/file/service/dept/files/[filename]</tt> - a file in the shared file cabinet<br />
*<tt>/file/service/dept/icons/[filename]</tt> - an icon file in the shared file cabinet<br />
*<tt>/file/service/dept/add</tt> - add a file to the shared file cabinet<br />
*<tt>/file/service/dept/delete?list=</tt> - delete files from the shared file cabinet<br />
*<tt>/file/service/dept/export?list=</tt> - export files from the shared file cabinet as a zip file<br />
*<tt>/file/service/dept/update?text=...&list=</tt> - update the keywords text of files in the shared file cabinet<br />
*<tt>/file/service/dept/dicom?list=</tt> - display a DICOM element listing of the first file in the list, from the shared file cabinet<br />
*<tt>/file/service/common/[filename]</tt> - a standard icon file<br />
<br />
===Admin URLs===<br />
*<tt>/mircadmin/controller</tt> - the controller servlet<br />
*<tt>/mircadmin/logviewer</tt> - the log viewer servlet<br />
*<tt>/mircadmin/logviewer/[filename]</tt> - display a specific log file<br />
*<tt>/mircadmin/users</tt> - the user role manager servlet<br />
*<tt>/mircadmin/user</tt> - the user account manager servlet<br />
<br />
==Appendix: System Block Diagram==<br />
[[Image:RsnaMircBlockDiagram-1.GIF]]</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=MIRC_Overview_-_CTP_and_TFS&diff=2045MIRC Overview - CTP and TFS2006-08-13T14:36:48Z<p>209.242.55.28: /* Administrator's Manual */</p>
<hr />
<div>=== About the MIRC Project ===<br />
The MIRC project was initiated by the RSNA Radiology Informatics Committee to construct a library of medical information, globally accessible to the imaging community through the Internet. The project has evolved to support communities of cooperating libraries, individually managed by healthcare and educational institutions, whose content can be accessed by a user as if it were a single library. The libraries can provide all kinds of digital information, including teaching files, clinical and technical documents, electronic presentations, and imaging datasets for research and clinical trials. <br />
<br />
The RSNA manages an open-source project that has produced software making it easy to install a system for teaching files and clinical trials at no cost. Numerous other developers have produced complete or partial MIRC implementations.<br />
<br />
=== The MIRC Community ===<br />
Many MIRC communities have arisen - some within institutions and some shared globally. The RSNA maintains a MIRC site that provides access to libraries around the world.<br />
<br />
Any MIRC site can function as an access point for users, called a query service, or an indexed information library, called a storage service, or both. A query service provides a point of access to a MIRC community. It provides a query form to the user, distributes the search criteria to all selected storage services, collates the responses, and presents them to the user. A storage service responds to the query received from the query service, searches its index for documents meeting the search criteria, and returns abstracts and locations of the matching documents to the query service.<br />
<br />
Authors on a storage service can use a MIRC-defined format to construct teaching files and other documents in a common structure that allows libraries to index the documents in medically meaningful ways. The indexing mechanism provides users great flexibility in searching the MIRC community. Users can perform free-text searches on the contents of documents as well as structured searches on patient criteria (e.g., sex, age), image criteria (e.g., modality, anatomical region, storage format, compression), diagnosis and other codes, through a standard web browser.<br />
<br />
There are several ways for an individual or an institution to establish a system that can participate in a MIRC community:<br />
*The RSNA MIRC software provides both a query service and a storage service as well as support for the MIRC-defined authoring format.<br />
*An existing teaching file system can be modified to use its internal database to provide an index of its documents, requiring only the construction of the software layer necessary to respond to a MIRC query.<br />
*Some commercial teaching file systems also support the MIRC query mechanism, allowing them to participate in a MIRC community.<br />
<br />
=== The RSNA MIRC Site ===<br />
<br />
=== User's Manual ===<br />
The RSNA MIRC implementation has numerous components for accessing, creating, and managing documents and files.<br />
Information on how to use the RSNA MIRC software is collected in a [[MIRC_User%27s_Manual|separate article]].<br />
<br />
=== Administrator's Manual ===<br />
The RSNA MIRC implementation is designed to minimize management effort. The [[MIRC Administrator's Manual]] describes how to set up a MIRC site using the software and how to configure it to meet the needs of its users.<br />
<br />
=== Clinical Trial Administrator's Manual ===<br />
The RSNA MIRC implementation includes a powerful suite of tools to support both single-site and multi-site clinical trials. A [[Clinical Trial Administrator's Manual|separate article]], intended for clinical trial administrators, provides details on configuring the software for a trial. Some of the information may also be useful for MIRC site administrators who want to enable DICOM communication with PACS or modalities and who need to configure the system to manage PHI in accordance with HIPAA regulations.<br />
<br />
=== Developer's Manual ===<br />
The RSNA MIRC implementation is an open source project. Developers are welcome to download the software, modify it for their own purposes, and to participate in the extension of the software for the entire community. <br />
<br />
There are several separate articles which may be of use in this context:<br />
*[[The_RSNA_MIRC_Source_Code|The RSNA MIRC Source Code]] describes the RSNA CVS repository and how to obtain the code from it. It also describes how to build the software using Ant.<br />
*[[Implementing_an_External_Database_Interface_for_MIRC_Clinical_Trials|Implementing an External Database Interface for MIRC Clinical Trials]] describes how to interface an external database to the Database Export Service on a storage service used for a clinical trial.<br />
<br />
All MIRC XML files are described by schema documents:<br />
*[[The MIRCdocument Schema]] describes all the elements in a MIRCdocument.<br />
*[[The MIRCquery Schema]] describes the XML object that carries a query from a query service to a storage service.<br />
*[[The MIRCqueryresult Schema]] describes the XML object that carries query results from a storage service back to a query service.<br />
*[[The MIRC Protocol for Document Exchange]] describes the packaging of a MIRCdocument for exporting from one MIRC site or importing into another one.<br />
*[[The Storage Service List Schema]] describes the XML object for exchanging lists of storage services among query services.<br />
<br />
=== Special Notes ===<br />
=== Tools ===<br />
The RSNA MIRC project has developed several tools which are not part of the MIRC site software but which are useful as stand-alone applications in MIRC-related projects. The source code for all the tools is part of [[the RSNA MIRC Source Code]]. The key ones are:<br />
*DicomEditor: a tool for examining DICOM objects and for testing anonymization scripts for clinical trials. This tool is also useful for correcting certain problems in DICOM objects.<br />
*FileSender: a tool for transmitting files of various types using the DICOM, HTTP, and HTTPS protocols. This tool includes a zip unpacking feature that is very useful when managing large groups of images in multi-centeer clinical trials.<br />
*HttpTest: a tool for testing HTTP connections. This tool is useful for testing the connection of a remote image acquisition site to a principal investigator site in a clinical trial, especially when the remote site is behind a proxy server.<br />
*DicomRouter: a general tool for routing DICOM transmissions to one or more destinations depending on their contents.<br />
*ExportManager: an implementation of the IHE TCE integration profile, providing a very powerful coupling between PACS diagnostic workstations and MIRC.<br />
*[[MIRC Powerpoint Tool|PowerpointTool]]: a Powerpoint plug-in that saves presentations as MIRCdocuments on a MIRC server.</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=The_MIRCdocument_Schema&diff=2044The MIRCdocument Schema2006-08-12T01:38:25Z<p>209.242.55.28: /* <b>metadata-refs</b> */</p>
<hr />
<div>==Introduction==<br />
This article describes the XML schema for indexable documents on sites using the RSNA MIRC software. It is intended for engineers implementing MIRC sites and authoring tools as well as for administrators and MIRCdocument authors who wish to exploit the full capabilities of their sites. The article assumes a basic understanding of XML. For more information on XML, see the [[XML_Primer|XML Primer]].<br />
<br />
The MIRCdocument schema includes all the MIRC-specific elements and attributes that can be included in a document on a MIRC site running the RSNA MIRC software. Where noted below, HTML elements may also be included as well.<br />
<br />
All elements in the schema include a <b>visible</b> attribute that allows the author to instruct a MIRC site's display software whether to render the contents of the element. Except where noted, the default value of the <b>visible</b> attribute is <b>yes</b>. The rendering behavior described inthis article is that provided by the RSNA MIRC software when MIRCdocuments are accessed by a browser (via an HTTP GET). In all cases, if a parent element's <b>visible</b> attribute is <b>no</b>, none of its children are rendered, and if a parent element's <b>visible</b> attribute is <b>yes</b>, only children whose <b>visible</b> attributes are <b>yes</b> are rendered.<br />
<br />
==The <b>MIRCdocument</b> Element==<br />
The <b>MIRCdocument</b> element is the root element of all MIRCdocuments. It encloses all the content of a MIRCdocument:<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
====The <b>docref</b> Attribute====<br />
When a user selects a MIRCdocument for display, the user's browser is directed either to the MIRCdocument itself or to another document. The optional <b>docref</b> attribute provides the link. To understand its use, it is helpful to understand the MIRC search mechanism. <br />
<br />
A user accesses a MIRC Query Service from a web browser. The Query Service provides an HTML form into which the user inserts the search criteria. Upon completion of the form, the browser posts it to the Query Service, which then constructs a query from the form data and posts it to the MIRC Storage Services identified in the form. The query is an XML object in a format defined by the <b>MIRCquery</b> schema. Each Storage Service searches its content for documents matching the search criteria, encodes the list of matching documents in an XML object in a format defined by the <b>MIRCqueryresult</b> schema, and sends the list to the Query Service. In the <b>MIRCqueryresult</b> schema, each document that matches the search criteria is identified by a URL. The Query Service compiles the results from all the Storage Services polled and sends the consolidated results to the user's browser. The consolidated results are constructed as an HTML ordered list, where each item in the list describes one document matching the search criteria and provides a link to the document iself. When the user selects an item in the list, the browser obtains the document identified by the link. In the RSNA MIRC implementation, the <b>docref</b> attribute is used to construct the URL that provides that link. <br />
<br />
Some MIRCdocuments contain a complete document, allowing them to be self-indexing. Other MIRCdocuments serve as indexable documents describing information in other formats. To accommodate these different kinds of MIRCdocuments on sites using the RSNA MIRC software, the docref attribute may be coded in several ways. <br />
*If the <b>docref</b> attribute is not included in the <b>MIRCdocument</b> element, the RSNA MIRC Storage Service provides a link to the file containing the MIRCdocument. This technique is used when the <b>MIRCdocument</b> element contains a complete document. For example, a teaching file case can be constructed as a MIRCdocument and indexed by a Storage Service. When a user selects the document from a list of search results, the link takes the user to the document itself. In this case, the <b>MIRCdocument</b> element is defined without a <b>docref</b> attribute:<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with no path information, the RSNA MIRC Storage Service provides a link to the named document in the same directory on the Storage Service as the MIRCdocument. This technique is used when the MIRCdocument is only a means to index another kind of content. For example, when the actual content of interest is a presentation in PowerPoint format, it can be indexed by creating a short MIRCdocument containing the title, the authors, and an abstract. This MIRCdocument, called an "index card", is only useful during the user's search for the document, so the <b>docref</b> attribute is set to point to the presentation file itself, and the Storage Service stores the presentation file and the index file in the same directory.<br />
<br />
<pre><br />
<MIRCdocument docref="presentationfilename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with path information, the RSNA MIRC Storage Service provides a link to the named document. This technique is a more general example of the previous case. It is used when the actual document of interest is not stored in the same directory on the Storage Service as the MIRCdocument that indexes it. Since authors generally do not control the actual storage locations of their documents, this mechanism is infrequently used, and then only by MIRC administrators.<br />
<br />
This is an example of an index card referencing a presentation stored by a MIRC administrator in a common "presentations" directory under the "MIRCdocuments" directory of the server root:<br />
<br />
<pre><br />
<MIRCdocument docref="/MIRCdocuments/presentations/filename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with a fully qualified path, the RSNA MIRC Storage Service provides a link to the named document. This technique is a more general example of the previous case. It is used when the actual content of interest is a document not stored on the same Storage Service as the MIRCdocument that indexes it. This mechanism can be used to index the contents of a webserver on a MIRC Storage Service without storing the documents on the Storage Service itself. <br />
<br />
This is an example of an index card referencing a document stored somewhere on the web:<br />
<br />
<pre><br />
<MIRCdocument docref="http://www.somewhere.edu/filename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
=====Important Note for MIRC Site Implementers=====<br />
The description in the section above applies to MIRCdocuments stored on MIRC sites using the RSNA MIRC software. It is important not to confuse the flexibility in the use of the <b>docref</b> attribute described here with the inflexible requirement that a Storage Service provide a fully qualified URL for each document in its <b>MIRCqueryresult</b> reply to a Query Service.<br />
<br />
The <b>MIRCqueryresult</b> schema uses the <b>MIRCdocument</b> element to describe each document meeting the search criteria it received in a MIRCquery. A detailed description of the <b>MIRCqueryresult</b> schema is included in a [[The_MIRCquery_and_MIRCqueryresult_Schemas|separate article]]. Briefly, a <b>MIRCqueryresult</b> has the following form:<br />
<br />
<pre><br />
<MIRCqueryresult><br />
<MIRCdocument docref="http://www.somewhere.edu/filename"><br />
…title, author, abstract content…<br />
</MIRCdocument><br />
…additional <MIRCdocument> elements – one for each query match…<br />
</MIRCqueryresult><br />
</pre><br />
<br />
In the <b>MIRCqueryresult</b> schema, each <b>MIRCdocument</b> element is required to provide a fully qualified URL pointing to the document. On sites using the RSNA MIRC software, that URL is generated automatically by the Storage Service as described in the section above for documents with a missing <b>docref</b> attribute or with one that contains a less than fully qualified URL.<br />
<br />
====The <b>display</b> Attribute====<br />
The <b>MIRCdocument</b> element also supports the optional <b>display</b> attribute, which can be used to instruct the MIRC rendering software on how the author intended the document to be displayed. The RSNA MIRC rendering software supports three values of the <b>display</b> attribute:<br />
<br />
*<b>page</b> instructs the rendering software to display the document in a linear, sequential fashion as a normal document would appear. This is the default value.<br />
*<b>tab</b> instructs the rendering software to display the document with each section appearing as a separate tab.<br />
*<b>mstf</b> instructs the rendering software to display the document in a standardized teaching file format oriented toward residents. For compatibility with previous releases, <b>mirctf</b> is a synonym for <b>mstf</b>.<br />
<br />
====The <b>first-tab</b> Attribute====<br />
The <b>first-tab</b> attribute of the <b>MIRCdocument</b> element instructs the rendering software which tab to display first. This attribute is used in the tab and mstf display formats. It is ignored in the page display format. The default value of the first-tab attribute is 2.<br />
<br />
====The <b>show-empty-tabs</b> Attribute====<br />
The <b>show-empty-tabs</b> attribute of the <b>MIRCdocument</b> element instructs the rendering software whether to display sections that have no content. This attribute is used in the tab and mstf display formats. It is ignored in the page display format. The possible values are yes and no. The default value of the show-empty-tabs attribute is no.<br />
<br />
====The <b>background</b> Attribute====<br />
The <b>background</b> attribute of the <b>MIRCdocument</b> element defines the background color of the document when it is displayed. The possible values are <b>light</b> and <b>dark</b>. The default is <b>light</b>.<br />
<br />
====The <b>path</b> Attribute====<br />
The <b>path</b> attribute of the <b>MIRCdocument</b> element is dynamically generated by the RSNA MIRC software when a MIRCdocument is exported from a storage service. It is used to provide third-party, client-side authoring tools the relative path to the document on the server.<br />
<br />
====The <b>as-mode</b> Attribute====<br />
The <b>as-mode</b> attribute of the <b>MIRCdocument</b> element is automatically generated by the Author Service when an author edits the MIRCdocument. It defines whether technical elements are displayed in the editor. Its possible values are <b>true</b> and <b>false</b>.<br />
<br />
====The <b>visible</b> Attribute====<br />
The <b>visible</b> attribute of the <b>MIRCdocument</b> element is ignored by the RSNA MIRC software.<br />
<br />
==Document Structure Elements==<br />
Certain first-generation child elements of the <b>MIRCdocument</b> element are used to provide structure for a document, encapsulating titles, authors, abstracts, keywords, and the various content sections of the document. They are used both to encode key information to be matched against search criteria and to organize the entire document for display.<br />
<br />
The RSNA MIRC software only displays MIRCdocument content which appears within one of these elements. Information included for indexing purposes only can be placed as text value or child elements of the <b>MIRCdocument</b> element or in a <b>section</b> element with the <b>visible</b> attribute set to <b>no</b>.<br />
===<b>title</b>===<br />
The <b>title</b> element contains the title of the document. The <b>title</b> element and the <b>alternative-title</b> element determine the title displayed when the document is rendered or when it appears in a list of search results. See the next section, <b>alternative-title</b>, for details.<br />
HTML should not be embedded in the <b>title</b> element.<br />
<br />
<pre><br />
<MIRCdocument><br />
<title>This is the Title</title><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>title</b> element.<br />
===<b>alternative-title</b>===<br />
The optional <b>alternative-title</b> element provides a title which is used when the document is requested to be displayed as an unknown case. <br />
<br />
HTML should not be embedded in the <b>alternative-title</b> element.<br />
<br />
The RSNA MIRC software ignores the the <b>visible</b> attribute of the <alternative-title> element.<br />
<br />
When the Storage Service receives a query requesting the results as unknowns, it substitutes the contents of the <b>alternative-title</b> element for the <b>title</b> element when constructing the list of query results. If the <b>alternative-title</b> element is missing, the Storage Service generates a title as described in the section on the <b>category</b> element.<br />
<br />
The Storage Service similarly substitutes the contents of the <b>alternative-title</b> element when it is requested to display the document as an unknown.<br />
<br />
===<b>author</b>===<br />
The optional <b>author</b> element contains information for a single author. When a document has multiple authors, multiple <b>author</b> elements are used.<br />
<br />
Within the <b>author</b> element are three optional child elements containing the author's name, affiliation, and contact information.<br />
<br />
HTML should not be embedded in the <b>author</b> element or its children.<br />
<br />
<pre><br />
<MIRCdocument><br />
<title>This is the Title</title><br />
<author><br />
<name>John Author</name><br />
<affiliation>Organization of John Author</affiliation><br />
<contact>Email address of John Author</contact><br />
<contact>Post address of John Author – line 1</contact><br />
<contact>Post address of John Author – line 2</contact><br />
</author><br />
<author><br />
<name>Mary Author</name><br />
<affiliation>Organization of Mary Author</affiliation><br />
<contact>Email address of Mary Author</contact><br />
</author><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the visible attribute of the <b>author</b> element and its children.<br />
<br />
====<b>name</b>====<br />
The <b>name</b> element contains the author's name. No provision is made for identifying the given name, surname, or titles. The value of each <b>name</b> element appears in the search result list.<br />
<br />
====<b>affiliation</b>====<br />
The <b>affiliation</b> element contains one line of the name of an organization with which the author is affiliated. If multiple lines are required, or if the author is affiliated with multiple organizations, multiple <b>affiliation</b> elements are used. No provision is made for separating multiple organizations.<br />
====<b>contact</b>====<br />
The <b>contact</b> element contains one line of information on how to contact the author. If multiple lines are required, multiple <b>contact</b> elements are used. No provision is made for identifying the kind of contact information (phone, email, post, etc.) contained in the element.<br />
===<b>abstract</b>===<br />
The <b>abstract</b> element contains the abstract of the document. The <b>abstract</b> element and the <b>alternative-abstract</b> element determine the abstract displayed when the document is rendered or when it appears in a list of search results. See the next section, <b>alternative-abstract</b>, for details.<br />
<br />
HTML may be used for formatting; in particular, HTML paragraph elements must be used to identify the paragraphs.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<abstract><br />
<p><br />
First <b>paragraph</b> of the abstract.<br />
</p><br />
<p><br />
Second <b>paragraph</b> of the abstract.<br />
</p><br />
</abstract><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b><abstract</b> element.<br />
<br />
===<b>alternative-abstract</b>===<br />
The <b>alternative-abstract</b> element provides an alternative abstract which is used when the document is requested to be displayed as an unknown case.<br />
<br />
HTML may be used for formatting as in the <b>abstract</b> element.<br />
<br />
The RSNA MIRC software ignores the <b>visible</b> attribute of the <b>alternative-abstract</b> element.<br />
<br />
When the Storage Service receives a query requesting the results as unknowns, it substitutes the contents of the <b>alternative-abstract</b> element for the <b>abstract</b> element when constructing the list of query results. If the <b>alternative-abstract</b> element is missing, the Storage Service generates no <b>abstract</b> element.<br />
<br />
For MIRCdocuments with the <b>display</b> attribute set to <b>page</b>, the Storage Service similarly substitutes the contents of the <b>alternative-abstract</b> element when it is requested to display the document as an unknown. (The <b>abstract</b> element is used in MIRCdocuments with the <b>display</b> attribute set to <b>tab</b> or <b>mstf</b>. In these documents, the abstract is included in the first tab and the first tab displayed is typically the second tab, thus concealing the content of the abstract until the user wants to see it.)<br />
<br />
===<b>keywords</b>===<br />
The optional <b>keywords</b> element contains a list of words under which the document should be indexed. Although all words in a document are indexed, the <b>keywords</b> element makes it also possible to query for only those words explicitly identified as keywords.<br />
<br />
HTML should not be embedded in the <b>keywords</b> element.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<keywords>word1 word2 word3</keywords><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>keywords</b> element.<br />
===<b>section</b>===<br />
The optional <b>section</b> element is used to identify separate parts of a MIRCdocument. It contains one attribute, <b>heading</b>, that is used to contain the heading applied to the section when the MIRCdocument is rendered by a browser. The value of the <b>section</b> element is the content of the section. HTML may be used for formatting; in particular, HTML paragraph elements should generally be used to identify paragraphs. (The rendering software can display content not contained in paragraphs, and certain third-party authoring software sometimes creates documents in this way, but the Author Service is more strict than the display software, so it is necessary to use HTML paragraphs if the Author Service is to be used to edit the document.)<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<section heading="Method"><br />
…Method section contents…<br />
</section><br />
<section heading="Results"><br />
…Results section contents…<br />
</section><br />
…more content…<br />
</MIRCdocument><br />
</pre><br />
<br />
MIRCdocuments used as index cards generally do not have <b>section</b> elements since index cards are only displayed as query results. For all other applications of the MIRCdocument schema, however, the <b>section</b> element provides the way for the author to group related parts of the document together. This grouping instructs the RSNA MIRC software on how to handle the parts of the document when it is displayed. For example, in <b>tab</b> display mode, the RSNA MIRC software creates a separate tab for each <b>section</b>, using the <b>heading</b> attribute as the title of the tab.<br />
<br />
===<b>image-section</b>===<br />
The optional <b>image-section</b> element is used to collect groups of related images. The <b>image-section</b> element supports the <b>heading</b> attribute in the <b>page</b> and <b>tab</b> display modes. The <b>heading</b> attribute provides a label for the section containing the images.<br />
<br />
The <b>image-section</b> element supports the <b>image-pane-width</b> attribute, which instructs the RSNA display software how much space to allocate for image display in the right pane in the <b>tab</b> and <b>mstf</b> display modes. The default value of the <b>image-pane-width</b> attribute is 700. The RSNA MIRC software enforces a minimum width of 512.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>image-section</b> element.<br />
<br />
===<b>references</b>===<br />
The optional <b>references</b> element encapsulates a set of <b>reference</b> elements in the MIRCdocument. The RSNA MIRC software generates a separate section entitled "References" when the MIRCdocument is displayed. The software automatically generates an ordered list of the <b>reference</b> child elements.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<references><br />
<reference><br />
…text of the first reference…<br />
</reference><br />
<reference><br />
…text of the second reference…<br />
</reference><br />
…additional references…<br />
</references><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>references</b> element.<br />
====<b>reference</b>====<br />
The <b>reference</b> element is a simple container identifying the enclosed content as a reference to a publication. It has no internal formatting, although this is an area open to extension. Numbering of the <b>reference</b> elements is generated automatically by the <b>references</b> element when the MIRCdocument is rendered. HTML may be embedded in the <b>reference</b> element.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>reference</b> element.<br />
<br />
===<b>rights</b> and <b>publication-date</b>===<br />
If the <b>rights</b> element and/or the <b>publication-date</b> element appear as direct children of the <b>MIRCdocument</b> element, the RSNA MIRC software displays their values at the end of the document. If they appear within a <b>section</b> element, they are displayed as part of the section.<br />
<br />
See the section below for information about the elements and their contents.<br />
<br />
==Special Purpose Elements==<br />
The schema includes many element which identify specific kinds of information. The RSNA MIRC software renders these elements only when they appear within a <b>section</b> element. Each element may appear multiple times in a <b>section</b> element. These elements can also be used to encode non-displayed information for indexing purposes by placing the elements as direct child elements of the <b>MIRCdocument</b> element.<br />
===<b>history</b>===<br />
The optional <b>history</b> element allows content to be identified as a patient history for use in specialized searches.<br />
===<b>findings</b>===<br />
The optional <b>findings</b> element allows content to be identified as the patient's history for use in specialized searches.<br />
===<b>diagnosis</b>===<br />
The optional <b>diagnosis</b> element allows content to be identified as a diagnosis for use in specialized searches. <br />
<br />
The text value of the <b>diagnosis</b> element contains the diagnosis. It may also contain one or more <b>code</b> elements to capture diagnostic coding information. In addition, it may contain a <b>confirmation</b> element to describe how the diagnosis was confirmed.<br />
<pre><br />
<diagnosis><br />
At <confirmation>autopsy</confirmation>, the patient<br />
was determined to have … .<br />
<code coding-system="coding system name">12345.67890</code><br />
</diagnosis><br />
</pre><br />
====<b>confirmation</b>====<br />
The <b>confirmation</b> element describes how a diagnosis was confirmed.<br />
<br />
===<b>differential-diagnosis</b>===<br />
The optional <b>differential-diagnosis</b> element allows all or part of a part of a section to be identified as the differential diagnosis of the current case for use in specialized searches.<br />
===<b>discussion</b>===<br />
The optional <b>discussion</b> element allows all or part of a part of a section to be identified as case discussion for use in specialized searches.<br />
===<b>pathology</b>===<br />
The optional <b>pathology</b> element allows all or part of a part of a section to be identified as pathology relating to the case for use in specialized searches.<br />
===<b>anatomy</b>===<br />
The optional <b>anatomy</b> element allows all or part of a part of a section to be identified as anatomy relating to the case for use in specialized searches.<br />
===<b>organ-system</b>===<br />
The optional <b>organ-system</b> element allows all or part of a part of a section to be identified as anatomy relating to the case for use in specialized searches.<br />
===<b>a</b>===<br />
The <b>a</b> element inserts a hyperlink into a MIRCdocument. The <b>a</b> element is taken directly from HTML, with the addition of the format attribute:<br />
*<b>href</b> contains the address of the document to which the value text is linked.<br />
*<b>format</b> contains a description of the format of the document to be found at <b>href</b>.<br />
<br />
The value text contains the link text that is rendered in the MIRCdocument.<br />
<br />
The <b>format</b> attribute is optional and is not displayed in the MIRCdocument.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>a</b> element and applies instead the <b>visible</b> attribute of its parent.<br />
<br />
Note:<br />
In version 8.0 of the schema, the <b>link</b> element was used as a synonym of the <b>a</b> element, but only the <b>link</b> element had the <b>format</b> attribute. To eliminate any confusion with the HTML <b>link</b> element, subsequent versions deprecate the <b>link</b> element and add the <b>format</b> attribute to the <b>a</b> element. <br />
<br />
===<b>code</b>===<br />
The <b>code</b> element contains information related to a medical code. It has one attribute and value text:<br />
*<b>coding-system</b> contains the name of the code, e.g., CPT.<br />
*the value text contains the code value itself.<br />
The <b>code</b> element can optionally contain a <b>meaning</b> element. <br />
<br />
When rendered by the RSNA MIRC software, the <b>code</b> element is displayed as: <br />
<br />
<center><br />
[<b>coding-system</b> attribute value]:[<b>code</b> element value] ([<b>meaning</b> element value])<br />
</center><br />
<br />
For example, the following element:<br />
<br />
<pre><br />
<code coding-system="MyCode" visible="yes"><br />
12345.67890<br />
</code><br />
</pre><br />
is displayed by the RSNA MIRC software as: MyCode:12345.67890<br />
====<b>meaning</b>====<br />
The <b>meaning</b> element is used to encapsulate the human language meaning of the code value.<br />
For example, the following element:<br />
<pre><br />
<code coding-system="MyCode" visible="yes"><br />
12345.67890<br />
<meaning visible="yes"><br />
normal variant<br />
</meaning><br />
</code><br />
</pre><br />
is displayed by the RSNA MIRC software as: <br />
MyCode:12345.67890 (normal variant)<br />
<br />
===<b>modality</b>===<br />
The optional <b>modality</b> element contains a list of the modalities related to the document. If contained within an <b>image</b> element, it identifies the modality of the image.<br />
<br />
===<b>patient</b>===<br />
The <b>patient</b> element is used to encapsulate elements describing specific parameters of a patient. <br />
<br />
The subsections below describe the child elements unique to the <b>patient</b> element. Here is an example using some of the child elements:<br />
<br />
<pre><br />
<patient><br />
<pt-name>John Doe</pt-name><br />
<pt-id>7654321</pt-id><br />
<pt-mrn>1234567</pt-id><br />
<pt-age><br />
<years>3</years><br />
</pt-age><br />
<pt-sex>male</pt-sex><br />
<pt-race>caucasian</pt-race><br />
</patient><br />
</pre><br />
====<b>pt-name</b>====<br />
The <b>pt-name</b> element may be used to identify a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-id</b>====<br />
The <b>pt-id</b> element may also be used to identify a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-mrn</b>====<br />
The <b>pt-mrn</b> element may be used to identify the medical record number of a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-age</b>====<br />
The <b>pt-age</b> element encapsulates one or more of the following child elements: <br />
*<b>years</b><br />
*<b>months</b><br />
*<b>weeks</b><br />
*<b>days</b><br />
=====<b>years</b>=====<br />
The <b>years</b> element contains the patient age if expressed in years.<br />
=====<b>months</b>=====<br />
The <b>months</b> element contains the patient age if expressed in months.<br />
=====<b>weeks</b>=====<br />
The <b>weeks</b> element contains the patient age if expressed in weeks.<br />
=====<b>days</b>=====<br />
The <b>days</b> element contains the patient age if expressed in days.<br />
====<b>pt-sex</b>====<br />
The <b>pt-sex</b> element contains one of the values male or female (or neutered in veterinary medicine applications).<br />
====<b>pt-race</b>====<br />
The <b>pt-race</b> element contains the name of the race of the patient.<br />
====<b>pt-species</b>====<br />
<b>pt-species</b> element contains the name of the species of the patient. This element is intended for use in veterinary medicine and paleontology.<br />
====<b>pt-breed</b>====<br />
The <b>pt-breed</b> element contains the name of the breed of the patient. This element is intended for use in veterinary medicine.<br />
<br />
===<b>image</b>===<br />
The <b>image</b> element is used to encapsulate an image and related information<br />
Its <b>src</b> attribute contains the URL of the image to be displayed.<br />
<br />
The <b>image</b> element also has the <b>width</b> and <b>height</b> attributes of the HTML <b>img</b> element. These are passed to the browser to set the displayed width and height of the image; they do not refer to the actual size of the image in the file on the server.<br />
<br />
The value of an <b>image</b> element may be empty or it one or more <b>alternative-image</b> elements, and optionally <b>patient</b>, <b>diagnosis</b>, <b>anatomy</b>, <b>pathology</b>, and <b>code</b> elements to associate the parameters of the patient and/or the diagnosis with the image. It may also contain the <b>modality</b>, <b>format</b> and <b>compression</b> elements to encode parameters of the image itself.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>image</b> element and applies instead the <b>visible</b> attribute of its parent.<br />
<br />
The following example shows the use of an <b>image</b> element to include a JPEG image directly in the rendered document.<br />
<pre><br />
<image src="http://www.abc.edu/images/image1.jpeg"><br />
<format>jpeg</format><br />
</image><br />
</pre><br />
The image appears in sequence with the rest of the text value of the element in which the <b>image</b> element is contained.<br />
<br />
The following more complex coding of the previous example shows the use of multiple child elements within an <b>image</b> element.<br />
<pre><br />
<a href="http://www.abc.edu/images/image1.dcm"><br />
<image src="http://www.abc.edu/images/image1.jpeg"><br />
<format visible=”no”>DICOM</format><br />
<compression visible=”no”>original</compression><br />
<modality visible=”no”>CT</modality><br />
<anatomy visible=”no”>abdomen</anatomy><br />
<pathology visible=”no”>renal carcinoma</pathology><br />
<patient visible=”no”><br />
<pt-age><br />
<years>86</years><br />
</pt-age><br />
<pt-sex>male</pt-sex><br />
</patient><br />
<diagnosis visible=”no”><br />
renal carcinoma<br />
<confirmation>pathology</confirmation><br />
<code coding-system="ABC Code">1234.5678</code><br />
</diagnosis><br />
</image><br />
</a><br />
</pre><br />
The RSNA MIRC implementation often groups related images together within an <b>image</b> element which appears in an <b>image-section</b>. Such groups are sometimes called "megasave groups". The following example shows a megasave group for an image.<br />
<pre><br />
<image src="IMG_1719.jpg" width="374"><br />
<alternative-image role="icon" src="IMG_1719_icon"/><br />
<alternative-image role="annotation" src="IMG_1719_an.svg" type="svg"/><br />
<alternative-image role="annotation" src="IMG_1719_an.jpg" type="image"/><br />
<alternative-image role="original-dimensions" src="IMG_1719_orig.jpg"/><br />
<alternative-image role="original-format" src="IMG_1719.dcm"/><br />
</image><br />
</pre><br />
In this group, the <b>alternative-image</b> children are different versions of the original image (in this case, <b>IMG_1719.dcm</b>) for various purposes. As in the preceding example, other child elements could have been included to provide additional information about the group.<br />
====<b>format</b>====<br />
The <b>format</b> element is used to identify the storage format of an image.<br />
The <b>format</b> element has the enumerated values:<br />
*<b>DICOM</b><br />
*<b>JPEG</b><br />
*<b>PNG</b><br />
*<b>GIF</b><br />
*<b>TIFF</b><br />
====<b>compression</b>====<br />
The <b>compression</b> element is used to identify the compression history of an image.<br />
The <b>compression</b> element has four enumerated values:<br />
*<b>original</b><br />
*<b>reversible</b><br />
*<b>non-reversible</b><br />
*<b>unknown</b><br />
A value at any level in the list above implies that the compression history of the image does not include a version at a lower level. Thus, a value of <b>reversible</b> implies that the image in question is not simply a reversibly compressed version of an image that was non-reversibly compressed.<br />
====<b>alternative-image</b>====<br />
The <b>alternative-image</b> element identifies a version of the parent <b>image</b> element intended to be used for a specific purpose. The <b>alternative-image</b> element has two required attributes.<br />
*<b>src</b> contains the URL of the <b>alternative-image</b>.<br />
*<b>role</b> identifies the purpose of the <b>alternative-image</b>. <br />
The <b>role</b> attribute has four enumerated values:<br />
*<b>icon</b> identifies the <b>alternative-image</b> as a small image intended for use as an icon link to the parent image.<br />
*<b>annotation</b> identifies the <b>alternative-image</b> as annotations for the parent image.<br />
*<b>original-dimensions</b> identifies the <b>alternative-image</b> as a version of the parent image having the same dimensions as the original-format image.<br />
*<b>original-format</b> identifies the <b>alternative-image</b> as the original image acquired by the modality (except for changes required for anonymization).<br />
The <b>alternative-image</b> element with <b>role=”annotation”</b> has one additional attribute, <b>type</b>, that describes the format of the annotation data. The type attribute has two enumerated values:<br />
*<b>image</b> (the default) identifies the annotation data as an image that is to replace the primary image when annotations are displayed.<br />
*<b>svg</b> identifies the annotation data as scalar vector graphics instructions for displaying the annotations overlaid on the primary image when annotations are to be displayed.<br />
The <b>alternative-image</b> element may optionally contain the <b>width</b> and <b>height</b> attributes of the HTML <b>img</b> element. <br />
The <b>alternative-image</b> element is always a child of a <b>image</b> element, and its <b>visible</b> attribute and those of all its children are ignored. <br />
The <b>alternative-image</b> element may also contain <b>format</b> and <b>compression</b> child elements.<br />
<br />
===<b>quiz</b>===<br />
The <b>quiz</b> element is used to contain a quiz that is displayed within a <b>section</b> element in the MIRCdocument. Multiple <b>quiz</b> elements may appear within one <b>section</b> element. Multiple <b>section</b> elements may contain <b>quiz</b> elements.<br />
A quiz has the following structure:<br />
<br />
<pre><br />
<quiz id="…"><br />
<quiz-context><br />
…content defining the context of the quiz…<br />
</quiz-context><br />
<question><br />
<question-body><br />
…content defining the question…<br />
</question-body><br />
<answer correct="yes|no"><br />
<answer-body><br />
…content shown to the user as a possible selection…<br />
</answer-body><br />
<response><br />
…content shown to the user if the answer is selected…<br />
</response><br />
</answer><br />
…additional <answer> elements…<br />
</question><br />
…additional <question> elements…<br />
</quiz><br />
</pre><br />
The <b>quiz</b> element has an <b>id</b> attribute that is intended to allow a CME interface to distinguish all the quizzes in a document. The value of the <b>id</b> attribute should be unique within the <b>MIRCdocument</b>.<br />
<br />
HTML and MIRC elements are permitted in all the child elements. Numbering of the questions and answers is generated automatically by the display software.<br />
<br />
Within a single <b>quiz</b> element, there is no limit to the number of <b>question</b> elements.<br />
<br />
The RSNA MIRC software ignores the <b>visible</b> attribute of the <b>quiz</b> element and all its children.<br />
====<b>quiz-context</b>====<br />
The optional <b>quiz-context</b> element contains any description required to provide a context for the questions to follow. <br />
====<b>question</b>====<br />
The <b>question</b> element contains the body of a quiz question and its possible answers. <br />
Within a single <b>question</b> element, there is no limit to the number of <b>answer</b> elements.<br />
=====<b>question-body</b>=====<br />
The <b>question-body</b> element contains the content of a quiz question. <br />
=====<b>answer</b>=====<br />
The <b>answer</b> element contains the body of an answer to a quiz question and the response which will be provided if the user selects the answer.<br />
<br />
The <b>answer</b> element may contain a <b>correct</b> attribute indicating whether the answer is correct (<b>yes</b>) or not (<b>no</b>). At least one answer to a question must be identified as being correct. Multiple answers to a single question may be identified as being correct. The default value of the <b>correct</b> attribute is <b>no</b>.<br />
======<b>answer-body</b>======<br />
The <b>answer-body</b> element contains the body of an answer to a quiz question. <br />
======<b>response</b>======<br />
The optional <b>response</b> element contains the response which the browser will display if the user selects the answer.<br />
<br />
===<b>show</b>===<br />
The <b>show</b> element is a special purpose display command for documents in the <b>mstf</b> display mode. It is used within paragraphs in <b>section</b> elements to generate a button that allows the user to display a specific image. The <b>show</b> element has two possible attributes, only one of which may be present in any specific element:<br />
*<b>image=”n”</b> causes the button to display the image corresponding to the <b>src</b> attribute of the n-th <b>image</b> element in the <b>image-section</b>.<br />
*<b>annotation=”n”</b> causes the button to display the image corresponding to the <b>src</b> attribute of the <alternative-image role=”annotation”> child element of the n-th <b>image</b> element in the <b>image-section</b>.<br />
<br />
The <b>show</b> element is ignored in the <b>page</b> and <b>tab</b> display modes.<br />
<br />
The <b>show</b> element contains no text or element children. The proper usage is:<br />
<pre><show image="3"/></pre><br />
or <br />
<pre><show annotation="2"/></pre><br />
<br />
===<b>text</b>===<br />
The <b>text</b> element is an encapsulating element whose contents are rendered as if they were part of the element’s parent element. Its function has been overtaken by the development of the T25 version of the Author Service, but it remains in the schema for backward compatibility.<br />
<br />
===<b>text-caption</b>===<br />
The <b>text-caption</b> element is used to embed a centered caption between groups of content in a <b>section</b> element. The <b>text-caption</b> element has several optional attributes:<br />
*<b>display</b> can have the values <b>always</b> and <b>normal</b>. The default is <b>normal</b>.<br />
*<b>jump-buttons</b> can have the values <b>yes</b> and <b>no</b>. The default is <b>no</b>.<br />
*<b>show-button</b> can have the values <b>yes</b> and <b>no</b>. The default is <b>no</b>.<br />
The rendering of the <b>text-caption</b> element depends on its contents and on the values of the <b>display</b>, <b>jump-buttons</b> and <b>show-button</b> attributes:<br />
*If the <b>text-caption</b> element contains only whitespace text, the entire element is ignored when the MIRCdocument is rendered unless the <b>display</b> attribute is present with the value <b>always</b>, in which case the element is rendered, essentially providing an HTML break in the flow. <br />
*If the <b>text-caption</b> element contains any non-whitespace text, the text contents are displayed. <br />
*If the <b>jump-buttons</b> attribute has the value <b>yes</b>, the rendering software inserts two HTML buttons with the values “<<<” and “>>>”. The buttons allow the user to jump up or down to the previous or next <b>text-caption</b>. <br />
*If the the <b>show-button</b> attribute has the value <b>yes</b> and the text content of the caption is non-whitespace, then the text content of the caption is initially hidden when the document is rendered and an HTML button with the value “Show Caption” is inserted between the “<<<” and “>>>” buttons, allowing the user to reveal the caption after examining the content above it.<br />
Note: The RSNA MIRC software also supports the substitution of images for the buttons described above. The default is to use the button images distributed with the software. The buttons are contained in the storage service's <b>buttons</b> directory and are called:<br />
*back.png<br />
*showcaption.png<br />
*forward.png<br />
===<b>metadata-refs</b>===<br />
The RSNA MIRC implementation calls all files "metadata files". The <b>metadata-refs</b> element encapsulates a list of references to metadata files. The <b>metadata-refs</b> element may appear anywhere within a <b>section</b> element. It is rendered by the RSNA MIRC software as a table, with each of its <b>metadata</b> child elements being one row. The value of each <b>metadata</b> element's <b>href</b> attribute provides a link to the corresponding metadata file. The RSNA MIRC software ignores the <b>visible</b> attribute of the <b>metadata-refs</b> element and all its children.<br />
====<b>metadata</b>====<br />
The <b>metadata</b> element identifies a reference to a single data file. It has one required attribute, <b>href</b>, which provides the URL of the data file. There are three child elements.<br />
=====<b>type</b>=====<br />
The <b>type</b> element identifies the type of the metadata file. MIRC currently defines four classes:<br />
*<b>DicomObject</b>: a DICOM file (image, GSPS, KOS, or SR)<br />
*<b>XmlObject</b>: an XML file of any kind<br />
*<b>ZipObject</b>: a zip file with any contents<br />
*<b>FileObject</b>: any file not meeting the criteria above.<br />
<br />
=====<b>date</b>=====<br />
The <b>date</b> element identifies the date associated with the metadata file. The MIRCdocument generator attempts to get the date from the file, and if it fails, uses the last modified date of the file (typically the date the file was received).<br />
<br />
=====<b>desc</b>=====<br />
The <b>desc</b> element describes the metadata file. The MIRCdocument generator attempts to get the description from the file, and if it fails, inserts the file name.<br />
<br />
==Document Description Elements==<br />
Document description elements are used to describe a document at a high level. They typically appear as children of the <b>MIRCdocument</b> element and are therefore not displayed. However, they may also be placed within <b>section</b> elements if display is desired. With the exception of the <b>rights</b> element, HTML may not be used in these elements.<br />
===<b>phi</b>===<br />
The <b>phi</b> element identifies the protected health information (PHI) that is contained in the document. Absence of the element is interpreted to mean that the document contains no PHI. If the document contains PHI, the <b>phi</b> element contains one or more <b>study</b> child elements, each identifying one patient study referenced in the document. The contents of the PHI element and its children are not rendered by the RSNA MIRC implementation; they are used only to provide access logging information required by HIPAA.<br />
====<b>study</b>====<br />
The <b>study</b> element encapsulates the PHI for one patient study. If the document contains PHI for multiple studies, multiple <b>study</b> elements must be present.<br />
=====<b>si-uid</b>=====<br />
The <b>si-uid</b> element contains the Study Instance UID of the study whose images or patient identifying information are contained in the document.<br />
=====<b>pt-id</b>=====<br />
The <b>pt-id</b> element contains the identifier of the patient corresponding to the study.<br />
=====<b>pt-name</b>=====<br />
The <b>pt-name</b> element contains the name of the patient corresponding to the study.<br />
===<b>document-type</b>===<br />
The optional <b>document-type</b> element identifies the document as one of the following types:<br />
*<b>radiologic teaching file</b>: a teaching file, which may be a single case or a collection of cases in a single MIRCdocument<br />
*<b>radiologic collection</b>: a document containing references to multiple radiologic teaching files; a course; a conference<br />
*<b>research dataset</b>: a MIRCdocument describing and containing a link to a research dataset<br />
*<b>educational document</b>: an educational document, e.g. a presentation or course<br />
*<b>technical document</b>: a technical document<br />
Since the MIRCdocument schema permits the construction of complex documents combining characteristics of all the listed document types, multiple types may be listed within the element.<br />
<br />
===<b>category</b>===<br />
The optional <b>category</b> element identifies the document as belonging to one of the American Board of Radiology categories:<br />
*<b>Musculoskeletal</b><br />
*<b>Pulmonary</b><br />
*<b>Cardiovascular </b><br />
*<b>Gastrointestinal</b><br />
*<b>Genitourinary</b><br />
*<b>Neuro</b><br />
*<b>Vascular and Interventional</b><br />
*<b>Nuclear</b><br />
*<b>Ultrasound</b><br />
*<b>Pediatric</b><br />
*<b>Breast</b><br />
When searching for teaching file documents, a user may request that query results be displayed as unknowns. In this case, if the document does not contain an <b>alternative-title</b> element, the RSNA MIRC Storage Service generates a title in the form "Unknown - <b>category value</b>".<br />
<br />
===<b>level</b>===<br />
The optional <b>level</b> element indicates the degree of difficulty of the document. It is intended to allow teaching files to be graded for difficulty, allowing students to search for teaching files corresponding to their level. The level element contains one of:<br />
*<b>primary</b><br />
*<b>intermediate</b><br />
*<b>advanced</b><br />
===<b>lexicon</b>===<br />
The optional <b>lexicon</b> element identifies the name of the lexicon used in the document. <br />
===<b>access</b>===<br />
The optional <b>access</b> element indicates whether a document is accessible:<br />
*<b>public</b>: accessable by anyone<br />
*<b>restricted</b>: accessible only by certain authenticated users<br />
*<b>owner</b>: accessible only by the owner of the document<br />
This element is automatically generated by the RSNA MIRC site software from the contents of the <b>authorization</b> element.<br />
===<b>authorization</b>===<br />
The optional <b>authorization</b> element controls access to the document for various purposes.<br />
====<b>owner</b>====<br />
The optional <b>owner</b> element defines the owner of the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a comma or whitespace delimited list of usernames to be granted all privileges (read, update, export, delete).<br />
====<b>read</b>====<br />
The optional <b>read</b> element defines the individuals or groups who are authorized to view the the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to read the document. Individual users can be granted the read privilege by including their usernames in the list enclosed in square brackets as in this example:<br />
<pre><read>resident staff [drjones] [drjohnson] technologist</read></pre><br />
If the <b>read</b> element is missing, or if the value of the element contains “*”, all users are granted read access. <br />
====<b>update</b>====<br />
The optional <b>update</b> element defines the individuals or groups who are authorized to modify the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to access the document through the author service and store modifications back on the server. Individual users can be granted the update privilege by including their usernames in the list enclosed in square brackets as in the example above.<br />
<br />
If the <b>update</b> element is missing, updates are not authorized. If the value of the element contains “*”, all users are granted update privileges. <br />
====<b>export</b>====<br />
The optional <b>export</b> element defines the individuals or groups who are authorized to export the document from the server to their browser in the source format. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to export the standard MIRC zip file containing the document’s XML file and all its local references. Individual users can be granted the export privilege by including their usernames in the list enclosed in square brackets as in the example above.<br />
<br />
If the <b>export</b> element is missing, or if the value of the element contains “*”, all users are granted export privileges.<br />
<br />
===<b>peer-review</b>===<br />
The optional <b>peer-review</b> element contains information about the peer-review status of the document. If the <b>peer-review</b> element is missing, the document is assumed not to have been peer-reviewed. If the element is present, it must contain child elements identifying the reviewing authority and the status of the peer-review. If the <peer-review> element is displayed, all its children are displayed.<br />
====<b>approval-date</b>====<br />
The <b>approval-date</b> element represents the date on which the document was approved by the reviewing authority. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
====<b>expiration-date</b>====<br />
The optional <b>expiration-date</b> element represents the date on which the reviewing authority's approval of the document will expire. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
====<b>reviewing-authority</b>====<br />
The <b>reviewing-authority</b> element contains the name of the institution or organization responsible for providing the independent peer review before publication. <br />
====<b>reviewer</b>====<br />
The optional <b>reviewer</b> element contains the name of the reviewer.<br />
<br />
===<b>language</b>===<br />
The optional <b>language</b> element specifies the language in which the document is written.<br />
The <b>language</b> element has a required <b>code</b> attribute specifying the ISO 639:1988(E) two-letter code for the language, as defined as in http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt.<br />
<br />
The following code fragment:<br />
<pre><language code="en">English</language></pre><br />
generates the word "English".<br />
<br />
The RSNA MIRC software does not enforce the correspondence between the value of the <b>code</b> attribute and the value of the element. Query searches on language use the value of the <b>code</b> attribute, so the following fragment will possibly produce unexpected results:<br />
<pre><language code="en">French</language></pre><br />
<br />
===<b>creator</b>===<br />
The optional <b>creator</b> element identifies the application program that was used to create the document.<br />
===<b>document-id</b>===<br />
The optional <b>document-id</b> element is intended to provide a place to store a unique identifier for the document. This element is not yet implemented in the RSNA MIRC software.<br />
<br />
===<b>publication-date</b>===<br />
The optional <b>publication-date</b> element contains the date associated with the document, coded in accordance with ISO 8601 (e.g., yyyy-mm-dd). <br />
===<b>revision-history</b>===<br />
The optional <b>revision-history</b> element encapsulates a set of <b>revision</b> elements, one for each revision of the document. If the <b>revision-history</b> element is displayed, all its children are displayed.<br />
====<b>revision</b>====<br />
The optional <b>revision</b> element encapsulates a set of elements that define the author of the revision, the date, and a description of the revision. When present, it must contain the child elements <b>revision-author</b>, <b>revision-date</b>, and <b>revision-description</b>.<br />
=====<b>revision-author</b>=====<br />
The <b>revision-author</b> element contains the name of the person who authored or revised the document.<br />
=====<b>revision-date</b>=====<br />
The <b>revision-date</b> element contains the release date of the revision. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
=====<b>revision-description</b>=====<br />
The <b>revision-description</b> element contains a description of the changes made in the revision.<br />
<br />
===<b>rights</b>===<br />
The optional <b>rights</b> element can contain any text describing the rights held to the document. HTML may be used to format the presentation of the rights text.<br />
<br />
When the <b>rights</b> element is not contained within a <b>section</b> element, the RSNA MIRC software automatically displays the contents of the <b>rights</b> element at the end of a MIRCdocument. This is the only instance where a document description element is displayed when it is not contained within a document structure element.<br />
<br />
==Template Elements==<br />
The RSNA MIRC implementation uses XML files as templates for the automatic construction of MIRCdocuments by several of the services provided by a Storage Service. These are:<br />
*the Author Service<br />
*the DICOM Service<br />
*the TCE Service<br />
*the Zip Service<br />
Except in the case of the Author Service, the reception of a file by a service triggers either the construction of a new MIRCdocument or the modification of an existing one. Templates are MIRCdocument files, that is, they obey the MIRCdocument schema, extended to include elements that instruct the automatic document construction mechanism how to insert data from a file into the MIRCdocument. Except where noted below, template elements themselves are not displayed when a MIRCdocument is displayed.<br />
<br />
===<b>DICOM Elements</b>===<br />
DICOM elements in a template instruct the MIRCdocument generator to insert the values of DICOM dataset elements of a DICOM object into a MIRCdocument. DICOM elements are of the form <GxxxxEyyyy/>. DICOM elements have no child elements or text values. The group (G) and element (E) identifiers (xxxx and yyyy) are 4-place hexadecimal numbers. Upper case and lower case may be mixed anywhere within the element name. <br />
<br />
DICOM elements have an optional <b>desc</b> attribute which is typically used to indicate the human-readable name of the DICOM element it references. This attribute is not used by the MIRCdocument generator if the element references a DICOM element in the DICOM dictionary. For private elements in the dataset, however, it can provide a label for the data in a table. Generally it is recommended to supply the <b>desc</b> attribute, if only to make the template file more readable. The following are examples of DICOM elements:<br />
<pre><br />
<g0010e0010 desc="Patient Name"/><br />
<G0010E0011 desc="Patient ID"/><br />
<g0011e0030 desc="A Private Element"/><br />
</pre><br />
As a MIRCdocument is created from a template, DICOM elements are removed and replaced by data values from the DICOM object which occasioned the creation of the MIRCdocument in the first place. For this reason, DICOM elements can only be populated from the first DICOM object encountered for the document unless the elements are wrapped in a <b>block</b> element.<br />
===<b>block</b>===<br />
The <b>block</b> element is used to encapsulate template contents that are to be preserved for application to every object that is inserted into the MIRCdocument. The MIRCdocument generator processes the contents of the <b>block</b> element and inserts them immediately before the <b>block</b> element in the MIRCdocument. The <b>block</b> element itself is not rendered when the MIRCdocument is displayed.<br />
<br />
This is an example of a <b>block</b> element being used to create a table of SOP Instance UIDs for the objects inserted into a MIRCdocument in a clinical trial:<br />
<pre><br />
<section heading="SOP Instance UIDs"><br />
<p><br />
<table border="1"><br />
<tr><th>Image Number</th><th>SOP Instance UID</th></tr><br />
<block><br />
<tr><br />
<td><g0020e0013 desc="Instance Number"/></td><br />
<td><g0008e0018 desc="SOP Instance UID"/></td><br />
</tr><br />
</block><br />
</table><br />
</p><br />
</section><br />
</pre><br />
<br />
===<b>insert-image</b>===<br />
The <b>insert-image</b> element appears within a <b>section</b> element and instructs the MIRCdocument generator to insert a reference to an image. It supports the following attributes:<br />
*<b>width</b> specifies the maximum width of the JPEG image to be created. The default value is 700.<br />
*<b>min-width</b> specifies the minimum width of the JPEG image to be created. The default value is 0.<br />
*<b>extra-image-min-size</b> specifies the minimum width of an extra JPEG image to be created but not referenced by the MIRCdocument. If the attribute is not present, or if the image being inserted is not a DICOM image, no extra image is created. <br />
*<b>caption</b> specifies whether a <b>text-caption</b> element is to be generated after the image reference. The value of the <b>caption</b> attribute must be numeric.<br />
*<b>jump-buttons</b> indicates whether the <b>text-caption</b> element is to be generated with a <b>jump-buttons</b> attribute. The possible values of the next-button attribute are <b>yes</b> and <b>no</b>.<br />
*<b>show-button</b> indicates whether the <b>text-caption</b> element is to be generated with a <b>show-button</b> attribute. The possible values of the next-button attribute are <b>yes</b> and <b>no</b>.<br />
<br />
The <b>insert-image</b> element has no child elements or text value.<br />
<br />
===<b>insert-megasave</b>===<br />
The <b>insert-megasave</b> element appears within an <b>image-section</b> element and instructs the MIRCdocument generator to insert a reference to a megasave image group. It supports the following attributes:<br />
*<b>width</b> specifies the maximum width of the JPEG image to be created. The default value is 700.<br />
*<b>min-width</b> specifies the minimum width of the JPEG image to be created. The default value is 0.<br />
*<b>extra-image-min-size</b> specifies the minimum width of an extra JPEG image to be created but not referenced by the MIRCdocument. If the attribute is not present, or if the image being inserted is not a DICOM image, no extra image is created.<br />
<br />
The <b>insert-megasave</b> element has no child elements or text value.<br />
<br />
===<b>insert-dataset</b>===<br />
The <b>insert-dataset</b> element instructs the MIRCdocument generator to create a folder hierarchy within the MIRCdocument’s directory and store a copy of a DICOM image within it. The <b>insert-dataset</b> element appears as a first-generation child of the <b>MIRCdocument</b> element.<br />
<br />
The <b>insert-dataset</b> element supports the <b>phi</b> attribute, which specifies whether the stored DICOM instance is to contain protected healthcare information. The possible values of the phi attribute are <b>yes</b> and <b>no</b>:<br />
<br />
*<b>phi=”yes”</b> creates a folder named <b>phi</b>. Instances are stored unmodified in subdirectories named for the Series Description (if present), the Series Number (if present), or the Series Instance UID. <br />
<br />
*<b>phi=”no”</b> creates a folder named <b>no-phi</b>. Instances are first de-identified using the storage service’s anonymization rules and then stored in subdirectories named as described above.<br />
<br />
When MIRCdocuments containing <b>insert-dataset</b> elements are displayed, links are provided allowing for the export of a zip file containing the requested dataset.<br />
<br />
===<b>metadata-refs</b>===<br />
The <b>metadata-refs</b> element instructs the MIRCdocument generator to insert a <b>metadata</b> child element to identify a file referenced by the MIRCdocument. This element and its children are described in the [[#metadata-refs|Special Purpose Elements section]].</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=The_MIRCdocument_Schema&diff=2043The MIRCdocument Schema2006-08-12T01:36:55Z<p>209.242.55.28: /* <b>insert-dataset</b> */</p>
<hr />
<div>==Introduction==<br />
This article describes the XML schema for indexable documents on sites using the RSNA MIRC software. It is intended for engineers implementing MIRC sites and authoring tools as well as for administrators and MIRCdocument authors who wish to exploit the full capabilities of their sites. The article assumes a basic understanding of XML. For more information on XML, see the [[XML_Primer|XML Primer]].<br />
<br />
The MIRCdocument schema includes all the MIRC-specific elements and attributes that can be included in a document on a MIRC site running the RSNA MIRC software. Where noted below, HTML elements may also be included as well.<br />
<br />
All elements in the schema include a <b>visible</b> attribute that allows the author to instruct a MIRC site's display software whether to render the contents of the element. Except where noted, the default value of the <b>visible</b> attribute is <b>yes</b>. The rendering behavior described inthis article is that provided by the RSNA MIRC software when MIRCdocuments are accessed by a browser (via an HTTP GET). In all cases, if a parent element's <b>visible</b> attribute is <b>no</b>, none of its children are rendered, and if a parent element's <b>visible</b> attribute is <b>yes</b>, only children whose <b>visible</b> attributes are <b>yes</b> are rendered.<br />
<br />
==The <b>MIRCdocument</b> Element==<br />
The <b>MIRCdocument</b> element is the root element of all MIRCdocuments. It encloses all the content of a MIRCdocument:<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
====The <b>docref</b> Attribute====<br />
When a user selects a MIRCdocument for display, the user's browser is directed either to the MIRCdocument itself or to another document. The optional <b>docref</b> attribute provides the link. To understand its use, it is helpful to understand the MIRC search mechanism. <br />
<br />
A user accesses a MIRC Query Service from a web browser. The Query Service provides an HTML form into which the user inserts the search criteria. Upon completion of the form, the browser posts it to the Query Service, which then constructs a query from the form data and posts it to the MIRC Storage Services identified in the form. The query is an XML object in a format defined by the <b>MIRCquery</b> schema. Each Storage Service searches its content for documents matching the search criteria, encodes the list of matching documents in an XML object in a format defined by the <b>MIRCqueryresult</b> schema, and sends the list to the Query Service. In the <b>MIRCqueryresult</b> schema, each document that matches the search criteria is identified by a URL. The Query Service compiles the results from all the Storage Services polled and sends the consolidated results to the user's browser. The consolidated results are constructed as an HTML ordered list, where each item in the list describes one document matching the search criteria and provides a link to the document iself. When the user selects an item in the list, the browser obtains the document identified by the link. In the RSNA MIRC implementation, the <b>docref</b> attribute is used to construct the URL that provides that link. <br />
<br />
Some MIRCdocuments contain a complete document, allowing them to be self-indexing. Other MIRCdocuments serve as indexable documents describing information in other formats. To accommodate these different kinds of MIRCdocuments on sites using the RSNA MIRC software, the docref attribute may be coded in several ways. <br />
*If the <b>docref</b> attribute is not included in the <b>MIRCdocument</b> element, the RSNA MIRC Storage Service provides a link to the file containing the MIRCdocument. This technique is used when the <b>MIRCdocument</b> element contains a complete document. For example, a teaching file case can be constructed as a MIRCdocument and indexed by a Storage Service. When a user selects the document from a list of search results, the link takes the user to the document itself. In this case, the <b>MIRCdocument</b> element is defined without a <b>docref</b> attribute:<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with no path information, the RSNA MIRC Storage Service provides a link to the named document in the same directory on the Storage Service as the MIRCdocument. This technique is used when the MIRCdocument is only a means to index another kind of content. For example, when the actual content of interest is a presentation in PowerPoint format, it can be indexed by creating a short MIRCdocument containing the title, the authors, and an abstract. This MIRCdocument, called an "index card", is only useful during the user's search for the document, so the <b>docref</b> attribute is set to point to the presentation file itself, and the Storage Service stores the presentation file and the index file in the same directory.<br />
<br />
<pre><br />
<MIRCdocument docref="presentationfilename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with path information, the RSNA MIRC Storage Service provides a link to the named document. This technique is a more general example of the previous case. It is used when the actual document of interest is not stored in the same directory on the Storage Service as the MIRCdocument that indexes it. Since authors generally do not control the actual storage locations of their documents, this mechanism is infrequently used, and then only by MIRC administrators.<br />
<br />
This is an example of an index card referencing a presentation stored by a MIRC administrator in a common "presentations" directory under the "MIRCdocuments" directory of the server root:<br />
<br />
<pre><br />
<MIRCdocument docref="/MIRCdocuments/presentations/filename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with a fully qualified path, the RSNA MIRC Storage Service provides a link to the named document. This technique is a more general example of the previous case. It is used when the actual content of interest is a document not stored on the same Storage Service as the MIRCdocument that indexes it. This mechanism can be used to index the contents of a webserver on a MIRC Storage Service without storing the documents on the Storage Service itself. <br />
<br />
This is an example of an index card referencing a document stored somewhere on the web:<br />
<br />
<pre><br />
<MIRCdocument docref="http://www.somewhere.edu/filename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
=====Important Note for MIRC Site Implementers=====<br />
The description in the section above applies to MIRCdocuments stored on MIRC sites using the RSNA MIRC software. It is important not to confuse the flexibility in the use of the <b>docref</b> attribute described here with the inflexible requirement that a Storage Service provide a fully qualified URL for each document in its <b>MIRCqueryresult</b> reply to a Query Service.<br />
<br />
The <b>MIRCqueryresult</b> schema uses the <b>MIRCdocument</b> element to describe each document meeting the search criteria it received in a MIRCquery. A detailed description of the <b>MIRCqueryresult</b> schema is included in a [[The_MIRCquery_and_MIRCqueryresult_Schemas|separate article]]. Briefly, a <b>MIRCqueryresult</b> has the following form:<br />
<br />
<pre><br />
<MIRCqueryresult><br />
<MIRCdocument docref="http://www.somewhere.edu/filename"><br />
…title, author, abstract content…<br />
</MIRCdocument><br />
…additional <MIRCdocument> elements – one for each query match…<br />
</MIRCqueryresult><br />
</pre><br />
<br />
In the <b>MIRCqueryresult</b> schema, each <b>MIRCdocument</b> element is required to provide a fully qualified URL pointing to the document. On sites using the RSNA MIRC software, that URL is generated automatically by the Storage Service as described in the section above for documents with a missing <b>docref</b> attribute or with one that contains a less than fully qualified URL.<br />
<br />
====The <b>display</b> Attribute====<br />
The <b>MIRCdocument</b> element also supports the optional <b>display</b> attribute, which can be used to instruct the MIRC rendering software on how the author intended the document to be displayed. The RSNA MIRC rendering software supports three values of the <b>display</b> attribute:<br />
<br />
*<b>page</b> instructs the rendering software to display the document in a linear, sequential fashion as a normal document would appear. This is the default value.<br />
*<b>tab</b> instructs the rendering software to display the document with each section appearing as a separate tab.<br />
*<b>mstf</b> instructs the rendering software to display the document in a standardized teaching file format oriented toward residents. For compatibility with previous releases, <b>mirctf</b> is a synonym for <b>mstf</b>.<br />
<br />
====The <b>first-tab</b> Attribute====<br />
The <b>first-tab</b> attribute of the <b>MIRCdocument</b> element instructs the rendering software which tab to display first. This attribute is used in the tab and mstf display formats. It is ignored in the page display format. The default value of the first-tab attribute is 2.<br />
<br />
====The <b>show-empty-tabs</b> Attribute====<br />
The <b>show-empty-tabs</b> attribute of the <b>MIRCdocument</b> element instructs the rendering software whether to display sections that have no content. This attribute is used in the tab and mstf display formats. It is ignored in the page display format. The possible values are yes and no. The default value of the show-empty-tabs attribute is no.<br />
<br />
====The <b>background</b> Attribute====<br />
The <b>background</b> attribute of the <b>MIRCdocument</b> element defines the background color of the document when it is displayed. The possible values are <b>light</b> and <b>dark</b>. The default is <b>light</b>.<br />
<br />
====The <b>path</b> Attribute====<br />
The <b>path</b> attribute of the <b>MIRCdocument</b> element is dynamically generated by the RSNA MIRC software when a MIRCdocument is exported from a storage service. It is used to provide third-party, client-side authoring tools the relative path to the document on the server.<br />
<br />
====The <b>as-mode</b> Attribute====<br />
The <b>as-mode</b> attribute of the <b>MIRCdocument</b> element is automatically generated by the Author Service when an author edits the MIRCdocument. It defines whether technical elements are displayed in the editor. Its possible values are <b>true</b> and <b>false</b>.<br />
<br />
====The <b>visible</b> Attribute====<br />
The <b>visible</b> attribute of the <b>MIRCdocument</b> element is ignored by the RSNA MIRC software.<br />
<br />
==Document Structure Elements==<br />
Certain first-generation child elements of the <b>MIRCdocument</b> element are used to provide structure for a document, encapsulating titles, authors, abstracts, keywords, and the various content sections of the document. They are used both to encode key information to be matched against search criteria and to organize the entire document for display.<br />
<br />
The RSNA MIRC software only displays MIRCdocument content which appears within one of these elements. Information included for indexing purposes only can be placed as text value or child elements of the <b>MIRCdocument</b> element or in a <b>section</b> element with the <b>visible</b> attribute set to <b>no</b>.<br />
===<b>title</b>===<br />
The <b>title</b> element contains the title of the document. The <b>title</b> element and the <b>alternative-title</b> element determine the title displayed when the document is rendered or when it appears in a list of search results. See the next section, <b>alternative-title</b>, for details.<br />
HTML should not be embedded in the <b>title</b> element.<br />
<br />
<pre><br />
<MIRCdocument><br />
<title>This is the Title</title><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>title</b> element.<br />
===<b>alternative-title</b>===<br />
The optional <b>alternative-title</b> element provides a title which is used when the document is requested to be displayed as an unknown case. <br />
<br />
HTML should not be embedded in the <b>alternative-title</b> element.<br />
<br />
The RSNA MIRC software ignores the the <b>visible</b> attribute of the <alternative-title> element.<br />
<br />
When the Storage Service receives a query requesting the results as unknowns, it substitutes the contents of the <b>alternative-title</b> element for the <b>title</b> element when constructing the list of query results. If the <b>alternative-title</b> element is missing, the Storage Service generates a title as described in the section on the <b>category</b> element.<br />
<br />
The Storage Service similarly substitutes the contents of the <b>alternative-title</b> element when it is requested to display the document as an unknown.<br />
<br />
===<b>author</b>===<br />
The optional <b>author</b> element contains information for a single author. When a document has multiple authors, multiple <b>author</b> elements are used.<br />
<br />
Within the <b>author</b> element are three optional child elements containing the author's name, affiliation, and contact information.<br />
<br />
HTML should not be embedded in the <b>author</b> element or its children.<br />
<br />
<pre><br />
<MIRCdocument><br />
<title>This is the Title</title><br />
<author><br />
<name>John Author</name><br />
<affiliation>Organization of John Author</affiliation><br />
<contact>Email address of John Author</contact><br />
<contact>Post address of John Author – line 1</contact><br />
<contact>Post address of John Author – line 2</contact><br />
</author><br />
<author><br />
<name>Mary Author</name><br />
<affiliation>Organization of Mary Author</affiliation><br />
<contact>Email address of Mary Author</contact><br />
</author><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the visible attribute of the <b>author</b> element and its children.<br />
<br />
====<b>name</b>====<br />
The <b>name</b> element contains the author's name. No provision is made for identifying the given name, surname, or titles. The value of each <b>name</b> element appears in the search result list.<br />
<br />
====<b>affiliation</b>====<br />
The <b>affiliation</b> element contains one line of the name of an organization with which the author is affiliated. If multiple lines are required, or if the author is affiliated with multiple organizations, multiple <b>affiliation</b> elements are used. No provision is made for separating multiple organizations.<br />
====<b>contact</b>====<br />
The <b>contact</b> element contains one line of information on how to contact the author. If multiple lines are required, multiple <b>contact</b> elements are used. No provision is made for identifying the kind of contact information (phone, email, post, etc.) contained in the element.<br />
===<b>abstract</b>===<br />
The <b>abstract</b> element contains the abstract of the document. The <b>abstract</b> element and the <b>alternative-abstract</b> element determine the abstract displayed when the document is rendered or when it appears in a list of search results. See the next section, <b>alternative-abstract</b>, for details.<br />
<br />
HTML may be used for formatting; in particular, HTML paragraph elements must be used to identify the paragraphs.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<abstract><br />
<p><br />
First <b>paragraph</b> of the abstract.<br />
</p><br />
<p><br />
Second <b>paragraph</b> of the abstract.<br />
</p><br />
</abstract><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b><abstract</b> element.<br />
<br />
===<b>alternative-abstract</b>===<br />
The <b>alternative-abstract</b> element provides an alternative abstract which is used when the document is requested to be displayed as an unknown case.<br />
<br />
HTML may be used for formatting as in the <b>abstract</b> element.<br />
<br />
The RSNA MIRC software ignores the <b>visible</b> attribute of the <b>alternative-abstract</b> element.<br />
<br />
When the Storage Service receives a query requesting the results as unknowns, it substitutes the contents of the <b>alternative-abstract</b> element for the <b>abstract</b> element when constructing the list of query results. If the <b>alternative-abstract</b> element is missing, the Storage Service generates no <b>abstract</b> element.<br />
<br />
For MIRCdocuments with the <b>display</b> attribute set to <b>page</b>, the Storage Service similarly substitutes the contents of the <b>alternative-abstract</b> element when it is requested to display the document as an unknown. (The <b>abstract</b> element is used in MIRCdocuments with the <b>display</b> attribute set to <b>tab</b> or <b>mstf</b>. In these documents, the abstract is included in the first tab and the first tab displayed is typically the second tab, thus concealing the content of the abstract until the user wants to see it.)<br />
<br />
===<b>keywords</b>===<br />
The optional <b>keywords</b> element contains a list of words under which the document should be indexed. Although all words in a document are indexed, the <b>keywords</b> element makes it also possible to query for only those words explicitly identified as keywords.<br />
<br />
HTML should not be embedded in the <b>keywords</b> element.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<keywords>word1 word2 word3</keywords><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>keywords</b> element.<br />
===<b>section</b>===<br />
The optional <b>section</b> element is used to identify separate parts of a MIRCdocument. It contains one attribute, <b>heading</b>, that is used to contain the heading applied to the section when the MIRCdocument is rendered by a browser. The value of the <b>section</b> element is the content of the section. HTML may be used for formatting; in particular, HTML paragraph elements should generally be used to identify paragraphs. (The rendering software can display content not contained in paragraphs, and certain third-party authoring software sometimes creates documents in this way, but the Author Service is more strict than the display software, so it is necessary to use HTML paragraphs if the Author Service is to be used to edit the document.)<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<section heading="Method"><br />
…Method section contents…<br />
</section><br />
<section heading="Results"><br />
…Results section contents…<br />
</section><br />
…more content…<br />
</MIRCdocument><br />
</pre><br />
<br />
MIRCdocuments used as index cards generally do not have <b>section</b> elements since index cards are only displayed as query results. For all other applications of the MIRCdocument schema, however, the <b>section</b> element provides the way for the author to group related parts of the document together. This grouping instructs the RSNA MIRC software on how to handle the parts of the document when it is displayed. For example, in <b>tab</b> display mode, the RSNA MIRC software creates a separate tab for each <b>section</b>, using the <b>heading</b> attribute as the title of the tab.<br />
<br />
===<b>image-section</b>===<br />
The optional <b>image-section</b> element is used to collect groups of related images. The <b>image-section</b> element supports the <b>heading</b> attribute in the <b>page</b> and <b>tab</b> display modes. The <b>heading</b> attribute provides a label for the section containing the images.<br />
<br />
The <b>image-section</b> element supports the <b>image-pane-width</b> attribute, which instructs the RSNA display software how much space to allocate for image display in the right pane in the <b>tab</b> and <b>mstf</b> display modes. The default value of the <b>image-pane-width</b> attribute is 700. The RSNA MIRC software enforces a minimum width of 512.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>image-section</b> element.<br />
<br />
===<b>references</b>===<br />
The optional <b>references</b> element encapsulates a set of <b>reference</b> elements in the MIRCdocument. The RSNA MIRC software generates a separate section entitled "References" when the MIRCdocument is displayed. The software automatically generates an ordered list of the <b>reference</b> child elements.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<references><br />
<reference><br />
…text of the first reference…<br />
</reference><br />
<reference><br />
…text of the second reference…<br />
</reference><br />
…additional references…<br />
</references><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>references</b> element.<br />
====<b>reference</b>====<br />
The <b>reference</b> element is a simple container identifying the enclosed content as a reference to a publication. It has no internal formatting, although this is an area open to extension. Numbering of the <b>reference</b> elements is generated automatically by the <b>references</b> element when the MIRCdocument is rendered. HTML may be embedded in the <b>reference</b> element.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>reference</b> element.<br />
<br />
===<b>rights</b> and <b>publication-date</b>===<br />
If the <b>rights</b> element and/or the <b>publication-date</b> element appear as direct children of the <b>MIRCdocument</b> element, the RSNA MIRC software displays their values at the end of the document. If they appear within a <b>section</b> element, they are displayed as part of the section.<br />
<br />
See the section below for information about the elements and their contents.<br />
<br />
==Special Purpose Elements==<br />
The schema includes many element which identify specific kinds of information. The RSNA MIRC software renders these elements only when they appear within a <b>section</b> element. Each element may appear multiple times in a <b>section</b> element. These elements can also be used to encode non-displayed information for indexing purposes by placing the elements as direct child elements of the <b>MIRCdocument</b> element.<br />
===<b>history</b>===<br />
The optional <b>history</b> element allows content to be identified as a patient history for use in specialized searches.<br />
===<b>findings</b>===<br />
The optional <b>findings</b> element allows content to be identified as the patient's history for use in specialized searches.<br />
===<b>diagnosis</b>===<br />
The optional <b>diagnosis</b> element allows content to be identified as a diagnosis for use in specialized searches. <br />
<br />
The text value of the <b>diagnosis</b> element contains the diagnosis. It may also contain one or more <b>code</b> elements to capture diagnostic coding information. In addition, it may contain a <b>confirmation</b> element to describe how the diagnosis was confirmed.<br />
<pre><br />
<diagnosis><br />
At <confirmation>autopsy</confirmation>, the patient<br />
was determined to have … .<br />
<code coding-system="coding system name">12345.67890</code><br />
</diagnosis><br />
</pre><br />
====<b>confirmation</b>====<br />
The <b>confirmation</b> element describes how a diagnosis was confirmed.<br />
<br />
===<b>differential-diagnosis</b>===<br />
The optional <b>differential-diagnosis</b> element allows all or part of a part of a section to be identified as the differential diagnosis of the current case for use in specialized searches.<br />
===<b>discussion</b>===<br />
The optional <b>discussion</b> element allows all or part of a part of a section to be identified as case discussion for use in specialized searches.<br />
===<b>pathology</b>===<br />
The optional <b>pathology</b> element allows all or part of a part of a section to be identified as pathology relating to the case for use in specialized searches.<br />
===<b>anatomy</b>===<br />
The optional <b>anatomy</b> element allows all or part of a part of a section to be identified as anatomy relating to the case for use in specialized searches.<br />
===<b>organ-system</b>===<br />
The optional <b>organ-system</b> element allows all or part of a part of a section to be identified as anatomy relating to the case for use in specialized searches.<br />
===<b>a</b>===<br />
The <b>a</b> element inserts a hyperlink into a MIRCdocument. The <b>a</b> element is taken directly from HTML, with the addition of the format attribute:<br />
*<b>href</b> contains the address of the document to which the value text is linked.<br />
*<b>format</b> contains a description of the format of the document to be found at <b>href</b>.<br />
<br />
The value text contains the link text that is rendered in the MIRCdocument.<br />
<br />
The <b>format</b> attribute is optional and is not displayed in the MIRCdocument.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>a</b> element and applies instead the <b>visible</b> attribute of its parent.<br />
<br />
Note:<br />
In version 8.0 of the schema, the <b>link</b> element was used as a synonym of the <b>a</b> element, but only the <b>link</b> element had the <b>format</b> attribute. To eliminate any confusion with the HTML <b>link</b> element, subsequent versions deprecate the <b>link</b> element and add the <b>format</b> attribute to the <b>a</b> element. <br />
<br />
===<b>code</b>===<br />
The <b>code</b> element contains information related to a medical code. It has one attribute and value text:<br />
*<b>coding-system</b> contains the name of the code, e.g., CPT.<br />
*the value text contains the code value itself.<br />
The <b>code</b> element can optionally contain a <b>meaning</b> element. <br />
<br />
When rendered by the RSNA MIRC software, the <b>code</b> element is displayed as: <br />
<br />
<center><br />
[<b>coding-system</b> attribute value]:[<b>code</b> element value] ([<b>meaning</b> element value])<br />
</center><br />
<br />
For example, the following element:<br />
<br />
<pre><br />
<code coding-system="MyCode" visible="yes"><br />
12345.67890<br />
</code><br />
</pre><br />
is displayed by the RSNA MIRC software as: MyCode:12345.67890<br />
====<b>meaning</b>====<br />
The <b>meaning</b> element is used to encapsulate the human language meaning of the code value.<br />
For example, the following element:<br />
<pre><br />
<code coding-system="MyCode" visible="yes"><br />
12345.67890<br />
<meaning visible="yes"><br />
normal variant<br />
</meaning><br />
</code><br />
</pre><br />
is displayed by the RSNA MIRC software as: <br />
MyCode:12345.67890 (normal variant)<br />
<br />
===<b>modality</b>===<br />
The optional <b>modality</b> element contains a list of the modalities related to the document. If contained within an <b>image</b> element, it identifies the modality of the image.<br />
<br />
===<b>patient</b>===<br />
The <b>patient</b> element is used to encapsulate elements describing specific parameters of a patient. <br />
<br />
The subsections below describe the child elements unique to the <b>patient</b> element. Here is an example using some of the child elements:<br />
<br />
<pre><br />
<patient><br />
<pt-name>John Doe</pt-name><br />
<pt-id>7654321</pt-id><br />
<pt-mrn>1234567</pt-id><br />
<pt-age><br />
<years>3</years><br />
</pt-age><br />
<pt-sex>male</pt-sex><br />
<pt-race>caucasian</pt-race><br />
</patient><br />
</pre><br />
====<b>pt-name</b>====<br />
The <b>pt-name</b> element may be used to identify a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-id</b>====<br />
The <b>pt-id</b> element may also be used to identify a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-mrn</b>====<br />
The <b>pt-mrn</b> element may be used to identify the medical record number of a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-age</b>====<br />
The <b>pt-age</b> element encapsulates one or more of the following child elements: <br />
*<b>years</b><br />
*<b>months</b><br />
*<b>weeks</b><br />
*<b>days</b><br />
=====<b>years</b>=====<br />
The <b>years</b> element contains the patient age if expressed in years.<br />
=====<b>months</b>=====<br />
The <b>months</b> element contains the patient age if expressed in months.<br />
=====<b>weeks</b>=====<br />
The <b>weeks</b> element contains the patient age if expressed in weeks.<br />
=====<b>days</b>=====<br />
The <b>days</b> element contains the patient age if expressed in days.<br />
====<b>pt-sex</b>====<br />
The <b>pt-sex</b> element contains one of the values male or female (or neutered in veterinary medicine applications).<br />
====<b>pt-race</b>====<br />
The <b>pt-race</b> element contains the name of the race of the patient.<br />
====<b>pt-species</b>====<br />
<b>pt-species</b> element contains the name of the species of the patient. This element is intended for use in veterinary medicine and paleontology.<br />
====<b>pt-breed</b>====<br />
The <b>pt-breed</b> element contains the name of the breed of the patient. This element is intended for use in veterinary medicine.<br />
<br />
===<b>image</b>===<br />
The <b>image</b> element is used to encapsulate an image and related information<br />
Its <b>src</b> attribute contains the URL of the image to be displayed.<br />
<br />
The <b>image</b> element also has the <b>width</b> and <b>height</b> attributes of the HTML <b>img</b> element. These are passed to the browser to set the displayed width and height of the image; they do not refer to the actual size of the image in the file on the server.<br />
<br />
The value of an <b>image</b> element may be empty or it one or more <b>alternative-image</b> elements, and optionally <b>patient</b>, <b>diagnosis</b>, <b>anatomy</b>, <b>pathology</b>, and <b>code</b> elements to associate the parameters of the patient and/or the diagnosis with the image. It may also contain the <b>modality</b>, <b>format</b> and <b>compression</b> elements to encode parameters of the image itself.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>image</b> element and applies instead the <b>visible</b> attribute of its parent.<br />
<br />
The following example shows the use of an <b>image</b> element to include a JPEG image directly in the rendered document.<br />
<pre><br />
<image src="http://www.abc.edu/images/image1.jpeg"><br />
<format>jpeg</format><br />
</image><br />
</pre><br />
The image appears in sequence with the rest of the text value of the element in which the <b>image</b> element is contained.<br />
<br />
The following more complex coding of the previous example shows the use of multiple child elements within an <b>image</b> element.<br />
<pre><br />
<a href="http://www.abc.edu/images/image1.dcm"><br />
<image src="http://www.abc.edu/images/image1.jpeg"><br />
<format visible=”no”>DICOM</format><br />
<compression visible=”no”>original</compression><br />
<modality visible=”no”>CT</modality><br />
<anatomy visible=”no”>abdomen</anatomy><br />
<pathology visible=”no”>renal carcinoma</pathology><br />
<patient visible=”no”><br />
<pt-age><br />
<years>86</years><br />
</pt-age><br />
<pt-sex>male</pt-sex><br />
</patient><br />
<diagnosis visible=”no”><br />
renal carcinoma<br />
<confirmation>pathology</confirmation><br />
<code coding-system="ABC Code">1234.5678</code><br />
</diagnosis><br />
</image><br />
</a><br />
</pre><br />
The RSNA MIRC implementation often groups related images together within an <b>image</b> element which appears in an <b>image-section</b>. Such groups are sometimes called "megasave groups". The following example shows a megasave group for an image.<br />
<pre><br />
<image src="IMG_1719.jpg" width="374"><br />
<alternative-image role="icon" src="IMG_1719_icon"/><br />
<alternative-image role="annotation" src="IMG_1719_an.svg" type="svg"/><br />
<alternative-image role="annotation" src="IMG_1719_an.jpg" type="image"/><br />
<alternative-image role="original-dimensions" src="IMG_1719_orig.jpg"/><br />
<alternative-image role="original-format" src="IMG_1719.dcm"/><br />
</image><br />
</pre><br />
In this group, the <b>alternative-image</b> children are different versions of the original image (in this case, <b>IMG_1719.dcm</b>) for various purposes. As in the preceding example, other child elements could have been included to provide additional information about the group.<br />
====<b>format</b>====<br />
The <b>format</b> element is used to identify the storage format of an image.<br />
The <b>format</b> element has the enumerated values:<br />
*<b>DICOM</b><br />
*<b>JPEG</b><br />
*<b>PNG</b><br />
*<b>GIF</b><br />
*<b>TIFF</b><br />
====<b>compression</b>====<br />
The <b>compression</b> element is used to identify the compression history of an image.<br />
The <b>compression</b> element has four enumerated values:<br />
*<b>original</b><br />
*<b>reversible</b><br />
*<b>non-reversible</b><br />
*<b>unknown</b><br />
A value at any level in the list above implies that the compression history of the image does not include a version at a lower level. Thus, a value of <b>reversible</b> implies that the image in question is not simply a reversibly compressed version of an image that was non-reversibly compressed.<br />
====<b>alternative-image</b>====<br />
The <b>alternative-image</b> element identifies a version of the parent <b>image</b> element intended to be used for a specific purpose. The <b>alternative-image</b> element has two required attributes.<br />
*<b>src</b> contains the URL of the <b>alternative-image</b>.<br />
*<b>role</b> identifies the purpose of the <b>alternative-image</b>. <br />
The <b>role</b> attribute has four enumerated values:<br />
*<b>icon</b> identifies the <b>alternative-image</b> as a small image intended for use as an icon link to the parent image.<br />
*<b>annotation</b> identifies the <b>alternative-image</b> as annotations for the parent image.<br />
*<b>original-dimensions</b> identifies the <b>alternative-image</b> as a version of the parent image having the same dimensions as the original-format image.<br />
*<b>original-format</b> identifies the <b>alternative-image</b> as the original image acquired by the modality (except for changes required for anonymization).<br />
The <b>alternative-image</b> element with <b>role=”annotation”</b> has one additional attribute, <b>type</b>, that describes the format of the annotation data. The type attribute has two enumerated values:<br />
*<b>image</b> (the default) identifies the annotation data as an image that is to replace the primary image when annotations are displayed.<br />
*<b>svg</b> identifies the annotation data as scalar vector graphics instructions for displaying the annotations overlaid on the primary image when annotations are to be displayed.<br />
The <b>alternative-image</b> element may optionally contain the <b>width</b> and <b>height</b> attributes of the HTML <b>img</b> element. <br />
The <b>alternative-image</b> element is always a child of a <b>image</b> element, and its <b>visible</b> attribute and those of all its children are ignored. <br />
The <b>alternative-image</b> element may also contain <b>format</b> and <b>compression</b> child elements.<br />
<br />
===<b>quiz</b>===<br />
The <b>quiz</b> element is used to contain a quiz that is displayed within a <b>section</b> element in the MIRCdocument. Multiple <b>quiz</b> elements may appear within one <b>section</b> element. Multiple <b>section</b> elements may contain <b>quiz</b> elements.<br />
A quiz has the following structure:<br />
<br />
<pre><br />
<quiz id="…"><br />
<quiz-context><br />
…content defining the context of the quiz…<br />
</quiz-context><br />
<question><br />
<question-body><br />
…content defining the question…<br />
</question-body><br />
<answer correct="yes|no"><br />
<answer-body><br />
…content shown to the user as a possible selection…<br />
</answer-body><br />
<response><br />
…content shown to the user if the answer is selected…<br />
</response><br />
</answer><br />
…additional <answer> elements…<br />
</question><br />
…additional <question> elements…<br />
</quiz><br />
</pre><br />
The <b>quiz</b> element has an <b>id</b> attribute that is intended to allow a CME interface to distinguish all the quizzes in a document. The value of the <b>id</b> attribute should be unique within the <b>MIRCdocument</b>.<br />
<br />
HTML and MIRC elements are permitted in all the child elements. Numbering of the questions and answers is generated automatically by the display software.<br />
<br />
Within a single <b>quiz</b> element, there is no limit to the number of <b>question</b> elements.<br />
<br />
The RSNA MIRC software ignores the <b>visible</b> attribute of the <b>quiz</b> element and all its children.<br />
====<b>quiz-context</b>====<br />
The optional <b>quiz-context</b> element contains any description required to provide a context for the questions to follow. <br />
====<b>question</b>====<br />
The <b>question</b> element contains the body of a quiz question and its possible answers. <br />
Within a single <b>question</b> element, there is no limit to the number of <b>answer</b> elements.<br />
=====<b>question-body</b>=====<br />
The <b>question-body</b> element contains the content of a quiz question. <br />
=====<b>answer</b>=====<br />
The <b>answer</b> element contains the body of an answer to a quiz question and the response which will be provided if the user selects the answer.<br />
<br />
The <b>answer</b> element may contain a <b>correct</b> attribute indicating whether the answer is correct (<b>yes</b>) or not (<b>no</b>). At least one answer to a question must be identified as being correct. Multiple answers to a single question may be identified as being correct. The default value of the <b>correct</b> attribute is <b>no</b>.<br />
======<b>answer-body</b>======<br />
The <b>answer-body</b> element contains the body of an answer to a quiz question. <br />
======<b>response</b>======<br />
The optional <b>response</b> element contains the response which the browser will display if the user selects the answer.<br />
<br />
===<b>show</b>===<br />
The <b>show</b> element is a special purpose display command for documents in the <b>mstf</b> display mode. It is used within paragraphs in <b>section</b> elements to generate a button that allows the user to display a specific image. The <b>show</b> element has two possible attributes, only one of which may be present in any specific element:<br />
*<b>image=”n”</b> causes the button to display the image corresponding to the <b>src</b> attribute of the n-th <b>image</b> element in the <b>image-section</b>.<br />
*<b>annotation=”n”</b> causes the button to display the image corresponding to the <b>src</b> attribute of the <alternative-image role=”annotation”> child element of the n-th <b>image</b> element in the <b>image-section</b>.<br />
<br />
The <b>show</b> element is ignored in the <b>page</b> and <b>tab</b> display modes.<br />
<br />
The <b>show</b> element contains no text or element children. The proper usage is:<br />
<pre><show image="3"/></pre><br />
or <br />
<pre><show annotation="2"/></pre><br />
<br />
===<b>text</b>===<br />
The <b>text</b> element is an encapsulating element whose contents are rendered as if they were part of the element’s parent element. Its function has been overtaken by the development of the T25 version of the Author Service, but it remains in the schema for backward compatibility.<br />
<br />
===<b>text-caption</b>===<br />
The <b>text-caption</b> element is used to embed a centered caption between groups of content in a <b>section</b> element. The <b>text-caption</b> element has several optional attributes:<br />
*<b>display</b> can have the values <b>always</b> and <b>normal</b>. The default is <b>normal</b>.<br />
*<b>jump-buttons</b> can have the values <b>yes</b> and <b>no</b>. The default is <b>no</b>.<br />
*<b>show-button</b> can have the values <b>yes</b> and <b>no</b>. The default is <b>no</b>.<br />
The rendering of the <b>text-caption</b> element depends on its contents and on the values of the <b>display</b>, <b>jump-buttons</b> and <b>show-button</b> attributes:<br />
*If the <b>text-caption</b> element contains only whitespace text, the entire element is ignored when the MIRCdocument is rendered unless the <b>display</b> attribute is present with the value <b>always</b>, in which case the element is rendered, essentially providing an HTML break in the flow. <br />
*If the <b>text-caption</b> element contains any non-whitespace text, the text contents are displayed. <br />
*If the <b>jump-buttons</b> attribute has the value <b>yes</b>, the rendering software inserts two HTML buttons with the values “<<<” and “>>>”. The buttons allow the user to jump up or down to the previous or next <b>text-caption</b>. <br />
*If the the <b>show-button</b> attribute has the value <b>yes</b> and the text content of the caption is non-whitespace, then the text content of the caption is initially hidden when the document is rendered and an HTML button with the value “Show Caption” is inserted between the “<<<” and “>>>” buttons, allowing the user to reveal the caption after examining the content above it.<br />
Note: The RSNA MIRC software also supports the substitution of images for the buttons described above. The default is to use the button images distributed with the software. The buttons are contained in the storage service's <b>buttons</b> directory and are called:<br />
*back.png<br />
*showcaption.png<br />
*forward.png<br />
===<b>metadata-refs</b>===<br />
The RSNA MIRC implementation calls all files "metadata files". The <b>metadata-refs</b> element encapsulates a list of references to metadata files. The <b>metadata-refs</b> element may appear anywhere within a <b>section</b> element. It is rendered by the RSNA MIRC software as a table, with each of its <b>metadata</b> child elements being one row. The value of each <b>metadata</b> element's <b>href</b> attribute provides a link to the corresponding metadata file. The RSNA MIRC software ignores the visible attribute of the <b>metadata-refs</b> element and all its children.<br />
====<b>metadata</b>====<br />
The <b>metadata</b> element identifies a reference to a single data file. It has one required attribute, <b>href</b>, which provides the URL of the data file. There are three child elements.<br />
=====<b>type</b>=====<br />
The <b>type</b> element identifies the type of the metadata file. MIRC currently defines four classes:<br />
*<b>DicomObject</b>: a DICOM file (image, GSPS, KOS, or SR)<br />
*<b>XmlObject</b>: an XML file of any kind<br />
*<b>ZipObject</b>: a zip file with any contents<br />
*<b>FileObject</b>: any file not meeting the criteria above.<br />
<br />
=====<b>date</b>=====<br />
The <b>date</b> element identifies the date associated with the metadata file. The MIRCdocument generator attempts to get the date from the file, and if it fails, uses the last modified date of the file (typically the date the file was received).<br />
<br />
=====<b>desc</b>=====<br />
The <b>desc</b> element describes the metadata file. The MIRCdocument generator attempts to get the description from the file, and if it fails, inserts the file name.<br />
<br />
==Document Description Elements==<br />
Document description elements are used to describe a document at a high level. They typically appear as children of the <b>MIRCdocument</b> element and are therefore not displayed. However, they may also be placed within <b>section</b> elements if display is desired. With the exception of the <b>rights</b> element, HTML may not be used in these elements.<br />
===<b>phi</b>===<br />
The <b>phi</b> element identifies the protected health information (PHI) that is contained in the document. Absence of the element is interpreted to mean that the document contains no PHI. If the document contains PHI, the <b>phi</b> element contains one or more <b>study</b> child elements, each identifying one patient study referenced in the document. The contents of the PHI element and its children are not rendered by the RSNA MIRC implementation; they are used only to provide access logging information required by HIPAA.<br />
====<b>study</b>====<br />
The <b>study</b> element encapsulates the PHI for one patient study. If the document contains PHI for multiple studies, multiple <b>study</b> elements must be present.<br />
=====<b>si-uid</b>=====<br />
The <b>si-uid</b> element contains the Study Instance UID of the study whose images or patient identifying information are contained in the document.<br />
=====<b>pt-id</b>=====<br />
The <b>pt-id</b> element contains the identifier of the patient corresponding to the study.<br />
=====<b>pt-name</b>=====<br />
The <b>pt-name</b> element contains the name of the patient corresponding to the study.<br />
===<b>document-type</b>===<br />
The optional <b>document-type</b> element identifies the document as one of the following types:<br />
*<b>radiologic teaching file</b>: a teaching file, which may be a single case or a collection of cases in a single MIRCdocument<br />
*<b>radiologic collection</b>: a document containing references to multiple radiologic teaching files; a course; a conference<br />
*<b>research dataset</b>: a MIRCdocument describing and containing a link to a research dataset<br />
*<b>educational document</b>: an educational document, e.g. a presentation or course<br />
*<b>technical document</b>: a technical document<br />
Since the MIRCdocument schema permits the construction of complex documents combining characteristics of all the listed document types, multiple types may be listed within the element.<br />
<br />
===<b>category</b>===<br />
The optional <b>category</b> element identifies the document as belonging to one of the American Board of Radiology categories:<br />
*<b>Musculoskeletal</b><br />
*<b>Pulmonary</b><br />
*<b>Cardiovascular </b><br />
*<b>Gastrointestinal</b><br />
*<b>Genitourinary</b><br />
*<b>Neuro</b><br />
*<b>Vascular and Interventional</b><br />
*<b>Nuclear</b><br />
*<b>Ultrasound</b><br />
*<b>Pediatric</b><br />
*<b>Breast</b><br />
When searching for teaching file documents, a user may request that query results be displayed as unknowns. In this case, if the document does not contain an <b>alternative-title</b> element, the RSNA MIRC Storage Service generates a title in the form "Unknown - <b>category value</b>".<br />
<br />
===<b>level</b>===<br />
The optional <b>level</b> element indicates the degree of difficulty of the document. It is intended to allow teaching files to be graded for difficulty, allowing students to search for teaching files corresponding to their level. The level element contains one of:<br />
*<b>primary</b><br />
*<b>intermediate</b><br />
*<b>advanced</b><br />
===<b>lexicon</b>===<br />
The optional <b>lexicon</b> element identifies the name of the lexicon used in the document. <br />
===<b>access</b>===<br />
The optional <b>access</b> element indicates whether a document is accessible:<br />
*<b>public</b>: accessable by anyone<br />
*<b>restricted</b>: accessible only by certain authenticated users<br />
*<b>owner</b>: accessible only by the owner of the document<br />
This element is automatically generated by the RSNA MIRC site software from the contents of the <b>authorization</b> element.<br />
===<b>authorization</b>===<br />
The optional <b>authorization</b> element controls access to the document for various purposes.<br />
====<b>owner</b>====<br />
The optional <b>owner</b> element defines the owner of the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a comma or whitespace delimited list of usernames to be granted all privileges (read, update, export, delete).<br />
====<b>read</b>====<br />
The optional <b>read</b> element defines the individuals or groups who are authorized to view the the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to read the document. Individual users can be granted the read privilege by including their usernames in the list enclosed in square brackets as in this example:<br />
<pre><read>resident staff [drjones] [drjohnson] technologist</read></pre><br />
If the <b>read</b> element is missing, or if the value of the element contains “*”, all users are granted read access. <br />
====<b>update</b>====<br />
The optional <b>update</b> element defines the individuals or groups who are authorized to modify the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to access the document through the author service and store modifications back on the server. Individual users can be granted the update privilege by including their usernames in the list enclosed in square brackets as in the example above.<br />
<br />
If the <b>update</b> element is missing, updates are not authorized. If the value of the element contains “*”, all users are granted update privileges. <br />
====<b>export</b>====<br />
The optional <b>export</b> element defines the individuals or groups who are authorized to export the document from the server to their browser in the source format. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to export the standard MIRC zip file containing the document’s XML file and all its local references. Individual users can be granted the export privilege by including their usernames in the list enclosed in square brackets as in the example above.<br />
<br />
If the <b>export</b> element is missing, or if the value of the element contains “*”, all users are granted export privileges.<br />
<br />
===<b>peer-review</b>===<br />
The optional <b>peer-review</b> element contains information about the peer-review status of the document. If the <b>peer-review</b> element is missing, the document is assumed not to have been peer-reviewed. If the element is present, it must contain child elements identifying the reviewing authority and the status of the peer-review. If the <peer-review> element is displayed, all its children are displayed.<br />
====<b>approval-date</b>====<br />
The <b>approval-date</b> element represents the date on which the document was approved by the reviewing authority. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
====<b>expiration-date</b>====<br />
The optional <b>expiration-date</b> element represents the date on which the reviewing authority's approval of the document will expire. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
====<b>reviewing-authority</b>====<br />
The <b>reviewing-authority</b> element contains the name of the institution or organization responsible for providing the independent peer review before publication. <br />
====<b>reviewer</b>====<br />
The optional <b>reviewer</b> element contains the name of the reviewer.<br />
<br />
===<b>language</b>===<br />
The optional <b>language</b> element specifies the language in which the document is written.<br />
The <b>language</b> element has a required <b>code</b> attribute specifying the ISO 639:1988(E) two-letter code for the language, as defined as in http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt.<br />
<br />
The following code fragment:<br />
<pre><language code="en">English</language></pre><br />
generates the word "English".<br />
<br />
The RSNA MIRC software does not enforce the correspondence between the value of the <b>code</b> attribute and the value of the element. Query searches on language use the value of the <b>code</b> attribute, so the following fragment will possibly produce unexpected results:<br />
<pre><language code="en">French</language></pre><br />
<br />
===<b>creator</b>===<br />
The optional <b>creator</b> element identifies the application program that was used to create the document.<br />
===<b>document-id</b>===<br />
The optional <b>document-id</b> element is intended to provide a place to store a unique identifier for the document. This element is not yet implemented in the RSNA MIRC software.<br />
<br />
===<b>publication-date</b>===<br />
The optional <b>publication-date</b> element contains the date associated with the document, coded in accordance with ISO 8601 (e.g., yyyy-mm-dd). <br />
===<b>revision-history</b>===<br />
The optional <b>revision-history</b> element encapsulates a set of <b>revision</b> elements, one for each revision of the document. If the <b>revision-history</b> element is displayed, all its children are displayed.<br />
====<b>revision</b>====<br />
The optional <b>revision</b> element encapsulates a set of elements that define the author of the revision, the date, and a description of the revision. When present, it must contain the child elements <b>revision-author</b>, <b>revision-date</b>, and <b>revision-description</b>.<br />
=====<b>revision-author</b>=====<br />
The <b>revision-author</b> element contains the name of the person who authored or revised the document.<br />
=====<b>revision-date</b>=====<br />
The <b>revision-date</b> element contains the release date of the revision. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
=====<b>revision-description</b>=====<br />
The <b>revision-description</b> element contains a description of the changes made in the revision.<br />
<br />
===<b>rights</b>===<br />
The optional <b>rights</b> element can contain any text describing the rights held to the document. HTML may be used to format the presentation of the rights text.<br />
<br />
When the <b>rights</b> element is not contained within a <b>section</b> element, the RSNA MIRC software automatically displays the contents of the <b>rights</b> element at the end of a MIRCdocument. This is the only instance where a document description element is displayed when it is not contained within a document structure element.<br />
<br />
==Template Elements==<br />
The RSNA MIRC implementation uses XML files as templates for the automatic construction of MIRCdocuments by several of the services provided by a Storage Service. These are:<br />
*the Author Service<br />
*the DICOM Service<br />
*the TCE Service<br />
*the Zip Service<br />
Except in the case of the Author Service, the reception of a file by a service triggers either the construction of a new MIRCdocument or the modification of an existing one. Templates are MIRCdocument files, that is, they obey the MIRCdocument schema, extended to include elements that instruct the automatic document construction mechanism how to insert data from a file into the MIRCdocument. Except where noted below, template elements themselves are not displayed when a MIRCdocument is displayed.<br />
<br />
===<b>DICOM Elements</b>===<br />
DICOM elements in a template instruct the MIRCdocument generator to insert the values of DICOM dataset elements of a DICOM object into a MIRCdocument. DICOM elements are of the form <GxxxxEyyyy/>. DICOM elements have no child elements or text values. The group (G) and element (E) identifiers (xxxx and yyyy) are 4-place hexadecimal numbers. Upper case and lower case may be mixed anywhere within the element name. <br />
<br />
DICOM elements have an optional <b>desc</b> attribute which is typically used to indicate the human-readable name of the DICOM element it references. This attribute is not used by the MIRCdocument generator if the element references a DICOM element in the DICOM dictionary. For private elements in the dataset, however, it can provide a label for the data in a table. Generally it is recommended to supply the <b>desc</b> attribute, if only to make the template file more readable. The following are examples of DICOM elements:<br />
<pre><br />
<g0010e0010 desc="Patient Name"/><br />
<G0010E0011 desc="Patient ID"/><br />
<g0011e0030 desc="A Private Element"/><br />
</pre><br />
As a MIRCdocument is created from a template, DICOM elements are removed and replaced by data values from the DICOM object which occasioned the creation of the MIRCdocument in the first place. For this reason, DICOM elements can only be populated from the first DICOM object encountered for the document unless the elements are wrapped in a <b>block</b> element.<br />
===<b>block</b>===<br />
The <b>block</b> element is used to encapsulate template contents that are to be preserved for application to every object that is inserted into the MIRCdocument. The MIRCdocument generator processes the contents of the <b>block</b> element and inserts them immediately before the <b>block</b> element in the MIRCdocument. The <b>block</b> element itself is not rendered when the MIRCdocument is displayed.<br />
<br />
This is an example of a <b>block</b> element being used to create a table of SOP Instance UIDs for the objects inserted into a MIRCdocument in a clinical trial:<br />
<pre><br />
<section heading="SOP Instance UIDs"><br />
<p><br />
<table border="1"><br />
<tr><th>Image Number</th><th>SOP Instance UID</th></tr><br />
<block><br />
<tr><br />
<td><g0020e0013 desc="Instance Number"/></td><br />
<td><g0008e0018 desc="SOP Instance UID"/></td><br />
</tr><br />
</block><br />
</table><br />
</p><br />
</section><br />
</pre><br />
<br />
===<b>insert-image</b>===<br />
The <b>insert-image</b> element appears within a <b>section</b> element and instructs the MIRCdocument generator to insert a reference to an image. It supports the following attributes:<br />
*<b>width</b> specifies the maximum width of the JPEG image to be created. The default value is 700.<br />
*<b>min-width</b> specifies the minimum width of the JPEG image to be created. The default value is 0.<br />
*<b>extra-image-min-size</b> specifies the minimum width of an extra JPEG image to be created but not referenced by the MIRCdocument. If the attribute is not present, or if the image being inserted is not a DICOM image, no extra image is created. <br />
*<b>caption</b> specifies whether a <b>text-caption</b> element is to be generated after the image reference. The value of the <b>caption</b> attribute must be numeric.<br />
*<b>jump-buttons</b> indicates whether the <b>text-caption</b> element is to be generated with a <b>jump-buttons</b> attribute. The possible values of the next-button attribute are <b>yes</b> and <b>no</b>.<br />
*<b>show-button</b> indicates whether the <b>text-caption</b> element is to be generated with a <b>show-button</b> attribute. The possible values of the next-button attribute are <b>yes</b> and <b>no</b>.<br />
<br />
The <b>insert-image</b> element has no child elements or text value.<br />
<br />
===<b>insert-megasave</b>===<br />
The <b>insert-megasave</b> element appears within an <b>image-section</b> element and instructs the MIRCdocument generator to insert a reference to a megasave image group. It supports the following attributes:<br />
*<b>width</b> specifies the maximum width of the JPEG image to be created. The default value is 700.<br />
*<b>min-width</b> specifies the minimum width of the JPEG image to be created. The default value is 0.<br />
*<b>extra-image-min-size</b> specifies the minimum width of an extra JPEG image to be created but not referenced by the MIRCdocument. If the attribute is not present, or if the image being inserted is not a DICOM image, no extra image is created.<br />
<br />
The <b>insert-megasave</b> element has no child elements or text value.<br />
<br />
===<b>insert-dataset</b>===<br />
The <b>insert-dataset</b> element instructs the MIRCdocument generator to create a folder hierarchy within the MIRCdocument’s directory and store a copy of a DICOM image within it. The <b>insert-dataset</b> element appears as a first-generation child of the <b>MIRCdocument</b> element.<br />
<br />
The <b>insert-dataset</b> element supports the <b>phi</b> attribute, which specifies whether the stored DICOM instance is to contain protected healthcare information. The possible values of the phi attribute are <b>yes</b> and <b>no</b>:<br />
<br />
*<b>phi=”yes”</b> creates a folder named <b>phi</b>. Instances are stored unmodified in subdirectories named for the Series Description (if present), the Series Number (if present), or the Series Instance UID. <br />
<br />
*<b>phi=”no”</b> creates a folder named <b>no-phi</b>. Instances are first de-identified using the storage service’s anonymization rules and then stored in subdirectories named as described above.<br />
<br />
When MIRCdocuments containing <b>insert-dataset</b> elements are displayed, links are provided allowing for the export of a zip file containing the requested dataset.<br />
<br />
===<b>metadata-refs</b>===<br />
The <b>metadata-refs</b> element instructs the MIRCdocument generator to insert a <b>metadata</b> child element to identify a file referenced by the MIRCdocument. This element and its children are described in the [[#metadata-refs|Special Purpose Elements section]].</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=The_MIRCdocument_Schema&diff=2042The MIRCdocument Schema2006-08-12T01:34:46Z<p>209.242.55.28: /* Template Elements */</p>
<hr />
<div>==Introduction==<br />
This article describes the XML schema for indexable documents on sites using the RSNA MIRC software. It is intended for engineers implementing MIRC sites and authoring tools as well as for administrators and MIRCdocument authors who wish to exploit the full capabilities of their sites. The article assumes a basic understanding of XML. For more information on XML, see the [[XML_Primer|XML Primer]].<br />
<br />
The MIRCdocument schema includes all the MIRC-specific elements and attributes that can be included in a document on a MIRC site running the RSNA MIRC software. Where noted below, HTML elements may also be included as well.<br />
<br />
All elements in the schema include a <b>visible</b> attribute that allows the author to instruct a MIRC site's display software whether to render the contents of the element. Except where noted, the default value of the <b>visible</b> attribute is <b>yes</b>. The rendering behavior described inthis article is that provided by the RSNA MIRC software when MIRCdocuments are accessed by a browser (via an HTTP GET). In all cases, if a parent element's <b>visible</b> attribute is <b>no</b>, none of its children are rendered, and if a parent element's <b>visible</b> attribute is <b>yes</b>, only children whose <b>visible</b> attributes are <b>yes</b> are rendered.<br />
<br />
==The <b>MIRCdocument</b> Element==<br />
The <b>MIRCdocument</b> element is the root element of all MIRCdocuments. It encloses all the content of a MIRCdocument:<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
====The <b>docref</b> Attribute====<br />
When a user selects a MIRCdocument for display, the user's browser is directed either to the MIRCdocument itself or to another document. The optional <b>docref</b> attribute provides the link. To understand its use, it is helpful to understand the MIRC search mechanism. <br />
<br />
A user accesses a MIRC Query Service from a web browser. The Query Service provides an HTML form into which the user inserts the search criteria. Upon completion of the form, the browser posts it to the Query Service, which then constructs a query from the form data and posts it to the MIRC Storage Services identified in the form. The query is an XML object in a format defined by the <b>MIRCquery</b> schema. Each Storage Service searches its content for documents matching the search criteria, encodes the list of matching documents in an XML object in a format defined by the <b>MIRCqueryresult</b> schema, and sends the list to the Query Service. In the <b>MIRCqueryresult</b> schema, each document that matches the search criteria is identified by a URL. The Query Service compiles the results from all the Storage Services polled and sends the consolidated results to the user's browser. The consolidated results are constructed as an HTML ordered list, where each item in the list describes one document matching the search criteria and provides a link to the document iself. When the user selects an item in the list, the browser obtains the document identified by the link. In the RSNA MIRC implementation, the <b>docref</b> attribute is used to construct the URL that provides that link. <br />
<br />
Some MIRCdocuments contain a complete document, allowing them to be self-indexing. Other MIRCdocuments serve as indexable documents describing information in other formats. To accommodate these different kinds of MIRCdocuments on sites using the RSNA MIRC software, the docref attribute may be coded in several ways. <br />
*If the <b>docref</b> attribute is not included in the <b>MIRCdocument</b> element, the RSNA MIRC Storage Service provides a link to the file containing the MIRCdocument. This technique is used when the <b>MIRCdocument</b> element contains a complete document. For example, a teaching file case can be constructed as a MIRCdocument and indexed by a Storage Service. When a user selects the document from a list of search results, the link takes the user to the document itself. In this case, the <b>MIRCdocument</b> element is defined without a <b>docref</b> attribute:<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with no path information, the RSNA MIRC Storage Service provides a link to the named document in the same directory on the Storage Service as the MIRCdocument. This technique is used when the MIRCdocument is only a means to index another kind of content. For example, when the actual content of interest is a presentation in PowerPoint format, it can be indexed by creating a short MIRCdocument containing the title, the authors, and an abstract. This MIRCdocument, called an "index card", is only useful during the user's search for the document, so the <b>docref</b> attribute is set to point to the presentation file itself, and the Storage Service stores the presentation file and the index file in the same directory.<br />
<br />
<pre><br />
<MIRCdocument docref="presentationfilename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with path information, the RSNA MIRC Storage Service provides a link to the named document. This technique is a more general example of the previous case. It is used when the actual document of interest is not stored in the same directory on the Storage Service as the MIRCdocument that indexes it. Since authors generally do not control the actual storage locations of their documents, this mechanism is infrequently used, and then only by MIRC administrators.<br />
<br />
This is an example of an index card referencing a presentation stored by a MIRC administrator in a common "presentations" directory under the "MIRCdocuments" directory of the server root:<br />
<br />
<pre><br />
<MIRCdocument docref="/MIRCdocuments/presentations/filename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with a fully qualified path, the RSNA MIRC Storage Service provides a link to the named document. This technique is a more general example of the previous case. It is used when the actual content of interest is a document not stored on the same Storage Service as the MIRCdocument that indexes it. This mechanism can be used to index the contents of a webserver on a MIRC Storage Service without storing the documents on the Storage Service itself. <br />
<br />
This is an example of an index card referencing a document stored somewhere on the web:<br />
<br />
<pre><br />
<MIRCdocument docref="http://www.somewhere.edu/filename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
=====Important Note for MIRC Site Implementers=====<br />
The description in the section above applies to MIRCdocuments stored on MIRC sites using the RSNA MIRC software. It is important not to confuse the flexibility in the use of the <b>docref</b> attribute described here with the inflexible requirement that a Storage Service provide a fully qualified URL for each document in its <b>MIRCqueryresult</b> reply to a Query Service.<br />
<br />
The <b>MIRCqueryresult</b> schema uses the <b>MIRCdocument</b> element to describe each document meeting the search criteria it received in a MIRCquery. A detailed description of the <b>MIRCqueryresult</b> schema is included in a [[The_MIRCquery_and_MIRCqueryresult_Schemas|separate article]]. Briefly, a <b>MIRCqueryresult</b> has the following form:<br />
<br />
<pre><br />
<MIRCqueryresult><br />
<MIRCdocument docref="http://www.somewhere.edu/filename"><br />
…title, author, abstract content…<br />
</MIRCdocument><br />
…additional <MIRCdocument> elements – one for each query match…<br />
</MIRCqueryresult><br />
</pre><br />
<br />
In the <b>MIRCqueryresult</b> schema, each <b>MIRCdocument</b> element is required to provide a fully qualified URL pointing to the document. On sites using the RSNA MIRC software, that URL is generated automatically by the Storage Service as described in the section above for documents with a missing <b>docref</b> attribute or with one that contains a less than fully qualified URL.<br />
<br />
====The <b>display</b> Attribute====<br />
The <b>MIRCdocument</b> element also supports the optional <b>display</b> attribute, which can be used to instruct the MIRC rendering software on how the author intended the document to be displayed. The RSNA MIRC rendering software supports three values of the <b>display</b> attribute:<br />
<br />
*<b>page</b> instructs the rendering software to display the document in a linear, sequential fashion as a normal document would appear. This is the default value.<br />
*<b>tab</b> instructs the rendering software to display the document with each section appearing as a separate tab.<br />
*<b>mstf</b> instructs the rendering software to display the document in a standardized teaching file format oriented toward residents. For compatibility with previous releases, <b>mirctf</b> is a synonym for <b>mstf</b>.<br />
<br />
====The <b>first-tab</b> Attribute====<br />
The <b>first-tab</b> attribute of the <b>MIRCdocument</b> element instructs the rendering software which tab to display first. This attribute is used in the tab and mstf display formats. It is ignored in the page display format. The default value of the first-tab attribute is 2.<br />
<br />
====The <b>show-empty-tabs</b> Attribute====<br />
The <b>show-empty-tabs</b> attribute of the <b>MIRCdocument</b> element instructs the rendering software whether to display sections that have no content. This attribute is used in the tab and mstf display formats. It is ignored in the page display format. The possible values are yes and no. The default value of the show-empty-tabs attribute is no.<br />
<br />
====The <b>background</b> Attribute====<br />
The <b>background</b> attribute of the <b>MIRCdocument</b> element defines the background color of the document when it is displayed. The possible values are <b>light</b> and <b>dark</b>. The default is <b>light</b>.<br />
<br />
====The <b>path</b> Attribute====<br />
The <b>path</b> attribute of the <b>MIRCdocument</b> element is dynamically generated by the RSNA MIRC software when a MIRCdocument is exported from a storage service. It is used to provide third-party, client-side authoring tools the relative path to the document on the server.<br />
<br />
====The <b>as-mode</b> Attribute====<br />
The <b>as-mode</b> attribute of the <b>MIRCdocument</b> element is automatically generated by the Author Service when an author edits the MIRCdocument. It defines whether technical elements are displayed in the editor. Its possible values are <b>true</b> and <b>false</b>.<br />
<br />
====The <b>visible</b> Attribute====<br />
The <b>visible</b> attribute of the <b>MIRCdocument</b> element is ignored by the RSNA MIRC software.<br />
<br />
==Document Structure Elements==<br />
Certain first-generation child elements of the <b>MIRCdocument</b> element are used to provide structure for a document, encapsulating titles, authors, abstracts, keywords, and the various content sections of the document. They are used both to encode key information to be matched against search criteria and to organize the entire document for display.<br />
<br />
The RSNA MIRC software only displays MIRCdocument content which appears within one of these elements. Information included for indexing purposes only can be placed as text value or child elements of the <b>MIRCdocument</b> element or in a <b>section</b> element with the <b>visible</b> attribute set to <b>no</b>.<br />
===<b>title</b>===<br />
The <b>title</b> element contains the title of the document. The <b>title</b> element and the <b>alternative-title</b> element determine the title displayed when the document is rendered or when it appears in a list of search results. See the next section, <b>alternative-title</b>, for details.<br />
HTML should not be embedded in the <b>title</b> element.<br />
<br />
<pre><br />
<MIRCdocument><br />
<title>This is the Title</title><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>title</b> element.<br />
===<b>alternative-title</b>===<br />
The optional <b>alternative-title</b> element provides a title which is used when the document is requested to be displayed as an unknown case. <br />
<br />
HTML should not be embedded in the <b>alternative-title</b> element.<br />
<br />
The RSNA MIRC software ignores the the <b>visible</b> attribute of the <alternative-title> element.<br />
<br />
When the Storage Service receives a query requesting the results as unknowns, it substitutes the contents of the <b>alternative-title</b> element for the <b>title</b> element when constructing the list of query results. If the <b>alternative-title</b> element is missing, the Storage Service generates a title as described in the section on the <b>category</b> element.<br />
<br />
The Storage Service similarly substitutes the contents of the <b>alternative-title</b> element when it is requested to display the document as an unknown.<br />
<br />
===<b>author</b>===<br />
The optional <b>author</b> element contains information for a single author. When a document has multiple authors, multiple <b>author</b> elements are used.<br />
<br />
Within the <b>author</b> element are three optional child elements containing the author's name, affiliation, and contact information.<br />
<br />
HTML should not be embedded in the <b>author</b> element or its children.<br />
<br />
<pre><br />
<MIRCdocument><br />
<title>This is the Title</title><br />
<author><br />
<name>John Author</name><br />
<affiliation>Organization of John Author</affiliation><br />
<contact>Email address of John Author</contact><br />
<contact>Post address of John Author – line 1</contact><br />
<contact>Post address of John Author – line 2</contact><br />
</author><br />
<author><br />
<name>Mary Author</name><br />
<affiliation>Organization of Mary Author</affiliation><br />
<contact>Email address of Mary Author</contact><br />
</author><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the visible attribute of the <b>author</b> element and its children.<br />
<br />
====<b>name</b>====<br />
The <b>name</b> element contains the author's name. No provision is made for identifying the given name, surname, or titles. The value of each <b>name</b> element appears in the search result list.<br />
<br />
====<b>affiliation</b>====<br />
The <b>affiliation</b> element contains one line of the name of an organization with which the author is affiliated. If multiple lines are required, or if the author is affiliated with multiple organizations, multiple <b>affiliation</b> elements are used. No provision is made for separating multiple organizations.<br />
====<b>contact</b>====<br />
The <b>contact</b> element contains one line of information on how to contact the author. If multiple lines are required, multiple <b>contact</b> elements are used. No provision is made for identifying the kind of contact information (phone, email, post, etc.) contained in the element.<br />
===<b>abstract</b>===<br />
The <b>abstract</b> element contains the abstract of the document. The <b>abstract</b> element and the <b>alternative-abstract</b> element determine the abstract displayed when the document is rendered or when it appears in a list of search results. See the next section, <b>alternative-abstract</b>, for details.<br />
<br />
HTML may be used for formatting; in particular, HTML paragraph elements must be used to identify the paragraphs.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<abstract><br />
<p><br />
First <b>paragraph</b> of the abstract.<br />
</p><br />
<p><br />
Second <b>paragraph</b> of the abstract.<br />
</p><br />
</abstract><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b><abstract</b> element.<br />
<br />
===<b>alternative-abstract</b>===<br />
The <b>alternative-abstract</b> element provides an alternative abstract which is used when the document is requested to be displayed as an unknown case.<br />
<br />
HTML may be used for formatting as in the <b>abstract</b> element.<br />
<br />
The RSNA MIRC software ignores the <b>visible</b> attribute of the <b>alternative-abstract</b> element.<br />
<br />
When the Storage Service receives a query requesting the results as unknowns, it substitutes the contents of the <b>alternative-abstract</b> element for the <b>abstract</b> element when constructing the list of query results. If the <b>alternative-abstract</b> element is missing, the Storage Service generates no <b>abstract</b> element.<br />
<br />
For MIRCdocuments with the <b>display</b> attribute set to <b>page</b>, the Storage Service similarly substitutes the contents of the <b>alternative-abstract</b> element when it is requested to display the document as an unknown. (The <b>abstract</b> element is used in MIRCdocuments with the <b>display</b> attribute set to <b>tab</b> or <b>mstf</b>. In these documents, the abstract is included in the first tab and the first tab displayed is typically the second tab, thus concealing the content of the abstract until the user wants to see it.)<br />
<br />
===<b>keywords</b>===<br />
The optional <b>keywords</b> element contains a list of words under which the document should be indexed. Although all words in a document are indexed, the <b>keywords</b> element makes it also possible to query for only those words explicitly identified as keywords.<br />
<br />
HTML should not be embedded in the <b>keywords</b> element.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<keywords>word1 word2 word3</keywords><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>keywords</b> element.<br />
===<b>section</b>===<br />
The optional <b>section</b> element is used to identify separate parts of a MIRCdocument. It contains one attribute, <b>heading</b>, that is used to contain the heading applied to the section when the MIRCdocument is rendered by a browser. The value of the <b>section</b> element is the content of the section. HTML may be used for formatting; in particular, HTML paragraph elements should generally be used to identify paragraphs. (The rendering software can display content not contained in paragraphs, and certain third-party authoring software sometimes creates documents in this way, but the Author Service is more strict than the display software, so it is necessary to use HTML paragraphs if the Author Service is to be used to edit the document.)<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<section heading="Method"><br />
…Method section contents…<br />
</section><br />
<section heading="Results"><br />
…Results section contents…<br />
</section><br />
…more content…<br />
</MIRCdocument><br />
</pre><br />
<br />
MIRCdocuments used as index cards generally do not have <b>section</b> elements since index cards are only displayed as query results. For all other applications of the MIRCdocument schema, however, the <b>section</b> element provides the way for the author to group related parts of the document together. This grouping instructs the RSNA MIRC software on how to handle the parts of the document when it is displayed. For example, in <b>tab</b> display mode, the RSNA MIRC software creates a separate tab for each <b>section</b>, using the <b>heading</b> attribute as the title of the tab.<br />
<br />
===<b>image-section</b>===<br />
The optional <b>image-section</b> element is used to collect groups of related images. The <b>image-section</b> element supports the <b>heading</b> attribute in the <b>page</b> and <b>tab</b> display modes. The <b>heading</b> attribute provides a label for the section containing the images.<br />
<br />
The <b>image-section</b> element supports the <b>image-pane-width</b> attribute, which instructs the RSNA display software how much space to allocate for image display in the right pane in the <b>tab</b> and <b>mstf</b> display modes. The default value of the <b>image-pane-width</b> attribute is 700. The RSNA MIRC software enforces a minimum width of 512.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>image-section</b> element.<br />
<br />
===<b>references</b>===<br />
The optional <b>references</b> element encapsulates a set of <b>reference</b> elements in the MIRCdocument. The RSNA MIRC software generates a separate section entitled "References" when the MIRCdocument is displayed. The software automatically generates an ordered list of the <b>reference</b> child elements.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<references><br />
<reference><br />
…text of the first reference…<br />
</reference><br />
<reference><br />
…text of the second reference…<br />
</reference><br />
…additional references…<br />
</references><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>references</b> element.<br />
====<b>reference</b>====<br />
The <b>reference</b> element is a simple container identifying the enclosed content as a reference to a publication. It has no internal formatting, although this is an area open to extension. Numbering of the <b>reference</b> elements is generated automatically by the <b>references</b> element when the MIRCdocument is rendered. HTML may be embedded in the <b>reference</b> element.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>reference</b> element.<br />
<br />
===<b>rights</b> and <b>publication-date</b>===<br />
If the <b>rights</b> element and/or the <b>publication-date</b> element appear as direct children of the <b>MIRCdocument</b> element, the RSNA MIRC software displays their values at the end of the document. If they appear within a <b>section</b> element, they are displayed as part of the section.<br />
<br />
See the section below for information about the elements and their contents.<br />
<br />
==Special Purpose Elements==<br />
The schema includes many element which identify specific kinds of information. The RSNA MIRC software renders these elements only when they appear within a <b>section</b> element. Each element may appear multiple times in a <b>section</b> element. These elements can also be used to encode non-displayed information for indexing purposes by placing the elements as direct child elements of the <b>MIRCdocument</b> element.<br />
===<b>history</b>===<br />
The optional <b>history</b> element allows content to be identified as a patient history for use in specialized searches.<br />
===<b>findings</b>===<br />
The optional <b>findings</b> element allows content to be identified as the patient's history for use in specialized searches.<br />
===<b>diagnosis</b>===<br />
The optional <b>diagnosis</b> element allows content to be identified as a diagnosis for use in specialized searches. <br />
<br />
The text value of the <b>diagnosis</b> element contains the diagnosis. It may also contain one or more <b>code</b> elements to capture diagnostic coding information. In addition, it may contain a <b>confirmation</b> element to describe how the diagnosis was confirmed.<br />
<pre><br />
<diagnosis><br />
At <confirmation>autopsy</confirmation>, the patient<br />
was determined to have … .<br />
<code coding-system="coding system name">12345.67890</code><br />
</diagnosis><br />
</pre><br />
====<b>confirmation</b>====<br />
The <b>confirmation</b> element describes how a diagnosis was confirmed.<br />
<br />
===<b>differential-diagnosis</b>===<br />
The optional <b>differential-diagnosis</b> element allows all or part of a part of a section to be identified as the differential diagnosis of the current case for use in specialized searches.<br />
===<b>discussion</b>===<br />
The optional <b>discussion</b> element allows all or part of a part of a section to be identified as case discussion for use in specialized searches.<br />
===<b>pathology</b>===<br />
The optional <b>pathology</b> element allows all or part of a part of a section to be identified as pathology relating to the case for use in specialized searches.<br />
===<b>anatomy</b>===<br />
The optional <b>anatomy</b> element allows all or part of a part of a section to be identified as anatomy relating to the case for use in specialized searches.<br />
===<b>organ-system</b>===<br />
The optional <b>organ-system</b> element allows all or part of a part of a section to be identified as anatomy relating to the case for use in specialized searches.<br />
===<b>a</b>===<br />
The <b>a</b> element inserts a hyperlink into a MIRCdocument. The <b>a</b> element is taken directly from HTML, with the addition of the format attribute:<br />
*<b>href</b> contains the address of the document to which the value text is linked.<br />
*<b>format</b> contains a description of the format of the document to be found at <b>href</b>.<br />
<br />
The value text contains the link text that is rendered in the MIRCdocument.<br />
<br />
The <b>format</b> attribute is optional and is not displayed in the MIRCdocument.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>a</b> element and applies instead the <b>visible</b> attribute of its parent.<br />
<br />
Note:<br />
In version 8.0 of the schema, the <b>link</b> element was used as a synonym of the <b>a</b> element, but only the <b>link</b> element had the <b>format</b> attribute. To eliminate any confusion with the HTML <b>link</b> element, subsequent versions deprecate the <b>link</b> element and add the <b>format</b> attribute to the <b>a</b> element. <br />
<br />
===<b>code</b>===<br />
The <b>code</b> element contains information related to a medical code. It has one attribute and value text:<br />
*<b>coding-system</b> contains the name of the code, e.g., CPT.<br />
*the value text contains the code value itself.<br />
The <b>code</b> element can optionally contain a <b>meaning</b> element. <br />
<br />
When rendered by the RSNA MIRC software, the <b>code</b> element is displayed as: <br />
<br />
<center><br />
[<b>coding-system</b> attribute value]:[<b>code</b> element value] ([<b>meaning</b> element value])<br />
</center><br />
<br />
For example, the following element:<br />
<br />
<pre><br />
<code coding-system="MyCode" visible="yes"><br />
12345.67890<br />
</code><br />
</pre><br />
is displayed by the RSNA MIRC software as: MyCode:12345.67890<br />
====<b>meaning</b>====<br />
The <b>meaning</b> element is used to encapsulate the human language meaning of the code value.<br />
For example, the following element:<br />
<pre><br />
<code coding-system="MyCode" visible="yes"><br />
12345.67890<br />
<meaning visible="yes"><br />
normal variant<br />
</meaning><br />
</code><br />
</pre><br />
is displayed by the RSNA MIRC software as: <br />
MyCode:12345.67890 (normal variant)<br />
<br />
===<b>modality</b>===<br />
The optional <b>modality</b> element contains a list of the modalities related to the document. If contained within an <b>image</b> element, it identifies the modality of the image.<br />
<br />
===<b>patient</b>===<br />
The <b>patient</b> element is used to encapsulate elements describing specific parameters of a patient. <br />
<br />
The subsections below describe the child elements unique to the <b>patient</b> element. Here is an example using some of the child elements:<br />
<br />
<pre><br />
<patient><br />
<pt-name>John Doe</pt-name><br />
<pt-id>7654321</pt-id><br />
<pt-mrn>1234567</pt-id><br />
<pt-age><br />
<years>3</years><br />
</pt-age><br />
<pt-sex>male</pt-sex><br />
<pt-race>caucasian</pt-race><br />
</patient><br />
</pre><br />
====<b>pt-name</b>====<br />
The <b>pt-name</b> element may be used to identify a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-id</b>====<br />
The <b>pt-id</b> element may also be used to identify a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-mrn</b>====<br />
The <b>pt-mrn</b> element may be used to identify the medical record number of a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-age</b>====<br />
The <b>pt-age</b> element encapsulates one or more of the following child elements: <br />
*<b>years</b><br />
*<b>months</b><br />
*<b>weeks</b><br />
*<b>days</b><br />
=====<b>years</b>=====<br />
The <b>years</b> element contains the patient age if expressed in years.<br />
=====<b>months</b>=====<br />
The <b>months</b> element contains the patient age if expressed in months.<br />
=====<b>weeks</b>=====<br />
The <b>weeks</b> element contains the patient age if expressed in weeks.<br />
=====<b>days</b>=====<br />
The <b>days</b> element contains the patient age if expressed in days.<br />
====<b>pt-sex</b>====<br />
The <b>pt-sex</b> element contains one of the values male or female (or neutered in veterinary medicine applications).<br />
====<b>pt-race</b>====<br />
The <b>pt-race</b> element contains the name of the race of the patient.<br />
====<b>pt-species</b>====<br />
<b>pt-species</b> element contains the name of the species of the patient. This element is intended for use in veterinary medicine and paleontology.<br />
====<b>pt-breed</b>====<br />
The <b>pt-breed</b> element contains the name of the breed of the patient. This element is intended for use in veterinary medicine.<br />
<br />
===<b>image</b>===<br />
The <b>image</b> element is used to encapsulate an image and related information<br />
Its <b>src</b> attribute contains the URL of the image to be displayed.<br />
<br />
The <b>image</b> element also has the <b>width</b> and <b>height</b> attributes of the HTML <b>img</b> element. These are passed to the browser to set the displayed width and height of the image; they do not refer to the actual size of the image in the file on the server.<br />
<br />
The value of an <b>image</b> element may be empty or it one or more <b>alternative-image</b> elements, and optionally <b>patient</b>, <b>diagnosis</b>, <b>anatomy</b>, <b>pathology</b>, and <b>code</b> elements to associate the parameters of the patient and/or the diagnosis with the image. It may also contain the <b>modality</b>, <b>format</b> and <b>compression</b> elements to encode parameters of the image itself.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>image</b> element and applies instead the <b>visible</b> attribute of its parent.<br />
<br />
The following example shows the use of an <b>image</b> element to include a JPEG image directly in the rendered document.<br />
<pre><br />
<image src="http://www.abc.edu/images/image1.jpeg"><br />
<format>jpeg</format><br />
</image><br />
</pre><br />
The image appears in sequence with the rest of the text value of the element in which the <b>image</b> element is contained.<br />
<br />
The following more complex coding of the previous example shows the use of multiple child elements within an <b>image</b> element.<br />
<pre><br />
<a href="http://www.abc.edu/images/image1.dcm"><br />
<image src="http://www.abc.edu/images/image1.jpeg"><br />
<format visible=”no”>DICOM</format><br />
<compression visible=”no”>original</compression><br />
<modality visible=”no”>CT</modality><br />
<anatomy visible=”no”>abdomen</anatomy><br />
<pathology visible=”no”>renal carcinoma</pathology><br />
<patient visible=”no”><br />
<pt-age><br />
<years>86</years><br />
</pt-age><br />
<pt-sex>male</pt-sex><br />
</patient><br />
<diagnosis visible=”no”><br />
renal carcinoma<br />
<confirmation>pathology</confirmation><br />
<code coding-system="ABC Code">1234.5678</code><br />
</diagnosis><br />
</image><br />
</a><br />
</pre><br />
The RSNA MIRC implementation often groups related images together within an <b>image</b> element which appears in an <b>image-section</b>. Such groups are sometimes called "megasave groups". The following example shows a megasave group for an image.<br />
<pre><br />
<image src="IMG_1719.jpg" width="374"><br />
<alternative-image role="icon" src="IMG_1719_icon"/><br />
<alternative-image role="annotation" src="IMG_1719_an.svg" type="svg"/><br />
<alternative-image role="annotation" src="IMG_1719_an.jpg" type="image"/><br />
<alternative-image role="original-dimensions" src="IMG_1719_orig.jpg"/><br />
<alternative-image role="original-format" src="IMG_1719.dcm"/><br />
</image><br />
</pre><br />
In this group, the <b>alternative-image</b> children are different versions of the original image (in this case, <b>IMG_1719.dcm</b>) for various purposes. As in the preceding example, other child elements could have been included to provide additional information about the group.<br />
====<b>format</b>====<br />
The <b>format</b> element is used to identify the storage format of an image.<br />
The <b>format</b> element has the enumerated values:<br />
*<b>DICOM</b><br />
*<b>JPEG</b><br />
*<b>PNG</b><br />
*<b>GIF</b><br />
*<b>TIFF</b><br />
====<b>compression</b>====<br />
The <b>compression</b> element is used to identify the compression history of an image.<br />
The <b>compression</b> element has four enumerated values:<br />
*<b>original</b><br />
*<b>reversible</b><br />
*<b>non-reversible</b><br />
*<b>unknown</b><br />
A value at any level in the list above implies that the compression history of the image does not include a version at a lower level. Thus, a value of <b>reversible</b> implies that the image in question is not simply a reversibly compressed version of an image that was non-reversibly compressed.<br />
====<b>alternative-image</b>====<br />
The <b>alternative-image</b> element identifies a version of the parent <b>image</b> element intended to be used for a specific purpose. The <b>alternative-image</b> element has two required attributes.<br />
*<b>src</b> contains the URL of the <b>alternative-image</b>.<br />
*<b>role</b> identifies the purpose of the <b>alternative-image</b>. <br />
The <b>role</b> attribute has four enumerated values:<br />
*<b>icon</b> identifies the <b>alternative-image</b> as a small image intended for use as an icon link to the parent image.<br />
*<b>annotation</b> identifies the <b>alternative-image</b> as annotations for the parent image.<br />
*<b>original-dimensions</b> identifies the <b>alternative-image</b> as a version of the parent image having the same dimensions as the original-format image.<br />
*<b>original-format</b> identifies the <b>alternative-image</b> as the original image acquired by the modality (except for changes required for anonymization).<br />
The <b>alternative-image</b> element with <b>role=”annotation”</b> has one additional attribute, <b>type</b>, that describes the format of the annotation data. The type attribute has two enumerated values:<br />
*<b>image</b> (the default) identifies the annotation data as an image that is to replace the primary image when annotations are displayed.<br />
*<b>svg</b> identifies the annotation data as scalar vector graphics instructions for displaying the annotations overlaid on the primary image when annotations are to be displayed.<br />
The <b>alternative-image</b> element may optionally contain the <b>width</b> and <b>height</b> attributes of the HTML <b>img</b> element. <br />
The <b>alternative-image</b> element is always a child of a <b>image</b> element, and its <b>visible</b> attribute and those of all its children are ignored. <br />
The <b>alternative-image</b> element may also contain <b>format</b> and <b>compression</b> child elements.<br />
<br />
===<b>quiz</b>===<br />
The <b>quiz</b> element is used to contain a quiz that is displayed within a <b>section</b> element in the MIRCdocument. Multiple <b>quiz</b> elements may appear within one <b>section</b> element. Multiple <b>section</b> elements may contain <b>quiz</b> elements.<br />
A quiz has the following structure:<br />
<br />
<pre><br />
<quiz id="…"><br />
<quiz-context><br />
…content defining the context of the quiz…<br />
</quiz-context><br />
<question><br />
<question-body><br />
…content defining the question…<br />
</question-body><br />
<answer correct="yes|no"><br />
<answer-body><br />
…content shown to the user as a possible selection…<br />
</answer-body><br />
<response><br />
…content shown to the user if the answer is selected…<br />
</response><br />
</answer><br />
…additional <answer> elements…<br />
</question><br />
…additional <question> elements…<br />
</quiz><br />
</pre><br />
The <b>quiz</b> element has an <b>id</b> attribute that is intended to allow a CME interface to distinguish all the quizzes in a document. The value of the <b>id</b> attribute should be unique within the <b>MIRCdocument</b>.<br />
<br />
HTML and MIRC elements are permitted in all the child elements. Numbering of the questions and answers is generated automatically by the display software.<br />
<br />
Within a single <b>quiz</b> element, there is no limit to the number of <b>question</b> elements.<br />
<br />
The RSNA MIRC software ignores the <b>visible</b> attribute of the <b>quiz</b> element and all its children.<br />
====<b>quiz-context</b>====<br />
The optional <b>quiz-context</b> element contains any description required to provide a context for the questions to follow. <br />
====<b>question</b>====<br />
The <b>question</b> element contains the body of a quiz question and its possible answers. <br />
Within a single <b>question</b> element, there is no limit to the number of <b>answer</b> elements.<br />
=====<b>question-body</b>=====<br />
The <b>question-body</b> element contains the content of a quiz question. <br />
=====<b>answer</b>=====<br />
The <b>answer</b> element contains the body of an answer to a quiz question and the response which will be provided if the user selects the answer.<br />
<br />
The <b>answer</b> element may contain a <b>correct</b> attribute indicating whether the answer is correct (<b>yes</b>) or not (<b>no</b>). At least one answer to a question must be identified as being correct. Multiple answers to a single question may be identified as being correct. The default value of the <b>correct</b> attribute is <b>no</b>.<br />
======<b>answer-body</b>======<br />
The <b>answer-body</b> element contains the body of an answer to a quiz question. <br />
======<b>response</b>======<br />
The optional <b>response</b> element contains the response which the browser will display if the user selects the answer.<br />
<br />
===<b>show</b>===<br />
The <b>show</b> element is a special purpose display command for documents in the <b>mstf</b> display mode. It is used within paragraphs in <b>section</b> elements to generate a button that allows the user to display a specific image. The <b>show</b> element has two possible attributes, only one of which may be present in any specific element:<br />
*<b>image=”n”</b> causes the button to display the image corresponding to the <b>src</b> attribute of the n-th <b>image</b> element in the <b>image-section</b>.<br />
*<b>annotation=”n”</b> causes the button to display the image corresponding to the <b>src</b> attribute of the <alternative-image role=”annotation”> child element of the n-th <b>image</b> element in the <b>image-section</b>.<br />
<br />
The <b>show</b> element is ignored in the <b>page</b> and <b>tab</b> display modes.<br />
<br />
The <b>show</b> element contains no text or element children. The proper usage is:<br />
<pre><show image="3"/></pre><br />
or <br />
<pre><show annotation="2"/></pre><br />
<br />
===<b>text</b>===<br />
The <b>text</b> element is an encapsulating element whose contents are rendered as if they were part of the element’s parent element. Its function has been overtaken by the development of the T25 version of the Author Service, but it remains in the schema for backward compatibility.<br />
<br />
===<b>text-caption</b>===<br />
The <b>text-caption</b> element is used to embed a centered caption between groups of content in a <b>section</b> element. The <b>text-caption</b> element has several optional attributes:<br />
*<b>display</b> can have the values <b>always</b> and <b>normal</b>. The default is <b>normal</b>.<br />
*<b>jump-buttons</b> can have the values <b>yes</b> and <b>no</b>. The default is <b>no</b>.<br />
*<b>show-button</b> can have the values <b>yes</b> and <b>no</b>. The default is <b>no</b>.<br />
The rendering of the <b>text-caption</b> element depends on its contents and on the values of the <b>display</b>, <b>jump-buttons</b> and <b>show-button</b> attributes:<br />
*If the <b>text-caption</b> element contains only whitespace text, the entire element is ignored when the MIRCdocument is rendered unless the <b>display</b> attribute is present with the value <b>always</b>, in which case the element is rendered, essentially providing an HTML break in the flow. <br />
*If the <b>text-caption</b> element contains any non-whitespace text, the text contents are displayed. <br />
*If the <b>jump-buttons</b> attribute has the value <b>yes</b>, the rendering software inserts two HTML buttons with the values “<<<” and “>>>”. The buttons allow the user to jump up or down to the previous or next <b>text-caption</b>. <br />
*If the the <b>show-button</b> attribute has the value <b>yes</b> and the text content of the caption is non-whitespace, then the text content of the caption is initially hidden when the document is rendered and an HTML button with the value “Show Caption” is inserted between the “<<<” and “>>>” buttons, allowing the user to reveal the caption after examining the content above it.<br />
Note: The RSNA MIRC software also supports the substitution of images for the buttons described above. The default is to use the button images distributed with the software. The buttons are contained in the storage service's <b>buttons</b> directory and are called:<br />
*back.png<br />
*showcaption.png<br />
*forward.png<br />
===<b>metadata-refs</b>===<br />
The RSNA MIRC implementation calls all files "metadata files". The <b>metadata-refs</b> element encapsulates a list of references to metadata files. The <b>metadata-refs</b> element may appear anywhere within a <b>section</b> element. It is rendered by the RSNA MIRC software as a table, with each of its <b>metadata</b> child elements being one row. The value of each <b>metadata</b> element's <b>href</b> attribute provides a link to the corresponding metadata file. The RSNA MIRC software ignores the visible attribute of the <b>metadata-refs</b> element and all its children.<br />
====<b>metadata</b>====<br />
The <b>metadata</b> element identifies a reference to a single data file. It has one required attribute, <b>href</b>, which provides the URL of the data file. There are three child elements.<br />
=====<b>type</b>=====<br />
The <b>type</b> element identifies the type of the metadata file. MIRC currently defines four classes:<br />
*<b>DicomObject</b>: a DICOM file (image, GSPS, KOS, or SR)<br />
*<b>XmlObject</b>: an XML file of any kind<br />
*<b>ZipObject</b>: a zip file with any contents<br />
*<b>FileObject</b>: any file not meeting the criteria above.<br />
<br />
=====<b>date</b>=====<br />
The <b>date</b> element identifies the date associated with the metadata file. The MIRCdocument generator attempts to get the date from the file, and if it fails, uses the last modified date of the file (typically the date the file was received).<br />
<br />
=====<b>desc</b>=====<br />
The <b>desc</b> element describes the metadata file. The MIRCdocument generator attempts to get the description from the file, and if it fails, inserts the file name.<br />
<br />
==Document Description Elements==<br />
Document description elements are used to describe a document at a high level. They typically appear as children of the <b>MIRCdocument</b> element and are therefore not displayed. However, they may also be placed within <b>section</b> elements if display is desired. With the exception of the <b>rights</b> element, HTML may not be used in these elements.<br />
===<b>phi</b>===<br />
The <b>phi</b> element identifies the protected health information (PHI) that is contained in the document. Absence of the element is interpreted to mean that the document contains no PHI. If the document contains PHI, the <b>phi</b> element contains one or more <b>study</b> child elements, each identifying one patient study referenced in the document. The contents of the PHI element and its children are not rendered by the RSNA MIRC implementation; they are used only to provide access logging information required by HIPAA.<br />
====<b>study</b>====<br />
The <b>study</b> element encapsulates the PHI for one patient study. If the document contains PHI for multiple studies, multiple <b>study</b> elements must be present.<br />
=====<b>si-uid</b>=====<br />
The <b>si-uid</b> element contains the Study Instance UID of the study whose images or patient identifying information are contained in the document.<br />
=====<b>pt-id</b>=====<br />
The <b>pt-id</b> element contains the identifier of the patient corresponding to the study.<br />
=====<b>pt-name</b>=====<br />
The <b>pt-name</b> element contains the name of the patient corresponding to the study.<br />
===<b>document-type</b>===<br />
The optional <b>document-type</b> element identifies the document as one of the following types:<br />
*<b>radiologic teaching file</b>: a teaching file, which may be a single case or a collection of cases in a single MIRCdocument<br />
*<b>radiologic collection</b>: a document containing references to multiple radiologic teaching files; a course; a conference<br />
*<b>research dataset</b>: a MIRCdocument describing and containing a link to a research dataset<br />
*<b>educational document</b>: an educational document, e.g. a presentation or course<br />
*<b>technical document</b>: a technical document<br />
Since the MIRCdocument schema permits the construction of complex documents combining characteristics of all the listed document types, multiple types may be listed within the element.<br />
<br />
===<b>category</b>===<br />
The optional <b>category</b> element identifies the document as belonging to one of the American Board of Radiology categories:<br />
*<b>Musculoskeletal</b><br />
*<b>Pulmonary</b><br />
*<b>Cardiovascular </b><br />
*<b>Gastrointestinal</b><br />
*<b>Genitourinary</b><br />
*<b>Neuro</b><br />
*<b>Vascular and Interventional</b><br />
*<b>Nuclear</b><br />
*<b>Ultrasound</b><br />
*<b>Pediatric</b><br />
*<b>Breast</b><br />
When searching for teaching file documents, a user may request that query results be displayed as unknowns. In this case, if the document does not contain an <b>alternative-title</b> element, the RSNA MIRC Storage Service generates a title in the form "Unknown - <b>category value</b>".<br />
<br />
===<b>level</b>===<br />
The optional <b>level</b> element indicates the degree of difficulty of the document. It is intended to allow teaching files to be graded for difficulty, allowing students to search for teaching files corresponding to their level. The level element contains one of:<br />
*<b>primary</b><br />
*<b>intermediate</b><br />
*<b>advanced</b><br />
===<b>lexicon</b>===<br />
The optional <b>lexicon</b> element identifies the name of the lexicon used in the document. <br />
===<b>access</b>===<br />
The optional <b>access</b> element indicates whether a document is accessible:<br />
*<b>public</b>: accessable by anyone<br />
*<b>restricted</b>: accessible only by certain authenticated users<br />
*<b>owner</b>: accessible only by the owner of the document<br />
This element is automatically generated by the RSNA MIRC site software from the contents of the <b>authorization</b> element.<br />
===<b>authorization</b>===<br />
The optional <b>authorization</b> element controls access to the document for various purposes.<br />
====<b>owner</b>====<br />
The optional <b>owner</b> element defines the owner of the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a comma or whitespace delimited list of usernames to be granted all privileges (read, update, export, delete).<br />
====<b>read</b>====<br />
The optional <b>read</b> element defines the individuals or groups who are authorized to view the the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to read the document. Individual users can be granted the read privilege by including their usernames in the list enclosed in square brackets as in this example:<br />
<pre><read>resident staff [drjones] [drjohnson] technologist</read></pre><br />
If the <b>read</b> element is missing, or if the value of the element contains “*”, all users are granted read access. <br />
====<b>update</b>====<br />
The optional <b>update</b> element defines the individuals or groups who are authorized to modify the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to access the document through the author service and store modifications back on the server. Individual users can be granted the update privilege by including their usernames in the list enclosed in square brackets as in the example above.<br />
<br />
If the <b>update</b> element is missing, updates are not authorized. If the value of the element contains “*”, all users are granted update privileges. <br />
====<b>export</b>====<br />
The optional <b>export</b> element defines the individuals or groups who are authorized to export the document from the server to their browser in the source format. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to export the standard MIRC zip file containing the document’s XML file and all its local references. Individual users can be granted the export privilege by including their usernames in the list enclosed in square brackets as in the example above.<br />
<br />
If the <b>export</b> element is missing, or if the value of the element contains “*”, all users are granted export privileges.<br />
<br />
===<b>peer-review</b>===<br />
The optional <b>peer-review</b> element contains information about the peer-review status of the document. If the <b>peer-review</b> element is missing, the document is assumed not to have been peer-reviewed. If the element is present, it must contain child elements identifying the reviewing authority and the status of the peer-review. If the <peer-review> element is displayed, all its children are displayed.<br />
====<b>approval-date</b>====<br />
The <b>approval-date</b> element represents the date on which the document was approved by the reviewing authority. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
====<b>expiration-date</b>====<br />
The optional <b>expiration-date</b> element represents the date on which the reviewing authority's approval of the document will expire. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
====<b>reviewing-authority</b>====<br />
The <b>reviewing-authority</b> element contains the name of the institution or organization responsible for providing the independent peer review before publication. <br />
====<b>reviewer</b>====<br />
The optional <b>reviewer</b> element contains the name of the reviewer.<br />
<br />
===<b>language</b>===<br />
The optional <b>language</b> element specifies the language in which the document is written.<br />
The <b>language</b> element has a required <b>code</b> attribute specifying the ISO 639:1988(E) two-letter code for the language, as defined as in http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt.<br />
<br />
The following code fragment:<br />
<pre><language code="en">English</language></pre><br />
generates the word "English".<br />
<br />
The RSNA MIRC software does not enforce the correspondence between the value of the <b>code</b> attribute and the value of the element. Query searches on language use the value of the <b>code</b> attribute, so the following fragment will possibly produce unexpected results:<br />
<pre><language code="en">French</language></pre><br />
<br />
===<b>creator</b>===<br />
The optional <b>creator</b> element identifies the application program that was used to create the document.<br />
===<b>document-id</b>===<br />
The optional <b>document-id</b> element is intended to provide a place to store a unique identifier for the document. This element is not yet implemented in the RSNA MIRC software.<br />
<br />
===<b>publication-date</b>===<br />
The optional <b>publication-date</b> element contains the date associated with the document, coded in accordance with ISO 8601 (e.g., yyyy-mm-dd). <br />
===<b>revision-history</b>===<br />
The optional <b>revision-history</b> element encapsulates a set of <b>revision</b> elements, one for each revision of the document. If the <b>revision-history</b> element is displayed, all its children are displayed.<br />
====<b>revision</b>====<br />
The optional <b>revision</b> element encapsulates a set of elements that define the author of the revision, the date, and a description of the revision. When present, it must contain the child elements <b>revision-author</b>, <b>revision-date</b>, and <b>revision-description</b>.<br />
=====<b>revision-author</b>=====<br />
The <b>revision-author</b> element contains the name of the person who authored or revised the document.<br />
=====<b>revision-date</b>=====<br />
The <b>revision-date</b> element contains the release date of the revision. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
=====<b>revision-description</b>=====<br />
The <b>revision-description</b> element contains a description of the changes made in the revision.<br />
<br />
===<b>rights</b>===<br />
The optional <b>rights</b> element can contain any text describing the rights held to the document. HTML may be used to format the presentation of the rights text.<br />
<br />
When the <b>rights</b> element is not contained within a <b>section</b> element, the RSNA MIRC software automatically displays the contents of the <b>rights</b> element at the end of a MIRCdocument. This is the only instance where a document description element is displayed when it is not contained within a document structure element.<br />
<br />
==Template Elements==<br />
The RSNA MIRC implementation uses XML files as templates for the automatic construction of MIRCdocuments by several of the services provided by a Storage Service. These are:<br />
*the Author Service<br />
*the DICOM Service<br />
*the TCE Service<br />
*the Zip Service<br />
Except in the case of the Author Service, the reception of a file by a service triggers either the construction of a new MIRCdocument or the modification of an existing one. Templates are MIRCdocument files, that is, they obey the MIRCdocument schema, extended to include elements that instruct the automatic document construction mechanism how to insert data from a file into the MIRCdocument. Except where noted below, template elements themselves are not displayed when a MIRCdocument is displayed.<br />
<br />
===<b>DICOM Elements</b>===<br />
DICOM elements in a template instruct the MIRCdocument generator to insert the values of DICOM dataset elements of a DICOM object into a MIRCdocument. DICOM elements are of the form <GxxxxEyyyy/>. DICOM elements have no child elements or text values. The group (G) and element (E) identifiers (xxxx and yyyy) are 4-place hexadecimal numbers. Upper case and lower case may be mixed anywhere within the element name. <br />
<br />
DICOM elements have an optional <b>desc</b> attribute which is typically used to indicate the human-readable name of the DICOM element it references. This attribute is not used by the MIRCdocument generator if the element references a DICOM element in the DICOM dictionary. For private elements in the dataset, however, it can provide a label for the data in a table. Generally it is recommended to supply the <b>desc</b> attribute, if only to make the template file more readable. The following are examples of DICOM elements:<br />
<pre><br />
<g0010e0010 desc="Patient Name"/><br />
<G0010E0011 desc="Patient ID"/><br />
<g0011e0030 desc="A Private Element"/><br />
</pre><br />
As a MIRCdocument is created from a template, DICOM elements are removed and replaced by data values from the DICOM object which occasioned the creation of the MIRCdocument in the first place. For this reason, DICOM elements can only be populated from the first DICOM object encountered for the document unless the elements are wrapped in a <b>block</b> element.<br />
===<b>block</b>===<br />
The <b>block</b> element is used to encapsulate template contents that are to be preserved for application to every object that is inserted into the MIRCdocument. The MIRCdocument generator processes the contents of the <b>block</b> element and inserts them immediately before the <b>block</b> element in the MIRCdocument. The <b>block</b> element itself is not rendered when the MIRCdocument is displayed.<br />
<br />
This is an example of a <b>block</b> element being used to create a table of SOP Instance UIDs for the objects inserted into a MIRCdocument in a clinical trial:<br />
<pre><br />
<section heading="SOP Instance UIDs"><br />
<p><br />
<table border="1"><br />
<tr><th>Image Number</th><th>SOP Instance UID</th></tr><br />
<block><br />
<tr><br />
<td><g0020e0013 desc="Instance Number"/></td><br />
<td><g0008e0018 desc="SOP Instance UID"/></td><br />
</tr><br />
</block><br />
</table><br />
</p><br />
</section><br />
</pre><br />
<br />
===<b>insert-image</b>===<br />
The <b>insert-image</b> element appears within a <b>section</b> element and instructs the MIRCdocument generator to insert a reference to an image. It supports the following attributes:<br />
*<b>width</b> specifies the maximum width of the JPEG image to be created. The default value is 700.<br />
*<b>min-width</b> specifies the minimum width of the JPEG image to be created. The default value is 0.<br />
*<b>extra-image-min-size</b> specifies the minimum width of an extra JPEG image to be created but not referenced by the MIRCdocument. If the attribute is not present, or if the image being inserted is not a DICOM image, no extra image is created. <br />
*<b>caption</b> specifies whether a <b>text-caption</b> element is to be generated after the image reference. The value of the <b>caption</b> attribute must be numeric.<br />
*<b>jump-buttons</b> indicates whether the <b>text-caption</b> element is to be generated with a <b>jump-buttons</b> attribute. The possible values of the next-button attribute are <b>yes</b> and <b>no</b>.<br />
*<b>show-button</b> indicates whether the <b>text-caption</b> element is to be generated with a <b>show-button</b> attribute. The possible values of the next-button attribute are <b>yes</b> and <b>no</b>.<br />
<br />
The <b>insert-image</b> element has no child elements or text value.<br />
<br />
===<b>insert-megasave</b>===<br />
The <b>insert-megasave</b> element appears within an <b>image-section</b> element and instructs the MIRCdocument generator to insert a reference to a megasave image group. It supports the following attributes:<br />
*<b>width</b> specifies the maximum width of the JPEG image to be created. The default value is 700.<br />
*<b>min-width</b> specifies the minimum width of the JPEG image to be created. The default value is 0.<br />
*<b>extra-image-min-size</b> specifies the minimum width of an extra JPEG image to be created but not referenced by the MIRCdocument. If the attribute is not present, or if the image being inserted is not a DICOM image, no extra image is created.<br />
<br />
The <b>insert-megasave</b> element has no child elements or text value.<br />
<br />
===<b>insert-dataset</b>===<br />
The <b>insert-dataset</b> element instructs the MIRGdocument generator to create a folder hierarchy within the MIRCdocument’s directory and store a copy of a DICOM image within it. The <b>insert-dataset</b> element appears as a first-generation child of the <b>MIRCdocument</b> element.<br />
<br />
The <b>insert-dataset</b> element supports the <b>phi</b> attribute, which specifies whether the stored DICOM instance is to contain protected healthcare information. The possible values of the phi attribute are <b>yes</b> and <b>no</b>:<br />
<br />
*<b>phi=”yes”</b> creates a folder named <b>phi</b>. Instances are stored unmodified in subdirectories named for the Series Description (if present), the Series Number (if present), or the Series Instance UID. <br />
<br />
*<b>phi=”no”</b> creates a folder named <b>no-phi</b>. Instances are first de-identified using the storage service’s anonymization rules and then stored in subdirectories named as described above.<br />
<br />
When MIRCdocuments containing <b>insert-dataset</b> elements are displayed, links are provided allowing for the export of a zip file containing the requested dataset.<br />
===<b>metadata-refs</b>===<br />
The <b>metadata-refs</b> element instructs the MIRCdocument generator to insert a <b>metadata</b> child element to identify a file referenced by the MIRCdocument. This element and its children are described in the [[#metadata-refs|Special Purpose Elements section]].</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=The_MIRCdocument_Schema&diff=2041The MIRCdocument Schema2006-08-12T01:32:49Z<p>209.242.55.28: /* <b>insert-image</b> */</p>
<hr />
<div>==Introduction==<br />
This article describes the XML schema for indexable documents on sites using the RSNA MIRC software. It is intended for engineers implementing MIRC sites and authoring tools as well as for administrators and MIRCdocument authors who wish to exploit the full capabilities of their sites. The article assumes a basic understanding of XML. For more information on XML, see the [[XML_Primer|XML Primer]].<br />
<br />
The MIRCdocument schema includes all the MIRC-specific elements and attributes that can be included in a document on a MIRC site running the RSNA MIRC software. Where noted below, HTML elements may also be included as well.<br />
<br />
All elements in the schema include a <b>visible</b> attribute that allows the author to instruct a MIRC site's display software whether to render the contents of the element. Except where noted, the default value of the <b>visible</b> attribute is <b>yes</b>. The rendering behavior described inthis article is that provided by the RSNA MIRC software when MIRCdocuments are accessed by a browser (via an HTTP GET). In all cases, if a parent element's <b>visible</b> attribute is <b>no</b>, none of its children are rendered, and if a parent element's <b>visible</b> attribute is <b>yes</b>, only children whose <b>visible</b> attributes are <b>yes</b> are rendered.<br />
<br />
==The <b>MIRCdocument</b> Element==<br />
The <b>MIRCdocument</b> element is the root element of all MIRCdocuments. It encloses all the content of a MIRCdocument:<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
====The <b>docref</b> Attribute====<br />
When a user selects a MIRCdocument for display, the user's browser is directed either to the MIRCdocument itself or to another document. The optional <b>docref</b> attribute provides the link. To understand its use, it is helpful to understand the MIRC search mechanism. <br />
<br />
A user accesses a MIRC Query Service from a web browser. The Query Service provides an HTML form into which the user inserts the search criteria. Upon completion of the form, the browser posts it to the Query Service, which then constructs a query from the form data and posts it to the MIRC Storage Services identified in the form. The query is an XML object in a format defined by the <b>MIRCquery</b> schema. Each Storage Service searches its content for documents matching the search criteria, encodes the list of matching documents in an XML object in a format defined by the <b>MIRCqueryresult</b> schema, and sends the list to the Query Service. In the <b>MIRCqueryresult</b> schema, each document that matches the search criteria is identified by a URL. The Query Service compiles the results from all the Storage Services polled and sends the consolidated results to the user's browser. The consolidated results are constructed as an HTML ordered list, where each item in the list describes one document matching the search criteria and provides a link to the document iself. When the user selects an item in the list, the browser obtains the document identified by the link. In the RSNA MIRC implementation, the <b>docref</b> attribute is used to construct the URL that provides that link. <br />
<br />
Some MIRCdocuments contain a complete document, allowing them to be self-indexing. Other MIRCdocuments serve as indexable documents describing information in other formats. To accommodate these different kinds of MIRCdocuments on sites using the RSNA MIRC software, the docref attribute may be coded in several ways. <br />
*If the <b>docref</b> attribute is not included in the <b>MIRCdocument</b> element, the RSNA MIRC Storage Service provides a link to the file containing the MIRCdocument. This technique is used when the <b>MIRCdocument</b> element contains a complete document. For example, a teaching file case can be constructed as a MIRCdocument and indexed by a Storage Service. When a user selects the document from a list of search results, the link takes the user to the document itself. In this case, the <b>MIRCdocument</b> element is defined without a <b>docref</b> attribute:<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with no path information, the RSNA MIRC Storage Service provides a link to the named document in the same directory on the Storage Service as the MIRCdocument. This technique is used when the MIRCdocument is only a means to index another kind of content. For example, when the actual content of interest is a presentation in PowerPoint format, it can be indexed by creating a short MIRCdocument containing the title, the authors, and an abstract. This MIRCdocument, called an "index card", is only useful during the user's search for the document, so the <b>docref</b> attribute is set to point to the presentation file itself, and the Storage Service stores the presentation file and the index file in the same directory.<br />
<br />
<pre><br />
<MIRCdocument docref="presentationfilename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with path information, the RSNA MIRC Storage Service provides a link to the named document. This technique is a more general example of the previous case. It is used when the actual document of interest is not stored in the same directory on the Storage Service as the MIRCdocument that indexes it. Since authors generally do not control the actual storage locations of their documents, this mechanism is infrequently used, and then only by MIRC administrators.<br />
<br />
This is an example of an index card referencing a presentation stored by a MIRC administrator in a common "presentations" directory under the "MIRCdocuments" directory of the server root:<br />
<br />
<pre><br />
<MIRCdocument docref="/MIRCdocuments/presentations/filename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with a fully qualified path, the RSNA MIRC Storage Service provides a link to the named document. This technique is a more general example of the previous case. It is used when the actual content of interest is a document not stored on the same Storage Service as the MIRCdocument that indexes it. This mechanism can be used to index the contents of a webserver on a MIRC Storage Service without storing the documents on the Storage Service itself. <br />
<br />
This is an example of an index card referencing a document stored somewhere on the web:<br />
<br />
<pre><br />
<MIRCdocument docref="http://www.somewhere.edu/filename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
=====Important Note for MIRC Site Implementers=====<br />
The description in the section above applies to MIRCdocuments stored on MIRC sites using the RSNA MIRC software. It is important not to confuse the flexibility in the use of the <b>docref</b> attribute described here with the inflexible requirement that a Storage Service provide a fully qualified URL for each document in its <b>MIRCqueryresult</b> reply to a Query Service.<br />
<br />
The <b>MIRCqueryresult</b> schema uses the <b>MIRCdocument</b> element to describe each document meeting the search criteria it received in a MIRCquery. A detailed description of the <b>MIRCqueryresult</b> schema is included in a [[The_MIRCquery_and_MIRCqueryresult_Schemas|separate article]]. Briefly, a <b>MIRCqueryresult</b> has the following form:<br />
<br />
<pre><br />
<MIRCqueryresult><br />
<MIRCdocument docref="http://www.somewhere.edu/filename"><br />
…title, author, abstract content…<br />
</MIRCdocument><br />
…additional <MIRCdocument> elements – one for each query match…<br />
</MIRCqueryresult><br />
</pre><br />
<br />
In the <b>MIRCqueryresult</b> schema, each <b>MIRCdocument</b> element is required to provide a fully qualified URL pointing to the document. On sites using the RSNA MIRC software, that URL is generated automatically by the Storage Service as described in the section above for documents with a missing <b>docref</b> attribute or with one that contains a less than fully qualified URL.<br />
<br />
====The <b>display</b> Attribute====<br />
The <b>MIRCdocument</b> element also supports the optional <b>display</b> attribute, which can be used to instruct the MIRC rendering software on how the author intended the document to be displayed. The RSNA MIRC rendering software supports three values of the <b>display</b> attribute:<br />
<br />
*<b>page</b> instructs the rendering software to display the document in a linear, sequential fashion as a normal document would appear. This is the default value.<br />
*<b>tab</b> instructs the rendering software to display the document with each section appearing as a separate tab.<br />
*<b>mstf</b> instructs the rendering software to display the document in a standardized teaching file format oriented toward residents. For compatibility with previous releases, <b>mirctf</b> is a synonym for <b>mstf</b>.<br />
<br />
====The <b>first-tab</b> Attribute====<br />
The <b>first-tab</b> attribute of the <b>MIRCdocument</b> element instructs the rendering software which tab to display first. This attribute is used in the tab and mstf display formats. It is ignored in the page display format. The default value of the first-tab attribute is 2.<br />
<br />
====The <b>show-empty-tabs</b> Attribute====<br />
The <b>show-empty-tabs</b> attribute of the <b>MIRCdocument</b> element instructs the rendering software whether to display sections that have no content. This attribute is used in the tab and mstf display formats. It is ignored in the page display format. The possible values are yes and no. The default value of the show-empty-tabs attribute is no.<br />
<br />
====The <b>background</b> Attribute====<br />
The <b>background</b> attribute of the <b>MIRCdocument</b> element defines the background color of the document when it is displayed. The possible values are <b>light</b> and <b>dark</b>. The default is <b>light</b>.<br />
<br />
====The <b>path</b> Attribute====<br />
The <b>path</b> attribute of the <b>MIRCdocument</b> element is dynamically generated by the RSNA MIRC software when a MIRCdocument is exported from a storage service. It is used to provide third-party, client-side authoring tools the relative path to the document on the server.<br />
<br />
====The <b>as-mode</b> Attribute====<br />
The <b>as-mode</b> attribute of the <b>MIRCdocument</b> element is automatically generated by the Author Service when an author edits the MIRCdocument. It defines whether technical elements are displayed in the editor. Its possible values are <b>true</b> and <b>false</b>.<br />
<br />
====The <b>visible</b> Attribute====<br />
The <b>visible</b> attribute of the <b>MIRCdocument</b> element is ignored by the RSNA MIRC software.<br />
<br />
==Document Structure Elements==<br />
Certain first-generation child elements of the <b>MIRCdocument</b> element are used to provide structure for a document, encapsulating titles, authors, abstracts, keywords, and the various content sections of the document. They are used both to encode key information to be matched against search criteria and to organize the entire document for display.<br />
<br />
The RSNA MIRC software only displays MIRCdocument content which appears within one of these elements. Information included for indexing purposes only can be placed as text value or child elements of the <b>MIRCdocument</b> element or in a <b>section</b> element with the <b>visible</b> attribute set to <b>no</b>.<br />
===<b>title</b>===<br />
The <b>title</b> element contains the title of the document. The <b>title</b> element and the <b>alternative-title</b> element determine the title displayed when the document is rendered or when it appears in a list of search results. See the next section, <b>alternative-title</b>, for details.<br />
HTML should not be embedded in the <b>title</b> element.<br />
<br />
<pre><br />
<MIRCdocument><br />
<title>This is the Title</title><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>title</b> element.<br />
===<b>alternative-title</b>===<br />
The optional <b>alternative-title</b> element provides a title which is used when the document is requested to be displayed as an unknown case. <br />
<br />
HTML should not be embedded in the <b>alternative-title</b> element.<br />
<br />
The RSNA MIRC software ignores the the <b>visible</b> attribute of the <alternative-title> element.<br />
<br />
When the Storage Service receives a query requesting the results as unknowns, it substitutes the contents of the <b>alternative-title</b> element for the <b>title</b> element when constructing the list of query results. If the <b>alternative-title</b> element is missing, the Storage Service generates a title as described in the section on the <b>category</b> element.<br />
<br />
The Storage Service similarly substitutes the contents of the <b>alternative-title</b> element when it is requested to display the document as an unknown.<br />
<br />
===<b>author</b>===<br />
The optional <b>author</b> element contains information for a single author. When a document has multiple authors, multiple <b>author</b> elements are used.<br />
<br />
Within the <b>author</b> element are three optional child elements containing the author's name, affiliation, and contact information.<br />
<br />
HTML should not be embedded in the <b>author</b> element or its children.<br />
<br />
<pre><br />
<MIRCdocument><br />
<title>This is the Title</title><br />
<author><br />
<name>John Author</name><br />
<affiliation>Organization of John Author</affiliation><br />
<contact>Email address of John Author</contact><br />
<contact>Post address of John Author – line 1</contact><br />
<contact>Post address of John Author – line 2</contact><br />
</author><br />
<author><br />
<name>Mary Author</name><br />
<affiliation>Organization of Mary Author</affiliation><br />
<contact>Email address of Mary Author</contact><br />
</author><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the visible attribute of the <b>author</b> element and its children.<br />
<br />
====<b>name</b>====<br />
The <b>name</b> element contains the author's name. No provision is made for identifying the given name, surname, or titles. The value of each <b>name</b> element appears in the search result list.<br />
<br />
====<b>affiliation</b>====<br />
The <b>affiliation</b> element contains one line of the name of an organization with which the author is affiliated. If multiple lines are required, or if the author is affiliated with multiple organizations, multiple <b>affiliation</b> elements are used. No provision is made for separating multiple organizations.<br />
====<b>contact</b>====<br />
The <b>contact</b> element contains one line of information on how to contact the author. If multiple lines are required, multiple <b>contact</b> elements are used. No provision is made for identifying the kind of contact information (phone, email, post, etc.) contained in the element.<br />
===<b>abstract</b>===<br />
The <b>abstract</b> element contains the abstract of the document. The <b>abstract</b> element and the <b>alternative-abstract</b> element determine the abstract displayed when the document is rendered or when it appears in a list of search results. See the next section, <b>alternative-abstract</b>, for details.<br />
<br />
HTML may be used for formatting; in particular, HTML paragraph elements must be used to identify the paragraphs.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<abstract><br />
<p><br />
First <b>paragraph</b> of the abstract.<br />
</p><br />
<p><br />
Second <b>paragraph</b> of the abstract.<br />
</p><br />
</abstract><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b><abstract</b> element.<br />
<br />
===<b>alternative-abstract</b>===<br />
The <b>alternative-abstract</b> element provides an alternative abstract which is used when the document is requested to be displayed as an unknown case.<br />
<br />
HTML may be used for formatting as in the <b>abstract</b> element.<br />
<br />
The RSNA MIRC software ignores the <b>visible</b> attribute of the <b>alternative-abstract</b> element.<br />
<br />
When the Storage Service receives a query requesting the results as unknowns, it substitutes the contents of the <b>alternative-abstract</b> element for the <b>abstract</b> element when constructing the list of query results. If the <b>alternative-abstract</b> element is missing, the Storage Service generates no <b>abstract</b> element.<br />
<br />
For MIRCdocuments with the <b>display</b> attribute set to <b>page</b>, the Storage Service similarly substitutes the contents of the <b>alternative-abstract</b> element when it is requested to display the document as an unknown. (The <b>abstract</b> element is used in MIRCdocuments with the <b>display</b> attribute set to <b>tab</b> or <b>mstf</b>. In these documents, the abstract is included in the first tab and the first tab displayed is typically the second tab, thus concealing the content of the abstract until the user wants to see it.)<br />
<br />
===<b>keywords</b>===<br />
The optional <b>keywords</b> element contains a list of words under which the document should be indexed. Although all words in a document are indexed, the <b>keywords</b> element makes it also possible to query for only those words explicitly identified as keywords.<br />
<br />
HTML should not be embedded in the <b>keywords</b> element.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<keywords>word1 word2 word3</keywords><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>keywords</b> element.<br />
===<b>section</b>===<br />
The optional <b>section</b> element is used to identify separate parts of a MIRCdocument. It contains one attribute, <b>heading</b>, that is used to contain the heading applied to the section when the MIRCdocument is rendered by a browser. The value of the <b>section</b> element is the content of the section. HTML may be used for formatting; in particular, HTML paragraph elements should generally be used to identify paragraphs. (The rendering software can display content not contained in paragraphs, and certain third-party authoring software sometimes creates documents in this way, but the Author Service is more strict than the display software, so it is necessary to use HTML paragraphs if the Author Service is to be used to edit the document.)<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<section heading="Method"><br />
…Method section contents…<br />
</section><br />
<section heading="Results"><br />
…Results section contents…<br />
</section><br />
…more content…<br />
</MIRCdocument><br />
</pre><br />
<br />
MIRCdocuments used as index cards generally do not have <b>section</b> elements since index cards are only displayed as query results. For all other applications of the MIRCdocument schema, however, the <b>section</b> element provides the way for the author to group related parts of the document together. This grouping instructs the RSNA MIRC software on how to handle the parts of the document when it is displayed. For example, in <b>tab</b> display mode, the RSNA MIRC software creates a separate tab for each <b>section</b>, using the <b>heading</b> attribute as the title of the tab.<br />
<br />
===<b>image-section</b>===<br />
The optional <b>image-section</b> element is used to collect groups of related images. The <b>image-section</b> element supports the <b>heading</b> attribute in the <b>page</b> and <b>tab</b> display modes. The <b>heading</b> attribute provides a label for the section containing the images.<br />
<br />
The <b>image-section</b> element supports the <b>image-pane-width</b> attribute, which instructs the RSNA display software how much space to allocate for image display in the right pane in the <b>tab</b> and <b>mstf</b> display modes. The default value of the <b>image-pane-width</b> attribute is 700. The RSNA MIRC software enforces a minimum width of 512.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>image-section</b> element.<br />
<br />
===<b>references</b>===<br />
The optional <b>references</b> element encapsulates a set of <b>reference</b> elements in the MIRCdocument. The RSNA MIRC software generates a separate section entitled "References" when the MIRCdocument is displayed. The software automatically generates an ordered list of the <b>reference</b> child elements.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<references><br />
<reference><br />
…text of the first reference…<br />
</reference><br />
<reference><br />
…text of the second reference…<br />
</reference><br />
…additional references…<br />
</references><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>references</b> element.<br />
====<b>reference</b>====<br />
The <b>reference</b> element is a simple container identifying the enclosed content as a reference to a publication. It has no internal formatting, although this is an area open to extension. Numbering of the <b>reference</b> elements is generated automatically by the <b>references</b> element when the MIRCdocument is rendered. HTML may be embedded in the <b>reference</b> element.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>reference</b> element.<br />
<br />
===<b>rights</b> and <b>publication-date</b>===<br />
If the <b>rights</b> element and/or the <b>publication-date</b> element appear as direct children of the <b>MIRCdocument</b> element, the RSNA MIRC software displays their values at the end of the document. If they appear within a <b>section</b> element, they are displayed as part of the section.<br />
<br />
See the section below for information about the elements and their contents.<br />
<br />
==Special Purpose Elements==<br />
The schema includes many element which identify specific kinds of information. The RSNA MIRC software renders these elements only when they appear within a <b>section</b> element. Each element may appear multiple times in a <b>section</b> element. These elements can also be used to encode non-displayed information for indexing purposes by placing the elements as direct child elements of the <b>MIRCdocument</b> element.<br />
===<b>history</b>===<br />
The optional <b>history</b> element allows content to be identified as a patient history for use in specialized searches.<br />
===<b>findings</b>===<br />
The optional <b>findings</b> element allows content to be identified as the patient's history for use in specialized searches.<br />
===<b>diagnosis</b>===<br />
The optional <b>diagnosis</b> element allows content to be identified as a diagnosis for use in specialized searches. <br />
<br />
The text value of the <b>diagnosis</b> element contains the diagnosis. It may also contain one or more <b>code</b> elements to capture diagnostic coding information. In addition, it may contain a <b>confirmation</b> element to describe how the diagnosis was confirmed.<br />
<pre><br />
<diagnosis><br />
At <confirmation>autopsy</confirmation>, the patient<br />
was determined to have … .<br />
<code coding-system="coding system name">12345.67890</code><br />
</diagnosis><br />
</pre><br />
====<b>confirmation</b>====<br />
The <b>confirmation</b> element describes how a diagnosis was confirmed.<br />
<br />
===<b>differential-diagnosis</b>===<br />
The optional <b>differential-diagnosis</b> element allows all or part of a part of a section to be identified as the differential diagnosis of the current case for use in specialized searches.<br />
===<b>discussion</b>===<br />
The optional <b>discussion</b> element allows all or part of a part of a section to be identified as case discussion for use in specialized searches.<br />
===<b>pathology</b>===<br />
The optional <b>pathology</b> element allows all or part of a part of a section to be identified as pathology relating to the case for use in specialized searches.<br />
===<b>anatomy</b>===<br />
The optional <b>anatomy</b> element allows all or part of a part of a section to be identified as anatomy relating to the case for use in specialized searches.<br />
===<b>organ-system</b>===<br />
The optional <b>organ-system</b> element allows all or part of a part of a section to be identified as anatomy relating to the case for use in specialized searches.<br />
===<b>a</b>===<br />
The <b>a</b> element inserts a hyperlink into a MIRCdocument. The <b>a</b> element is taken directly from HTML, with the addition of the format attribute:<br />
*<b>href</b> contains the address of the document to which the value text is linked.<br />
*<b>format</b> contains a description of the format of the document to be found at <b>href</b>.<br />
<br />
The value text contains the link text that is rendered in the MIRCdocument.<br />
<br />
The <b>format</b> attribute is optional and is not displayed in the MIRCdocument.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>a</b> element and applies instead the <b>visible</b> attribute of its parent.<br />
<br />
Note:<br />
In version 8.0 of the schema, the <b>link</b> element was used as a synonym of the <b>a</b> element, but only the <b>link</b> element had the <b>format</b> attribute. To eliminate any confusion with the HTML <b>link</b> element, subsequent versions deprecate the <b>link</b> element and add the <b>format</b> attribute to the <b>a</b> element. <br />
<br />
===<b>code</b>===<br />
The <b>code</b> element contains information related to a medical code. It has one attribute and value text:<br />
*<b>coding-system</b> contains the name of the code, e.g., CPT.<br />
*the value text contains the code value itself.<br />
The <b>code</b> element can optionally contain a <b>meaning</b> element. <br />
<br />
When rendered by the RSNA MIRC software, the <b>code</b> element is displayed as: <br />
<br />
<center><br />
[<b>coding-system</b> attribute value]:[<b>code</b> element value] ([<b>meaning</b> element value])<br />
</center><br />
<br />
For example, the following element:<br />
<br />
<pre><br />
<code coding-system="MyCode" visible="yes"><br />
12345.67890<br />
</code><br />
</pre><br />
is displayed by the RSNA MIRC software as: MyCode:12345.67890<br />
====<b>meaning</b>====<br />
The <b>meaning</b> element is used to encapsulate the human language meaning of the code value.<br />
For example, the following element:<br />
<pre><br />
<code coding-system="MyCode" visible="yes"><br />
12345.67890<br />
<meaning visible="yes"><br />
normal variant<br />
</meaning><br />
</code><br />
</pre><br />
is displayed by the RSNA MIRC software as: <br />
MyCode:12345.67890 (normal variant)<br />
<br />
===<b>modality</b>===<br />
The optional <b>modality</b> element contains a list of the modalities related to the document. If contained within an <b>image</b> element, it identifies the modality of the image.<br />
<br />
===<b>patient</b>===<br />
The <b>patient</b> element is used to encapsulate elements describing specific parameters of a patient. <br />
<br />
The subsections below describe the child elements unique to the <b>patient</b> element. Here is an example using some of the child elements:<br />
<br />
<pre><br />
<patient><br />
<pt-name>John Doe</pt-name><br />
<pt-id>7654321</pt-id><br />
<pt-mrn>1234567</pt-id><br />
<pt-age><br />
<years>3</years><br />
</pt-age><br />
<pt-sex>male</pt-sex><br />
<pt-race>caucasian</pt-race><br />
</patient><br />
</pre><br />
====<b>pt-name</b>====<br />
The <b>pt-name</b> element may be used to identify a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-id</b>====<br />
The <b>pt-id</b> element may also be used to identify a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-mrn</b>====<br />
The <b>pt-mrn</b> element may be used to identify the medical record number of a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-age</b>====<br />
The <b>pt-age</b> element encapsulates one or more of the following child elements: <br />
*<b>years</b><br />
*<b>months</b><br />
*<b>weeks</b><br />
*<b>days</b><br />
=====<b>years</b>=====<br />
The <b>years</b> element contains the patient age if expressed in years.<br />
=====<b>months</b>=====<br />
The <b>months</b> element contains the patient age if expressed in months.<br />
=====<b>weeks</b>=====<br />
The <b>weeks</b> element contains the patient age if expressed in weeks.<br />
=====<b>days</b>=====<br />
The <b>days</b> element contains the patient age if expressed in days.<br />
====<b>pt-sex</b>====<br />
The <b>pt-sex</b> element contains one of the values male or female (or neutered in veterinary medicine applications).<br />
====<b>pt-race</b>====<br />
The <b>pt-race</b> element contains the name of the race of the patient.<br />
====<b>pt-species</b>====<br />
<b>pt-species</b> element contains the name of the species of the patient. This element is intended for use in veterinary medicine and paleontology.<br />
====<b>pt-breed</b>====<br />
The <b>pt-breed</b> element contains the name of the breed of the patient. This element is intended for use in veterinary medicine.<br />
<br />
===<b>image</b>===<br />
The <b>image</b> element is used to encapsulate an image and related information<br />
Its <b>src</b> attribute contains the URL of the image to be displayed.<br />
<br />
The <b>image</b> element also has the <b>width</b> and <b>height</b> attributes of the HTML <b>img</b> element. These are passed to the browser to set the displayed width and height of the image; they do not refer to the actual size of the image in the file on the server.<br />
<br />
The value of an <b>image</b> element may be empty or it one or more <b>alternative-image</b> elements, and optionally <b>patient</b>, <b>diagnosis</b>, <b>anatomy</b>, <b>pathology</b>, and <b>code</b> elements to associate the parameters of the patient and/or the diagnosis with the image. It may also contain the <b>modality</b>, <b>format</b> and <b>compression</b> elements to encode parameters of the image itself.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>image</b> element and applies instead the <b>visible</b> attribute of its parent.<br />
<br />
The following example shows the use of an <b>image</b> element to include a JPEG image directly in the rendered document.<br />
<pre><br />
<image src="http://www.abc.edu/images/image1.jpeg"><br />
<format>jpeg</format><br />
</image><br />
</pre><br />
The image appears in sequence with the rest of the text value of the element in which the <b>image</b> element is contained.<br />
<br />
The following more complex coding of the previous example shows the use of multiple child elements within an <b>image</b> element.<br />
<pre><br />
<a href="http://www.abc.edu/images/image1.dcm"><br />
<image src="http://www.abc.edu/images/image1.jpeg"><br />
<format visible=”no”>DICOM</format><br />
<compression visible=”no”>original</compression><br />
<modality visible=”no”>CT</modality><br />
<anatomy visible=”no”>abdomen</anatomy><br />
<pathology visible=”no”>renal carcinoma</pathology><br />
<patient visible=”no”><br />
<pt-age><br />
<years>86</years><br />
</pt-age><br />
<pt-sex>male</pt-sex><br />
</patient><br />
<diagnosis visible=”no”><br />
renal carcinoma<br />
<confirmation>pathology</confirmation><br />
<code coding-system="ABC Code">1234.5678</code><br />
</diagnosis><br />
</image><br />
</a><br />
</pre><br />
The RSNA MIRC implementation often groups related images together within an <b>image</b> element which appears in an <b>image-section</b>. Such groups are sometimes called "megasave groups". The following example shows a megasave group for an image.<br />
<pre><br />
<image src="IMG_1719.jpg" width="374"><br />
<alternative-image role="icon" src="IMG_1719_icon"/><br />
<alternative-image role="annotation" src="IMG_1719_an.svg" type="svg"/><br />
<alternative-image role="annotation" src="IMG_1719_an.jpg" type="image"/><br />
<alternative-image role="original-dimensions" src="IMG_1719_orig.jpg"/><br />
<alternative-image role="original-format" src="IMG_1719.dcm"/><br />
</image><br />
</pre><br />
In this group, the <b>alternative-image</b> children are different versions of the original image (in this case, <b>IMG_1719.dcm</b>) for various purposes. As in the preceding example, other child elements could have been included to provide additional information about the group.<br />
====<b>format</b>====<br />
The <b>format</b> element is used to identify the storage format of an image.<br />
The <b>format</b> element has the enumerated values:<br />
*<b>DICOM</b><br />
*<b>JPEG</b><br />
*<b>PNG</b><br />
*<b>GIF</b><br />
*<b>TIFF</b><br />
====<b>compression</b>====<br />
The <b>compression</b> element is used to identify the compression history of an image.<br />
The <b>compression</b> element has four enumerated values:<br />
*<b>original</b><br />
*<b>reversible</b><br />
*<b>non-reversible</b><br />
*<b>unknown</b><br />
A value at any level in the list above implies that the compression history of the image does not include a version at a lower level. Thus, a value of <b>reversible</b> implies that the image in question is not simply a reversibly compressed version of an image that was non-reversibly compressed.<br />
====<b>alternative-image</b>====<br />
The <b>alternative-image</b> element identifies a version of the parent <b>image</b> element intended to be used for a specific purpose. The <b>alternative-image</b> element has two required attributes.<br />
*<b>src</b> contains the URL of the <b>alternative-image</b>.<br />
*<b>role</b> identifies the purpose of the <b>alternative-image</b>. <br />
The <b>role</b> attribute has four enumerated values:<br />
*<b>icon</b> identifies the <b>alternative-image</b> as a small image intended for use as an icon link to the parent image.<br />
*<b>annotation</b> identifies the <b>alternative-image</b> as annotations for the parent image.<br />
*<b>original-dimensions</b> identifies the <b>alternative-image</b> as a version of the parent image having the same dimensions as the original-format image.<br />
*<b>original-format</b> identifies the <b>alternative-image</b> as the original image acquired by the modality (except for changes required for anonymization).<br />
The <b>alternative-image</b> element with <b>role=”annotation”</b> has one additional attribute, <b>type</b>, that describes the format of the annotation data. The type attribute has two enumerated values:<br />
*<b>image</b> (the default) identifies the annotation data as an image that is to replace the primary image when annotations are displayed.<br />
*<b>svg</b> identifies the annotation data as scalar vector graphics instructions for displaying the annotations overlaid on the primary image when annotations are to be displayed.<br />
The <b>alternative-image</b> element may optionally contain the <b>width</b> and <b>height</b> attributes of the HTML <b>img</b> element. <br />
The <b>alternative-image</b> element is always a child of a <b>image</b> element, and its <b>visible</b> attribute and those of all its children are ignored. <br />
The <b>alternative-image</b> element may also contain <b>format</b> and <b>compression</b> child elements.<br />
<br />
===<b>quiz</b>===<br />
The <b>quiz</b> element is used to contain a quiz that is displayed within a <b>section</b> element in the MIRCdocument. Multiple <b>quiz</b> elements may appear within one <b>section</b> element. Multiple <b>section</b> elements may contain <b>quiz</b> elements.<br />
A quiz has the following structure:<br />
<br />
<pre><br />
<quiz id="…"><br />
<quiz-context><br />
…content defining the context of the quiz…<br />
</quiz-context><br />
<question><br />
<question-body><br />
…content defining the question…<br />
</question-body><br />
<answer correct="yes|no"><br />
<answer-body><br />
…content shown to the user as a possible selection…<br />
</answer-body><br />
<response><br />
…content shown to the user if the answer is selected…<br />
</response><br />
</answer><br />
…additional <answer> elements…<br />
</question><br />
…additional <question> elements…<br />
</quiz><br />
</pre><br />
The <b>quiz</b> element has an <b>id</b> attribute that is intended to allow a CME interface to distinguish all the quizzes in a document. The value of the <b>id</b> attribute should be unique within the <b>MIRCdocument</b>.<br />
<br />
HTML and MIRC elements are permitted in all the child elements. Numbering of the questions and answers is generated automatically by the display software.<br />
<br />
Within a single <b>quiz</b> element, there is no limit to the number of <b>question</b> elements.<br />
<br />
The RSNA MIRC software ignores the <b>visible</b> attribute of the <b>quiz</b> element and all its children.<br />
====<b>quiz-context</b>====<br />
The optional <b>quiz-context</b> element contains any description required to provide a context for the questions to follow. <br />
====<b>question</b>====<br />
The <b>question</b> element contains the body of a quiz question and its possible answers. <br />
Within a single <b>question</b> element, there is no limit to the number of <b>answer</b> elements.<br />
=====<b>question-body</b>=====<br />
The <b>question-body</b> element contains the content of a quiz question. <br />
=====<b>answer</b>=====<br />
The <b>answer</b> element contains the body of an answer to a quiz question and the response which will be provided if the user selects the answer.<br />
<br />
The <b>answer</b> element may contain a <b>correct</b> attribute indicating whether the answer is correct (<b>yes</b>) or not (<b>no</b>). At least one answer to a question must be identified as being correct. Multiple answers to a single question may be identified as being correct. The default value of the <b>correct</b> attribute is <b>no</b>.<br />
======<b>answer-body</b>======<br />
The <b>answer-body</b> element contains the body of an answer to a quiz question. <br />
======<b>response</b>======<br />
The optional <b>response</b> element contains the response which the browser will display if the user selects the answer.<br />
<br />
===<b>show</b>===<br />
The <b>show</b> element is a special purpose display command for documents in the <b>mstf</b> display mode. It is used within paragraphs in <b>section</b> elements to generate a button that allows the user to display a specific image. The <b>show</b> element has two possible attributes, only one of which may be present in any specific element:<br />
*<b>image=”n”</b> causes the button to display the image corresponding to the <b>src</b> attribute of the n-th <b>image</b> element in the <b>image-section</b>.<br />
*<b>annotation=”n”</b> causes the button to display the image corresponding to the <b>src</b> attribute of the <alternative-image role=”annotation”> child element of the n-th <b>image</b> element in the <b>image-section</b>.<br />
<br />
The <b>show</b> element is ignored in the <b>page</b> and <b>tab</b> display modes.<br />
<br />
The <b>show</b> element contains no text or element children. The proper usage is:<br />
<pre><show image="3"/></pre><br />
or <br />
<pre><show annotation="2"/></pre><br />
<br />
===<b>text</b>===<br />
The <b>text</b> element is an encapsulating element whose contents are rendered as if they were part of the element’s parent element. Its function has been overtaken by the development of the T25 version of the Author Service, but it remains in the schema for backward compatibility.<br />
<br />
===<b>text-caption</b>===<br />
The <b>text-caption</b> element is used to embed a centered caption between groups of content in a <b>section</b> element. The <b>text-caption</b> element has several optional attributes:<br />
*<b>display</b> can have the values <b>always</b> and <b>normal</b>. The default is <b>normal</b>.<br />
*<b>jump-buttons</b> can have the values <b>yes</b> and <b>no</b>. The default is <b>no</b>.<br />
*<b>show-button</b> can have the values <b>yes</b> and <b>no</b>. The default is <b>no</b>.<br />
The rendering of the <b>text-caption</b> element depends on its contents and on the values of the <b>display</b>, <b>jump-buttons</b> and <b>show-button</b> attributes:<br />
*If the <b>text-caption</b> element contains only whitespace text, the entire element is ignored when the MIRCdocument is rendered unless the <b>display</b> attribute is present with the value <b>always</b>, in which case the element is rendered, essentially providing an HTML break in the flow. <br />
*If the <b>text-caption</b> element contains any non-whitespace text, the text contents are displayed. <br />
*If the <b>jump-buttons</b> attribute has the value <b>yes</b>, the rendering software inserts two HTML buttons with the values “<<<” and “>>>”. The buttons allow the user to jump up or down to the previous or next <b>text-caption</b>. <br />
*If the the <b>show-button</b> attribute has the value <b>yes</b> and the text content of the caption is non-whitespace, then the text content of the caption is initially hidden when the document is rendered and an HTML button with the value “Show Caption” is inserted between the “<<<” and “>>>” buttons, allowing the user to reveal the caption after examining the content above it.<br />
Note: The RSNA MIRC software also supports the substitution of images for the buttons described above. The default is to use the button images distributed with the software. The buttons are contained in the storage service's <b>buttons</b> directory and are called:<br />
*back.png<br />
*showcaption.png<br />
*forward.png<br />
===<b>metadata-refs</b>===<br />
The RSNA MIRC implementation calls all files "metadata files". The <b>metadata-refs</b> element encapsulates a list of references to metadata files. The <b>metadata-refs</b> element may appear anywhere within a <b>section</b> element. It is rendered by the RSNA MIRC software as a table, with each of its <b>metadata</b> child elements being one row. The value of each <b>metadata</b> element's <b>href</b> attribute provides a link to the corresponding metadata file. The RSNA MIRC software ignores the visible attribute of the <b>metadata-refs</b> element and all its children.<br />
====<b>metadata</b>====<br />
The <b>metadata</b> element identifies a reference to a single data file. It has one required attribute, <b>href</b>, which provides the URL of the data file. There are three child elements.<br />
=====<b>type</b>=====<br />
The <b>type</b> element identifies the type of the metadata file. MIRC currently defines four classes:<br />
*<b>DicomObject</b>: a DICOM file (image, GSPS, KOS, or SR)<br />
*<b>XmlObject</b>: an XML file of any kind<br />
*<b>ZipObject</b>: a zip file with any contents<br />
*<b>FileObject</b>: any file not meeting the criteria above.<br />
<br />
=====<b>date</b>=====<br />
The <b>date</b> element identifies the date associated with the metadata file. The MIRCdocument generator attempts to get the date from the file, and if it fails, uses the last modified date of the file (typically the date the file was received).<br />
<br />
=====<b>desc</b>=====<br />
The <b>desc</b> element describes the metadata file. The MIRCdocument generator attempts to get the description from the file, and if it fails, inserts the file name.<br />
<br />
==Document Description Elements==<br />
Document description elements are used to describe a document at a high level. They typically appear as children of the <b>MIRCdocument</b> element and are therefore not displayed. However, they may also be placed within <b>section</b> elements if display is desired. With the exception of the <b>rights</b> element, HTML may not be used in these elements.<br />
===<b>phi</b>===<br />
The <b>phi</b> element identifies the protected health information (PHI) that is contained in the document. Absence of the element is interpreted to mean that the document contains no PHI. If the document contains PHI, the <b>phi</b> element contains one or more <b>study</b> child elements, each identifying one patient study referenced in the document. The contents of the PHI element and its children are not rendered by the RSNA MIRC implementation; they are used only to provide access logging information required by HIPAA.<br />
====<b>study</b>====<br />
The <b>study</b> element encapsulates the PHI for one patient study. If the document contains PHI for multiple studies, multiple <b>study</b> elements must be present.<br />
=====<b>si-uid</b>=====<br />
The <b>si-uid</b> element contains the Study Instance UID of the study whose images or patient identifying information are contained in the document.<br />
=====<b>pt-id</b>=====<br />
The <b>pt-id</b> element contains the identifier of the patient corresponding to the study.<br />
=====<b>pt-name</b>=====<br />
The <b>pt-name</b> element contains the name of the patient corresponding to the study.<br />
===<b>document-type</b>===<br />
The optional <b>document-type</b> element identifies the document as one of the following types:<br />
*<b>radiologic teaching file</b>: a teaching file, which may be a single case or a collection of cases in a single MIRCdocument<br />
*<b>radiologic collection</b>: a document containing references to multiple radiologic teaching files; a course; a conference<br />
*<b>research dataset</b>: a MIRCdocument describing and containing a link to a research dataset<br />
*<b>educational document</b>: an educational document, e.g. a presentation or course<br />
*<b>technical document</b>: a technical document<br />
Since the MIRCdocument schema permits the construction of complex documents combining characteristics of all the listed document types, multiple types may be listed within the element.<br />
<br />
===<b>category</b>===<br />
The optional <b>category</b> element identifies the document as belonging to one of the American Board of Radiology categories:<br />
*<b>Musculoskeletal</b><br />
*<b>Pulmonary</b><br />
*<b>Cardiovascular </b><br />
*<b>Gastrointestinal</b><br />
*<b>Genitourinary</b><br />
*<b>Neuro</b><br />
*<b>Vascular and Interventional</b><br />
*<b>Nuclear</b><br />
*<b>Ultrasound</b><br />
*<b>Pediatric</b><br />
*<b>Breast</b><br />
When searching for teaching file documents, a user may request that query results be displayed as unknowns. In this case, if the document does not contain an <b>alternative-title</b> element, the RSNA MIRC Storage Service generates a title in the form "Unknown - <b>category value</b>".<br />
<br />
===<b>level</b>===<br />
The optional <b>level</b> element indicates the degree of difficulty of the document. It is intended to allow teaching files to be graded for difficulty, allowing students to search for teaching files corresponding to their level. The level element contains one of:<br />
*<b>primary</b><br />
*<b>intermediate</b><br />
*<b>advanced</b><br />
===<b>lexicon</b>===<br />
The optional <b>lexicon</b> element identifies the name of the lexicon used in the document. <br />
===<b>access</b>===<br />
The optional <b>access</b> element indicates whether a document is accessible:<br />
*<b>public</b>: accessable by anyone<br />
*<b>restricted</b>: accessible only by certain authenticated users<br />
*<b>owner</b>: accessible only by the owner of the document<br />
This element is automatically generated by the RSNA MIRC site software from the contents of the <b>authorization</b> element.<br />
===<b>authorization</b>===<br />
The optional <b>authorization</b> element controls access to the document for various purposes.<br />
====<b>owner</b>====<br />
The optional <b>owner</b> element defines the owner of the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a comma or whitespace delimited list of usernames to be granted all privileges (read, update, export, delete).<br />
====<b>read</b>====<br />
The optional <b>read</b> element defines the individuals or groups who are authorized to view the the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to read the document. Individual users can be granted the read privilege by including their usernames in the list enclosed in square brackets as in this example:<br />
<pre><read>resident staff [drjones] [drjohnson] technologist</read></pre><br />
If the <b>read</b> element is missing, or if the value of the element contains “*”, all users are granted read access. <br />
====<b>update</b>====<br />
The optional <b>update</b> element defines the individuals or groups who are authorized to modify the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to access the document through the author service and store modifications back on the server. Individual users can be granted the update privilege by including their usernames in the list enclosed in square brackets as in the example above.<br />
<br />
If the <b>update</b> element is missing, updates are not authorized. If the value of the element contains “*”, all users are granted update privileges. <br />
====<b>export</b>====<br />
The optional <b>export</b> element defines the individuals or groups who are authorized to export the document from the server to their browser in the source format. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to export the standard MIRC zip file containing the document’s XML file and all its local references. Individual users can be granted the export privilege by including their usernames in the list enclosed in square brackets as in the example above.<br />
<br />
If the <b>export</b> element is missing, or if the value of the element contains “*”, all users are granted export privileges.<br />
<br />
===<b>peer-review</b>===<br />
The optional <b>peer-review</b> element contains information about the peer-review status of the document. If the <b>peer-review</b> element is missing, the document is assumed not to have been peer-reviewed. If the element is present, it must contain child elements identifying the reviewing authority and the status of the peer-review. If the <peer-review> element is displayed, all its children are displayed.<br />
====<b>approval-date</b>====<br />
The <b>approval-date</b> element represents the date on which the document was approved by the reviewing authority. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
====<b>expiration-date</b>====<br />
The optional <b>expiration-date</b> element represents the date on which the reviewing authority's approval of the document will expire. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
====<b>reviewing-authority</b>====<br />
The <b>reviewing-authority</b> element contains the name of the institution or organization responsible for providing the independent peer review before publication. <br />
====<b>reviewer</b>====<br />
The optional <b>reviewer</b> element contains the name of the reviewer.<br />
<br />
===<b>language</b>===<br />
The optional <b>language</b> element specifies the language in which the document is written.<br />
The <b>language</b> element has a required <b>code</b> attribute specifying the ISO 639:1988(E) two-letter code for the language, as defined as in http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt.<br />
<br />
The following code fragment:<br />
<pre><language code="en">English</language></pre><br />
generates the word "English".<br />
<br />
The RSNA MIRC software does not enforce the correspondence between the value of the <b>code</b> attribute and the value of the element. Query searches on language use the value of the <b>code</b> attribute, so the following fragment will possibly produce unexpected results:<br />
<pre><language code="en">French</language></pre><br />
<br />
===<b>creator</b>===<br />
The optional <b>creator</b> element identifies the application program that was used to create the document.<br />
===<b>document-id</b>===<br />
The optional <b>document-id</b> element is intended to provide a place to store a unique identifier for the document. This element is not yet implemented in the RSNA MIRC software.<br />
<br />
===<b>publication-date</b>===<br />
The optional <b>publication-date</b> element contains the date associated with the document, coded in accordance with ISO 8601 (e.g., yyyy-mm-dd). <br />
===<b>revision-history</b>===<br />
The optional <b>revision-history</b> element encapsulates a set of <b>revision</b> elements, one for each revision of the document. If the <b>revision-history</b> element is displayed, all its children are displayed.<br />
====<b>revision</b>====<br />
The optional <b>revision</b> element encapsulates a set of elements that define the author of the revision, the date, and a description of the revision. When present, it must contain the child elements <b>revision-author</b>, <b>revision-date</b>, and <b>revision-description</b>.<br />
=====<b>revision-author</b>=====<br />
The <b>revision-author</b> element contains the name of the person who authored or revised the document.<br />
=====<b>revision-date</b>=====<br />
The <b>revision-date</b> element contains the release date of the revision. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
=====<b>revision-description</b>=====<br />
The <b>revision-description</b> element contains a description of the changes made in the revision.<br />
<br />
===<b>rights</b>===<br />
The optional <b>rights</b> element can contain any text describing the rights held to the document. HTML may be used to format the presentation of the rights text.<br />
<br />
When the <b>rights</b> element is not contained within a <b>section</b> element, the RSNA MIRC software automatically displays the contents of the <b>rights</b> element at the end of a MIRCdocument. This is the only instance where a document description element is displayed when it is not contained within a document structure element.<br />
<br />
==Template Elements==<br />
The RSNA MIRC implementation uses XML files as templates for the automatic construction of MIRCdocuments by several of the services provided by a Storage Service. These are:<br />
*the Author Service<br />
*the DICOM Service<br />
*the TCE Service<br />
*the Zip Service<br />
Except in the case of the Author Service, the reception of a file by a service triggers either the construction of a new MIRCdocument or the modification of an existing one. Templates are MIRCdocument files, that is, they obey the MIRCdocument schema, extended to include elements that instruct the automatic document construction mechanism how to insert data from a file into the MIRCdocument. Except where noted below, template elements themselves are not displayed when a MIRCdocument is displayed.<br />
<br />
===<b>DICOM Elements</b>===<br />
DICOM elements in a template instruct the MIRCdocument generator to insert the values of DICOM dataset elements of a DICOM object into a MIRCdocument. DICOM elements are of the form <GxxxxEyyyy/>. DICOM elements have no child elements or text values. The group (G) and element (E) identifiers (xxxx and yyyy) are 4-place hexadecimal numbers. Upper case and lower case may be mixed anywhere within the element name. <br />
<br />
DICOM elements have an optional <b>desc</b> attribute which is typically used to indicate the human-readable name of the DICOM element it references. This attribute is not used by the MIRCdocument generator if the element references a DICOM element in the DICOM dictionary. For private elements in the dataset, however, it can provide a label for the data in a table. Generally it is recommended to supply the <b>desc</b> attribute, if only to make the template file more readable. The following are examples of DICOM elements:<br />
<pre><br />
<g0010e0010 desc="Patient Name"/><br />
<G0010E0011 desc="Patient ID"/><br />
<g0011e0030 desc="A Private Element"/><br />
</pre><br />
As a MIRCdocument is created from a template, DICOM elements are removed and replaced by data values from the DICOM object which occasioned the creation of the MIRCdocument in the first place. For this reason, DICOM elements can only be populated from the first DICOM object encountered for the document unless the elements are wrapped in a <b>block</b> element.<br />
===<b>block</b>===<br />
The <b>block</b> element is used to encapsulate template contents that are to be preserved for application to every object that is inserted into the MIRCdocument. The MIRCdocument generator processes the contents of the <b>block</b> element and inserts them immediately before the <b>block</b> element in the MIRCdocument. The <b>block</b> element itself is not rendered when the MIRCdocument is displayed.<br />
<br />
This is an example of a <b>block</b> element being used to create a table of SOP Instance UIDs for the objects inserted into a MIRCdocument in a clinical trial:<br />
<pre><br />
<section heading="SOP Instance UIDs"><br />
<p><br />
<table border="1"><br />
<tr><th>Image Number</th><th>SOP Instance UID</th></tr><br />
<block><br />
<tr><br />
<td><g0020e0013 desc="Instance Number"/></td><br />
<td><g0008e0018 desc="SOP Instance UID"/></td><br />
</tr><br />
</block><br />
</table><br />
</p><br />
</section><br />
</pre><br />
<br />
===<b>insert-image</b>===<br />
The <b>insert-image</b> element appears within a <b>section</b> element and instructs the MIRCdocument generator to insert a reference to an image. It supports the following attributes:<br />
*<b>width</b> specifies the maximum width of the JPEG image to be created. The default value is 700.<br />
*<b>min-width</b> specifies the minimum width of the JPEG image to be created. The default value is 0.<br />
*<b>extra-image-min-size</b> specifies the minimum width of an extra JPEG image to be created but not referenced by the MIRCdocument. If the attribute is not present, or if the image being inserted is not a DICOM image, no extra image is created. <br />
*<b>caption</b> specifies whether a <b>text-caption</b> element is to be generated after the image reference. The value of the <b>caption</b> attribute must be numeric.<br />
*<b>jump-buttons</b> indicates whether the <b>text-caption</b> element is to be generated with a <b>jump-buttons</b> attribute. The possible values of the next-button attribute are <b>yes</b> and <b>no</b>.<br />
*<b>show-button</b> indicates whether the <b>text-caption</b> element is to be generated with a <b>show-button</b> attribute. The possible values of the next-button attribute are <b>yes</b> and <b>no</b>.<br />
<br />
The <b>insert-image</b> element has no child elements or text value.<br />
<br />
===<b>insert-megasave</b>===<br />
The <b>insert-megasave</b> element appears within an <b>image-section</b> element and instructs the MIRCdocument generator to insert a reference to a megasave image group. <br />
<br />
The <b>insert-megasave</b> element supports the <b>width</b> attribute, which specifies the width of the primary JPEG image to be created for initial display of the image. The default value of the <b>width</b> attribute is 700. <br />
<br />
The <b>insert-megasave</b> element has no child elements or text value.<br />
<br />
===<b>insert-dataset</b>===<br />
The <b>insert-dataset</b> element instructs the MIRGdocument generator to create a folder hierarchy within the MIRCdocument’s directory and store a copy of a DICOM image within it. The <b>insert-dataset</b> element appears as a first-generation child of the <b>MIRCdocument</b> element.<br />
<br />
The <b>insert-dataset</b> element supports the <b>phi</b> attribute, which specifies whether the stored DICOM instance is to contain protected healthcare information. The possible values of the phi attribute are <b>yes</b> and <b>no</b>:<br />
<br />
*<b>phi=”yes”</b> creates a folder named <b>phi</b>. Instances are stored unmodified in subdirectories named for the Series Description (if present), the Series Number (if present), or the Series Instance UID. <br />
<br />
*<b>phi=”no”</b> creates a folder named <b>no-phi</b>. Instances are first de-identified using the storage service’s anonymization rules and then stored in subdirectories named as described above.<br />
<br />
When MIRCdocuments containing <b>insert-dataset</b> elements are displayed, links are provided allowing for the export of a zip file containing the requested dataset.<br />
===<b>metadata-refs</b>===<br />
The <b>metadata-refs</b> element instructs the MIRCdocument generator to insert a <b>metadata</b> child element to identify a file referenced by the MIRCdocument. This element and its children are described in the [[#metadata-refs|Special Purpose Elements section]].</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=The_MIRCdocument_Schema&diff=2040The MIRCdocument Schema2006-08-12T01:29:46Z<p>209.242.55.28: /* <b>insert-image</b> */</p>
<hr />
<div>==Introduction==<br />
This article describes the XML schema for indexable documents on sites using the RSNA MIRC software. It is intended for engineers implementing MIRC sites and authoring tools as well as for administrators and MIRCdocument authors who wish to exploit the full capabilities of their sites. The article assumes a basic understanding of XML. For more information on XML, see the [[XML_Primer|XML Primer]].<br />
<br />
The MIRCdocument schema includes all the MIRC-specific elements and attributes that can be included in a document on a MIRC site running the RSNA MIRC software. Where noted below, HTML elements may also be included as well.<br />
<br />
All elements in the schema include a <b>visible</b> attribute that allows the author to instruct a MIRC site's display software whether to render the contents of the element. Except where noted, the default value of the <b>visible</b> attribute is <b>yes</b>. The rendering behavior described inthis article is that provided by the RSNA MIRC software when MIRCdocuments are accessed by a browser (via an HTTP GET). In all cases, if a parent element's <b>visible</b> attribute is <b>no</b>, none of its children are rendered, and if a parent element's <b>visible</b> attribute is <b>yes</b>, only children whose <b>visible</b> attributes are <b>yes</b> are rendered.<br />
<br />
==The <b>MIRCdocument</b> Element==<br />
The <b>MIRCdocument</b> element is the root element of all MIRCdocuments. It encloses all the content of a MIRCdocument:<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
====The <b>docref</b> Attribute====<br />
When a user selects a MIRCdocument for display, the user's browser is directed either to the MIRCdocument itself or to another document. The optional <b>docref</b> attribute provides the link. To understand its use, it is helpful to understand the MIRC search mechanism. <br />
<br />
A user accesses a MIRC Query Service from a web browser. The Query Service provides an HTML form into which the user inserts the search criteria. Upon completion of the form, the browser posts it to the Query Service, which then constructs a query from the form data and posts it to the MIRC Storage Services identified in the form. The query is an XML object in a format defined by the <b>MIRCquery</b> schema. Each Storage Service searches its content for documents matching the search criteria, encodes the list of matching documents in an XML object in a format defined by the <b>MIRCqueryresult</b> schema, and sends the list to the Query Service. In the <b>MIRCqueryresult</b> schema, each document that matches the search criteria is identified by a URL. The Query Service compiles the results from all the Storage Services polled and sends the consolidated results to the user's browser. The consolidated results are constructed as an HTML ordered list, where each item in the list describes one document matching the search criteria and provides a link to the document iself. When the user selects an item in the list, the browser obtains the document identified by the link. In the RSNA MIRC implementation, the <b>docref</b> attribute is used to construct the URL that provides that link. <br />
<br />
Some MIRCdocuments contain a complete document, allowing them to be self-indexing. Other MIRCdocuments serve as indexable documents describing information in other formats. To accommodate these different kinds of MIRCdocuments on sites using the RSNA MIRC software, the docref attribute may be coded in several ways. <br />
*If the <b>docref</b> attribute is not included in the <b>MIRCdocument</b> element, the RSNA MIRC Storage Service provides a link to the file containing the MIRCdocument. This technique is used when the <b>MIRCdocument</b> element contains a complete document. For example, a teaching file case can be constructed as a MIRCdocument and indexed by a Storage Service. When a user selects the document from a list of search results, the link takes the user to the document itself. In this case, the <b>MIRCdocument</b> element is defined without a <b>docref</b> attribute:<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with no path information, the RSNA MIRC Storage Service provides a link to the named document in the same directory on the Storage Service as the MIRCdocument. This technique is used when the MIRCdocument is only a means to index another kind of content. For example, when the actual content of interest is a presentation in PowerPoint format, it can be indexed by creating a short MIRCdocument containing the title, the authors, and an abstract. This MIRCdocument, called an "index card", is only useful during the user's search for the document, so the <b>docref</b> attribute is set to point to the presentation file itself, and the Storage Service stores the presentation file and the index file in the same directory.<br />
<br />
<pre><br />
<MIRCdocument docref="presentationfilename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with path information, the RSNA MIRC Storage Service provides a link to the named document. This technique is a more general example of the previous case. It is used when the actual document of interest is not stored in the same directory on the Storage Service as the MIRCdocument that indexes it. Since authors generally do not control the actual storage locations of their documents, this mechanism is infrequently used, and then only by MIRC administrators.<br />
<br />
This is an example of an index card referencing a presentation stored by a MIRC administrator in a common "presentations" directory under the "MIRCdocuments" directory of the server root:<br />
<br />
<pre><br />
<MIRCdocument docref="/MIRCdocuments/presentations/filename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
*If the <b>docref</b> attribute contains the name of a document with a fully qualified path, the RSNA MIRC Storage Service provides a link to the named document. This technique is a more general example of the previous case. It is used when the actual content of interest is a document not stored on the same Storage Service as the MIRCdocument that indexes it. This mechanism can be used to index the contents of a webserver on a MIRC Storage Service without storing the documents on the Storage Service itself. <br />
<br />
This is an example of an index card referencing a document stored somewhere on the web:<br />
<br />
<pre><br />
<MIRCdocument docref="http://www.somewhere.edu/filename"><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
=====Important Note for MIRC Site Implementers=====<br />
The description in the section above applies to MIRCdocuments stored on MIRC sites using the RSNA MIRC software. It is important not to confuse the flexibility in the use of the <b>docref</b> attribute described here with the inflexible requirement that a Storage Service provide a fully qualified URL for each document in its <b>MIRCqueryresult</b> reply to a Query Service.<br />
<br />
The <b>MIRCqueryresult</b> schema uses the <b>MIRCdocument</b> element to describe each document meeting the search criteria it received in a MIRCquery. A detailed description of the <b>MIRCqueryresult</b> schema is included in a [[The_MIRCquery_and_MIRCqueryresult_Schemas|separate article]]. Briefly, a <b>MIRCqueryresult</b> has the following form:<br />
<br />
<pre><br />
<MIRCqueryresult><br />
<MIRCdocument docref="http://www.somewhere.edu/filename"><br />
…title, author, abstract content…<br />
</MIRCdocument><br />
…additional <MIRCdocument> elements – one for each query match…<br />
</MIRCqueryresult><br />
</pre><br />
<br />
In the <b>MIRCqueryresult</b> schema, each <b>MIRCdocument</b> element is required to provide a fully qualified URL pointing to the document. On sites using the RSNA MIRC software, that URL is generated automatically by the Storage Service as described in the section above for documents with a missing <b>docref</b> attribute or with one that contains a less than fully qualified URL.<br />
<br />
====The <b>display</b> Attribute====<br />
The <b>MIRCdocument</b> element also supports the optional <b>display</b> attribute, which can be used to instruct the MIRC rendering software on how the author intended the document to be displayed. The RSNA MIRC rendering software supports three values of the <b>display</b> attribute:<br />
<br />
*<b>page</b> instructs the rendering software to display the document in a linear, sequential fashion as a normal document would appear. This is the default value.<br />
*<b>tab</b> instructs the rendering software to display the document with each section appearing as a separate tab.<br />
*<b>mstf</b> instructs the rendering software to display the document in a standardized teaching file format oriented toward residents. For compatibility with previous releases, <b>mirctf</b> is a synonym for <b>mstf</b>.<br />
<br />
====The <b>first-tab</b> Attribute====<br />
The <b>first-tab</b> attribute of the <b>MIRCdocument</b> element instructs the rendering software which tab to display first. This attribute is used in the tab and mstf display formats. It is ignored in the page display format. The default value of the first-tab attribute is 2.<br />
<br />
====The <b>show-empty-tabs</b> Attribute====<br />
The <b>show-empty-tabs</b> attribute of the <b>MIRCdocument</b> element instructs the rendering software whether to display sections that have no content. This attribute is used in the tab and mstf display formats. It is ignored in the page display format. The possible values are yes and no. The default value of the show-empty-tabs attribute is no.<br />
<br />
====The <b>background</b> Attribute====<br />
The <b>background</b> attribute of the <b>MIRCdocument</b> element defines the background color of the document when it is displayed. The possible values are <b>light</b> and <b>dark</b>. The default is <b>light</b>.<br />
<br />
====The <b>path</b> Attribute====<br />
The <b>path</b> attribute of the <b>MIRCdocument</b> element is dynamically generated by the RSNA MIRC software when a MIRCdocument is exported from a storage service. It is used to provide third-party, client-side authoring tools the relative path to the document on the server.<br />
<br />
====The <b>as-mode</b> Attribute====<br />
The <b>as-mode</b> attribute of the <b>MIRCdocument</b> element is automatically generated by the Author Service when an author edits the MIRCdocument. It defines whether technical elements are displayed in the editor. Its possible values are <b>true</b> and <b>false</b>.<br />
<br />
====The <b>visible</b> Attribute====<br />
The <b>visible</b> attribute of the <b>MIRCdocument</b> element is ignored by the RSNA MIRC software.<br />
<br />
==Document Structure Elements==<br />
Certain first-generation child elements of the <b>MIRCdocument</b> element are used to provide structure for a document, encapsulating titles, authors, abstracts, keywords, and the various content sections of the document. They are used both to encode key information to be matched against search criteria and to organize the entire document for display.<br />
<br />
The RSNA MIRC software only displays MIRCdocument content which appears within one of these elements. Information included for indexing purposes only can be placed as text value or child elements of the <b>MIRCdocument</b> element or in a <b>section</b> element with the <b>visible</b> attribute set to <b>no</b>.<br />
===<b>title</b>===<br />
The <b>title</b> element contains the title of the document. The <b>title</b> element and the <b>alternative-title</b> element determine the title displayed when the document is rendered or when it appears in a list of search results. See the next section, <b>alternative-title</b>, for details.<br />
HTML should not be embedded in the <b>title</b> element.<br />
<br />
<pre><br />
<MIRCdocument><br />
<title>This is the Title</title><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>title</b> element.<br />
===<b>alternative-title</b>===<br />
The optional <b>alternative-title</b> element provides a title which is used when the document is requested to be displayed as an unknown case. <br />
<br />
HTML should not be embedded in the <b>alternative-title</b> element.<br />
<br />
The RSNA MIRC software ignores the the <b>visible</b> attribute of the <alternative-title> element.<br />
<br />
When the Storage Service receives a query requesting the results as unknowns, it substitutes the contents of the <b>alternative-title</b> element for the <b>title</b> element when constructing the list of query results. If the <b>alternative-title</b> element is missing, the Storage Service generates a title as described in the section on the <b>category</b> element.<br />
<br />
The Storage Service similarly substitutes the contents of the <b>alternative-title</b> element when it is requested to display the document as an unknown.<br />
<br />
===<b>author</b>===<br />
The optional <b>author</b> element contains information for a single author. When a document has multiple authors, multiple <b>author</b> elements are used.<br />
<br />
Within the <b>author</b> element are three optional child elements containing the author's name, affiliation, and contact information.<br />
<br />
HTML should not be embedded in the <b>author</b> element or its children.<br />
<br />
<pre><br />
<MIRCdocument><br />
<title>This is the Title</title><br />
<author><br />
<name>John Author</name><br />
<affiliation>Organization of John Author</affiliation><br />
<contact>Email address of John Author</contact><br />
<contact>Post address of John Author – line 1</contact><br />
<contact>Post address of John Author – line 2</contact><br />
</author><br />
<author><br />
<name>Mary Author</name><br />
<affiliation>Organization of Mary Author</affiliation><br />
<contact>Email address of Mary Author</contact><br />
</author><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the visible attribute of the <b>author</b> element and its children.<br />
<br />
====<b>name</b>====<br />
The <b>name</b> element contains the author's name. No provision is made for identifying the given name, surname, or titles. The value of each <b>name</b> element appears in the search result list.<br />
<br />
====<b>affiliation</b>====<br />
The <b>affiliation</b> element contains one line of the name of an organization with which the author is affiliated. If multiple lines are required, or if the author is affiliated with multiple organizations, multiple <b>affiliation</b> elements are used. No provision is made for separating multiple organizations.<br />
====<b>contact</b>====<br />
The <b>contact</b> element contains one line of information on how to contact the author. If multiple lines are required, multiple <b>contact</b> elements are used. No provision is made for identifying the kind of contact information (phone, email, post, etc.) contained in the element.<br />
===<b>abstract</b>===<br />
The <b>abstract</b> element contains the abstract of the document. The <b>abstract</b> element and the <b>alternative-abstract</b> element determine the abstract displayed when the document is rendered or when it appears in a list of search results. See the next section, <b>alternative-abstract</b>, for details.<br />
<br />
HTML may be used for formatting; in particular, HTML paragraph elements must be used to identify the paragraphs.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<abstract><br />
<p><br />
First <b>paragraph</b> of the abstract.<br />
</p><br />
<p><br />
Second <b>paragraph</b> of the abstract.<br />
</p><br />
</abstract><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b><abstract</b> element.<br />
<br />
===<b>alternative-abstract</b>===<br />
The <b>alternative-abstract</b> element provides an alternative abstract which is used when the document is requested to be displayed as an unknown case.<br />
<br />
HTML may be used for formatting as in the <b>abstract</b> element.<br />
<br />
The RSNA MIRC software ignores the <b>visible</b> attribute of the <b>alternative-abstract</b> element.<br />
<br />
When the Storage Service receives a query requesting the results as unknowns, it substitutes the contents of the <b>alternative-abstract</b> element for the <b>abstract</b> element when constructing the list of query results. If the <b>alternative-abstract</b> element is missing, the Storage Service generates no <b>abstract</b> element.<br />
<br />
For MIRCdocuments with the <b>display</b> attribute set to <b>page</b>, the Storage Service similarly substitutes the contents of the <b>alternative-abstract</b> element when it is requested to display the document as an unknown. (The <b>abstract</b> element is used in MIRCdocuments with the <b>display</b> attribute set to <b>tab</b> or <b>mstf</b>. In these documents, the abstract is included in the first tab and the first tab displayed is typically the second tab, thus concealing the content of the abstract until the user wants to see it.)<br />
<br />
===<b>keywords</b>===<br />
The optional <b>keywords</b> element contains a list of words under which the document should be indexed. Although all words in a document are indexed, the <b>keywords</b> element makes it also possible to query for only those words explicitly identified as keywords.<br />
<br />
HTML should not be embedded in the <b>keywords</b> element.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<keywords>word1 word2 word3</keywords><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>keywords</b> element.<br />
===<b>section</b>===<br />
The optional <b>section</b> element is used to identify separate parts of a MIRCdocument. It contains one attribute, <b>heading</b>, that is used to contain the heading applied to the section when the MIRCdocument is rendered by a browser. The value of the <b>section</b> element is the content of the section. HTML may be used for formatting; in particular, HTML paragraph elements should generally be used to identify paragraphs. (The rendering software can display content not contained in paragraphs, and certain third-party authoring software sometimes creates documents in this way, but the Author Service is more strict than the display software, so it is necessary to use HTML paragraphs if the Author Service is to be used to edit the document.)<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<section heading="Method"><br />
…Method section contents…<br />
</section><br />
<section heading="Results"><br />
…Results section contents…<br />
</section><br />
…more content…<br />
</MIRCdocument><br />
</pre><br />
<br />
MIRCdocuments used as index cards generally do not have <b>section</b> elements since index cards are only displayed as query results. For all other applications of the MIRCdocument schema, however, the <b>section</b> element provides the way for the author to group related parts of the document together. This grouping instructs the RSNA MIRC software on how to handle the parts of the document when it is displayed. For example, in <b>tab</b> display mode, the RSNA MIRC software creates a separate tab for each <b>section</b>, using the <b>heading</b> attribute as the title of the tab.<br />
<br />
===<b>image-section</b>===<br />
The optional <b>image-section</b> element is used to collect groups of related images. The <b>image-section</b> element supports the <b>heading</b> attribute in the <b>page</b> and <b>tab</b> display modes. The <b>heading</b> attribute provides a label for the section containing the images.<br />
<br />
The <b>image-section</b> element supports the <b>image-pane-width</b> attribute, which instructs the RSNA display software how much space to allocate for image display in the right pane in the <b>tab</b> and <b>mstf</b> display modes. The default value of the <b>image-pane-width</b> attribute is 700. The RSNA MIRC software enforces a minimum width of 512.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>image-section</b> element.<br />
<br />
===<b>references</b>===<br />
The optional <b>references</b> element encapsulates a set of <b>reference</b> elements in the MIRCdocument. The RSNA MIRC software generates a separate section entitled "References" when the MIRCdocument is displayed. The software automatically generates an ordered list of the <b>reference</b> child elements.<br />
<br />
<pre><br />
<MIRCdocument><br />
…content…<br />
<references><br />
<reference><br />
…text of the first reference…<br />
</reference><br />
<reference><br />
…text of the second reference…<br />
</reference><br />
…additional references…<br />
</references><br />
…content…<br />
</MIRCdocument><br />
</pre><br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>references</b> element.<br />
====<b>reference</b>====<br />
The <b>reference</b> element is a simple container identifying the enclosed content as a reference to a publication. It has no internal formatting, although this is an area open to extension. Numbering of the <b>reference</b> elements is generated automatically by the <b>references</b> element when the MIRCdocument is rendered. HTML may be embedded in the <b>reference</b> element.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>reference</b> element.<br />
<br />
===<b>rights</b> and <b>publication-date</b>===<br />
If the <b>rights</b> element and/or the <b>publication-date</b> element appear as direct children of the <b>MIRCdocument</b> element, the RSNA MIRC software displays their values at the end of the document. If they appear within a <b>section</b> element, they are displayed as part of the section.<br />
<br />
See the section below for information about the elements and their contents.<br />
<br />
==Special Purpose Elements==<br />
The schema includes many element which identify specific kinds of information. The RSNA MIRC software renders these elements only when they appear within a <b>section</b> element. Each element may appear multiple times in a <b>section</b> element. These elements can also be used to encode non-displayed information for indexing purposes by placing the elements as direct child elements of the <b>MIRCdocument</b> element.<br />
===<b>history</b>===<br />
The optional <b>history</b> element allows content to be identified as a patient history for use in specialized searches.<br />
===<b>findings</b>===<br />
The optional <b>findings</b> element allows content to be identified as the patient's history for use in specialized searches.<br />
===<b>diagnosis</b>===<br />
The optional <b>diagnosis</b> element allows content to be identified as a diagnosis for use in specialized searches. <br />
<br />
The text value of the <b>diagnosis</b> element contains the diagnosis. It may also contain one or more <b>code</b> elements to capture diagnostic coding information. In addition, it may contain a <b>confirmation</b> element to describe how the diagnosis was confirmed.<br />
<pre><br />
<diagnosis><br />
At <confirmation>autopsy</confirmation>, the patient<br />
was determined to have … .<br />
<code coding-system="coding system name">12345.67890</code><br />
</diagnosis><br />
</pre><br />
====<b>confirmation</b>====<br />
The <b>confirmation</b> element describes how a diagnosis was confirmed.<br />
<br />
===<b>differential-diagnosis</b>===<br />
The optional <b>differential-diagnosis</b> element allows all or part of a part of a section to be identified as the differential diagnosis of the current case for use in specialized searches.<br />
===<b>discussion</b>===<br />
The optional <b>discussion</b> element allows all or part of a part of a section to be identified as case discussion for use in specialized searches.<br />
===<b>pathology</b>===<br />
The optional <b>pathology</b> element allows all or part of a part of a section to be identified as pathology relating to the case for use in specialized searches.<br />
===<b>anatomy</b>===<br />
The optional <b>anatomy</b> element allows all or part of a part of a section to be identified as anatomy relating to the case for use in specialized searches.<br />
===<b>organ-system</b>===<br />
The optional <b>organ-system</b> element allows all or part of a part of a section to be identified as anatomy relating to the case for use in specialized searches.<br />
===<b>a</b>===<br />
The <b>a</b> element inserts a hyperlink into a MIRCdocument. The <b>a</b> element is taken directly from HTML, with the addition of the format attribute:<br />
*<b>href</b> contains the address of the document to which the value text is linked.<br />
*<b>format</b> contains a description of the format of the document to be found at <b>href</b>.<br />
<br />
The value text contains the link text that is rendered in the MIRCdocument.<br />
<br />
The <b>format</b> attribute is optional and is not displayed in the MIRCdocument.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>a</b> element and applies instead the <b>visible</b> attribute of its parent.<br />
<br />
Note:<br />
In version 8.0 of the schema, the <b>link</b> element was used as a synonym of the <b>a</b> element, but only the <b>link</b> element had the <b>format</b> attribute. To eliminate any confusion with the HTML <b>link</b> element, subsequent versions deprecate the <b>link</b> element and add the <b>format</b> attribute to the <b>a</b> element. <br />
<br />
===<b>code</b>===<br />
The <b>code</b> element contains information related to a medical code. It has one attribute and value text:<br />
*<b>coding-system</b> contains the name of the code, e.g., CPT.<br />
*the value text contains the code value itself.<br />
The <b>code</b> element can optionally contain a <b>meaning</b> element. <br />
<br />
When rendered by the RSNA MIRC software, the <b>code</b> element is displayed as: <br />
<br />
<center><br />
[<b>coding-system</b> attribute value]:[<b>code</b> element value] ([<b>meaning</b> element value])<br />
</center><br />
<br />
For example, the following element:<br />
<br />
<pre><br />
<code coding-system="MyCode" visible="yes"><br />
12345.67890<br />
</code><br />
</pre><br />
is displayed by the RSNA MIRC software as: MyCode:12345.67890<br />
====<b>meaning</b>====<br />
The <b>meaning</b> element is used to encapsulate the human language meaning of the code value.<br />
For example, the following element:<br />
<pre><br />
<code coding-system="MyCode" visible="yes"><br />
12345.67890<br />
<meaning visible="yes"><br />
normal variant<br />
</meaning><br />
</code><br />
</pre><br />
is displayed by the RSNA MIRC software as: <br />
MyCode:12345.67890 (normal variant)<br />
<br />
===<b>modality</b>===<br />
The optional <b>modality</b> element contains a list of the modalities related to the document. If contained within an <b>image</b> element, it identifies the modality of the image.<br />
<br />
===<b>patient</b>===<br />
The <b>patient</b> element is used to encapsulate elements describing specific parameters of a patient. <br />
<br />
The subsections below describe the child elements unique to the <b>patient</b> element. Here is an example using some of the child elements:<br />
<br />
<pre><br />
<patient><br />
<pt-name>John Doe</pt-name><br />
<pt-id>7654321</pt-id><br />
<pt-mrn>1234567</pt-id><br />
<pt-age><br />
<years>3</years><br />
</pt-age><br />
<pt-sex>male</pt-sex><br />
<pt-race>caucasian</pt-race><br />
</patient><br />
</pre><br />
====<b>pt-name</b>====<br />
The <b>pt-name</b> element may be used to identify a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-id</b>====<br />
The <b>pt-id</b> element may also be used to identify a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-mrn</b>====<br />
The <b>pt-mrn</b> element may be used to identify the medical record number of a patient. It is intended for use in clinical situations where access to the patient's protected health information is restricted by the computer system on which the MIRCdocument resides. It should be omitted in situations where access to the document could compromise the privacy of the patient.<br />
====<b>pt-age</b>====<br />
The <b>pt-age</b> element encapsulates one or more of the following child elements: <br />
*<b>years</b><br />
*<b>months</b><br />
*<b>weeks</b><br />
*<b>days</b><br />
=====<b>years</b>=====<br />
The <b>years</b> element contains the patient age if expressed in years.<br />
=====<b>months</b>=====<br />
The <b>months</b> element contains the patient age if expressed in months.<br />
=====<b>weeks</b>=====<br />
The <b>weeks</b> element contains the patient age if expressed in weeks.<br />
=====<b>days</b>=====<br />
The <b>days</b> element contains the patient age if expressed in days.<br />
====<b>pt-sex</b>====<br />
The <b>pt-sex</b> element contains one of the values male or female (or neutered in veterinary medicine applications).<br />
====<b>pt-race</b>====<br />
The <b>pt-race</b> element contains the name of the race of the patient.<br />
====<b>pt-species</b>====<br />
<b>pt-species</b> element contains the name of the species of the patient. This element is intended for use in veterinary medicine and paleontology.<br />
====<b>pt-breed</b>====<br />
The <b>pt-breed</b> element contains the name of the breed of the patient. This element is intended for use in veterinary medicine.<br />
<br />
===<b>image</b>===<br />
The <b>image</b> element is used to encapsulate an image and related information<br />
Its <b>src</b> attribute contains the URL of the image to be displayed.<br />
<br />
The <b>image</b> element also has the <b>width</b> and <b>height</b> attributes of the HTML <b>img</b> element. These are passed to the browser to set the displayed width and height of the image; they do not refer to the actual size of the image in the file on the server.<br />
<br />
The value of an <b>image</b> element may be empty or it one or more <b>alternative-image</b> elements, and optionally <b>patient</b>, <b>diagnosis</b>, <b>anatomy</b>, <b>pathology</b>, and <b>code</b> elements to associate the parameters of the patient and/or the diagnosis with the image. It may also contain the <b>modality</b>, <b>format</b> and <b>compression</b> elements to encode parameters of the image itself.<br />
<br />
The RSNA MIRC software ignores the value of the <b>visible</b> attribute of the <b>image</b> element and applies instead the <b>visible</b> attribute of its parent.<br />
<br />
The following example shows the use of an <b>image</b> element to include a JPEG image directly in the rendered document.<br />
<pre><br />
<image src="http://www.abc.edu/images/image1.jpeg"><br />
<format>jpeg</format><br />
</image><br />
</pre><br />
The image appears in sequence with the rest of the text value of the element in which the <b>image</b> element is contained.<br />
<br />
The following more complex coding of the previous example shows the use of multiple child elements within an <b>image</b> element.<br />
<pre><br />
<a href="http://www.abc.edu/images/image1.dcm"><br />
<image src="http://www.abc.edu/images/image1.jpeg"><br />
<format visible=”no”>DICOM</format><br />
<compression visible=”no”>original</compression><br />
<modality visible=”no”>CT</modality><br />
<anatomy visible=”no”>abdomen</anatomy><br />
<pathology visible=”no”>renal carcinoma</pathology><br />
<patient visible=”no”><br />
<pt-age><br />
<years>86</years><br />
</pt-age><br />
<pt-sex>male</pt-sex><br />
</patient><br />
<diagnosis visible=”no”><br />
renal carcinoma<br />
<confirmation>pathology</confirmation><br />
<code coding-system="ABC Code">1234.5678</code><br />
</diagnosis><br />
</image><br />
</a><br />
</pre><br />
The RSNA MIRC implementation often groups related images together within an <b>image</b> element which appears in an <b>image-section</b>. Such groups are sometimes called "megasave groups". The following example shows a megasave group for an image.<br />
<pre><br />
<image src="IMG_1719.jpg" width="374"><br />
<alternative-image role="icon" src="IMG_1719_icon"/><br />
<alternative-image role="annotation" src="IMG_1719_an.svg" type="svg"/><br />
<alternative-image role="annotation" src="IMG_1719_an.jpg" type="image"/><br />
<alternative-image role="original-dimensions" src="IMG_1719_orig.jpg"/><br />
<alternative-image role="original-format" src="IMG_1719.dcm"/><br />
</image><br />
</pre><br />
In this group, the <b>alternative-image</b> children are different versions of the original image (in this case, <b>IMG_1719.dcm</b>) for various purposes. As in the preceding example, other child elements could have been included to provide additional information about the group.<br />
====<b>format</b>====<br />
The <b>format</b> element is used to identify the storage format of an image.<br />
The <b>format</b> element has the enumerated values:<br />
*<b>DICOM</b><br />
*<b>JPEG</b><br />
*<b>PNG</b><br />
*<b>GIF</b><br />
*<b>TIFF</b><br />
====<b>compression</b>====<br />
The <b>compression</b> element is used to identify the compression history of an image.<br />
The <b>compression</b> element has four enumerated values:<br />
*<b>original</b><br />
*<b>reversible</b><br />
*<b>non-reversible</b><br />
*<b>unknown</b><br />
A value at any level in the list above implies that the compression history of the image does not include a version at a lower level. Thus, a value of <b>reversible</b> implies that the image in question is not simply a reversibly compressed version of an image that was non-reversibly compressed.<br />
====<b>alternative-image</b>====<br />
The <b>alternative-image</b> element identifies a version of the parent <b>image</b> element intended to be used for a specific purpose. The <b>alternative-image</b> element has two required attributes.<br />
*<b>src</b> contains the URL of the <b>alternative-image</b>.<br />
*<b>role</b> identifies the purpose of the <b>alternative-image</b>. <br />
The <b>role</b> attribute has four enumerated values:<br />
*<b>icon</b> identifies the <b>alternative-image</b> as a small image intended for use as an icon link to the parent image.<br />
*<b>annotation</b> identifies the <b>alternative-image</b> as annotations for the parent image.<br />
*<b>original-dimensions</b> identifies the <b>alternative-image</b> as a version of the parent image having the same dimensions as the original-format image.<br />
*<b>original-format</b> identifies the <b>alternative-image</b> as the original image acquired by the modality (except for changes required for anonymization).<br />
The <b>alternative-image</b> element with <b>role=”annotation”</b> has one additional attribute, <b>type</b>, that describes the format of the annotation data. The type attribute has two enumerated values:<br />
*<b>image</b> (the default) identifies the annotation data as an image that is to replace the primary image when annotations are displayed.<br />
*<b>svg</b> identifies the annotation data as scalar vector graphics instructions for displaying the annotations overlaid on the primary image when annotations are to be displayed.<br />
The <b>alternative-image</b> element may optionally contain the <b>width</b> and <b>height</b> attributes of the HTML <b>img</b> element. <br />
The <b>alternative-image</b> element is always a child of a <b>image</b> element, and its <b>visible</b> attribute and those of all its children are ignored. <br />
The <b>alternative-image</b> element may also contain <b>format</b> and <b>compression</b> child elements.<br />
<br />
===<b>quiz</b>===<br />
The <b>quiz</b> element is used to contain a quiz that is displayed within a <b>section</b> element in the MIRCdocument. Multiple <b>quiz</b> elements may appear within one <b>section</b> element. Multiple <b>section</b> elements may contain <b>quiz</b> elements.<br />
A quiz has the following structure:<br />
<br />
<pre><br />
<quiz id="…"><br />
<quiz-context><br />
…content defining the context of the quiz…<br />
</quiz-context><br />
<question><br />
<question-body><br />
…content defining the question…<br />
</question-body><br />
<answer correct="yes|no"><br />
<answer-body><br />
…content shown to the user as a possible selection…<br />
</answer-body><br />
<response><br />
…content shown to the user if the answer is selected…<br />
</response><br />
</answer><br />
…additional <answer> elements…<br />
</question><br />
…additional <question> elements…<br />
</quiz><br />
</pre><br />
The <b>quiz</b> element has an <b>id</b> attribute that is intended to allow a CME interface to distinguish all the quizzes in a document. The value of the <b>id</b> attribute should be unique within the <b>MIRCdocument</b>.<br />
<br />
HTML and MIRC elements are permitted in all the child elements. Numbering of the questions and answers is generated automatically by the display software.<br />
<br />
Within a single <b>quiz</b> element, there is no limit to the number of <b>question</b> elements.<br />
<br />
The RSNA MIRC software ignores the <b>visible</b> attribute of the <b>quiz</b> element and all its children.<br />
====<b>quiz-context</b>====<br />
The optional <b>quiz-context</b> element contains any description required to provide a context for the questions to follow. <br />
====<b>question</b>====<br />
The <b>question</b> element contains the body of a quiz question and its possible answers. <br />
Within a single <b>question</b> element, there is no limit to the number of <b>answer</b> elements.<br />
=====<b>question-body</b>=====<br />
The <b>question-body</b> element contains the content of a quiz question. <br />
=====<b>answer</b>=====<br />
The <b>answer</b> element contains the body of an answer to a quiz question and the response which will be provided if the user selects the answer.<br />
<br />
The <b>answer</b> element may contain a <b>correct</b> attribute indicating whether the answer is correct (<b>yes</b>) or not (<b>no</b>). At least one answer to a question must be identified as being correct. Multiple answers to a single question may be identified as being correct. The default value of the <b>correct</b> attribute is <b>no</b>.<br />
======<b>answer-body</b>======<br />
The <b>answer-body</b> element contains the body of an answer to a quiz question. <br />
======<b>response</b>======<br />
The optional <b>response</b> element contains the response which the browser will display if the user selects the answer.<br />
<br />
===<b>show</b>===<br />
The <b>show</b> element is a special purpose display command for documents in the <b>mstf</b> display mode. It is used within paragraphs in <b>section</b> elements to generate a button that allows the user to display a specific image. The <b>show</b> element has two possible attributes, only one of which may be present in any specific element:<br />
*<b>image=”n”</b> causes the button to display the image corresponding to the <b>src</b> attribute of the n-th <b>image</b> element in the <b>image-section</b>.<br />
*<b>annotation=”n”</b> causes the button to display the image corresponding to the <b>src</b> attribute of the <alternative-image role=”annotation”> child element of the n-th <b>image</b> element in the <b>image-section</b>.<br />
<br />
The <b>show</b> element is ignored in the <b>page</b> and <b>tab</b> display modes.<br />
<br />
The <b>show</b> element contains no text or element children. The proper usage is:<br />
<pre><show image="3"/></pre><br />
or <br />
<pre><show annotation="2"/></pre><br />
<br />
===<b>text</b>===<br />
The <b>text</b> element is an encapsulating element whose contents are rendered as if they were part of the element’s parent element. Its function has been overtaken by the development of the T25 version of the Author Service, but it remains in the schema for backward compatibility.<br />
<br />
===<b>text-caption</b>===<br />
The <b>text-caption</b> element is used to embed a centered caption between groups of content in a <b>section</b> element. The <b>text-caption</b> element has several optional attributes:<br />
*<b>display</b> can have the values <b>always</b> and <b>normal</b>. The default is <b>normal</b>.<br />
*<b>jump-buttons</b> can have the values <b>yes</b> and <b>no</b>. The default is <b>no</b>.<br />
*<b>show-button</b> can have the values <b>yes</b> and <b>no</b>. The default is <b>no</b>.<br />
The rendering of the <b>text-caption</b> element depends on its contents and on the values of the <b>display</b>, <b>jump-buttons</b> and <b>show-button</b> attributes:<br />
*If the <b>text-caption</b> element contains only whitespace text, the entire element is ignored when the MIRCdocument is rendered unless the <b>display</b> attribute is present with the value <b>always</b>, in which case the element is rendered, essentially providing an HTML break in the flow. <br />
*If the <b>text-caption</b> element contains any non-whitespace text, the text contents are displayed. <br />
*If the <b>jump-buttons</b> attribute has the value <b>yes</b>, the rendering software inserts two HTML buttons with the values “<<<” and “>>>”. The buttons allow the user to jump up or down to the previous or next <b>text-caption</b>. <br />
*If the the <b>show-button</b> attribute has the value <b>yes</b> and the text content of the caption is non-whitespace, then the text content of the caption is initially hidden when the document is rendered and an HTML button with the value “Show Caption” is inserted between the “<<<” and “>>>” buttons, allowing the user to reveal the caption after examining the content above it.<br />
Note: The RSNA MIRC software also supports the substitution of images for the buttons described above. The default is to use the button images distributed with the software. The buttons are contained in the storage service's <b>buttons</b> directory and are called:<br />
*back.png<br />
*showcaption.png<br />
*forward.png<br />
===<b>metadata-refs</b>===<br />
The RSNA MIRC implementation calls all files "metadata files". The <b>metadata-refs</b> element encapsulates a list of references to metadata files. The <b>metadata-refs</b> element may appear anywhere within a <b>section</b> element. It is rendered by the RSNA MIRC software as a table, with each of its <b>metadata</b> child elements being one row. The value of each <b>metadata</b> element's <b>href</b> attribute provides a link to the corresponding metadata file. The RSNA MIRC software ignores the visible attribute of the <b>metadata-refs</b> element and all its children.<br />
====<b>metadata</b>====<br />
The <b>metadata</b> element identifies a reference to a single data file. It has one required attribute, <b>href</b>, which provides the URL of the data file. There are three child elements.<br />
=====<b>type</b>=====<br />
The <b>type</b> element identifies the type of the metadata file. MIRC currently defines four classes:<br />
*<b>DicomObject</b>: a DICOM file (image, GSPS, KOS, or SR)<br />
*<b>XmlObject</b>: an XML file of any kind<br />
*<b>ZipObject</b>: a zip file with any contents<br />
*<b>FileObject</b>: any file not meeting the criteria above.<br />
<br />
=====<b>date</b>=====<br />
The <b>date</b> element identifies the date associated with the metadata file. The MIRCdocument generator attempts to get the date from the file, and if it fails, uses the last modified date of the file (typically the date the file was received).<br />
<br />
=====<b>desc</b>=====<br />
The <b>desc</b> element describes the metadata file. The MIRCdocument generator attempts to get the description from the file, and if it fails, inserts the file name.<br />
<br />
==Document Description Elements==<br />
Document description elements are used to describe a document at a high level. They typically appear as children of the <b>MIRCdocument</b> element and are therefore not displayed. However, they may also be placed within <b>section</b> elements if display is desired. With the exception of the <b>rights</b> element, HTML may not be used in these elements.<br />
===<b>phi</b>===<br />
The <b>phi</b> element identifies the protected health information (PHI) that is contained in the document. Absence of the element is interpreted to mean that the document contains no PHI. If the document contains PHI, the <b>phi</b> element contains one or more <b>study</b> child elements, each identifying one patient study referenced in the document. The contents of the PHI element and its children are not rendered by the RSNA MIRC implementation; they are used only to provide access logging information required by HIPAA.<br />
====<b>study</b>====<br />
The <b>study</b> element encapsulates the PHI for one patient study. If the document contains PHI for multiple studies, multiple <b>study</b> elements must be present.<br />
=====<b>si-uid</b>=====<br />
The <b>si-uid</b> element contains the Study Instance UID of the study whose images or patient identifying information are contained in the document.<br />
=====<b>pt-id</b>=====<br />
The <b>pt-id</b> element contains the identifier of the patient corresponding to the study.<br />
=====<b>pt-name</b>=====<br />
The <b>pt-name</b> element contains the name of the patient corresponding to the study.<br />
===<b>document-type</b>===<br />
The optional <b>document-type</b> element identifies the document as one of the following types:<br />
*<b>radiologic teaching file</b>: a teaching file, which may be a single case or a collection of cases in a single MIRCdocument<br />
*<b>radiologic collection</b>: a document containing references to multiple radiologic teaching files; a course; a conference<br />
*<b>research dataset</b>: a MIRCdocument describing and containing a link to a research dataset<br />
*<b>educational document</b>: an educational document, e.g. a presentation or course<br />
*<b>technical document</b>: a technical document<br />
Since the MIRCdocument schema permits the construction of complex documents combining characteristics of all the listed document types, multiple types may be listed within the element.<br />
<br />
===<b>category</b>===<br />
The optional <b>category</b> element identifies the document as belonging to one of the American Board of Radiology categories:<br />
*<b>Musculoskeletal</b><br />
*<b>Pulmonary</b><br />
*<b>Cardiovascular </b><br />
*<b>Gastrointestinal</b><br />
*<b>Genitourinary</b><br />
*<b>Neuro</b><br />
*<b>Vascular and Interventional</b><br />
*<b>Nuclear</b><br />
*<b>Ultrasound</b><br />
*<b>Pediatric</b><br />
*<b>Breast</b><br />
When searching for teaching file documents, a user may request that query results be displayed as unknowns. In this case, if the document does not contain an <b>alternative-title</b> element, the RSNA MIRC Storage Service generates a title in the form "Unknown - <b>category value</b>".<br />
<br />
===<b>level</b>===<br />
The optional <b>level</b> element indicates the degree of difficulty of the document. It is intended to allow teaching files to be graded for difficulty, allowing students to search for teaching files corresponding to their level. The level element contains one of:<br />
*<b>primary</b><br />
*<b>intermediate</b><br />
*<b>advanced</b><br />
===<b>lexicon</b>===<br />
The optional <b>lexicon</b> element identifies the name of the lexicon used in the document. <br />
===<b>access</b>===<br />
The optional <b>access</b> element indicates whether a document is accessible:<br />
*<b>public</b>: accessable by anyone<br />
*<b>restricted</b>: accessible only by certain authenticated users<br />
*<b>owner</b>: accessible only by the owner of the document<br />
This element is automatically generated by the RSNA MIRC site software from the contents of the <b>authorization</b> element.<br />
===<b>authorization</b>===<br />
The optional <b>authorization</b> element controls access to the document for various purposes.<br />
====<b>owner</b>====<br />
The optional <b>owner</b> element defines the owner of the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a comma or whitespace delimited list of usernames to be granted all privileges (read, update, export, delete).<br />
====<b>read</b>====<br />
The optional <b>read</b> element defines the individuals or groups who are authorized to view the the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to read the document. Individual users can be granted the read privilege by including their usernames in the list enclosed in square brackets as in this example:<br />
<pre><read>resident staff [drjones] [drjohnson] technologist</read></pre><br />
If the <b>read</b> element is missing, or if the value of the element contains “*”, all users are granted read access. <br />
====<b>update</b>====<br />
The optional <b>update</b> element defines the individuals or groups who are authorized to modify the document. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to access the document through the author service and store modifications back on the server. Individual users can be granted the update privilege by including their usernames in the list enclosed in square brackets as in the example above.<br />
<br />
If the <b>update</b> element is missing, updates are not authorized. If the value of the element contains “*”, all users are granted update privileges. <br />
====<b>export</b>====<br />
The optional <b>export</b> element defines the individuals or groups who are authorized to export the document from the server to their browser in the source format. The value of the element is specific to the server hosting the document. The RSNA MIRC software uses the element to contain a list of usernames and roles that are authorized to export the standard MIRC zip file containing the document’s XML file and all its local references. Individual users can be granted the export privilege by including their usernames in the list enclosed in square brackets as in the example above.<br />
<br />
If the <b>export</b> element is missing, or if the value of the element contains “*”, all users are granted export privileges.<br />
<br />
===<b>peer-review</b>===<br />
The optional <b>peer-review</b> element contains information about the peer-review status of the document. If the <b>peer-review</b> element is missing, the document is assumed not to have been peer-reviewed. If the element is present, it must contain child elements identifying the reviewing authority and the status of the peer-review. If the <peer-review> element is displayed, all its children are displayed.<br />
====<b>approval-date</b>====<br />
The <b>approval-date</b> element represents the date on which the document was approved by the reviewing authority. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
====<b>expiration-date</b>====<br />
The optional <b>expiration-date</b> element represents the date on which the reviewing authority's approval of the document will expire. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
====<b>reviewing-authority</b>====<br />
The <b>reviewing-authority</b> element contains the name of the institution or organization responsible for providing the independent peer review before publication. <br />
====<b>reviewer</b>====<br />
The optional <b>reviewer</b> element contains the name of the reviewer.<br />
<br />
===<b>language</b>===<br />
The optional <b>language</b> element specifies the language in which the document is written.<br />
The <b>language</b> element has a required <b>code</b> attribute specifying the ISO 639:1988(E) two-letter code for the language, as defined as in http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt.<br />
<br />
The following code fragment:<br />
<pre><language code="en">English</language></pre><br />
generates the word "English".<br />
<br />
The RSNA MIRC software does not enforce the correspondence between the value of the <b>code</b> attribute and the value of the element. Query searches on language use the value of the <b>code</b> attribute, so the following fragment will possibly produce unexpected results:<br />
<pre><language code="en">French</language></pre><br />
<br />
===<b>creator</b>===<br />
The optional <b>creator</b> element identifies the application program that was used to create the document.<br />
===<b>document-id</b>===<br />
The optional <b>document-id</b> element is intended to provide a place to store a unique identifier for the document. This element is not yet implemented in the RSNA MIRC software.<br />
<br />
===<b>publication-date</b>===<br />
The optional <b>publication-date</b> element contains the date associated with the document, coded in accordance with ISO 8601 (e.g., yyyy-mm-dd). <br />
===<b>revision-history</b>===<br />
The optional <b>revision-history</b> element encapsulates a set of <b>revision</b> elements, one for each revision of the document. If the <b>revision-history</b> element is displayed, all its children are displayed.<br />
====<b>revision</b>====<br />
The optional <b>revision</b> element encapsulates a set of elements that define the author of the revision, the date, and a description of the revision. When present, it must contain the child elements <b>revision-author</b>, <b>revision-date</b>, and <b>revision-description</b>.<br />
=====<b>revision-author</b>=====<br />
The <b>revision-author</b> element contains the name of the person who authored or revised the document.<br />
=====<b>revision-date</b>=====<br />
The <b>revision-date</b> element contains the release date of the revision. The date must be coded in accordance with ISO 8601 (e.g., yyyy-mm-dd).<br />
=====<b>revision-description</b>=====<br />
The <b>revision-description</b> element contains a description of the changes made in the revision.<br />
<br />
===<b>rights</b>===<br />
The optional <b>rights</b> element can contain any text describing the rights held to the document. HTML may be used to format the presentation of the rights text.<br />
<br />
When the <b>rights</b> element is not contained within a <b>section</b> element, the RSNA MIRC software automatically displays the contents of the <b>rights</b> element at the end of a MIRCdocument. This is the only instance where a document description element is displayed when it is not contained within a document structure element.<br />
<br />
==Template Elements==<br />
The RSNA MIRC implementation uses XML files as templates for the automatic construction of MIRCdocuments by several of the services provided by a Storage Service. These are:<br />
*the Author Service<br />
*the DICOM Service<br />
*the TCE Service<br />
*the Zip Service<br />
Except in the case of the Author Service, the reception of a file by a service triggers either the construction of a new MIRCdocument or the modification of an existing one. Templates are MIRCdocument files, that is, they obey the MIRCdocument schema, extended to include elements that instruct the automatic document construction mechanism how to insert data from a file into the MIRCdocument. Except where noted below, template elements themselves are not displayed when a MIRCdocument is displayed.<br />
<br />
===<b>DICOM Elements</b>===<br />
DICOM elements in a template instruct the MIRCdocument generator to insert the values of DICOM dataset elements of a DICOM object into a MIRCdocument. DICOM elements are of the form <GxxxxEyyyy/>. DICOM elements have no child elements or text values. The group (G) and element (E) identifiers (xxxx and yyyy) are 4-place hexadecimal numbers. Upper case and lower case may be mixed anywhere within the element name. <br />
<br />
DICOM elements have an optional <b>desc</b> attribute which is typically used to indicate the human-readable name of the DICOM element it references. This attribute is not used by the MIRCdocument generator if the element references a DICOM element in the DICOM dictionary. For private elements in the dataset, however, it can provide a label for the data in a table. Generally it is recommended to supply the <b>desc</b> attribute, if only to make the template file more readable. The following are examples of DICOM elements:<br />
<pre><br />
<g0010e0010 desc="Patient Name"/><br />
<G0010E0011 desc="Patient ID"/><br />
<g0011e0030 desc="A Private Element"/><br />
</pre><br />
As a MIRCdocument is created from a template, DICOM elements are removed and replaced by data values from the DICOM object which occasioned the creation of the MIRCdocument in the first place. For this reason, DICOM elements can only be populated from the first DICOM object encountered for the document unless the elements are wrapped in a <b>block</b> element.<br />
===<b>block</b>===<br />
The <b>block</b> element is used to encapsulate template contents that are to be preserved for application to every object that is inserted into the MIRCdocument. The MIRCdocument generator processes the contents of the <b>block</b> element and inserts them immediately before the <b>block</b> element in the MIRCdocument. The <b>block</b> element itself is not rendered when the MIRCdocument is displayed.<br />
<br />
This is an example of a <b>block</b> element being used to create a table of SOP Instance UIDs for the objects inserted into a MIRCdocument in a clinical trial:<br />
<pre><br />
<section heading="SOP Instance UIDs"><br />
<p><br />
<table border="1"><br />
<tr><th>Image Number</th><th>SOP Instance UID</th></tr><br />
<block><br />
<tr><br />
<td><g0020e0013 desc="Instance Number"/></td><br />
<td><g0008e0018 desc="SOP Instance UID"/></td><br />
</tr><br />
</block><br />
</table><br />
</p><br />
</section><br />
</pre><br />
<br />
===<b>insert-image</b>===<br />
The <b>insert-image</b> element appears within a <b>section</b> element and instructs the MIRCdocument generator to insert a reference to an image. It supports the following attributes:<br />
*<b>width</b> specifies the maximum width of the JPEG image to be created. The default value is 700.<br />
*<b>min-width</b> specifies the minimum width of the JPEG image to be created. The default value is 0.<br />
*<b>extra-image-min-size</b> specifies the minimum width of an extra JPEG image to be created but not referenced by the MIRCdocument. If the attribute is not present, no extra image is created. This capability is specifically designed for the NCI's CaImage project.<br />
*<b>caption</b> specifies whether a <b>text-caption</b> element is to be generated after the image reference. The value of the <b>caption</b> attribute must be numeric.<br />
*<b>jump-buttons</b> indicates whether the <b>text-caption</b> element is to be generated with a <b>jump-buttons</b> attribute. The possible values of the next-button attribute are <b>yes</b> and <b>no</b>.<br />
*<b>show-button</b> indicates whether the <b>text-caption</b> element is to be generated with a <b>show-button</b> attribute. The possible values of the next-button attribute are <b>yes</b> and <b>no</b>.<br />
<br />
The <b>insert-image</b> element has no child elements or text value.<br />
<br />
===<b>insert-megasave</b>===<br />
The <b>insert-megasave</b> element appears within an <b>image-section</b> element and instructs the MIRCdocument generator to insert a reference to a megasave image group. <br />
<br />
The <b>insert-megasave</b> element supports the <b>width</b> attribute, which specifies the width of the primary JPEG image to be created for initial display of the image. The default value of the <b>width</b> attribute is 700. <br />
<br />
The <b>insert-megasave</b> element has no child elements or text value.<br />
<br />
===<b>insert-dataset</b>===<br />
The <b>insert-dataset</b> element instructs the MIRGdocument generator to create a folder hierarchy within the MIRCdocument’s directory and store a copy of a DICOM image within it. The <b>insert-dataset</b> element appears as a first-generation child of the <b>MIRCdocument</b> element.<br />
<br />
The <b>insert-dataset</b> element supports the <b>phi</b> attribute, which specifies whether the stored DICOM instance is to contain protected healthcare information. The possible values of the phi attribute are <b>yes</b> and <b>no</b>:<br />
<br />
*<b>phi=”yes”</b> creates a folder named <b>phi</b>. Instances are stored unmodified in subdirectories named for the Series Description (if present), the Series Number (if present), or the Series Instance UID. <br />
<br />
*<b>phi=”no”</b> creates a folder named <b>no-phi</b>. Instances are first de-identified using the storage service’s anonymization rules and then stored in subdirectories named as described above.<br />
<br />
When MIRCdocuments containing <b>insert-dataset</b> elements are displayed, links are provided allowing for the export of a zip file containing the requested dataset.<br />
===<b>metadata-refs</b>===<br />
The <b>metadata-refs</b> element instructs the MIRCdocument generator to insert a <b>metadata</b> child element to identify a file referenced by the MIRCdocument. This element and its children are described in the [[#metadata-refs|Special Purpose Elements section]].</div>209.242.55.28http://mircwiki.rsna.org/index.php?title=Implementing_an_External_Database_Interface_for_MIRC_Clinical_Trials&diff=1876Implementing an External Database Interface for MIRC Clinical Trials2006-07-26T16:20:43Z<p>209.242.55.28: /* The Database Export Service */</p>
<hr />
<div>The article is intended for software developers interfacing their MIRC sites to specialized databases for clinical trials. The reader is expected to be familiar with Java and with [[The_RSNA_MIRC_Source_Code|the RSNA MIRC Source Code]].<br />
<br />
===The Database Export Service===<br />
The Database Export Service is a component of a MIRC Storage Service. It provides a queuing mechanism for submitting files to a database interface, relieving the interface from having to manage the queue. It attempts to parse each file to determine its type and calls the overloaded <b>process</b> method of the interface with one of four objects, encapsulating an XML file, a zip file, a DICOM file, or a file of unparsable contents. Each of the objects includes methods providing access to the internals of the file, allowing the interface to interrogate the files to obtain some or all of their data to insert into an external system.<br />
<br />
The Database Export Service dynamically loads the database interface class, obtaining the name of the class from the Storage Service’s <b>trial/trial.xml</b> configuration file. This file is typically configured by the trial administrator through the Admin Service.<br />
<br />
To fully understand this article, you may wish to reference [[The RSNA MIRC Source Code]].<br />
<br />
===The Object Classes===<br />
As noted above, MIRC provides four classes to encapsulate files of various types. The classes are all in the <b>org.rsna.mircsite.util</b> package.<br />
====FileObject====<br />
The FileObject class encapsulates a file of unknown contents. It is the parent class of the other three classes and provides a method for obtaining a java.io.File object pointing to the file, as well as methods for moving, renaming, and copying the file. It also provides dummy methods for obtaining key information about the file. These methods are overridden by subclasses that can parse their corresponding file types to obtain meaningful values. The FileObject class also includes a factory method, <b>getObject(java.io.File)</b>, which parses a file and returns an instance of the matching FileObject subclass or, if no subclass matches the file, a FileObject itself.<br />
<br />
====XmlObject====<br />
The XmlObject class encapsulates an XML file, parsing the XML in the constructor and throwing an Exception if the file does not parse. In addition to the methods of the FileObject, it provides methods for accessing the XML DOM object and reading its elements and attributes. For many purposes, the <b>getValue(String path)</b> method makes it easy to obtain the necessary data to insert into a database, but if necessary, you can use the entire XML DOM.<br />
<br />
The Javadocs explain how specific types of data (the <b>uid</b>, the <b>study-uid</b>, the file <b>description</b>) are obtained from the XML DOM object. When designing XML metadata files for a clinical trial, if you put the data in those places, MIRC will be able to manage the files and pass them to your database interface more efficiently.<br />
====ZipObject====<br />
The ZipObject class encapsulates a zip file, parsing the file in the constuctor and throwing an Exception if the file does not parse. In addition to the methods of the FileObject, it provides methods for accessing the individual files within the zip file. It also provides methods for accessing the contents of a special file, <b>manifest.xml</b>, that contains data necessary to identify the zip file and relate it to other clinical trial data.<br />
<br />
The ZipObject allows a clinical trial to collect a group of related objects, for example multiple output files from an analytical program for a single analysis, and to manage them as a single object.<br />
<br />
The Javadocs explain how identifying data are obtained from the <b>manifest.xml</b> file. The ZipObject is much less flexible than the XmlObject in the placement of identifying data. When designing zip metadata files for a clinical trial, you should try to construct manifests exactly by the rules described in the Javadocs.<br />
====DicomObject====<br />
The DicomObject class encapsulates a DICOM dataset, parsing the file in the constructor and throwing an Exception if the file does not parse. In addition to the methods of the FileObject, it provides access to all the DICOM attributes, as well as image conversion methods returning JPEG images of any size from the DICOM image.<br />
<br />
===The DatabaseAdapter Class===<br />
The DatabaseAdapter class, <b>org.rsna.mircsite.util.DatabaseAdapter</b>, is a base class for building an interface between the Database Export Service and an external database. To be recognized and loaded by the Database Export Service, an external database interface class must be an extension of DatabaseAdapter.<br />
<br />
The DatabaseAdapter class provides a set of methods allowing the Database Export Service to perform various functions, all of which are explained in the Javadocs. The basic interaction model is:<br />
*When the Database Export Service detects that files are in its queue, it verifies that the database interface class is loaded and loads it if it is not.<br />
*It then calls the database interface’s <b>connect()</b> method.<br />
*For each file in the queue, it instantiates an object matching the file’s contents and calls the database interface’s <b>process()</b> method. There are four overloaded process methods, one for each object class. The <b>process()</b> methods have two arguments: the metadata object and the URL of the MIRCdocument which references the file.<br />
*When the queue is empty, it calls the database interface’s <b>disconnect()</b> method.<br />
*If the Database Export Service is restarted after the database interface has been instantiated, it calls the interface’s <b>reset()</b> method.<br />
*When the Database Export Service is completely finished with an instance of the database interface and is about to discard the instance before either exiting or instantiating a new instance of the interface, it calls the interface’s <b>shutdown()</b> method.<br />
<br />
All the methods of the DatabaseAdapter class return an integer status value. Static values for the statuses are defined in the class. There are three values:<br />
*<b>STATUS_OK</b> means that the operation succeeded completely.<br />
*<b>STATUS_FAIL</b> means that the operation failed and trying again will also fail. This status value indicates a problem with the object being processed.<br />
*<b>STATUS_WAIT</b> means that the operation failed but trying again later may succeed. This status value indicates a temporary problem accessing the external database.<br />
All the methods of the DatabaseAdapter class return the value <b>STATUS_OK</b>.<br />
<br />
===Extending the DatabaseAdapter Class===<br />
To implement a useful interface to an external database, you must extend the <b>DatabaseAdapter</b> class. The <b>build.xml</b> file provides an example of such an implementation in the <b>testdatabase</b> target. It builds a jar containing <b>org.rsna.database.TestDatabase</b>. This implementation only logs method calls.<br />
<br />
Since the DatabaseAdapter class implements dummy methods returning STATUS_OK, your class that extends DatabaseAdapter only has to override the methods that apply to your application. If, for example, you only care about XML objects, you can just override the <b>process(XmlObject xmlObject)</b> method and let DatabaseAdapter supply the other <b>process()</b> methods, thus ignoring objects of other types.<br />
<br />
The database interface should not rely on the <b>reset()</b> and <b>shutdown()</b> methods. They are called when possible, but there are certain situations in which they cannot be called (a power failure, for example), and you should make sure that the data is protected in those situations. Similarly, since one <b>connect()</b> call is made for possibly multiple <b>process()</b> method calls, it is possible that a failure could result in no <b>disconnect()</b> call. Thus, depending on the design of the external system, it may be wise to commit changes in each <b>process()</b> call.<br />
<br />
If you want to log information that will be visible through the “</b>Show Log</b>” button on the admin page, you can use the static methods in the <b>org.rsna.mircsite.log.Log</b> class. Remember, however, that the <b>Log</b> class only maintains a circular buffer of the past 200 entries, so if you make many calls, you may be removing log entries made by other objects.<br />
<br />
===Connecting Your Database Class to MIRC===<br />
After building your database interface and producing a jar file for it, you have to install it and configure it. The Database Export Service is part of a Storage Service, and each storage service can have its own (possibly different) external database. Therefore, the interface is installed and configured at the level of the Storage Service.<br />
====Installation====<br />
The database interface jar file must be installed in the:<br />
<br />
<center><tt>Tomcat/webapps/[storageservice]/WEB-INF/lib</tt></center><br />
<br />
directory, where [storageservice] is the name of the storage service for the clinical trial. Do <b>not</b> place the jar file in the Tomcat/shared/lib directory. Doing so will cause the class not to load.<br />
<br />
The MIRCsite-installer program always deletes the <br />
<br />
<center><tt>Tomcat/webapps/[storageservice]/WEB-INF/lib</tt></center><br />
<br />
directory during an upgrade to prevent old libraries from contaminating a new release. This has the unfortunate effect of deleting the database interface jar file. You must therefore be careful to restore the database interface jar file after an upgrade.<br />
<br />
====Configuring MIRC for Your Database Class====<br />
The Admin Service provides a web interface for setting the configuration parameters. The interface is accessed by clicking the “Update Configuration” button in the “DICOM Service” column on the admin page. In the Database Export Service section of the resulting page, there are four parameters:<br />
*<b>Mode</b> determines whether objects that are received are automatically forwarded to the Database Export Service. In “auto” mode, they are. In “QC” mode, they are not. In QC mode, the assumption is made that the administrator will review the MIRCdocument that contains the received objects and verify that they are appropriate for sending to the database. If they are, he can click the “Export to database” button in the “Images” column at the bottom of the displayed document’s “Document” tab. Doing so queues all the objects in the document for export. An important subtlety is that the only objects that make it into MIRCdocuments are ones that contain a Study Instance UID. Thus, a FileObject will never be sent to the Database Export Service (since a FileObject’s contents cannot be parsed by MIRC). In auto mode, however, all received objects are exported, so if you plan to receive unparseable files as part of your clinical trial, you must operate the Database Export Service in auto mode.<br />
*<b>Anonymizer enabled</b> determines whether the objects are anonymized after being sent to the database. This operation is a little counter-intuitive at first sight. The operational model is that objects are anonymized before they are transmitted to the MIRC site. Typically, this would be done by the MIRC FieldCenter application which transmits them to the MIRC site. Actual anonymization takes place at that time, but in some cases, it is desirable to have the anonymizer include provenance information that is intended for the database but not for viewers of the MIRCdocument or its referenced objects. In that situation, the FieldCenter’s anonymizer is configured to add the provenance information, the object is sent to and received by the MIRC site, which stores the file in the directory for the Study Instance UID of the file and references it in the associated MIRCdocument. The file is then passed to the Database Export Service with the provenance information intact. If the anonymizer is enabled, then after the process() method of the database interface class returns, the Storage Service’s anonymizer is called to remove the provenance information.<br />
*<b>Sleep interval</b> determines the frequency at which the Database Export Service checks its queue. The interval is specified in milliseconds, and a typical interval is 10,000, or 10 seconds. The Database Export Service enforces a reasonability criterion on the value, so if it is very short or very long, it uses a 10 second default. <br />
*<b>Database class name</b> specifies the fully qualified name of the class, for instance, org.rsna.database.TestDatabase. If this field is empty, the Database Export Service will operate as if it were disabled.<br />
<br />
If you want to have references to received metadata files placed in the MIRCdocuments that are automatically created for clinical trial studies, you should add a <metadata-refs/> element to the Tomcat/webapps/[storageservice]/trial/template.xml file. This element is explained in “The MIRCdocument Schema” documentation, which is available on the RSNA MIRC site (mirc.rsna.org).<br />
<br />
====Operational Note====<br />
When a file is received, the Object Processor and the Database Export Service attempts to figure out the type of file by parsing it. It first tries to parse it based on the extension of the filename. If that fails, it tries all the untried classes in the order:<br />
#DicomObject<br />
#ZipObject<br />
#XmlObject<br />
If none of the objects can be instantiated, a FileObject is created for the file. If the file is a binary object that is neither a DICOM file nor a zip file, the attempt to instantiate the XmlObject will cause the Xerces parser to encounter a fatal, but not serious, error, which it logs to the console stream where it can be seen in the log viewer or by accessing the <b>Tomcat/logs/stdout.log</b> file. The error is not serious because although the Xerces parser fails, it is reinstantiated whenever it is needed, so there is no effect on the operation of the system. This error will never occur in trials which produce only DICOM, zip, or XML files.</div>209.242.55.28