Customizing Alerting

This section describes how to create custom query alerts.

With Query Alerting, users can save queries and be alerted whenever new or modified documents that match these queries are added to the index. You can configure it using the Business Console (see Setting up Query Alerting the Exalead CloudView Business Console User's Guide ) or the MAMI (see below.)

This page discusses:

AlertingManager Class
Manage Alerts
Implement Custom Publishers

AlertingManager Class

The AlertingManager class provides a simple API to manage existing alerts, add new ones, and handles the communication with the Alerting MAMI.

import com.exalead.cloudview.mami.client.ManagersCreator;
import com.exalead.cloudview.alerting.service.AlertingManager;

.
.

ManagersCreator managerCreator = new ManagersCreator(GW_URL, GW_LOGIN, GW_PASSWORD);
AlertingManager alertingManager = managerCreator.get(AlertingManager.class, "/mami/alerting");

Manage Alerts

Create an Alert

When creating an alert, you have to specify the AlertDesc instance.

According to the alerting mode (scheduled or real-time), the following fields are mandatory:


Field	Mandatory for	Example
`NAME`	Scheduled Real-time	-
`USERNAME`	Scheduled Real-time	-
`GROUP`	Scheduled Real-time	When using several groups, use commas as separators. For example, `'group1, group2'`
`QUERY_ARGS`	Scheduled Real-time	For the query `london flat` refined on file extension, language and source: `'cloudview.r=f%2FSource%2F4&cloudview.r=f%2FLanguage%2Fen&cloudview.r=%2Bf%2Ffile_extension%2F6&q=london%20flat&isDebugModeEnable=false& lang=en'`
`PAGE`	Scheduled	-
`UI_LEVEL_QUERY_ARGS`	Scheduled	For the query `london flat` refined on file extension, language and source: `'cloudview.r=f%2FSource%2F4&cloudview.r=f%2FLanguage%2Fen&cloudview.r=%2Bf%2Ffile_extension%2F6&q=london%20flat'`

The Description field is optional.

Sample

import com.exalead.cloudview.alerting.v10.*;

.
.

AlertDesc alertDesc = new AlertDesc().withName(NAME).withUser(USERNAME).withGroup(GROUPS_SEPARATED_BY_COMMA)
.withQueryArgs(MASHUP_API_QUERY_ARGS);
alertDesc.withDescription(DESCRIPTION); // optional
alertDesc.withUiLevelQueryArgs(UI_LEVEL_QUERY_ARGS); // scheduled only, mandatory
alertDesc.withPage(PAGE); // scheduled only, mandatory

AddAlert mAMICmd = new AddAlert();
mAMICmd.withAlertDesc(alertDesc);

alertingManager.addAlert(mAMICmd);

Retrieve Existing Alerts or Alert Groups

Sample for Alerts

import com.exalead.cloudview.alerting.v10.*;

.
.

AlertDescList alertList = alertingManager.getUserAlerts(new GetUserAlerts().withUser(USERNAME).
withGroup(GROUP));
// for a given user & a given group
// or

alertList = alertingManager.getUserAlerts(new GetUserAlerts().withUser(USERNAME).withGroup(GROUP));
// for all users & a given group

for (AlertDesc alertDesc : alertList.getAlertDesc()) { // iterates on retrieved alerts
  // do whatever you want with your alert
}

Sample for Alert Groups

import com.exalead.cloudview.alerting.v10.*;

.
.

AlertingStatus status = alertingManager.getAlertingStatus(new GetAlertingStatus());

for (AlertingGroupStatus groupStatus : status.getAlertingGroupStatus()) {
// iterates on retrieved alert group statuses
  // do whatever you want with your alert group status
  System.out.println("Name: '" + groupStatus.getName() + "'");
  System.out.println("Description: '" + groupStatus.getDescription() + "'");
  System.out.println("Default? '" + groupStatus.isUseAsDefault() + "'");
}

Edit an Alert

When creating an alert, a key is automatically defined to identify it. This key is required to edit an alert and is it retrieved from the Alerting Manager.

Sample

import com.exalead.cloudview.alerting.v10.*;

.
.

AlertDesc anExistingAlert; // retrieve key

anExistingAlert.withName(NEW_ALERT_NAME); // edit alert name

EditAlert editCmd = new EditAlert().withAlertDesc(anExistingAlert);
alertingManager.editAlert(editCmd);

Remove an Alert

When creating an alert, a key is automatically defined to identify it. This key is required to remove an alert and is it retrieved from the Alerting Manager.

Sample

import com.exalead.cloudview.alerting.v10.*;

.
.

AlertDesc anExistingAlert; // retrieve key

anExistingAlert.withName(NEW_ALERT_NAME); // edit alert name

DeleteAlert removeCmd = new DeleteAlert().withKey(anExistingAlert.getKey());
alertingManager.deleteAlert(removeCmd);

Test a Scheduled Alert Group Manually

Sample

import com.exalead.cloudview.alerting.v10.*;

.
.

alertingManager.runAlertGroup(new RunAlertGroup().withGroup(GROUP);
alertingManager.abortAlertGroupRun(new AbortAlertGroupRun().withGroup(GROUP);

Implement Custom Publishers

Using the alerting API, you can implement custom publishers for:

Real-time actions
Scheduled actions

Each custom publisher is made of:

A configuration class
A publisher class

Custom Real-Time Publisher

Publisher Configuration Class

import com.exalead.cloudview.alerting.v2.realtime.CustomRTPublisherConfig;
import com.exalead.config.bean.PropertyLabel;

@PropertyLabel("Log RT Publisher")
public class LogRTPublisherConfig extends CustomRTPublisherConfig {

    private String logPrefix;

    public String getLogPrefix() {
        return logPrefix;
    }

    public void setLogPrefix(String logPrefix) {
        this.logPrefix = logPrefix;
    }

}

Publisher Class

import org.apache.log4j.Logger;

import com.exalead.cloudview.alerting.v2.realtime.CustomRTPublisher;
import com.exalead.cloudview.alerting.v2.realtime.RTAlertOccurrence;
import com.exalead.cloudview.alerting.v2.realtime.RTMatch;
import com.exalead.mercury.component.config.CVComponentConfigClass;

@CVComponentConfigClass(configClass = LogRTPublisherConfig.class)
public class LogRTPublisher extends CustomRTPublisher {

    private final static Logger logger = Logger.getLogger("alerting.v2.rt.log");
    private final LogRTPublisherConfig config;

    public LogRTPublisher(LogRTPublisherConfig config) throws AlertingException {
        this.config = config;
    }

    @Override
    public void onMatch(Context ctx, RTMatch match) throws AlertingException {
        if (ctx.isTesting()) {
          logger.info(config.getLogPrefix() + "#" + "onMatch - testing analysis pipeline");
        } else {
          logger.info(config.getLogPrefix() + "#" + "onMatch");
        }
    }

    @Override
    public void publish(RTAlertOccurrence occurrence) throws AlertingException {
        logger.info(config.getLogPrefix() + "#" + "publish");
    }
}

Custom Scheduled Publisher

Publisher Configuration Class

import com.exalead.config.bean.PropertyLabel;

@PropertyLabel("Log Scheduled Publisher")
public class LogScheduledPublisherConfig extends CustomScheduledPublisherConfig {

    private String logPrefix;

    public String getLogPrefix() {
        return logPrefix;
    }

    public void setLogPrefix(String logPrefix) {
        this.logPrefix = logPrefix;
    }
}

Publisher Class

import com.exalead.cloudview.alerting.v2.AlertingException;
import com.exalead.mercury.component.config.CVComponentConfigClass;
import com.google.common.base.Preconditions;

@CVComponentConfigClass(configClass = LogScheduledPublisherConfig.class)
public class LogScheduledPublisher extends CustomScheduledPublisher {

    private final static Logger logger = Logger.getLogger("alerting.v2.scheduled.log");
    private final LogScheduledPublisherConfig config;

    public LogScheduledPublisher(LogScheduledPublisherConfig config) throws AlertingException {
        super();
        this.config = Preconditions.checkNotNull(config);
    }

    @Override
    public void begin() throws AlertingException {
        logger.info(config.getLogPrefix() + "#" + "Begin");
    }

    @Override
    public void beginUser(String user) throws AlertingException {
        logger.info(config.getLogPrefix() + "#" + "Begin user: " + user);
    }

    @Override
    public void publish(ScheduledAlertOccurrence occurrence) throws AlertingException {
        logger.info(config.getLogPrefix() + "#" + "Publish occurrence of alert: 
" + occurrence.getUnderlyingAlert().getName());
    }

    @Override
    public void endUser(String user) throws AlertingException {
        logger.info(config.getLogPrefix() + "#" + "End user: " + user);
    }

    @Override
    public void end() throws AlertingException {
        logger.info(config.getLogPrefix() + "#" + "End");
    }
}