Break New Ground

A Simple Guide to Oracle Intelligent Bots Error Handling

Frank Nimphius
Master Principal Product Manager

Like any software development, building chatbots is rarely perfect first time.  In particular areas such as the conversation flow or backend system integration, which are programmed, are more likely to be subject to bugs and errors. The assumption is that where there is room for failure, there is a way to handle those failures ;and in fact, there is. This blog post explains how to handle errors in Oracle Intelligent Bots. 

Categories of Errors

There are three broad categories of errors that may occur in the context of a bot.

The first category are design time errors in the dialog definition, for example, a missing colon or invalid indents.  The good news is that the Intelligent Bots designer validates the dialog definition at design time and highlights which line it thinks is in error.

Second problem relates to system components at runtime.  Component properties can have their value assigned at runtime, for which bot designers would use an expression such as ${myKeepTurnVar.value} that references a context variable defined in the dialog flow. If a component property attempts to read the variable value before it gets set then this also produces a failure on the component level.

The third category is a problem within a custom component, for example a failed connection to a backend service or a failed input validation. Possibly the backend system is returning an HTTP 404 because it can’t find the requested data, or maybe there is an HTTP 5xx error because the backend system is down. Given the nature of these problems they don't show at design time but only at runtime.

Layers of Error Handling

So now that you know about the categories of errors bot designers and developers usually deal with, let’s have a look how these can be handled.

  • Implicit error handling is what Oracle Intelligent Bots does when there is no error handler defined at all, which is the default. You wouldn’t want to put any bot into production that only has this level of error handling.
  • Component level error handling allows conversation flow designers to catch errors as close as possible to their cause.
  • Global error handling is defined on the chatbot level. All errors that are not handled on the component level will be passed to this error handler.

Component Level Error Handling

To handle errors, each component can have an error transition property set. The error transition references a state in the same dialog flow that the dialog engine navigates to in case of an error.

So first thing you learn is that an error transition in Oracle Intelligent Bots donesn't handle errors itself but triggers navigation.

The Oracle BotML example below shows a definition of a System.Out component with a missing value for the "keepTurn" property. The state has an error transition defined that points to a state with the name "handleError".


  component: "System.Output"


      text: "Welcome ${profile.firstName} ${profile.lastName}"



      next: "showOptions"

      error: "handleError"


Note: The keep turn property must have a value defined. The code above is not valid and thus will fail at runtime. As the time of writing, design time validation does not catch a missing keepTurn property.

The BotML below shows how the "handleError" state may look like:


   component: "System.Output"


     text: "This is a problem caught by the component. The error
            state is the \"${system.errorState}\" state"


      return: "done"

In this example, the error handler simply displays a message containing the errorState, which is the name of the dialog state in which the error occurred. If you wanted to componentize the error handler you could build a specific custom component and the error handler state could reference this custom component which would be a more elegant solution


   component: "my.errorhandler"


     errorState: "${system.errorState}"

     user: "${profile.firstName} {profile.lastName}"

     isDebug: "true"


     next: "start"


Custom components can be used within any state in a dialog flow. In the example above the custom component has input properties defined for the error state, the user and a flag to indicate whether this component is used in development or in production. The latter could be used to determine the message to be printed to the user.

What makes a custom component special, as an error handler is that it can log the problem, try to recover or – in serious cases –perform incident reporting so an administrator becomes aware of a runtime problem.

The custom component could also dynamically determine the next state to visit by updating a context variable that is configured as the value for the "next" element in the "transitions" section.

For example


   component: "my.errorhandler"


     errorState: "${system.errorState}"

     user: "${profile.firstName} {profile.lastName}"

     isDebug: "true"


     next: "${variableName.value}"

Global Error Handling

So defining error handling at the component level is our first strategy.  The second line of defence is a global error handler. There is a good reason for defining a bot wide global error handler, which is to avoid the implicit error handler. The global error handler is defined using an "error" element in the bot header definition as shown below.


  platformVersion: 1.0

main: true

name: TheBotName



    iResult: "nlpresult"

error: "handleGlobalError"




Because this error handler is defined on the bot level, it behaves exactly as the component level error handler in that it triggers navigation to a state defined as the error handler, "handleGlobalError" in this example.

So all that I wrote in the previous section about the component level error handler can be used here as well. However, special caution should be put on using custom components to handle global errors as the global error setting replaces the implicit handler. An error in the custom component could then lead to an infinitive loop.

Implicit Error Handler

This error handler is used if nothing else has been defined. The error message displayed by this error handler is

Oops I'm encountering a spot of trouble. Please try again later...

Hope you agree that this should not be a message to display to a user in a production bot. However, it is important that a generic implicit error hander like this exists because bot design usually starts with the use case at hand and not custom error handling. 

Learn more

To learn more about Oracle Intelligent Bots and Chatbots, visit http://oracle.com/bots


Feature image courtesy of Sira Anamwong at FreeDigitalPhotos.net

Join the discussion

Comments ( 1 )
  • AK Wednesday, November 8, 2017
    Really nice write-up Frank!
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.