Remote configuration as code

Change how your application behaves without releasing it again. Settings live in Git as typed values, are reviewed and tested like code, and reach applications in the next datafile.

Good candidates are settings that change more often than releases, and that someone other than an engineer often decides: the payment methods offered in each market, a free shipping threshold, the text of a promotional banner or a support address.

A setting without a flag#

A global variable holds a setting on its own, with no feature attached. checkoutSettings gives the checkout its currency and payment methods, with local methods for Dutch users:

variables/checkoutSettings.yml

description: Checkout settings
type: object
properties:
  currency:
    type: string
  paymentMethods:
    type: array
    items:
      type: string
defaultValue:
  currency: EUR
  paymentMethods:
    - card
overrides:
  - key: netherlands
    conditions: netherlands
    mutate:
      paymentMethods:
        - ideal
        - paypal

The schema means a typo such as paymentMethod, or a number where a list belongs, fails lint before anything ships. mutate changes paymentMethods and keeps the default currency, as Mutations explains.

Read it in your application#

const context = {
  userId: 'user-4',
  country: 'nl',
}
const settings = f.getVariable('checkoutSettings', context)

For user-4 in the Netherlands, settings is { currency: 'EUR', paymentMethods: ['ideal', 'paypal'] }. A German user gets the default, { currency: 'EUR', paymentMethods: ['card'] }.

checkoutSettings gives Dutch users ideal and paypal, and everyone else card, all in EUR.

Change it safely#

A change to a setting is a pull request, which the person who owns the setting can open themselves, from an editor or with Catalog's Propose change. Its test spec checks each audience gets the right value:

tests/variables/checkoutSettings.spec.yml

variable: checkoutSettings
assertions:
  - description: Dutch users pay locally
    context:
      country: nl
    expectedValue:
      currency: EUR
      paymentMethods: [ideal, paypal]
  - description: Everyone else pays by card
    context:
      country: de
    expectedValue:
      currency: EUR
      paymentMethods: [card]

Once it merges, your pipeline publishes the datafile. Applications get the new value on their next refresh, and a bad value is undone the same way, as Configuration rollback describes.

Narrow it further#

Overrides grow with the setting:

Nested overrides refine a value for a narrower audience, such as a city within a country.
Accumulating overrides let several matching overrides change one value in turn.
conditions gives users of a feature their own value, without the setting belonging to it.

Global or feature variable#

Use a global variable for a setting that stands on its own. When a value belongs to a feature, and should follow its rollout or its experiment, make it a feature variable instead, such as the label of buyButton, which changes with the button's variation.

Load updates#

The SDK evaluates whatever datafile it has. When your application fetches a newer one, replace the old one, so settings removed from the project do not linger:

f.setDatafile(nextDatafile, true)

Deployment compares ways to fetch it, and Offline evaluation covers starting without one.