Sending alerts to i2 Analyze users

i2 Analyze enables system administrators and third-party extensions to send alerts to users of the system. These alerts appear in the Analyst's Notebook Premium client alongside the alerts from Visual Queries that users are familiar with.

In principle, alerts can contain any information that you think it might be useful for i2 Analyze users to receive. In practice, alerts are often about data in the system - to inform users about a change, perhaps, or to warn them that something temporary is soon to be deleted.

Important: Alerting is always enabled in deployments that include the Information Store, but by default it is not enabled in deployments that include only the Chart Store. To enable alerting in a Chart Store deployment, you must set EnableAlerting=true in, and then restart the i2 Analyze server.

Creating alerts

The alerts that you create contain an icon, a title, and an optional message. In addition, they can contain either a group of records or a link to an external resource. They can be created through three different APIs:

Each API provides the same control over the contents of alerts. The Java and REST APIs provide additional functionality for specifying the recipients of alerts, based on group membership or command access control permissions. (The stored procedures require recipients to be specified explicitly, one at a time.)

Note: Alerts can only be sent to users who have previously logged in to i2 Analyze. An authorized user who has never logged in will not see alerts that were created and sent before they do so.

Alert structure

The structure of an alert is the same no matter which API creates it. Alerts can contain the following elements:

  • title

    The title is mandatory and should contain a short string that will be displayed for the alert.

  • message

    The message is optional. If supplied, it can contain a longer string with more information than the title.

  • icon

    The icon is optional and determines the image that is shown next to the alert in the user interface. If supplied, it must be one of the following values. If not supplied, it defaults to INFORMATION.




    • ERROR

    • PLUS

    • MINUS

  • record identifiers

    Record identifiers are optional. If they are supplied, the alert links to the specified records or charts and displays them in a results grid (in the same way that Visual Query alert results are displayed).

    Record identifiers cannot be supplied if an href is supplied.

  • href

    The href is optional. If supplied, it should contain a URL for a resource that provides more information or context for the alert. The URL is displayed as a hyperlink in the user interface.

    An href cannot be supplied if record identifiers are supplied.

Database API

The Information Store (or Chart Store, when alerting is enabled) database contains two public stored procedures for creating alerts. To create an alert with an optional hyperlink, use IS_Public.Create_Alert, which takes the following parameters:

ParameterAlert elementDb2 typeSQL Server typeSize

For example:

CALL IS_Public.Create_Alert('test-user', 'For your information', 'Take a look at this link', 'https://example.domain/news/123', 'INFORMATION')

EXEC IS_Public.Create_Alert 'test-user', 'For your information', 'Take a look at this link', 'https://example.domain/news/123', 'INFORMATION'

Note: To send the same alert to multiple users, you must execute the stored procedure multiple times, changing the user_principal_name as required.

To create an alert with one or more record identifiers, use IS_Public.Create_Records_Alert, which takes the following parameters:

ParameterAlert elementDb2 typeSQL Server typeSize
alert_record_ids_csvrecord identifiersVARCHARVARCHAR8000

For example:

CALL IS_Public.Create_Records_Alert('test-user', 'Records added!', 'h6cBtBz6CuYEU3YwzqUuZEmrhJ,TaUjsCpKUnmY85YWgBQbeNqou2', 'New records added from example source', 'PLUS')

EXEC IS_Public.Create_Records_Alert 'test-user', 'Records added!', 'h6cBtBz6CuYEU3YwzqUuZEmrhJ,TaUjsCpKUnmY85YWgBQbeNqou2', 'New records added from example source', 'PLUS'

Note: Alerts that you create through this stored procedure can contain at most 242 records, because of the sizes of record identifiers and the alert_record_ids_csv parameter. The Java and REST APIs call the stored procedure, so they have the same limit.

Java API

The Java API for creating alerts is available through the API for creating custom, scheduled tasks.

The API provides the ability to identify the recipients of an alert by specifying lists of users, groups, and command access control permissions. The criteria are ORed together inclusively, so only one criterion must be met in order for a user to receive an alert. It is also possible to specify that an alert should be sent to all system users.

Note: You can send an alert to all users that are in the Analyst group OR the Clerk group. But you cannot specify that an alert should be sent only to users that are members of both the Analyst group AND the Clerk group.

For example:

package com.example.tasks;

import com.i2group.disco.alerts.AlertIcon;
import com.i2group.disco.alerts.IAlertManager;
import com.i2group.disco.alerts.ISendTo;
import com.i2group.disco.alerts.SendTo;
import com.i2group.disco.task.spi.CustomTaskFailedException;
import com.i2group.disco.task.spi.IScheduledTask;
import com.i2group.tracing.ITracer;
import java.sql.SQLException;
import java.util.List;

public class ExampleCustomTask implements IScheduledTask {
  private IScheduledTaskObjects scheduledTaskObjects;

  public void onStartup(IScheduledTaskObjects scheduledTaskObjects) {
    this.scheduledTaskObjects = scheduledTaskObjects;

  public void run() {
    final IAlertManager alertManager = scheduledTaskObjects.getAlertManager();

    try {
      // Create an alert with a hyperlink
      final ISendTo sendToTestUser = SendTo.createWithUsers("test-user");
          sendToTestUser, "For your information",
          AlertIcon.INFORMATION, "Take a look at this link",

      // Create an alert that contains records
      final ISendTo sendToAnalysts = SendTo.createWithGroups("Analyst");
          sendToAnalysts, "Records added!",
          AlertIcon.PLUS, "New records added from example source",
          List.of("h6cBtBz6CuYEU3YwzqUuZEmrhJ", "TaUjsCpKUnmY85YWgBQbeNqou2"));
    } catch (SQLException ex) {
      final ITracer tracer = scheduledTaskObjects.getTracerFactory().getTracer(getClass());
      tracer.warn("Could not create alert", ex);
      throw CustomTaskFailedException.reschedule("Failed to create alerts. Will try again later.");


The REST API for creating alerts maps to the Java API and provides the same functionality. You can view the documentation for the REST API on a running i2 Analyze server at /opal/doc/#!/alerts.

Important: In order to use the REST API for creating alerts, you must be logged in to the i2 Analyze server as a user with the i2:AlertsCreate command access control permission.

For example, the following POST request creates an alert that contains a link, and sends it to the user named test-user:

POST http://<server-name>:9082/opal/api/v1/alerts
    "title": "For your information",
    "sendTo": {
        "users": ["test-user"]
    "icon": "INFORMATION",
    "message": "Take a look at this link",
    "href": "https://example.domain/news/123"

And the next POST request creates an alert that contains records, and sends it to all the users in the Analyst group:

POST http://<server-name>:9082/opal/api/v1/alerts
    "title": "Records added!",
    "sendTo": {
        "groups": ["Analyst"]
    "icon": "PLUS",
    "message": "New records added from example source",
    "recordIdentifiers": [

In either case, the response might look like this:

  "sentToCount" : 1

The sentToCount field indicates how many users the alert was sent to. If the count is different from what you expected - too high or too low - you can enable DEBUG logging on the com.i2group.disco.alerts.SendToResolver class, and send the request again to see an explanation in the server logs of who the alert was sent to.

Deleting alerts

To delete an alert programmatically, use the database view named IS_Public.Alerts_DV. Alerts can be deleted through this view with standard SQL expressions.

For example, to delete all alerts, execute:

DELETE FROM IS_Public.Alerts_DV;

To delete specific alerts, use a WHERE clause. For example, to delete all alerts sent more than 30 days ago (on Db2):

DELETE FROM IS_Public.Alerts_DV WHERE create_time_stamp < NOW() - 30 DAYS;

Note: A user who has received an alert can delete it for themselves through the user interface in i2 Analyst's Notebook Premium.