The MIRC TCE Service

From MircWiki
Jump to navigation Jump to search

This article describes how to configure the TCE Service. It is intended for MIRC administrators and for third-party developers intending to interface their products to the TCE Service.

The TCE Service implements the Export Receiver actor defined in the IHE TCE Integration Profile. The TCE Service is implemented in a CTP pipeline. The function of the pipeline is to receive objects and to group them into teaching file cases as defined by a manifest supplied with the objects by the sending system (typically a PACS workstation). The pipeline can be configured as described in MIRC Pipelines.

1 Standard TCE Export Receiver Functions

The TCE Service contains a DICOM Storage SCP that receives manifests, Additional Teaching File Information (ATFI) objects, and DICOM instances from an IHE Export Manager. The TCE Service pipeline includes a special TCEStorageService stage that creates a MIRCdocument from all the objects identified in a manifest. As such, it fully meets the requirements of a TCE Export Receiver. The TCEStorageService also includes a configurable anonymizer, so it also meets the requirements of a TCE Export Manager in the teaching files application.

When the TCE Service receives a complete set of objects (a manifest and all the objects it references), it creates a MIRCdocument from a template file and then inserts the objects into it.

If the manifest is a DICOM KOS object, the standard MIRC TCE template file is used. The standard template file is delivered in the CTP/libraries/MIRC.jar file. (In that jar file, the template is located at /storage/TCEServiceTemplate.xml.) When the first submission is received, the TCE Service copies the template to the root directory of the library in which the MIRCdocument will be stored (typically, CTP/mircsite/storage/ss1). Changes to the template are not lost during an upgrade.

If the manifest is an XML object in the form of a MIRCdocument as described below, the manifest itself is used as the template file.

The library into which the MIRCdocument is stored is determined by the ssid attribute of the TCEStorageService element in the TCE Service Pipeline of the CTP/config.xml file. This value specifies the default location, but it can be overridden in one of two ways:

  • If the Called AE Title of the DICOM transfer of the TCE manifest is a valid ssid, it takes precedence over the default.
  • If the manifest is a MIRCdocument XML file and the ssid attribute of the root element is a valid ssid, it takes precedence over the default.

For DICOM manifests, overriding the default storage library can be done by inserting the calledAETTag attribute in the DicomImportService element of the TCE ServicePipeline and the ssidTag attribute in the TCEStorageService element, specifying the same DICOM text element in each case. A convenient element is 00120010, which is in the clinical trials group and not typically used in teaching files. See the DicomImportService documentation for details on the calledAETTag attribute.

2 MIRC Extensions to the TCE Profile

The MIRC TCE Service implementation provides several extensions to the IHE TCE profile, including the ability to parse the Key Object Description element in the manifest to obtain information not provided in the profile, and the ability to accept a manifest as an XML MIRCdocument template.

2.1 Key Object Description

The Key Object Description element in the IHE manifest is an Unlimited Text DICOM element. Some PACS vendors provide a user interface on the Export Selector (typically a PACS workstation) allowing the user to populate this element with comments. Since the TCE specification does not provide elements for certain fields of interest to teaching file authors, MIRC implements a syntax for the element and parses it whenever a manifest is received.

The syntax allows character sequences in the form mirc:path=value to be inserted anywhere in the element text, where path defines the path from the root element of the MIRCdocument to the element whose value is to be modified and value is the value to be inserted in the element. Paths do not include the root element name. Whitespace is not allowed in mirc:path=. Values may contain whitespace, including newline characters. Values consist of all the characters after the equal sign and before the next mirc:path=value sequence. When inserted into MIRCdocument elements that are displayed, the value is broken into paragraphs delimited by two newline characters.

IHE currently does not define elements for two important fields:

  • the username of the user on the teaching file system;
  • the title of the created document.

The Key Object Description syntax can be used to supply these fields as shown below:

mirc:title=My Document Title
mirc:authorization/owner=myusername
mirc:freetext=

For an element in a MIRCdocument to be populated from the parsed values in the Key Object Description element, there must be an element in the TCEServiceTemplate.xml file which has the same path relative to the root element. Any parsed value which does not correspond to a path in the MIRCdocument is ignored.

In the example above, the last item, mirc:freetext=, is used simply to delimit the previous item and to allow users to insert comments.

The entire contents of the Key Object Description element are inserted in the Notes section of the template, allowing the author to see any unparsable notes passed in the element. (Note: since there is no freetext element in the MIRCdocument schema, the content of that field will only be inserted into the Notes section.)

Note to third-party developers wishing to interface to the MIRC TCE Service: it is possible to place all the content of teaching file items in an ATFI object in the Key Object Description element without having to construct the ATFI object. While this is not encouraged, this approach removes the complexity of an ATFI object from the list of excuses not to implement TCE. Just do it.

2.2 XML Manifest

The TCE Service Pipeline has two ImportService elements, one for reception of DICOM objects via the DICOM protocol, and one for the reception of both DICOM and XML objects via the HTTP protocol.

HTTP transmissions require the content to be transmitted as an HTTP POST with Content-Type application/x-mirc. An XML manifest must be encoded in UTF-8. Both manifests and DICOM instances can be transmitted in this way if desired, or manifests can be sent via HTTP and DICOM instances via DICOM.

An XML manifest is a MIRCdocument XML template that contains a special element identifying the SOPInstanceUIDs of the instances (and ATFI object, if any) for inclusion in the teaching file case. The element is described in The MIRCdocument Schema. See also Extended TCE Service Templates.

When the TCEStorageService receives a normal TCE manifest (a DICOM KOS object). it uses a standard MIRCdocument template to control the form of the created case. When the manifest is a MIRCdocument XML template, it uses the manifest as the template for the created case. The purpose of the XML template is to allow third-party developers greater control over the format of the case and to avoid the necessity for creating either the DICOM manifest or the ATFI object, since all the information in both objects can be passed in the template itself.