# Notifications

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:

<table><thead><tr><th width="165">Description</th><th width="152">Code</th><th width="266">Details</th><th>Payload</th></tr></thead><tbody><tr><td>Analysis failure</td><td>ICA_EXEC_001</td><td>Emitted when an analysis fails</td><td>Analysis</td></tr><tr><td>Analysis success</td><td>ICA_EXEC_002</td><td>Emitted when an analysis succeeds</td><td>Analysis</td></tr><tr><td>Analysis aborted</td><td>ICA_EXEC_027</td><td>Emitted when an analysis is aborted either by the system or the user</td><td>Analysis</td></tr><tr><td>Analysis status change</td><td>ICA_EXEC_028</td><td>Emitted when an state transition on an analysis occurs</td><td>Analysis</td></tr><tr><td>Base Job failure</td><td>ICA_BASE_001</td><td>Emitted when a Base job fails</td><td>BaseJob</td></tr><tr><td>Base Job success</td><td>ICA_BASE_002</td><td>Emitted when a Base job succeeds</td><td>BaseJob</td></tr><tr><td>Data transfer success</td><td>ICA_DATA_002</td><td>Emitted when a data transfer is marked as Succeeded</td><td>DataTransfer</td></tr><tr><td>Data transfer stalled</td><td>ICA_DATA_025</td><td>Emitted when data transfer hasn't progressed in the past 2 minutes</td><td>DataTransfer</td></tr><tr><td>Data &#x3C;action></td><td>ICA_DATA_100</td><td>Subscribing to this serves as a wildcard for all project data status changes and covers those changes that have no separate code. This does not include DataTransfer events or changes that trigger no data status changes such as adding tags to data.</td><td>ProjectData</td></tr><tr><td>Data linked to project</td><td>ICA_DATA_104</td><td>Emitted when a file is linked to a project</td><td>ProjectData</td></tr><tr><td>Data can not be created in non-indexed folder</td><td>ICA_DATA_105</td><td>Emitted when attempting to create data in a non-indexed folder</td><td>ProjectData</td></tr><tr><td>Data deleted</td><td>ICA_DATA_106</td><td>Emitted when data is deleted</td><td>ProjectData</td></tr><tr><td>Data created</td><td>ICA_DATA_107</td><td>Emitted when data is created</td><td>ProjectData</td></tr><tr><td>Data uploaded</td><td>ICA_DATA_108</td><td>Emitted when data is uploaded</td><td>ProjectData</td></tr><tr><td>Data updated</td><td>ICA_DATA_109</td><td>Emitted when data is updated</td><td>ProjectData</td></tr><tr><td>Data archived</td><td>ICA_DATA_110</td><td>Emitted when data is archived</td><td>ProjectData</td></tr><tr><td>Data unarchived</td><td>ICA_DATA_114</td><td>Emitted when data is unarchived</td><td>ProjectData</td></tr><tr><td>Job status changed</td><td>ICA_JOB_001</td><td>Emitted when a job changes status (INITIALIZED, WAITING_FOR_RESOURCES, RUNNING, STOPPED, SUCCEEDED, PARTIALLY_SUCCEEDED, FAILED)</td><td>JobId</td></tr><tr><td>Sample completed</td><td>ICA_SMP_002</td><td>Emitted when a sample is marked as completed</td><td>ProjectSample</td></tr><tr><td>Sample linked to a project</td><td>ICA_SMP_003</td><td>Emitted when a sample is linked to a project</td><td>ProjectSample</td></tr><tr><td>Workflow session start</td><td>ICA_WFS_001</td><td>Emitted when workflow is started</td><td>WorkflowSession</td></tr><tr><td>Workflow session failure</td><td>ICA_WFS_002</td><td>Emitted when workflow fails</td><td>WorkflowSession</td></tr><tr><td>Workflow session success</td><td>ICA_WFS_003</td><td>Emitted when workflow succeeds</td><td>WorkflowSession</td></tr><tr><td>Workflow session aborted</td><td>ICA_WFS_004</td><td>Emitted when workflow is aborted</td><td>WorkflowSession</td></tr></tbody></table>

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.

{% hint style="info" %}
When integrating with external systems, it is advised to not solely rely on ICA notifications, but to also add a polling system to check the status of long-running tasks. For example verifying the status of long-running (>24h) analyses with a 12 hour interval.
{% endhint %}

## Delivery Targets

Event notifications can be delivered to the following delivery targets:

<table><thead><tr><th width="138">Delivery Target</th><th width="235">Description</th><th>Value</th></tr></thead><tbody><tr><td>Mail</td><td>E-mail delivery</td><td>E-mail Address</td></tr><tr><td>Sqs</td><td>AWS SQS Queue</td><td>AWS SQS Queue URL</td></tr><tr><td>Sns</td><td>AWS SNS Topic</td><td>AWS SNS Topic ARN</td></tr><tr><td>Http</td><td>Webhook (POST request)</td><td>URL</td></tr></tbody></table>

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

<figure><img src="https://3193631692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWUqIqZhOK_i4HqCUpT%2Fuploads%2Fgit-blob-8915464c6a045c46f8e1e761f1977d5e97681bc1%2Fimage%20(51).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

Once created, you can **disable**, **enable** or **delete** the notification subscriptions at **Projects > your\_project > Project Settings > Notifications**.

{% hint style="info" %}
Subscriptions can only be deleted if there are no failed or pending notifications, so if the delete button is not available, look at the failed notifications details of the subscription. **Projects > your\_project > Project Settings > Notifications > your\_notification > Delivery failed** tab. From there, either reprocess or delete the failed notification so you can delete the notification subscription.
{% endhint %}

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

```json
{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Principal":{
            "AWS":"arn:aws:iam::<platform_aws_account>:root"
         },
         "Action":"<action>",
         "Resource": "<arn>"
      }
   ]
}
```

Substitute the variables in the example above according to the table below.

<table><thead><tr><th width="229.9296875">Variable</th><th>Description</th></tr></thead><tbody><tr><td>platform_aws_account</td><td>The platform AWS account ID: <code>079623148045</code></td></tr><tr><td>action</td><td>For SNS use <code>SNS:Publish</code>. For SQS, use <code>SQS:SendMessage</code></td></tr><tr><td>arn</td><td>The Amazon Resource Name (ARN) of the target SNS topic or SQS queue</td></tr></tbody></table>

See examples for setting policies in [Amazon SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-basic-examples-of-sqs-policies.html) and [Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-access-policy-use-cases.html).

### Amazon SNS Topic

To create a subscription to deliver events to an Amazon SNS topic, you can use either the GUI or API endpoints.

#### GUI

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.

<figure><img src="https://3193631692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWUqIqZhOK_i4HqCUpT%2Fuploads%2Fgit-blob-e5a67f0d9cf1dc51e13b0e385721825f8a78e882%2Fimage%20(50).png?alt=media" alt=""><figcaption></figcaption></figure>

#### API

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.

#### GUI

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.
* Finally, you can enter a **filter expression** to get only those events are relevant for you. Only those events matching the expression will be received.

#### API

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:

<table><thead><tr><th width="209.91796875">Attribute</th><th>Description</th></tr></thead><tbody><tr><td>correlationId</td><td>GUID used to identify the event</td></tr><tr><td>timestamp</td><td>Date when the event was sent</td></tr><tr><td>eventCode</td><td>Event code of the event</td></tr><tr><td>description</td><td>Description of the event</td></tr><tr><td>payload</td><td>Event payload</td></tr></tbody></table>

The following example is a Data Updated event payload sent to an AWS SQS delivery target (condensed for readability):

```json
{
    "correlationId": "2471d3e2-f3b9-434c-ae83-c7c7d3dcb4e0",
    "timestamp": "2022-10-06T07:51:09.128Z",
    "eventCode": "ICA_DATA_100",
    "description": "Data updates",
    "payload": {
        "id": "fil.8f6f9511d70e4036c60908daa70ea21c",
        ...
    }
}
```

## Filtering

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 [JsonPath](https://github.com/json-path/JsonPath) library for describing the matching pattern to be applied to event payloads. The filter must be in the format `[?(<expression>)]`.

### Examples

The ***Analysis Success*** event delivers a JSON event payload matching the ***Analysis*** data model (as output from the API to [retrieve a project analysis](https://ica.illumina.com/ica/api/swagger/index.html#/Project%20Analysis/getAnalysis)).

```json
 {
     "id": "0c2ed19d-9452-4258-809b-0d676EXAMPLE",
     "timeCreated": "2025-10-16T23:41:04Z",
     "timeModified": "2025-10-17T00:08:00Z",
     "owner":
         {
         "id": "15d51d71-b8a1-4b38-9e3d-74cdfEXAMPLE"
         },
     "tenant":
         {
         "id": "022c9367-8fde-48fe-b129-741a4EXAMPLE",
         "name": "ExampleTenant"
         },
     "reference": "210920-1-CopyToolDev-9d78096d-35f4-47c9-b9b6-e0cbcEXAMPLE",
     "userReference": "210920-1",
     "pipeline":
        {
            "id": "20261676-59ac-4ea0-97bd-8a684EXAMPLE",
            "urn": "urn:ilmn:ica:pipeline:20261676-59ac-4ea0-97bd-8a684EXAMPLE",
            "timeCreated": "2023-07-12T20:03:23Z",
            "timeModified": "2023-07-12T20:03:32Z",
            "owner":
            {
                "id": "15d51d71-b8a1-4b38-9e3d-74cdfEXAMPLE"
            },
            "tenant":
            {
                "id": "022c9367-8fde-48fe-b129-741a4EXAMPLE",
                "name": "ExampleTenant"
            },
            "code": "CopyToolDev",
            "description": "Copy Tool Demonstration",
            "status": "RELEASED",
            "language": "NEXTFLOW",
            "languageVersion":
            {
                "id": "b1585d18-f88c-4ca0-8d47-34f6c01eb6f3",
                "name": "22.04.3",
                "language": "NEXTFLOW"
            },
            "pipelineTags":
            {
                "technicalTags":
                ["Demo"]
            },
            "analysisStorage":
            {
                "id": "6e1b6c8f-f913-4332-9bd0-7fc13eda0fd0",
                "name": "Small",
                "description": "1.2TB"
            },
            "proprietary": false,
            "inputFormType": "XML",
            "reportConfigs":
            {
                "configs":
                []
            }
        },
        "status": "SUCCEEDED",
        "startDate": "2025-10-16T23:41:22Z",
        "endDate": "2025-10-17T00:07:52Z",
        "analysisStorage":
        {
            "id": "6e1b6c8f-f913-4362-9bd0-7fc13eda0fd0",
            "name": "Small",
            "description": "1.2TB"
        },
        "analysisPriority": "HIGH",
        "tags":
        {
            "technicalTags":
            [],
            "userTags":
            [],
            "referenceTags":
            []
        },
        "application":
        {
            "id": "e395cd36-9b1f-4f51-bec0-d4e940cd0739",
            "name": "ICA"
        }
}
```

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

  Both payload Version V3 and V4 guarantee the presence of the final state (SUCCEEDED, FAILED, FAILED\_FINAL, ABORTED) but depending on the flow (so not every intermediate state is guaranteed):

  * V3 can have status REQUESTED - IN\_PROGRESS - SUCCEEDED
  * V4 can have status REQUESTED - QUEUED - INITIALIZING - PREPARING\_INPUTS - IN\_PROGRESS - GENERATING\_OUTPUTS - SUCCEEDED
* **Filter on pipeline**, having a **technical tag** “Demo":

  `[?('Demo' in $.pipeline.pipelineTags.technicalTags)]`
* **Combination of multiple expressions** using `&&`. It's best practice to surround each individual expression with parentheses:

  `[?(($.pipeline.code =~ /Copy.*/) && $.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

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.

#### API

Custom events can be defined using the API. To create a custom event for your project, follow the steps below:

1. 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.
2. 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`.
3. Create a notification subscription `POST {ICA_URL}/ica/rest/api/projects/{projectId}/customNotificationSubscriptions`.\
   a. Use the event code created in step 1.\
   b. Use the channel ID from step 2.

#### GUI

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:

```
def post_custom_event(metric_name: str, metric_value: str, threshold: str, sample_name: str):
    api_url = f"{ICA_HOST}/api/projects/{PROJECT_ID}/customEvents"
    headers = {
        "Content-Type": "application/vnd.illumina.v3+json",
        "accept": "application/vnd.illumina.v3+json",
        "X-API-Key": f"{ICA_API_KEY}"
    }
    content = {\"code\": \"ICA_CUSTOM_123\", \"content\": { \"metric_name\": metric_name, \"metric_value\": metric_value,\"threshold\": threshold, \"sample_name\": sample_name}}
    json_data = json.dumps(content)
    response = requests.post(api_url, data=json_data, headers=headers)

    if response.status_code != 204:
        print(f"[EVENT-ERROR] Could not post metric failure event for the metric {metric_name} (sample {sample_name}).")
                
```