Co-authors: Vanadis Crawford, Mohamed Rafiq and Maria Luisa Lopez de Silanes

Have you come across the need to configure a custom email template for IBM Cloud Logs alerts instead of using the predefined email destination? This blog will show how to configure alert emails with a custom template by using IBM Cloud Internet Services, IBM Cloud Logs, and IBM Event Notifications.

Before you start - some context

Alerts allow for timely detection of anomalies, proactive incident response, improved mean time to resolution (MTTR), and reduced manual monitoring effort. When you design an alert, there are different parts to consider:

• What is the condition that you want to monitor
• Who do you want to notify if the condition is met
• How do you want to notify and through which notification channel

IBM Cloud Logs integrates with IBM Cloud Event Notifications to send notifications of its alerts. In IBM Cloud Logs, you configure the condition of the alert. In Event Notifications, you configure the notification channels where you want to send the notification. Event Notifications offer a range of destinations, also referred as notification channels. For email notifications, it offers 2 types:

• An IBM email destination for sending event notification emails to recipients who need to be aware of events that happen within your IBM Cloud account.
  • This destination can be used to send email notifications for events originating only from IBM Cloud sources.
  • The content sent cannot be modified.
  • This destination is provided by default and is available whenever you create an instance of the Event Notifications service.
  • To receive detailed information about an event notification in your email, you must select the Add notification payload option when you create an Event Notifications subscription.
• A custom email destination for sending emails by using the email address associated with your specific email domain.
  • You can use a custom email template to personalize the content. For more information, see Email Templates.
  • For more information about using custom domains, see IBM Cloud Email service with custom domain.
  • Configuring custom email destinations requires an IBM Cloud Event Notifications instance running the Standard pricing plan. 

Prerequisites

Before you try these steps, make sure:

• You have access and permissions to:
  • An IBM Cloud account 
  • Configure alerts in an IBM Cloud Logs instance. For more information, see Configuring alerts in IBM Cloud Logs.
  • Configure resources in an IBM Cloud Event Notifications instance. For more information, see Configuring routing of events to destinations in IBM Cloud Event Notifications.
  • Configure DNS records in an IBM Cloud Internet Services (CIS) instance.
• The integration between IBM Cloud Logs and IBM Cloud Event Notifications is working. For more information, see Configuring an outbound integration to connect IBM Cloud Logs with IBM Cloud Event Notifications.
• You have the name of the Cloud Internet Services domain in your account. For more information, see Adding domains to your CIS instance.
• You have access to an email account.

Step 1: Add a custom email destination in Event Notifications

You can configure a custom email destination for sending emails by using the email address associated with your specific email domain. For more information, see IBM Cloud Email Service with Custom domain.

To create a custom email destination, complete the following steps:

1. Login to IBM Cloud (https://cloud.ibm.com).
2. Select Resource List.
3. Select the IBM Cloud Event Notifications instance that you want to use.
4.  Select Destinations.
5. Click Add. A popup window opens.
6. Enter a name, choose the Destination type Custom email, and for the Domain, enter monitoring-<ADD YOUR CIS DOMAIN>. For example, you can add a domain such as monitoring-mycompany.com. Notice that you can find the CIS domain in the Overview page of your CIS instance UI.When you add a domain, notice that domain groups should not start or end with hyphens( - ). Top Level Domain (TLD) should contain only alpha numeric characters (A-Z, a-z, 0-9), and between 2 and 63 characters.
7. Click Add. You should see something similar to:

Next, you must configure your CIS instance. The information to configure is available by selecting the yellow exclamation icon that shows with your custom email destination entry. Click the icon and select Configure and Verify.

A window opens with information of 2 TXT records to define in your CIS instance:

Keep this information handy for the next step!

Step 2: Allow Event Notifications to send emails by using a custom email domain configured through IBM Cloud Internet services (CIS)

To configure CIS, you must configure a DNS record. For more information, see Configuring DNS records and settings.

Complete the following steps:

1. Under Resource List, in the Network section, identify your CIS instance and click on it to launch the dashboard.
2. Select Reliability.
3. Select the DNS tab.
4. Look for the DNS records section. Then, click Add.
5. Add the SPF record. Use the data from the previous section. The Sender Policy Framework (SPF) is used to authenticate the sender of an email. SPF specifies the mail servers that are allowed to send email for your domain. With this entry, you are authorizing Event Notifications to send emails through your domain.
6. Click Add again to add the DKIM record. The DomainKeys Identified Mail (DKIM) allows an organization to take responsibility for transmitting a message by signing it. DKIM allows the receiver to check the email that claimed to have come from a specific domain is authorized by the owner of that domain.

Step 3: Configure your custom email destination in Event Notifications

After you have added the TXT records to your DNS, you must verify the configurations. Go back to your Event notifications destination and click Verify on both records. They must turn green.

Next, configure an alert end-to-end so that you are notified via email.

Step 4: Configure an alert

As we explained at the beginning of the blog, there are 2 parts to configuring an alert:

1. Configuring the alert in Cloud Logs, where you define the triggering condition.
2. Configuring Event Notifications to indicate the destination to send the notification.

We are going to configure an alert to test the integration between Cloud Logs and Event Notifications. For more info, see Test your connection. Notice that you can also configure an alert based on your data following Configuring alerts in IBM Cloud Logs. 

Complete the following steps in your Event Notifications instance:

1. Verify the source with name IBM Cloud Logs - <CLOUD_LOGS_INSTANCE_ID>, that matches your integration name, is available in the IBM Cloud Event Notifications instance.

   1. Select Sources.
   2. Look for the source with name IBM Cloud Logs - <CLOUD_LOGS_INSTANCE_ID>.

2. Create a topic that specifies this Cloud Logs instance as the source and "Event type" scoped to "Test Event".

   1. Select Topics. Then, click Create.
   2. Enter a topic name, for example, CloudLogsInstance-test.
   3. Select the source IBM Cloud Logs - <CLOUD_LOGS_INSTANCE_ID> for the instance whose integration you want to test.
   4. Select the Event type Test Event.
   5. Select Add a condition > Save source.
   6. Click Create.
3. Create a subscription pairing the topic and the custom email destination. The subscription defines the alert notifications that are sent based on the topic configuration to the configured destination.
   1. Enter a name, for example, Test integration.
   2. Select the topic CloudLogsInstance-test.
   3. Select a destination.
      
   4. Add the Notification Payload if you want your emails to include a full copy of the alert event that IBM Cloud Logs generates when an alert triggers. Alternatively, you can use an email template with the details that you just want to include in the email. 
   5. Enter the Sender details:
      1. Enter IBM Cloud Logs in From name and Reply name
      2. Enter cloud-logs@monitoring-<ADD YOUR CIS DOMAIN> in From email.
      3. Enter no-reply@ibm.com in Reply to Email. This must be an email on the ibm.com domain.
          
   6. Configure the emails of the recipients that you want to receive the notification via email.

Important: The users that you add will receive an email invitation that they must accept to receive the notifications that are sent through this subscription.

Try it out!

In the IBM Cloud Logs UI, complete the following steps:

1. Edit the outbound integration.
2. Click Test.
3. Check your chosen destination and verify the test event has been sent by checking your email. (Remember you must have accepted the invitation to receive notifications previously. If you have not, you will not receive any test alert notification).