Frequently Asked Questions

Developing HL7 Applications

  1. Why are some message classes missing? For example, I can find the class ADT_A01, but not the class ADT_A04.
  2. Why is leading space disappearing from strings in my messages?
  1. I generated a conformance profile using the Messaging Workbench (MWB) but HAPI says it is invalid, or doesn't seem to be applying it.

General Questions

  1. Is HAPI ready for production use?
  2. Who else uses HAPI?

Hacking HAPI

  1. I am trying to build HAPI using Maven and it is prompting me for a JDBC URL. What does this do? What is the sourcegen module for?

Developing HL7 Applications

Why are some message classes missing? For example, I can find the class ADT_A01, but not the class ADT_A04.

HL7 defines that some message triggers reuse the same structure. So, for example, the ADT^A04 message has the exact same structure as an ADT^A01 message. Therefore, when an ADT^A04 message is parsed, or when you want to create one, you will actually use the ADT_A01 message class, but the "triggerEvent" property of MSH-9 will be set to A04.

HAPI uses property files in the following package: 

ca.uhn.hl7v2.parser.eventmap
...with the name... 
[version].properties
to determine the mapping between trigger event and message structure.
Why is leading space disappearing from strings in my messages?

HAPI's default validation settings include a rule which trims leading spaces from FT, ST, and TX fields. In fact, even the less string NoValidation rule still contains this particular setting.

See the message validation example for more information about how to disable this.

I generated a conformance profile using the Messaging Workbench (MWB) but HAPI says it is invalid, or doesn't seem to be applying it.

The most likely problem is that you have generated the conformance profile incorrectly. Try opening the XML conformance profile in a text editor, and look at the root tag. If it isn't a "HL7v2xConformanceProfile" tag, you have the wrong format of file. See the documentation for the Profile Compiler for information on how to generate conformance profile files.

General Questions

Is HAPI ready for production use?

We make no guarantees that HAPI is perfect. That said, HAPI has been in use at University Health Network for close to 10 years, and we use it almost daily in developing applications which collectively handle thousands of transactions each hour, 24 hours a day.

These applications include an eMPI system, lab and clinical document messaging systems, and various point-of-service applications used in a clinical setting.

Our best suggestion is to make sure you devise good unit tests for any HL7 messaging code that uses HAPI. This is good practise in any software development activity, but it is especially important when you are doing something as complicated as HL7 messaging.

Who else uses HAPI?

That is something we would love to know. If you are using HAPI, we are trying to compile a list, and would love to hear from you. Please email us and tell us your story!

Based on our website logs, we know that HAPI is used on all continents. A few hot spots include the United States, Canada, Brazil, India, China, and Japan.

Hacking HAPI

I am trying to build HAPI using Maven and it is prompting me for a JDBC URL. What does this do? What is the sourcegen module for?

The JDBC URL is a reference to the HL7 DB used to build the message libraries for HAPI. This DB is sold by HL7 international, and unless you have a copy of it this part of the build won't work.

There shouldn't be any reason for you to need to though, this part of the build generates the hl7-structures-vXX parts of the library, and both the source and compiled versions of these are already available.

If you are trying to build HAPI yourself (you have made modifications of some kind or want to test something), you can build HAPI using the following command:

mvn install

This skips the sourcegen modules and only builds the core library.