Configure feature flags

Configure a flag using product and user data to determine feature deployment conditions. Release features based on user properties such as location, device type, language, or dynamic target groups, using custom attributes that are evaluated at runtime.

A flag is the same flag across environments, but you can vary its configuration depending on the flag environment. Refer to how flags relate to environments for more information.

Nest conditions to create more complex flag configuration logic, containing flag, property, and target group condition types.

A flag configuration must be enabled to be functional.

Configuration values

To add complexity, add property, target group, and flag conditional statements using IF/THEN , ELSEIF/THEN, and ELSE logical operators.

Nested conditions are those that occur within a single conditional statement. Use as in the following table:

Table 1. Number of property, target group, and flag conditions permitted within a single conditional statement.
Condition	Maximum number of instances
Property	Unlimited
Target group	1
Flag	1

Figure 1. Configuring a string flag with nested conditions.

Default value

The default condition for a flag is to serve the value written in the source code.

Figure 2. Example string flag with the default condition.

Free text value

When you set the configuration for a number or string flag, you can select from predefined variations or enter free text as a flag value. Free text can only be added after Set to, THEN, or ELSE, not in IF or ELSEIF clauses. Free text values are useful when you have a string or numerical value which cannot be predetermined, such as a timeout value or URL.

Figure 3. A string flag with entered free text highlighted.

At any time during configuration, select Reset to restore the flag configuration to its saved state.

Add a conditional statement

Add conditional logic to your feature flag, choosing among property, target group, and flag options.

To add a conditional statement:

Select Feature management from the left pane.
Select next to the flag you want to configure.
Select Configure.
Select an Environment from the options.
Select Add new condition, and select an IF statement from the options.
1. If you select Property:
  1. Choose from the Select property options.
  2. Select an Operator from the options.
  3. Select a Value from the options.
2. If you select Target group:
  1. Choose from the Matches… options.
  2. Choose from the Select one or more groups options.
  3. Select a Value from the options.
3. If you select Flag:
  1. Choose from the Select flag options.
  2. Select Variant(s) from the options.
    
    Figure 4. Drag with one of the highlighted icons to reorder multiple conditions.
(Optional) Select Add new condition to create a new conditional statement, or select Add condition to add another nested condition.
Select one of the following for each ELSE and/or THEN value.
- For a Boolean flag:
  - True
  - False
  - Split
  - Scheduled
  - Value written in source code
- For a string or number flag:
  - A free text value
  - Any predefined variation
  - Split
  - Value written in source code
Select Save configuration, or select Save and activate configuration.

Refer to Configuration values for more information.

A conditional statement for a flag configuration is set accordingly. Enable the flag configuration by turning the configuration status to On.

Figure 5. A number flag property condition with save options highlighted.

Add a nested condition

Add complex logic to your flag configuration statements with nested conditions separated by an AND or an OR.

To add a nested condition:

Select Feature management from the left pane.
Select next to the flag you want to configure.
Select Configure.
Select an Environment from the options.
Select Add new condition if you have not already added at least one condition to create a conditional statement.
Select Add condition to add a nested condition.
Select MATCHES ALL OF THE FOLLOWING (an AND logical operator) or MATCHES ANY OF THE FOLLOWING (an OR logical operator).

Figure 6. Nested string flag configuration with AND highlighted.
Select from the options.
(Optional) Select Add condition to add another nested condition, or select Add new condition to create a new conditional statement.
Select Save configuration, or select Save and activate configuration.

Select the next to a condition to remove it.

A nested flag configuration condition within a conditional statement is set accordingly. Enable the flag configuration by turning the configuration status to On.

Configuration status

The configuration status is the key flag controller within an environment.

By enabling a flag configuration, release features based on user properties such as location, device type, language, or dynamic target groups, using custom attributes that are evaluated at runtime.

Turning a flag configuration on or off only affects the flag configuration in a given environment.

To change the configuration status:

Select Feature management from the left pane.
Select the Environment from the options.
Select next to the flag configuration you want to enable.
Select Configure.
Select the configuration On or Off toggle to turn the configuration status off or on, respectively.

Figure 7. A string flag with the configuration toggle highlighted.

Turning a configuration On sets the flag value to the Configure rules. Turning a configuration Off disables the configuration rules and serves the default configuration value as written in the code. The selected flag configuration status is updated accordingly for the specified environment only.

Configure a scheduled release (boolean flags only)

Schedule a Boolean flag configuration to be enabled for a fraction of users at a given date and time. For example, you may want to deploy a feature to 25% of users on a particular day, to 50% of users a month later, and to 100% of users two months later, to allow for user feedback and testing.

By designating the percentage of users exposed to the feature and the timing of release, you provide granular control over your feature release schedule.

To create a feature release schedule:

Select Feature management from the left pane.
Select next to the flag you want to configure.
Select Configure.
Select an Environment from the options.
Do one of the following:
- If your flag has no conditional statements, select Scheduled from the Set to options.
- If you have added conditions, and/or nested conditions to a feature flag, select Scheduled from the THEN and/or the ELSE options.
  
  The scheduled percentage is displayed, and defaults to True 0% at the current time, and True 100% five minutes later in 24-hour clock format.
(Optional) Select a time zone from the options.
(Optional) Enter a positive number to adjust either of the schedule percentages.
(Optional) Set the schedule percentage date by either of the following:
- Select the date and enter your desired date.
- Select the .
  1. (Optional) Select the to adjust the year.
  2. (Optional) Select the to adjust the month.
    
    Figure 8. Scheduled flag example with date and time controls highlighted.
    
    You must set any new scheduled percentage date and time to occur after any existing scheduled percentage date and time.
(Optional) Set the schedule percentage time by either of the following:
- Select the time and enter your desired time, in one-minute increments.
- Select the , and scroll to adjust the hour and minutes, in five-minute increments.
(Optional) Select Add row to add unlimited scheduled percentages and dates/times, each of which default to True 0% at five minutes after the last scheduled time, and adjust accordingly.
Select SAVE CONFIGURATION, or select Save and activate configuration.

The scheduled condition(s) for the flag configuration is set accordingly. Enable the flag configuration by turning the configuration status to On. Once enabled, the Boolean flag serves the value True to the designated percentage of users at the designated dates and times.

You can add more than one schedule, as in the below example:

Figure 9. Example flag with two schedules configured.

Configure a split release

Split releases are designed to provide consistency for the user. A distributed algorithm, which is similar to tossing a coin, determines the split. When the user revisits the page, the flag configuration persists, and provides a consistent user experience. Configure any flag to release its associated features to a specified percentage of users.

For example, you might want to release an experimental feature to a third of your beta user group, chosen randomly. To be sure the same third of testers experience the experimental feature each time they access your application, configure a split release.

To configure a split percentage flag:

Select Feature management from the left pane.
Select next to the flag you want to configure.
Select Configure.
Select an Environment from the options.
Do one of the following:
- If your flag has no conditional statements, select Split from the Set to options.
- If you have added conditions, and/or nested conditions to a feature flag, select Split from the THEN and/or the ELSE options.
The split percentage is displayed, and defaults to the following (according to flag type):
- Boolean flag: A split between True and False.
- Number flag: A split among all variations.
- String flag: A split among all variations.

(Optional) Adjust the split percentages by either of the following:

Select the .

Enter an exact number.

Figure 10. Boolean split percentage example with arrow controls highlighted.

The total percentage must equal 100%. To remove a string or number variation, set the percentage to 0%.

To add a new variation to the split:

Define a new variation in the flag settings.
In the flag configuration, delete the current split and set up a new one. The new split has the new variation.

Figure 11. String split percentage example with one variation unused.

Select Save configuration, or select Save and activate configuration.

The new split conditions for the flag configuration are set accordingly. Enable the flag configuration by turning the configuration status to On.

Once enabled, each split percentage serves its specific value to that same set of users each time they open the application. For a Boolean flag, the values are True or False, and for a number or string flag, the values are the indicated variations.

CloudBees strongly recommends that you preserve the consistency of the user experience by never decreasing a live Boolean flag’s True percentage. Decreasing the True percentage of a flag that is enabled in production may lead to inconsistencies, in which some users who previously had received a True value may instead receive a False value.

While CloudBees recommends that you avoid updating any flags live in production, sometimes changes must be made. If so, you can safely increase a flag’s True percentage. When a flag’s True percentage is increased, all users that previously received a True value continue to have that same experience.

The split release algorithm

The split release flag algorithm works as follows:

The built-in property rox.distinct_id is a universally unique identifier (UUID). It is generated and serialized in the app.
Every feature flag has its own seed to remove any potential statistical bias between two feature flags.
The SDK uses the seed and rox.distinct_id (known as the "stickiness property") to run a hash function that is mapped to a double number from 0 to 1.

If you select a 50% split, for example, the platform checks if the hash result is smaller than 0.5.

Modify the stickiness property

The stickiness behavior for a particular feature flag determines what value a user should get when splitting values.

For example, if you select userId as the stickiness property, the userId has a consistent behavior on all devices. Alternatively, if you select account_id as the stickiness property, all users in the same account experience consistent behavior.

The default value for the stickiness property is the UUID distinct_id, but this can be modified. The distinct_id is stored on the local storage of the end user device.

You can choose to override the rox.distinct_id to support the following:

A consistent cross-platform behavior for split releases.
A consistent experience for back-end SDK users.

The stickiness property of a flag can be any property you choose, and is specific for each environment.

To update the default (distinct_id) stickiness property:

Select Feature management from the left pane.
Select next to the flag you want to configure.
Select Configure.
Select an Environment from the options.
Select to the right of the flag name.
Select Flag settings.

Figure 12. Example flag with Flag settings highlighted.
Select from the Stickiness property options, which are any custom or built-in properties.
Select Update.

The stickiness property is updated accordingly.

Clone a flag configuration

Cloning a flag configuration overrides the destination flag configuration. The flag rules are copied during cloning to override the flag configuration in the destination environment. Cloning is an efficient way to set up complex flag configurations in a different environment(s).

To clone a flag configuration:

Select Feature management from the left pane.
Select next to the flag you want to clone.
Select Configure.
Select Environment from the options to clone the configuration for that environment to another environment or environments.
Select Clone configuration.

Figure 13. Example flag with Clone configuration highlighted.
Select the environment(s) you want to clone to, or Select all.

Any existing configuration on the flag in the selected environment(s) is overridden if you select Save at the below cloning step.
Select SAVE.

The selected flag configuration and its configuration status are cloned to the chosen environment(s).