Configuring the Enterprise Message Bank
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® client productions. This topic describes how to configure it.
Identifying Enterprise Systems for Viewing and Monitoring describes how to configure enterprise systems so that you can resend messages from the Message Bank.
For information on defining the Enterprise Message Bank, which is a specialized production, see Defining an Enterprise Message Bank.
For information on using it, see Using the Enterprise Message Bank.
Configuring the Message Bank Link
The Interoperability > Configure > Message Bank Link page allows you to configure a link (for this namespace) to the Enterprise Message Bank.
On this page, provide the following information so the InterSystems IRIS® can connect to the Message Bank (if defined):
-
Web Server IP Address — Specify the IP address of the machine on which the Message Bank is running.
-
Web Server Port Number — Specify the port number used by the web server that is configured for use with InterSystems IRIS on that machine.
-
Instance Prefix — Specify the path for the instance of InterSystems IRIS on the web server. This is required if you are using HealthShare Health Connect as the target Message Bank. Also, if you are using a different web server, potentially with other instances of InterSystems IRIS using the same web server, you must specify this prefix so that the Message Bank can construct URLs that connect with the correct InterSystems IRIS instance through the web server.
-
Message Bank Production Namespace — Specify the InterSystems IRIS namespace in which the Message Bank production is running.
-
Use SSL To Connect To The Message Bank Web Server — Select this to use TLS to connect to the Message Bank.
For information on defining the Enterprise Message Bank, which is a specialized production, see Defining an Enterprise Message Bank in Developing Productions.
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:
-
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.
-
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, and the Management Portal has a link to the Message Bank web pages.
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. Indentifying Enterprise Systems for Viewing and Monitoring has instructions on enabling access to productions, so that messages can be resent.
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 Terminal 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.
Configuring the Message Bank Service on the Server
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 it there may be conflicting information to identify the enterprise system sending the message:
-
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.
-
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 in the High Availability Guide).
