Events Are Opportunities!

Nowadays, web services are rapidly adopting the publisher-subscriber architecture to realize event-driven business cases, such as scheduling asynchronous jobs, sending push notifications, IoT applications, and data streaming. The key point to understand in the architecture is, the publisher and the subscriber asynchronously communicate with each other with the help of message broker, and they are decoupled. Most of the implementations done using the publisher-subscriber are oriented to handle asynchronous and low-priority tasks in a non-blocking manner to synchronous and high-priority tasks and it also helps to load balance resource-constrained environments.

With this introduction, we are coming to the topic of interest today, the recently unveiled Asgardeo to Choreo event publishing feature, which enables you to publish the important events in your Asgardeo organization to your Choreo organization. The feature is built on top of the pub-sub architecture, which we will talk about very soon.

The identity and access management lifecycle produces a vast number of important events such as new user registrations, user logins, user accounts getting locked/unlocked, user group updates, etc. With this feature, we are given the capability to observe such events. These events bear a great business potential, and this event observability provides the means to,

1. Third-party integrations to push notifications, and send messages.
2. Statistics collection, based on event payloads.
3. Business insights and analytics based on statistics collected.
4. Perform administrative actions, such as helping users unlock accounts.

The possibilities to use these events to create meaningful value additions are endless. and they could be seen as wasted business opportunities if we don’t transform them into business opportunities, thereby turning them into good value additions to your Asgardeo subscription.

Let’s dive into the mechanics of this event publishing process.

How It’s Happening!

Asgardeo Eventing Architecture

Intro to keywords : Asgardeo is an Identity as a Service platform(IdaaS). Ballerina is a cloud-native open-source programming language. Choreo is an Integration Platform as a Service(IPaaS) offering, and the sole integration platform supported by Asgardeo. All these are three products of WSO2.

The different events originating during the identity and access management operations happening on the Asgardeo side are published to a hub, making your Asgardeo organization the publisher.

The hub is a message broker implemented in Ballerina.

The events of the Asgardeo tenant are received and only received by the Choreo organization bearing the same name. This makes your Choreo organization the subscriber.

Let’s now dive into one possible use case of this feature, Sending a welcome mail to a user who just signed up in your organization.

Step 1 : Enable Sending Events

The first step is to configure your Asgardeo tenant to send the events, which is a matter of ticking some checkboxes.

Sign in to your Asgardeo tenant, and in the click on the Develop tab. In the side panel, you will see the Event Publishing section. Click on it and you will see the event configuration Section. Click on Configure button.

You can see the different types of events you can capture from the Asgardeo side under three categories.

Now Let’s select the event that we want to publish. We want to send a welcome email when a user is onboarded. So instinctively, it should be a registration event. Why there’s three types though? hmmm!

Well, users can be onboarded to your Asgardeo tenants in multiple ways.

• Self Signup where user onboards him/herself (Confirm self-signup event)
• Admin adds the user through Asgardeo console. (Add user event)
• User accepts invite and proceeds to set password (Accept user invite event)

Since we are going to send a welcome email to any new user and the way he got signed up doesn’t matter, let’s tick on all of the user registration events. Finally, click on the Update button.

Event configuration UI

We are all set from the Asgardeo side!

Let’s navigate to your Choreo organization. On the events configuration page, you can see the Go to Choreo button, upon clicking it will land you right in the Choreo org.( Even if you don’t have a Choreo organization yet, it will create a one on the fly if you click it.How awesome right???)

Go to Choreo button

Step 2 : Enable Receiving Events

Now it’s the time to do what’s necessary in Choreo to receive and utilize those events.

After you clicked on the Go to Choreo button, now you are in the Choreo home page. Select the project you like to work with (If you don’t have hard feelings, just select the default one). You are now prompted with a bunch of component types that you could try in Choreo. Let’s click on the Webhook tile > Create.

Component type selection

On the next page, give a name to the webhook, give a description and keep the Access Mode as External, because the API is going to be calling the WebSub hub, which is an external entity. Click Next.

Webhook basic info

Next you are prompted with the Authorization part shown in the next image. Click on Authorize with GitHub and in the redirected prompt, Do the account selection, two factor authentication etc.

GitHub authorization prompt

Once it’s completed, you are prompted with the screen below. Select your GitHub account.

The Choreo webhook requires you to provide a GitHub repository to store the source code. As mentioned earlier, we have to define a logic inside the webhook to read and utilize the events we receive. This logic has to be coded in Ballerina. So visit GitHub and create a new repository with a ReadMe file to store the source code.

GitHub repo creation

Now navigate back to Choreo and under the GitHub Repository, select the newly created repo. Select the main as the branch, and since we are fine with source code being in the root, let’s keep the project path empty.

Tick the Start with a sample checkbox, so that Choreo will send a a pull request to your repo with the boiler plate code.

Click Next.

GiHub repo details

Select Asgardeo as the trigger type and click Next.

Webhook type selection UI

Select the RegistrationService as the trigger channel (Alternatively, you can select UserOperationService or LoginService if you want to trigger user operation events or login events. The trigger channel NotificationService is used to receive SMS OTP events. Refer here to configure SMS OTP as a second factor for your Asgardeo applications’ login).

Click onCreate.

Trigger type selection

Upon creation, Choreo sends a pull request to the GitHub repository we created. You can browse to your PR from the Choreo console by clicking on the button below.

Click to Navigate to the PR.

Merge the PR and have a look at the boilerplate code in the webhook.bal. You will see three Ballerina functions, (onAddUser, onConfirmSelfSignup, onAcceptUserInvite) that will handle the three different kinds of user registration events, that this webhook will receive. We can tweak the logic inside these functions to cater to our own requirements.

Follow this *link* and follow up to step 3 to generate a Google credential and enable the Gmail API, so that we can use that credential to send emails using the Gmail API.

Navigate back to our code repository, and replace code in the webhook.bal file with the code below, and commit the changes. (You could also find my repository at: https://github.com/Shaaali/asgardeo-registrations

import ballerinax/trigger.asgardeo;
import ballerina/log;
import ballerina/http;
import ballerinax/googleapis.gmail;
import ballerina/regex;

configurable asgardeo:ListenerConfig config = ?;

configurable string googleClientId = ?;
configurable string googleClientSecret = ?;
configurable string googleRefreshToken = ?;
configurable string senderEmail = ?;

listener http:Listener httpListener = new(8090);
listener asgardeo:Listener webhookListener =  new(config,httpListener);

service asgardeo:RegistrationService on webhookListener {

    remote function onAddUser(asgardeo:AddUserEvent event ) returns error? {
      log:printInfo(event.toJsonString());

      asgardeo:GenericUserData? userData = event.eventData;
      string? userName = userData?.userName;

      error? err = sendMail(<string> userName);
      if (err is error) {
          log:printInfo(err.message());
      }
     return;
    }

    remote function onConfirmSelfSignup(asgardeo:GenericEvent event ) returns error? {

        log:printInfo(event.toJsonString());

        asgardeo:GenericUserData? userData = event.eventData;
        string? userName = userData?.userName;

        error? err = sendMail(<string> userName);
        if (err is error) {
            log:printInfo(err.message());
        }
        return;
    }

    remote function onAcceptUserInvite(asgardeo:GenericEvent event ) returns error? {

        log:printInfo(event.toJsonString());

        asgardeo:GenericUserData? userData = event.eventData;
        string? userName = userData?.userName;

        error? err = sendMail(<string> userName);
        if (err is error) {
            log:printInfo(err.message());
        }
        return; 
    }
}

service /ignore on httpListener {}

function sendMail(string recipientEmail) returns error? {

    string rawEmailTemplate= "<!DOCTYPE html><html><head></head><body><div style='background-image: url(https://images.ctfassets.net/pdf29us7flmy/52UASbQFmBwaZYJBEHHKfs/30a5818482dabfe06ca83166a4ce6014/B8044-Tips-for-Using-Outlook-Email-Social.png);background-size: 1000px 400px;background-repeat: no-repeat;padding: 20px;'><h1 style='color:purple'>Welcome to John Doe Holdings Pvt Ltd!</h1><div>Dear <span style='color:blue;font-weight:bold'>NewUser</span>,<br><br>Thank you for signing up with <b>John Doe Holdings Pvt Ltd!</b> We're thrilled to have you join us and are looking forward to your contributions to our organization.</div><div><br/>Best regards,<br/>Manager,<br/>John Doe Holdings Pvt Ltd</div></div></body></html>";

    string emailTemplate = regex:replaceAll(rawEmailTemplate, "NewUser", recipientEmail);

    gmail:ConnectionConfig gmailConfig = {
        auth: {
            refreshUrl: gmail:REFRESH_URL,
            refreshToken: googleRefreshToken,
            clientId: googleClientId,
            clientSecret: googleClientSecret
        }
    };

    gmail:Client gmailClient = check trap new (gmailConfig);
    string userId = "me";
    gmail:MessageRequest messageRequest = {
        recipient: recipientEmail,
        subject: "Your Dream Home with John Doe Holdings",
        messageBody:  emailTemplate,
        contentType: gmail:TEXT_HTML,
        sender: "Asgardeo E2E Test <senderEmail>"
    };
    gmail:Message m = check gmailClient->sendMessage(messageRequest, userId = userId);
    log:printInfo(m.toJsonString());
}

See how I have defined several variables at top of the code as configurable strings. This means I can pass these values later during the webhook deployment, which we will see later how to do. I need to send the welcome email to the email of new user, So I’m taking the new user’s email address from the event payload through the following code block.

asgardeo:GenericUserData? userData = event.eventData;
string? userName = userData?.userName;

I have passed this email as a parameter to the function sendMail to send a Gmail using the Gmail API. Inside the function, we are using the Ballerina gmail client.

The next step is to deploy the webhook. Navigate back to the Choreo console, and click on the deploy section. You will see a button configure and deploy, click it. You are now prompted with a panel in the right, and it’s asking for a set of configuration values. Observe these are the variable that we marked as configurable in the code before. You need to input the Google client id, client secret and the Gmail address that you are going to send the emails from (The same email that you used to create the Google project and a pair of credentials).

Input these values and click on Deploy button in the bottom of the panel. Wait until every step of the deployment is complete.

Configure and deploy UI

After all the deployment steps are completed as in the UI above, click on the Observe button. the left of Choreo console UI, and click Logs. You will see the webhook logs, and most importantly, you will see the following log.

Successfully subscribed log

This log present means, everything is up and running from Asgardeo and Choreo ends. Nice!!!.

Small prerequisites

Now before going to test the implementation, we need to acquire two small prerequisites, from Asgardeo.

1. Enable self-registration to Asgardeo.
2. Enable My Account

to acquire prerequisites,

1. Navigate to your Asgardeo console > Manage tab > Self Registration .
2. Click on Self Registration > Configure.
3. Click on enable, untick account verification, and click update.
4. On the Manage tab menu, click on Self-Service Portal.
5. Click on My Account > Configure.
6. Click on Enable.

Hooray!!!, we are done with the system configuration and logic implementation. Let’s proceed to test.

Step 3 : Let’s Test!

In order to test, we need to sign up as a new user in your Asgardeo tenant.

Navigate to the My Account page of your Asgardeo tenant from an incognito window in your browser through :

https://myaccount.asgardeo.io/t/<your_organization_name>

My account is a self-service portal that enables users to create and manage their user profiles. Upon landing on the site, you will see the option to create a new account.

Click on Create Account and proceed to the signup page. Input your email address and other mandatory details. click on sign up.

You will land on a page which tells you the account creation has been successful.

Now Let’s navigate to the email inbox of the email you used to sign up. You will find the following nice welcome email, which shows our effort has been successful.

Summary

We were able to successfully implement a very straightforward use case of the Asgardeo event publishing feature. It goes without saying, that you can come up with very complex integrations using this feature, that would help your business go the extra mile.

Until next time, Happy coding and happy integrations!!!

P.S. : Since Asgardeo and Choreo are still new in town, the UIs are being continuously improved and might be a little bit different to the images in this blog when visit the sites, But still you will be able to get the sence of it. Feel free to post any questions in the comment section.