RIM Maintenance and Tooling Documentation

Introduction

To quote the HL7 standard "Core Principle and Properties of V3 Models":

The essential feature of HL7 Version 3 is that its specifications (standards) SHALL be based on a set of common models, and that, to the extent possible, these models will be based on the object modeling facilities of the Unified Modeling Language (UML). In HL7 Version 3, the information models for the specifications (standards) are based on three "core" models that are published as individual specifications but have been developed and maintained though careful collaboration and coordination within the HL7 community. These models are:

• HL7 Reference Information Model (RIM) is an "information model" covering all information that must be communicated in support of health care ...

• HL7 Abstract Data Types Model is a robust specification of data types ...

• HL7 Vocabulary Model is a set of HL7-defined and maintained Concept Domains, Code Systems and Value Sets ...

To this end, development of the HL7 Reference Information Model (RIM) was started in 1996, and has been a continuing process since. To date, HL7 has released over 60 RIM versions, including three "normative" releases. This document lays out the processes and tooling used to maintain the RIM.

Harmonization and Publication

The primary process for RIM development and maintenance process known as the Vocabulary and RIM Harmonization Process. This process was initiated as RIM Harmonization and extended when Vocabulary specifications became a key, formal part of V3 specifications. This process is documented elsewhere.

Publication of the RIM occurs in several forms:

• As a formal document for balloting and inclusion in V3 Normative Editions.

• As a set of formal definitions (represented in Model Interchange Format (MIF) files or data bases) and released for use with tools developed by HL7 and others. These are released under the "Design Repository Project" on Gforge. Prior to May 2011, the primary representation was an an HL7 Design Repository in Access. With the release of this updated process, the primary representations become MIF "definition files" for the RIM and Vocabulary.

• A formal RIM "model package" release that inlcudes modeling tool files, documentation of Harmonization changes, graphics, etc.

Prior Maintenance and Objectives

As the first version 3 methodology was defined, an Access "Design Repository" database was designed to represent all of the HL7 modeling artifacts in Access tables. Thus, there were tables for RIM classes, attributes, etc. Moreover, for each of the major elements model, a set of unique identifiers (GUID) was defined, and recorded along with data showing which version of the RIM a particular element became effective, and/or was dropped.

Not only were the data recorded in the primary design repository tables, but they were also transferred to an archive of model elements that allowed reconstruction of any single RIM version. With these data, it is possible to track the evolution of a particular attribute from its initial introduction into the RIM, through a variety of updates, to its final version, or perhaps its elimination from the RIM altogether.

The actual modeling the RIM depended upon in early-release UML modeling tool produced by Rational Software. HL7-specific properties were added to this modeling tool to allow documentation of the assigned each identifiers, vocabulary constraints, etc. The maintenance tooling included software that used programming interfaces (API) to both the modeling program and the Access repository to automate the processes of loading models to the data base, comparing the content, documenting differences, and updating the unique identifiers as recorded in the modeling tool, if necessary.

The development of new tools used this suite of capabilities as its primary set of requirements.

RIM Maintenance Process

The Vocabulary and RIM Harmonization Process for RIM development remains unchanged.

Modeling Tool

The primary modeling is now performed with IBM's Rational Software Architect - a UML tool implemented in the Eclipse environment and using the Eclipse modeling framework. This model is then "exported" using the UML XMI format.

RIM Archive

Representation of individual RIM models is expressed as a "mif:staticModel" from MIF 2.1.6. The representation of the RIM Archive data is contained in a

• mif:package element whose
  • mif:content is made up of
    • the most recent RIM mif:staticModel, in its entirety, followed by
    • a set of historic mif:staticModels that reflect the changes, version-to-version as the models evolved.

Transforms are provided for updating the archive to accommodate a new RIM release, and for extracting any particular RIM from the archive.

RIM Distribution

RIM distribution continues in the three primary groups as outlined under publication in the Introduction section above, although the specific content of each changes, as outlined in the following tooling discussion.

RIM Maintenance Tooling

Base Modeler

Model Elements Used

As noted above, the base modeling tool is Rational Software Architect. Within the RIM, the following model elements from the UML suite are used:

• Package to aggregate classes into "subject areas"
• Class
• Attribute
• Primitive Type to capture the assignment of a particular HL7 data type. The data types are not explicitly modeled in the RIM. The Primitive Type "name" establishes the binding to an HL7 data type.
• Bidirectional Association to capture the relationships, names and multiplicities between classes.
• Generalization to establish inheritance relationships between classes.
• State Machine made up of
  • State
    • Initial State
    • Final State
  • Transition - triggered by a named Signal Event

HL7 Profile

In order to support model properties that are extensions to the standard UML model, an "HL7" profile has been created for use with the RIM. The profile is defined in Rational Software Architect (RSA) as a set of named Stereotypes defined as Extensions of a particular UML meta-class.

The naming convention for the Stereotypes was established by the original RIM "property sets" from Rational Rose to RSA. The name, in the HL7:namespace, is the metaclass to which the stereotype applies.

Stereotype Definition

Each Stereotype is defined by a set of Attributes. Each such attribute has the following properties:

• Name - unique within the stereotype
• Type - With one exception (in each Stereotype) the types are either "Boolean" or String". The exception is the "base_" element attribute which is typed by the UML Meta-class that the Stereotype extends
• Default Value - populated principally for Boolean properties
• Is Static - uniformly set "false"
• Multiplicity - uniformly set to "1"
• Owner - which is set to the name of the Stereotype in which the attribute is found

History Properties

With the exception of the stereotype "HL7:Model" assigned to the model as a whole, all of the other stereotypes include a set of three properties that have been, and continue to be used to track the history of model elements. These three properties are:

History Properties

Name	Type	Default	Notation
zhxId	String		The current GUID assigned to this element when it was created or last updated. (This assignment will actually be made in the transforms that process each RIM, and then will be updated in the RSA model.)
zhxDate	String		The RIM release date on which this zhxId GUID was assigned. (This assignment is tracked in the RIM Archive and will be updated in the RSA model.)
zprevHxId	String		The GUID assigned to this element (or its predecessor) before its most recent change. This GUID provides a thread that allows tracing the history of a particular model element.

Stereotypes Defined for RIM

Within the HL7 Profiles, the following Stereotypes contain only the History Properties listed above:

• Category - extends the base type of Package.

• Inherit - extends the base type of Generalization.

• State - extends the base types of State, Pseudostate,InitalNode, and FinalNode.

• StateTransition - extends the base types of Transition and ActivityEdge.

The following tables list the additional properties provided in the remaining stereotypes defined in the HL7 Profile.

Class extends type Class and includes History Properties plus following

Name	Type	Default	Notation
ClassCode	String		For classes in the Act, Role or Entity hierarchies, this lists the terminology code that represents this RIM class within its encoded class hierarchy.
StateAttribute	String		For those classes that possess a defined StateMachine, this is the name of the attribute that holds the current state.

Attribute extends type Attribute and includes History Properties plus following

Name	Type	Default	Notation
SortKey	String		A two digit string that represents the appearance order of the RIM attributes, when the model is serialized. (Class displays should be arranged to use this display order in diagrams.)
isImmutable	Boolean	false	Whether this is treated in the RIM and ITS as an immutable attribute.
isMandatory	Boolean	false	Whether this is a Mandatory attribute in all RIM-derived designs.
isDocumentCharacteristic	Boolean	false	Applies to attributes of Act class (and its descendants).
conductible	Boolean	false	Whether this attribute can be conducted through ActRelationships and Participations.
conformance	String	U	The RIM-defined "conformance" value for this attribute.
Vocab_domain	String		Each coded attribute in the RIM SHALL use this to identify the Concept Domain that provides the concepts that are appropriate for this attribute.

The Following stereotype applies to the model itself. This profile has been extended beyond the elements required by the RIM to provide a variety of defining properties for "mif:staticModel"d that are needed to fully characterize the model, including all of the elements of the "mif:packageLocation" identifier (represented as elements whose names are prefixed with "pln_" where n is a hex digit).

Model extends type Model

Name	Type	Default	Notation
VocabularyVersion	String		The identifier of the Vocabulary version that should be imported for use with this model. (Typically differs for each RIM release.)
sortKey	String		Included but not applicable to this element of the RIM. (For RIM leave blank.)
title	String		The formal title for this model.
isSerializable	Boolean		Whether this model can be serialized (determined by association traversals). (For RIM set to false.)
representationKind	String		Determines whether the resultant should be represented in the MIF as a "flat" or "serialized" model. (For RIM set to flat.)
pl1_root	String		The value for the "root" attribute in the "mif:packageLocation" for this Model. (For RIM set to DEFN.)
pl2_section	String		The value for the "section" attribute in the "mif:packageLocation" for this Model. (For RIM leave blank.)
pl3_subSection	String		The value for the "subSection" attribute in the "mif:packageLocation" for this Model. (For RIM leave blank.)
pl4_artifact	String		The value for the "artifact" attribute in the "mif:packageLocation" for this Model. (For RIM set to RIM.)
pl5_subArtifact	String		The value for the "subArtifact" attribute in the "mif:packageLocation" for this Model. (For RIM leave blank.)
pl6_domain	String		The value for the "domain" attribute in the "mif:packageLocation" for this Model. (For RIM leave blank.)
pl7_realmNamespace	String		The value for the "realmNamespace" attribute in the "mif:packageLocation" for this Model. (For RIM set to UV.)
pl8_version	String		The value for the "version" attribute in the "mif:packageLocation" for this Model. (For RIM, set to version number (like "0235") for this RIM release.)
pl9_name	String		The value for the "name" attribute in the "mif:packageLocation" for this Model. (For RIM leave blank.)
pla_id	String		The value for the "id" attribute in the "mif:packageLocation" for this Model. (For RIM leave blank.)
plb_releaseDate	String		The value for the "releaseDate" attribute in the "mif:packageLocation" for this Model. (For RIM, set this tp calendar date (like "2011-08-11") on which the RIM will be released. )
pl0_combinedId	String		The value for the "combinedId" attribute in the "mif:packageLocation" for this Model. (For RIM leave blank.)

RIM Content Export

Once a RIM release has been completed in Rational Software Architect (RSA), it is exported in XMI and its graphics are exported as GIF graphic files.

To export model in XMI:

1. Right-click on the RIM.Models.rim in the Project Explorer and select Close
2. Right-click on the RIM.Models.rim in the Project Explorer, and select Export...
3. Select an Export Destination under Modeling of UML 2.2. XMI Interchange Model
4. Select the Destination to be in the Workspace as /RIM-XMI/XMI-OUT, and check Export Applied Profiles
5. Click Finish

To export all diagrams in GIF format:

1. In Project Explorer, Select: RIM.Models.rim.LogicalView.Information_Model
2. Select Menu:Modeling.Publish.Web...
3. In resulting dialog, select tab General and then set:
   • Level of Detail: Minimum - documentation Only
   • Navigation Style: Interactive Tree
   • Check - Generate Diagram Image Files
   • Select - Diagram Image File Format: GIF
   • Check - Always clean destination folder without asking
   • Browse - Select folder to publish to: to be ...workspace\RIM-XMI\publish
4. Ignore other tabs
5. Click OK

The XMI file from above will be transformed to create the RIM Archive, etc. The GIF files exported under publish/images will be renamed in ANT (using file workspace\RIM-XMI\renameDiagramsANT.xml) to the names used in HL7 Publishing of the RIM. It will place the result in directory workspace\RIM-XMI\outputgraphics.

If this ANT script does not work, it is because the internally assigned GUIDs (assigned by RSA) have changed. The ANT script can be rebuilt by running the transform workspace\RIM-XMI\Transforms\DiagramRenameANTscriptBuilder.xsl with the file workspace\RIM-XMI\publish\content\*-diagrams.xml as the source file.

CAUTION: as of November 2011, these graphics are not fully useful because:

• The previous graphics were all scaled down to a maximum of about 800 pixels wide, and these have NOT been reduced. Previously, this was a manual operation performed in Visio.

• The state machine diagrams produced in RSA need MAJOR re-work, and probably re-modeling. At present, they are neither fit nor correct for publication.

Updating Managed Object GUIDs

This process occurs after the exported model has been incorporated into the RIM Archive, and is discussed as a topic under the following section.

Archive Maintenance

Archive Structure

The RIM Archive is a "mif:package" whose "mif:content" is:

• A complete version of the most recently released RIM that is correct except that the sort keys for RIM attributes are the sort order within the class and does not consider the need to sort the attributes that are inherited by the class and should precede. (When the RIM is extracted from the archive, the extraction transform establishes the correct, complete sort order.)
• An incomplete model for each previous RIM release, that includes only those model elements that were "retired" (due to removal or update) from the RIM after that release.

Elements with management history records

Within the Archive (as in the past) there are seven RIM elements for which a "management history" is maintained. These are MIF elements: subjectAreaPackage, association, class, attribute, parentClass, subState, and transition. The history management is documented through the assignment of mif:historyItem(s) to each such element.

The historyItem(s) have two attributes:

1. an "id" in GUID form, and
2. a "dateTime" establishing the effective date for the GUID.

   In practice, these dates align with RIM release dates (as recorded in the mif:historyItem for each model) such that, for example a historyItem from "2010-03-21" was added when RIM "0231" was created.

Each history-managed element must have at least one historyItem, but may have up to three, with the following rules:

• If a historyItem has a "null" id represented as "00000000-0000-0000-0000-000000000000", this historyItem must have a date later than its siblings, and it must have at least one sibling historyItem.

  The null item represents the first model in which the element no longer occurs. (Within the archive, the dateTime of the null item is normally the date of the next model released after the model in which the null is listed.)

• If an element has two history items with non-null "id", then
  • the more recent (later "dateTime") historyItem holds the active GUID for the element, and
  • the older (earlier dateTime) historyItem holds the GUID assigned to the previous version of this element.

Changes in history-managed elements

An element will be updated and a new GUID assignment any time there is a change in the components that are part of the element (XML attributes and contained elements), except for changes in other history-managed elements that may be part of the element. Phrased another way, changes in the history-managed elements contained within an element do not cause a change in the containing element.

Thus, for example:

• If the isAbstract of a class changes, the class has changed;
• If any textual annotation of a class changes, the class has changed;
• If the data type of an attribute changes, the attribute has changed, but the class containing the attribute has not changed;
• If attributes are added or removed from a class, the class has not changed;
• If the definition of a state changes, the state has changed, but the class holding the state machine in which that state resides has not changed.

This strategy allowing history-managed item changes to be independent of changes in its parent or child elements has been part of the history-management since 1997, and results in a much leaner archive than would otherwise occur.

Archive Update for New Release

When a new RIM release is exported as an XMI file, the process of updating the RIM Archive is handled by a single run of a transform (R0-CreateNewArchiveFromXmiModel.xsl)that takes the XMI file as its input, and the previous archive file via a parameter, and outputs the updated RIM Archive.

The transform process consists of eight "passes" through node sets as follows:

1. Converts the XMI file into a starter RIM coremif file - produces variable $xmiModel

2. Update $xmiModel by assigning historyItem GUIDs to new elements in the model (ones for which no hxId was exported) - produces variable $updatedSource

3. Walks through the "root model" in the starting RIM Archive (the previous RIM release) and compare it to the elements in $updatedSource, attempting to identify the "twin" element that matches each element of the original.

   Identity matches may be made by type/position, name, history GUID, or similar means.

   If a twin is found, the two elements are compared for change, including the addition or removal of attributes and elements from either.

   All changes are documented in variable $modelComparison

4. Reduces $modelComparison to just the elements that have changed in any fashion, producing variable $deltaComparison

5. Walks through the RIM Archive root model along with $deltaComparison data to determine the "actions" that must be taken to update the old model to the new. The actions are recorded in variable $modelAction.

6. Walks through $updatedSource along with $modelAction to produce the final form for the new RIM that will be the root of the next archive - produces variable $rimUpdate

7. Walks through the RIM Archive root model along with $modelAction to reduce the previous root model to only those elements that document the change to the new model - produces variable $revisedArchRoot

8. Finally, processes the entire RIM Archive file to make $rimUpdate the new root model, followed by $revisedArchRoot, and then the remainder of the models that followed the root in the source archive. This produces the XML output that is the new RIM Archive.

Base Model Update

A separate XSLT transform (S0-UpdateRationalModelForHistory.xsl) is used to update the "history data" in the Rational Software Architect model file (rim.emx) from the updated new RIM in the root of the updated RIM Archive. The transform simply copies the rim.emx file except that it updates the HL7 stereotype attributes for those elements in which values have changed.