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 desktop 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, for example, 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 DiscoServerSettingsCommon.properties, 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. 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:

Parameter

Alert element

Db2 type

PostgresSQL type

SQL Server type

Size

user_principal_name

n/a

VARCHAR

VARCHAR

NVARCHAR

256

alert_title

title

VARGRAPHIC

VARCHAR

NVARCHAR

100

alert_message

message

VARGRAPHIC

VARCHAR

NVARCHAR

1000

alert_link

href

VARGRAPHIC

VARCHAR

VARCHAR

256

alert_icon

icon

VARCHAR

VARCHAR

VARCHAR

20

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:

Parameter

Alert element

Db2 type

PostgreSQL type

SQL Server type

Size

user_principal_name

n/a

VARCHAR

VARCHAR

NVARCHAR

256

alert_title

title

VARGRAPHIC

VARCHAR

NVARCHAR

100

alert_record_ids_csv

record identifiers

VARCHAR

TEXT

VARCHAR

8000

alert_message

message

VARGRAPHIC

VARCHAR

NVARCHAR

1000

alert_icon

icon

VARCHAR

VARCHAR

VARCHAR

20

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.