Effects
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.
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)
}
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.)
Input Validation
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.
Video Tutorial: Validating Input in Bixby
The following video tutorial shows how to validate inputs with the Input Validation and Error Handling sample capsule.
Error Handling
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 and Runtime Flags
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 |
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)
}
}
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.