Sending alerts to i2 Analyze users

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. Alerts can be created through three different APIs:

• Database stored procedures

• The i2 Analyze Java API

• The i2 Analyze REST API

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.

i2 Analyze Developer Essentials contains examples of using the Java API and the REST API to create alerts. For examples of using the database stored procedures, keep reading.

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.

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

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:

Note: Since version 4.4.4 of i2 Analyze, the user_principal_name parameter actually accepts the user identifier. In most deployments, the principal name and the identifier are the same - but if they're not, you must use the identifier instead of the principal name.

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')

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

[SQLServer]
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')

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

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

Note: For both Db2 and SQL Server, any 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. PostgreSQL does not have the same restriction.

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;

[PostgreSQL]
DELETE FROM IS_Public.Alerts_DV WHERE create_time_stamp < NOW() - INTERVAL '30 DAYS';

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