Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

Virtual Property Paths

This chapter introduces virtual property paths, which Ensemble uses to access data within virtual documents. It contains the following sections:


To work with a virtual document, you must be able to identify a specific data item within it. The data item is called a virtual property. An virtual property path is the syntax that Ensemble uses to specify the location of a virtual property.

Except for XML virtual documents, you can use virtual property paths only if you have loaded the applicable EDI schema into Ensemble. Once the schema is loaded into Ensemble, Ensemble has all the information necessary to parse the corresponding documents as intended by the EDI schema.

Parsing EDI Documents: Segments and Fields

For ASTM, EDIFACT, HL7 version 2, and X12 documents, the raw data stream is divided into segments, which are further subdivided into fields. (The details are different for XML documents; see Ensemble XML Virtual Document Development Guide.)

The following example shows the raw contents of a partial HL7 message. The right-hand portion of the text is truncated for reasons of space:

PID:1::000616898;;;A;MR~00531098;;;;PI::LaRocca;Yan::19980202:F::4:924 Maple Blv
NK1:1:Taylor;Chelsea:M;MOTHER:7702 Oak Street;;Reston;NV;93076;USA:854-495-4757:
DG1:2:I9:599.0:URIN TRACT INFECTION NOS::AM::::::::::
DG1:3:I9:599.0:URIN TRACT INFECTION NOS::F:::::::::1:

A terminator character (often a carriage return) marks the end of the segment. In this case, each line is a segment.

Within a segment, separator characters mark the boundaries between fields. In this case, the colon is the separator character between fields and the semicolon is the separator between subfields.

A field can contain sub-fields and further subdivisions. These are delimited by other separator characters.

The details of the terminator character and separator characters depend upon the EDI format.

  • For details on HL7 Version 2, see Separators. The default HL7.2 separators are:

    | ^ ~ \ &

    The fourth character (by default \) is used to escape characters rather than separate fields.

  • For details on X12, see Separators. The default X12 separators are:

    * : \a ~ \r \n
  • For details on EDIFACT see Separators. The default EDIFACT separators are:

    : + ? ' \r \n
  • For details on ASTM see Separators. The default ASTM separators are:

    | \ ^ &

    The fourth character (by default &) is used to escape characters rather than separate fields.

ASTM Example

The following figure shows how Ensemble parses an ASTM document. It shows the document as displayed in the Document Viewer page, described in “Portal Tools,” later in this book.

generated description: example astm doc

Segment Structures

Generally, an EDI standard defines a large number of possible segment structures to use as building blocks. Each document structure can contain only specific segments. Different document structures may also combine segments in different sequences or quantities. For example, for HL7 Version 2.3:

  • An ADT_A01 message contains the following segments: MSN, EVN, PID, PD1, NK1, PV1, PV2, DB1, OBX, AL1, DG1, DRG, PR1, ROL, GT1, IN1, IN2, IN3, ACC, UB1, UB2

  • In contrast, an ADT_A02 message contains only the following segments: MSN, EVN, PID, PD1, PV1, PV2, DB1, OBX

(The details are different for XML documents; see Ensemble XML Virtual Document Development Guide.)

Determining Virtual Property Paths

Conceptually, a virtual property path includes all the following units:

  • category:structure — the DocType

  • segment:field — the path to a data value within a virtual document of that DocType

The following figure illustrates this convention.

generated description: segment field

Generally the segment portion of the path identifies the target segment within a hierarchical document structure containing groups and repeating blocks of segments. For example, an NTE segment in a 2.3:ORM_O01 message might be identified as:


Similarly, the field portion of the path identifies a target field within a hierarchical structure of fields, subfields, and repeating groups within the target segment. As it happens, each field within NTE is simple, for example:


So that the complete segment:field path looks like this:


Some fields can have complex hierarchical structures. Suppose we look at a PID segment in the same 2.3:ORM_O01 message structure. In the segment identified as:


There could be a field path as follows:


Unlike segment paths, the field portion of the path generally allows numbers instead of names for fields and subfields; for example, instead of the names previously shown, the following numbers may be used:


The Management Portal provides pages to help you determine the correct segment:field paths. (To access these pages, click Ensemble, and then click Interoperate.) The DTL editor also provides a view of the document structures used in a particular transformation.

(The details are different for XML documents; see Ensemble XML Virtual Document Development Guide.)

Virtual Document Classes

To work with virtual documents, there is no need to create message classes. Ensemble provides message classes, for example, one class to carry X12 documents, another for HL7 messages, another for XML documents, and so on. The business host classes automatically use the appropriate message class.

These messages are known collectively as virtual documents.

The virtual document classes provide properties to carry the information that Ensemble needs to process the messages. These properties include the following:

DocType property

Indicates the document type, a string in two parts as follows:



The following examples show DocType values for various HL7 messages:

  • 2.3.1:ORM_O01

  • 2.4:ORD_O04

  • myCustomCategory:MFN_M03

This property is visible in the Management Portal. You can use it for filtering, for example.

RawContent property

Contains the first 32 KB of the raw message.

This property is also visible in the Management Portal and is useful in analyzing and reporting badly formed messages.

Note that this property is not indexed in any way. If you were to use this property in an SQL search query, the query would not execute very efficiently. It is not recommended to access this property programmatically (for example from a DTL). Instead, use virtual property paths to access the data that you need.

BuildMapStatus property

Contains a %Status value that indicates the success or failure of the most recent effort to map the raw content of the message to a particular DocType. You can test BuildMapStatus in code as follows:

  • Use the macro $$$ISOK(myHL7Message.BuildMapStatus) in ObjectScript and the method $SYSTEM.Status.IsOK(myHL7Message.BuildMapStatus) in Basic. If the test returns a True value, BuildMapStatus contains a success value.

  • Use the macro $$$ISERR(myHL7Message.BuildMapStatus) in ObjectScript and the method $system.Status.IsError(myHL7Message.BuildMapStatus) in Basic. If the test returns a True value, BuildMapStatus contains a failure value.

To view details of any BuildMapStatus failure codes, use the Schema Structures page as described in the chapter “Portal Tools.”

The virtual document classes also provide the logic that Ensemble needs to interpret a virtual property path for a specific format and DocType. The classes provide the following instance methods which you can (depending on the context) use to get or set values within a virtual document:

GetValueAt() method

Returns the value of a virtual property in the message, given a virtual property path.

You can invoke this method (and the next one) from any place in the production where you have access to the message and you can execute custom code — for example, within a BPL <code> element.

SetValueAt() method

Sets a value in the message, given a virtual property path and a value. See the comments for GetValueAt().

Testing Virtual Property Paths in the Terminal

It can be useful to test virtual document property paths in the Terminal before using them in business processes, data transformations, and so on, particularly when you are getting familiar with the syntax. To do so:

  1. Load the corresponding schema into Ensemble, if it is not yet loaded. To do so, see the chapter “Portal Tools.”

  2. In the Terminal or in test code:

    1. Create a string that contains the text of a suitable document.

    2. Use the ImportFromString() method of the applicable virtual document class to create an instance of a virtual document from this string.

      The following table lists the classes:

      Document Type Virtual Document Class
      ASTM EnsLib.EDI.ASTM.Document
      EDIFACT EnsLib.EDI.EDIFACT.Document
      HL7 Version 2 EnsLib.HL7.Message
      XML EnsLib.EDI.XML.Document
    3. Set the DocType property of this instance.

    4. Use the GetValueAt() instance method of this instance.

The following method demonstrates step 2:

ClassMethod TestHL72Path()
 set string="MSH|^~\&|HIHLS6A-223103|AAH|Bayside Medical|AAH|20120421112842||ADT^A11|"
      _"  |||||||||||||||AAH"_$C(13,10)
 set target=##class(EnsLib.HL7.Message).ImportFromString(string,.status)
 if 'status {do $system.Status.DisplayError(status)  quit}
 set target.DocType="2.5:ADT_A09"
 set pathvalue=target.GetValueAt("PID:PatientName.familyname",,.status)
 if 'status {do $system.Status.DisplayError(status)}
 write pathvalue

The following shows output from this method:

ENSDEMO>d ##class(EEDI.CheckPaths).TestHL72Path()