Ruby API

The following information is for the latest version of the Ruby SDK. If you are running an older version, please check the CloudBees Feature Management - Ruby changelog for any differences.

type Rox

require 'rox/server/rox_server'▼

Rox::Server::RoxServer▼

The Rox class provides an interface for CloudBees Feature Management to manage feature flags that control the behavior of your application. This is the central repository for your application’s flags. This class handles communications with the server to obtain the latest flag values, implement flag settings, and set up flag configurations. It works with a RoxContainer object, which holds your application’s feature flags. The values in the provided container are marked as feature flags and display in the CloudBees Feature Management UI once the application is run.

This class also allows you to manage custom properties. These can be static settings of type string, boolean, integer, or double, or you can use a generator type to provide a custom property that is dependent upon code state.

You can also use a RoxOptions object to configure some aspects of this type. You can set the verbosity level, custom platform, global freeze level, impression handler, and fetch handler.

setup

Rox::Server::RoxServer.setup("<ROLLOUT_KEY>"[, Rox::Server::RoxOptions]).join▼

Configures the Rox object to work with the provided application.

Parameter Modifier and Type Description

Parameter	Modifier and Type	Description
apiKey	string	The environment key provided by the CloudBees Feature Management dashboard
options	RoxOptions (optional)	A `RoxOptions` instance with the desired configuration for this application

apiKey

string

The environment key provided by the CloudBees Feature Management dashboard

options

RoxOptions (optional)

A RoxOptions instance with the desired configuration for this application

Returns

Thread that indicates when the SDK has received the configuration from the CloudBees Feature Management servers.

shutdown

Rox::Server::RoxServer.shutdown▼

Performs graceful shutdown of the Rox object; this will close and clean all background tasks and threads. Shutdown can only be used when Rox has been successfully set up; otherwise it results in a log warning. You can call Setup again after Shutdown; all Register and SetCustomProperty use the new Rox object, and register the objects to the CloudBees Feature Management UI on the next Setup call.

register

Rox::Server::RoxServer.register(container)▼

Rox::Server::RoxServer.register_with_namespace(namespace, container)▼

Registers a feature flag container with the Rox client. The public member variables of this container are a flag in the CloudBees Feature Management UI and are named with the object name. When using register, the container does not use namespace, so flag names do not have a prefix. It is equivalent to register_with_namespace with a namespace as an empty string.

Parameter Modifier and Type Description

Parameter	Modifier and Type	Description
namespace	string	The prefix namespace for all flags in this container (defaults to `''`)
container	object	An object that contains your application’s feature flags

namespace

string

The prefix namespace for all flags in this container (defaults to '')

container

object

An object that contains your application’s feature flags

To create a new container and register it:

require 'rox/server/rox_server'

class LoginContainer
  attr_accessor :include_github
  attr_accessor :include_facebook

  def initialize
    @include_github = Rox::Server::RoxFlag.new
    @include_facebook = Rox::Server::RoxFlag.new
  end
end

class SystemContainer
  attr_accessor :showNewUserScreen
  attr_accessor :useBulkFetch

  def initialize
    @showNewUserScreen = Rox::Server::RoxFlag.new
    @useBulkFetch = Rox::Server::RoxFlag.new
  end
end


login_container = LoginContainer.new
system_container = SystemContainer.new
Rox::Server::RoxServer.register_with_namespace('login', login_container)
Rox::Server::RoxServer.register(system_container)▼

The flags in the UI have the names login.include_facebook, login.include_github, showNewUserScreen, and useBulkFetch. The namespace is useful for organizing flags.

set_custom_boolean_property

Rox::Server::RoxServer.set_custom_boolean_property(name, value = nil, &block)▼

Sets a custom boolean property on the Rox client. The value can either be a computed boolean, or a boolean.

Parameter Modifier and Type Description

Parameter	Modifier and Type	Description
name	value	The name of the property to create
boolean	`boolean`	`(context) → boolean` (the value of the property, or a code block to compute the value for a given context)

name

value

The name of the property to create

boolean

boolean

(context) → boolean (the value of the property, or a code block to compute the value for a given context)

To create a new container and register it:

Rox::Server::RoxServer.set_custom_boolean_property('hasItemsInShoppingCart') do |context|
  context['shopping_cart'].empty?
end▼

set_custom_string_property

Rox::Server::RoxServer.set_custom_string_property(name, value = nil, &block)▼

Sets a custom string property on the Rox client. The value can either be a computed string, or a string.

Parameter Modifier and Type Description

Parameter	Modifier and Type	Description
name	value	The name of the property to create
string	`string`	`(context) → string` (the value of the property, or a code block to compute the value for a given context)

name

value

The name of the property to create

string

string

(context) → string (the value of the property, or a code block to compute the value for a given context)

To create a new container and register it:

Rox::Server::RoxServer.set_custom_string_property('email') do |context|
  context['user'].email
end▼

set_custom_float_property

Rox::Server::RoxServer.set_custom_float_property(name, value = nil, &block)▼

Sets a custom float property on the Rox client. The value can either be a computed float, or a float.

Parameter Modifier and Type Description

Parameter	Modifier and Type	Description
name	value	The name of the property to create
float	`float`	`(context) → float`

name

value

The name of the property to create

float

float

(context) → float

To create a new container and register it:

Rox::Server::RoxServer.set_custom_float_property('height') do |context|
  context['user'].height
end▼

set_custom_int_property

Rox::Server::RoxServer.set_custom_int_property(name, value = nil, &block)▼

Sets a custom int property on the Rox client. The value can either be a computed int, or a int.

Parameter Modifier and Type Description

Parameter	Modifier and Type	Description
name	value	The name of the property to create
int	`int`	`(context) → int`

name

value

The name of the property to create

int

int

(context) → int

To create a new container and register it:

Rox::Server::RoxServer.set_custom_int_property('age') do |context|
  context['user'].age
end▼

set_custom_semver_property

Rox::Server::RoxServer.set_custom_semver_property(name, value = nil, &block)▼

Sets a custom semver property on the Rox client. The value can either be a computed semver, or a semver.

Parameter Modifier and Type Description

Parameter	Modifier and Type	Description
name	value	The name of the property to create
string	`string`	`(context) → string`

name

value

The name of the property to create

string

string

(context) → string

To create a new container and register it:

Rox::Server::RoxServer.set_custom_semver_property('ruby version', RUBY_VERSION)▼

Global context

Rox::Server::RoxServer.context▼

Set a global context, which is available to all flag evaluations.

global_context = {'user': user}
Rox::Server::RoxServer.context = global_context▼

fetch

thread = Rox::Server::RoxServer.fetch▼

Create a network request for the latest configuration.

use_userspace_unhandled_error_handler

Rox::Server::RoxServer.use_userspace_unhandled_error_handler do |exception_source, exception_trigger, exception|
  # ...
end▼

A handler for all user function errors, which can assist with debugging and understanding unexpected flag values. If not set, errors are logged to the logger.

Wrapping all user methods with try-except to handle errors in the relevant context is recommended, rather than handling errors afterward.

When invoking the user_unhandled_error_invoker, the arguments passed are the exception_source, exception_trigger and exception. The exception_source is the original handler that caused the exception.

The exception_trigger is an enum for the user to delegate the type.

class ExceptionTrigger
  DYNAMIC_PROPERTIES_RULE = 1
  CONFIGURATION_FETCHED_HANDLER = 2
  IMPRESSION_HANDLER = 3
  CUSTOM_PROPERTY_GENERATOR = 4
end▼

The exception is the exception which was originally raised.

type RoxOptions

Rox::Server::RoxOptions▼

RoxOptions covers configuration options, including logging verbosity settings for the Rox client. Instances of this type should be created using server.NewRoxOptions.

Set up a new RoxOptions object. This object sets the version, creates a logger, provides an impression handler, and includes a configurationFetchedHandler.

require 'rox/server/rox_server'
option = Rox::Server::RoxOptions.new(
      configuration_fetched_handler: configuration_fetched_handler,
      impression_handler: impression_handler,
      dynamic_property_rule_handler: dynamic_property_handler,
      logger: Logger.new,
      version: '2.0.0',
      fetch_interval: 120
    )

    Rox::Server::RoxServer.setup('<ROLLOUT_KEY>', option).join▼

version

Set the version of the service running the CloudBees Feature Management SDK.

fetch_interval

Set the polling interval for fetching configuration from the CloudBees Feature Management storage service (in seconds, default to 60, canot be set below 30).

logger

Set the Logger to be used for logging.

class Logger
    def debug(message, ex = nil)
      puts 'Before Rox.Setup', message
    end

    def error(message, ex = nil)
      puts 'Before Rox.Setup', message
    end

    def warn(message, ex = nil)
      puts 'Before Rox.Setup', message
    end
  end
  option = Rox::Server::RoxOptions.new(
    logger: Logger.new
  )▼

configuration_fetched_handler

Set the configuration event handler, to add actions after configurations fetched.

proc do |configuration_fetcher_args|
  # ..
end▼

Properties of the argument passed into the configuration_fetched_handler.

Property Description

Property	Description
`fetcher_status`	Enum indicating the fetch result; can be `APPLIED_FROM_EMBEDDED`, `APPLIED_FROM_LOCAL_STORAGE`, `APPLIED_FROM_NETWORK`, or `ERROR_FETCHED_FAILED`.
`creation_date`	Time when the fetched configurations created and signed.
`error_details`	Enum indicating which error occurred while fetching and setting up new configurations. Can be `CORRUPTED_JSON`, `EMPTY_JSON`, `SIGNATURE_VERIFICATION_ERROR`, `NETWORK_ERROR`, `MISMATCH_APP_KEY`, `UNKNOWN`, or `NO_ERROR`.
`has_changes`	A boolean indication (as opposed to a configuration change).

fetcher_status

Enum indicating the fetch result; can be APPLIED_FROM_EMBEDDED, APPLIED_FROM_LOCAL_STORAGE, APPLIED_FROM_NETWORK, or ERROR_FETCHED_FAILED.

creation_date

Time when the fetched configurations created and signed.

error_details

Enum indicating which error occurred while fetching and setting up new configurations. Can be CORRUPTED_JSON, EMPTY_JSON, SIGNATURE_VERIFICATION_ERROR, NETWORK_ERROR, MISMATCH_APP_KEY, UNKNOWN, or NO_ERROR.

has_changes

A boolean indication (as opposed to a configuration change).

Refer to Flag update flow for more information.

impression_handler

Set the impression event handler to add actions after an impression.

proc do |impression_handler_args|
  # ..
end▼

Properties of the argument to be passed into the impression_handler.

Property Description

Property	Description
`reporting_value`	Object that contains name (string), value (string), and targeting (boolean).
`context`	The context in which the impression was called. (This is a merged context containing the global context and the call’s context.)

reporting_value

Object that contains name (string), value (string), and targeting (boolean).

context

The context in which the impression was called. (This is a merged context containing the global context and the call’s context.)

Refer to Impression handler for more information.

dynamic_property_rule_handler

The Dynamic Custom Property Generator is called when an explicit custom property definition does not exist on the client side.

proc do |prop_name, context|
  # ..
end▼

If you do not set the dynamic_property_rule_handler, it activates the default method, which tries to extract the property value from context.

Table 1. Arguments passed into the `dynamic_property_rule_handler`
Property	Description
`prop_name`	The property name request by the flag evaluation.
`context`	The context used to evaluate the flag.

Refer to Custom properties for more information.

roxy_url

A roxy url. Refer to Microservices automated testing and local development for more information.

type RoxFlag

require 'rox/server/flags/rox_flag'▼

Rox::Server::RoxFlag.new▼

RoxFlag is a boolean feature flag. It can be either true or false.

enabled?

enabled?(context)▼

Returns true if the flag is enabled based on given context.

enabled

enabled(context){ || block } -> Void▼

Runs the block if flag is true.

disabled

disabled(context){ || block } -> Void▼

Runs the block if flag is false.

name

@name▼

The name of the flag.

Class RoxString

require 'rox/server/rox_server'▼

Rox::Server::RoxString.new▼

RoxString is a feature flag object that can have string values. RoxString accepts a list of possible values for the feature flag and a default value. This list of values is used when selecting new values for the feature and is available for override in the UI.

require 'rox/server/rox_string'

class MyContainer
  attr_accessor :title_color

 def initialize
    @title_color = Rox::Server::RoxString.new('red', ['red', 'blue', 'green'])
  end
end

container = MyContainer.new

Rox::Server::RoxServer.register(container)
Rox::Server::RoxServer.setup('<ROLLOUT_KEY>').join▼

value

@value▼

Returns the RoxString value, considering the given context.

name

@name▼

The name of the RoxString.

Class RoxInt

require 'rox/server/rox_int'▼

RoxInt is a feature flag object that can have int values. RoxInt accepts a list of possible int values for the feature flag and a default value. This list of values is used when selecting new values for the feature and is available for override in the UI.

title_size_flag = Rox::Server::RoxInt.new(14, [14, 18, 24])

title_size = title_size_flag.value▼

value

flag.value(context = nil)▼

Returns the RoxInt value, considering the given context.

Class RoxDouble

require 'rox/server/rox_double'▼

RoxDouble is a feature flag object that can have double values. RoxDouble accepts a list of possible double values for the feature flag and a default value. This list of values is used when selecting new values for the feature and is available for override in the UI.

Example

price_options_flag = Rox::Server::RoxDouble.new(19.99, [19.99, 29.99, 40.5])

price = price_options_flag.value▼

value

flag.value(context = nil)▼

Returns the RoxDouble value, considering the given context.