Bixby Developer Center

Suppose your capsule performs a search action on behalf of the user, such as finding a restaurant with specific criteria, and the action returns no results. While you can have Bixby report the lack of results to the user, you might want to relax the search constraints and try again. You might increase the search radius for restaurants, or drop the requirement for a price range. Relaxing includes modifying or dropping an input, or even prompting the user for more or different information. You might also want to perform similar operations in the case of an error or during input validation. These operations, which modify the plan and change its execution, are effects.

Make sure that you read and follow Bixby's Design Guidelines as you develop your capsule.

Handling Empty Output

When an action's output is empty, such as a search action that returns no results, you can use an on-empty block to apply effects that can change the plan's execution.

For example, in the Basic Cart Transactional Sample Capsule, the SelectItem action has an on-empty block that drops the search term and prompts for a new selection when no results are found:

    }
    on-empty {
      //prompt for items, clear searchTerm
      ordered-effects {
        drop (searchTerm)
        prompt (items) {
          required-value (true)
          single-value (true)
          candidates (items)
        }

View 0690617 on GitHub

This block uses ordered-effects to group drop and prompt together.

You can use the following child keys in an on-empty block:

• drop: Drop the specified input from an action.
• halt: Halt execution completely, displaying an error message.
• prompt: Prompt the user for a new input value.
• replace: Replace an existing input value with a new one.
• replan: Restart the planner, using a new intent.
• unlock: Pause execution if the device is locked and inform users they need to unlock it to continue.
• flag-as-off-topic: Flag the current utterance as off-topic. (See the Prompting the User section in the Guiding Conversations Developers' Guide for details.)

Validating Input

Validation rules for inputs are defined in a validate block. These rules consist of conditionals and an effect to be applied if the condition is met. For example, Bixby might need to prompt for more information or prompt the user to unlock their device. An airport search might check to make sure that at least one of the possible search fields is available and prompt the user if none of them are.

In this example from the Error Handling sample capsule, this validate block runs several tests on an input named integer, taking one of several demonstration actions based on the input's value.

action (ValidateInputs) {
  type (Search)
  description (Show how to use validate.)
  collect {
    input (integer) {
      type (Integer)
      max (One)
      min (Required)
      validate {
        if (integer == 101) {
          halt {
            dialog ("Halting because you entered 101.")
          }
        }
        if (integer == 42) {
          replan {
            dialog ("Using replan to change integer to 0, because you entered 42.")
            intent {
              goal: Integer
              value: Integer (0)
            }
          }
        }
        if (integer > 9) {
          prompt {
            dialog ("Please provide an integer smaller than 10.")
          }
        }
      }
    }
  }
  output (Result)
}

View master on GitHub

A validate block cannot replace or drop inputs, but the halt, prompt, replan, and unlock effects are available.

Video Tutorial: Validating Input

Catching Errors

Effects can also be used for handling errors. If your JavaScript action implementation throws an error, it can be caught by a throws block in your action model, with the effects to execute in an on-catch block.

output (Receipt) {
  ...
  throws {
    error (PaymentUnaccepted) {

      property (vendorName) {
        type (Name)
        min (Required) max (One)
      }
      property (paymentType) {
        type (payment.PaymentType)
        min (Required) max (One)
      }
      on-catch {
        halt {
          dialog {
            template ("#{value(vendorName)} does not accept #{value (paymentType)}")
          }
          display (order)
        }
      }
    }
  }
}

In the example below, a capsule checks to see if there is no data available and throws a NoData checked error.

//if response is bad, throw NoData error
if (!response || response.failure || !response.globalairquality)
  throw fail.checkedError('no air quality data', 'NoData')

The output of the GetAirQuality action in that capsule catches this error and uses a noDataAirQuality dialog macro to provide a useful error using on-catch and halt:

action (GetAirQuality) {
  description (Get the air quality for a location)
  type (Search)

...

  output (AirQuality) {
    throws {
      error (NoData) {
        on-catch {
          halt {
            dialog {
              macro(noDataAirQuality)
            }
          }
        }
      }
    }
  }
}

The actual definition of the macro (macro-def) looks like this:

macro-def(noDataAirQuality){
  content: template ("No air quality data available.")
}

All the effects available in an on-empty block are available in on-catch: drop, halt, prompt, replace, replan, unlock, and flag-as-off-topic.

Runtime Versions and Runtime Flags

Runtime versions changes the behavior of your capsule during runtime execution. Each runtime version has a specific set of runtime flags. Runtime flags enable you to change specific runtime behavior during the execution of the capsule.

If your capsule uses a feature affected by one of the flags, analyze how it changes your capsule's behavior and adjust accordingly with the overrides key in runtime-versions. Each flag adjusts the behavior of different features. See the flag's reference page for more information. The table below lists the flag with a link to its reference page, as well as a short description of the flag.

Grouping Multiple Effects

By default, Bixby only executes the first qualifying effect in a block. If you need to run multiple effects, you can wrap them in an ordered-effects block.

    on-empty {
      //prompt for items, clear searchTerm
      ordered-effects {
        drop (searchTerm)
        prompt (items) {
          required-value (true)
          single-value (true)
          candidates (items)
        }
      }

View 0690617 on GitHub

The effects will be executed sequentially, in the order declared. The ordered-effects block itself can only contain other effect keys: drop, halt, prompt, replace, replan, unlock, and flag-as-off-topic. You cannot use conditionals in an ordered-effects block, nor nest ordered-effects.

You can put ordered-effects blocks within on-empty and on-catch blocks, but not validate blocks.