mirror of
https://github.com/Unleash/unleash.git
synced 2025-01-25 00:07:47 +01:00
Merge pull request #1200 from Unleash/docs/unleash-context
docs: Flesh out Unleash Context, Strategy constraints, add how-to guides for both
This commit is contained in:
Thomas Heartman
GitHub
commit
73b05ec415
@ -17,7 +17,7 @@ Because the number assigned to a user won't change, Unleash also guarantees that
|
||||
|
||||
For instance: When using the [gradual rollout activation strategy](../user_guide/activation-strategies.md#gradual-rollout), any user whose number is less than or equal to the rollout percentage will see the feature. This means that the same users will keep seeing the feature even as you increase the percentage of your user base that sees the feature.
|
||||
|
||||
## Custom stickiness (beta)
|
||||
## Custom stickiness (beta) {#custom-stickiness}
|
||||
|
||||
:::info
|
||||
Custom stickiness is available starting from Unleash Enterprise v4.
|
||||
@ -26,7 +26,7 @@ Custom stickiness is available starting from Unleash Enterprise v4.
|
||||
When using [the gradual rollout strategy](../user_guide/activation-strategies.md#gradual-rollout) or [feature toggle variants](./feature-toggle-variants.md), you can use parameters other than the user id to calculate stickiness. More specifically, you can use any field, custom or otherwise, of the [Unleash Context](../user_guide/unleash-context.md) as long as you have enabled custom stickiness for these fields.
|
||||
|
||||
:::note
|
||||
This is a beta featue, so not all client SDKs support this feature yet. Check your SDK's documentation to learn more.
|
||||
This feature is currently in beta and is not yet supported by all our SDKs. Check out the [SDK compatibility table](../sdks/index.md#server-side-sdk-compatibility-table) to see what SDKs support it at the moment.
|
||||
:::
|
||||
|
||||
### Enabling custom stickiness
|
||||
|
||||
@ -3,71 +3,54 @@ id: strategy_constraints
|
||||
title: Strategy Constraints
|
||||
---
|
||||
|
||||
<div class="alert alert--info" role="alert">
|
||||
Strategy constraints are part of Unleash Pro and Enterprise.
|
||||
</div>
|
||||
<br />
|
||||
:::info Availability
|
||||
Strategy constraints are available to Unleash Pro and Enterprise users.
|
||||
:::
|
||||
|
||||
Strategy constraints allow you to set preconditions on activation strategies that must be satisfied for the activation strategy to take effect. For example, you might want a strategy to only trigger if a user belongs to a specific group or is in a specific country.
|
||||
:::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](../how-to/how-to-add-strategy-constraints.md "how to add strategy constraints").
|
||||
:::
|
||||
|
||||
Constraints use fields from the [Unleash Context](../user_guide/unleash_context) to determine whether a strategy should apply or not. You can constrain on both standard context fields and on custom context fields.
|
||||
**Strategy constraints** allow you to set preconditions on activation strategies that must be satisfied for the activation strategy to take effect. For example, you might want a strategy to only trigger if a user belongs to a specific group or is in a specific country.
|
||||
|
||||
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. See [the section on defining your own custom fields](#define-your-own-custom-fields) for more info.
|
||||
|
||||
## How to add strategy constraints
|
||||
|
||||
To add a strategy constraint, you'll need a feature toggle with a defined strategy.
|
||||
|
||||
Then, use the "add constraint" button in the UI, choose your context field, and the appropriate values that you wish to constrain it to.
|
||||
|
||||
|
||||
Constraints use fields from the [Unleash Context](../user_guide/unleash_context) to determine whether a strategy should apply or not. You can constrain on both [standard context fields](../user_guide/unleash_context#structure) and on [custom context fields](../user_guide/unleash_context#custom-context-fields). A common use for using custom context fields is a multi-tenant service where you want to use a tenant identifier to control the feature rollout. This would allow you to decide which users should get access to your new feature based on the tenant. Other commonly seen custom context fields include fields for region, country, and customer type.
|
||||
|
||||
|
||||
### Constraining on standard context fields
|
||||
Combining strategy constraints with the [gradual rollout strategy](../user_guide/activation_strategy#gradual-rollout) allows you to do a gradual rollout to a specific segment of your user base.
|
||||
|
||||
To constrain on a standard context field, choose the field you wish to constrain on. If the context field you want to constrain on isn't listed, you'll need to add it manually via the Context Field menu. Follow the procedure as if you were [defining custom context fields](#define-your-own-custom-fields), but give it a name that matches the desired field in the Unleash Context. Note that context fields are case-sensitive.
|
||||
|
||||
|
||||
### Constraining on custom context fields {#constrain-on-custom-context-fields}
|
||||
## Constraint structure
|
||||
|
||||
If you need context data that isn't available in the default Unleash Context, you can also constrain on custom context fields. A common use case is a multi-tenant service where you want to use a tenant identifier to control the feature rollout. This would allow you to decide which users should get access to your new feature based on the tenant.
|
||||
Each strategy constraint has three parts:
|
||||
|
||||
|
||||
- **Context field**: The context field to evaluate.
|
||||
- **Operator**: Either `IN` or `NOT_IN`.
|
||||
- **Values**: The list of values that trigger this constraint.
|
||||
|
||||
#### Defining custom fields {#define-your-own-custom-fields}
|
||||
The **context field** is the field that you want to use for constraining this strategy. The **values** field is a list of values that the constraint should either allow or deny. The **operator** determines whether the values are allowed or denied.
|
||||
|
||||
> Starting with Unleash-enterprise version 3.2.28 customers can define their custom context fields via the user interface.
|
||||
For instance, to constrain the strategy to only users with IDs `id-123` and `id-456`: select `userId` as the context field, use the `IN` operator, and set values to `id-123, id-456`. The strategy will then be evaluated only for these two users.
|
||||
|
||||
You can also define custom context fields to use with strategy constraints. We have seen customers use multiple variants of custom context fields to control their feature rollout, such as:
|
||||
If, on the other hand, you would like to ensure the strategy is never evaluated for the same users, you would use the same configuration as above, but set the operator to `NOT_IN`. This would mean that the strategy is evaluated for all users _not_ listed in the values.
|
||||
|
||||
- `region`
|
||||
- `country`
|
||||
- `customerType`
|
||||
- `tenantId`
|
||||
## Interacting with strategy constraints in the client SDKs {#sdks}
|
||||
|
||||
Combining strategy constraints with the [gradual rollout strategy](../user_guide/activation_strategy#gradual-rollout) would allow you to do a gradual rollout to a specific segment of your user base.
|
||||
:::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.
|
||||
:::
|
||||
|
||||
##### Step 1: Navigate to “Context Fields“ {#step-1-navigate-to-context-fields}
|
||||
Strategy constraints require [the Unleash Context](../user_guide/unleash_context) to work. All official [Unleash client SDKs](../sdks/index.md) support the option to pass [dynamic context values](../user_guide/unleash_context#structure "Unleash Context, section: structure") to the `isEnabled` function (or the SDKs equivalent).
|
||||
|
||||
Locate “context fields in the menu"
|
||||
If the strategy constraint uses a [**standard Unleash Context field**](../user_guide/unleash_context#structure), set the context field to the value you wish to give it.
|
||||
|
||||
|
||||
If the strategy constraint uses a [**custom context field**](../user_guide/unleash_context#custom-context-fields), 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.
|
||||
|
||||
##### Step 2: Define new context field {#step-2-define-new-context-field}
|
||||
## Prerequisites
|
||||
|
||||
Next you can define your new context field. The minimum requirement is to give it a unique _name_. In addition, you can give it a description and define [_legal values_](#what-is-legal-values).
|
||||
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](../how-to/how-to-define-custom-context-fields.md) for more info.
|
||||
|
||||
|
||||
|
||||
###### What are “legal values”? {#what-is-legal-values}
|
||||
|
||||
To constrain what values a user can enter for a context field in the Unleash Admin UI, you can use _legal values_. This is a set of predefined values that show up as a dropdown
|
||||
|
||||
A context field's _legal values_ are a set of predefined values that you can
|
||||
|
||||
define all possible values for that context field. These values appear in the Unleash Admin UI to guide users when working with context fields to make sure they only use legal values.
|
||||
|
||||
|
||||
|
||||
### [Deprecated]: Constrain on a specific environment {#constrain-on-a-specific-environment}
|
||||
## [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](../user_guide/environments).
|
||||
|
||||
44
website/docs/how-to/how-to-add-strategy-constraints.md
Normal file
44
website/docs/how-to/how-to-add-strategy-constraints.md
Normal file
@ -0,0 +1,44 @@
|
||||
---
|
||||
title: How to add strategy constraints
|
||||
---
|
||||
|
||||
:::info Availability
|
||||
Strategy constraints are available to Unleash Pro and Enterprise users.
|
||||
:::
|
||||
|
||||
This guide shows you how to add [strategy constraints](../advanced/strategy-constraints.md) to your feature toggles via the admin UI. For information on how to interact with strategy constraints from an [Unleash client SDK](../sdks/index.md), visit the specific SDKs documentation or see [the relevant section in the strategy constraints documentation](../advanced/strategy-constraints.md#sdks "strategy constraints documentation, section on interacting with constraints from client SDKs").
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You'll need to have an existing feature toggle with a defined strategy to add a constraint. The rest of this guide assumes you have a specific strategy that you're working with.
|
||||
|
||||
## Step 1: Open the constraints menu {#step-1}
|
||||
|
||||
Every strategy will have button labeled "add constraints" when viewed in the admin UI. Interact with this to open the constraints menu.
|
||||
|
||||
|
||||
|
||||
## Step 2: Configure the constraint {#step-2}
|
||||
|
||||
Refer to [the _constraint structure_ section of the strategy constraints reference](../advanced/strategy-constraints.md#constraint-structure) for a thorough explanation of the fields.
|
||||
|
||||
From the "Context Field" dropdown, select the context field you would like to constrain the strategy on.
|
||||
|
||||
|
||||
|
||||
## Step 3: Add additional constraints {#step-3}
|
||||
|
||||
To add additional constraints:
|
||||
1. Repeat [step one](#step-1 "step 1: open the constraints menu") to open the constraints menu.
|
||||
2. Use the "Add constraint" button to add a new constraint.
|
||||
|
||||
|
||||
|
||||
3. Follow [step two](#step-2 "step 2: configure the constraint") for the new constraint.
|
||||
|
||||
## How to update existing constraints
|
||||
|
||||
You can update any existing constraint by doing one of the following:
|
||||
|
||||
- Open the "add constraints" menu and modify existing constraints.
|
||||
- Using the constraint's "edit" button to bring up the constraints menu.
|
||||
29
website/docs/how-to/how-to-define-custom-context-fields.md
Normal file
29
website/docs/how-to/how-to-define-custom-context-fields.md
Normal file
@ -0,0 +1,29 @@
|
||||
---
|
||||
title: How to define custom context fields
|
||||
---
|
||||
|
||||
:::info Availability
|
||||
Custom context fields are available to Pro and Enterprise users. They were introduced in Unleash 3.2.28.
|
||||
:::
|
||||
|
||||
This guide shows you how to create [custom context field for the Unleash Context](../user_guide/unleash-context.md#custom-context-fields). You can use custom context fields for [strategy constraints](../advanced/strategy-constraints.md) and for [custom stickiness calculations](../advanced/stickiness.md#custom-stickiness). If there are [standard Unleash Context fields](../user_guide/unleash-context.md#structure) missing from the context fields page, you can use the same steps to add them too.
|
||||
|
||||
## Step 1: Navigate to the context field creation form {#step-1-navigate-to-context-fields}
|
||||
|
||||
In the Unleash Admin UI, navigate to the _context fields_ page:
|
||||
1. Click the "Configure" button in the top menu to open the configuration dropdown menu.
|
||||
2. Click the "Context fields" menu item.
|
||||
|
||||
|
||||
|
||||
3. On the context fields page, click the "add new context field" button.
|
||||
|
||||
|
||||
|
||||
## Step 2: Define the new context field {#step-2-define-new-context-field}
|
||||
|
||||
Define the custom context field by filling out the form. You must at least the field a unique _name_. Everything else is optional. Refer to the [custom context field reference guide](../user_guide/unleash-context.md#custom-context-fields) for a full overview of the parameters and their functions and requirements.
|
||||
|
||||
When you are satisfied with the context field's values, use the "create" button to submit the form and save the context field.
|
||||
|
||||
|
||||
@ -3,24 +3,76 @@ id: unleash_context
|
||||
title: Unleash Context
|
||||
---
|
||||
|
||||
To standardize a few activation strategies, we also needed to standardize the Unleash context, which contains fields that vary per request, required to implement the activation strategies.
|
||||
The **Unleash Context** contains information relating to the current feature toggle request. Unleash uses this context to evaluate [activation strategies](activation-strategies.md) and [strategy constraints](../advanced/strategy-constraints.md) and to calculate [toggle stickiness](../advanced/stickiness.md). The Unleash Context is an important feature of all the [Unleash client SDKs](../sdks/index.md).
|
||||
|
||||
The Unleash context is composed of a set of predefined fields. The static fields do not change in the life-time of your application, while dynamic fields can change per feature toggle evaluation.
|
||||
## Structure
|
||||
|
||||
**Static context fields**
|
||||
You can group the Unleash Context fields into two separate groups based on how they work in the client SDKs: **static** and **dynamic** context fields.
|
||||
|
||||
- appName: String
|
||||
- environment: String
|
||||
**Static** fields' values remain constant throughout an application's lifetime. You'll typically set these when you initialize the client SDK.
|
||||
|
||||
**Dynamic context fields**
|
||||
**Dynamic** fields, however, can change with every request. You'll typically provide these when checking whether a toggle is enabled in your client.
|
||||
|
||||
- userId: String,
|
||||
- sessionId: String,
|
||||
- remoteAddress: String,
|
||||
- properties: Map<String, String>
|
||||
_All fields are optional_, but some strategies depend on certain fields being present. For instance, [the UserIDs strategy](activation-strategies.md#userids) requires that the `userId` field is present on the Context.
|
||||
|
||||
All fields are optional, but if they are not set you will not be able to use certain activation strategies. E.g., the `userWithId` strategy obviously depends on the `userId` field.
|
||||
The below table gives a brief overview over what the fields' intended usage is, their lifetime, and their type. Note that the exact type can vary between programming languages and implementations. Be sure to consult your specific client SDK for more information on its implementation of the Unleash Context.
|
||||
|
||||
The `properties` field is more generic and can be used to provide more arbitrary data to strategies. Typical usage is to add more metadata. For instance, the `betaUser` strategy may read a field from `properties` to check whether the current user is a beta user.
|
||||
| field name | type | lifetime | description |
|
||||
|-------------------|-----------------------|----------|----------------------------------------|
|
||||
| `appName` | `string` | static | the name of the application |
|
||||
| `environment`[^1] | `string` | static | the environment the app is running in |
|
||||
| `userId` | `string` | dynamic | an identifier for the current user |
|
||||
| `sessionId` | `string` | dynamic | an identifier for the current session |
|
||||
| `remoteAddress` | `string` | dynamic | an identifier for the current session |
|
||||
| `properties` | `Map<string, string>` | dynamic | a key-value store of any data you want |
|
||||
|
||||
In Unleash Enterprise you may also pre-configure all you customer context fields (`properties`) and use them together with [strategy constraints](../advanced/strategy_constraints) to compose any target rules you need.
|
||||
|
||||
### The `properties` field
|
||||
|
||||
The `properties` field is different from the others. You can use the `properties` field to provide arbitrary data to [custom strategies](../advanced/custom-activation-strategy.md) or to [strategy constraints](../advanced/strategy-constraints.md). The `properties` field is also where you add values for [custom context fields](#custom-context-fields).
|
||||
|
||||
|
||||
#### A note on properties and constraints
|
||||
|
||||
Some SDK implementations of the Unleash Context allow for the values in the `properties` map to be of other types than a string type. Using non-string types as values may cause issues if you're using the property in a constraint. Because the Unleash Admin UI accepts any string as input for constraint checking, the SDKs must also assume that the value is a string.
|
||||
|
||||
As an example: You've created a custom field called `groupId`. You know group IDs will always be numeric. You then create a constraint on a strategy that says the user must be in group `123456`. If you were to set the property `groupId` to the number `123456` in the `properties` field on the SDK side, the constraint check would fail, because in most languages the number `123456` is not equal to the string `123456` (i.e. `123456 != "123456"`).
|
||||
|
||||
|
||||
|
||||
## Custom context fields
|
||||
|
||||
:::info Availability
|
||||
Custom context fields are available to Pro and Enterprise users.
|
||||
:::
|
||||
|
||||
Custom context fields allow you to extend the Unleash Context with more data that is applicable to your situation. Each context field definition consists of a name and an optional description. Additionally, you can choose to define a set of [_legal values_](#legal-values "legal values for custom context fields"), and you can choose whether or not the context field can be used in [custom stickiness calculations](../advanced/stickiness.md#custom-stickiness) for the [gradual rollout strategy](activation-strategies.md#customize-stickiness-beta) and for [feature toggle variants](../advanced/feature-toggle-variants.md).
|
||||
|
||||
When interacting with custom context fields in code, they must be accessed via the Unleash Context's `properties` map, using the context field's name as the key.
|
||||
|
||||
### Creating and updating custom context fields
|
||||
|
||||
You can create as many custom context fields as you wish. Refer to ["how to define custom context fields"](../how-to/how-to-define-custom-context-fields) for information on how you define your own custom context fields.
|
||||
|
||||
You can update custom context fields after they have been created. You can change everything about the definition except for the name.
|
||||
|
||||
### Legal values
|
||||
|
||||
By using the **legal values** option when creating a context field, you can create a set of valid options for a context field's values.
|
||||
If a context field has a defined set of legal values, the Unleash Admin UI will only allow users to enter one or more of the specified values. If a context field _doesn't_ have any defined legal values, the user can enter whatever they want.
|
||||
|
||||
Using a custom context field called _region_ as an example: if you define the field's legal values as _Africa_, _Asia_, _Europe_, and _North America_, then you would only be allowed to use one or more of those four values when using the custom context field as a [strategy constraint](../advanced/strategy-constraints.md).
|
||||
|
||||
|
||||
|
||||
### Custom stickiness
|
||||
|
||||
:::note
|
||||
This feature is currently in beta and is not yet supported by all our SDKs. Check out the [SDK compatibility table](../sdks/index.md#server-side-sdk-compatibility-table) to see what SDKs support it at the moment.
|
||||
:::
|
||||
|
||||
Any context field _can_ be used to [calculate custom stickiness](../advanced/stickiness.md#custom-stickiness). However, you need to explicitly tell Unleash that you want a field to be used for custom stickiness for it to be possible. You can enable this functionality either when you create the context field or at any later point. For steps on how to do this, see [the _How to define custom context fields_ guide](../how-to/how-to-define-custom-context-fields).
|
||||
|
||||
|
||||
|
||||
[^1]: If you're on Unleash 4.3 or higher, you'll probably want to use [the environments feature](../user_guide/environments.md) instead of relying on the `environment` context field when working with environments.
|
||||
|
||||
@ -68,6 +68,10 @@ module.exports = {
|
||||
],
|
||||
'Topic guides': [
|
||||
'topics/a-b-testing'
|
||||
],
|
||||
"How-to guides": [
|
||||
"how-to/how-to-add-strategy-constraints",
|
||||
"how-to/how-to-define-custom-context-fields",
|
||||
]
|
||||
},
|
||||
api: {
|
||||
|
||||
BIN
website/static/img/constraints-add-additional.png
Normal file
BIN
website/static/img/constraints-add-additional.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 167 KiB |
BIN
website/static/img/context-field-create-button.png
Normal file
BIN
website/static/img/context-field-create-button.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 248 KiB |
Loading…
Reference in New Issue
Block a user