Alert Service

The Alert service logs errors to an independent log file when business processes have errors.

The following table provides an overview of the Alert service:

System name	Alert Service
Graphical Process Modeler (GPM) categories	All Services, System
Description	The Alert service runs as a scheduled service, independent of any specific business process. If an error occurs and is not handled by the business process, the Alert service detects the error and reports it, regardless of the business process that generated the error.
Business usage	Alert service not only provides an optimal method to monitor and notify Sterling B2B Integrator errors in a production environment, also provides flexibility to track specific business processes.
Usage example	The Alert service is an independent business process. It does not need any input and does not work with any other services. You can run the Alert service anytime you want to track failed business processes, and the Alert service sends notification on any error or warning that happens in any business process.
Preconfigured?	No
Requires third-party files?	No
Platform availability	All supported platforms
Related services	None
Application requirements	None
Initiates business processes?	No
Invocation	Not applicable
Business process context considerations	None
Returned status values	None
Restrictions	None
Persistence level	None
Testing considerations	None

How the Alert Service Works

The Alert service runs as a scheduled service, independent of any specific business process. If an error occurs and is not handled by the business process, the Alert service detects the error and reports it, regardless of the business process that generated the error.

If an error occurs in a business process, the Alert service logs notification failures to an independent log file. An external business process can monitor this file for growth to determine whether the Alert service subsystem fails.

The Alert service consists of:

A subsystem controller—the Main Alerter
Individual instances of alerter and filter components
A Sterling B2B Integrator Alert service
A default Sterling B2B Integrator Alert Notification business process

The following figure shows how the components of the Alert service work together:

Main Alerter

The Main Alerter receives event data and delegates the responsibility for notifying the appropriate alerter instances. Each event has a type depending on the data that produced it. All alerters receive the event. The Main Alerter uses filters to determine whether the event needs to be reported. Each alert instance in turn calls the filter method on each of its configured filter instances to determine whether the event should be reported. If a system type event occurs, the Main Alerter immediately calls the configured system alerter as the fallback mechanism for unreportable errors.

Alerters

An alerter is an implementation class that can report an error. One alerter implementation class can have many configured instances that alert in different ways. Two alerter instances are preconfigured: the system alerter and the business process alerter.

The system alerter is the fallback mechanism that writes errors to the Alert service log file. The business process alerter is the default mechanism for executing a business process that sends notification. You can add more alerter instances through Sterling B2B Integrator and more alerter classes by modifying the alerter.properties file.

Filters

A filter is an object that determines which events should or should not be reported. As with alerters, any number of filter instances can be configured per filter implementation class. Each filter instance can be associated with one or more alerters. An alerter can be configured with any number of filter instances. If more than one filter instance is assigned to an alerter, you are prompted to choose whether to combine the filters with AND or OR (default).

If the AND method is used, the alerter uses the minimum value returned by the set of filter instances to determine if an event should be reported. If an OR method is used, the alerter uses the maximum value returned by the filter set to determine whether it should report the event.

For example, consider an alerter instance with two filter instances defined. Each filter returns a return code with a particular weight. One filter instance returns ALERT (1) and the other returns DENY (0). If the alerter is configured in an AND method, the alerter uses the minimum value (DENY) and the event is not reported. If the OR method is specified, the alerter uses the maximum value (ALERT) and the event is reported.

One filter implementation is provided—the XPathFilter. XPathFilter instances enable you to specify an XPath query as criteria. If the Boolean result of evaluating the XPath query against the Event data is true, the XPathFilter returns ALERT. Otherwise, the XPathFilter returns DENY. For a discussion about how XPath expressions are evaluated for Boolean results, see www.w3.org/TR/xpath#section-Boolean-Functions.

Alert Service

The Alert service collects event data from Sterling B2B Integrator and passes that data to the Main Alerter for event notification. It runs at a scheduled interval within the AlertProcess business process within Sterling B2B Integrator. Event data is collected from the database (for information about which business processes have occurred) and from any active threads (for information about what is currently happening).

Alert Notification Business Processes

The Alert Notification business process sends e-mail to all members of the Alert Notifications user group. This business process is a default method of alert notification. It can be changed to accommodate the alerting needs of the particular organization that is hosting Sterling B2B Integrator.

Implementing the Alert Service

By default, when you implement and create a service configuration of the Alert service, the Alert service sends notification on any error or warning that happens in any business process, but this and other behavior is fully customizable.

You can customize the Alert service using the following options:

Modifying the predefined AlertNotification business process
Configuring additional alerters and filter instances for the predefined classes
Implementing new filter and alerter classes to plug in

To implement the Alert service, complete the following tasks:

Create an Alert service configuration. See Managing Services and Adapters.
Configure the Alert service in one of the following methods:
- Accept the default behavior for the Alert service (to send e-mail notification on any business process error or warning).
- Modify the predefined AlertNotification business process. For information, see Modifying the Predefined AlertNotification Business Processes.
- Configure additional alerters and filter instances for the predefined classes. For information, see Configuring Additional Alerters and Filter Instances for Predefined Classes.
- Implement new filter and alerter classes to plug in. For information, see Implementing New Filter Classes to Plug In and Implementing New Alerter Classes to Plug In.
Enable the Alert service schedule.
Use the Alert service in a business process.

Modifying the Predefined AlertNotification Business Processes

The AlertNotification business process performs notification. The default behavior for the AlertNotification process is to send an e-mail message to all members of the Alert Notifications user group. You can change this behavior by modifying the AlertNotification business process using the Sterling B2B Integrator Web administration tool.

From the Business Processes menu, select Manager and search for AlertNotification. Upload a new copy of the process and activate the new version.

If you choose to write your own business process, instead of using the AlertNotification business process, there are some extra steps that need to be taken in order for the system to use the business process defined in the alerter.properties file if it is something other than the default.

Edit the alerter.properties.in for the alerter.2.props.1.value to be set to the new custom business process, as shown in the following example from alerter.properties:

#
# BR Alerter
#
...
alerter.2.props.1.key=process
alerter.2.props.1.value=AlertNotification  (this is the business process to run)
alerter.2.props.2.key=load_status_rpt_and_process_data
alerter.2.props.2.value=true (set this value to true if you want to load the status report into the process data)

Stop Sterling B2B Integrator.
Run setupfiles.sh (UNIX) or setupfiles.cmd (Windows).
Restart Sterling B2B Integrator.
Run setup_alerters.sh (UNIX) or setup_alerters.cmd (Windows).
Note: The instance must be running during the last step.

Configuring Additional Alerters and Filter Instances for Predefined Classes

The alerter and filter configuration are defined in the alerter.properties file and loaded during the Main Alerter initialization process.

The alerter.properties file has the following general form:

# Alerters
alerter.#.id=<alerter_name>
alerter.#.class=<fully qualified class name>
# Alerter supported keys 
# - multiple_filters_logic = [AND | OR]
#
# BP Alerter
# - process = <process_name>
#
# System Alerter
# - logger = <logger_name>
# alerter.#.props.#.key=<key name>
alerter.#.props.#.value=<value for key with corresponding number>
alerter.#.filter.#.name=<filter name>
# Filters
filter.#.class=<fully qualified class name>
filter.#.name=<unique filter name>
filter.#.criteria=<filter criteria data>

Edit the alerter.properties file when the Alert service is offline, or commit changes at run time through Sterling B2B Integrator.

The alerter.properties file has the following default configurations:

Scheduled_AlertService – The Scheduled_AlertService process is the scheduled process that starts the main Alert process. The Alert process is the process that runs AlertService.
This business process has a daily default schedule. If you want to change the Scheduled_AlertService schedule, from the Deployment menu, select Services > Schedules.
AlertNotification – By default, the AlertNotification process processes reported events. The AlertNotification retrieves the e-mail addresses of the members of the Alert Notifications group and sends them e-mail with details of the event.
By default, there is one Alert Notifications group member, the Admin user. You can add or modify receivers of the notifications by adding or removing users from the Alert Notifications group.

The alerter.properties file has the following default properties:

#####################
# Alerters settings #
#####################
#
# System Alerter
#
# class implementations
alerter.1.class=com.sterlingcommerce.woodstock.alert.impl.SystemAlerter
# alerter's id (must be unique)
alerter.1.id=system_alerter
# key for first value of alerter properties 
alerter.1.props.1.key=logger
# Value for first property of alerter properties 
alerter.1.props.1.value=alerterlogger
alerter.1.props.2.key=multiple_filters_logic
# for this property the default value is "OR", the only other you can 
   specify is "AND"
alerter.1.props.2.value=AND
# filter name
alerter.1.filter.1.name=xpathfilter_type_alerter
#
# BR Alerter
#
alerter.2.class=com.sterlingcommerce.woodstock.alert.impl.ProcessLauncherAlerter
alerter.2.id=bp_alerter
alerter.2.props.1.key=process
alerter.2.props.1.value=AlertNotification
alerter.2.props.2.key=multiple_filters_logic
alerter.2.props.2.value=OR
alerter.2.filter.1.name=xpathfilter_bp_status_notSuccess
#####################
#  Filters settings # 
#####################
#
# Filter for status other then success
#
# implementation class
filter.1.class=com.sterlingcommerce.woodstock.alert.filter.XPathFilter
# filter name (must be unique)
filter.1.name=xpathfilter_bp_status_notSuccess
# Filter's criteria (in this case we ignore BProcess of status "SUCCESS" or 
         "WAITING" and state "ACTIVE" )
filter.1.criteria=//EVENT/@type="BUSINESS_PROCESS" and not(//wf_status=0 or 
          //wf_status=3) and  not(//wf_state=0)
#
# Filter for events type "ALERTER"
#
filter.2.class=com.sterlingcommerce.woodstock.alert.filter.XPathFilter
filter.2.name=xpathfilter_type_alerter
filter.2.criteria=//EVENT/@type="ALERTER"

Implementing New Filter Classes to Plug In

A Filter implementation must implement the com.sterlingcommerce.woodstock.alert.filter.Filter interface.

For ease of development, the Alert service API provides a base filter implementation (com.sterlingcommerce.woodstock.alert.filter.FilterBase), which new filter implementations can extend. Derive the new implementation class from this base class and implement the Decide method. If you want your new filter to be loaded on initialization, define properties for it in the alerter.properties file or create a new instance of the filter in Sterling B2B Integrator.

The filter Decide method of the object must return an integer value. The weight of the return code (the positive integer value) is used to determine if an event should be alerted. The greater the weight, the more important the event. A weight of zero indicates that the event should be ignored.

Two default weight constants are provided by the Filter interface: ALERT and DENY. The ALERT constant has a weight of one and the DENY constant has a weight of zero. These constants should be adequate for most filter implementations.

Implementing New Alerter Classes to Plug In

An Alerter implementation must implement the com.sterlingcommerce.woodstock.alert.Alerter interface.

For ease of development, the Alert Service API provides a base alerter implementation (com.sterlingcommerce.woodstock.alert.impl.AlerterBase), which new alerter implementations can extend. Extend the base class and provide the implementation method report. Then, add the Alerter into the alerter.properties file. If you do not add the alerter definitions to this file, your Alerter will not be used.