Send a Customized Automated Email via Custom Event Handler in WSO2 Identity Server

This blog is to provide the WSO2 Identity Server (IS) users on how to glue together Customize Automated Emails and Custom Event Handler so that the user will be able to trigger a custom email template defined in the authorization flows.

This blog will focus more on the configuration and code and you could find all the definitions and descriptions in the official documentations.

Please find following 2 main steps on getting the this achieved.

Define an custom email template type

First define an email template type as per the instructions provided in the documentation. Select English (United Stated) for the Email Template Locale, if not there will be some code changes to be added to get the locale from the claims as well.

Im using the following template as my email body and please note the two parameterised variables {{user-name}} and {{tenant-domain}}. These will be sent to the email sender via the custom event handler that we are going to define in next step.

The email template that I added is named as CustomLoginSuccessful

Define an custom event handler and integrate with the email template created.

The custom event handler is implemented based on the official documentation. And please find the full code in github.

The WSO2 IS is providing the the capability to listen to many events as mentioned in the documentation such as AUTHENTICATION_STEP_SUCCES, SAUTHENTICATION_STEP_FAILURE, AUTHENTICATION_SUCCESS, AUTHENTICATION_FAILURE, PRE_AUTHENTICATION, etc.in the identity server flows And the full list is mentioned in the github repo file.

Since the documentation explains all the necessary steps on the code, the following will be focussed on gluing the event handler and the email template from now on.

In order to send the emails, WSO2 IS uses this buildNotification() NotificationUtil.java underneath. And all the compulsory atributes thats needed to be sent are as send-to, user-name and TEMPLATE_TYPE. And if we have defined other parameters similar to {{tenant-domain}}, that value has to be passed as well.

• send-to: The email address of the user. This will be extracted using the userstores using the following code block.
• TEMPLATE_TYPE: the name of the custom email template that we defined in the previous step which is CustomLoginSuccessful
• user-name: this is received via the event properties
• tenant-domain: this is received via the event properties

After all these information is collected, You could use the following code to send the event with all those data to that the NotificationUtil.java will use that event to send out the email using the template we have defined.

Event identityMgtEvent = new Event(IdentityEventConstants.Event.TRIGGER_NOTIFICATION, properties);
NotificationTaskDataHolder.getInstance().getIdentityEventService().handleEvent(identityMgtEvent);

Once you have the jar file in the /repository/components/dropins/ folder, and have the following config in /repository/conf/deployement.toml which should be the same as the name in the event handler. Start the product.

[[event_handler]]
name= "customEmailEventHandler"
subscriptions =["POST_AUTHENTICATION"]

You should be able to get the email after a successful login with the cusomized new login template as follows.

Hope you find this article useful when triggering new email templates that you define.