Skip to main content

Virtual Documents

This chapter explains what virtual documents are, why there are useful, and how they are different from standard messages. It also briefly introduces tools that Ensemble provides so that virtual documents can be used in all the same ways as standard messages. This chapter contains the following sections:


A virtual document is a kind of message that Ensemble parses only partially. To understand the purpose of virtual documents, it is useful to examine Ensemble messages a little more closely. Every Ensemble message consists of two parts:

  • The message header contains the data needed to route the message within Ensemble. The message header is always the same type of object. This is a persistent object, meaning that it is stored within a table in the Ensemble database.

  • The message body contains the message data. For standard messages, the message body is a persistent object. For virtual documents, the message body is implemented in a different way, as explained below.

An object represents each piece of data as a separate property. This is convenient in that any value in the object is easy to access. When writing code, you simply reference a class property by name to get its value.

For EDI (Electronic Data Interchange) formats, this approach becomes unwieldy and unnecessary. The approach is unwieldy because a large number of properties (possibly hundreds) would be required, and the process of creating an instance of the object can be slow. The standard approach is unnecessary because many applications use only a small number of the fields actually available in the document.

To address these issues, Ensemble provides an alternative type of message body called a virtual document. A virtual document allows you to send raw document content as a body of an Ensemble message, without creating objects to hold the contents of the document as a formal set of properties. The data in the virtual document is stored directly in an internal-use global, for greater processing speed.

The virtual document approach is also useful for XML documents (which can also be handled as standard messages).

Kinds of Virtual Documents

Ensemble can handle the following kinds of documents as virtual documents:

Kind of Document See
ASTM documents Ensemble ASTM Development Guide
EDIFACT documents Ensemble EDIFACT Development Guide
HL7 version 2 messages Ensemble HL7 Version 2 Development Guide
X12 documents Ensemble X12 Development Guide
XML documents Ensemble XML Virtual Document Development Guide

You can also handle XML documents as standard messages. To do so, you can generate classes from the corresponding XML schema. For information, see Using Caché XML Tools.

Other books in the Interoperability set do not describe virtual documents.

Access to Contents of Virtual Documents

To work with data in 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. You can use virtual property paths in the following locations, among others:

  • Business rules. The following shows an example:

    generated description: busrule example

    The curly braces enclose a virtual property path.

  • Data transformations. The following shows an example:

    generated description: dtl example

    For both Property and Value, the curly braces enclose a virtual property path.

As a consequence, your production can work with a virtual document in much the same way that it works with standard messages.

For details, see the chapter “Virtual Property Paths,” later in this book.

Support for Filter and Search

For standard message bodies, each property of the message is directly searchable in the Management Portal. That is, the user can use the property for searching or filtering without having to know its path.

By default, with the exception of the message identifier, none of the data in an virtual document is directly searchable in the Management Portal. That is, a user must know the property path for a data item in order to use that item for searching or filtering.

To assist the user, you can use the following mechanism to make virtual properties directly searchable:

  • You define a search table class; this class uses virtual property paths to define the searchable properties.

  • You configure the applicable business hosts to use the search table class.

    As the business host receives messages, Ensemble indexes these properties as if they were properties in a standard message body.

Users can then use these properties directly without having to know the property paths that they use. For example:

generated description: search table using

For details on defining search tables, see “Defining Search Tables,” later in this book.

FeedbackOpens in a new tab