saxxonpike / nextlevelseven

A fast and simple library for Health Level Seven (HL7) v2 messages.

NextLevelSeven

A class library for parsing and manipulating HL7 v2 messages, designed to be fast and easy to use. There's a few things you should know:

1. This library targets Microsoft .NET Framework version 4.5 or .NET Standard 2.0
2. This project is not affiliated with Health Level Seven International, the developers and maintainers of the HL7 v2 standard
   • Their website is located at https://hl7.org/

License

NextLevelSeven is available under the ISC license. It would be greatly appreciated (but certainly not required) to link back to this repository if you use this in a project.

Usage

This library was designed to have a small footprint and rely on the smallest number of external resources.

Element Heirarchy

Before working with messages, you'll need to know what's inside what. The heirarchy looks like this:

• Message
  • Segment
    • Field
      • Repetition
        • Component
          • Subcomponent

A Message is an atomic unit which contains the others. It is the root element and does not have ancestors.

The first Segment of a Message must be an MSH Segment. The MSH Segment must contain Fields 1 and 2, which are the Field delimiter and encoding characters respectively. Each Segment must contain at least one Field, the first of which is the Segment type. Besides these required components, everything is optional.

All of these elements have indices beginning with 1, which matches the HL7 standard. However, the Segment type can be accessed by a Field index of 0, and is the only time an index of 0 is valid.

Messages

There are two ways you can handle an HL7 message: building and parsing. Both methods provide the same functionality from the top down, but are fundamentally different on the inside.

Message Builder

If you are creating a message from scratch, using a Message Builder is the way to go. Memory is allocated as you populate segments and fields. When you're done building, the message can be exported to a string.

// create a message builder with the default MSH segment
var builder = Message.Build();

// create a message builder with existing content
var builder = Message.Build(@"MSH|^~\&|ABCD|EFGH");

Message Parser

If you're working with a message that already exists, but you only need information from a few fields, using the Message Parser is a better choice. Instead of allocating memory for each distinct piece of the message, the parser uses cursors to extract the information you're looking for. The benefits of this method really start to add up when your messages are very large.

// create a message parser with the default MSH segment
var parser = Message.Parse();

// create a message parser with existing content
var parser = Message.Parse(@"MSH|^~\&|ABCD|EFGH");

Field Access

No matter if you're using a message parser or message builder, you have complete access to every bit of data in a message. Accessing elements is a breeze. You can access them either as indexers or as an IEnumerable for use with LINQ.

Here are a few examples:

// first segment in a message (returns IElement)
var mshSegment = message[1];

// alternate way to get first segment (returns ISegment)
var mshSegment = message.Segment(1);

// LINQ works on just about everything
var mshSegment = message.Segments.First();

// 1st segment, 9th field, 1st repetition, 2nd component (returns IElement)
var messageTriggerEvent = message[1][9][1][2];

// 1st segment, 9th field, 2nd component (returns IComponent)
// note: the 1st repetition is implied in this format unless specified
var messageTriggerEvent = message.Segment(1).Field(9).Component(2);

// get the first PID segment
var pidSegment = message.Segments.OfType("PID").First();

Write Limitations

Both the parser and builder have the ability to read from any field and will give you identical results given identical input. However, a builder has the ability to change encoding characters while a parser does not. If you need the ability to change MSH-1 or MSH-2 for some reason, you must use a builder.

Type Conversion

If you need to access an element in a message of a type other than a string, built-in conversion methods are very easy to access.

// get the message timestamp (returns DateTimeOffset? type)
var dateTime = message[1][7].Converter.AsDateTime;

// get the message sequence number (returns decimal)
var sequenceNumber = message.Segment(1).Field(13).Converter.AsDecimal;

Manipulation

Sometimes, you might want to modify an existing message. Using either a Builder or Parser, you can do just that. This functionality works on any IElement!

// make a field null
message.Segment(1).Field(3).Nullify();

// delete the second segment of a message
message.Segment(2).Delete();

// insert a component value at the beginning of MSH.18
message.Segment(1).Field(18).Component(1).Insert("ASCII");

// move the third segment before the second segment
message.Segment(3).Move(2);

// an alternative way to move a segment within a message
message.Move(3, 2);

Development

Any help is greatly appreciated! Here's what you need to know...

Testing

The project has successfully been moved to NUnit. Currently, version 2 is being used. The tests do use ExpectedExceptionAttribute which is not supported in version 3. FluentAssertions is also used for testing. Moq is planned to be used for mocking in the test framework.

Pull Requests

When you've got something to contribute, and tests pass, put in a request and I (SaxxonPike) will review it. After a quick review, if everything checks out, I'll bring it in. Thanks for your interest!

nextlevelseven's Issues

Handling Escape characters

I'm evaluating your library for performance and wow it's good. One issue I've encountered however is handling of escape characters. For instance \T\ should evaluate to &. I was thinking this should happen in the converter but I don't see how yet. Can you point me in the right direction? Or if you don't handle this, could you offer a suggestion on the best way to do so?

Here's a link to some of the accepted escapes https://docs.intersystems.com/latest/csp/docbook/DocBook.UI.Page.cls?KEY=EHL72_escape_sequences It doesn't appear as if there are too many.

Add NetStandard 2.0

Hey,

Question - I'd like to add NetStandard support for your library. I've already done all the work to add multi-targeting to your library. Would you be ok with that pull request? The actual change is simple, I did have to reconfigure the test project but all tests are passing in both full .NET Framework and .NET Core now.

Bump up .NET Framework target to 4.6.1?

Now that we're targeting .NET Standard 2.0, it will greatly simplify things if we also bump the .NET Framework to at least 4.6.1, according to Microsoft:
https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/cross-platform-targeting

Thoughts?

Nuget Package

Hi, it would be great if Nuget package is published.

Thanks