Using Virtual Documents in Productions
Virtual Property Paths
This chapter introduces virtual property paths, which InterSystems IRIS™ 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 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
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:
For details on EDIFACT see Separators
. The default EDIFACT separators are:
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.
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:
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:
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
There could be a field
path as follows:
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 Interoperability
, and then click Interoperate
.) The DTL editor also provides a view of the document structures used in a particular transformation.
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.
The virtual document classes provide properties to carry the information that InterSystems IRIS needs to process the messages. These properties include the following:
Indicates the document type, a string in two parts as follows:
This property is visible in the Management Portal. You can use it for filtering, for example.
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.
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:
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:
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.
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:
In the Terminal or in test code:
Create a string that contains the text of a suitable document.
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:
Set the DocType
property of this instance.