RMIM Designer Documentation (Vocabulary MIF)

Overview

2010/11 Updates

VocabMIF

DataTypeReleases

BatchProcess

CommandLine

Errors/Install

Vis2002-3-7-10-13

Introduction ·  Loading-RIM-Vocab ·  ConstraintSelection (ProperConstraints) ·  VocabBrowser (Controls · Searching)

Introduction

Release 4.4.0 of the HL7 RMIM Designer (in Visio) was the first release to use a vocabulary "core MIF" file as its source for Vocabulary content. The "core MIF" files (with names like DEFN=UV=VO=822-20090227.coremif) have been released along with the Design Repository in every design repository release since September 2008.

Note: It is recommended that this tool only be used on machines with at least 1 GB of memory, because the in-memory vocabulary content is large.

In the past, the designer presented you a "drop-down" that displayed a tree view of vocabulary content that was actually in mixed-mode - it combined concept domains, value sets and code systems into a single hierarchical display. This combined display was replaced because it was introducing confusion (and errors) and because it was constraining the ability to create a "clean", correct vocabulary model.

The new release opens a new "modal" window pane that displays vocabulary content as three independent tree views - one each for concept domains, code systems and value sets.

Features of the selection pane are:

• Independent tree views for the three types of vocabulary content;
• Tree views may be tiled side-by-side (default) or displayed singly on a "Tab" control;
• When opened, tree views are constrained to the relevant sub-set of content (such as ActClass when selecting a class code for an Act clone);
• When opened, the "selected" constraint in the pane is set to the previous constraint from the source model;
• Search capability to find content in the vocabulary (uses a case-insensitive search on descriptive text, names and identifiers of vocabulary content);
• Text descriptions for an element selected in a tree view may be called up for display;
• "Current" selection box shows what is the current (most-recent) selection;
• "Help" display summarizes the function of each button on the pane;
• In addition to mouse control, "Enter" key and "Esc" key will close the pane and either return a constraint (or nothing for "Esc")

These features and their use are discussed in the following sections.

Jump to top of page

Loading RIM and Vocabulary Content

As of June 2011, the RMIM Designer will accept two forms for the "source" models that hold RIM and Vocabulary content. The Model Selector Dialog was altered to change the label on the primary file and to change the rest of the display depending upon which type of file was selected.

Selecting RIM and Vocabulary Source from MIF Files Only

Model Selection Window with RIM core mif selected	Model Selection Window with "package" MIF (both RIMs and Vocabulary) selected.

With a MIF file selected, the browser drops the "Model drop-down list" and the Vocabulary file selection option in favor of one of the two displays above:

• If a RIM coremif is selected (left diagram) there are no other choices, except to accept the selection by clicking "OK". The RMIM Designer expects to find the Vocabulary coremif to which the RIM is bound in the same directory.

• If a Package MIF is selected (right panel), there may be both a data types R1 RIM and a data types R2 RIM in the package, along with the vocabulary. Therefore a selection buttons for the data types are included on the model selector pane.

Selecting RIM and Vocabulary Source from Design Repository plus Vocabulary MIF

Model Selection Window with Access Design Repository selected.

The Model Selection window was modified to allow selection of both a Design Repository file ("mdb" file) and a Vocabulary MIF file (either "coremif" or "mif" file extension.) Since September of 2008, all RIM Repository distribution have included a vocabulary "core"mif file (with names like DEFN=UV=VO=822-20090227.coremif) as part of the distribution. In both RoseTree and the new RMIM Designer releases, the associated vocabulary "coremif" file will be loaded unless the user over-rides that selection.

The simplest way to use the latest RMIM Designers is to place a copy of the design repository from the Design Repository Project on Gforge along with its associated vocabulary file in some convenient directory, perhaps the Visio solutions HL7 directory, and then start the RMIM Designer in the usual fashion.

The first pane to appear will be the Model Selection pane (right-above). This pane now includes tweo selectioln boxes. One for the Repository file and the other for the "Vocab MIF" file. You do not need to select the latter file. If it has not been selected, the RMIM Designer will look for the correct file to associate with the repository and will use that, if one is found. (It will seek your permission before using the found file.) If it cannot find a file, it will prompt you to select one. It is not possible to run the RMIM Designer without a vocabulary mif file available.

Loaded Model Dialog

Previously Loaded Model Warning

In some circumstances, activating the clone editor or "awakening" the RMIM Designer may cause it to re-load the RIM and Vocabulary. In that case, you may see a dialog box like the one at the right. Just say "NO" to this dialog. What has happened is that the vocabulary content is already in memory. In that case you do not need to replace it, and, more importantly, you do not want to because replacing it will consume another 300MB of memory!

Jump to top of page

Selecting Vocabulary Constraints

Clone Editor - Properties Pane Vocabulary constraints for RIM attributes are established in one of two ways in the RMIM designer. Both methods are done within the HL7 Class Refinement Editor as seen at right and below. This editor has two panels selected by a tab control The Properties tab is where the typeCode, classCode, moodCode, etc. are selected. The vocabulary constraints for doing this are circled in the first of the three panes at the right. The process of constraining these properties is initiated by either clicking on the associated "Browse" button, or by double-clicking on the text box that displays the constraint. The remaining vocabulary constraints are established in the Attributes tab, as seen in the second of the panes to the right. For each coded attribute, there are three "controls" a selection box for the kind of constraint, the text field that displays the constraint, and a "Browse" button. The vocabulary selector/browser can be started by either clicking the associated "Browse" button, or by double-clicking the text field. NOTE: Although the constraint type box may be changed by clicking on it, its value will always be correctly set by choosing a constraint in the browser, and thus this control is best treated as a display-only control. Finally, in selected cases it may be reasonable to set a "fixed" or "default" value constraint on an attribute. (This can only be done with attributes whose data type is CS in the RIM, or has been constrained to CV in the static model design.) When such constraints are established, a second row of vocabulary constraints that includes a code value and a code browser button are added to the Attributes tab display, as in the third pane at right.

Jump to top of page

Clone Editor - Arttributes Pane Proper Constraints by Attribute Kind The HL7 methodology specifies varying constraint expressions for the different kinds of attributes found in the HL7 Reference Information Model (RIM) and in static models derived from the RIM. Moreover, the appropriate form of constraint is different for a "universal" (UV) design or constraint than it would be for an implementation-level constraint. Simply stated, at the "UV" level constraints (with the exception of structural attributes) should be abstractions or generalizations that permit realms, projects and implementers to refine these further in order to meet the requirements of their particular design. The following sub-sections provide an informative overview of these principles to help guide model designers. The formal "rules" are embedded in other documents. Structural Attribute Constraints - classCode, typeCode, moodCode, and determinerCode The so-called "structural attributes" are those attributes in the RIM that encode design content that might otherwise have been part of the model structure. For example, a class code represents a sub-type enumeration that might have been represented as a physical class in the RIM, but was not because while it had unique meaning, it did not require unique attributes or associations. There are a total of eight structural attributes in the RIM - the classCode attributes for each of the Act, Role and Entity classes; the typeCode attributes for the ActRelationship, Participation and RoleLink classes; the moodCode attribute for the Act class; and the determinerCode attribute for the Entity class. The constraints for these attributes are unique in that they: are bound to the Code System that supports them, including a value set binding to "all codes" for the RIM concept domain constraint; are selected from the Properties tab of the Clone Editor rather than the attributes tab; are usually displayed in the model as code values, with symbols to indicate a fixed value or a hierarchy; usually do not have value set constraints, except for enumerated "x_" value sets; and commonly replace their RIM Concept Domain Constraint with either a code or value set. Governing Principles In November 2007, M&M and Vocabulary committee agreed on the following principles for defining these constraints and for managing the vocabulary content for these attributes: For each coded concept in the appropriate code system, define a value set uses that particular concept code as its "head code" and includes that code and all of that code's specialized descendants in the value set. Thus a constraint that appears to be a code constraint is actually short hand for a constraint to a predefined value set. Provide enumerated value sets, where needed, to accommodate constraints that do not align with a logical hierarchy of the code system; and Limit the concept domains for these attributes to a single concept domain that represents the RIM constraint and is bound in the universal realm to the appropriate code system - usually as "all codes" of the supporting code system. Selecting Structural Constraints Thus when selecting constraints for these attributes users should: Expect code constraints to be the dominant constraint in universal designs; Occasionally use an enumerated value set; and Never use a concept domain constraint other than the one asserted in the RIM.

Jump to top of page

Clone Editor - Attributes Pane for Fixed/Default Other Attributes with CS Data Type in RIM In addition to the eight structural attributes there are another thirty or so RIM attributes whose data type is CS. By the data type definition, these attributes are constrained in the RIM to values drawn from a single code system that can only be extended through harmonization or ballot. The principles for vocabulary content management (stated above) apply to these attributes as well. However these principles have a slightly different impact since the representation of these constraints in the RMIM iconography does not dominantly depend on a code value. This means that in most cases, the user will wish to select a value set as the primary constraint, rather than a code. Selecting Other CS Constraints Thus when selecting constraints for these attributes users should expect: Value set constraints to be the dominant constraint in universal designs; and Never use a concept domain constraint other than the one asserted in the RIM. Other Attributes Constrained to Data Type CV Occasionally, universal designs may involve an attribute that has been constrained to the CV data type, and for which there exists a universal binding of some concept domain to a particular value set (and code system). In those cases, it may be reasonable to assert a fixed or default code value as a constraint. All Other Attributes As a general rule all other attributes in universal designs should be constrained to a Concept Domain. Absent a universal context binding, all such attributes should retain the generality provided by a concept domain constraint.

Jump to top of page

Vocabulary Browser

Vocabulary Selection Window

Single Vocabulary Pane Display

Window Sizing controls

Descriptive Text Display

The vocabulary browser and selection window is patterned after a display used in RoseTree since early 2008. This display segregates the displays of the hierarchies for Concept Domains (left pane in figure at right), Code Systems (middle pane) and Value Sets (right pane). These panes are tiled side-by-side by default, but may also be displayed as a single pane. (See figure below the one at right.)

The content displayed when the browser is opened is limited to the vocabulary content appropriate to the attribute being displayed. Thus, for example, the display at right is limited to the ActClass hierarchies because it is being used to constrain the value for the classCode attribute in Act.

The primary window is made up of the browsing pane(s) above, and a set of controls for selecting content and managing the display at the bottom of the window. The controls are discussed in the following sub-section .

Selection Controls

There are nine buttons (one hidden) and a text box that make up the controls for this display. Treating these from Right-to-Left and Top-to-Bottom they are:

• Return

  Closes the window and returns the last-selected node as the result. (If a search return was done immediately before, it will return the search selection.) This action is also activated by the "Enter" key or by double-clicking on the desired node.

• Search

  Activates a text search on the displayed vocabulary content. With the search pane displayed, selecting one of the search results and pressing "Return" on the search pane will cause the tree views to "select" the result on the primary pane. Search is also activated by F3 and Ctrl-F.

• FreeHand

  Unlocks the current result text box (below) to allow manual entry of a constraint. Formats are:

  • "D:[ConceptDomainName]"
  • "V:[ValueSetName]"
  • "C:[CodeSystemName]:[CodeValue]"

• Current Result Text Box

  Displays the last selected constraint, either as the result of a manual selection or of a search. The formats are:

  • "D:[ConceptDomainName]"
  • "V:[ValueSetName]:[ValueSetOID]"
  • "C:[CodeSystemName]:[CodeValue]:[ConceptInternalId]".

  If the box displays "nothing", there is no current selection.

• Cancel

  Closes the window and returns a "nothing" result. This is also activated by the "Esc" key.

• Help

  Displays a help window that displays the meaning of all icons and has limited help notations.

• Tile View / Single View

  Switches between:

  1. a tiled view, with three trees, one each for Concept Domains, Code Systems and Value Sets displayed side-by-side (sharing the horizontal screen space) and
  2. a single, tabbed view where you select which of the three tree views to show, as seen in the second figure at right.

  Right-clicking on the tabs, or the three tree view selector buttons (in tiled view) offers to "reset" the contents of a particular tree.

• Size

  Displays and hides a frame of seven buttons that allow re-sizing of the window and the trees. This pane is outlined in red in the partial figure shown third from the top at the right. The seven buttons are:

  • "^^" and "W" increase and decrease the height of the window by 20%
  • "<>" and "><" increase and reduce the width of the window by 20%
  • "F" and "f" increase and decrease the font in the trees and result text box (limited range)
  • "*" hides the sizing options frame.

• Show Text / Hide Text

  Displays the definition or description of the currently selected tree view node. This display uses the full pane and overlays the tree views until "Hide Text" is selected.

• Dispay raw text / Render using HTML

  Is seen only when descriptive text is being displayed. It switches the rendering of the descriptive text. The raw text can be useful as a cut-and-paste source.

Searching Content

Vocabulary Search Pane

Vocabulary Search Results

Searching the vocabulary content is initiated by the Search button. This will expose another modal form from which the search is initiated. The primary search form is seen at the right. It consists of four primary areas:

1. A list of the search results

   These are displayed one "hit" per line, as seen in the second pane at right. The format for the search results is:

   • "C:[CodeSystemName]:[CodeValue]:[ConceptInternalId]".
   • "V:[ValueSetName]:[ValueSetOID]"
   • "D:[ConceptDomainName]"

2. A set of constraints.
   • The search can be constrained to return or suppress results from each of "Concept Domains", "Code Systems", or "Value Sets" as indicated by the check boxes.
   • Further, the search may be constrained to return only content related to a particular code system, plus the value sets based on that code system, plus concept domains descended from a concept domain whose name is the same as the code system name. The drop-down list is pre-populated with a complete list of code systems.
3. Search text box.

   A string entered into this box is used to search the vocabulary for a case-insensitive exact match to the string. (Thus, a search string of "aCT CLass" will match "act class" or Act class" but not "ActClass".)

   The search is applied to all of the definitions, descriptions, names and identifiers of the selected elements.

4. A set of buttons to initiate the search and return the results to the vocabulary browser. These buttons are:
   • Search

     Initiates a new search for the designated search string within the constraints listed. There is no functionality to further refine a previous search set.

   • Return

     Returns a the search set, including any selection made in the search results to the browser.

     The search set is not cleared, so that selecting search again from the browser will return to the same search set as before.

     Normally when this is selected, the browser will find the selected result in the appropriate tree and select that tree node.

   • Close

     Closes the search pane without returning a search result to the browser. This also "clears" the result set from the search pane.

Impact of Deferred Vocabulary Assembly on Searching

Vocabulary Search: Deferred Vocabulary Assembly

The addition of deferred vocabulary assembly in June 2011 impacted only one function in the RMIM Designer and RoseTree applications - the ability to search vocabulary content. Deferred vocabulary assembly is a strategy adopted to reduce the memory requirements of the RMIM Designer. Over two thirds of the memory required by the RMIM Designer is taken up simply to hold representations of the complete vocabulary. Deferred assembly simply means that the representation of individual concepts in code systems is not extracted from the vocabulary source file until a user action causes the program to require such concepts. At that time, all of the concepts of the particular code system are expanded.

This strategy affects vocabulary searching because the search process is limited to code system definitions, concept domain definitions, value set definitions, and the definitions of those concepts that have already been expanded. Thus,a search term that is matched within a concept definition will be missed if the code system that holds that concept has not been expanded.

As noted in the figure at right, it is possible to determine which code systems have been expanded by looking at the drop-down list indicated. Further, the user may choose to immediately expand all code systems by clicking the "Assemble All CS" button at the top right.

Jump to top of page