Developing Ensemble Productions
Defining an Alert Processor
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

System alerts and user-generated alerts provide a way to inform users of problems in the Ensemble 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 processsor to a production. This chapter describes how to create an alert processor with custom code. It includes the following topics:

Background Information
Your business hosts can send alerts; see Generating Alerts in the chapter Programming in Ensemble.” Ensemble 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, Ensemble automatically sends a specialized request message (Ens.AlertRequest) 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:
In all cases, Ensemble also writes the information to the Ensemble Event Log, with the type Alert.
Note:
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.AlertOperation for the Ens.Alert component. This specialized business operation does the following:
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.AlertOperation, then create a business operation named Ens.Alert as follows:
You might want to define the class so that details such as email addresses and telephone numbers are configurable. See Adding and Removing Settings,” earlier in this chapter.
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.AlertRequest 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.AlertRequest 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:
You could use the class EnsLib.MsgRouter.RoutingEngine 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:
Alert Manager
The Alert Manager has the class Ens.Alerting.AlertManager 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:
  1. 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.
  2. 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:
    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.
  3. 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.AlertManager. 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.NotificationManager and is responsible for determining what groups to notify and which notification operations to use.
The Notification Manager executes in three phases:
  1. 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.
  2. Executes the data transformation if one is configured. See Adding the Notification Manager and Defining Its Data Transformation for information about the data transformation.
  3. 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:
  1. 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.
  2. Evaluate the OverdueAlertRule rule. This rule has access to tOverdueContext. The overdue context provides access to:
    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:
  3. 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.