Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center

Guides

Capsule Configuration

There are two ways to store configuration information for your capsules, such as endpoint URIs, API keys, permission scopes, environment modes, or any other configuration data that you'd like to be able to change without editing capsule code:

  • The capsule.properties file within your capsule itself.
  • The Config & Secrets tab of your capsule's information page in the Teams & Capsules section of the Bixby Developer Center.
Note

Endpoint URIs can be stored in the Config & Secrets dynamic configuration section, but only if they're going to be accessed directly by a local JavaScript function. Values entered here are not available to the endpoints.bxb file.

Secrets are sensitive information that should not be stored in code and might need to be updated frequently, such as API keys or other authentication details. By entering these in the Secrets section of the Bixby Developer Center, they will be securely encrypted end-to-end, and will even appear obfuscated in the Developer Center's UI. Secrets can be updated at any time.

Static, non-sensitive information that isn't likely to change often should be defined in the capsule.properties file. This could include endpoint URIs, permission scopes, and feature gates.

By setting dynamic properties in the Config section of the Bixby Developer Center, you can change property values without editing capsule code. If you define capsule properties in the Developer Center with the same names as properties in the capsule.properties file, the dynamic values will override the static ones in the file. Delete these dynamic properties to return to the values defined in the file.

Capsule Properties File

Use the capsule.properties file to store configuration properties related to your capsule, such as endpoints, scopes, or whether to use test or production configuration properties. This file is for properties that you don't expect to change very often, if at all. Properties that are likely to change should be handled through the Config & Secrets screen of the Bixby Developer Center. (You can override any property defined in this file by entering a new value for it in the Config screen.)

This file use a simple INI-like format:

key=value
group.key=value
Caution

API keys, passwords, and other sensitive information must be entered and managed through the Secrets section of the Config & Secrets page. They must never be stored in the capsule.properties file!

Configuration Mode

You can set the configuration mode for your capsule using capsule.config.mode.

You can set properties for specific configuration modes, which are helpful when you want to use your capsule in different environments.

capsule.config.mode=default

Capsule Properties

You can set properties for each mode using this format:

config.%mode%.%propertyKey%=%propertyValue%

Use the default mode for any fallback property values:

config.default.my.property.key=myValue 123

Capsule properties are treated as strings, so ensure that you cast them to right type. Do not include empty strings, as they are then surrounded by quotes ("""").

Toggling Properties and Capsules

You can toggle individual capsule properties using this format:

config.default.toppicks=false

You can toggle content from a capsule using this format:

capsule.enabled=false

Config & Secrets

To set configuration properties and secrets dynamically through the web interface:

  1. Select the Capsules tab within Teams & Capsules.

  2. Select the capsule for which you want to edit configuration values or secrets.

    Config & Secrets View

  3. Click the + Add button to add a new key/value pair to either the Configuration section or the Secrets section. This will display fields to enter a new name and value; click Add on the new field to save it.

  4. Click an existing row to edit its name and value.

  5. Click the X to the right of the row that appears on hover to delete it.

You can provide different values for properties and secrets in development and production modes by selecting Dev or Prod.

Note

The configuration mode setting in the Config & Secrets UI screen is independent of the configuration mode setting in the capsule.properties file.

When you make changes, a new set of buttons will appear at the top of the screen.

Config & Secrets View

You can continue to add, update, and delete configuration properties and secrets while these buttons are displayed.

  • Click Save & Apply to save your changes. The new keys will be used by all deployed versions of this capsule.
  • Click Reset to cancel. The changes you've made will be lost.

Property Precedence

When Bixby looks for a property value, it follows this precedence:

  • Properties defined in the Config & Secrets UI Dev mode (as long as the capsule is synced or in revision override)
  • Properties defined in the Config & Secrets UI Prod mode
  • Properties defined in the currently active configuration mode in capsule.properties
  • Properties defined in the default configuration mode in capsule.properties

For example, if you define config.sport=baseball in the properties file and then use the Config & Secrets screen to set sport to cricket, calling config.get('sport') from the JavaScript API (see Reading Properties & Secrets below) will return cricket, not baseball. The definition in the UI screen has a higher precedence than the definition in capsule.properties.

Reading Properties & Secrets

To access configuration properties, use the config.get() JavaScript method. To access secrets, use the secrets.get() JavaScript method.

require('config');
var value = config.get('key');

Secrets and configuration properties are entirely separate from each other: config.get('key') and secret.get('key') can yield different values. The configuration property named key and the secret named key are separate.

Note

Changes made in the Config & Secrets screen will not be reflected in the Bixby Developer Studio Simulator until a new conversation is started. If the Simulator is open when you make a change to a configuration or secret value, then recompile the NL model or press the Reset button in the Simulator to reload the new value.