Previous section   Next section

Defining an Enterprise Message Bank

This chapter describes how to define an optional, specialized kind of production called the Enterprise Message Bank. It includes the following sections:
After you have defined the Enterprise Message Bank, see “Configuring the Enterprise Message Bank”’ in Configuring Ensemble.

Overview

The Enterprise Message Bank is an optional remote archiving facility where you can collect messages, Event Log items, and search table entries from multiple Ensemble client productions. It consists of the following components:
  • The Message Bank server, which is a simple Ensemble production consisting exclusively of a Message Bank service that receives submissions from any number of client productions.
  • A client operation (the Message Bank operation) that you add to an Ensemble production and configure with the address of a Message Bank server.
The following shows a conceptual example:
images/egdv_msg_bank_arch.png
So that you can conveniently see the messages in the Message Bank, Ensemble provides the following additional options:
  • For the Message Bank instance, the Management Portal automatically includes the Enterprise Monitor pages, where you can monitor the status of client productions, browse the Message Bank, and perform a search of messages from the monitored clients.
  • For each client instance, you configure a link to the Enterprise Monitor in the Message Bank instance.
The following shows an example:
images/egdv_msg_bank_and_portals.png

Defining the Message Bank Server

To define the Message Bank server, do the following on the server machine, in an Ensemble-enabled namespace:
  1. Create a subclass of the Ens.Enterprise.MsgBank.Production abstract class.
  2. Copy its
    ProductionDefinition
    XData block into your class.
  3. Compile your new class in that namespace.
The following shows an example:
Class MyEnsemble.MyMessageBank Extends Ens.Enterprise.MsgBank.Production
{

XData ProductionDefinition
{
<Production Name="Ens.Enterprise.MsgBank.Production" TestingEnabled="false" LogGeneralTraceEvents="false">
  <Description>Production for receiving and collating message bank submissions from one or more client 
   Ensemble namespaces and for maintaining a local repository of production status information about each
   client namespace, for display on the Enterprise Monitor page. Open the the Monitor page on the same
   machine that that is hosting this Production.</Description>
  <ActorPoolSize>0</ActorPoolSize>
  <Setting Target="Production" Name="ShutdownTimeout">120</Setting>
  <Setting Target="Production" Name="UpdateTimeout">10</Setting>
  <Item Name="MonitorService" Category="" ClassName="Ens.Enterprise.MonitorService" PoolSize="1"
        Enabled="true" Foreground="false" InactivityTimeout="0" Comment="Populates global 
        ^CacheTemp.Ens.EntMonitorStatus by polling namespaces from Systems List every CallInterval seconds"
        LogTraceEvents="false" Schedule="">
    <Setting Target="Host" Name="AlertGracePeriod">0</Setting>
    <Setting Target="Host" Name="AlertOnError">0</Setting>
    <Setting Target="Host" Name="ArchiveIO">0</Setting>
    <Setting Target="Adapter" Name="CallInterval">10</Setting>
  </Item>
  <Item Name="MsgBankService" Category="" ClassName="Ens.Enterprise.MsgBank.TCPService" PoolSize="100"
        Enabled="true" Foreground="false" InactivityTimeout="20" Comment="" LogTraceEvents="true" Schedule="">
    <Setting Target="Host" Name="AlertGracePeriod">0</Setting>
    <Setting Target="Host" Name="AlertOnError">0</Setting>
    <Setting Target="Host" Name="ArchiveIO">0</Setting>
    <Setting Target="Adapter" Name="Endian">Big</Setting>
    <Setting Target="Adapter" Name="UseFileStream">0</Setting>
    <Setting Target="Adapter" Name="JobPerConnection">1</Setting>
    <Setting Target="Adapter" Name="AllowedIPAddresses"></Setting>
    <Setting Target="Adapter" Name="QSize">100</Setting>
    <Setting Target="Adapter" Name="CallInterval">5</Setting>
    <Setting Target="Adapter" Name="Port">9192</Setting>
    <Setting Target="Adapter" Name="StayConnected">-1</Setting>
    <Setting Target="Adapter" Name="ReadTimeout">10</Setting>
    <Setting Target="Adapter" Name="SSLConfig"></Setting>
  </Item>
</Production>
}

}
This production has the following services:
This production receives this data and maintains a local repository.
For testing purposes, you can put the Message Bank production on the same machine and instance as your regular productions, but it must be in a separate namespace from any production you plan to monitor.

Adding a Message Bank Helper Class

By default, the message bodies are not indexed and cannot be searched. You can add a helper class to implement the search capability in the Message Bank. To do so:
  1. Create a subclass of Ens.Enterprise.MsgBank.BankHelperClass and implement its OnBankMsg() method. See the InterSystems Class Reference for details on the method.
    The OnBankMsg() method specifies any custom processing to perform when inbound messages include a message body.
    In your implementation of this method, you should decide whether to handle messages in process (and possibly reduce the input capacity), or whether the method should asynchronously forward the messages to a secondary process to balance the work more effectively.
  2. In the Message Bank production, select the Ens.Enterprise.MsgBank.TCPService business service and specify the Bank Helper Class setting. For the value, use the name of your helper class.

Notes about the Message Bank

Note the following important characteristics of the Message Bank:
  • The Message Bank has no synchronization dependencies for message body classes with the contributing productions; therefore, it receives a serialized form of each message. For virtual document message bodies (HL7, for example), it reparses the serialized document into an object, and receives and stores the search table entries from the contributing production as well. You can perform almost the same search for HL7 messages as on the original machine; however, the same is not true for other types of message bodies.
    To enable searching by HL7 custom schema properties in the Message Bank, make sure to place the custom schema definition in the Message Bank production namespace.
  • For uniqueness, the Message Bank production prepends the numeric identifier of client productions to the message IDs.
  • The Message Bank page also serves as a portal for viewing the state of multiple client productions and for invoking a resend service on them. For these extra features to work, the Message Bank needs to know the web addresses of the client productions. For details, see “Configuring the Enterprise Message Bank”’ in Configuring Ensemble.
  • The Message Bank mechanisms do not delete the messages from the originating production; you should handle that function with a separate purge process.
  • It is possible to replay messages from the Message Bank back into the originating production or another client production. See “Using the Enterprise Message Bank”’ in Monitoring Ensemble.
Previous section   Next section