Navigating the pitfalls: Implementing HL7 version 3
The contents of this whitepaper are public domain.
for the latest version of this document.
Editor: René Spronk - Sr.Consultant, Ringholm bv
Document status: Draft, version 0.9 (2006-12-28)
Please sent questions and comments to
The amount of implementations of the HL7 Version 3 standard, whether in the form of HL7 messages or the HL7 Clinical Document Architecture (CDA), is steadily increasing. This whitepaper contains a number of recommendations for implementers of HL7 version 3 artefacts. It is based on the experiences of actual implementers.
In September 2005, after 10 years of development, HL7 version 3 (V3) has been released for the first time in the form of the “Normative Edition 2005”. HL7 V3 is being adopted right now to support: large scale integration (state/province, region, country), public health, decision support, and research.
HL7 V3 is the standard of choice for countries and their initiatives to create continuity-of-care oriented national EHRs - it provides a level of semantic interoperability unavailable with previous versions and other standards. Significant V3 national implementations exist in many countries, e.g. in the UK (the English NHS), the Netherlands, Canada, Mexico, Germany and Croatia. Within the US, jurisdictional agencies needing support for large scale integration (e.g. CDC, FDA) have adopted V3.
This document aims to describe the most important lessons learned from these early implementations. Some of the recommendations may sound "obvious" to you; this may not necessarily be true for other implementers. Semi-random numbers have been assigned to the recommendations for reference purposes only.
2. Pitfalls - and: how to navigate around them
This paper contains a series of recommendations related to issues or pitfalls discovered by implementers of HL7 v3 artefacts. They have been grouped for your convenience: Organizational issues, Development issues, and Framework issues.
2.1 Organizational Issues
This section contains recommendations related to the organization or project that is responsible for the implementation.
100. Overcome steep learning curve
Approaching a new subject area when implementing a complex project can be quite a daunting prospect in any situation, but what if that subject area is an emerging standard such as HL7 V3? Over the years since its inception, HL7 V3 has developed an aura of mystery and impenetrability which is little helped by the fact that a large proportion of HL7 V3 knowledge and expertise is held in the heads of a relatively small number of specialists.
- Make sure to invest both time and resources in the initial phase. The cost to entry is significant, however once you know the basics it is relatively easy to extend. The HL7 object model introduces complexity for simple messages on the one hand, but provides a unified model for complex clinical messages.
- Use the introductory presentations on the HL7.org website (although these are fragmented at the moment, have inconsistent design/presentation, are confusing when read "out of context", and some are quite old).
- Read Understanding Version 3 (the primer) - Go to the HL7.org Bookstore [HL7bookstore]. Those who started working with HL7 before the primer was available agreed that they would have benefited a great deal from such a resource. The primer is a good introduction to the basics, but it doesn't contain enough detail to be very helpful in terms of actual message design and implementation. Such a level of detail is out of scope for that document, but a more practical follow-on artefact would be very useful for message developers. Most agreed that although literature is unlikely ever to be as helpful as hands-on experience and learning from peers, it is very helpful in terms of topic familiarisation and as an aid for learning the basics.
- Use a (Framework-) Implementation Guide (one single domain within the implementation guide) as a starter document for those new to v3, and not a Normative/Development Edition. The implementation guide describes a relatively small and selfcontained subset of the standard and is implementation oriented, which makes it easier on the reader. Study the examples as provided in (or: with) the implementation guide.
The Normative/Development Editions are useful at a later stage. It is an important resource, although it may not be terribly useful in the early stages of learning; it is not a 'beginner's guide' and is not intended to be such. Within the package, start with reading the V3 guide. Then read the sections on data types (the XML ITS Datatypes specification, not the Abstract Datatypes section), the RIM, messaging infrastructure, and the domain sections that cover the application or applications of interest. Read the data types section with great care.
- Have one or more HL7 v3 experts on your team. They play the role of catalyst and keep the rest of the team on track through peer review and collaborative design. Having people around (or at least easily contactable) who know V3 and can provide advice and guidance to newcomers regarding design decisions, tooling 'features', standards compliance and so forth is more valuable than mountains of literature.
- Attend HL7 training outside of normal peer-based learning.
- Hands-on experience is probably the most effective way to learn quickly and to retain the knowledge.
- Use the contents of the HL7 Wiki [HL7Wiki], especially for areas such as Lore. It presents a consensus of ideas in plain English (as opposed to standards-speak).
- Familiarity with healthcare workflows, as well as messaging in general is a plus.
- HL7 is an open community, which allows for Peer Knowledge Transfer, between countries/organizations. Avoid re-inventing the wheel.
120. Exchange experiences with other v3 implementers
The exchange of experience in a forum with other implementers/vendors saves money. HL7 affiliate organizations offer a platform for such a forum.
2.2 Development Issues
This section contains recommendations related to the architecture of the implementation.
220. Support OIDs/UUIDs within the application.
Don't try to map local codes to other code sets in the integration layer. Only the generation of non-persistent object identifiers can be outsourced to middleware. OIDs/UUIDs have to be supported by the database of the core application.
OIDs/UUIDs are new for most implementers/vendors an may have a significant impact on the application.
It's a sure sign implementers haven't understood the concept of OIDs (i.e. why they are of importance) if one sees implementations that use the exact same OIDs as contained in example messages provided with the documentation.
225. Consistent OID use when migrating data.
Ensure that all Identifiers (including identification of the ID schemes) are persisted when migrating data from one application to another one. "Renumbering" (changing the identifier of objects) can only be done if the original IDs are linked to the new ones. Systems other than the one whose data is being migrated may have stored identifiers (e.g. of clinical data, for later reference). These identifiers have to be persisted, or the object effectively won't be available anymore. In short: persist current identifiers, do not use a renumbering scheme nor change the OID of the identification scheme.
230. Don't assume v2 - v3 mapping can be done at the integration layer
If your application already supports HL7 v2: HL7 v2-v3 migration by means of a mapping is problematic. The main problem is not the mapping itself (although HL7 v3 is much more detailed than HL7 v2), but the behaviour of the application. This is mainly a business flow issue.
The dynamic behaviour and trigger events in V2 and V3 are sufficiently different, that your application
behaviour will need to map on to them differently.
If your application has to support both HL7 v3 as well as HL7 v2: create a new communication module for the HL7 v3 messages/documents, and use it in parallel to the HL7 v2 communication module.
240. Multi version support in the application
Do allow for the support of multiple model-versions at the same time; not just in terms of transformations of the intermediate XML based format, but also in terms of database structure and application functionality. Create application behaviours which can be easily changed/upgraded/switched.
245. Adopt HL7 v3-like models within the application
Create a static model for your database - for that is what you're communicating about.
In as far as possible the physical data model of your application should follow the HL7-models.
This doesn't mean one should implement the RIM or v3 models as a database structure (although you might follow it selectively),
indeed it is unlikely that a interoperability architecture is directly
appropriate for use as an application architecture, but there should be
a strong and actively maintained relationship between them.
This is especially true when one is developing an entirely new application. Using information models defined by standards (e.g. HL7 RIM) as a starting point (a) makes messaging easier, (b) re-uses the tremendous modeling effort and review has gone into their development (i.e. hundreds of man/years). Your application’s information model will generally be a superset of the standard Message Information Models.
It is relevant to note that HL7 was not developed as a tool for application development. It was developed as a tool for standardizing the exchange of information between systems. However, many of the insights created within V3 will prove useful in application development work.
The important point is to have a clear mapping from the physical data
model onto the logical data model (e.g. D-MIM, R-MIM), and from the triggers used by the application to those used in the interfaces.
282. Data Type: NullFlavors.
Given that HL7 stresses the importance of semantics, NullFlavors can be used in almost all datatypes. If the use of a nullFlavour has not been explicitely disallowed in the standard or in the applicable implementation guide, then one has to take care to develop the code to deal with the receipt of nullFlavours. Receiving a nullFlavour essentially means having to "throw an exception" to handle it.
290. Obsolete CDA Documents.
When CDA documents become obsolete, (by reason of context) all data which may have been extracted from that document (e.g. Level 3 constructs) become obsolete.
The fact that a document has become obsolete/nullified may be conveyed by various mechanisms, e.g. a medical records message. Consideration should be given if, and how, any data known to be derived from that document should be dealt with. A recommendation may be given in the forthcoming CDA Release 3 specification.
2.3 Framework Issues
This section has been given the title "Framework Issues". The Framework being referenced is defined to be the set of message and infrastructural specifications and business rules as defined by an inter-organizational body; either at a regional or national level. Examples include the English NPfIT Program, or the Dutch National Infrastructure. The Framework is mostly published as a set of implementation guides. Implementation Guides represent the HL7 standard profiled for the specific Framework use cases.
300. Understand the architecture and the message flow of the Framework
Makes sure both you as well as the application users understand the architecture, the business rules as well as the message flows as described in the Framework.
310. Being conformant to a Framework has consequences for internal interfaces
The applications within the organization need to support the business models as defined by the Framework. The Framework therefore has a serious impact on the HL7 version 2 (and other) interfaces within an organization. HL7 version 2 interfaces are likely to be used for many years to come. There is a requirement for more rigour in the use of HL7 v2, as HL7 v3 is much richer in content.
All of the above means that one shouldn't/can't ignore the "internal" interfaces if inter-organizational v3 interfaces are added to an application. i.e. one may have to change/improve the existing v2 interfaces.
330. Maximize the utilization of registries
If the Framework architecture contains registries for patients, care providers or insurance details, retrieve the latest available data from these registries before including it in outbound messages or documents.
350. Support multiple versions of interactions
The Framework is likely to periodically publish new versions of existing interactions. During a specified transitory phase an application will need to support multiple versions of an interaction. The underlying business process for different versions of an interaction may also be slightly different.
[HL7Bookstore] HL7 Bookstore at https://www.hl7.org/library/bookstore/
[HL7Wiki] HL7 Wiki, http://wiki.hl7.org
(antispam: username= wiki , password= wikiwiki)
http://wiki.hl7.org/index.php?title=Implementation_FAQ Hl7 v3 messaging implementation FAQ
http://wiki.hl7.org/index.php?title=CDA_FAQ HL7 CDA Implementation FAQ
About Ringholm bv
Ringholm bv is a group of European experts in the field of messaging standards and systems integration in healthcare IT.
We provide the industry's most advanced training courses and consulting on healthcare information exchange standards.
or call +31 33 7 630 636 for additional information.