Changing the E-mail template in WSO2 DAS based APIM-Analytics Alerts.

3 min readJul 8, 2021

WSO2 APIM Analytics provides you an alert subscription mechanism to track various alert-related scenarios such as sudden API failures, abnormal API usages, abnormal response times, and etc.

These alerts can be viewed in the admin console and we can subscribe to them to receive an email once an alert is triggered.

We have a default format for these emails. Which is similar to the following template.

APIM Analytics Alert : {{type}}
message:{alert- message}
type:{alert type}
alertTimestamp:{alertTimestamp}

Let’s see how we receive the APIM Health availability alert email when triggered.

If needed, we can change this template for a customized format that may be suits your company format better. Let’s see how we can do that.

So this email template is set via the email event publisher, and if we need to change this we need to update the default carbon application which contains the said event publisher. ( A carbon application in the WSO2 domain is a collection of artifacts deployable on a WSO2 product instance.)

Navigate to <wso2am-analytics-2.1.0>/repository/deployment/server/carbonapps directory.
Edit the org_wso2_carbon_analytics_apim-1.0.0.car (you can change the extension to zip, unzip it)
Navigate to the folder org_wso2_analytics_apim_emailAlertStreamPublisher_1.0.0.
Open org.wso2.analytics.apim.emailAlertStreamPublisher.xml.

<?xml version="1.0" encoding="UTF-8"?>
<eventPublisher name="org.wso2.analytics.apim.emailAlertStreamPublisher"
                statistics="disable" trace="disable" xmlns="http://wso2.org/carbon/eventpublisher">
    <from streamName="org.wso2.analytics.apim.emailAlertStream" version="1.0.0"/>
    <mapping customMapping="enable" type="text">
        <inline>message:{{msg}}
type:{{type}}
alertTimestamp:{{alertTimestamp}}</inline>
    </mapping>
    <to eventAdapterType="email">
        <property name="email.address">{{emails}}</property>
        <property name="email.type">text/plain</property>
        <property name="email.subject">APIM Analytics Alert : {{type}}</property>
    </to>
</eventPublisher>

Change the hard-coded subject and body as per your requirement.
Save the changes, zip the carbon app and change the extension back to .car
And deploy the carbon application.
You can navigate to the analytics management console → manage → publishers → org.wso2.analytics.apim.emailAlertStreamPublisher and observe that the changes you made are reflected.

Change the E-mail template to an HTML format

If needed we can change the template to the HTML format as well.

After opening the org.wso2.analytics.apim.emailAlertStreamPublisher.xml.
Add customMapping xml as <mapping customMapping=”enable” type=”xml”>
Add email type to text/html as <property name=”email.type”>text/html</property>
Add the HTML code within the inline tag of org.wso2.analytics.apim.emailAlertStreamPublisher.xml. file.

<mapping customMapping="enable" type="xml"> 
<inline> 
<html xmlns=""> 
<body> 
<h2>Custom email alert heading</h2> 
<p> <b>The alert type:{{type}}</b> </p> <p>The alert message:{{msg}}</p> 
alertTimestamp:{{alertTimestamp}} 
</body> 
</html> 
</inline> 
</mapping> 
<to eventAdapterType="email"> 
<property name="email.address">{{emails}}</property> 
<property name="email.type">text/html</property> 
<property name="email.subject">APIM Analytics Alert Edited : {{type}}</property>

For testing purposes, we can do this change temporarily using the APIM analytics management console directly as well.

Navigate to the analytics management console → manage → publishers → org.wso2.analytics.apim.emailAlertStreamPublisher
Do the necessary changes
Test by sending an email using the simulator as follow

Navigate to Manage → Event → Flow.

Select the stream org.wso2.analytics.apim.emailAlertStream:1.0.0 (which is the associated stream used to send emails)

Once it is loaded click on simulate events on the right side top corner and fill the relevant fields with mock data.

Make sure to add the correct email address you need to receive the alert.

And see whether you have received the dummy email.

But please keep in mind this will be reverted back to the original format if the server is restarted.

Therefore as the permanent solution, we could stick with editing the XML file within the carbon application.

I hope this blog will be useful if you need to customize the email template as per your requirements. Will get back with another blog soon

Cheers!

Changing the E-mail template in WSO2 DAS based APIM-Analytics Alerts.

Change the E-mail template to an HTML format

Written by Umesha Guruge