Skip to content

Commit ee4ae33

Browse files
guiwritehtessaro
guiwrite
and
htessaro
authored
docs: Managing Flags section (#5774)
Co-authored-by: htessaro <[email protected]>
1 parent e2fa4d4 commit ee4ae33

File tree

9 files changed

+479
-0
lines changed

9 files changed

+479
-0
lines changed

‎docs/docs/managing-flags/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Managing Flags",
3+
"position": 10
4+
}

‎docs/docs/managing-flags/core-management.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: Basic Flag Management
3+
sidebar_label: Basic Flag Management
4+
sidebar_position: 1
5+
---
6+
7+
Feature flags in Flagsmith are used to categorise and monitor user actions or events, such as detecting spam or abuse. This guide covers how to create, edit, clone, and delete flags in your project.
8+
9+
---
10+
11+
## Creating a Feature Flag
12+
13+
To create a new feature flag:
14+
15+
1. Go to the **Features** section in your dashboard.
16+
2. Click **Create Feature**.
17+
3. Enter a descriptive name for your flag (e.g., `new_ui_enabled`).
18+
4. Fill in the available fields according to the specifications of your feature. Note that these values are applied to all your [environments]. You can edit each environment individually later.
19+
- **Enabled by default**: determines the initial state of the flag for all environments. This can be edited for each environment later.
20+
- **Value** (optional): additionally to their boolean value, you can choose a format and a value for your flag.
21+
- **Tags** (optional): organise your flags by tags or add `protected` to prevent them from accidentally being deleted.
22+
- **Description** (optional): add a feature flag description.
23+
- **Server-side only**: enabling this prevents your flag from being accessed by client-side SDKs.
24+
5. Click **Create Feature**.
25+
26+
:::tip
27+
28+
By clicking the **Create A/B/n Test** button, you can define values for A/B testing. To learn more about this operation, refer to the [A/B Testing guide](../advanced-use/ab-testing).
29+
30+
:::
31+
32+
---
33+
34+
## Editing a Feature Flag
35+
36+
You create feature flags once per project, but you edit them within each environment. To edit an existing feature flag:
37+
38+
1. While on the **Environments** tab on the dashboard, use the dropdown to select the environment where you want to apply the changes.
39+
2. Locate the feature flag you want to edit and click on it. You can use the search bar to find the feature flag by its name.
40+
41+
:::tip
42+
43+
If you just want to toggle the feature flag *on* or *off*, use the switch under the **View** column in the list view.
44+
45+
:::
46+
47+
3. On the **Value** tab, you can set the feature flag to be on or off, as well as edit a value for it. Click **Update Feature Value** to save your changes.
48+
4. Optionally, create segment-specific feature flags and define **segment overrides**. Refer to the documentation to learn more about [segments](../basic-features/segments.md). Save any changes by clicking the **Update Segment Overrides** button.
49+
5. On the **Settings** tab, you can:
50+
- Add tags to your feature flag.
51+
- Assign it to specific *users* and *groups*.
52+
- Update the feature flag's description.
53+
- Mark the feature flag as **Server-side only** to prevent it from being accessed by client-side SDKs.
54+
- Set the **Archived** status to filter the feature flag as no longer relevant. Note that the feature flag will still be returned by the endpoint as before.
55+
Click **Update Settings** to save your changes.
56+
57+
:::tip
58+
59+
Changes made in the **Settings** tab affect all environments. Changes made in other tabs while editing a feature flag are valid only for the selected environment.
60+
61+
:::
62+
63+
---
64+
65+
## Deleting a Feature Flag
66+
67+
To delete a feature flag:
68+
69+
1. In the **Features** section, locate the feature flag you want to remove and click the **three dots** icon on the right.
70+
2. Select the **Remove feature** option.
71+
3. Type in the name of the feature flag to confirm the deletion.
72+
73+
:::caution
74+
75+
Deleting a feature flag is permanent and cannot be undone. Make sure your applications do not contain any reference to this feature flag before confirming deleting it.
76+
77+
:::
78+
79+
---
80+
81+
## Troubleshooting
82+
83+
### Feature Flags Not Updating
84+
85+
- Make sure you have saved your changes in each tab of the edit feature flag panel.
86+
- Check that you are in the correct project and environment.
87+
88+
### Permission Issues
89+
90+
- You may need additional permissions to create, edit, clone, or delete feature flags. If you see permission errors or options are disabled, contact your Flagsmith administrator to review your access rights. For more information, see the [Permissions and Roles](../system-administration/rbac.md) page.

‎docs/docs/managing-flags/manage-flags/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Manage Flags",
3+
"position": 10
4+
}

‎docs/docs/managing-flags/manage-flags/feature-health-metrics.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
title: Feature Health Metrics
3+
sidebar_label: Feature Health Metrics
4+
sidebar_position: 4
5+
---
6+
7+
Feature health enables you to monitor observability metrics within Flagsmith, specifically in relation to your features and environments. When your observability provider sends alert notifications, Flagsmith can mark features (and optionally environments) as **unhealthy**, providing details about the alerts. This assists your team in responding quickly and making informed decisions.
8+
9+
:::info
10+
11+
Feature Health is in Beta, please email [email protected] or chat with us <a href="#" class="open-chat" data-crisp-chat-message="Hello, I'm interested in joining the feature health beta.">here</a> if you'd like to join.
12+
13+
:::
14+
15+
## Prerequisites
16+
17+
- You must have a supported observability provider (see below).
18+
- You need admin access to your Flagsmith project settings.
19+
20+
---
21+
22+
## How to enable Feature Health
23+
24+
1. Go to your **Project Settings** in Flagsmith.
25+
2. Navigate to the **Feature Health** section.
26+
3. Choose your desired provider from the **Provider Name** drop-down menu (e.g., Grafana/Prometheus Alertmanager or Sample).
27+
4. Click **Create** and copy the webhook URL.
28+
29+
---
30+
31+
## How to integrate with Feature Health providers
32+
33+
### Grafana / Prometheus Alertmanager
34+
35+
[Learn more](/integrations/apm/grafana/#feature-health-provider-setup) about configuring Grafana / Prometheus Alertmanager feature health provider.
36+
37+
### Sample Provider
38+
39+
We provide a Sample Provider for your custom integrations. To create a Sample Feature Health webhook:
40+
41+
1. Go to Project Settings > Feature Health.
42+
2. Select "Sample" from the Provider Name drop-down menu.
43+
3. Click Create and copy the webhook URL.
44+
45+
You can use the webhook in your custom integration. Refer to the payload schema below:
46+
47+
```json
48+
{
49+
"$schema": "http://json-schema.org/draft-07/schema#",
50+
"title": "SampleEvent",
51+
"type": "object",
52+
"properties": {
53+
"environment": {
54+
"type": "string"
55+
},
56+
"feature": {
57+
"type": "string"
58+
},
59+
"status": {
60+
"type": "string",
61+
"enum": ["healthy", "unhealthy"]
62+
},
63+
"reason": {
64+
"$ref": "#/definitions/FeatureHealthEventReason"
65+
}
66+
},
67+
"required": ["feature", "status"],
68+
"definitions": {
69+
"FeatureHealthEventReason": {
70+
"type": "object",
71+
"properties": {
72+
"text_blocks": {
73+
"type": "array",
74+
"items": {
75+
"$ref": "#/definitions/FeatureHealthEventReasonTextBlock"
76+
}
77+
},
78+
"url_blocks": {
79+
"type": "array",
80+
"items": {
81+
"$ref": "#/definitions/FeatureHealthEventReasonUrlBlock"
82+
}
83+
}
84+
}
85+
},
86+
"FeatureHealthEventReasonTextBlock": {
87+
"type": "object",
88+
"properties": {
89+
"text": {
90+
"type": "string"
91+
},
92+
"title": {
93+
"type": "string"
94+
}
95+
},
96+
"required": ["text"]
97+
},
98+
"FeatureHealthEventReasonUrlBlock": {
99+
"type": "object",
100+
"properties": {
101+
"url": {
102+
"type": "string"
103+
},
104+
"title": {
105+
"type": "string"
106+
}
107+
},
108+
"required": ["url"]
109+
}
110+
}
111+
}
112+
```
113+
114+
---
115+
116+
## What's next?
117+
118+
- For more on observability integrations, see the [integrations documentation](/integrations/).
119+
- Need help or want to join the Beta? Contact [[email protected]](mailto:[email protected]) or chat with us in-app.

‎docs/docs/managing-flags/manage-flags/scheduled-flags.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: Scheduled Flags
3+
sidebar_label: Scheduled Flags
4+
sidebar_position: 3
5+
---
6+
7+
Scheduled flags allow you to queue and automatically apply changes to feature flags at a specified future time, eliminating the need for manual intervention at the exact moment of change. This page shows you how to schedule flag changes.
8+
9+
There are two methods for creating a scheduled feature flag change:
10+
11+
- As part of a change request.
12+
- Directly while editing a feature flag, if change requests are not enforced.
13+
14+
## Prerequisites
15+
16+
- To schedule feature flag changes with a change request, you must [have change requests enabled](../../advanced-use/change-requests.md) in your environment. This is not necessary to directly schedule changes when editing a flag.
17+
- Scheduled flags are available only for our **Scale-up** and **Enterprise** plans.
18+
19+
---
20+
21+
## How to create a Scheduled Flag change as part of a Change Request
22+
23+
1. Ensure your environment has change requests enabled.
24+
2. Attempt to change a feature flag value within the environment. You will be prompted to create a new change request.
25+
3. Fill in the following details:
26+
- The title of the change request
27+
- (Optional) A description of the reason for the change request
28+
- The date and time at which you want the feature flag change to take effect
29+
4. Submit the change request. The scheduled change will appear in the change request area as 'Pending'.
30+
31+
---
32+
33+
## How to create a stand-alone scheduled feature flag change
34+
35+
If change requests are not enabled for your environment, you can schedule a flag change directly:
36+
37+
1. In the Features list view, go to the feature flag you want to edit.
38+
2. Choose the new value or state for the feature flag.
39+
3. Click the **Schedule Update** button to set the date and time for the change to take effect.
40+
4. Save your changes. The scheduled change will be queued and applied automatically at the specified time.
41+
42+
---
43+
44+
## Scheduled Flags and Change Requests
45+
46+
Scheduled feature flags awaiting application will be listed in the change request area as 'Pending'.
47+
48+
Once the scheduled date and time have passed and the feature flag change has been applied, the scheduled feature flag will automatically move to the 'Closed' list in the change request area.
49+
50+
---
51+
52+
## What's next?
53+
54+
- To learn more about managing and approving changes to your feature flags, see the [change requests](../../advanced-use/change-requests.md) page.
55+
- To learn how to monitor the performance and health of your feature flags, see the [feature health metrics](./feature-health-metrics.md) page.

‎docs/docs/managing-flags/rollout/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Rollout",
3+
"position": 10
4+
}

‎docs/docs/managing-flags/rollout/rollout-by-attribute.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: Rollout by Attribute
3+
sidebar_label: Rollout by Attribute
4+
sidebar_position: 1
5+
---
6+
7+
This guide explains how to enable a feature for specific users based on their attributes (traits) in Flagsmith using segments and segment overrides. Attributes can include user role, subscription plan, application version, or device type.
8+
9+
## Prerequisites
10+
11+
- A Flagsmith project and environment.
12+
- A feature flag created in your project.
13+
- Your application's [Flagsmith SDK](../../clients/index.md) integrated and configured.
14+
15+
## Steps
16+
17+
### 1. Identify and Send User Traits
18+
19+
Ensure your application is identifying users and sending their relevant attributes (traits) to Flagsmith. For example, you might send traits like `plan`, `email`, `platform`, or `version` using your SDK:
20+
21+
```javascript
22+
flagsmith.identify('user_123');
23+
flagsmith.setTrait('plan', 'pro');
24+
flagsmith.setTrait('version', '5.4.1');
25+
```
26+
27+
### 2. Create a Segment Based on Attribute(s)
28+
29+
1. Go to the **Segments** section in the Flagsmith dashboard.
30+
2. Create a new segment and add rules that match the attribute(s) you want to target. For example:
31+
- `plan = pro`
32+
- `email Contains @yourcompany.com`
33+
- `version SemVer >= 5.4.0`
34+
3. You can combine multiple rules for more precise targeting.
35+
36+
### 3. Apply a Segment Override to Your Feature Flag
37+
38+
1. In the environment where you want to apply the rollout, go to the **Features** section and select the feature flag you want to roll out.
39+
2. Navigate to the **Segment Overrides** tab.
40+
- Select the segment you created in the dropdown and set the desired feature flag state or value for users in that segment.
41+
- Save your changes.
42+
43+
Done! Now you can test with users who match (and don’t match) the segment to ensure the feature is enabled/disabled as expected.
44+
45+
---
46+
47+
## Advanced Use Cases
48+
49+
- You can combine attribute rules with a **% split** rule for staged rollouts (e.g., only 10% of "pro" users).
50+
- You can use operators such as `In`, `SemVer`, `Modulo`, etc., for more complex targeting.
51+
52+
---
53+
54+
## What's next
55+
56+
- Read the [segments documentation](../../basic-features/segments.md) to understand how they work and their relationship with overrides.
57+
- See the [staged feature rollouts guide](./rollout-by-percentage.md) to combine attribute rules with percentage-based rollouts for gradual releases.
58+
- Understand [managing identities](../../basic-features/managing-identities.md) to ensure consistent user identification and attribute management across your application.

0 commit comments

Comments
 (0)