HL7 Schemas and Available Tools

Viewing a List of Document Types

To list all the document type structures in a category, first select the category and then click the DocType Structures tab.

Viewing a Message Structure

To view the internal organization of a message structure, click its name from the DocType Structures tab on the HL7 Schemas page (select Interoperability > Interoperate > HL7 v2.x > HL7 v2.x Schema Structures). The InterSystems product displays the segment structure of the message in the Structure section using the following visual cues and naming conventions.

• The segments that comprise the message structure are listed in sequential order from top to bottom.

• Segment names must be all uppercase.

• The three-letter name of each message segment is displayed: MSH, NTE, PID, etc. This name indicates the type of segment that exists at this location in the HL7 message structure. The names of segments that enclose a choice, are repeating, or contain a group of other segments have special characters appended to the name.

• Green dotted lines enclose segments, groups, or fields that are optional.

• Segments that can be repeated have parentheses appended to the segment name. For example, if the PID segment can be repeated, PID( ) appears.

• Segments that enclose a choice of other segments are considered a union of segments. These union segments have the word “union” appended to the segment name. Only one of the segments contained in the union can appear at this location within the message structure.

• Segments that contain a group of segments have the letters “grp” appended to the segment name. To expand or collapse a group, use the arrow icon next to the group’s name.

Double-clicking a segment name opens up the structure of that segment in a separate window.

To see the message structure in a raw text format, click .

Viewing a Segment Structure

To view the structure of a message segment, click on its name in any page similar to the example shown in the previous section. InterSystems products display a table that lists all the fields in that segment. This is the HL7 Schema Segment Structure page.

For example, if you click the PR1 segment in the 2.3:ADT_A01 message structure, InterSystems products display the following page.

The columns are as follows:

• Field — the number to use to access the field within the segment (if you prefer numbers).

• Description — a short description of the field.

• Property Name — the name to use to access the field within the segment (if you prefer names).

• Data Structure — for more complex field values that use a data structure, you need further syntax details before you can complete the segment:field virtual property path. You can get this by clicking on the name in this column

• Symbol — indicates the syntax rules for the field. The characters in this column indicate whether you can expect this field to be present, absent, or repeated within the message segment. Possible values are:

  Symbol	Meaning
  !	(1 only) The field is required; it must occur only once.
  ?	(0 or 1) The field is optional, but if it occurs, it may occur only once.
  +	(1 or more) The field may repeat one or more times.
  *	(0 or more) The field may repeat zero or more times.
  &	The field may be present, and may repeat, but only under certain conditions.
  n*	(0 to n) The field repeats a maximum of n times.

• Repeat Count — the maximum number of times the field can repeat (if it repeats, and if there is a maximum).

• Minimum Length — the minimum number of characters in the field. Each repeat of the field must contain this number of characters.

• Maximum Length — the maximum number of characters in the field. Each repeat of the field may contain this number of characters.

• Required — displays R for required, O for optional.

• Repeating — displays 1 for true, 0 for false.

• Code Table — click on an entry to view the valid codes that may be entered in this field.

• Alternate Description — a second, longer description of the field.

You can use this information, particularly the Property Name column, to build virtual property paths in the format segment:field. The following are examples of virtual property paths involving simple field values from the PR1 segment in the 2.3:ADT_A01 message structure. The () shortcut syntax indicates all available instances of a repeating field, whereas (1) indicates the first instance:

PR1grp().PR1:ProcedureType
PR1grp().PR1:ProcedureCode()
PR1grp().PR1:ProcedureCode(1)
PR1grp().PR1:ProcedureCode(x)
PR1grp().PR1:ProcedurePriority

Viewing a Data Structure

When you click on a name in the Data Structure column, InterSystems displays all the fields in that data structure. This is the HL7 Data Structure page. The following columns of the display are most useful:

• The Component column lists the numbers you can use to access fields within the segments (if you prefer numbers).

• The Property Name column lists the names you can use to access fields within the segments (if you prefer names).

• Click on an entry in the Data Structure column (if any) to drill down for detail.

• Click on an entry in the Code Table column (if any) to view the valid codes that may be entered in this field.

The following sample page appears when you click the Data Structure item called 2.3:XCN in the segment structure page above. The page states that the category 2.3 data structure XCN describes an “Extended Composite ID number and name” and consists of fourteen fields. Of these, some are simple values, some are data structures, and some are codes.

Given this information, you can create virtual property paths for the complex PR1grp().PR1:Surgeon field in the message structure 2.3:ADT_A01 as follows:

PR1grp().PR1:Surgeon.familyname
PR1grp().PR1:Surgeon.degree

Viewing a Code Table

When you click on a name in the Code Table column, it lists and explains the valid codes for that field. This is the HL7 Code Table page. The following sample page appears when you click the Code Table item called 2.3:200 in the data structure page shown in the previous section.

The example above shows that the category 2.3 code table 200 describes a “Name type” that can have the value L, O, M, A, C, or D.

This means that if you have an HL7 message with a DocType of 2.3:ADT_A01, it has an optional virtual property with the path PR1grp().PR1:Anesthesiologist.nametype that can contain one of the following values: L, O, M, A, C, or D.

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:

1. Select your custom schema in the left panel, select the Message Types tab, and click Copy From Base.

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

3. Click the DocType Structures tab and the ORU_R01 structure type. The custom schema editor displays the graphical representation of the structure type.

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

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

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

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

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.

Selecting Options

To specify the document to display:

1. For Document Source, select File, Message Header ID, or Message Body ID.

2. Specify the document to display:

   • If you selected File, use Browse to choose a file. For Document Number in File, type the number of the document to display.

   • If you selected Message Header ID or Message Body ID, type the ID of the message header or message body to display.

3. Specify how to parse the document. To do so, select one of the following options for Document Structure or Schema:

   • As received by a business service — Use the schema as assigned by a business service. If you select this, select a business service from the drop-down list.

     This option enables you to determine the DocType to which a particular business service would assign this document.

   • Use a specific Schema Category/Version — Choose a document category from the drop-down list.

   • Use a specific DocType — Enter the name of an document structure (<MessageStructure>) in the format category:structure. The parser uses this document structure.

   • Use content-declared Version:Name — Use the document structure associated with the document type declared in the document.

   • Use object's stored DocType — Use the DocType as declared in the document body object. (This option does not apply to stored documents loaded from a file.)

   • None — Do not use any DocType to parse the document. Instead, display the raw segments without transforming any of them into links.

   This option enables you to try interpreting documents from a particular data source as different schema category types to determine which DocType is the right one to use when handling documents from that source. There are a variety of reasons why you might need to do this. For example, you might find when you update an external application that it has changed the actual version of the documents it sends, but has neglected to update the type declaration that it sends in these documents. It is also useful in determining which of the built-in categories to use as a schema base, when a document uses a custom document structure.

4. Optionally click Transform Document? and specify the transformation details. See Testing a Transformation.

5. Click OK.

Parsing the Message

The Message Viewer displays the following on the right side of the screen after completing the steps above:

• Summary Report, which contains following basic information about the document:

  • The Data Transformation applied, if applicable

  • The Message ID

  • The DocType

  • The DocType Category

  • The DocType description, if available

  • The number of segments

  • The number of child and parent documents, if applicable

• Message Data, which has one row for each segment in the message structure. Each row contains:

  • Segment number

  • Segment name, such as PID or NTE

  • Field contents and separators, as contained in the message

  If the message matches the schema you have selected, segments and elements will appear in blue, as seen below. Clicking on the segments or fields will link to the relevant structure page.

  

Displaying the Segment Address

To display the segment address, hover the cursor over a segment name in the shaded column. The tooltip displays the following:

• Segment address to use in a virtual property path

• Descriptive name of this segment

Displaying the Field Address

To display the field address, hover the cursor over a field within the message structure. The tooltip displays the following:

• The field address to use in a virtual property path (as a number)

• The field address to use in a virtual property path (as a name)

• Characters that indicate the syntax rules for this field. The characters can begin with:

  Symbol	Meaning
  !	(1 only) The field is required; it must occur only once.
  ?	(0 or 1) The field is optional, but if it occurs, it may occur only once.
  +	(1 or more) The field may repeat one or more times.
  *	(0 or more) The field may repeat zero or more times.
  &	The field may be present, and may repeat, but only under certain conditions.
  n*	(0 to n) The field repeats a maximum of n times.
  (m)	m is the maximum number of characters in the field. Each repeat of the field may contain this number of characters.

Testing a Transformation

To test a transformation:

1. Click Transform Document?.

2. For Choose Data Transformation, select a data transformation.

3. For Choose Display Option, select one of the following:

   • Transformation Result Only — Display only the transformed document.

   • Original Message and Result Together — Display both the original document and the transformed document.

4. Now do either or both of the following:

   • Click OK to display the transformed document.

   • Click Save Result To File? to save the transformed document to a file. In this case, also specify a path and filename.

     The default directory is the management directory for the active namespace. For example, if you installed InterSystems IRIS into the directory C:\MyIRIS and your current namespace is MyNamespace, the file is saved as C:\MyIRIS\Mgr\MyNamespace\filename

Details on the HL7 Message Class

InterSystems products provide a built-in class for HL7 Version 2 virtual documents. The class is EnsLib.HL7.MessageOpens in a new tab. For basic information on virtual document message classes, see “Virtual Document Classes” in Using Virtual Documents in Productions. In addition to the basic properties and methods, EnsLib.HL7.MessageOpens in a new tab provides the following properties: