article by Frank Nimphius, October 2019
requires Oracle Digital Assistant 19.4.1 and later
System intents exist in Oracle Digital Assistant for "help", "exit" and the "unresolvedIntent". The "help" System Intent, when resolved in Oracle Digital Assistant, generates a UI that consists of cards with the contained skills' invocation names and sample utterances.
The image below shows the card for a Pasta Maker skill contained in a digital assistant. The invocation name "Pasta Maker" is shown as the title of the skill. A brief description and example utterances are provided to explain to the user how she could call the skill. A similar card is displayed in a carousel for all other skills in a digital assistant.
The image below (screenshot of the embedded conversation tester in Oracle Digital assistant) shows a customized System.help in Oracle Digital Assistant 19.4.1 (you need Oracle Digital Assistant 19.4.1 or later) built using a custom skill.
The custom skill driven System.help intent menu, as shown in the image, allows you to create a richer user interface for the menu and also allows you to change the display from e.g. horizontal cards to vertical cards. As some messengers are more restrictive than others, you can even use a custom help menu to e.g. implement pagination, allowing your digital assistant to show help for more skills than what otherwise would fit on the number of allowed cards for a messenger.
The example help used in the screen shots (you can download the sources at the end of this article) uses a System.CommonResponse component to render the UI. The System.CommonResponse component allows the custom help skill to navigate to a specific skill when the user presses a button. It also shows a single card per skill that is lead by a longer introductory text.
Building the Custom Help Skill
To build the custom help skill, you change to the skill dashboard and create a new skill.
For this article, the custom help skill is FN_CUSTOM_HELP. To use the skill as a custom help skill, it needs to be published.
Optional, though good design practice, you can use custom skill parameters to pass information, like skill invocation names, to the menu skill. For the menu to navigate to other skills, it is best to use skill invocation names to perform explicit routing. So anything that might change for a digital assistant configuration (like invocation names) should be passed as custom skill parameters to the help skill. Don't underestimate the powers of custom skill parameters.
Note: You can decide to provide the invocation name as a static value in the custom help skill BotML, or, as in the sample you can download, pass the invocation names in skill parameters.
As a reminder: Custom skill parameters that have a name prefix of "da:" will show in the digital assistant configuration (see "TechExchange Quick-Tip: How to remote-control skill bots in Oracle Digital Assistant through parameterization").
The help state in the dialog flow below uses the System.CommonResponse component to render the bot user interface. The System.CommonResponse component can be configured with a specific action (system.textReceived) that allows you to send messages to Oracle Digital Assistant for routing to one of the configured skills and intents (see: TechExchange Quick-Tip: How-to Call a Skill from another Skill And How to Avoid Dependencies).
The following BotML code defines the custom menu action items for the Pasta Order skill. As you can see in the payload element, the action element calls an action named "system.textReceived" and passes the string "I want to order pasta" along with the pasta skill's invocation name. The expression ${system.config.da.pastaSkill} refers to the custom skill parameter used to retrieve the name of the pasta skill invocation name. Using messages that contain the invocation name of the skill ensures explicit navigation. This means that the request is forwarded directly to this skill and not to any other skill, even if the message has a matching intent.
Note: The da.pastaSkill skill parameter is also referenced in the card title and the help text preceding the card. Its an implementation detail of the provided sample skill, but I hope that this makes sense to you and you use a similar technique in your implementations.
Important: After you built the skill and your are happy with it, ensure you train the model (only needed if the skill contains intents or entity bag entities) and then publish it. Note that only published skills can be added to a digital assistant.
Adding the Help Skill to Digital Assistant
To change the default help implementation with your custom skill, you first need to add the custom help skill to the digital assistant (see image below).
Next you select the Settings panel and switch to the Configurations tab. Set the Digital Assistant Custom Help Skill field to the name of your custom help skill (FN_CUSTOM_HELP in this sample). In addition, set the name of the dialog flow state that renders the menu UI as the value of the Digital Assistant Custom Help field.
If you have followed the advice to use custom skill parameters to pass the skill invocation names, then you configure the invocation names in the configuration section shown in the image below. If the invocation name was set as the default value of a skill parameter, and if it hasn't been changed, then the value is automatically set.
Finally, train the digital assistant model and test in in the conversation tester.
If needed, you can fine tune the help utterances by adding examples to the help system intent.
Recommendation
Unless you want the help skill to also be considered in Oracle Digital Assistant routing, it is recommended to create the custom help skill without own intents and utterances. Help-skills that have their own intents and utterances "compete" with other configured skills in digital assistant to process incoming user messages. This may lead to messages being routed to the help skill instead of a business skills.
Be aware of digital assistant skill routing
The custom help skill is added as a skill to Oracle Digital Assistant, which also means that routing from the help to another skill is considered a sub flow. As such, smart dialog messages are displayed asking the user whether she wants to navigate from the help skill to the target skill. You can suppress these messages in the configuration panel of a digital assistant.
You need to change values in the Routing Parameters and Conversation Parameters section. The routing section should have thresholds set to a reasonable value. E.g. 0.7 for explicit routing. In the conversation parameters section, look e.g. for "Interrupt Prompt Confidence Threshold" (which for the sample I set to 0.4). Have a look at the sample for more settings.
Download the Sample
To use the sample digital assistant shown in the screen shots
- Download the sample
- Import as a new digital assistant (use ZIP as is)
- Train the sample
- Start the embedded conversation tester and type : help
DOWNLOAD (ZIP)
Related Content
TechExchange: Oracle Digital Assistant Primer
TechExchange Quick-Tip: How-to Call a Skill from another Skill And How to Avoid Dependencies
TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube
