From 9497f83ed3097c3df3a2c74483b38240aae041b3 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Thu, 28 Jul 2022 13:37:16 -0400 Subject: [PATCH 1/3] Add evaluation context doc Signed-off-by: Todd Baert --- .../evaluation-context/evaluation-context.mdx | 59 +++++++++++++++++++ docs/reference/intro.md | 2 +- sidebars.js | 3 +- 3 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 docs/reference/evaluation-context/evaluation-context.mdx diff --git a/docs/reference/evaluation-context/evaluation-context.mdx b/docs/reference/evaluation-context/evaluation-context.mdx new file mode 100644 index 00000000..f596306f --- /dev/null +++ b/docs/reference/evaluation-context/evaluation-context.mdx @@ -0,0 +1,59 @@ +--- +sidebar_position: 1 +id: evaluation-context +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Evaluation Context + +The _evaluation context_ is a container for arbitrary contextual data that can be used as a basis for dynamic evaluation. Static data such as the host or an identifier for the application can be configured globally. Dynamic evaluation context, such as the IP address of the client in a web application, can be implicitly propagated or explicitly passed to during flag evaluation, and can be merged with static values. Many flag management systems support the definitions of targeting rules which allow for + +## Providing Evaluation Context + + + +Values relevant for flag evaluation can be included in the evaluation context. + + + + +```ts +// add a value to the invocation context +const context: EvaluationContext = { + myKey: 'myValue', +}; +const boolValue = await client.getBooleanValue('boolFlag', false, context); +``` + + + + +```java +// add a value to the invocation context +EvaluationContext context = new EvaluationContext(); +context.addStringAttribute("myKey", "myValue") +Boolean boolValue = client.getBooleanValue("boolFlag", false, context); +``` + + + + +```csharp +// add a value to the invocation context +var context = new EvaluationContext(); +context.Add("myKey", "myValue"); +var boolValue = await client.GetBooleanValue("boolFlag", false, context); +``` + + + + +## Targeting Key + +Many feature flag management systems require an identifier for the subject of flag evaluation. For many feature flag systems this is required in order to perform fractional evaluation or percentage-based rollouts deterministically. In the case of web applications or mobile apps, the subject is frequently an end user, but in other cases it could be a service or client application. The `evaluation context` includes an optional `targeting key` field for this purpose. The targeting key should contain a string uniquely identifying the subject (i.e.: a UUID, a hash of some user attribute such as an email, or a the hostname of an application or service). Some providers may require this field to be set to function correctly. + +## Personally Identifiable Information (PII) Considerations + +Be thoughtful in your inclusion of personal data in the `evaluation context`. Such data is useful for targeting and dynamic evaluation, but you should consider how the provider in use may handle or persist this data. Hooks (specifically hooks implementing the _before_ stage) can be useful to restrict, filter or anonymize data in the `evaluation context`. diff --git a/docs/reference/intro.md b/docs/reference/intro.md index 4b5262fd..f273d7ed 100644 --- a/docs/reference/intro.md +++ b/docs/reference/intro.md @@ -29,7 +29,7 @@ The [_evaluation API_](./evaluation-api/) is the aspect of OpenFeature that the ### Evaluation Context -The _evaluation context_ is a container for arbitrary contextual data that can be used as a basis for dynamic evaluation. Static data such as the host or an identifier for the application can be configured globally. Dynamic evaluation context, such as the IP address of the client in a web application, can be implicitly propagated or explicitly passed to during flag evaluation, and can be merged with static values. +The [_evaluation context_](./evaluation-context/) is a container for arbitrary contextual data that can be used as a basis for dynamic evaluation. Static data such as the host or an identifier for the application can be configured globally. Dynamic evaluation context, such as the IP address of the client in a web application, can be implicitly propagated or explicitly passed to during flag evaluation, and can be merged with static values. ### Providers diff --git a/sidebars.js b/sidebars.js index 1e0e52cb..0dec649f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -22,7 +22,8 @@ const sidebars = { items: [ 'reference/evaluation-api/evaluation-api', 'reference/using-open-feature-with-your-flag-system/implement-a-provider', - 'reference/hooks/hooks' + 'reference/hooks/hooks', + 'reference/evaluation-context/evaluation-context' ], }, ], From 5dfe70abada6132e408be25ba26aef8a6d4c81b8 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Thu, 28 Jul 2022 14:39:51 -0400 Subject: [PATCH 2/3] Update docs/reference/evaluation-context/evaluation-context.mdx Co-authored-by: Michael Beemer Signed-off-by: Todd Baert --- docs/reference/evaluation-context/evaluation-context.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/evaluation-context/evaluation-context.mdx b/docs/reference/evaluation-context/evaluation-context.mdx index f596306f..e0433392 100644 --- a/docs/reference/evaluation-context/evaluation-context.mdx +++ b/docs/reference/evaluation-context/evaluation-context.mdx @@ -56,4 +56,4 @@ Many feature flag management systems require an identifier for the subject of fl ## Personally Identifiable Information (PII) Considerations -Be thoughtful in your inclusion of personal data in the `evaluation context`. Such data is useful for targeting and dynamic evaluation, but you should consider how the provider in use may handle or persist this data. Hooks (specifically hooks implementing the _before_ stage) can be useful to restrict, filter or anonymize data in the `evaluation context`. +Be thoughtful in your inclusion of personal data in the `evaluation context`. Such data is useful for targeting and dynamic evaluation, but you should consider how the provider may handle or persist this data. Hooks (specifically hooks implementing the _before_ stage) can be useful to restrict, filter or anonymize data in the `evaluation context`. From 52c6ef45c6c0fd36f0b72c076c52b9eb1f763acb Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Thu, 28 Jul 2022 14:42:57 -0400 Subject: [PATCH 3/3] Fix final sentence Signed-off-by: Todd Baert --- docs/reference/evaluation-context/evaluation-context.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/evaluation-context/evaluation-context.mdx b/docs/reference/evaluation-context/evaluation-context.mdx index e0433392..1a01f825 100644 --- a/docs/reference/evaluation-context/evaluation-context.mdx +++ b/docs/reference/evaluation-context/evaluation-context.mdx @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem'; # Evaluation Context -The _evaluation context_ is a container for arbitrary contextual data that can be used as a basis for dynamic evaluation. Static data such as the host or an identifier for the application can be configured globally. Dynamic evaluation context, such as the IP address of the client in a web application, can be implicitly propagated or explicitly passed to during flag evaluation, and can be merged with static values. Many flag management systems support the definitions of targeting rules which allow for +The _evaluation context_ is a container for arbitrary contextual data that can be used as a basis for dynamic evaluation. Static data such as the host or an identifier for the application can be configured globally. Dynamic evaluation context, such as the IP address of the client in a web application, can be implicitly propagated or explicitly passed to during flag evaluation, and can be merged with static values. ## Providing Evaluation Context @@ -56,4 +56,4 @@ Many feature flag management systems require an identifier for the subject of fl ## Personally Identifiable Information (PII) Considerations -Be thoughtful in your inclusion of personal data in the `evaluation context`. Such data is useful for targeting and dynamic evaluation, but you should consider how the provider may handle or persist this data. Hooks (specifically hooks implementing the _before_ stage) can be useful to restrict, filter or anonymize data in the `evaluation context`. +Be thoughtful in your inclusion of personal data in the `evaluation context`. Such data is useful for targeting and dynamic evaluation, but you should consider how the provider in use may handle or persist this data. Hooks (specifically hooks implementing the _before_ stage) can be useful to restrict, filter or anonymize data in the `evaluation context`.