article by Frank Nimphius, December 2019
Messengers differ in the layout they support. The Oracle Digital Assistant connector architecture renders the best possible bot response for a connected client based on its internal metadata (CMM). With the connector architecture, a skill that renders a rich card layout on Facebook would render a list of text messages on SMS without the user needing to code for it. Still, a messenger platform like Microsoft Teams, Facebook or Slack may provide functionality that is not created by the connector architecture.
The System.CommonResponse component has a property called "channelCustomProperties" that you can use to implement channel specific layout properties. This way you can optimize the Oracle Digital Assistant generated bot response for specific channels.
This article explains the channelCustomProperties property by example of adaptive cards in the Microsoft Teams channel. Adaptive cards are available in Oracle Digital Assistant 19.12 and later.
Oracle Digital Assistant Connector Architecture
Oracle Digital Assistant uses an internal metadata structure called conversation message model (CMM) to deal with incoming and outgoing message payloads. For all channels that are natively supported in Oracle Digital Assistant, a connector exists that transforms the CMM payload to a format understood by the connected messaging client and the payload of the message client to the CMM format. With this architecture, Oracle Digital Assistant is able to serve multiple messaging platforms with a single skill or digital assistant.
System.CommonResponse component
The System.CommonResponse component is very powerful and allows the bot developer to create all sorts of user interfaces of varying complexity. The component, in its properties and structure, aligns well to the CMM metadata model. One of its properties, the channelCustomProperties property, supports a documented set of channel specific extensions that you, as a skill developer, can use to optimize the bot response for a specific channel: https://docs.cloud.oracle.com/iaas/Content/digital-assistant/channels-part-topic.html
Microsoft Teams Example
In this article I am exploring a visually attractive UI extension that exists for the Microsoft Teams channel. Microsoft supports the concept of adaptive cards on their platform and also in Microsoft Teams messenger. Adaptive cards is the ability for developers to customize the layout of cards to their needs. All of this is based on JSON. See: https://adaptivecards.io/ and https://adaptivecards.io/designer/
Though Oracle Digital Assistant skill does not support JSON as in its configuration, you can use the channelCustomProperties property with YAML on the System.CommonResponse component to implement adaptive cards. See https://www.json2yaml.com/
You can find more details about limitations and features of the Microsoft Team platform in the Oracle Digital Assistant product documentation: https://docs.cloud.oracle.com/iaas/Content/digital-assistant/microsoft-teams.html#GUID-7E688AA4-6C63-4F1E-99CB-06773BD0A878
The image below shows the sample skill provided with this article rendering a card layout in Microsoft Teams. The layout of the card is rendered by the MS teams connector in Oracle Digital Assistant. So without applying any change, your bot will work in Microsoft teams.
The image below uses an adaptive card definition in the System.CommonResponse component's channelCustomProperties property. Notice the change to the vertical layout as well as the change in the position of the image on the card.
The BotML Code for this layout is shown in the image below. Note that to create the layout I used the Adaptive Card designer (https://adaptivecards.io/designer/) and converted the card's JSON definition to YAML using the following link: https://www.json2yaml.com/. As you can see in line 185, the content gets only applied if the channel is msteams. This way you can add customizations for different channels without messing up.
The structure starting with the body: element in line 190 got created by the JSON to YAML converter referenced above. All I needed to do is to add the Apache FreeMarker expression to reference the the System.CommonResponse component iterator variable for the data to inject.
Another example provided in the sample skill is a single card that renders the pasta order confirmation. Before using the card, the confirmation was create as a text response and an image attachment using the System.CommonResponse component.
To use a single adaptive card for the confirmation, I added an extra response item to the System.CommonResponse component and used the visible property to show it for msteams but hide it for all other channels. Similar, the text response and attachment was configured to only show for non-msteams channels
The BotML code below shows the configuration for the card shown above. Notice line 313, which uses an expression to hide the text response with the confirmation message if the channel type is detected as msteams. This message is displayed for all other channels.
Same in line 331, which renders the image attachment. This too is hidden for the MS teams channel but displayed for other channels using an expression. Lastly, line 335 defines a text response that is shown if the channel is msteams. This response item contains the adaptive card definition in line 341 and following. To see the full BotML code, I encourage you to download the test case and to import it to your Oracle Digital Assistant instance. Alternatively, you can unzip the downloaded file to look at the dialog flow definition.
It doesn't stop with Microsoft Teams
The Microsoft team channel and adaptive card layout are just the example used in this article. The Oracle Digital Assistant documentation for channels also lists properties for other channels that can be used with the System.CommonResponse component "channelCustomProperties" property.
You'll also learn about limitations of the different channels that Oracle Digital Assistant has no control over. Knowing about these limitations allows you to design bots that work best for any messenger your bot needs to support. Note that the System.CommonResponse component channelCustomProperties property is just one tool in your toolbox for creating adaptive bot responses. More about this in a later article.
https://docs.cloud.oracle.com/iaas/Content/digital-assistant/channels-part-topic.html
Download Sample Skill
Pasta Skill with MS Teams Extension
Related Content
TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube
TechExchange Quick-Tip: Using RAW Message Payloads in Custom Components to Leverage Channel Specific UI Extensions (MS TEAMS Example)
TechExchange Quick-Tip: Optimize Bot Responses for a specific Channel in Oracle Digital Assistant
TechExchange Quick-Tip: Printing Multi-Line Text Messages from an Output component
