Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

Defining Ensemble Messages

This chapter describes how to define the classes that define Ensemble message bodies. It contains the following sections:


A message body can be any persistent object.

In practice, you often create a subclass of Ens.Request or Ens.Response and add properties. This creates the standard message body. If you use these classes, you have easy access to the various built-in features for viewing the contents of messages from the Management Portal. These features help developers and administrators detect errors in a running production, especially if the production uses message content to determine where the message should be sent.

Some electronic documents — Electronic Data Interchange (EDI) formats such as HL7 or X12 — contain data that is arbitrarily long and complex. In this case, it is better to use an alternative class, a class that represents an Ensemble virtual document. In this case, the message body does not have a set of properties to contain the message contents. For details, see Ensemble Virtual Documents.

Most of the examples in this book assume a standard message body, with a relatively small number of message properties.

Creating a Simple Message Body Class

To create a message class (to be used as the message body), create a class that:

  • Extends either Ens.Request or Ens.Response.

  • Contains properties as needed to represent elements of data to be carried in the message.

The following shows a simple example:

Class Demo.Loan.Msg.CreditRatingResponse Extends Ens.Response

Property TaxID As %String;

Property CreditRating As %Integer;


The class can also contain methods. For example:

Class Demo.Loan.Msg.Application Extends Ens.Request{

Property Amount As %Integer;
Property Name As %String;
Property TaxID As %String;
Property Nationality As %String;
Property BusinessOperationType As %String;
Property Destination As %String;

Method RecordNumber() As %String
  If ..%Id()="" Do ..%Save()
  Quit ..%Id()

Method GetRecordNumberText(pFormatAsHTML As %Boolean = 0) As %String
  Set tCRLF=$s(pFormatAsHTML:"<br>",1:$c(13,10))
  Set tText=""
  Set tText=tText_"Your loan application has been received,"_tCRLF
  Set tText=tText_"and is being processed."_tCRLF
  Set tText=tText_"Your record number is "_..RecordNumber()_"."_tCRLF
  Set tText=tText_"You'll receive a reply from FindRate"_tCRLF
  Set tText=tText_"within 2 business days."_tCRLF
  Set tText=tText_"Thank you for applying with FindRate."_tCRLF
  Quit tText


If you create a message class that does not extend Ens.Request or Ens.Response:

Creating a Complex Message Body Class

In the previous example, the message body class contained only simple properties. In some cases, you may need to define properties that use other classes. If so, you should carefully consider what to do when you purge message bodies (as described in Managing Ensemble).

When you purge message bodies, Ensemble deletes only the specific message body object. For example, consider the following message class:

Class MyApp.Messages.Person Extends Ens.Response

Property Name As %String;

Property MRN As %String;

Property BirthDate As %Date;

Property Address As MyApp.Messages.Address;


The Address class is as follows:

Class MyApp.Messages.Address Extends %Persistent

Property StreetAddress As %String;

Property City As %String;

Property State As %String;

Property ZIP As %String;


In this case, if you purge message bodies, Ensemble deletes instances of MyApp.Messages.Person, but does not delete instances of MyApp.Messages.Address.

If your message body class uses other classes as properties and if your application requires that any referenced objects should also be purged, use one of the following approaches:

  • Make sure that the referenced classes are serial. For example, redefine the Address class as follows:

    Class MyApp.Messages.Address Extends %SerialObject

    In this case, the data for the Address class is stored as part of the Person class (and is thus automatically purged at the same time).

  • Define the property as a suitable relationship. See “Persistent Behavior of Relationships” in the chapter “Relationships” in Using Caché Objects.

  • Add a delete trigger or %OnDelete() method to the message class so that this class deletes the appropriate records in the referenced classes.

  • Optionally include %XML.Adaptor as a superclass so that the properties defined in the referenced class can be displayed in the Management Portal.