by Frank Nimphius, March 2018

Update: Oracle Intelligent Bots has been rebranded Oracle Digital Assistant to better describe its capabilities beyond a standard chatbot. To learn more, visit cloud.oracle.com/digital-assistant

About the maxPrompts property

The maxPrompts property is exposed on Oracle Intelligent Bots built-in input components like System.Text, System.List and System.CommonResponse. It takes a numeric value indicating the maximum number of attempts allowed for a user to provide valid data input. If the allowed number of attempts is exceeded by a user, then the dialog engine performs navigation to a pre-configured "cancel" state that helps the user out. So in summary, what the maxPrompts property is good for is to validate user input and to ensure users are not getting locked-in.

What you should know about the maxPrompts property

The maxPrompts property only works for variables of an entity type. For this you reference a context variable of an entity from the component's variable property. The entity type can be a custom entity or system entity. 

Note: Simulating the maxPrompts behaviour for a primitive type variable is a good topic for a later quick-tip. 

Example

A simple example is one in which a user is asked to enter a value that matches a certain pattern, like the format for car licenses in Germany. German license plates have the following format: <1-3 characters> for the city the car is registered in, followed by a dash and <1-2 alphanumeric characters>,  followed by a blank and <1-4 numeric digits>. The RegularExpression for this is [A-Z]{1,3}-[A-Z]{1,2} [0-9]{1,4}\b

In Oracle Intelligent Bots, you define an entity of type RegularExpression as shown in the image below.

RegularExpression Entity

The next steps then are to

  • define a variable of the entity type (LicensePlate in this example)
  • create a System.Text component that references the variable and that has its maxPrompts property set (set to 2 in the sample)
  • create a success state that prints the license number of valid, and one that helps the user with how a valid car license number looks before redirecting to the text component again

The image below shows the dialog flow definition for this

Dialog flow defining the variable and the text input component

The image above also shows a goodie provided by the dialog flow engine. When a user fails to provide a valid car license number, the system automatically sets a flag to the botsUserError variable. This flag is then used to modify the input component prompts to reflect the situation that the user previously failed providing a valid input. The expression used in the component prompt property is an Apache Freemarker expression. Note that the botsUserError property requires maxPrompts to be set. 

 

!!! IMPORTANT CHANGE !!!: As of 18.2.3 production release the user.botsUserError variable is not named system.invalidUserInput. So please adapt this change when following the content in this article. 

 

At runtime, a user conversation may look as in the image shown below. Notice that after two failed attempts, a help message is displayed before the user is redirected to the input component again. 

Conversation demonstrating maxPrompts in a conversation

Summary

The maxPrompts property on input components can be used for use data input  validation if used in combination with a context variable of an entity type. Using the cancel action on the component, you can navigate to a state in the dialog flow you set up to help the user providing a valid component entry. 

 

Author