docs(context): Update doc; add how-to make custom context fields.

website/docs/advanced/stickiness.md

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

website/docs/how-to/how-to-define-custom-context-fields.md

@@ -0,0 +1,41 @@
+---
+title: How to define custom context fields
+---
+
+
+## Constrain on custom context fields {#constrain-on-custom-context-fields}
+
+It is also possible to constrain an activation strategy configuration on custom context fields. A common use case is a multi-tenant service where you want to control roll-out on a tenant identifier. This allows you to decide which customer should get access to your new feature.
+
+![Custom constraints](/img/custom-constraints.png)
+
+## Define your own custom fields {#define-your-own-custom-fields}
+
+> Starting with Unleash-enterprise version 3.2.28 customers can define their custom context fields via the user interface.
+
+You can also define your own custom context fields that you can use together with strategy constraints. We have seen customers use multiple variants of custom context fields to control their feature roll-out:
+
+- region
+- country
+- customerType
+- tenantId
+
+Combining strategy constraints with the “flexibleRollout” allows you to do a gradual roll-out to a specific segment of your user base.
+
+#### Step 1: Navigate to “Context Fields“ {#step-1-navigate-to-context-fields}
+
+Locate “context fields in the menu
+
+![Context fields](/img/context-fields.png)
+
+#### Step 2: Define new context field {#step-2-define-new-context-field}
+
+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 the legal values.
+
+![New context fields](/img/new_context_field.png)
+
+#### What is “legal values”? {#what-is-legal-values}
+
+Legal values defines all possible values for the context field. this will be used in Unleash Admin UI to guide users when working with context fields to make sure they only use legal values.
+
+![New context fields](/img/constraints_legal_values.png)

website/docs/user_guide/unleash-context.md

@@ -3,24 +3,62 @@ 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 an Enterprise-only feature.
+:::
+
+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.
+
+Common custom context fields include _region_, _country_, _customerType_, and _tentantId_.
+
+See ["how to define custom context fields"](../how-to/how-to-define-custom-context-fields) for information on how you create your own custom context fields.
+
+### 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).
+
+[^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.

website/sidebars.js

@@ -68,6 +68,9 @@ module.exports = {
         ],
         'Topic guides': [
             'topics/a-b-testing'
+        ],
+        "How-to guides": [
+            "how-to/how-to-define-custom-context-fields"
         ]
     },
     api: {