Skip to main content

Virtual Property Path Basics

Describes how to create a virtual property path.

Introduction

For most EDI formats (not XML virtual documents), a virtual property path has the following syntax:

segmentorsubsegmentID:fieldorsubfieldID

Where:

A virtual property path is relative to a specific message structure, and might not be valid in any other message structure. The Management Portal provides pages to help you determine paths. See the chapter “Portal Tools.”

Important:

For XML virtual documents, the syntax is different. See Ensemble XML Virtual Document Development Guide.

Segment and Subsegment Identifiers

To refer to a segment, use either of the following:

  • Symbolic name of the segment.

    If a message has multiple segments of the same name, append (n) to the end of the identifier, where n is the 1–based position of the desired segment.

  • Number of the segment as contained in the message. Typically this number is not known, so this syntax is less useful. An exception (for HL7 Version 2) is the MSH segment, which is always first.

A segment can have subsegments (which can have further subsegments). To identify a subsegment, use the following syntax:

segmentID.subsegmentID

Where both segmentID and subsegmentID follow the preceding rules for identifying a segment. Note that you cannot mix symbolic names and numeric identifiers. That is, if you use a symbolic name for any part of this syntax, you must use symbolic names in all parts of this syntax. Similarly, if you use the numeric identifier in any part of this syntax, you must use the numeric identifiers in all parts of this syntax.

Field and Subfield Identifiers

To refer to a field, use either of the following:

  • Symbolic name of the field.

    If the parent segment or subsegment has multiple fields of the same name, append (n) to the end of the identifier, where n is the 1–based position of the desired field.

  • Number of the field within the parent segment or subsegment

A field can have subfields (which can have further subfields). To identify a subfield, use the following syntax:

fieldID.subfieldID

Where both fieldID and subfieldID follow the preceding rules for identifying a field. Note that you cannot mix symbolic names and numeric identifiers. That is, if you use a symbolic name for any part of this syntax, you must use symbolic names in all parts of this syntax. Similarly, if you use the numeric identifier in any part of this syntax, you must use the numeric identifiers in all parts of this syntax.

Examples

The following virtual property path accesses the streetaddress subfield of the Address field of the second NK1 segment:

NK1(2):Address.streetaddress

The following virtual property path accesses the streetaddress subfield of the ContactAddress field of the AUTgrp.CTD subsegment of the first PR1grp segment:

PR1grp(1).AUTgrp.CTD:ContactAddress.streetaddress

Special Variations for Repeating Fields

This section describes variations of virtual property paths that apply when you are referring to a repeating field.

Iterating Through the Repeating Fields

When you are using curly bracket {} notation in BPL or DTL, the shortcut () iterates through every instance of a repeating field. For example, consider the following single line of DTL:

<assign property='target.{PID:3().4}' value='"001"'/>

This line is equivalent to the following three lines of equally valid DTL:

<foreach key='i' property='target.{PID:3()}'>
   <assign property='target.{PID:3(i).4}' value='"001"'/>
</foreach>

The same () convention is also available in BPL.

Counting Fields

If the path refers to a repeating field, you can use (*) to return the number of fields. For example, ORCgroup is a repeating field in an HL7 message. The following expression returns the number of ORC groups in the first PID group:

 HL7.{PIDgrpgrp(1).ORCgrp(*)} 
Important:

To count fields within DTL, use ("*") instead of (*).

This syntax is also available for collection properties in standard messages.

Accessing the Last Field in a Set of Repeating Fields

If the path refers to a repeating field, you can use .(-) to return the last field.

This syntax is also available for collection properties in standard messages.

Appending to a Set of Repeating Fields

If the path refers to a repeating field, you can use .() to append another field.

This syntax is also available for collection properties in standard messages.

FeedbackOpens in a new tab