This page provides an overview of the InterSystems tools that you can use to work with HL7 Version 2 schemas and documents.
Overview of HL7 Schemas and Messages
InterSystems products can process and pass through an HL7 message without using a schema to parse it, but associating a schema with a message allows you to do the following:
Each HL7 message is identified by a message type, which is specified in the MSH segment MessageType field (MSH:9). Some message types share the same message structure. For example, in HL7 Version 2.3.1, the ADT_A05 message to pre-admit a patient has the same structure as the ADT_A01 admit message. The schema specifies that the ADT_A05 message has the structure type ADT_A01.
In order to parse an HL7 message, InterSystems products need two pieces of information:
-
Schema category — this is the HL7 version number, such as 2.3.1 or 2.7, or it may be a category for a custom schema defined in your InterSystems product. The production obtains the schema category from the business service Message Schema Category setting or from the Data Transformation settings. Although the HL7 message includes a schema version number in the MSH segment VersionID field (MSH:12), InterSystems does not use this value because many applications do not set this field consistently.
-
Structure type — The production obtains the message type from the MSH:9 field and then checks the schema definition to get the structure type for that message.
InterSystems uses the MSH:9.3 subfield to qualify the message type in some cases. The MSH:9:3 subfield is used in HL7 messages in two ways: 1) as a modifier to the message type, or 2) to specify the structure type. If MSH:9:3 modifies the message type, typically as a numeric digit, InterSystems products include it as part of the message type. If MSH:9:3 specifies a structure type, such as ADT_A01, InterSystems ignores it in both determining the message type and setting the Name property. InterSystems products do not need the MSH:9.3 subfield to determine the structure type because they get the structure type from the schema.
When a business service or Data Transformation creates an EnsLib.HL7.Message object to store an HL7 message, it combines the schema category and structure type and stores it in the DocType property using this syntax:
category:structureType
For example, valid DocType values for category 2.3.1 include 2.3.1:ACK, 2.3.1:ADT_A17, 2.3.1:BAR_P01, and 2.3.1:PEX_P07. The message type, which can be different from the structure type is stored in the Name property.
If you create an EnsLib.HL7.Message object in ObjectScript code, you should set the DocType and Name properties based on the value in the MSH:9 field.
The HL7 standard allows local extensions, such as trailing Z segments. These segments are not defined in the base schema categories. If you want to access a field in a custom Z segment in a data transformation, routing rule, or ObjectScript, you need to define a custom schema category that specifies the extended message. See Using the Custom Schema Editor for details on defining a custom schema.
You can place custom HL7 schemas under source control. Once source control is enabled, the source control options, such as check out and check in, are available from the main HL7 Schemas page, but not on the other pages that you use to work with custom schemas such as the HL7 Schema Message Type page. You must check out the entire schema from the HL7 Schemas page before editing the schema using other pages. A Source Control Output window is available from the main HL7 Schemas page that captures source control activity from all related HL7 schema pages. For information about setting up source control, see Integrating InterSystems IRIS with Source Control Systems.
Using the HL7 Schema Structures Page
The HL7 Schemas page enables you to import and view HL7 Version 2 schema specifications. To display this page, select Interoperability > Interoperate > HL7 v2.x > HL7 v2.x Schema Structures from the Home page. For general information on using this page, see Using the Schema Structures Page in Using Virtual Documents in Productions.
The HL7 Schemas page provides an additional tab: Message Types. This tab identifies two message structures as a request/response pair.
For information on creating and editing custom schema categories, see Using the Custom Schema Editor.
Using the Custom Schema Editor
The Custom Schema Editor allows you to create a new custom HL7 schema or edit an existing custom HL7 schema. Typically, a custom schema has a base schema, which is a standard schema or another custom schema. When an InterSystems product is using the custom schema to parse a message, if the message type, segment, or other element is not defined in the custom schema, it uses the definition in the base schema. Consequently, you only have to define the elements in the custom schema that are not present in the base schema or require a different definition from the one in the base schema. You cannot edit a standard schema.
The most common reason to define a custom schema is to be able to parse HL7 messages with trailing Z segments. InterSystems products can handle messages with trailing Z segments that are not defined in the schema, but to do any of the following you need to define a custom schema:
-
Access field paths in the trailing Z segments in a routing rule, data transformation, or ObjectScript code.
-
Validate the trailing Z segments.
If you have a production that is currently using a standard schema and you need to access trailing Z segment field paths in a data transformation or routing rule, you should do the following:
-
Use the Custom Schema Editor in the Management Portal to create a new HL7 schema. Enter a name for the custom schema and specify the base schema. See Creating a New Custom Schema.
-
Define the Z segment that can appear in your message. If your Z segment has similar fields to an existing segment in the base schema, you can copy the definition from the base and then modify it as needed. Otherwise, you can create a new segment. You can add fields, delete fields, or change the order of fields. See Defining a New Segment.
-
For each message type that includes the trailing Z segments, create a message type and structure type in the custom schema that is copied from the underlying schema. Add the Z segment to the end of the structure type. See Defining a New Message Type and Structure Type
-
Modify the business service in your production to use the new custom schema instead of the base schema.
-
Test the production by supplying new messages with the trailing Z segments to the production’s business services. If you view the messages in the message viewer, the Z segments will be shown in blue if they are defined in the schema. Unrecognized segments are shown in black.
Detailed instructions are in the following sections.
Creating a New Custom Schema
To start the Custom Schema Editor from the Management Portal, select Interoperability > Interoperate > HL7 v2.x >HL7 v2.x Schema Structures from the Home page.
To create a new HL7 schema, click New. In the Custom Schema Editor, select the base schema, schema name, and, optionally, a schema description. For example, to define a custom schema based on the Version 2.5 standard schema category, you could enter the following:
Once you have created the custom schema, the Custom Schema Editor presents you with an empty schema, and you can define the message types, structure types, segment structures, data structures, and code tables in it. You have to define only the elements that have different definitions than those in the base schema or that are not defined in the base schema.
The Custom HL7 Schema Editor has the following tabs:
-
Message Types
-
DocType Structures
-
Segment Structures
-
Data Structures
-
Code Tables
On each of these tabs, you can copy the elements from an existing base definition by selecting Copy From Base. This allows you to create a message type or other element that is an extension of an existing definition without having to reenter the common definitions.
Defining a New Segment
To define a new Z segment, select your new custom schema in the left panel and then select the Segment Structures tab. For custom schemas, the Segment Structures tab has the New and Copy From Base buttons and lists the segments that are currently defined in the custom schema. Since the schema doesn’t have any segments defined, the segment structure list is empty. If you are viewing a standard schema, you cannot add new segments and the buttons are not present
If you want to define a new segment without copying fields from another segment, click the New button and the wizard creates an empty segment. Name the segment and click the Add Field button. The wizard creates an empty field and you can fill in the form. For example:
If you are creating a segment that is very similar to an existing segment in the base schema, you should choose Copy From Base, it creates a new segment with the same fields as the specified segment. The Custom Segment Structure Wizard displays the copied fields and has a New button after the fields to create a new field. For example, the following segment was copied from the PID segment.
Once you have creating the segment either as a new segment or as a copy of a base segment, you can add or update fields as follows:
-
Click the Add Field button to add a field at the end of the segment.
-
Update the form text boxes that define the segment field. You cannot edit the Property Name text box. The wizard sets the property name based on the field Description value after it removes any spaces or special symbols. The property name is set when you click OK to end the wizard.
-
Change the order of a field by clicking on the up or down arrows.
-
Delete a field from the segment by clicking the red X.
When you have completed entering the fields, click OK to save the segment.
You can edit any saved segment in a custom schema by clicking on the segment name and then clicking Edit.
Once you have defined your Z segments, you should define the message types and structure types that contain the Z segments.
Defining a New Message Type and Structure Type
The Message Type identifies the message and matches the value in the HL7 MSH:9 field. When you define a message type, you specify the sending message structure type, which may be the same as the message type, and the return type. But you specify the segments that can be in the message in the structure type not in the message type. When you create a message type, you can optionally create a structure type at the same time.
To add a Z segment to a message type that is defined in the base schema, copy the message type and structure to the custom schema and then add the trailing Z segment to the structure type. For example, to add the ZPI segment to the ORU_R01 message in a custom schema that has Version 2.5 as the base schema, do the following:
-
Select your custom schema in the left panel, select the Message Types tab, and click Copy From Base.
-
Select the ORU_R01 message type in the Message Type to Copy pull-down. The wizard fills in the new message type name to be the same as the copied message type and sets the Message Structure and Returning Message Type to match the definition in the base. By checking the box, you automatically create the sending message structure in the custom schema if it is not yet defined. It is created by copying the structure from the base schema. Some versions of the HL7 standard include message type for which two message structures are available. Use the Alternate Message Structure to define an additional possible structure for this type.
After you click OK, the ORU_R01 message type and the ORU_R01 structure type are defined in the custom schema.
-
Click the DocType Structures tab and the ORU_R01 structure type. The custom schema editor displays the graphical representation of the structure type.
-
To begin adding, removing, or modifying segments that are a part of the message structure, click the Edit button. The Edit button and Available Segments section appear only if you are viewing a structure that is a part of a custom schema.
For example, if you are using the Custom Message Structure Wizard to edit a copy of the ORU_R01 structure type, the wizard displays the following:
When you are extending a message definition from the base schema, you should use the same segment and structure name as specified in the base schema.
You can drag and drop a segment from the Available Segments section to the Structure section to put it in the correct position within the message structure. To focus on adding custom segments, click the Filter button
so that only custom segments appear in the Available Segments section.
Once the segments are in the Structure section, you can click on the segment to define it as optional or repeating.
You can also create a group of segments that are optional or repeating as a whole. To create a group:
-
Click on the segment that will be at the top of the group and select group. The top level of the group is created, with its name being the same as the segment you selected, but with grp appended to it.
-
Click on the top-level group name, and select optional or repeating. Segments are not saved as a group unless the entire group is identified as optional or repeating.
-
Add segments to the group using drag and drop. A group is not saved if it contains only one segment.
You can also create a set of segments where the structure of the message can contain any one of the segments in the set. To create this set, click on a segment that will be part of the set and select choice. The top level of the set is created, with its name being the same as the segment you selected, but with union appended to it. You can then drag and drop the other segments that are part of this set; the union is not saved if it contains only one segment.
For more details on the visual cues and naming conventions of the segments in the Structure section, see Viewing a Message Structure.
To see the message structure in a raw text format, click
. If you are in edit mode, you can modify the message structure by editing the raw text.
Note:
Once you have defined a message structure in the custom schema, that definition is used for all message types that share the same structure. For example, if you add the ZPI trailing segment to the ORU_R30 structure, the trailing Z segment is allowed in the ORU_R30, ORU_R31, and ORU_R32 message types because they all share the same ORU_R30 structure. It is not necessary to include the message types in the custom schema. The definition from the base schema will use the structure type from the custom schema.
Editing Data Structures and Code Tables
Data structures provide a mechanism to specify a field that has a structured value rather than a simple data type, and code tables provide a mechanism to define a set of allowed values for a field. Typically, data structures and code tables are defined by the HL7 standard body and are not defined as custom extensions. The Custom HL7 Schema Editor does allow you to define data structures and code tables in your custom schemas in the rare cases where this is needed. The wizard to edit data structures is very similar to the wizard to edit segments. The wizard to edit code tables allows you to define codes and descriptions for the code table. The codes specify the values that can be used in a field.
Viewing Batch Messages
The HL7 Document page handles a message differently if it is a group of HL7 messages in batch format, rather than a single HL7 message. Specifically, it allows you to walk through the batch message structure one level at a time.
The following display is the result of asking to view a batch message that begins with an FHS segment. InterSystems parses the batch message and finds that it has 3 segments: FHS, FTS, and a block of child documents in between. The block contains two child documents; each beginning with BHS and ending with BTS. The message is a two-level batch message.
The Message Viewer assigns the child documents the identifiers <2> and <33>. It displays the top-level parent document, using links (<2> and <33>) to represent the two child documents. The display is as follows:
When you click on a child document link in an HL7 batch message display, a new browser window opens to display the child document. The Message Viewer window, with the top-level parent, remains open in the original browser window.
The next display is the result of clicking the child document link <2> in the previous display. This example is a two-level batch message, so the child document <2> has children of its own: child documents <3> through <32>.
This example highlights a useful navigation feature of the Message Viewer. If there are more than 10 child documents in a batch message, the Message Viewer displays links to the first five and last five child documents. Between the lists is a text field, into which you can enter any identifier number between the first and last numbers. After you enter a number, click Other. A new browser window opens to display the child document.
The next figure is the result of clicking the child document link <6> in the previous figure. Since this is the lowest level of the batch message hierarchy, message <6> shown in the following image is a normal HL7 Version 2 message that begins with an MSH segment.
When you are done viewing messages in the batch message hierarchy, you can close all the pop-up browser windows until the top-level parent document remains in the original Message Viewer window. From here, you may return to other Management Portal activities.