Skip to main content

Virtual Property Paths

This page introduces virtual property paths, which InterSystems IRIS® data platform uses to access data within virtual documents.

Introduction

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 InterSystems IRIS 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 InterSystems IRIS. Once the schema is loaded, InterSystems IRIS has all the information necessary to parse the corresponding documents as intended by the EDI schema.

Parsing EDI Documents: Segments and Fields

For EDIFACT 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 Routing XML Virtual Documents in Productions.)

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 X12, see Separators. The default X12 separators are:

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

    : + ? ' \r \n
    

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.

(The details are different for XML documents; see Routing XML Virtual Documents in Productions.)

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.

Diagram showing how fields in InterSystems IRIS correspond to fields in virtual documents

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:

ORCgrp(1).OBRuniongrp.OBXgrp(3).NTE(1)

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:

SourceofComment

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

ORCgrp(1).OBRuniongrp.OBXgrp(3).NTE(1):SourceofComment

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:

PIDgrp.PID

There could be a field path as follows:

PatientIDInternalID(1).identifiertypecode

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:

3(1).5

The Management Portal provides pages to help you determine the correct segment:field paths. (To access these pages, click Interoperability, 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 Routing XML Virtual Documents in Productions.)

Virtual Document Classes

To work with virtual documents, there is no need to create message classes. InterSystems IRIS provides message classes, for example, one class to carry X12 documents, 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 InterSystems IRIS needs to process the messages. These properties include the following:

DocType property

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

category:structure

Where:

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 %StatusOpens in a new tab 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(myX12Message.BuildMapStatus) in ObjectScript and the method $SYSTEM.Status.IsOK(myMessage.BuildMapStatus) in Basic. If the test returns a True value, BuildMapStatus contains a success value.

  • Use the macro $$$ISERR(myMessage.BuildMapStatus) in ObjectScript and the method $system.Status.IsError(myX12Message.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 Portal Tools.

The virtual document classes also provide the logic that InterSystems IRIS 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 InterSystems IRIS, if it is not yet loaded. To do so, see 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
      EDIFACT EnsLib.EDI.EDIFACT.DocumentOpens in a new tab
      XML EnsLib.EDI.XML.DocumentOpens in a new tab
    3. Set the DocType property of this instance.

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

FeedbackOpens in a new tab