Notifications (Projects > your_project > Project Settings > Notifications ) are events to which you can subscribe. When they are triggered, they deliver a message to an external target system such as emails, Amazon SQS or SNS systems or HTTP post requests. The following table describes available system events to which you can subscribe:
Description
Code
Details
Payload
Emitted when an analysis fails
When you subscribe to overlapping event codes such as ICA_EXEC_002 (analysis success) and ICA_EXEC_028 (analysis status change) you will get both notifications when analysis success occurs.
Delivery Targets
Event notifications can be delivered to the following delivery targets:
Delivery Target
Description
Value
Subscribing to Notifications
To create a subscription via the GUI, select Projects > your_project > Project Settings > Notifications > +Create > ICA event. Select an event from the dropdown menu and fill out the requested fields, depending on the selected delivery targets, the fields will change.
Once created, you can disable, enable or delete the notification subscriptions at Projects > your_project > Project Settings > Notifications.
Amazon Resource Policy Settings
In order to allow the platform to deliver events to Amazon SQS or SNS delivery targets, a cross-account policy needs to be added to the target Amazon service.
Substitute the variables in the example above according to the table below.
See examples for setting policies in and .
Amazon SNS Topic
To create a subscription to deliver events to an Amazon SNS topic, you can use either the GUI or API endpoints.
To create a subscription via the GUI, select Projects > your_project > Project Settings > Notifications > +Create > ICA event. Select an event from the dropdown menu, insert optional filter, select the channel type (SNS), and then insert the ARN from the target SNS topic and the AWS region.
To create a subscription via API, use the endpoint /api/notificationChannel to create a channel and then /api/projects/{projectId}/notificationSubscriptions to create a notification subscription.
Amazon SQS Queue
To create a subscription to deliver events to an Amazon SQS queue, you can use either GUI or API endpoints.
To create a subscription via the GUI, select Projects > your_project > Project Settings > Notifications > +Create > ICA event.
Select an event from the dropdown menu
Choose SQS as the way to receive the notifications and enter your SQS URL.
Depending on the event, you can choose a payload version. Not all payload versions are applicable for all events and targets, so the system will filter the options out for you.
To create a subscription via API, use the endpoint /api/notificationChannel to create a channel and then /api/projects/{projectId}/notificationSubscriptions to create a notification subscription.
Messages delivered to AWS SQS contain the following event body attributes:
The following example is a Data Updated event payload sent to an AWS SQS delivery target (condensed for readability):
Notification subscriptions will trigger for all events matching the configured event type. A filter may be configured on a subscription to limit the matching strategy to only those event payloads which match the filter.
The filter expressions leverage the library for describing the matching pattern to be applied to event payloads. The filter must be in the format [?(<expression>)].
The Analysis Success event delivers a JSON event payload matching the Analysis data model (as output from the API to ).
The below examples demonstrate various filters operating on the above event payload:
Filter on a pipeline, with a code that starts with ‘Copy’. You’ll need a regex expression for this:
[?($.pipeline.code =~ /Copy.*/)]
Filter on status (note that the Analysis success event is only emitted when the analysis is successful):
[?($.status == 'SUCCEEDED')]
Examples for other events
Filtering ICA_DATA_104 on owning project name. The top level keys on which you can filter are under the payload key, so payload is not included in this filter expression.
[?($.details.owningProjectName == 'my_project_name')]
Custom events let you trigger notification subscriptions using event that are not part of the system-defined event types. When creating a custom subscription, a custom event code can be specified to use within the project. Events can then be sent to the specified event code using a POST API with the request body specifying the event payload.
Custom events can be defined using the API. To create a custom event for your project, follow the steps below:
Create a new custom event POST {ICA_URL}/ica/rest/api/projects/{projectId}/customEvents
a. Your custom event code must be 1-20 characters long, e.g. 'ICA_CUSTOM_123'.
b. This event code will be used to reference that custom event type.
Create a new notification channel POST {ICA_URL}/ica/rest/api/notificationChannels
a. If there already is a notification channel with the desired configuration within the same project, you can get the existing channel ID using the call GET {ICA_URL}/ica/rest/api/notificationChannels.
To create a subscription via the GUI, select Projects > your_project > Project Settings > Notifications > +Create > Custom event.
Once the steps above have been completed successfully, the call from the first step POST {ICA_URL}/ica/rest/api/projects/{projectId}/customEvents could be reused with the same event code to continue sending events through the same channel and subscription.
Below is a sample Python function used inside an ICA pipeline to post custom events for each failed metric:
