Navigating the pitfalls: Implementing HL7 version 3.

The contents of this whitepaper are public domain.
See 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.

1. Introduction

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

110. Need a “keeper of the vision”
Designate one person to keep the architecture and the business requirements (as a whole) on a consistent track. Otherwise scope creep will ensure they are disjunctive.

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.

130. Dealing with being an early adopter
If the scope of your implementation is broad you should anticipate being an early adopter of the Standard and breaking new ground. It’s worth it, but you must factor into your plans a steep learning curve; ongoing participation in the HL7 organization to move your designs through membership approval; and retrofitting of early installations to the approved specifications.

2.2 Development Issues

This section contains recommendations related to the architecture of the implementation.

200. Create site-specific use-cases and storyboards
Document the existing workflows and business rules before choosing what HL7 v3 artefacts to implement. This could be done in the form of unstructured examples of existing data transports. These can subsequently be mapped to existing HL7 v3 artefacts. The mapping between business-events and HL7-events is often not a 1 to 1 relationship. This should be the first step in *any* implementation; it precedes the development of applications and interfaces. Actors: business experts, domain experts, messaging specialists and software architects.

210. Don’t have native HL7 version 3 support in the application itself
Specifications evolve. Do add a layer of abstraction, in the form of an intermediate XML based format, and map this to HL7 v3 artefacts, e.g. with the aid of a stylesheet. The structure of the intermediate format should be the best possible mix of the internal database format and the model used by CDA/Clinical statements.
Alternatively, use a third-party broker that hides most of the HL7 v3 complexity behind an easy to use API. In this case the API acts as the “intermediate format”.

If you are working with XSLT you need to define an intermediate XML format for your data. This can be in “close to HL7” form or in “close to native” form. It’s normally sensible to quickly export your data in a near-native format, and then encapsulate just the HL7 specifics in the XSLT. This means you can target various HL7 messages from the same intermediate file format by varying only the transform.
You also need to decide which parts of the end to end data processing are done while your application creates the intermediate XML and what is to be done afterwards in XSLT. Some tasks are better handled by traditional compiled languages. Converting between coding systems, for instance, needs large datasets and not well suited to XSLT. You should probably convert clincial codes (eg. from UK Read code to SNOMED CT) using your application code or stored procedures. Conversion of dates to HL7 formats can be done in XSLT but it is fiddly and may be slower than converting at the point the data is written to intermediate XML. Aim to produce an intermediate XML that is suitable for restructuring into HL7, but that no longer requires a lot of complex processing.
Although this approach is architecturally sound, there are performance issues associated with it. As such its a tradeof between performance and flexibility.
Another thing to bear in mind is that error handling is very tricky in XSL. XSLT tends to be a one-shot process that either succeeds or fails, and it isn’t easy to recover from error conditions or interact with the user in the middle. It’s often best to deal with any likely exceptions in procedural code when targetting your intermediate format, and do just the final rendering into HL7 in the XSLT.

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.

250. Migrate to unified Identification schemes
For the identification of for key entities such as patients, providers, organizations, aim to use 1 identification scheme over time. This may require that one starts to use (national) identifications as primary keys, without assigning application specific identifiers to these entities.

255. By default message(fragments) should not be regarded as persistent objects
A Message(fragment) by default is transient in nature and not a piece of persistent data. If you treat messages as persistent objects, document such a decision early and be aware of the consequences (e.g. identification issues because of business IDs instead of snapshot IDs in messages).
The situation where one application regards the data in a message as persistent whereas another does not has to be avoided at all cost. If the contents of a message are regarded to be non-persistent then it should be semantically evaluated by a receiving system and imported into the appropriate database structures of the application. Keep in mind that there will probably still be a need for the versioning of data, based on point-in-time.

260. Receiving artefacts is much more difficult than sending them
Getting the semantics right on the receiving end, especially for Clinical Statement based HL7 v3 artefacts, takes a lot of effort. Make sure to get a detailed specification and lots of examples from the sending side.

265. Logging of transmissions
A robust tracking and logging system, which logs everything (including wrappers etc.) that which is actually send/received is crucial.

270. Rollback the process if message fails
If a real-time interaction fails (after timeout) roll-back the message and the transaction; and ask user to repeat the action later. Use an in-sequence reliable delivery method to minimize transactional issues.

275. Keep synchronization of data under control
Make sure to think about the process of keeping the data synchronized. This requires that one supports various synchronization methods in HL7 (snapshot, update mode). The queuing of updates by various parties if the network is down has to be taken care of. Increase your reliance on queries; they ensure you have the latest data.

280. Order in Names and Addresses.
When parsing a XML ITS based instance of a v3 artefact, please keep in mind that there are a few datatypes in v3 where the order of the elements is of importance (e.g. names, addresses). This effectively precludes you from using things like XPath expressions. A small snippet of custom code is required to correctly parse them. Note that the “mixed content, ordered” nature of names and addresses is a result from the definition of the underlying abstract datatypes and not just of the XML ITS.

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.


Advertisement for Ringholm training.


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.

315. Address how non-Framework flows will co-exist.
There will be existing interfaces that are not consistent with the framework that need to be maintained, and there will also be flows for which there is a “bottom-up” business rationale that are not supported by the framework. This does happen and needs to be managed, ideally in a way that can cleanly converge with the framework. The use of open standards are critical here. Also clear Information Governence rules need to be available to set realistic requirements on such flows. If this is not recognised then there will be too much pressure on the framework to deliver everything, and too much dependance on the framework to meet short term tactical needs.

An issue may occur if (on the initiative of providers and/or vendors) an extension of the Framework is created, which is not “accepted” as such by the Framework organization. The Framework organization may have other priories (or may not have the budget) to do a full accreditation of the extension. This means the extension ends up being used in paralel to the Framework infrastructure, and that one can’t use the transport infrastructure nor registries (e.g. patient/provider registries) as present under the Framework. This may cause a duplication at the infrastructural level.

320. Avoid “lock-in” of the application into a separate VPN
Intra-organizational communication requires a secure environment. In order to guarantee a secure environment a Framework may specify that all communications have to take place using one specific VPN network. This creates a conflict with the need to have access to corporate network (or internet access in general), e.g. for the ordering of supplies. Such issues have to be resolved with the organization responsible for the creation of the Framework.

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.

340. Get knowledge about security issues
For many IT vendors in healthcare, security requirements for inter-organization communications are a new topic. Familiarize yourself with the security aspects of the Framework, as well as with other commonly used standards in this area.

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.

3. Acknowledgements

We’d like to thank the various HL7 v3 implementers for their feedback on this document.

4. References

[HL7Bookstore] HL7 Bookstore at
[HL7Wiki] HL7 Wiki, (antispam: username= wiki , password= wikiwiki)


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, mentoring and advice in integration standards and technologies.
See or call +31 318 589 789 for additional information.

One Response to Navigating the pitfalls: Implementing HL7 version 3
  1. Now we know who the selnbise one is here. Great post!


Leave a Reply

电子邮件地址不会被公开。 必填项已用*标注