This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "RIM Maintenance and Tooling Documentation"

From HL7Wiki
Jump to navigation Jump to search
 
(36 intermediate revisions by the same user not shown)
Line 50: Line 50:
 
The [[Vocabulary and RIM Harmonization Process]] for RIM development remains unchanged.  
 
The [[Vocabulary and RIM Harmonization Process]] for RIM development remains unchanged.  
 
==Modeling Tool==
 
==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.
+
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==
 
==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  
 
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  
Line 58: Line 59:
 
*** a set of historic '''mif:staticModel'''s that reflect the changes, version-to-version as the models evolved.
 
*** a set of historic '''mif:staticModel'''s 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.
+
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==
Line 66: Line 69:
 
==Base Modeler==
 
==Base Modeler==
 
===Model Elements Used===
 
===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:
+
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:
*'''Package''' to aggregate classes into "subject areas"
+
*'''hModel''' to as root package for IM
*'''Class'''
+
*'''hSubjectArea''' to hold related classes, associations and their state machnes
*'''Attribute'''
+
*'''Class diagrams at level of each hSubjectArea
*'''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.
+
*'''hClass''' within hSubjectArea
*'''Bidirectional Association''' to capture the relationships, names and multiplicities between classes.
+
*'''hAttribute''' within hClass
*'''Generalization''' to establish inheritance relationships between classes.
+
*'''StateMachine''' within some hClass
*'''State Machine''' made up of
+
*'''hState''' within StateMachine
**'''State'''
+
*'''hGeneralization''' within "Links" display of some classes
***'''Initial State'''
+
*'''hAssociation''' within "Links" display of some classes
***'''Final State'''
+
*'''RoseUserDefinedDataTypes''' to an enumerated type for DT R1 and DT R2 used in the RIM.
**'''Transition''' - triggered by a named '''Signal Event'''
+
 
 +
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===
 
===HL7 Profile===
Line 103: Line 128:
 
|String
 
|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.)  
+
|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
 
|zhxDate
 
|String
 
|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.)  
+
|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
 
|zprevHxId
 
|String
 
|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.
+
|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/>
 
<br/>
Line 288: Line 313:
 
|}
 
|}
  
===RIM Content Export===
+
===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.  
 
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''':
+
====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 '''Close'''
 
#Right-click on the '''RIM.Models.rim''' in the Project Explorer, and select '''Export...'''
 
#Right-click on the '''RIM.Models.rim''' in the Project Explorer, and select '''Export...'''
Line 298: Line 323:
 
#Click '''Finish'''
 
#Click '''Finish'''
  
To export '''all diagrams in GIF''' format:
+
====Export all diagrams in GIF format:====
 
#In Project Explorer, '''Select: RIM.Models.rim.LogicalView.Information_Model'''
 
#In Project Explorer, '''Select: RIM.Models.rim.LogicalView.Information_Model'''
 
#Select '''Menu:Modeling.Publish.Web...'''
 
#Select '''Menu:Modeling.Publish.Web...'''
Line 306: Line 331:
 
#*Check - '''Generate Diagram Image Files'''
 
#*Check - '''Generate Diagram Image Files'''
 
#*Select - Diagram Image File Format: '''GIF'''
 
#*Select - Diagram Image File Format: '''GIF'''
 +
#*Uncheck - '''Display element icons''' '''???????????'''
 
#*Check - '''Always clean destination folder without asking'''
 
#*Check - '''Always clean destination folder without asking'''
 
#*Browse - Select folder to publish to: to be '''...workspace\RIM-XMI\publish'''  
 
#*Browse - Select folder to publish to: to be '''...workspace\RIM-XMI\publish'''  
 
#Ignore other tabs
 
#Ignore other tabs
 
#Click '''OK'''
 
#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'''.  
 
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'''.  
Line 325: Line 363:
 
===Archive Structure===
 
===Archive Structure===
 
The RIM Archive is a "mif:package" whose "mif:content" is:
 
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.)
+
* 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.
 
* 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.
  
Line 378: Line 416:
 
#:
 
#:
 
#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'''.
 
#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===
 
===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.
 
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==
 
==RIM Release Distribution==
Line 387: Line 443:
 
* [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/ '''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://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.
+
* [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
 
Specific contents notes listed below
 
===Contents===
 
===Contents===
 
====[http://gforge.hl7.org/gf/project/design-repos/frs/ rimRepos]====
 
====[http://gforge.hl7.org/gf/project/design-repos/frs/ rimRepos]====
 +
=====Example content=====
 
* '''releaseNotes.txt''' - summary of the status of the content.
 
* '''releaseNotes.txt''' - summary of the status of the content.
 
* '''DEFN=UV=RIM=0238.coremif''' - RIM core mif file
 
* '''DEFN=UV=RIM=0238.coremif''' - RIM core mif file
Line 401: Line 458:
 
**directory of ''final'' proposals
 
**directory of ''final'' proposals
 
** directory of ''vml'' (vocabulary maintenance language) files used to update the data base.
 
** 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.
+
<!-- * '''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]====
 
====[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=)
 
* '''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.0.coremif''' -  
Line 427: Line 485:
  
 
====[http://www.hl7.org/implement/standards/rim.cfm Complete RIM package]====
 
====[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:  
 
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>DDDVVVVT</strong> where:
Line 440: Line 499:
 
* '''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.
 
* '''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 pair files (details in xml, readable in html) that show where the current RIM differs from the prior version.
+
* '''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.
 
* '''g - Graphics''', a set of files in Visio and GIF format that contain the graphic expressions for the current model.
Line 450: Line 509:
 
* '''r - readMe''', a text file with notes about this version of the model and the files that are posted here.
 
* '''r - readMe''', a text file with notes about this version of the model and the files that are posted here.
 
*:
 
*:
* '''t - Rational Software Architect tool''', the complete model as an EMX file suitable for loading into Rational Software Architect.
+
* '''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.
 
* '''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.

Latest revision as of 14:15, 20 September 2016

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.

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:

  1. Assumes that a new Normative RIM has been approved by the end of the September ballot cycle
  2. MnM makes RIM change proposals to remove deprecated items that have been published as deprecated in two Normative Editions
  3. 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.
  4. MnM creates RIM Version(s) that incorporate changes proposed in Harmonization
  5. MnM offers the resulting RIM for initial ballot in the May ballot cycle.
  6. MnM reconciles the RIM Negative comments in May and June
  7. If reconciliation results in substantive changes, MnM forwards the changes resulting from reconciliation to the July Harmonization Meeting for approval
  8. 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.
  9. 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 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 includes modeling tool files, documentation of Harmonization changes, graphics, etc.

Specific 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:staticModels 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 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 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.

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 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. (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.)


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 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:

  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

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
    • Uncheck - Display element icons ???????????
    • 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
WARNING: - 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:
  1. Open the selected graphic in RSA
  2. Right-click in the graphic window
  3. Select contectual Menu...File...Save As Image File...
  4. In resulting Dialog:
    1. Select target directory of workspace\RIM-XMI\outputgraphics\
    2. Select Image format of GIF
    3. Click OK
  5. Closed the selected graphic window
  6. 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 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:

  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.

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 <p/> element a child of another </p> element;
  • placing a <ul/> or <ol/> element inside a <p/> element;
  • placing a sub-list of an existing <ol/> or <ul/> as a direct child (between two <li/> elements) rather than placing it inside the <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\:

  1. 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.
  2. 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:

  • 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.
  • toolingRepos - is just the core mif representation of the RIM, VOcabulary, data types and CMETs used to support Publishing Tooling
  • 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

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.

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

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:

  • DDDVVVVT where:
    • DDD - This value is always "rim"
    • VVVV - the HL7 Version a four-digit sequence such as "0238 for RIM 2.38
    • T - 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
  1. Start with the equivalent zip file for the preceding release.
  2. 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.
  3. rimxxxxc.zip This is the ultimate goal. Collect all of the preceding files *.zip and *.txt into this archive, and delete the predecessor archive.
  4. 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.