docs.intersystems.com
Home  /  Application Development: Using EDI Documents in Productions  /  Using Virtual Documents in Productions  /  Virtual Property Paths


Using Virtual Documents in Productions
Virtual Property Paths
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


This chapter introduces virtual property paths, which InterSystems IRIS™ uses to access data within virtual documents. It contains the following sections:
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.
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:
The following figure illustrates this convention.
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 %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:
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 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 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
      EDIFACT EnsLib.EDI.EDIFACT.Document
      XML EnsLib.EDI.XML.Document
    3. Set the DocType property of this instance.
    4. Use the GetValueAt() instance method of this instance.