Medi7 Design
....................................... |
|
|
 |
| |
Mailing Address:
................................................
|
| |
8 Woodvue Road
Windham, NH 03087
................................................
|
| |
info@eversolve.com
................................................ |
| |
Copyright © 1999-2002
[]
................................................ |
| |
|
|
|
.......................................................................................................................
-
Medi7 Parser Toolkit:
Overview
-
Segment Groups
-
Message
Types/Trigger Events
-
Messaging Parsing
-
Message Validation
-
Message
Definition File
-
Message
Profile Format
-
Absolute Names
-
Object Model
The Medi7 HL7 Parser is
designed to simplify the task of exchanging HL7 messages
between
disparate, loosely coupled applications and devices. One of the major hurdles in integrating HL7
into an application is the parsing of an HL7 message that has
been received over the network. Another major difficulty is
being able to clearly identify the messaging requirements
because HL7 leaves many decisions up to site specific
negotiations.
The Medi7 Parser provides a simple to use
mechanism to access information in a message using a meta-data
approach. It also allows for full configurability of messages
along with specifying validation rules a message must adhere
to.
The Medi7 Parser Java Edition is designed to
be platform independent as it is built in Java and should run
on any platform that provides a Java Virtual Machine. The
Medi7 library uses standard Java exception handling to notify
of error conditions.
The Medi7 HL7 parser was designed to be
flexible and configurable. All messages are defined in an
external file along with message validation rules. Validation
rules for optional, required, exclusion, and the maximum
number of repeats are supported and it is your choice as to
whether you want to validate a message.
The Medi7 parser was designed to be
lightweight (small code size), require low runtime memory
requirements, and to be very fast. There is no code generation
scheme that creates very heavyweight implementations of an HL7
parser. This also means that there is no recompilation in
order to change a message definition or a validation rule
Back to
table of contents
............................................................................................................................................................................ |
|
We should first discuss what a
Segment Group is. A Segment Group is not a formal structure in
the HL7 specification but this construct is used in almost
every HL7 message definition. It simply means that groups of
segments have a common behavior in that they repeat together,
are required together, or are optional together as a group. If
you look at a simple message like the ADT^A01 message:
There are actually 2 segment groups. There
is the procedures group, which states that the PR1 is allowed
to repeat and if it does exist then a ROL can optionally
repeat for each PR1. This means a ROL cannot exist unless the
PR1 also exists – they are grouped together. The other group
is the insurance group, which states that the IN1 is allowed
to repeat and if it does exist then a single IN2 and/or an IN3
may also exist. This means that the IN2 and/or IN3 cannot
exist without an IN1 – they are grouped together.
The notion of segment groups is widely
recognized throughout the HL7 community. They are a common
construct used in the SIGOBT mapping as well as the approach
used by the Andover Working Group for modeling messages.
There are many difficulties to overcome when
trying to actually implement a parser and a very difficult one
centers on segment grouping constructs in HL7. The difficulty
is that for certain messages it is impossible to determine
when a segment group constructs ends and when the next one
begins when parsing a message. In some cases you can figure it
out by the next segment you see in the message, but there are
messages where the ambiguity cannot be resolved.
The messages that create an ambiguity in HL7
2.2 are the following:
-
The Diet Order Message and Result (ORM &
ORR) in Chapter 4
-
The Add and Update Patient Accounts (P01)
in chapter 6
-
The Unsolicited Transmission of an
Observation (ORU) in chapter 7
The additional messages with ambiguities in
HL7 2.3 are the following:
-
The Add and Update Patient Accounts (P05)
in chapter 6
-
Unsolicited study data messages (C09-C12)
in chapter 7
-
Product Experience (P07, P08, P09) in
chapter 7
A significant benefit would be to augment
the HL7 specification to add delimiters to identify segment
groupings within a message stream, but this is not likely to
happen since it would probably break existing implementations
of HL7. There are different ways to resolve these ambiguities
using the Medi7 parser and the different approaches depend on
the specific message in question. If using the Medi7 parser
for any of the above messages, contact Eversolve, LLC to
discuss the ways the parser can handle these messages to
resolve the ambiguity. In general, the approaches are:
-
Use a predefined segment group terminator
segment to indicate the end of a segment group
-
Force the inclusion of an empty segment
to indicate a break in a repeating segment group
-
Flatten out a repeating segment group to
multiple instances rather than an infinite repeat if the
number of repeating instances is known beforehand.
Back to
table of contents
............................................................................................................................................................................ |
|
The Medi7 parser uses the
Message Type field in the MSH segment to correlate the message
that needs to be parsed with a message definition that
describes the message layout in the Message Definition File.
This may be suitable for many messages but it is not
sufficient for all HL7 messages. Most notably, the Order
messages in Chapter 4 do not have different trigger event
codes for the different messages.
The
Medi7 parser will use all components of the message type field
to identify a message on the Message Definition File. Since
the HL7 specification says that extraneous fields should be
ignored at the end of a segment or at the end of a composite
field, it is valid to add another field to the end of the
Message Type composite field to clarify which message it is.
The Message Type is currently defined as:
<message type>^<trigger event>
example: ORM^001
A suggested use is to use a Message Type
field as follows:
<message type>^<trigger
event>^<format>
example: ORM^001^DIET
The Medi7 parser will then look for a
message definition with the key value of ORM:001:DIET, using
the above example. The Andover Working Group, HL7, or the HL7
SIGOBT may have recommended values for trigger event codes in
order to resolve this insufficiency in the Orders chapter. If
so, following one of those guidelines is recommended.
Back to
table of contents
............................................................................................................................................................................ |
| When
the Medi7 HL7 parser parses a message back into an object
graph, it uses definition of the message to determine how to
turn the message back into an object graph. When parsing a
message, the message is only broken down into the Segment
Groups and Segments. A Segment is only broken down into
Composite Fields and Field objects the first time that a value
from the Segment is retrieved. This allows for much faster
parsing of messages.
The Medi7 parser will ignore extraneous
Fields in a Segment not defined for that Segment in the
Message Definition File. Additional Fields in a Composite
Field are ignored if they are not defined for that Composite
Field in the Message Definition File. The Medi7 parser will
also ignore extra Segments that are passed in the Message that
are not defined in the Message Definition File.
Back to
table of contents |
|
The Medi7 parser can validate a
message, after it has been parsed or once it has been
assembled, by calling Validate on the M7Message object. A
specified profile is used to validate a message. A Message
Profile is a set of rules used to determine if a message is
valid. Each Message can have 0 to n profiles (See the
Message Definition File section to see how Profiles are
constructed.)
There are currently 3 types of validation rules that can be
applied to any HL7 object (i.e. Segment Group, Segment,
Composite Field, Field, or Subcomposite Field) within a
message supported by the Medi7 parser that are mutually
exclusive. They are:
Required – The object must exist.
This means the named object must exist in the Object Graph.
If the object repeats then at least one instance of the
object must exist. If a Field or Subcomposite Field is
marked as required then it cannot be set to NULL. If a
Segment Group. Segment, or Composite Field is defined to be
required then it must exist but this does not mean that any
of the fields within the Segment Group, Segment, or
Composite Field exists.
Optional – The object may exist.
This rule is the default for all pieces of an HL7 message
unless specified as required in a profile. There is no need
to configure into a message profile which pieces are
optional. However, if the object is marked as optional but
it has a child profile configured then the rules in the
child profile will be validated.
Excluded – This rule states that
the object cannot be present within this message. If the
object repeats then no instances of the object can exist.
The maximum number of times an object can
repeat within a message can also be specified. If no maximum
repeat is specified in the profile then there is no limit to
the number of times an object can repeat as long as the object
is defined to be a "repeat". The maximum repeat rule is not
applied as the repeat grows, rather it is only checked when
the Validation function is executed.
Back to
table of contents
............................................................................................................................................................................ |
Message Definition Format
|
The Message Definition File
is a flat ASCII text file that can be modified in any text
editor. The Message Definition File contains all of the
information used by the Medi7 parser to build and parse
messages and to apply validation rules.
The Message Definition File is broken down
into different sections. Each section is tagged with a
label. Following are the labels that should exist in the
file:
[MESSAGES] – This
section contains the definition of the message and
specifies what segments and segment groups exist in a
message and which segments and segment groups are allowed
to repeat.
[SEGMENT_GRPS] - This
section contains the definitions of segment groups and
specifies what segments and segment groups exist in a
segment group and which segments and segment groups are
allowed to repeat.
[SEGMENTS] - This
section contains the definition of a segment and specifies
what fields and composite fields exist in a segment and
which fields and composite fields are allowed to repeat.
[COMPOSITE_FIELD] -
This section contains the definition of a composite field
and specifies what fields and composite fields exist in a
composite field fields and composite fields are allowed to
repeat.
[MESSAGE_PROFILES] –
This section contains the definition of a message profile.
A message profile specifies which segments and segment
groups are required or optional, and if a segment or
segment group repeats in the message, the maximum number
of times it is allowed to repeat (if there is a maximum).
It also specifies which profiles should be used to
validate a segment or segment groups that are members of
this message.
[SEGMENT_GRP_PROFILES]
- This section contains segment group profile definitions.
A segment group profile specifies which segments and
segment groups are required or optional, and if a segment
or segment group repeats in the segment group, the maximum
number of times it is allowed to repeat (if there is a
maximum). It also specifies which profiles should be used
to validate a segment or segment groups that are members
of this segment group.
[SEGMENT_PROFILES] –
This section contains segment profiles definitions. A
segment profile specifies which fields and composite
fields are required or optional, and if a composite field
or field repeats in the segment group, the maximum number
of times it is allowed to repeat (if there is a maximum).
It also specifies which profiles should be used to
validate a composite field (A field does not have a
profile).
[COMPOSITE_FIELD_PROFILES]
- This section contains composite field profile
definitions. A composite field profile specifies which
fields and composite fields are required or optional. It
also specifies which profiles should be used to validate
composite fields that are members of this composite field.
In the message definition area sections
of the Message Definition File (Messages, Segment Groups,
Segments, and Composite Fields) they all follow the same
format.
| key
value=structure<type
and repeat>name|structure<type and
repeat>name|... |
The key value uniquely identifies a structure within
that section of the definition file. All key values within
a section must be unique. If not, then the first one found
is always used. The structure identifies what the datatype
for that piece of the definition. The type and repeat
identifies whether that element of the definition is a
segment group (<SG>), a segment (<S>), a composite field
(<CF>), or a field (<F>). The repeat portion identifies
whether that portion of the definition is allowed to
repeat and this is identified by an "R" at the end of the
type (i.e. repeating segment group would be <SGR>,
repeating segment would be <SR>, repeating composite field
would be <CFR>, repeating field would be <FR>). The name
value is optional for definitions in the Message, and
Segment Group sections but are required for Segments and
Composite Fields. If no name is specified then you can
reference that piece of the message using the structure
name. This allows you to identify that portion of the
message by name rather than by structure.
Following is a sample of the message definition of the
ADT AO5 message:
The following picture illustrates how different pieces
of the message definition file relate to each other:
Because the ADT:A05 message specifies that PID is a
segment with the "<S>" it will look in the [SEGMENTS]
section of the definition file for a line that has the key
value of PID. Because the INSGrp in the message is of type
segment group <SG> it looks to the [SEGMENT_GRPS] section
of the definition file. Here is one way you could
reference the Family Name field of the Patients Name in
the PID segment using the Medi7 parser:
|
msg.SetFieldValue(
"PID.PatientName.FamilyName", "Smith" );
|
Once you get all the way down to specifying a field you
must specify a valid data type known to the Medi7 parser.
Following are the valid values and the corresponding data
types:
- ST – String
- L – Long
- D – Double
- DM – Date/Time (the date/time
portion of the Timestamp composite field)
- DT – Date
- TM – Time
- TN – Telephone Number
Back to
table of contents
............................................................................................................................................................................ |
A Message Profile format
follows a chain similar to that of a Message Definition. The
"_PROFILES" sections of the Message Definition file contain
the definition of a Message Profile. A complete Message
Profile is constructed of child Profiles for different parts
of a message so the different child Profiles can be reused
in different messages. A Profile for any one object contains
a set of Rules for that object. Following is the structure
of a Profile and Rules:
|
KeyValue=ChildObjectName,<ChildObjectProfile>,<[r,o,x]>,<MaxRepeat>|ChildObjectName,
|
The KeyValue identifies an instance
of a Profile and is a combination of the Structure Type
along with an instance identifier separated by a colon. For
instance, if a PID segment had two different profiles you
might see "PID:1=…" and "PID:2…" profile definitions in the
[SEGMENT_PROFILES] section of the Message Definition File.
The Rules are placed after the "=" sign
and are delimited with the vertical bar ("|"). Each Rule has
the following components:
The ChildObjectName specifies the
name of the child object that this rule applies to. For
instance, in the PID segment you might have a rule for "PatientName".
The name must be the same as the one specified in the
Message Definition for that object. If no name was
provided in the Message Definition for that object (which
may be done for segment and segment groups), then you must
use the structure type. For instance, if in the message
definition you called the PID segment in a message the
PatientIdSegment (which is optional) then the
ChildObjectName must be PatientIdSegment.
The ChildObjectProfile specifes
the instance of a child profile object to use. The value
of ChildObjectProfile must correspond to a
KeyValue in the appropriate Profile section of the
Message Definition File. For instance, if the value for
ChildObjectProfile were "PID:0" then there must be a
line in the [SEGMENT_PROFILES] section of the Message
Definition File with a KeyValue of "PID:0". This is
the way Profiles are chained together. If no
ChildObjectProfile needs to be specified then this can
be left blank but the position is maintained by adding the
extra comma (,).
[r,o,x] means that one of the values must
be specified. "r" means required, "o" means optional, and
"x" means exclude. If no value is provided then the default
is optional.
MaxRepeat specifies how many times
this object is allowed to repeat. If the object is not a
repeat then this value is ignored. If no value is provided
then there is no maximum to the number of times an object is
allowed to repeat.
Following are example rules:
PID,PID:0,r| note that max repeat
is left off and no further commas need to be specified
EncodingCharacters,,r| note that
there is no child profile but that this is required, also
notice the extra comma since no child profile was
specified.
HomePhone,,,3| note that there is
no child profile, it will default to optional, but can
repeat up to 3 times (a 0 to 3 cardinality), again notice
the extra commas.
INSGrp,INSGrp:0| note that the
object rule defaults to optional but if the object does
exist then the child profile specified (INSGrp:0) will be
applied.
Following is an example of how a Profile
is configured in the Message Definition File:
 |
The following diagram depicts how Profiles
are chained together so they can be reused across multiple
messages:
|
Back to
table of contents
.............................................................................................................................................................................
|
Absolute names are what make
the Medi7 parser so easy to use. An absolute name is one that
specifies a message component relative to where you are in the
message graph. Each part of an absolute name is separated by a
period (.). An absolute name can also contain an index
reference for message components that are allowed to repeat.
Following are some examples of using the absolute names to
reference message components assuming that we are currently at
the top of the message object graph:
"PID" - references the PID segment.
"PID.PatientName.FamilyName" –
references the family name field in a PN composite field that
is the patient name in the PID segment.
"PID.IntPatID[1].PatientID" –
references the patient id field in the first position (indexes
are always 0 based) of the repeating internal patient id
composite field (which is a CM composite field) in the PID
segment. |
............................................................................................................................................................................
Back to
table of contents Copyright 1999-2002 Eversolve,
LLC |
|
..................................................................................................................................................................... |
