Properties and custom properties

Create properties using Custom properties in code or Built-in targeting properties properties defined in the code. All property configurations are scoped to the application where they are defined. They are not shared across applications.

Built-in targeting properties

The following table lists built-in targeting, in the format of rox.<attribute name>:

Table 1. Built-in target group attributes
Attribute name	Description	Data type
`rox.app_release`	Application release version. This is the value set in the SDK’s `roxOptions.version` during setup.	SemVer
`rox.distinct_id`	Universally unique identifier (UUID).	String
`rox.language`	ISO 639 two-letter language code. For example, 'en' for English, 'es' for Spanish, and 'zh' for Chinese.	String
`rox.now`	Current time.	DateTime
`rox.platform`	Code language or framework name. For example, 'Python' or 'Gradle'.	String
`rox.screen_height`	Screen height in pixels.	Number
`rox.screen_width`	Screen width in pixels.	Number

Learn more about defining properties in the SDK references, and using properties to configure flags.

Create custom properties in either the UI or in code.

The following property types are available:

Boolean
Number (some code languages use Double and Int)
String
SemVer (pre-release and patch labels are not supported.)
DateTime

Custom properties in code

Add a custom property to your connected app code for use in target groups or directly within feature flag configurations, then run the app to display the property options in the UI.

Custom properties are not limited to target groups; they can also be used individually inside a feature flag configuration. This allows for more granular flag targeting without requiring a predefined target group. For example, you can apply a custom property directly within flag rules to evaluate specific conditions based on user attributes.

For example, the following code within a connected JavaScript app results in the target group options displayed below.

Rox.setCustomStringProperty('company', getCompany())
Rox.setCustomBooleanProperty('isBetaUser', betaAccess())
Rox.setCustomBooleanProperty('isLoggedIn', isLoggedIn())
Rox.setCustomDateTimeProperty('isTargetDate', getTargetDate())▼

The DateTimeProperty is only available for CloudBees platform.

Figure 1. Custom properties options are highlighted.

Usage examples: Explicit custom properties

Define explicit custom properties depending on the code language of your connected application:

Rox.setCustomStringProperty("userName", user.getName());

Rox.setCustomBooleanProperty("isPayingUser", user.isPayingUser());

Rox.setCustomComputedStringProperty("userNameComputed", new CustomPropertyGenerator<String>() {
 @Override
  public String generateProperty() {
    return database.getUserName();
  }
});▼

rox_set_custom_integer_property("intProp", 100);
rox_set_custom_string_property("stringProp", "something");
rox_set_custom_boolean_property("boolProp", true);
rox_set_custom_double_property("doubleProp", 3.14);
rox_set_custom_semver_property("smvrProp", "3.11.0");

RoxDynamicValue *check_if_playing(void *target, RoxContext *context) {
    return rox_dynamic_value_create_boolean(rox_context_get(context, "playing"));
}

rox_set_custom_computed_boolean_property("isPlayingProperty", NULL, &check_if_playing);

RoxDynamicValue *user_email(void *target, RoxContext *context) {
    return rox_dynamic_value_create_string_copy(rox_context_get(context, "email"));
}

rox_set_custom_computed_string_property("emailProperty", NULL, &user_email);▼

Rox::SetCustomProperty<int>("intProp", 100);
Rox::SetCustomProperty<const char *>("stringProp", "something");
Rox::SetCustomProperty<bool>("boolProp", true);
Rox::SetCustomProperty<double>("doubleProp", 3.14);
Rox::SetCustomSemverProperty("smvrProp", "3.11.0");

class CheckIfPlaying : public Rox::CustomPropertyGeneratorInterface {
public:
    explicit CheckIfPlaying() {}

    Rox::DynamicValue *operator()(Rox::Context *context) override {
        return rox_context_get(context, "playing");
    }
};

CheckIfPlaying checkIfPlaying = CheckIfPlaying();
Rox::SetCustomComputedProperty<bool>("isPlayingProperty", &CheckIfPlaying);

class UserEmail : public Rox::CustomPropertyGeneratorInterface {
public:
    explicit UserEmail() {}

    Rox::DynamicValue *operator()(Rox::Context *context) override {
        return rox_context_get(context, "email");
    }
};

UserEmail userEmail = UserEmail();
Rox::SetCustomComputedProperty<const char *>("emailProperty", &CheckIfPlaying);▼

rox.SetCustomStringProperty("serviceName", serviceName)

rox.SetCustomComputedBooleanProperty("isPaying", func(context context.Context) bool {
        value, _ := context.Get("is_paying_user").(bool)
        return value
    })▼

Rox.setCustomStringProperty("serviceName", serviceName);

Rox.setCustomComputedBooleanProperty("isPayingUser", new CustomPropertyGeneratorWithContext() {

  @Override
  public Boolean generateProperty(Context context) {
    return context.user.isPayingUser();
  }
});▼

Rox.setCustomNumberProperty("numberProperty", 100)
Rox.setCustomStringProperty("serviceName", serviceName)
Rox.setCustomBooleanProperty("booleanProperty", true)

Rox.setCustomBooleanProperty("isPaying", () => Account.sharedInstance().paying)
Rox.setCustomBooleanProperty("isPayingUser", context => context.user.isPayingUser())

Rox.setCustomStringProperty("email", () => Account.sharedInstance().email())▼

Rox.setCustomNumberProperty("numberProperty", 100)
Rox.setCustomStringProperty("serviceName", serviceName)
Rox.setCustomBooleanProperty("booleanProperty", true)

Rox.setCustomBooleanProperty("isPaying", () => Account.sharedInstance().paying)
Rox.setCustomBooleanProperty("isPayingUser", context => context.user.isPayingUser())

Rox.setCustomStringProperty("email", () => Account.sharedInstance().email())▼

Rox.SetCustomStringProperty("serviceName", serviceName);

Rox.SetCustomComputedBooleanProperty("isPayingUser", (context) =>
{
return database.user.isPayingUser();
});▼

Rox.setCustomNumberProperty("numberProperty", 100)
Rox.setCustomStringProperty("serviceName", serviceName)
Rox.setCustomBooleanProperty("booleanProperty", true)

Rox.setCustomBooleanProperty("isPaying", () => Account.sharedInstance().paying)
Rox.setCustomBooleanProperty("isPayingUser", context => context.user.isPayingUser())

Rox.setCustomStringProperty("email", () => Account.sharedInstance().email())▼

[ROXCore setCustomIntProperty:100 forKey:@"intProp"];
[ROXCore setCustomStringProperty:@"something" forKey:@"stringProp"];
[ROXCore setCustomBooleanProperty:YES forKey:@"boolProp"];

[ROXCore setCustomComputedBooleanProperty:^Bool *{
  return [[Account sharedInstance] isPaying];
} forKey:@"payingUser"];

[ROXCore setCustomComputedIntProperty:^int *{
  return [[Account sharedInstance] age];
} forKey:@"age"];

[ROXCore setCustomComputedStringProperty:^NSString *{
  return [[Account sharedInstance] email];
} forKey:@"email"];▼

# simple string property
Rox::setCustomStringProperty("stringProp", "something");

# simple Boolean property
Rox::setCustomBooleanProperty("boolProp", true);

# simple integer property
Rox::setCustomIntegerProperty("intProp", 100);

# simple double/float property
Rox::setCustomDoubleProperty("doubleProp", 3.14);

# simple semver property
Rox::setCustomSemverProperty("smvrProp", "3.11.0");

# computed dtring property
Rox::setCustomComputedStringProperty("userEmail", function (ContextInterface $context) {
  return $context->get("email");
});

# computed Boolean property
Rox::setCustomComputedBooleanProperty("isPlayingProperty", function (ContextInterface $context) {
  return (bool)$context->get("isPlaying");
});▼

# simple string property
Rox.set_custom_string_property('SomeKeyName', 'SomeValue')

# simple Boolean computed property
Rox.set_custom_boolean_property('isPaying', lambda context :
        context['is_paying_user']
)▼

Rox.setCustomNumberProperty("numberProperty", 100)

Rox.setCustomStringProperty("serviceName", serviceName)

Rox.setCustomBooleanProperty("booleanProperty", true)

Rox.setCustomBooleanProperty("isPaying", () => Account.sharedInstance().paying)

Rox.setCustomBooleanProperty("isPayingUser", context => context.user.isPayingUser())

Rox.setCustomStringProperty("email", () => Account.sharedInstance().email())▼

Rox::Server::RoxServer.set_custom_string_property("serviceName", serviceName)

# simple Boolean computed property
Rox::Server::RoxServer.set_custom_boolean_property('isPaying') do {ruby-explicit}
  context['is_paying_user'] == true
end▼

ROX.setCustomProperty(key:"intProp", value: 100)
ROX.setCustomProperty(key:"stringProp", value: "something")
ROX.setCustomProperty(key:"boolProp", value: true)

ROX.setCustomProperty(key: "isPaying") { () -> Bool in
  return Account.sharedInstance().paying
}

ROX.setCustomProperty(key: "email") { () -> String in
  return Account.sharedInstance().email
}▼

Usage examples: Implicit custom properties

A dynamic custom property rule handler is called when an explicit custom property definition does not exist in the platform.

If you do not define this rule handler, the default function is activated, which tries to extract the property value from the context by its name.

A generic implementation of that handler is described by the following:

(propName, context) => context ? context[propName] : undefined▼

Create this handler for implicit custom properties, depending on the code language of your connected application:

options := server.NewRoxOptions(server.RoxOptionsBuilder{
  DynamicPropertyRuleHandler: func(args model.DynamicPropertyRuleHandlerArgs) interface{} {
    if args.Context != nil {
      if account := args.Context.Get("account"); account != nil {
        return account.(map[string]interface{})[args.PropName]
      }
    }
    return nil
  },
})
<-rox.Setup(<YOUR-SDK-KEY>, options)▼

RoxDynamicValue *dynamic_rule(char *propName, void *target, RoxContext *context) {
  return rox_context_get(context, propName);
}

RoxOptions *options = rox_options_create();
rox_options_set_dynamic_properties_rule(options, NULL, &dynamic_rule);▼

class DynamicPropertyRule : public Rox::DynamicPropertiesRuleInterface {
  public:
    explicit DynamicPropertiesRuleInterface() {}
  public:
    DynamicValue *Invoke(const char *propName, Context *context) override {
        return rox_context_get(context, propName);
    }
};

int main(int argc, char **argv) {
    DynamicPropertyRule dynamicPropertyRule = DynamicPropertyRule();
    Rox::Options *options = Rox::OptionsBuilder()
        .SetDynamicPropertiesRule(&dynamicPropertyRule)
        .Build();

    Rox::Setup(<YOUR-SDK-KEY>, options);
    Rox::Shutdown();
}▼

options := server.NewRoxOptions(server.RoxOptionsBuilder{
  DynamicPropertyRuleHandler: func(args model.DynamicPropertyRuleHandlerArgs) interface{} {
    if args.Context != nil {
      if account := args.Context.Get("account"); account != nil {
        return account.(map[string]interface{})[args.PropName]
      }
    }
    return nil
  },
})
<-rox.Setup(<YOUR-SDK-KEY>, options)▼

RoxOptions options = new RoxOptions.Builder()
  .withDynamicPropertyRule(new DynamicPropertyRule() {
        @Override
        public Object invoke(String propName, Context context) {
            return (context != null) ? ((Map<String, Object>)context.get("account")).get(propName) : null;
        }
    })
  .build();
Rox.setup(<YOUR-SDK-KEY>, options);▼

const options = { dynamicPropertyRuleHandler: (propName, context) =>
                                 getLoggedInUser().properties[propName] };
Rox.setup(<YOUR-SDK-KEY>, options);▼

const options = { dynamicPropertyRuleHandler: (propName, context) =>
                                 getLoggedInUser().properties[propName] };
Rox.setup(<YOUR-SDK-KEY>, options);▼

const options = { dynamicPropertyRuleHandler: (propName, context) => {
  if (propName.startsWith('account.')) {
    const accountProp = propName.split(".")[0];
    return context['account'].properties[accountProp]);
  }
  return null;
}
}
Rox.setup(<YOUR-SDK-KEY>, options);▼

ROXOptions *options = [[ROXOptions alloc] init];
options.dynamicPropertiesRule = ^NSObject *(NSString *propName, ROXDynamicPropertyContext context) {
        return context(propName);
    };

[ROXCore setupWithKey:<YOUR-SDK-KEY> options:options];▼

use Rox\Core\Context\ContextInterface;
use Rox\Server\Rox;
use Rox\Server\RoxOptions;
use Rox\Server\RoxOptionsBuilder;

$options = new RoxOptions((new RoxOptionsBuilder())
    ->setDynamicPropertiesRule(function ($propName, ContextInterface $ctx) {
        return $ctx->get($propName);
    }));

Rox::setup(<YOUR-SDK-KEY>, $options);▼

def handler(prop_name, context):
  if prop_name.startswith('account.'):
    account_prop = prop_name.split('.')[0]
    return context['account'].properties[account_prop]
  return None

options = RoxOptions(dynamic_property_rule_handler=handler)
Rox.setup(<YOUR-SDK-KEY>, options)▼

const options = { dynamicPropertyRuleHandler: (propName, context) =>
                                 getLoggedInUser().properties[propName] };
Rox.setup(<YOUR-SDK-KEY>, options);▼

require 'rox/server/rox_server'

dynamic_property_rule_handler = proc do {ruby-implicit}
  context ? context.get[prop_name] : nil
end

options = Rox::Server::RoxOptions.new(
  dynamic_property_rule_handler: dynamic_property_rule_handler
)

Rox::Server::RoxServer.setup("<YOUR-SDK-KEY>", options).join▼

func dynamicPropertiesRule(propName:String, context:ROXDynamicPropertyContext) -> NSObject! {
    return context(propName)
}

let options = RoxOptions();
options.dynamicPropertiesRule = dynamicPropertiesRule
ROX.setup(withKey: <YOUR-SDK-KEY>, options: options);▼

If you are using a client-side SDK, and the value of a custom property changes while the app is running, such as after a user signs in, you may need to use Rox.unfreeze().

Manage custom properties in the UI

Create your own custom properties in the UI that can be used in target groups or as criteria for feature releases.

Access custom properties

To access custom properties, select Feature management Custom properties. Search for a specific custom property by entering all or part of a property name into Search.

Select

next to a heading on the custom property list to sort ascending or descending, respectively, on that heading. Alternatively, sort by selecting a heading from the Sort by options.

Create a custom property

To create a custom property in the UI:

Select Feature management Custom properties.
Select Create custom property.
Enter a Name.
(Optional) Enter a Description.
Select a data type from the options.
Select Save.

The custom property is created accordingly.

Update a custom property

You cannot update the custom property Name or Data type, but you can update the optional Description.

To update a custom property description:

Select Feature management Custom properties.
Select next to the property you want to update.
Select Edit property, and update or delete the description.
Select Update.

The custom property is updated accordingly.

Delete a custom property

A custom property cannot be deleted while it is still in use. You must first remove all references to it, such as conditions or configurations that use the property. Select Edit custom property to review and remove all references. Once all references are removed, the property can be safely deleted.

To delete a custom property:

Select Feature management Custom properties.
Locate the custom property to be deleted.
Select next to the property.
Select Delete. One of two dialogues displays.
1. The Delete (custom property) dialogue appears when the property is still in use. Follow these steps to remove the references:
  1. Review the environments where the property is being used.
  2. Verify that deletion is blocked; the Delete option is disabled until all references are removed.
  3. Select the Edit flag configuration link to open the configuration interface and review how the property is applied in feature flag rules. Then, delete the configuration or condition as needed.
    
    view the Delete (custom property) dialogue
    
    Figure 2. Delete (custom property) dialogue
  4. To remove a full configuration, including all conditions within the configuration select Delete next to the configuration.
  5. Select Save configuration to confirm changes.
    
    Figure 3. Delete a configuration
  6. To remove conditions, select next to the conditions you want to delete.
    
    Figure 4. Delete a single condition
  7. Select Save configuration to confirm changes.
2. The safely delete (custom property) dialogue appears, indicating all references are removed.
  
  Select Delete to permanently remove the custom property from the CloudBees platform.
  
  Figure 5. Safely delete custom property dialogue

Once deleted, the custom property cannot be restored.

For configuring user segmentation with target groups, refer to Target groups.