Creating email notification integrations
Use email notification integrations to send custom email messages when incidents are created and closed. Once an email notification integration is set up and running, you can select it from the Notifications area of your Promote alerts to an incident policies.
- About this task
- Prerequisites
- Fields available for inclusion in custom emails
- Creating an email integration
- Editing an email integration
- Deleting an email integration
About this task
Create one or more integrations by defining the integration details that are outlined here. You must provide a source email address (to send the incident notifications from) and the email addresses of recipients. Also, specify what incident details are sent in an email when incidents are created and closed. A default template is provided.
Prerequisites
You need the following information to create an email notification integration:
- Hostname or IP address of your SMTP server
- Port of your SMTP server
- Source (sender) email address
- SMTP credentials for source email address (optional)
- Email addresses of the intended recipients
- Use of TLS to encrypt email
Note: Email notification integration supports the Simple Mail Transfer Protocol (SMTP) authentication exclusively with email addresses being used as the usernames. This approach ensures seamless integration with a wide range of email services. Amazon Simple Email Service (SES) uses non-email usernames as authentication and is therefore not supported with email notification integration until version 4.7.0 and above.
Fields available for inclusion in custom emails
The following dynamic fields are availble for you to include in custom emails:
Field | Type | Description |
---|---|---|
id |
string | A unique identifier for the incident. |
createdTime |
string | Time at which the incident was created. |
createdBy |
string | Person who created the incident. |
title |
string | Short description of the incident. |
description |
string | Longer description of the incident. |
langId |
string | ISO 639-3 language ID. |
priority |
integer | Indication of the relative impact of the issue that caused this incident to be raised. |
state |
string | The current state of the incident. |
lastChangedTime |
string | The time at which the incident last changed. |
owner |
string | The owner assigned to the incident. |
team |
string | The team assigned to the incident. |
alertIds |
array | The set of related alert id's that have triggered the creation of the incident. These alerts affect and are affected by the lifecycle of the incident. The incident will only be automatically resolved if all of the alerts are cleared. When the incident is resolved all of these alerts will be cleared. |
contextualAlertIds |
array | The set of alert id's that provide additional context to the incident due to relationships with the triggering alerts or other contextual alerts. These alerts do not affect or are affected by the lifecycle of the incident. |
insights |
array | An array of insights associated with the incident with one or more other entities or groupings. |
To include a dynamic field, use the following syntax:
$string(incident.<field_name>)
For example, if you want to include the time at which the incident was created, include the following code in the email template:
$string(incident.createdTime)
Creating an email integration
To create an email integration, complete the following steps:
-
Log in to IBM Cloud Pak for AIOps console.
-
Expand the navigation menu (four horizontal bars), then click Define > Integrations.
-
On the Integrations page, click Add integration.
-
From the list of available integrations, find and click the Email Notifications tile.
-
On the side-panel, review the instructions and when ready to continue, click Get started.
Figure. Configure Email Notifications integration -
On the Add integration page, define the general integration details:
-
Name: The display name of your integration. You cannot use spaces or special characters in the display name. Use only alphanumeric characters.
-
Description (optional): Optionally, enter a description of the integration.
-
Hostname or IP address of SMTP server: Enter the hostname or IP address of the SMTP server. Note: If running behind a proxy server, enter the proxy server hostname or IP address.
-
Port of SMTP server: Enter the port of the SMTP server.
Figure. Add Email Notifications integration -
Source email address: The email address that the new incident notifications will be sent from. It is recommended to use a functional email account for this purpose.
-
SMTP password for source email address (optional): Optionally, enter an SMTP password for the source email address.
-
Use TLS to encrypt outbound email (optional): Select from On or Off.
-
Email addresses of recipients: Enter the target email addresses (comma-separated). No more than 50 recipients are allowed per integration.
Important: The notification emails can include confidential information, so be sure to carefully specify the email address of each recipient. To ensure privacy, one recipient cannot see the email addresses of the other recipients.
-
Deployment options: Select one of the options, Local or Remote. Local deploys the integration in the same cluster and project (namespace) where IBM Cloud Pak for AIOps is installed. Alternatively, Remote deploys the integration in your chosen location, such as a different network region, on SaaS, or a remote on-premises VM, cluster, or container.
Note: If you select Remote after adding the integration, you are provided with a bootstrap script to finish the deployment. Download and run the bootstrap script on the remote cluster to complete the deployment.
-
-
Click Next.
-
Customize the content for both the 'Incident created' and the 'Incident closed' emails. You can use the default email templates as-is, or customize them to include different content. A subject and a message must be included; otherwise, an email will not be sent. For details of the fields that you can include, see Fields available for inclusion in custom emails.
Figure. Customize Email Notifications content -
Click Done. You are redirected to the email notification page for the integration.
Your new integration is listed in the table on the page. The integration has an initial status of Initializing. After a few minutes, the status changes to Running if your integration is successful.
Editing an email integration
After you create your integration, you can edit the integration. For example, if you want to add or change the listed recipient email addresses. To edit a integration, complete the following steps:
-
Log in to IBM Cloud Pak for AIOps console.
-
Expand the navigation menu (four horizontal bars), then click Define > Integrations.
-
Click the Email Notifications integration type on the Manage integrations tab of the Integrations page.
-
On the Email Notifications page, click the name of the integration that you want to edit. Alternatively, you can click the options menu (three vertical dots) for the integration and click Edit. The integration configuration opens.
Figure. Edit Email Notifications integration For details of the fields that you can include, see Fields available for inclusion in custom emails .
-
Edit your integration as required. Click Save when you are done editing.
Figure. Edit Email Notifications integration - customize
Your integration is now edited.
Deleting an email integration
If you no longer need your integration and want to delete it entirely, you can delete the integration from the console.
To delete a integration, complete the following steps:
-
Log in to IBM Cloud Pak for AIOps console.
-
Expand the navigation menu (four horizontal bars), then click Define > Integrations.
-
Click the Email Notifications integration type on the Manage integrations tab of the Integrations page.
-
On the Email Notifications integrations page, click the Delete icon for the integration that you want to delete.
-
Enter the name of the integration to confirm that you want to delete your integration. Then, click Delete.
Your integration is deleted in IBM Cloud Pak for AIOps.