Skip to content

Latest commit

 

History

History
171 lines (115 loc) · 10.6 KB

strategy-constraints.md

File metadata and controls

171 lines (115 loc) · 10.6 KB
Raw
id title
strategy_constraints
Strategy Constraints

:::info Availability Strategy constraints are available to Unleash Pro and Enterprise users.

Unleash 4.9 introduced a more comprehensive set of constraint operators. These require that both Unleash and your client SDK of choice support them. See the SDK compatibility table for more information. :::

:::tip This page explains what strategy constraints are in Unleash and how they work. If you want to know how you add strategy constraints to an activation strategy, see the corresponding how-to guide. :::

Strategy constraints are conditions that must be satisifed for an activation strategy to be evaluated for a feature toggle. With strategy constraints, you can:

  • roll out a feature only to users in a specific region
  • schedule a feature to be released at a specific time
  • make a feature available for a limited time only
  • release a feature to users with one of a set of email addresses
  • ... and much more!

Strategy constraints use fields from the Unleash Context to determine whether a strategy should apply or not. You can constrain both on standard context fields and on custom context fields.

Constraining on custom context fields

:::info Making custom context fields available To be able to constrain on a field, it must be listed under the Context Field menu. If a field isn't listed, you can add it yourself. See the how-to guide for creating your own custom fields for more info. :::

Unleash only provides a limited set of context fields by default, and they may not fulfill all your needs. By using custom context fields, you can tailor strategy constraints to your specific use case, such as:

  • based on tenant IDs,release a feature to only specific tenants in a multi-tenant setup
  • release a feature to users in a specific region
  • release a feature only to beta testers

You can also combine strategy constraints with the gradual rollout strategy to do a gradual rollout to a specific segment of your user base.

A toggle with the gradual rollout strategy. The toggle is constrained on the custom content field "region" and set to only activate if the region is Africa or Europe.

Constraint structure

Each strategy constraint has three parts:

  • a context field: The context field to use for evaluation.
  • an operator: One of the operators listed below.
  • a value/list of values: A value or list of values to use in the evaluation of the constraint.

These parts turn the strategy constraint into an expression that evaluates to either true or false.

To clarify, here's a few example strategy constraints and what they do:

Context field Operator Value(s) Description
userId STR_ENDS_WITH @example.com, @mycompany.com Evaluates to true for users whose user IDs end with @example.com or @mycompany.com.
currentTime DATE_AFTER 2022-06-05 21:43:22Z Evaluates to true if the current time is after 2022-06-05 21:43:22Z.
userScore1 NUM_GTE 1000 Evaluates to true if the custom context field userScore has a value of 1000 or higher.

Strategy constraint operators

:::note Placeholder context field In this section, <context-field> is used as a placeholder for an arbitrary context field. With the exception of the currentTime field, you can use any context field in its place. :::

Unleash currently supports 15 different constraint operators. The operators can be grouped into four different categories based on their method of comparison.

Constraint negation / inversion

All operators can be negated, meaning that they get their opposite value. Constraints are evaluated to either true or false. Negating an operator would turn a true value into a false and a false value into a true value.

For instance, using the numeric equivalence operator NUM_EQ, the following truth table shows the how value negation affects the result:

Expression Value Negated
4 NUM_EQ 4 true false
4 NUM_EQ 5 false true

Numeric operators

Numeric operators compare the numeric values of context fields with your provided value.

Numeric operators only accept single values.

Name true if <context-field> is ...
NUM_EQ equal to the provided value; the mathematical = operator
NUM_GT strictly greater than the provided value; the mathematical > operator
NUM_GTE greater than or equal to the provided value; the mathematical ⩾ operator
NUM_LT strictly less than the provided value; the mathematical < operator
NUM_LTE less than or equal to the provided value; the mathematical ⩽ operator

You can read more about numeric equality or numeric inequality operators at Wikipedia.

Date and time operators

:::info currentTime and date and time operators The date and time operators are only available on the currentTime context field. Furthermore, the currentTime context field can not be used with any of the other operators. :::

With the date and time operators, you can enable a feature before and/or after a specified time. The operators compare the Unleash context's currentTime property against the provided value.

You can create a time span by combining the two constraint operators using two different constraints on the same strategy. In that case the strategy will be evaluated from DATE_AFTER and until DATE_BEFORE.

Date and time operators only support single values.

Name true if currentTime is ...
DATE_AFTER after the provided date
DATE_BEFORE before the provided date

String operators

:::note Legacy note For backwards compatibility reasons, IN and NOT_IN are always case-sensitive. :::

String operators differ from the other categories in two different ways:

  • all operators accept multiple values
  • most operators also consider letter case and can be set to be case-sensitive or case-insensitive
Name true if <context-field> ... Available since
IN is equal to any of the provided values v3.3
NOT_IN is not equal to any of the provided values v3.3
STR_CONTAINS contains any of the provided strings v4.9
STR_ENDS_WITH ends with any of the provided strings v4.9
STR_STARTS_WITH starts with any of the provided strings v4.9

Versioning (SemVer) operators

The SemVer operators are used to compare version numbers such as application versions, dependency versions, etc.

You can enter SemVer values with or without a leading "v": v1.2.3 and 1.2.3 are both valid. Importantly, they are also considered equal.

Versions with pre-release indicators (e.g. 4.8.0-rc.2) are considered less than versions without (e.g. 4.8.0) in accordance with the SemVer specification.

SemVer operators only support single values.

Name true if <context-field> is ...
SEMVER_EQ equal to the provided value
SEMVER_GT strictly greater than the provided value
SEMVER_LT strictly less than the provided value

Interacting with strategy constraints in the client SDKs {#sdks}

:::note This section gives a brief overview over to use the client SDKs to interact with strategy constraints. The exact steps will vary depending on which client you are using, so make sure to consult the documentation for your specific client SDK. :::

Strategy constraints require the Unleash Context to work. All official Unleash client SDKs support the option to pass dynamic context values to the isEnabled function (or the SDK's equivalent).

If the strategy constraint uses a standard Unleash Context field, set the context field to the value you wish to give it.

If the strategy constraint uses a custom context field, use the Unleash Context's properties field. Use the name of the custom context field as a key and set the value to your desired string.

[Deprecated]: Constrain on a specific environment {#constrain-on-a-specific-environment}

Before Unleash 4.3, using strategy constraints was the recommended way to have different toggle configurations per environment. Now that Unleash has environment support built in, we no longer recommend you use strategy constraints for this. Instead, see the environments documentation.

Footnotes

  1. userScore is not a default Unleash field, but can be added as a custom context field. ↩