Skip to content
This repository was archived by the owner on Apr 14, 2023. It is now read-only.

Adding details on context and merging #110

Merged
merged 3 commits into from
Sep 8, 2022
Merged

Adding details on context and merging #110

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fe7c0b3
Adding details on context and merging
toddbaert Sep 8, 2022
fbb35a6
fix capitalization
toddbaert Sep 8, 2022
e74351c
Add provider links
toddbaert Sep 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 55 additions & 10 deletions docs/reference/concepts/03-evaluation-context.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,26 @@ 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.
The [_evaluation context_](/docs/specification/glossary#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

<!-- TODO: add doc about evaluation context merging (global, client) once it's spec'd -->

Values relevant for flag evaluation can be included in the evaluation context.
Values relevant for flag evaluation can be included in the evaluation context at multiple points: globally (on the top level API), on the client, and at the point of flag evaluation (invocation).

<Tabs groupId="code">
<TabItem value="js" label="TypeScript">

```ts
// add a value to the global context
OpenFeature.context = { myGlobalKey: 'myGlobalValue' }

// add a value to the client context
const client = OpenFeature.getClient();
client.context = { myClientKey: 'myClientValue' }

// add a value to the invocation context
const context: EvaluationContext = {
myKey: 'myValue',
myInvocationKey: 'myInvocationValue',
};
const boolValue = await client.getBooleanValue('boolFlag', false, context);
```
Expand All @@ -31,30 +36,62 @@ const boolValue = await client.getBooleanValue('boolFlag', false, context);
<TabItem value="java" label="Java">

```java
// add a value to the global context
OpenFeatureAPI api = OpenFeatureAPI.getInstance();
api.setEvaluationContext(new EvaluationContext().add("myGlobalKey", "myGlobalValue"));

// add a value to the client context
Client client = api.getClient();
client.setEvaluationContext(new EvaluationContext().add("myClientKey", "myClientValue"));

// add a value to the invocation context
EvaluationContext context = new EvaluationContext();
context.addStringAttribute("myKey", "myValue")
context.addStringAttribute("myInvocationKey", "myInvocationValue")
Boolean boolValue = client.getBooleanValue("boolFlag", false, context);
```

</TabItem>
<TabItem value="csharp" label="C#">

```csharp
// add a value to the global context
OpenFeature api = OpenFeature.Instance;
api.SetContext(new EvaluationContext().Add("myGlobalKey", "myGlobalValue"));

// add a value to the client context
FeatureClient client = api.GetClient();
api.SetContext(new EvaluationContext().Add("myClientKey", "myClientValue"));

// add a value to the invocation context
var context = new EvaluationContext();
context.Add("myKey", "myValue");
context.Add("myInvocationKey", "myInvocationValue");
var boolValue = await client.GetBooleanValue("boolFlag", false, context);
```

</TabItem>
<TabItem value="go" label="Go">

```go

// add a value to the global context
SetEvaluationContext(EvaluationContext{
Attributes: map[string]interface{}{
"myGlobalKey": "myGlobalValue",
},
})

// add a value to the client context
client := NewClient("my-app")
client.SetEvaluationContext(EvaluationContext{
Attributes: map[string]interface{}{
"myClientKey": "myClientValue",
},
})

// add a value to the invocation context
ctx := openfeature.EvaluationContext{
Attributes: map[string]interface{}{
"myKey": "myValue",
"myInvocationKey": "myInvocationValue",
},
}
boolValue, err := client.BooleanValue("boolFlag", false, ctx, openfeature.EvaluationOptions{})
Expand All @@ -63,10 +100,18 @@ boolValue, err := client.BooleanValue("boolFlag", false, ctx, openfeature.Evalua
</TabItem>
</Tabs>

### Context merging

At the point of flag evaluation, the evaluation context is merged, and duplicate values are overwritten as defined in the [specification](/docs/specification/sections/evaluation-context#merging-context).

### Circular structures in Evaluation Context

Many providers serialize the evaluation context as part of their operation. Be careful not to include circular structures in the evaluation context to avoid serialization issues.

## 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 <!--TODO: add provider link -->may require this field to be set to function correctly.
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](/docs/reference/concepts/provider) 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 <!--TODO: add provider link -->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](/docs/reference/concepts/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`.