View source for RIM Maintenance and Tooling Documentation

[[Category:HowTo]]
=Introduction=
To quote the HL7 standard "[http://www.hl7.org/v3ballot/html/infrastructure/coreprinciples/v3modelcoreprinciples.html 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 [http://www.hl7.org/v3ballot/html/infrastructure/rim/rim.html 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.
==RIM Balloting Using ANSI Continuous Maintenance Process==
Starting in 2009, Modeling and Methodology began maintaining the "normative" HL7 RIM under a continuous maintenance process.  The objective that MnM sought to fulfill was to have an up-to-date, Normative RIM specification to serve as the basis for each new Normative Edition.  In order to accomplish this, MnM initiates a new RIM Normative Ballot during the May ballot cycle of each calendar year.  Starting in May allows for re-balloting (in September) of significant changes that might arise from the Negative votes. Approval in May or September allows publication of the approved RIM in the Normative Edition for the following year. 

While adopting continuous maintenance, however, MnM also sought to retain the [[Vocabulary and RIM Harmonization Process]] as the primary mechanism for approving RIM changes, because Harmonization permits the creation of a strong consensus for RIM changes.  Thus the combined process that is followed is:
#Assumes that a new Normative RIM has been approved by the end of the September ballot cycle
#MnM makes RIM change proposals to remove deprecated items that have been published as deprecated in two Normative Editions
#Harmonization accepts proposals for changes to the RIM and to the Vocabulary that controls the RIM elements (all code systems that support attributes or data type components whose data type is CS) during the November and March Harmonization cycles.
#MnM creates RIM Version(s) that incorporate changes proposed in Harmonization
#MnM offers the resulting RIM for initial ballot in the May ballot cycle.
#MnM reconciles the RIM Negative comments in May and June
#If reconciliation '''results in substantive changes''', MnM forwards the '''changes resulting from reconciliation to the July Harmonization Meeting''' for approval
#For July, Harmonization will accept only those changes to the RIM and the Vocabulary that controls the RIM elements where those changes resulted from ballot reconciliation.
#MnM publishe the resulting RIM in the September ballot cycle, which may include the final ballot on the RIM if substantive changes were required to address Negative votes form the May cycle.

This restriction on acceptable RIM changes during the July Harmonization cycle is necessary to maintain the synchrony between the Normative RIM content and the Normative Editions.
==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 [[Vocabulary and RIM Harmonization Process|elsewhere.]]

Publication of the RIM occurs in several forms:
* As a [http://www.hl7.org/v3ballot/html/infrastructure/rim/rim.html formal document] for balloting and inclusion in V3 Normative Editions.
*:
* As a set of formal definitions (represented in [http://www.hl7.org/v3ballot/html/infrastructure/mif/mif.html Model Interchange Format] (MIF) files or data bases) and released for use with tools developed by HL7 and others.  These are released under the "[http://gforge.hl7.org/gf/project/design-repos/ 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 [http://www.hl7.org/implement/standards/rim.cfm?ref=common RIM "model package"] release that includes modeling tool files, documentation of Harmonization changes, graphics, etc.

Specific [[#RIM_Release_Distribution|Content for these Distributions is documented below]].

==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, since early 2014 is Sparx Systems Enterprise Architect - a stand-alone UML tool.This model is then "exported" using the UML XMI format and transformed to update the RIM Archive file.

==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:staticModel'''s that reflect the changes, version-to-version as the models evolved.

XSLT transforms are used to update the archive, adding the new RIM release, and changing the prior model to a change (delta) model relative the new RIM.  Similarly, transforms provide for extracting either the new RIor any particular RIM from the archive. 

Once the XMI is exported from Enterprise Architect, the Transform process is run by a single, mutli-step ANT script to produce all outputs - updated MIF RIM archive, new RIM release, files and new RIM graphics properly named as JPGS.

==RIM Distribution==
RIM distribution continues in the three primary groups as outlined under publication in the [[#Introduction|Introduction]] section above, although the specific content of each changes, as outlined in the following [[#RIM Maintenance Tooling|tooling discussion]].

=RIM Maintenance Tooling=
==Base Modeler==
===Model Elements Used===
As noted above, the base modeling tool is Enterprise Architect.  Within the RIM, the following model elements from the EA UML suite are used Note that the vast majority of the are named after a UML element with an "h" at the front of the name This signifies that the UML element has an hl7 profile applied to it. The element list is:
*'''hModel''' to as root package for IM
*'''hSubjectArea''' to hold related classes, associations and their state machnes
*'''Class diagrams at level of each hSubjectArea
*'''hClass''' within hSubjectArea
*'''hAttribute''' within hClass
*'''StateMachine''' within some hClass
*'''hState''' within StateMachine
*'''hGeneralization''' within "Links" display of some classes 
*'''hAssociation''' within "Links" display of some classes 
*'''RoseUserDefinedDataTypes''' to an enumerated type for DT R1 and DT R2 used in the RIM.

These elements are displayed in the EA Project Browser as seen below, right.

[[File:EAprojectBrowseofRIM.jpg|512px|thumb|right|EA Project Browser]]
===RIM Workspace Directory Structure===
The rim-workspace is defined and persisted in SVN at "http://gforge.hl7.org/svn/design-repos/trunk/rim-workspace".  The directory structure under rim-workspace is comprised of:
* '''documentation''' - random notes on the design
*:
* '''output''' - Content is generated automatically by the RIM update process and is divided into two subdirectories:
*:
** '''outputgraphics''' - all RIM graphic files named for use in publishing the RIM
**:
**'''xml''' - a variety of model-comparison file and the "final" coremif file for the new RIM
**:
*'''RIM''' the primary focus for processing the new RIM with subdirectories:
*:
**'''Archive''' holds the central persistent MIF package that is the Archive of all past RIM models '''rim-archive.mif'''
**:
**'''Models''' contains the single EA source file '''HL7_RIM.eap'''
**:
**'''Profiles''' contains the EA model file for HL7 Profile '''HL7Profile-model_2014.eap''' and the profile xml file '''HL7-RIM-profile2014.xml'''

HL7 Profile is maintained in a separate EA project - rim-workspace\RIM\Profiles\HL7Profile-model_2014.eap. From that project the Profile is exported as aa profile XML file - rim-workspace\RIM\Profiles\HL7-RIM-profile2014.xml. This, in turn was imported as a profile into the primary RIM model project - rim-workspace\RIM\Models\HL7_RIM.eap

===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 '''Stereotype'''s defined as '''''Extension'''''s 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:
{| border="1" cellpadding="5" cellspacing="0"
|+'''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. '''''(This assignment may be made manually, but it will usually be made in the transforms that process each RIM, and then will be updated in the RSA model.) '''''
|}
<br/>

====Stereotypes Defined for RIM====
Within the HL7 Profiles, the following Stereotypes contain '''only the [[#History Properties|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.

{| border="1" cellpadding="5" cellspacing="0"
|+'''Class''' extends type '''Class''' and includes [[#History Properties|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. 
|}
<br/>
<br/>
{| border="1" cellpadding="5" cellspacing="0"
|+'''Attribute''' extends type '''Attribute''' and includes [[#History Properties|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. 
|}
<br/>
<br/>
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).
<br/>
{| border="1" cellpadding="5" cellspacing="0"
|+'''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 WARNING Has Not been Updated for use of EA beyond here 1/13/16===
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. 

====Export model in XMI:====
#Right-click on the '''RIM.Models.rim''' in the Project Explorer and select '''Close'''
#Right-click on the '''RIM.Models.rim''' in the Project Explorer, and select '''Export...'''
#Select an Export Destination under '''Modeling''' of '''UML 2.2. XMI Interchange Model'''
#Select the Destination to be in the '''Workspace''' as '''/RIM-XMI/XMI-OUT''', and check '''Export Applied Profiles''' 
#Click '''Finish'''

====Export all diagrams in GIF format:====
#In Project Explorer, '''Select: RIM.Models.rim.LogicalView.Information_Model'''
#Select '''Menu:Modeling.Publish.Web...'''
# 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'''
#*Uncheck - '''Display element icons''' '''???????????'''
#*Check - '''Always clean destination folder without asking'''
#*Browse - Select folder to publish to: to be '''...workspace\RIM-XMI\publish''' 
#Ignore other tabs
#Click '''OK'''
:
:
:<big>'''WARNING:'''</big> - The above method began to FAIL in November 2012.  The attribute content from selected classes did NOT appear in the exported graphics, even though they were clearly present in the diagrams.  The ONLY change from previous processing is that the JAVA jre was updated from 1.6.x to 1.7.x.  I updated Rational Software Architect, but this did NOT correct it.  In the end, I had to export the graphics by hand by:
:# Open the selected graphic in RSA
:# Right-click in the graphic window
:# Select contectual Menu...File...Save As Image File...
:# In resulting Dialog:
:##Select target directory of '''''workspace\RIM-XMI\outputgraphics\'''''
:##Select Image format of '''''GIF'''''
:##Click '''''OK'''''
:#Closed the selected graphic window
:# Repeat until done

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 [[#Base Model Update|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 do 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:
# an "id" in GUID form, and 
# 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:
#Converts the XMI file into a starter RIM coremif file - produces variable '''$xmiModel'''
#:
#Update '''$xmiModel''' by assigning historyItem GUIDs to new elements in the model (ones for which no hxId was exported) - produces variable '''$updatedSource'''
#:
#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'''
#:
#Reduces '''$modelComparison''' to just the elements that have changed in any fashion, producing variable '''$deltaComparison'''
#:
#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'''.
#:
#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'''
#:
#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'''
#:
#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'''.

===Validate and SAVE the New Archive with MIF Schemas===
Before saving the new rim-archive.mif, validate it against the MIF schema "'''''COMPLETE.xsd'''''" that is in the MIF 2.1.6 schemas release package.  '''The objective of this step is to detect any mark-up errors that may have occurred''' in descriptive fields being updated.  The '''most common errors''' are:
*making a &lt;p/> element a child of another &lt;/p> element;
*placing a &lt;ul/> or &lt;ol/> element inside a &lt;p/> element;
*placing a sub-list of an existing &lt;ol/> or &lt;ul/> as a direct child (between two &lt;li/> elements) rather than placing it inside the &lt;li/> element of which it is a sub-list. 

If this is done BEFORE the rim-archive has been saved and before the following Base Model Update, you an make the needed changes in the Rational model, and begin the export/transformation process anew.

When you are satisfied with the new archive, '''SAVE the archive as RIM-XMI\rim_archive\''rim-archive.mif'''''.

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

===Extract RIM "CoreMif" File for Updated RIM===
A separate XSLT transform ('''T0-ExtractRimFromArchive.xsl''') is used to '''extract any previous RIM''' from the Archive and produce a RIM .coremif (version 2.1.6) file for use with tooling, etc. The first line of the transform sets a parameter whose name is "targetName".  Set the value to the version string sought, such as "0239" for version 2.39. The source file for the RIM is the "rim-archive.mif" (RIM Archive) file in "workspace\RIM-XMI\rim_archive".  The result should be saved as "DEFN=UV=RIM=nnnn.coremif" where "nnnn" is replaced with the version string used for the target name parameter.
===Create a Model-difference HTML File For Release Packages===
Working in Directory '''\RIM-XMI\XMI-OUT\''':
# Rename file '''DeltaComparison.xml''' By adding a string like '''"_0240-0241"''' before the extension.  This will identify the "from-to" identifiers of the two models being compared.
#:
# Apply transform  '''RIM-XMI\Transforms\U0-FormatDifferenceFileInHtmlForHumanReading.xsl''' to the file renamed above.  It will produce a a file to be named like '''DeltaComparison_0240-0241.xhtml''' that can be distributed in the combined RIM zip file as the difference file between releases.

==RIM Release Distribution==

The RIM and Vocabulary are published in three different forms:
* [http://gforge.hl7.org/gf/project/design-repos/frs/ '''rimRepos'''] - Under the "Design Repository" project on Gforge holds just the formal definition of the RIM and vocabulary  (as core mif files); the Vocabulary data base in Access, and related Harmonization files.
* [http://gforge.hl7.org/gf/project/design-repos/frs/ '''toolingRepos'''] - is just the core mif representation of the RIM, VOcabulary, data types and CMETs used to support Publishing Tooling
* [http://www.hl7.org/implement/standards/rim.cfm '''Complete RIM package'''] - on the HL7 Reference Information model page is the most comprehensive set of RIM artifacts, including core mif and model tooling files.

Specific contents notes listed below
===Contents===
====[http://gforge.hl7.org/gf/project/design-repos/frs/ rimRepos]====
=====Example content=====
* '''releaseNotes.txt''' - summary of the status of the content.
* '''DEFN=UV=RIM=0238.coremif''' - RIM core mif file
* '''DEFN=UV=VO=1148-20120324.coremif''' - Vocabulary core mif file
* '''EXTENSION=UV=VO=1028-20100322.zip''' - MIF file of vocabulary extensions included in core mif but not represented in the Access data base
* '''HarmonizationResults_2012Mar.zip''' - archive of Harmonization results including:
**review spreadsheet that links the proposal files and findings
**directory of ''initial'' proposals
**directory of ''final'' proposals
** directory of ''vml'' (vocabulary maintenance language) files used to update the data base.
<!-- * '''rim_none_Voc1148_20120324_Repository20120324.mdb''' Access data base that is the primary source for vocabulary content. -->

====[http://gforge.hl7.org/gf/project/design-repos/frs/ toolingRepos]====
===== '''Example content''' =====
* '''coremifs''' - Core MIF files for data types (=DT=), CMTs (=IFC=), RIM (=RIM=), and vocabulary (=VO=)
** '''DEFN=UV=DT=1.0.coremif''' - 
** '''DEFN=UV=DT=1.1.coremif''' - 
** '''DEFN=UV=DT=2.0.coremif''' - 
** '''DEFN=UV=IFC=1.11.1.coremif''' - 
** '''DEFN=UV=RIM=0238.coremif''' - 
** '''DEFN=UV=VO=1148-20120324.coremif''' - 
* '''coreschemas''' - Schemas for data types, and related elements
** '''datatypes-base.xsd''' - data types R1 base
** '''datatypes-r1.1-base.xsd''' - data types R1.1 base
** '''datatypes-r1.1.xsd''' - data types R1.1 
** '''datatypes-rX-cs.xsd''' - 
** '''datatypes.xsd''' - data types R1
** '''ExampleExtensions.xsd''' - 
** '''iso-21090_hl7-r2_datatypes.xsd''' -  dsta types R2
** '''NarrativeBlock.xsd''' - 
* '''mifenumerationsschema''' - enumerated vocabulary that forms a portion of the MIF schemas
** '''mif-core-enumerationsVocab.xsd''' - 
* '''Rim238.xml''' - dummy file for linking RIM publishing dselection to Generator
* '''Rim238R1.xml''' - dummy file for linking RIM publishing dselection to Generator
* '''Rim238R11.xml''' - dummy file for linking RIM publishing dselection to Generator

====[http://www.hl7.org/implement/standards/rim.cfm Complete RIM package]====
===== '''Content overview''' =====
This is a single ZIP archive comprised of a set of files (almost all of which are also archives) whose content is designated by their naming convention. The following Naming Convention is used for the model file names: 
*<strong>DDDVVVVT</strong> where:
** <strong>DDD</strong> - This value is always "rim"
** <strong>VVVV</strong> - the HL7 Version a four-digit sequence such as "0238 for RIM 2.38
**<strong>T</strong> - This refers to the type of the files in the parent archive. 

The type code for the overall composite archive is '''"c"'''.  Thus for RIM 2.38, the composite archive is '''rim0238c.zip'''.  The contents of this archive is made up of the following file types: 
* '''a - Archive''', a zip file holding  a MIF archive (mif:package) file whose content is made up the '''complete current RIM''', and change-elements for '''ALL prior RIM versions'''. Any given prior RIM can be extracted from this archive.
*:
* '''c - Composite''', a ZIP file of ALL of the other ZIP files in this list.
*:
* '''d - Definition''' the current RIM and current vocabulary represented in "coremif" definition (DEFN) files as a "mif:staticModel" and "mif:vocabularyModel", respectively. These definitions can be opened for browsing with the RoseTree application.
*:
* '''f - Difference''', a file (readable in html) that shows where the current RIM differs from the prior version.
*:
* '''g - Graphics''', a set of files in Visio and GIF format that contain the graphic expressions for the current model.
*:
* '''i - XMI''', an expression of the current RIM in the OMG UML 2.2 XMI standard. Includes the RIM xmi and a collection of "profiles" upon which the RIM is dependent.
*:
* '''n - Notes''', complete set of notes and proposals from the RIM harmonization meeting that reviewed the changes that are incorporated in the current models.
*:
* '''r - readMe''', a text file with notes about this version of the model and the files that are posted here.
*:
* '''t - Enterprise Architect file''', the complete model as an EAP file suitable for loading into Enterprise Architect.
*:
* '''x - XML''', a set of small XML files that will be used short-term (during 2012) to inform the V3 Generator of the RIM and data types versions to use for generation.

=====BUILDING A rimxxxxc.zip FILE_FOR DISTRIBUTION ON HL7.ORG SITE =====
# Start with the equivalent zip file for the preceding release.
# Extract above to an empty directory. You will need to create an update for every file in the prior package. (Or reuse, if unchanged) In sequence, the following tasks will work:
#* '''rimxxxxa.zip''' In the "current" rim-workspace (''gforge.hl7.org/svn/design-repos/trunk/rim-workspace'') find file ''rim-workspace\RIM\Archive\rim-archive.mif''. This file is the sole content for rimxxxxa.zip. Zip it with this name, and delete the predecessor "a" file.
#**'''"current" in this context''' refers to the "revision" of the rim-workspace in which the release being built was persisted.
#**:
#* '''rimxxxxd.zip''' The content for this zip is found if hl7_rimRepos-x.xx.n.zip, '''where x.xx is the last three x's of this (rimxxxxd.zip) release, and "n" is the last (highest) dot release for this. In that archive, the desired files are '''DEFN=UV=RIM=xxxx.coremif''' and the file that matches '''DEFN=UV=VOC=*.coremif'''. Zip these with this name, and delete the predecessor "d" file.
#*:
#* '''rimxxxxf.zip''' In the current rim-workspace, '''on your machine''', the directory rim-workspace/output/xml '''should''' contain a pair of files named like "'''DeltaComparison_yyyy-xxxx'''" (where yyyy is the previous release, and xxxx is the one being packaged) and with extensions '''.xml''' and '''.xhtml'''. These two files are sole content for rimxxxxf.zip. Zip it with this name, and delete the predecessor "f" file.
#*:
#* '''rimxxxxg.zip''' Contains, in .gif format and in a "graphics" subdirectory, the 18 graphic files and two .pdf files needed to publish the RIM. It also contains a Visio (.vsd) file with one page per graphic. 
#*:
#*:Visio is used to convert the "rim-workspace\output\outputgraphics" *.png files exported from the EA Modeling tool into properly scaled .gif files. It also is the base for creating the .pdf files for "RIM_Billboard.pdf" and "RIM_NormativeContent.pdf". These two files '''must be updated''' for each release as they carry a textual annotation citing the release.
#*:
#*:Other files '''need not be processed''' unless the RIM changes for this release include a change in the attributes for some class or the removal/addition of a new class.  In the event of a change, at the graphics will need to be updated, for the "subject area" (like 'Acts') in which the class resides.
#*:
#*:The process is to load the .png as a graphic onto a Visio page, scale it to about 800 pixels wide, and export it from Visio as a 'gif.  The easy way to do this is to pace the new .png image over the existing graphic and then scale the new image (maintaining x-y proportions) to match the old one.  Then delete the old (previously existing) graphic and save the image as a .gif.
#*:
#*:A similar process is used to create the two PDF files.
#*:
#* '''rimxxxxi.zip''' For Enterprise Architect, this archive contains the single file "rim-workspace\RIM\XMI\rim.xmi". This file is the sole content for rimxxxxi.zip. Zip it with this name, and delete the predecessor "i" file.
#*:
#* '''rimxxxxn.zip''' contains the '''HarmonizationMeetingResults''' (or equivalent name) folder, which in turn contains the initial and final results proposals, the VML files, and "meeting control" spreadsheet for the meeting(s) in which the changes for this release were approved. Take this folder, zip it, preserving the sub-directory structure and name it as the ....n.zip archive.  Delete the predecessor "n" file.
#*:
#* '''rimxxxxr.txt''' This text file acts as the "read me" for the overall archive, and is mostly ''pro forma'', therefore start with the content of the predecessor text file.  The '''exception is the "Version NOTES" section''' which is taken verbatim from the RIM description text in ''DEFN=UV=RIM=xxxx.coremif'' at xPath 'mif:staticModel/mif:historyItem/mif:description/mif:p' - take each mif:p and place its contents in a single paragraph of the text file. Once the edits are made save the file as "rimxxxxr.txt". Delete the predecessor "r" file.
#*:
#* '''rimxxxxt.zip''' Contains the processable "tool file" for Enterprise Architect. With "rim-workspace" that is "current" (see note above) for this release, find the file '''rim-workspace\RIM\Models\HL7_RIM.eap'''. This is the sole content for this archive. Zip it up and delete the predecessor archive. 
#*:
#* '''rimxxxxx.txt''' This holds three small RIM XML dummy files named like Rimxxx.xml, RimxxxR11.xml and RimxxxR1.xml, where xxx are the last three digits of the "xxxx" that defines this package.
#*:
# '''rimxxxxc.zip''' This is the ultimate goal.  Collect all of the preceding files *.zip and *.txt into this archive, and delete the predecessor archive.
#:
# Get HQ to post the generated file on hl7.org as '''www.hl7.org/documentcenter/public/standards/V3/RIM/C3xxxx/rimxxxxc.zip''' (where xxxx is same value as above), and to amend the web page (cfm) at "www.hl7.org/implement/standards/rim.cfm?ref=common" to place this file at the appropriate location in this list of files.