Ensemble HL7 Version 2 Development Guide
Additional Steps
[Back] [Next]
Go to:

This chapter discusses the additional steps needed to add HL7 processing to a production. It includes the following topics:

Be sure to perform these tasks in the same namespace that contains your production. When you create rule sets, transformations, and search tables, do not use reserved package names; see Reserved Package Names in Developing Ensemble Productions.
Also see Overriding the Validation Logic in Ensemble Virtual Documents.
Defining Routing Rule Sets for HL7
When creating a routing rule set for an HL7 interface, your goal is to tell Ensemble what to do with the source message based on the segments found within it. Sometimes it matters which segments are found; sometimes it matters which values are found within those segments.
In ordinary rule sets, each rule returns a value to the business process that invoked the rule set. In a routing rule set, a rule usually directs an HL7 message to a destination, possibly transforming the HL7 message before sending it.
For information on using the rule editor, see Creating and Editing Rules Sets in Developing Business Rules.
  1. When you create a new HL7 routing process using the Business Rule Wizard, Ensemble creates a new, empty routing rule set to accompany the new routing process. Its information tables contain the following values:
  2. You may also enter additional fields for your own rule reporting purposes:
  3. See Using the Rule Constraint Editor in Developing Business Rules for details on entering the constraints of a routing rule.
  4. Once you have created a new rule, you may add Conditions and Actions to it. For details, see chapter Creating and Editing Rule Sets in Developing Business Rules. As you add Conditions to each rule, remember these tips:
  5. Complete the instructions in the next several topics for creating any Source, Target, or Transform items that your routing rule set needs. The items might be:
    As you create items, return to the Message Routing Rule Editor to add them to the appropriate fields of the rule definition.
  6. Return to the diagram on the [Ensemble] > [Production Configuration] page. Select the corresponding HL7 routing process. In the BusinessRuleName field, enter the full name of the new routing rule set.
Defining DTL Data Transformations for HL7
Each interface may require some number of data transformations.
Do not manually change HL7 escape sequences in the data transformation; Ensemble handles these automatically.
You use the [Ensemble] > [Data Transformation Builder] page to create data transformations. (To access this page in the Management Portal, click Ensemble, click Build, click Data Transformations, and then click OK.) For general information on using this page, see Developing DTL Transformations.
The following figure shows this page, displaying MsgRouter.ADTLastNameTransform from the ENSDEMO namespace:
Note the following tips:
Null Mapping Codes
There are HL7 applications that use a null mapping convention. According to this convention, the source application can send a field that consists of two consecutive double-quote characters ("") to signify if you have data in this field, delete it from your application.
Many target applications do not expect these instructions and are not designed to respond to them. If this is the case, and the double quotes are saved in the target application as actual patient data, the application users see double-quote characters on their screens. This can be annoying and misleading.
When your source application uses a null mapping convention, your HL7 data transformation can check for null mapping entries in HL7 fields and replace them with empty strings, or otherwise fill in data for the benefit of the target application.
The following <if> statement represents the simplest case. It checks for a null mapping in the source and replaces it with an empty string in the target. The <if> condition tests for the null mapping code "" using a string of 2 quoted quotes. This results in a total of 6 double-quote characters, not including the single quotes that wrap the entire condition value. (Count carefully!)
<if condition='source.{PV1:7().4}=""""""'>
<assign property='target.{PV1:7().4}' value='""' />
In the above example, the <assign> value indicates a empty string using 2 consecutive double-quote characters, with single quotes wrapping the entire value.
The following syntax is equally valid:
<if condition='source.{PV1:7().4}=&quot;&quot;&quot;&quot;&quot;&quot;'>
<assign property='target.{PV1:7().4}' value='&quot;&quot;' />
You can achieve more sophisticated goals for handling null mappings. The following example takes alternative actions based on whether there is actually a value in {PV1:3}. If the field contains a null mapping code the <true> element executes. Otherwise the <false> element executes.
<if condition='source.{PV1:3}=""""""'>
<assign property='target.{PV1:3.1}' value='source.{PV1:PatientType}' />
<assign property='target.{PV1:3.2}' value='source.{PV1:PatientType}' />
 // Dr Chart pulls subfields as follows:
 // 1 location, 2 desc, 3 room, 4 bed, 5 wing, 6 floor
<assign property='target.{PV1:3.1}' value='source.{PV1:3.1}' />
<assign property='target.{PV1:3.2}' value='source.{PV1:3.1}' />
<assign property='target.{PV1:3.3}' value='source.{PV1:3.2}'  />
<assign property='target.{PV1:3.4.1}' value='source.{PV1:3.3}'  />
<assign property='target.{PV1:3.5}' value='source.{PV1:3.1}'  />
Defining HL7 Search Tables
The HL7 search table class, EnsLib.HL7.SearchTable, automatically indexes popular HL7 properties; see the subsection Properties That Are Indexed by Default.”
If you need more items to search, you can create a subclass. The subclass inherits the Identifier property, plus the infrastructure that makes search tables work. For details, see Defining a Search Table Class in Ensemble Virtual Documents.
For HL7, Ensemble supports an additional value for PropType. You can use DateTime:HL7 in addition to the types listed in Ensemble Virtual Documents.
Properties That Are Indexed by Default
When you choose EnsLib.HL7.SearchTable as your search table class, it enables Ensemble to search HL7 messages for the following virtual properties.
Choose... To refer to this value...
The message structure name. To create this string, Ensemble concatenates the following values from the HL7 message:
  • The MSH message header segment
    Field 9 (message type)
    Subfield 1 (message type: ADT, ORM, etc)
  • The literal character _
  • The MSH message header segment
    Field 9 (message type)
    Subfield 2 (trigger event: A01, A12, O01_2, etc)
The result is a message structure name in the format ADT_A01, ADT_A12, ORM_O01_2, etc.
The unique identifying number for this message. Ensemble retrieves this value from:
  • The MSH message header segment
    Field 10 (message control ID)
Ensemble interprets this value as a case-sensitive string.
The patient identifier for this message. This is a field whose location has shifted as the HL7 standard has evolved. For this reason, Ensemble looks for this value in all of the following locations. That way, the patient identifier can be found regardless of which HL7 schema category the message conforms to:
  • The PID patient identifier segment
    Field 2 (patient external identifier)
    Subfield 1 (patient identifier)
  • The PID patient identifier segment
    Field 3 (patient identifier list), all entries in the list
    Subfield 1 (patient identifier)
  • The PID patient identifier segment
    Field 4 (patient identifier list), all entries in the list
    Subfield 1 (patient identifier)
The PID patient identifier segment
Field 5 (patient name)
The PID patient identifier segment
Field 18 (patient account number)
Subfield 1 (ID)
The following example consists of one virtual property path that uses {} syntax. This <Item> element refers to the value at Segment 1, Field 10 of the HL7 message:
<Item DocType=""
      StoreNulls="true" >
The following more complex <Item> element uses the ObjectScript _ operator to concatenate three strings. From left to right, these are:
<Item DocType=""
      PropName="SendingFacilApp" >
The following <Item> example uses most of the possible syntax options: concatenation, virtual properties, a literal hyphen character (-), and the ObjectScript string function $PIECE:
XData SearchSpec [ XMLNamespace="http://www.intersystems.com/EnsSearchTable" ]
 <Item DocType="Mater:ORM_O01 "
       PropName="RelationKey" >
The following sample search table class provides several examples of valid <Item> entries. This class inherits from EnsLib.HL7.SearchTable, as is required for HL7 search tables. Comments above each group of <Item> entries describe the purpose of that set of entries. For details about {} or [] syntax, see the Syntax Guide section of Ensemble Virtual Documents.
Class Demo.HL7.MsgRouter.SearchTable Extends EnsLib.HL7.SearchTable

XData SearchSpec [ XMLNamespace="http://www.intersystems.com/EnsSearchTable" ]
   <!-- Items that do not depend on DocType, indexing any HL7 message -->
   <Item DocType="" PropName="SendingFacilApp" >{1:4}_"|"_{1:3}</Item>
   <Item DocType="" PropName="RecvingFacilApp" >{1:6}_"|"_{1:5}</Item>
   <Item DocType="" PropName="MSHDateTime" PropType="DateTime:HL7" >{1:7}</Item>

   <!-- Get fields from named segments found in any HL7 message -->
   <Item DocType="" PropName="PatientName" >[PID:5]</Item>
   <Item DocType="" PropName="InsuranceCo" >[IN1:4]</Item>

   <!-- Get patient name from any HL7 message declared type ADT_A05 -->
   <Item DocType=":ADT_A05" PropName="PatientName" >{3:5}</Item>

   <!-- Get specific field from specific segment when the        -->
   <!-- HL7 message is assigned a specific DocType. Only in this -->
   <!-- case can you use names for segments, instead of numbers. -->
   <Item DocType="Demo.HL7.MsgRouter.Schema:ORM_O01 " PropName="ServiceId" >
   <Item DocType="2.3.1:ORU_R01 " PropName="ServiceId" >