Defining an Alert Processor
System alerts and user-generated alerts provide a way to inform users of problems in the production. An alert processor is a business host that notifies applicable users via email, text pager, or other mechanism, about a problem that must be corrected. In many cases, you can define an alert processor without creating custom code. See Monitoring Alerts for information on adding an alert processor to a production. This page describes how to create an alert processor with custom code.
Background Information
Your business hosts can send alerts; see Generating Alerts in Programming in InterSystems IRIS. InterSystems IRIS® data platform also automatically sends alerts on specific occasions, depending on the values of settings in the production. If the production includes a business host named Ens.Alert, InterSystems IRIS automatically sends a specialized request message (Ens.AlertRequestOpens in a new tab) to that business host. This business host is the alert processor for the production; any production can contain no more than one of these.
The alert processor can then use the information in this message to determine who must be contacted. There are a couple of general scenarios:
-
If you can handle all alerts via the same output mechanism, the alert processor can be a business operation that uses the applicable adapter. See Using a Simple Email Alert Processor and Using a Simple Outbound Adapter Alert Processor.
-
If you need to route the alert, but do not need to track alert resolution, see Using a Routing Alert Processor.
-
If you want to track the alert resolution process, see Using Alert Management to Track Alert Resolution.
In all cases, InterSystems IRIS also writes the information to the InterSystems IRIS Event Log, with the type Alert.
Ens.Alert is the required name of the business host that serves as the alert processor. Do not confuse this with a class name. The alert processor can use any class name.
Using a Simple Email Alert Processor
If it is appropriate to send all alerts via email, use the class EnsLib.EMail.AlertOperationOpens in a new tab for the Ens.Alert component. This specialized business operation does the following:
-
The ADAPTER parameter is specified as EnsLib.EMail.OutboundAdapterOpens in a new tab.
This adapter provides settings to specify email recipients, as well as information needed to use an SMTP email server.
It also provides helper methods to send email via the configured server.
-
The OnMessage() method is implemented. This method expects Ens.AlertRequestOpens in a new tab as input.
This method does the following:
-
Reads the alert text from the Ens.AlertRequestOpens in a new tab.
-
Creates an email message (an instance of %Net.MailMessageOpens in a new tab) and writes the alert text into that.
-
Sends the email message to all configured recipients.
-
You might be able to use this class without modification. Or you could create and use a subclass of it.
Using a Simple Outbound Adapter Alert Processor
If you can handle all the alerts via the same output mechanism, but you cannot use EnsLib.EMail.AlertOperationOpens in a new tab, then create a business operation named Ens.Alert as follows:
-
Specify the ADAPTER parameter as the name of a suitable adapter class.
-
Implement the OnMessage() method. The signature of this method should be as follows:
Method OnMessage(pRequest As Ens.AlertRequest, Output pResponse As Ens.Response) As %Status {}
In your implementation, call methods of the adapter as needed.
See Defining Business Operations and see the adapter documentation.
You might want to define the class so that details such as email addresses and telephone numbers are configurable. See Adding and Removing Settings.
Using a Routing Alert Processor
If you need to contact users via multiple output mechanisms, the alert processor should be a business process that determines how to route the Ens.AlertRequestOpens in a new tab messages. In this case, your production must contain an additional business operation for each output mechanism, and the alert processor forwards messages to those business operations.
Defining the Alert Processor as a Routing Process
To define the alert processor as a routing process, create a business process class that can receive Ens.AlertRequestOpens in a new tab messages.
The business process would examine the messages and forward them to different business operations, depending on the alert contents and any logic that you include.
Your logic may need to consider the following factors:
-
Different requirements for various users
-
Different requirements depending on the time of day
-
The organization’s problem-solving policies and procedures
You could use the class EnsLib.MsgRouter.RoutingEngineOpens in a new tab as the Ens.Alert routing process. This class provides the setting Business Rule Name. If you specify this setting as the name of a routing rule set, this business host uses the logic in that rule set to forward all the messages that it receives.
Defining the Business Operations
You can define each of the needed business operations as described in Using a Simple Email Alert Processor or Using a Simple Outbound Adapter Alert Processor.
Adding Custom Code to Alert Management
Alert management allows you to assign alerts to users, track the status of alerts, and manage the progress of resolving alerts. For an overview of alert management, see Configuring Alert Management, which describes how to configure alert management components and define rules and data transformations for alert management. This section describes how to add custom code to the alert management components.
The alert management framework has the following architecture:
-
Single persistent object for a managed alert throughout its life cycle.
-
Alert Manager, Notification Manager, and Alert Monitor have the same overall internal structure. When one of these components is invoked, it performs its function in three phases:
-
First, the component executes the OnProcess method if it is implemented by a subclass. By implementing this method, you can include custom code in the component. If the OnProcess method sets a flag indicating that processing is complete, the component exits.
-
Next, the component evaluates its rule or for the Notification Manager its data transformation, which sets parameters that control the component’s actions.
-
Finally, the component performs its action based on either the parameters set by the rule or the defaults set by the component’s configuration.
-
-
The Alert Notification operation is a simpler component that formats and forwards messages to its destinations.
Alert Manager
The Alert Manager has the class Ens.Alerting.AlertManagerOpens in a new tab and must be named Ens.Alert. The Alert Manager receives alerts from all production components. The Alert Manager can promote an alert to a Managed Alert based on the conditions specified in a rule. The Alert Manager sends Managed Alerts to the Notification Manager.
The Alert Manager executes in three phases:
-
If the component’s class overrides the OnCreateManagedAlert() method, execute the override. You can provide custom code to process the alert request and create the managed alert in this method. If do not want the base Alert Manager code to evaluate the rule, create the managed alert, and send it to the Notification Manager, you should set the tProcessingComplete parameter to 1. In that case, the Alert Manager takes no further action.
-
Evaluate the CreateManagedAlertRule rule. This rule has access to tAlertContext. If it returns a true value (1), the Alert Manager creates the managed alert. If it returns false, the Alert Manager does not create the managed alert and the alert is only written to the log. The alert context provides access to:
-
Incoming alert
-
Alert groups configured for the component that originated the alert
-
Business partner configured for the component that originated the alert
-
Alert owner
The rule can suppress promoting the alert to a Managed Alert by returning 0 or can promote the alert to a Managed Alert by returning 1.
-
-
If the rule sets tCreateAlert to 1, the Alert Manager creates a Managed Alert, or, if there is no CreateManagedAlertRule rule defined, the Alert Manager takes the default action and creates a Managed Alert. The Alert Manager creates the Managed Alert by calling the OnCreateManagedAlert() method, which can be overridden by a class extending Ens.Alerting.AlertManagerOpens in a new tab. The default implementation of OnCreateManagedAlert() sets the production name in the Managed Alert and sets the current owner to be unassigned with the value as an empty string. If the Alert Manager creates a Managed Alert, it sends it to the Notification Manager.
Notification Manager
The Notification Manager has the class Ens.Alerting.NotificationManagerOpens in a new tab and is responsible for determining what groups to notify and which notification operations to use.
The Notification Manager executes in three phases:
-
If the component’s class overrides the OnProcessNotificationRequest() method, execute the override. If the override sets the pProcessingComplete parameter to 1, the Notification Manager does not evaluate the tranformation or apply the default action.
-
Executes the data transformation if one is configured. See Adding the Notification Manager and Defining Its Data Transformation for information about the data transformation.
-
If the transformation sets the target.Notify property to 1 or if there is no data transformation, the Notification Manager sends the Alert Notification to the component listed in each target and passes the list of addresses to the target.
The Notification Manager does not receive or send the Managed Alert object, but instead uses the Notification Request object, which contains a reference to the persistent Managed Alert object.
Alert Monitor
The Alert Monitor queries for all open Managed Alerts where the current time exceeds the NextActionTime value. It makes the following SQL query:
SELECT ID FROM Ens_Alerting.ManagedAlert WHERE IsOpen = 1 AND NextActionTime <= ?
where the current time returned by $$$timeUTC is specified as the parameter.
The Alert Monitor handles each returned Managed Alert message separately. For each Managed Alert, it processes it in three phases:
-
If the component’s class overrides the OnProcessOverdueAlert() method, execute the override. You can provide custom code to process the alert. If do not want the base Alert Monitor code to evaluate the rule, update the managed alert, and send it to the Notification Manager, you should set the tProcessingComplete parameter to 1. In that case, the Alert Monitor takes no further action.
-
Evaluate the OverdueAlertRule rule. This rule has access to tOverdueContext. The overdue context provides access to:
-
Incoming alert
-
Current time
-
NewNextActionTime
-
NewEscalationLevel
The rule can suppress sending the reminder by returning 0, can set the next time that the managed alert will be found by the Alert Monitor by setting the NewNextActionTime or can escalate or de-escalate the Managed Alert by setting NewEscalationLevel.
You can override the context of the alert rule and how the Alert Monitor processes the results:
-
You can add additional information to the alert rule context by overriding the GetOnOverdueAlertContext() method.
-
You can override how the Alert Monitor handles the rule results by overriding the OnProcessOverdueRuleResult() method. Otherwise, execute this method in the base class. The OnProcessOverdueRuleResult() method is responsible for escalating the managed alert. The override has access to the managed alert, tOverdueContext, tSendNotification, and tNotificationType. Note that you should either duplicate the functionality of the base class implementation or call it by calling ##super() .
-
-
If the rule returns 1, the Alert Monitor sends the managed alert to the Notification Manager.
Notification Operation
The Notification Operation sends notifications to groups of users. If you are sending notifications using more than one kind of mechanism, you can have a separate Notification Operation for each transmission method.