Go SDK reference

The following information is for the latest SDK version (6.x). The CloudBees platform requires that your installed SDK version be at least 6.x. Please install the latest SDK by following the instructions in the platform UI or in the SDK installation documentation.

Any updates to version 6.x are noted in the platform changelog.

type Rox

import  "{ROXGOVERSION}server"▼

server.NewRox()▼

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

This instance 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

Setup(appKey string, roxOptions model.RoxOptions) <-chan error▼

Configures the Rox object to work with the provided application.

Table 1. Parameter information
Parameter	Modifier and type	Description
appKey	string	The environment key provided by the UI
options	RoxOptions	A `RoxOptions` instance with the desired configuration for this application

Returns

Channel that indicates when the SDK has received the configuration from the platform if it signals nil or another error.

Shutdown

Shutdown() <-chan error▼

Perform graceful shutdown of the Rox object; this closes and cleans all background tasks and threads. Use Shutdown only when Rox is set up successfully. Calling Shutdown when it is not possible results in a log warning. You can call Setup again after Shutdown. All Register and SetCustomProperty then use a new Rox, and register the objects to the UI on the next setup call.

Register

Register(namespace string, roxContainer interface{})▼

RegisterWithEmptyNamespace(roxContainer interface{})▼

Registers a feature flag container with the Rox client. The public member variables of this container become a flag in the UI and are named with the object name.

Table 2. Parameter information
Parameter	Modifier and type	Description
namespace	string	The prefix namespace for all flags in this container (defaults to "")
container	interface	An object that contains your application’s feature flags

For example, assuming you have the following container:

type Container struct {
  IncludeFacebook server.RoxFlag
  IncludeGithub server.RoxString
}▼

and you register the container with the following code:

var conf = &Container {
  IncludeFacebook: server.NewRoxFlag(false),
  IncludeGithub: server.NewRoxFlag(false)
}
Rox.Register("login", conf);
<-Rox.Setup(rolloutKey, nil);▼

The flag and configuration in the UI have the names login.IncludeFacebook and login.IncludeGithub. This is useful in case you want groups of flags and configurations.

If you do not need a namespace, you can set the namespace to an empty string.

SetCustomComputedBooleanProperty

SetCustomComputedBooleanProperty(name string, value properties.CustomBooleanPropertyGenerator)▼

Sets a computed Boolean Custom Property on the Rox client. This is a computable Boolean, with an object that generates the value for the property.

Table 3. Parameter information
Parameter	Modifier and type	Description
name	string	The name of the property to create
generator	properties.CustomBooleanPropertyGenerator	An instance of the Boolean property’s generator type

SetCustomComputedFloatProperty

SetCustomComputedFloatProperty(name string, value properties.CustomFloatPropertyGenerator)▼

Sets a computed float Custom Property on the Rox client. This is a computable float, with an object that generates the value for the property.

Table 4. Parameter information
Parameter	Modifier and type	Description
name	string	The name of the property to create
generator	properties.CustomFloatPropertyGenerator	An instance of the float property’s generator type

SetCustomComputedIntegerProperty

SetCustomComputedIntegerProperty(name string, value properties.CustomIntegerPropertyGenerator)▼

Sets a computed integer Custom Property on the Rox client. This is a computable integer, with an object that generates the value for the property.

Table 5. Parameter information
Parameter	Modifier and type	Description
name	string	The name of the property to create
generator	properties.CustomIntegerPropertyGenerator	An instance of the integer property’s generator type

SetCustomComputedSemverProperty

SetCustomComputedSemverProperty(name string, value properties.CustomSemverPropertyGenerator)▼

Sets a computed semantic-versioned string Custom Property on the Rox client. This is a computable semantically-versioned string, with an object that generates the value for the property.

Table 6. Parameter information
Parameter	Modifier and type	Description
name	string	The name of the property to create
generator	properties.CustomSemverPropertyGenerator	An instance of the sematically-versioned property’s generator type

SetCustomComputedStringProperty

SetCustomComputedStringProperty(name string, value properties.CustomStringPropertyGenerator)▼

Sets a custom computed string property on the Rox client. This is a computable string, with an object that generates the value for the property.

Table 7. Parameter information
Parameter	Modifier and type	Description
name	string	The name of the property to create
generator	properties.CustomStringPropertyGenerator	An instance of the string property’s generator type

SetCustomBooleanProperty

SetCustomBooleanProperty(name string, value bool)▼

Sets a Custom Property representing a Boolean value.

Table 8. Parameter information
Parameter	Modifier and type	Description
name	string	The name of the custom property
value	bool	The value for the custom property

SetCustomFloatProperty

SetCustomFloatProperty(name string, value float64)▼

Sets a custom property that can store a specified float value.

Table 9. Parameter information
Parameter	Modifier and type	Description
name	string	The property name
value	float64	The value of the property

SetCustomIntegerProperty

SetCustomIntegerProperty(name string, value int)▼

Sets a custom property that can store a specified integer value.

Table 10. Parameter information
Parameter	Modifier and type	Description
name	string	The property name
value	int	The value of the property

SetCustomSemverProperty

SetCustomSemverProperty(name string, value string)▼

Sets a custom property that uses a semantic version as its value. Refer to the Semantic Versioning documentation for more information.

Table 11. Parameter information
Parameter	Modifier and type	Description
name	string	The name of the property to create.
value	string	The property value, formatted using the rules defined at `https://semver.org/`.

SetCustomStringProperty

SetCustomStringProperty(name string, value string)▼

Sets a custom string property for the Rox client, which is a string property you can fetch by name.

Table 12. Parameter information
Parameter	Modifier and type	Description
name	string	The name of the property to create
value	string	The property’s value

SetContext

SetContext(ctx context.Context)▼

Sets a global context. This context is available to all flag evaluations.

Fetch

Fetch() <-chan struct{}▼

Creates a network request for the latest configuration.

type RoxOptions

import  "{ROXGOVERSION}server"▼

server.NewRoxOptions()▼

RoxOptions covers configuration options for the Rox client. This includes settings like the log verbosity. Instances of this type should be created using server.NewRoxOptions.

The following is an example of setting up a new RoxOptions object. The options object sets the version, logger, impression handler, and fetch handler.

 options := server.NewRoxOptions(server.RoxOptionsBuilder{
    Logger:     &logger{},
    ConfigurationFetchedHandler: func(e *model.ConfigurationFetchedArgs) {
      if e != nil && e.FetcherStatus == model.FetcherStatusAppliedFromNetwork {
        TestVarsConfigurationFetchedCount      }
    },
    ImpressionHandler: func(e model.ImpressionArgs) {
      if e.ReportingValue != nil {
        if e.ReportingValue.Name == "FlagForImpression" {
          TestVarsIsImpressionRaised = true
        }
      }
      TestVarsImpressionReturnedArgs = &e
    },
    DynamicPropertyRuleHandler: func(e model.DynamicPropArgs) {
      if e.Context != nil {
        e.Context.Get(e.PropName)
      }
    }
  })
  rox = server.NewRox()


  err := <-rox.Setup("<Rollout_Key>", options)▼

type RoxOptions.RoxOptionsBuilder

server.RoxOptionsBuilder{...}▼

This Builder type is used to create a new RoxOptions instance.

Version

Set the version of the service running the feature management SDK.

FetchInterval

Set the polling interval for fetching the configuration from the platform. The default time setting is 60 seconds, and the minimum setting is 30 seconds.

Logger

Set the Logger to be used for logging.

type logger struct {
}

func (*logger) Debug(message string, err interface{}) {
  fmt.Println("Debug:", message)
}

func (*logger) Warn(message string, err interface{}) {
    fmt.Println("Warn", message)
}

func (*logger) Error(message string, err interface{}) {
    fmt.Println("Error", message)
}▼

ImpressionHandler

type ImpressionHandler = func(args ImpressionArgs)

type ImpressionArgs struct {
ReportingValue *ReportingValue
Context        context.Context
}

type ReportingValue struct {
	Name      string
	Value     string
	Targeting bool
}▼

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

Arguments to be passed into the ImpressionHandler

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).

DynamicPropertyRuleHandler

type DynamicPropertyRuleHandler = func(DynamicPropertyRuleHandlerArgs) interface{}

type DynamicPropertyRuleHandlerArgs struct {
	PropName string
	Context context.Context
}▼

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

If you do not set the DynamicPropertyRuleHandler, it activates the default method, which then attempts to extract the property value from context.

   dynamicPropertyRuleHandler := func(e model.DynamicPropArgs) {
      if e.Context != nil {
        e.Context.Get(e.PropName)
      }
    }▼

RoxyURL

A roxy URL for microservices automated testing and local development.

RoxContainer

The RoxContainer instance for your application contains all the feature flags for the features in your application. These feature flags are converted into CloudBees platform flags when the container is registered with Rox using Register(namespace string, container interface{}). Feature flag names are derived from the provided flag variable names.

For example, below is a quick example of how to use this container class:

var container = &Container {
  IncludeFacebook: server.NewRoxFlag(false),
  IncludeGithub: server.NewRoxFlag(false),
}
Rox.Register("login", conf);
<-Rox.Setup(rolloutKey, nil);▼

RoxFlag

import  "{ROXGOVERSION}server"▼

server.NewRoxFlag▼

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

IsEnabled

IsEnabled(ctx context.Context) bool▼

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

import "{ROXGOVERSION}core/context"

ctx := context.NewContext(map[string]interface{}{"email": "[email protected]"})
flagImpressionValue := container.IncludeFacebook.IsEnabled(ctx)▼

Name

Name() string▼

The name of the flag.

RoxString

import  "{ROXGOVERSION}server"▼

func NewRoxString(defaultValue string, options []string) RoxString▼

RoxString is a feature flag object that accepts a list of possible string values, and a default value. These values are used to select new values for the feature, and they can be overridden via the UI.

Use as in the following example:

var container = &Container {
  Variant: server.NewRoxString("red", []string{"red", "blue", "green"})
}

ctx := context.NewContext(map[string]interface{}{"gender": "female"})
container.VariantWithContext.GetValue(ctx)▼

GetValue

GetValue(context context.Context) string▼

Returns the RoxString value considering the given context.

Name

Name() string▼

The name of the RoxString.

RoxInt

import  "{ROXGOVERSION}server"▼

func NewRoxInt(defaultValue int, options []int) RoxInt▼

RoxInt is a feature flag object that accepts a list of possible integer values, and a default value. These values are used to select new values for the feature, and they can be overridden via the UI.

Use as in the following example:

priceOptionsFlag := server.NewRoxInt(2, []int{3,4,5}, nil)
titleSize := priceOptionsFlag.GetInt()▼

GetInt

GetInt(ctx context.Context)▼

Returns the RoxInt’s value considering the given context.

RoxDouble

import  "{ROXGOVERSION}server"▼

func NewRoxDouble(defaultValue float64, options []float64) RoxInt▼

RoxDouble is a feature flag object that accepts a list of possible double values, and a default value. These values are used to select new values for the feature, and they can be overridden via the UI.

Use as in the following example:

priceOptionsFlag := server.NewRoxDouble(19.99, []float64{20.99, 29.99, 40.5}, nil)

price := priceOptionsFlag.GetDouble()▼

GetDouble

GetDouble(ctx context.Context)▼

Returns the RoxDouble’s value considering the given context.

Context interface

import "{ROXGOVERSION}core/context"▼

context.NewContext▼

The context object is used to pass data to the Flag when checking if the current flag is enabled or disabled. This object is used by the registered Custom Properties to evaluate the experiment expression and return the flag value.

You can create a context using the NewContext function by sending a map as the argument.

Use as in the following example:

someContext := context.NewContext(map[string]interface{}{"user": user})▼

Get

Get(key string) interface{}▼

This get function is used to retrieve data from the context.

For example, you can see how the SetComputedStringProperty is using the context to get the username.

 rox.SetCustomComputedBooleanProperty("hasItemsInShoppingCart", func(ctx context.Context) bool {
    value, _ := ctx.Get("shoppingCart").(*ShoppingCart)
    return value.IsEmpty() })▼

DynamicAPI()

DynamicAPI()▼

An alternative of using container with register. This allows you to evaluate flags without having a static container. DynamicApi creates flags as if they were registered, including sending them to the UI.

IsEnabled

Evaluate a Boolean flag.

IsEnabled(name string, defaultValue boolean, ctx context.Context);▼

name

type

description

name

string

The flag’s name - throws an error if nil.

defaultValue

boolean

The default value to use if no dashboard configurations.

context

object

A context to evalute the flag with; is merged with the global context.

Value

Evaluate a string flag

Value(name string, defaultValue string, options []string, ctx context.Context);▼

name

type

description

name

string

The flag’s name - throws an error if nil.

defaultValue

string

The default value to use if no dashboard configurations, or value was set to default on dashboard throws an error if nil.

options

string[]

All alternative values to use on the UI (can be changed on the UI side).

context

object

A context to evalute the flag with, is merged with the global context.

GetInt

Evaluate an int flag.

GetInt(name string, defaultValue int, options []int, ctx context.Context);▼

Name	Type	Description
name	string	The flag’s name - throws an error if none.
defaultValue	int	The default value to use if no dashboard configurations or value was set to default on dashboard.
variations	int[]	All alternative values to use on the UI (can be changed on the UI side).
context	object	A context to evalute the flag with; is merged with the global context.

Name

Type

Description

name

string

The flag’s name - throws an error if none.

defaultValue

int

The default value to use if no dashboard configurations or value was set to default on dashboard.

variations

int[]

All alternative values to use on the UI (can be changed on the UI side).

context

object

A context to evalute the flag with; is merged with the global context.

GetDouble

Evaluate a double flag

GetDouble(name string, defaultValue float64, options []float64, ctx context.Context);▼

Name	Type	Description
name	string	The flag’s name - throws an error if none.
defaultValue	double	The default value to use if no dashboard configurations or value was set to default on dashboard.
variations	double[]	All alternative values to use on the UI (can be changed on the UI side).
context	object	A context to evaluate the flag with; is merged with the global context.

Name

Type

Description

name

string

The flag’s name - throws an error if none.

defaultValue

double

The default value to use if no dashboard configurations or value was set to default on dashboard.

variations

double[]

All alternative values to use on the UI (can be changed on the UI side).

context

object

A context to evaluate the flag with; is merged with the global context.