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, 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.SUCCESSINFORMATIONWARNINGERRORPLUSMINUS
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 |
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')
[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:
| 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')
[SQL-Server]
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 Premium.