Sending alerts to i2 Analyze users

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.

  • SUCCESS

  • INFORMATION

  • WARNING

  • 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.

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:

For example:

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

[SQL-Server]
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:

For example:

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

[SQL-Server]
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.

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;

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

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

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

      // Create an alert that contains records
      final ISendTo sendToAnalysts = SendTo.createWithGroups("Analyst");
      alertManager.createRecordsAlert(
          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": [
        "h6cBtBz6CuYEU3YwzqUuZEmrhJ",
        "TaUjsCpKUnmY85YWgBQbeNqou2"
    ]
}

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.