HL7 Tooling FAQs

HL7 Tooling FAQs

Wilfred Bonney

<wbonney@hl7.org>

Copyright © 2007 Health Level Seven, Inc.

July 27, 2007

---

Introduction

This Tooling FAQs are intended to provide general support for individuals wanting to use the HL7 tool suite. The FAQs are grouped under five themes: General, RMIM Designer, RoseTree, PubDb and V3 Generator.

General

How do I gain access to the current HL7 tool suite?

• All latest file/package releases of the HL7 tools are found in the HL7 Project Homebase, also known as the Homebase. You can gain access to the Homebase by visiting the URL: http://hl7projects.hl7.nscee.edu/. The Homebase site is intended to:

  • Serve as a central resource point for publishing, downloading, maintenance and support of non-commercial HL7 tools.
  • Provide a tool for other HL7 committees to manage project artifacts.
  • Simplify and coordinate the tooling and other committee maintenance processes by providing standardized mechanisms for requesting features, reporting defects and requesting support.
  • Support HL7 tool users in reporting issues with tools and tracking their resolution.
  • Enable release management and version control for tools and other committee artifacts.

How do I install with different Windows versions or differing versions of support software?

• An installation and configuration overview/instruction document is "under construction" on the Wiki at URL: http://wiki.hl7.org/wiki/index.php/Installing_and_Configuring_HL7_Tools. It covers questions such as:

  • Installation strategy differences between Windows XP and Vista;
  • Security settings for using the RMIM Designer with various releases of Visio; and
  • Requirements for Access and its use with various Windows XP versions.

Do I have to become an HL7 member to use the HL7 tools?

• No. You do not need to become an HL7 member. However, most of the existing tooling licenses restrict their use to the development of HL7 Standard artifacts.

Is there a tutorial on how to use the HL7 tools?

• Yes. The Tooling Committee has produced documentation called HL7 Tools: The Comprehensive Guide. You can download a copy from this Link.

Are the HL7 tools compatible with the Microsoft Vista operating system?

• Yes, provided they are installed in manner that is compatible with Vista security. Documentation for installing and running the tools is available from this Link.

  HL7 created a project in the Homebase called Vista Compatibility of HL7 Tools. This project was established to document efforts to assess and assure the compatibility of HL7 Tools (in use in February 2007) for use under the newly released Microsoft Vista operating system. You can access the project from the URL: http://hl7projects.hl7.nscee.edu/projects/vista-compat/.

How do I gain access to the newly released Eclipse-based tools?

• The Eclipse-based tools are maintained in a project in the Homebase called HTC Eclipse Tooling. This project is dedicated to providing commercial-quality highly integrated tools that support the development and implementation of HL7-complaint healthcare communication. At this time, two Eclipse-based tools (XML Instance Editor and MIF Validation Tool) have been released.

  • XML Instance Editor: An Eclipse plug-in developed by Jiva Medical (sponsored by NHS Connecting for Health). This tool allows the generation of XML Message Instances based on MIF models.
  • MIF Validation Tool: An Eclipse plug-in developed by Jiva Medical. The tool allows MIF Schemas to be validated.

  Instructions on how to download and install the tools in the Eclipse platform are available from the URL: http://hl7projects.hl7.nscee.edu/projects/htc/.

What are the licenses used by the HL7 tools?

• The HL7 End User License Agreement (EULA) can be found at the URL: http://hl7projects.hl7.nscee.edu/tc_include/hl7_eula.html.

What does MIF mean?

• MIF stands for Model Interchange Format. It is a set of XML schemas used to validate and represent any and all HL7 version 3 artifacts. The schemas use embedded Schematron rules to test conditions that cannot be tested in W3C schema. The intended uses of the MIF include:

  • Format for exchange between HL7 version 3 tools.
  • Format for import and export of all repository data.
  • Format for registration of affiliate ballot content.
  • Format for submission of HL7 version 3 proposals.
  • Format for documenting and registering application conformance profiles.

What does the terms: RIM, MIM, DMIM, RMIM and HMD mean in HL7?

• Each of these terms is a name for a type of UML static model used in developing HL7 standards. HL7 maintains a glossary of acronyms and HL7-specific terms and term-usages. The glosarry can be found at the URL: http://www.hl7.org/v3ballot/html/help/glossary/glossary.htm. For more information on these terms, see the HL7 Version 3 Guide.

What is the difference between Storyboard and Storyboard Example?

• A Storyboard is a short realistic description of a real-world process for which a message may be needed. It is written in the present tense and follows the process from start to finish. The storyboard provides a way of exploring scope, of checking what really happens, and is a basis for testing whether the information model being developed covers the particular scenario. It is also used to show the set of interactions associated with a real-life healthcare situation. It should demonstrate who is involved in the message, how they are involved, what they need to know and when they need to know it, as well as how they use computers to accomplish their tasks. It will also be part of the documentation for the finished message definition. Storyboards can be creative, but keep in mind that all functions demonstrated must be reflected in the subsequent messaging diagrams.

  A Storyboard Example is simply used to produce a storyboard. For more information on storyboards, see the HL7 Version 3 Guide.

What is a Receiver Responsibility?

• Receiver Responsibility identifies actions a receiving application must perform. It may include doing nothing and/or a set of mutually exclusive options (e.g. accept, reject or propose alternative). Each responsibility option consists of a specific response interaction and/or trigger event.

What is Cardinality?

• Cardinality specifies the minimum and maximum number of repetitions an association or attribute may have. E.g. [0..3] means an attribute must be present between 0 (not present at all) and 3 times. For more information on Cardinality, see the HL7 Version 3 Guide.

How are Clone Name, Formal Name and Fixed Name related?

• Clone Name identifies the name used for a specific instance.

  Formal Name is the name for a clone or association as determined by the HL7 naming algorithm including any suffixes.

  Fixed Name : Each clone is assigned a fixed unique name that is not changed when the formal naming algorithm is applied to a diagram. The fixed name was intended to provide for cross-reference between two diagrams where re-naming or user-naming has altered the formal names for one or more clones. However, the fixed name is not currently a valid referent.

  For more information on how these terms are related, see the HL7 Version 3 Guide.

What does CMETs mean in HL7?

• CMETs stand for Common Message Element Types. For more information on CMETs, see the HL7 Version 3 Guide.

RMIM Designer

Why does HL7 use Visio in RMIM design?

• HL7 uses Visio in RMIM design because:

  • Visio gives more flexibility in diagramming conventions
  • Visio capabilities allow for easy validation of RMIMs against the RoseTree repository
  • Visio RMIMs can be saved directly into RoseTree

Which version of Visio supports RMIM design?

• The RMIM Designer currently works with Visio 2000, 2002, 2003 and 2007.

Can I use UML in my RMIM design?

• The Visio RMIM diagramming conventions differ from standard UML conventions. HL7 RMIMs are built by cloning one or more of six key classes. UML lacks an easy way to visually distinguish the classes or to document HL7-specific constraints such as concept domain. By abbreviating some of the relationship conventions, diagrams can be made smaller and clearer. HL7 models must be submitted in the Visio format. If UML output is desired, it can automatically be derived by using the RoseTree II tool together with Rational Rose.

Why do I have to use UUDD_AAnnnnnnRRvv naming convention?

• Artifacts are uniquely identified to avoid conflicts/duplicates between committees or working groups.

  Artifact types and responsibilities are clearly defined and understood from the name. This increases accuracy and efficiency in ensuring that correct artifacts are published properly. It also enable high volume of artifacts and submissions being received from many committees to be coordinated centrally by publications.

  A future release of the tools will revise the artifact naming convention to allow assigning of identifiers by organizations other than HL7 and its affiliates.

How can I use my code system name or OID in the RMIM Designer? When I use them, the designer fails to validate the model.

• It will give a validation warning because the code system has not been registered in the HL7 RIM yet. All code systems need to be registered with the HL7 OID registry. Unfortunately at the moment, not all of these are propagating into RoseTree. Make sure your code system is registered, and then ignore the warning.

What is the purpose of entry points on RMIMs and DMIMs?

• Entry points indicate where model serialization should start ( i.e. What is the root/top-most element?). For RMIMs, there will only ever be one entry point. For DMIMs, there may be more than one entry point if the RMIMs derived from that DMIM might start from different classes.

What is the difference between Required and Mandatory elements?

• Required elements must be supported by an application, but don’t necessarily always need to be sent (i.e. application must send it if there is a value, but there won’t always be a value).

  Mandatory elements must always be sent (or defaulted). They must never be null. Mandatory elements are always Required.

What is Blocking?

• Relationships can be ‘blocked’. This means that the path cannot be walked when turning an RMIM into an HMD. The ‘blocked’ indicator is always on the side of the relationship where cardinality for that association is displayed.

How do I achieve Renaming?

• Renaming is an automated capability of the Visio templates which assigns new clone and association names to the diagram. It comes in two forms:

  • Process Renaming is invoked through the Visio menu system as “Rename shapes” and will systematically review the names for each shape on one or more pages. This should always be run just before a design is saved to the repository.
  • Dynamic Renaming is invoked whenever a new shape is “dropped” on the diagram, or when the property dialog box is used to alter the class, type or mood codes for a clone. Dynamic naming is intended as a design assist. It should always be followed by complete process renaming before a design is saved in the design repository.

How do I ensure that the connection glue is correct in my RMIM design?

• In Visio, the “color” of the connection changes from green to red if connected. If a connection point is green, then the tool will not recognize the shapes as connected, even if they visually appear to be connected. This will affect validation, saving to RoseTree, etc.

What is a Shadow?

• This is the name given to a duplicate clone. Duplicate clones are two or more clones that have the same names, attributes and structural attribute values as each other. They are created to simplify the layout of drawings by having a single concept appear in several places. The renaming process requires that the formal name and fixed name be the same for each member of a duplicate set, and that all but one of these be designated as a shadow.

What is a Traversal Path? What constraints are associated with it?

• Traversal Path is a path or route through the RMIM from one clone to another. It represents a trace along one or more associations in the HL7 RIM. The traversal path represents movement in one direction from clone to clone. Each traversal path is the basis for one or more association names in the RMIM. Traversal paths are represented in HL7 clone shapes in several ways.

  • Terminal shapes: The following shapes contain no traversal paths, but rather are linked by other shapes that do contain traversal paths: Act, Entity, and Other Class
  • Direct traversals: Two shapes represent direct traversals. The Role shape includes four direct traversals – to and from Entity for each of scoping and playing. (Role is also a terminal shape with respect to RoleLink and Participation.) The Misc Association contains two direct traversals, one in each direction between the clones that represent its source and target. A direct traversal carries a single association name, the name that appears as a property of the source or target RMIM clone, respectively.
  • Via traversals: The remaining shapes for Participation, RoleLink, and ActRelationship each contain two “via traversals”. In these shapes, the traversal starts from one clone (Act or Role) go through (via) the shape and goes to the ending clone (Act or Role). Each via traversal carries a pair of association names. One is as the property name in the clone that the traversal starts from, and the other is the name that appears in the “via” clone (ActRelationship, RoleLink or Participation)

  Traversal Constraints: Each traversal is characterized by one or more constraints on how the traversal will be named or used. These include the following:

  • Names: The association names are determined algorithmically and cannot be altered by the user.
  • Mandatory: Indicates that the element (property) representing this traversal will be “Mandatory” in HL7 messages based on this design.
  • Required: Indicates that the element (property) representing this traversal will have a conformance value of “Required” in HL7 messages based on this design.
  • Multiplicity: Represents the multiplicity that the element (property) representing this traversal will have in HL7 messages based on this design.
  • Enabled/blocked: A traversal path that is enabled may be traversed when the RMIM is “walked” to create an HMD. A path that is not enabled is blocked.

RoseTree

What will happen if, in opening RoseTree, I load All HMDs to XML?

• This is a shortcut used in the publication process to quickly open each of the HMDs and export the contents to XML. Because this is a time-intensive task frequently done as part of the ballot publication process, it has been automated.

How do I browse the vocabulary content of the RIM from RoseTree?

• You can browse the vocabulary content of the RIM by following these steps:

  • Load the selected RIM into RoseTree by going to the File menu and clicking on Open, and then browsing to where you installed the design repository
  • After successful loading of the model, click on the View menu and select Vocabulary to see the domain tree. Note that you can invoke the vocabulary icons by clicking on the Help menu and selecting the Vocabulary Icons.

How do I extract an XML expression of the RIM from RoseTree?

• RoseTree limits you to having only one window of each kind (RIM, RMIM, HMD) open at a time. Note that each window type has its own icon in the upper right corner of the window. You can extract the XML expression by following these simple steps:

  • Load the selected RIM into RoseTree by going to the File menu and clicking on Open, and then browsing to where you installed the design repository
  • After successful loading of the model, go to the File menu and click on the Export to, and then select the XML-Expression. You will be presented with a dialog box with RIM options to extract. Select the required options and click on the OK button to extract the XML expression of the RIM.

PubDb

Do I have to worry about using Structured Sort Names (SSN) for my topics?

• The HL7 Publication Database (PubDb), allows material to be segregated into topics. Each topic is assigned a title name and a sorting name. As artifacts are defined within the PubDb, they are given a structured sort name that begins with the sorting name of the topic to which the artifact belongs. In this fashion, the PubDb assembles material for each topic. There are couple of rules for defining the sorting name and the sort order for these topics that should be articulated. The first of these rules has been stated previously. The second one has recently been "discovered". They are:

  • Within a given domain, none of the strings used as the "sorting name" for a topic, may begin with the characters that make up the whole of another topic's "sorting name.
  • If a domain has a secondary domain (such as for queries or master files), the sort order string for each topic in the secondary domains, must be identical to the sort order string for the same topic in the primary domain.

Can I turn off the SSN Sorting?

• Yes. You can turn off the SSN sorting from the main PubDb screen. This will cause the database to cease sorting the records, but it will not affect sorting when the material is published. This may be useful as it stops the PubDb from automatically forcing you to the first item in the list every time you edit an artifact.

How do I build multiple topics in PubDb?

• The Topic tab, within a domain in the PubDb controls the topics that appear in the ballot. You associate artifacts with a particular topic by creating a structured sort name for the artifact that uses the topics name. The first pull down in the structure sort name dialog box for artifacts lists all the available topics. Topics that have artifacts associated with them via structured sort names will appear in the ballot.

  Artifacts like application roles, trigger events, message types, interactions can all be used across topics within a domain, no matter what topic they are defined in, as long as all those artifacts are contained in the same publication database.

I have installed Altova XMLSpy on my machine. However, I keep getting the error: “Unable to open Spy. Choosing simple text editor instead.” What should I do?

• You can avoid this error by making sure that you start the XMLSpy program first before double clicking on the text to edit. You can also edit your text directly on the pop-up window if you are comfortable with it.

When do I use DM and/or DO as domain artifact code?

• DO refers to the domain itself, e.g. Patient Administration (PA) is a domain (DO).

  DM refers to the DMIM (Domain Message Information Model) for a domain.

In the data entry to the PubDb, am I required to have DM and/or DO as artifact code?

• The DO is defined "within" the domain, and yes, a DM is "required" although this requirement is not enforced in the PubDb.

How do I migrate an old PubDb?

• The instructions are as follows:

  • Create a directory C:\Temp on your system.
  • Place a copy of your old PubDb in that directory, and name it temp.mdb
  • Open a fresh copy of the new (Version 200 or later) and click on one of the two Migrate Full DB buttons, depending on your version.

Where can I find the HMD’s and MT’s?

• These artifacts are part of a containment hierarchy that says an RMIM may be the basis for (contain) one or more HMDs, and an HMD may include the definition for (contain) one or more MessageTypes. Therefore, you can only find the HMDs and MTs when you edit the RMIM's tab. You need to follow these steps:

  • Select a domain in your PubDb that you want to edit
  • Click on the Edit Domain button next to the chosen domain
  • Select the RMIM's tab
  • Click on the Edit RMIM button and you will see the HMD's form
  • Click on the Edit HMD button and you will see the MessageType (MT's) form.

Where is the DMIM descriptive text?

• You can find the DMIM descriptive text as follows:

  • Select a domain in your PubDb that you want to edit
  • Click on the Edit Domain button next to the chosen domain
  • Select the RMIM's tab and then look for the entry that has isDMIM checked
  • Click on the Edit RMIM button and you will see HMD's form with the descriptive text of the DMIM above

When you do the local publishing, you are required to put the images in a specified folder. Is there any naming convention to follow for the images?

• Yes, for ST, DM and RM graphics, the name should be the artifact ID then dot (.) gif. For example, POLB_ST000000UV01.gif will be used for a storyboard’s gif image.

Under what condition(s) are you required to export the publication XML file from the PubDb and place it in the DynamicModelFiles folder of the V3 Generator?

• If you are running the V3 Generator for your own use, the exported file is required to define Interaction schemas. It is not needed for just the message type schemas.

Publishing (using PubDb) and V3 schema generation (using V3 Generator), which one need to be done first?

• The PubDb extract for the interaction schemas should be run first. Usually, an individual does not publish the documentation, but rather it is done by HL7 Headquarters (HQ). The HQ process has a number of interdependent steps. The actual publishing follows steps like creating clickable graphics, running the generator, etc. but the extract of the XML file from the PubDb is very early in the process.

V3 Generator

Does V3 Generator works with all JRE Versions?

• Prior to release 3.0.1, the V3 Generator required JRE Version 1.4.2_03. Effective with releases later than 3.0.1, the Generator should be run with JRE Version 1.5.0_10 or later. The later releases may work with earlier Java release, but have not been tested for this. JRE Version 1.5.0 may be obtained from the URL: http://java.sun.com/javase/downloads/index_jdk5.jsp. Ensure that the JRE is on the classpath. (For instructions on how to do this in Windows, refer to this link.

How do I check which JRE Version is running on my machine?

• To check the JRE Version that is running on your machine, simply start your MS DOS program (Assuming you have installed Java in your C: directory) and type the command:

  C:\>java –version
  
  The output will look similar to:
  
  java version "1.5.0_10"
  Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_10-b03)
  Java HotSpot(TM) Client VM (build 1.5.0_10-b03, mixed mode)
  
  C:\>
  
  This output indicates that JRE Version 1.5.0_10 is running on the machine.
  

What needs to be modified in the configuration.txt?

• For instructions on how to do this on Windows, refer to the documentations that came with the V3 Generator installation. For example, if you installed V3 Generator release 3.0.4 in the recommended folder (i.e. C:\Program Files\HL7\) then you can find the documentations in the folder path C:\Program Files\HL7\v3Generator-3.0.4_20070321\Documentation\

If I want to generate schemas with “local CMETs”, is there more to be done than putting the relevant HMDs in the CMET input folder?

• You will also need to be sure that the CMETs are in the cmetInfoExport.txt file. The Generator uses this file as a reference for binding CMET names to their identifiers. To ensure the ballot publishes properly, they need to be in the “official” cmetInfoExport.txt, not just your own copy. Discuss your local CMET requirements on the CMET listserv to ensure the official version is updated.

How does one get UV, UV01, UV02, to appear in the schema names as an element within the schema? When I run on my own, these do not seem to be appearing?

• To get the UVnn, you should set the dropUVnnFromFileNames parameter, in the configuration.txt file, to false (as shown below).

  
  # dropUVnnFromFileNames: true/false
  #   added to support publication of first Edition(s)
  #	If true, causes version code ('UVnn') to be dropped when
  #   creating *-NoEdit.hm (table view) and *.csv (Excel) files
  #   and also suppresses these within these files when generating 
  #   references to these files and to the rmim *.htm files.
  dropUVnnFromFileNames = false
  
  

What should I do with all the generated schemas?

• Usually, you will need to select the schemas that are specific with your requirements (including any schema dependencies). The generated schemas can be used:

  • As a mechanism for communicating the specification (though not all information will be exposed)
  • To validate instances
  • To generate code
  • As a guide when constructing examples and test cases