Skip to main content

Configuring the Enterprise Message Bank and Its Clients

The Enterprise Message Bank is an optional remote archiving facility where you can collect messages, Event Log items, and search table entries from multiple InterSystems IRIS® data platform client productions. This topic describes how to configure the Message Bank and its client systems.

Configuring the Message Bank

After defining the Enterprise Message Bank production, you may need to perform additional configuration, described here.

Specifically, the Ens.Enterprise.MsgBank.TCPServiceOpens in a new tab component on the Message Bank server helps process the incoming messages from the Message Bank client productions. If you have configured enterprise systems, the TCPService uses the information that you defined to associate the incoming message with the enterprise system. See Identifying Enterprise Systems for Viewing and Monitoring for details on configuring enterprise systems. If you do not identify the enterprise system, the monitor service identifies the incoming message based on the elements of the message.

There are two cases where there may be conflicting information to identify the enterprise system sending the message:

  1. If the enterprise system has multiple IP addresses and the system restarts it may be sending messages from a different IP address. To instruct the Message Bank to recognize that these messages are coming from the same enterprise system as the earlier messages, select the Ignore Client IP Changes check box on the Ens.Enterprise.MsgBank.TCPServiceOpens in a new tab.

  2. Although it is not a recommended configuration, it is possible to terminate an enterprise system and restart a new one with the exact same configuration and name but resetting the message IDs. Since the message IDs are not related to the ones in the messages sent by the previous enterprise system, the Message Bank should treat it as a new enterprise system. In this case you should clear the Ignore Client IP Changes check box on the Ens.Enterprise.MsgBank.TCPServiceOpens in a new tab.

The Ignore Client IP Changes check box does not affect how the Message Bank treats enterprise systems that are part of an InterSystems IRIS mirror set (see Mirroring Architecture and Planning).

Configuring a Client Production to Send Messages

You must configure each desired client production to send messages to the Message Bank. For each client production, perform the following configuration steps:

  1. Add the specialized message bank operation (Ens.Enterprise.MsgBankOperationOpens in a new tab) to the production and configure it as needed.

    Note:

    For this business host, Operation Name must be the Message Bank operation class name. Either leave this blank to use the default class name or enter Ens.Enterprise.MsgBankOperation.

    See the following subsection for configuration details.

  2. If you have not yet done so, configure the link to the Message Bank, as described in the previous section.

    Or navigate to the Interoperability > View > Enterprise Message Bank page. The first time you enter the Enterprise Message Bank page, InterSystems IRIS prompts you for information to define the link. This information is the same as described earlier.

Now the production is configured to send messages to the Message Bank.

Important:

While the Enterprise Message Bank can receive messages without having the sending production listed as an enterprise system, it cannot resend messages without access to the credentials. Identifying Enterprise Systems for Viewing and Monitoring has instructions on enabling access to productions, so that messages can be resent.

Note that as of 2024.2, this business operation has a default ResponseTimeout setting of two minutes, to reduce the possibility of the same message being banked repeatedly. Also, a warning is logged each time the ResponseTimeout is triggered, stating the current response timeout value and size of the message body being banked.

Configuring a Message Bank Business Operation

Configure the following settings specifically for the Message Bank:

Enable Archiving

Set to True. This starts messages queuing from all business hosts in the client production. Note that this queueing continues even if you disable the operation and while it is not able to connect to the Message Bank. The operation forwards any queued messages to the Message Bank server whenever it is enabled.

If set to False, the operation does not queue any messages for the Message Bank.

IP Address

IP address of the Message Bank production. Note that this does not include the web server port number.

Port

TCP port number used by the Message Bank production input service (9192 is the default).

Optionally configure the following additional settings:

Archive Items

Controls which messages to send to the Message Bank. The default behavior is to archive everything except scheduler messages as shown by the value:

*[*],-Ens.ScheduleService[*],-Ens.ScheduleHandler[*]

See the following subsection.

Event Log Interval

How frequently should we check for conforming Event Log events that may need to be forwarded to the Message Bank server. 0 means check only when messages are being forwarded.

Force Keepalives

If set to True, send empty event submissions periodically if no conforming events need to be submitted.

MyForceIPAddr

IP address to report to the Message Bank server. If you do not specify a value, the business operation queries the local system and reports the local IP address.

You may choose to specify an IP address for several reasons:

  • The client machine is a member of a cluster with a common cluster IP address. If you specify the cluster IP address, the Message Bank server responds to the cluster rather than to the client machine.

  • The client machine is multi-homed and associated with more than one local IP address. In this situation, you can specify which local IP address the business operation reports to the Message Bank server. Doing so prevents the Message Bank server from generating multiple Node Id values for the client machine.

You can modify the MyForceIPAddr setting only from the ObjectScript shell by defining the MyForceIPAddr node of the ^Ens.MsgBank global, for example:

set ^Ens.MsgBank("MyForceIPAddr") = "192.0.2.23"

Specifying the MyForceIPAddr setting may prevent the Message Bank server from automatically recognizing that a client has been upgraded or otherwise modified. Additionally, the setting may prevent the Message Bank from generating new Node Id values for client machines that report the same Node Id value. If multiple client machines contribute messages under the same Node Id, message ID collisions in the Message Bank repository may occur.

For information on other settings, see the following:

Details for the Archive Items Setting

The Archive Items setting controls which messages the production sends to the Message Bank. It is a comma-separated list of configuration names of items whose messages are to be archived to the Message Bank server.

Archive log events for each item using the following colon-separated syntax:

item[evtype1:evtype2:Trace_cat]

Within the event type brackets, you can use the following characters in your selection list:

Pattern character Placement Resulting action
*   include all event types
- at the front of an item exclude the type from archiving entirely
! at the end of an item exclude message bodies from archiving
$ at the end of an item exclude search table entries from archiving
- at the end of an item exclude message headers from archiving
_ for events of type Trace optionally used to select a particular category of trace event. Event type Trace without a suffix means Trace events of all categories.

For example:

  • *[*]—Archive everything

  • *$[*],Ens.Alert![-*]—Archive all events, headers, and bodies but not SearchTable entries; but do not archive bodies or events from item Ens.Alert.

Note:

InterSystems IRIS only archives trace events if it has logged them. You can use these settings only to restrict which logged events get archived, not to archive any events that you did not configure to be logged.

See Also

FeedbackOpens in a new tab