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.
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)
}
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.)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)
}
A validate
block cannot replace or drop inputs, but the halt
, prompt
, replan
, and unlock
effects are available.
The following video tutorial shows how to validate inputs with the Input Validation and Error Handling sample capsule.
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
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 change 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 and which versions the flag is set to true
as a default.
| Flag | Description | Default In Versions |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ---- |
| allow-dialogs-on-detail-pages
| Allows capsules to show dialog when they progress from a summary view to a detail view. | None |
| allow-empty-fragments-in-dialog-templates
| Allows capsules to use dialog fragments/macros that evaluate to empty strings in dialog templates. | Version 8 or later |
| allow-wildcard-matches-on-imported-resources
| Controls the scope of wildcard matches defined in an imported library capsule. | None |
| auto-insert-navigation-conversation-drivers
| Automatically adds "Previous" and "Next" conversation drivers to lists in Bixby Views. | Version 5 or later |
| auto-on-click-for-list-of
| Enables auto-selection behavior for list-of
. | Version 1-6 |
| avoid-page-selection-command-due-to-ambiguity
| Prefer next page navigation command to page selection command in case of ambiguity in a user utterance. | None |
| concepts-inherit-super-type-features
| Enables concepts to inherit features
(such as transient
or preferable
) when extending or being a role-of their parent type (also known as super-type). | Version 2 or later |
| disable-voice-content-selection
| Enables or disables voice content selection in views. | None |
| enhanced-list-navigation
| Change default list navigation behavior. | None | None |
| modern-default-view-behavior
| Changes behavior when a result view or input view is not defined. | Version 1 or later |
| modern-prompt-rejection
| Changes the behavior of how input prompt responses are handled. | Version 2 or later |
| no-auto-property-value-merging
| Ensures that equivalent values of a property within a node will not be merged. | Version 4 or later |
| no-default-init-when-input-already-instantiated
| Changes the behavior of default-init
. | Version 9 or later |
| no-fallback-dialog-in-views
| Prevent falling back to a default dialog if no message is defined in a view. | Version 6 or later |
| no-fallback-to-result-collections
| Renders nothing if no result view is specified. | None |
| no-filtering-with-validation
| Changes how Bixby applies validation conditions to reduce the number of ambiguous values. | Version 1 or later |
| relax-inputs-on-confirmation-denial
| Change how to handle cases when the user denies a confirmation prompt. | None |
| result-view-capsule-lock
| Enables automatic opt-in for capsule lock within result views with conversation drivers | Version 1 or later |
| short-timeout-on-halt-dialog
| Changes the conversation timeout length after a halt
effect. | Version 1 or later |
| show-ordinals-on-list
| Controls whether to display item numbers in lists in result and input views. | None | None |
| support-halt-effect-in-computed-inputs
| Enables halting execution while doing a computed-input
. | Version 2 or later |
| use-authorization-header-for-remote-endpoint-oauth
| Uses an Authorization
header when an HTTP request to a remote-endpoint
requires OAuth. | Version 3 or later |
| use-input-views-for-selection-list-detail
| Changes how a single result is rendered within an input-view
. | Version 2 or later |
| use-most-specific-instantiation-strategy
| Uses the MostSpecific
match mode for an instantiation strategy in the default-init
of an action. | Version 4 or later |
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)
}
}
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.