Implementing Event Notifications in ODA with Visual Flow Designer for various channels like MS-Teams, Slack, Twilio, Fusion Applications and others

Executive Summary

Oracle Digital Assistant (ODA) is usually seen as a conversation tool where users initiate the dialog. However, ODA can also be used to provide notifications to a user based on any event of interest. ODA can listen to events from external applications and send notifications accordingly to the targeted users. The messages would pop up when the user is in the ODA widget. This feature in ODA to consume external CloudEvents is supported in Visual Flow Designer (VFD) only. As ODA supports user conversations over different channels like MS-Teams, Slack, Twilio and others, the notifications can be sent seamlessly across different channels with channel-specific payloads. External applications need to be configured to send a REST payload to the ODA event channel to initiate the notification flow. This blog attempts to describe the overall setup in ODA to receive event notifications for different conversation channels from external applications.

ODA Event Processing Architecture

ODA can consume external events of CloudEvents^[1] specification via an inbound listening channel. The message after receipt can be processed in the ODA engine and sent out to any of the conversations channels that are supported by ODA platform. The high-level architecture diagram in Fig.1 describes the overall flow.

1. A REST payload is sent from an external application to the ODA event listening channel
2. After receiving the message, the ODA engine process it via the skills and posts the message content to one of the outbound conversation channels.

Fig. 1 ODA Event Processing Architecture

ODA Event Processing Flow

The triggering of an event from an external application creates a CloudEvents compatible message to be sent to the ODA listening channel. The high-level flow is illustrated in Fig. 2 as described in the ODA Documentation^[2].

Fig. 2 ODA Event Processing Flow

ODA Event Processing Implementation

We provide an example of event processing by sending a REST payload message from an external client (Postman) to simulate the triggering of event in an external application. The use case here represents the automatic reminder message sent to the employees of a company when their certification for corporate compliance is about to expire for a certain course and they will have to retake it before a certain date.

The basic key components in building a skill to receive events and send notifications to a Twilio channel has been described in a blog^[3] from the ODA PM team. The entire implementation here extends the same methodology and includes other notification delivery channels as listed below.

1. MS-Teams
2. Slack
3. Test Channel
4. Twilio
5. Fusion Applications
6. Custom Web Portal

The configuration is based on building a custom DA with a custom skill using Visual Flow Designer (VFD) and the basic flow for all the notification channels is the same as shown in Fig. 3. The only part which varies from one channel to another is the composition of the payload that is sent as part of the REST call from the external application. The next section discusses the payload structure and the significance of different fields in the payload as they apply to different channels.

Fig. 3 ODA Event Processing Implementation

Setup

A sample JSON payload used for the REST invoke from the external application is shown below.

{
  "specversion": "1.0",
  "type": "compliance.status",
    "source": "externalCurl",
    "id": "notify.user",
  "time": "<timestamp of event trigger, e.g. 2024-05-01T21:19:24Z>",
    "contenttype": "application/json",
    "userid": "+<countrycode><Twilio_telephone_number, e.g. +19885551212>",
  "channelname": "<Twilio_channel_name>, e.g. SL_Twilio",
    "version": "2.0",
    "data": {
        "expirydate": "07-JUN-2024",
        "coursename": "Annual Employee Compliance",
        "courselink": "https://companylearning.com/course"
    }
}

Table 1 below provides an explanation of each key field in the JSON payload and the significance of how it ties to the ODA configuration.

Table 1. REST Payload Details

The target URL and the header parameters for the REST call are described in Table 2 below.

Table 2. REST Invoke Details

As we try to setup the ODA configuration for multiple delivery channels, the only two fields in the JSON payload that changes are listed below.

• channelname
• userid

The value of channelname is the name of the channel configured in ODA console. The userid can be derived from the runtime value of the field ${system.message.userid}, which sometimes can be determined beforehand when they are constant for all user sessions. Fig. 4 below summarizes all the mapping correlations for the REST invoke.

Fig. 4 REST Call Mappings

Table 5 below highlights the nuances and specialties for the values of userid for various channels. This information could be useful for the Fusion Applications and few other channels, where the userid is dynamically set at runtime.

Table 3. userid for various channels

Results

The entire setup was tested by sending the POST invoke from an external REST client like Postman and observing the messages that pop-up in the ODA user sessions for various channels. The notification message text was formatted by using the variable values sent in the data block of the JSON payload.

A curl command equivalent of the REST call sent from Postman is shown below. After a successful send of the command, an HTTP code of 202 is returned. 

curl --location 'https://<…data.digitalassistant.oci.oraclecloud.com/events/v2/listeners/appevent/channels/592..>' \
--header 'Content-Type: application/cloudevents+json' \
--header 'X-Hub-Signature: sha256=<31ffeee….>' \
--data '{
    "specversion": "1.0",
    "type": "compliance.status",
     "source": "externalCurl",
     "id": "notify.user",
     "time": "2024-05-01T21:19:24Z",
     "contenttype": "application/json",
     "userid": "+18882221313",
     "channelname": "SL_Twilio",
     "version": "2.0",
     "data": {
        "expirydate": "07-JUN-2024",
        "coursename": "Annual Employee Compliance",
        "courselink": "https://companylearning.com/course"
        }
   }'

Sample notification messages that appear in the ODA windows for Fusion Applications, Slack and MS-Teams channels are shown below in Fig. 5.

Fig. 5 Event Notification in ODA for Fusion Appplications, Slack and MS-Teams channels

Similar messages also appear in Twilio and Test channels as shown in Fig. 6.

Fig. 6 Event Notification in ODA for Twilio and Test channels

Acknowledgements

I would like to acknowledge the assistance I received from my teammate, Greg Mally in building the sample test cases for this blog. I would also like to thank Jobinesh Puroshothaman from ODA Engineering Team and Daniel Teixeira from ODA Product Management Team for their help at different times.

References

1. CloudEvents Spec – GitHub for CloudEvents Information
2. External Events in ODA - ODA Product Documentation
3. The new Events channel enables a bot-initiated conversation! – Daniel Teixera, Oracle Blog from ODA Product Management