diff --git a/website/docs/reference/feature-toggles.mdx b/website/docs/reference/feature-toggles.mdx
new file mode 100644
index 0000000000..0c931f3b70
--- /dev/null
+++ b/website/docs/reference/feature-toggles.mdx
@@ -0,0 +1,39 @@
+---
+title: Feature Toggles
+---
+
+Feature toggles are the central concept that we built Unleash around. In Unleash, feature toggles are organized within [projects](../user_guide/projects.md). Feature toggles can have different [activation strategies](../user_guide/activation-strategies.md) for each of their project's [environments](../user_guide/environments.md), and can also be given [variants](../advanced/feature-toggle-variants.md) to facilitate A/B testing.
+
+## Configuration options
+
+Each feature toggle has the following configuration options
+
+| Option | Required? | Default value | Description |
+| --- | --- | --- | --- |
+| name | Yes | N/A | The feature toggle's name. Must be URL-friendly according to [section 2.3 of RFC 3986](https://www.rfc-editor.org/rfc/rfc3986#section-2.3) and must be unique within your Unleash instance. |
+| feature toggle type | Yes | Release | The [feature toggle's type](../advanced/feature-toggle-types.md). |
+| project | Yes | The [default project](../user_guide/projects.md#the-default-project). When created from a project page in the admin UI, that project will be the default value instead. | The [project](../user_guide/projects.md) that should contain the feature toggle. |
+| description | No | N/A | A description of the feature toggle's purpose. |
+| enable impression data | Yes | No | Whether to enable [impression data](../advanced/impression-data.md) for this toggle or not. |
+
+## Environments
+
+You probably won't want to use the same configuration to enable a toggle in development as you do in production. That's why feature toggles have different activation strategy configurations for each environment.
+
+You can enable and disable a toggle independently in each of the [project's environments](../user_guide/projects.md#projects-and-environments). When you disable a toggle in an environment, it will always evaluate to false in that environment. When you enable a toggle in an environment, the toggle will evaluate to true or false depending on its activation strategies.
+
+Refer to the [documentation on environments](../user_guide/environments.md) for more details on how environments work.
+
+## Activation strategies
+
+To enable a feature in an environment, you must assign it at least one activation strategy. A feature toggle's activation strategies determine whether the toggle gets enabled for a particular [Unleash context](../user_guide/unleash-context.md) (typically a user). When using multiple strategies in a single environment, only a single strategy needs to evaluate to true for the toggle to get enabled for a user. Whenever Unleash evaluates a toggle, it will evaluate strategies in the current environment until one of them resolves to true. If no strategies resolve to true, then the toggle's value is false.
+
+Refer to the [activation strategies documentation](../user_guide/activation-strategies.md) for a detailed description of all the built-in strategies.
+
+## Variants
+
+[Variants](../advanced/feature-toggle-variants.md) adds another dimension of flexibility to feature toggles. Each feature toggle can be assigned any number of variants which will then get distributed amongst your users based on your choice of [context field](../user_guide/unleash-context.md#structure). You can find out more about variants in the [variants docs](../advanced/feature-toggle-variants.md).
+
+### Creating toggles with payloads
+
+While variants are most often used for A/B testing and the like, you can also use variants to assign a constant payload to a toggle. If you give a toggle only a single variant and that variant has a payload, then all users variants will receive that payload.
diff --git a/website/docs/user_guide/create-feature-toggle.md b/website/docs/user_guide/create-feature-toggle.md
index ffcf4e560e..5c015da4f2 100644
--- a/website/docs/user_guide/create-feature-toggle.md
+++ b/website/docs/user_guide/create-feature-toggle.md
@@ -3,39 +3,141 @@ id: create_feature_toggle
title: How to create a feature toggle
---
-In this guide you will learn how to create your first feature toggle using Unleash.
+[Feature toggles](../reference/feature-toggles.mdx) are the foundation of Unleash. They are at the core of everything we do and are a fundamental building block in any feature management system. This guide shows you how to create feature toggles in Unleash and how to add any optional constraints, segments, variants, and more. Links to learn more about these concepts will be scattered throughout the text.
-## Step 1: Click the “create feature toggle” button {#step-1-click-the-create-feature-toggle-button}
+You can perform every action both via the UI and the admin API. This guide includes screenshots to highlight the relevant UI controls and links to the relevant API methods for each step.
-The first time you log-in to your Unleash instance you will see an empty list of feature toggles. In order to create a new feature toggle you have to click the “create feature toggle” button
+This guide is split into three sections:
+1. [Prerequisites](#prerequisites): you need these before you can create a toggle.
+2. [Required steps](#required-steps): all the required steps to create a toggle and activate it in production.
+3. [Optional steps](#optional-steps): optional steps you can take to further target and configure your feature toggle and its audience.
-
+## Prerequisites
-## Step 2: Create Feature toggle {#step-2-create-feature-toggle}
+To be able to create a feature toggle in an Unleash system you will need:
+- A running Unleash instance
+- A project to hold the toggle
+- A user with an **editor** or **admin** role OR a user with the following permissions inside the target project:
+ - create feature toggles
+ - create/edit variants
+ - create activation strategies (for the right environment)
+ - update activation strategies (for the right environment)
+ - enable/disable toggles (for the right environment)
-After clicking the “create feature toggle” button you will be presented with a form for creating a new feature toggle. You will need to define a few fields before you can actually complete the new feature toggle.
+:::info roles
-- **Name** – Must be unique across all your feature toggle. The name must also follow a URL friendly format. Can not be changed.
-- **Description** – A good description makes it easier for other members on your team to understand why this feature toggle exists.
-- **Enabled** – Whether the feature toggle should be enabled or disabled. If the feature toggle is disabled, activation strategy configurations will not be evaluated.
-- **Activation** strategies – A list of one or more activation strategies. An activation strategy is used to enable the feature toggle to a subset, or all, of your users.
+Refer to [the documentation on role-based access control](./rbac.md) for more information about the available roles and their permissions.
-In the example below we have chosen to not set up a strategy, which means that the standard strategy will be applied.
+:::
-
+## Required steps
-## Step 3: Congratulations, you have now created your first feature toggle! {#step-3-congratulations-you-have-now-created-your-first-feature-toggle}
+This section takes you through the required steps to create and activate a feature toggle. It assumes that you have all the prerequisites from the previous section done.
-The toggle is now created and ready to be used. The toggle does not have any metrics because it is not used by any applications, yet!
+### Step 1: Create a toggle {#step-1}
-
+:::tip API: create a toggle
-## Step 4: Enable the feature toggle only for your boss! {#step-4-enable-the-feature-toggle-only-for-your-boss}
+Use the [Admin API endpoint for creating a feature toggle](../api/admin/feature-toggles-api-v2.md#create-toggle). The payload accepts all the same fields as the Admin UI form. The Admin UI also displays the corresponding cURL command when you use the form.
-The next step is to change the activation strategy to only target your boss. You can use the “userIDs”-strategy for that. Using the configuration shown below will only enable the feature toggle for “boss@company.com” and “me@company.com”. Thus, you can safely test your feature in production, without exposing it to your users.
+:::
-
+In the project that you want to create the toggle in, use the "new feature toggle" button and fill the form out with your desired configuration. Refer to the [feature toggle reference documentation](../reference/feature-toggles.mdx) for the full list of configuration options and explanations.
-## Summary {#summary}
-In this guide you created your first feature toggle and enabled it for everyone. In later guides we will learn how we can reduce the risk by enabling the toggle for a controlled set of users first.
+
+
+### Step 2: Add a strategy {#step-2}
+
+:::tip API: Add a strategy
+
+Use the [API for adding a strategy to a feature toggle](../api/admin/feature-toggles-api-v2.md#add-strategy). You can find the configuration options for each strategy in the [activation strategy reference documentation](../user_guide/activation-strategies.md).
+
+:::
+
+Decide which environment you want to enable the toggle in. Select that environment and add an activation strategy. Different activation strategies will act differently as described in the [activation strategy documentation](../user_guide/activation-strategies.md). The configuration for each strategy differs accordingly. After selecting a strategy, complete the steps to configure it.
+
+
+
+### Step 3: Enable the toggle {#step-3}
+
+:::tip API: Enable a toggle
+
+Use the [API for enabling an environment for a toggle](../api/admin/feature-toggles-api-v2.md#enable-env) and specify the environment you'd like to enable.
+
+:::
+
+Use the environments toggles to switch on the environment that you chose above. Depending on the activation strategy you added in the previous step, the toggle should now evaluate to true or false depending on the Unleash context you provide it.
+
+
+
+## Optional steps
+
+These optional steps allow you to further configure your feature toggles to add optional payloads, variants for A/B testing, more detailed user targeting and exceptions/overrides.
+
+### Add constraints and segmentation
+
+
+Constraints and segmentation allow you to set filters on your strategies, so that they will only be evaluated for users and applications that match the specified preconditions. Refer to the [strategy constraints](../advanced/strategy-constraints.md "strategy constraints reference documentation") and [segments reference documentation](../reference/segments.mdx) for more information.
+
+To add constraints and segmentation, use the "edit strategy" button for the desired strategy.
+
+
+
+
+#### Constraints
+
+:::info
+
+Constraints aren't fixed and can be changed later to further narrow your audience. You can add them either when you add a strategy to a toggle or at any point thereafter.
+
+:::
+
+:::tip API: Add constraints
+
+You can either [add constraints when you add the strategy](../api/admin/feature-toggles-api-v2.md#add-strategy) or [PUT](../api/admin/feature-toggles-api-v2.md#update-strategy "PUT an activation strategy") or [PATCH the strategy afterwards](../api/admin/feature-toggles-api-v2.md#put-strategy)
+
+:::
+
+In the strategy configuration screen for the strategy that you want to configure, use the "add custom constraint" button to add a custom constraint.
+
+
+
+
+#### Segments
+
+:::info
+
+This can be done after you have created a strategy.
+
+:::
+
+:::tip API: add segments
+
+Use the [API for adding segments to a strategy](../api/admin/segments.mdx#replace-activation-strategy-segments) to add segments to your strategy.
+
+:::
+
+
+In the strategy configuration screen for the strategy that you want to configure, use the "select segments" dropdown to add segments.
+
+
+
+### Add variants
+:::info
+
+This can be done at any point after you've created your toggle.
+
+:::
+
+:::tip API: add variants
+
+
+Use the [update variants endpoint](../api/admin/feature-toggles-api-v2.md#update-variants). The payload should be your desired variant configuration.
+
+:::
+
+[Variants](../advanced/feature-toggle-variants.md) give you the ability to further target your users and split them into groups of your choosing, such as for A/B testing.
+On the toggle overview page, select the variants tab. Use the "new variant" button to add the variants that you want.
+
+
diff --git a/website/docs/user_guide/environments.md b/website/docs/user_guide/environments.md
index 35b721272c..cd5681dab4 100644
--- a/website/docs/user_guide/environments.md
+++ b/website/docs/user_guide/environments.md
@@ -8,7 +8,6 @@ title: Environments
-
@@ -23,10 +22,11 @@ Finally, metrics have also been upgraded to record the environment. This, in tur
Despite this being a shift in how Unleash works, everything will continue to work exactly how it did for existing users. For backwards compatibility, we have created an environment named "default" that will contain all of the existing toggles and API keys. Read more about that in [the migration section](#migration).
+
+## Global and project-level environments
-
-
+Environments exist on a global level, so they are available to all projects within Unleash. However, every [project](./projects.md) might not need to use every environment. That's why you can also choose which of the global environments should be available within a project.
## How to start using environments
@@ -42,30 +42,19 @@ Note that in order to enable an environment for a feature toggle, you must first
Navigate to the project and choose the “environments” tab.
-
-
-
-
-
+
### Step 2: Configure activation strategies for the new environment
From the “feature toggle view” you will now be able to configure activation strategies per environment. You can also enable and disable environments here. Remember that an environment must have activation strategies before you can enable it.
-
-
-
-
+
### Step 3: Create environment specific API keys
In order for the SDK to download the feature toggle configuration for the correct environment you will need to create an API token for a defined environment.
-
-
-
-
-
+
## Migration
@@ -73,12 +62,7 @@ To ease migration we have created a special environment called “default”. Al
If you're currently using strategy constraints together with the “environment” field on the Unleash Context, you should be aware that the new environment support works slightly differently. With environments, the SDK API will use the client's API key to determine which environment the client is configured for. The API then sends _only_ strategies belonging to the client's environment. This means that you might not need the "environment" property of the Unleash Context anymore.
-
-
-
-
-
-
+
### Addons
@@ -87,62 +71,48 @@ We have made some slight changes to events related to feature toggles: there's o
To avoid missing important updates, you will also need to update your addon configuration to subscribe to the new events.
**Deprecated events:**
-* **FEATURE_UPDATE** - _not used after switching to environments_
+
+- **FEATURE_UPDATE** - _not used after switching to environments_
**New Events**
-* **FEATURE-METADATA-UPDATED** - The feature toggle metadata was updated (across all environments).
-* **FEATURE-STRATEGY-ADD**¹ - An activation strategy was added to a feature toggle in an environment. The _data_ will contain the updated strategy configuration.
-* **FEATURE-STRATEGY-UPDATE**¹ - An activation strategy was updated for a feature toggle. The _data_ will contain the updated strategy configuration.
-* **FEATURE-STRATEGY-REMOVE**¹ - An activation strategy was removed for a feature toggle.
-* **FEATURE-ENVIRONMENT-ENABLED**¹ - Signals that a feature toggle has been _enabled_ in a defined environment.
-* **FEATURE-ENVIRONMENT-DISABLED**¹ - Signals that a feature toggle has been _disabled_ in a defined environment.
-* **FEATURE-PROJECT-CHANGE**¹ - The feature toggle was moved to a new project.
-> 1) These feature events will contain _project_ and _environment_ as part of the event metadata.
+- **FEATURE-METADATA-UPDATED** - The feature toggle metadata was updated (across all environments).
+- **FEATURE-STRATEGY-ADD**¹ - An activation strategy was added to a feature toggle in an environment. The _data_ will contain the updated strategy configuration.
+- **FEATURE-STRATEGY-UPDATE**¹ - An activation strategy was updated for a feature toggle. The _data_ will contain the updated strategy configuration.
+- **FEATURE-STRATEGY-REMOVE**¹ - An activation strategy was removed for a feature toggle.
+- **FEATURE-ENVIRONMENT-ENABLED**¹ - Signals that a feature toggle has been _enabled_ in a defined environment.
+- **FEATURE-ENVIRONMENT-DISABLED**¹ - Signals that a feature toggle has been _disabled_ in a defined environment.
+- **FEATURE-PROJECT-CHANGE**¹ - The feature toggle was moved to a new project.
+
+> 1. These feature events will contain _project_ and _environment_ as part of the event metadata.
### API
-
In order to support configuration per environment we had to rebuild our feature toggle admin API to account for environments as well. This means that we're making the following changes to the API:
-
-
-* **/api/admin/features** - _deprecated (scheduled for removal in Unleash v5.0). The [old feature toggles admin API](../api/admin/feature-toggles-api.md) still works, but strategy configuration will be assumed to target the “default” environment._
-* **/api/admin/projects/:projectId/features** - New feature API to be used for feature toggles which also adds support for environments. See [the documentation](../api/admin/feature-toggles-api-v2.md) to learn more.
-
+- **/api/admin/features** - _deprecated (scheduled for removal in Unleash v5.0). The [old feature toggles admin API](../api/admin/feature-toggles-api.md) still works, but strategy configuration will be assumed to target the “default” environment._
+- **/api/admin/projects/:projectId/features** - New feature API to be used for feature toggles which also adds support for environments. See [the documentation](../api/admin/feature-toggles-api-v2.md) to learn more.
## Plan Differences
-
### Open-Source (free)
-
-
-* Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments.
-* Will be possible to turn environments on/off for all projects.
-
+- Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments.
+- Will be possible to turn environments on/off for all projects.
### Pro (commercial)
-
-
-* Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments.
-* Will be possible to turn environments on/off for the default project.
-
+- Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments.
+- Will be possible to turn environments on/off for the default project.
### Enterprise (commercial)
-
-
-* Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments.
-* Will be possible to turn environments on/off for all projects
-* Will be allowed to update and remove environments.
-* Will be allowed to create new environments.
-
+- Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments.
+- Will be possible to turn environments on/off for all projects
+- Will be allowed to update and remove environments.
+- Will be allowed to create new environments.
## Rollout Plan
-
-
-* **Unleash v4.2** will provide _early access_ to environment support. This means that it can be enabled per customer via a feature flag.
-* **Unleash v4.3** plans to provide general access to the environment support for all users of Unleash (Open-Source, Pro, Enterprise).
+- **Unleash v4.2** will provide _early access_ to environment support. This means that it can be enabled per customer via a feature flag.
+- **Unleash v4.3** plans to provide general access to the environment support for all users of Unleash (Open-Source, Pro, Enterprise).
diff --git a/website/docs/user_guide/projects.md b/website/docs/user_guide/projects.md
index 9452dac02b..7d938aec5d 100644
--- a/website/docs/user_guide/projects.md
+++ b/website/docs/user_guide/projects.md
@@ -3,13 +3,17 @@ id: projects
title: Projects
---
-
- Projects are part of Unleash Pro and Unleash Enterprise.
-
+:::info feature availability
-## Overview {#overview}
+All users get access to projects, but only pro and enterprise users can create, update, or delete them.
-This topic explains how projects are supported in Unleash, how to create and maintain them.
+:::
+
+This document explains how Unleash uses projects, including how to create and maintain them.
+
+## The default project
+
+All users get access to the default project. You cannot delete this project. You can, however, rename it if you're using the pro or enterprise version of Unleash.
## Understanding purpose of projects {#understanding-purpose-of-projects}
@@ -17,7 +21,13 @@ Projects are a way to organize your feature toggles within Unleash. Within a lar
A common pattern is to organize the feature toggles according to key areas of the application, e.g. “Basic user process” and “Advanced user process”. This is illustrated below.
-
+
+
+## Projects and environments
+
+You can configure which [environments](./environments.md) should be available within a project. By default, all globally available environments are available. You can only enable/disable a feature toggle for the environments you configure for a project.
+
+Within the admin UI, the projects are available under the "environments" tab of the project page. Changing them requires the project owner role.
## Creating a new project {#creating-a-new-project}
@@ -25,15 +35,15 @@ When you log into Unleash for the first time, there is a Default project already
From the top-line menu – click on “Projects”
-
+
The available projects will now be listed. To create a new Project – choose the “Add new project”
-
+
The configuration of a new Project is now available. the following input is available to create the new Project.
-
+
| Item | Description |
| ------------ | ---------------------------------- |
@@ -44,14 +54,14 @@ The configuration of a new Project is now available. the following input is avai
## Deleting an existing project {#deleting-an-existing-project}
To keep your feature toggles clean, removing deprecated projects is important. From the overview of Projects –
-1. In the top right of the project card, find the project menu represented by three vertical dots.
+1. In the top right of the project card, find the project menu represented by three vertical dots.
2. Click on Delete Project
-
+
## Filter feature toggles on projects {#filter-feature-toggles-on-projects}
@@ -59,11 +69,11 @@ When browsing the feature toggles in Unleash, you might want to filter the view
From the UI top navigation menu, choose "Feature toggles".
-
+
The list of features toggles can be filtered on the project of your choice. By default, all feature toggles are listed in the view.
-
+
From the drop-down, chose the project to filter on.
@@ -75,11 +85,11 @@ The view will now be updated with the filtered feature toggles.
When you create a new feature toggle, you can choose which project to create it in. The default project is whatever project you are currently configuring.
-
+
All available projects are available from the drop-down menu.
-
+
## Change project for an existing feature toggle {#change-project-for-an-existing-feature-toggle}
diff --git a/website/sidebars.js b/website/sidebars.js
index 14f3a6fab1..44a7520bcf 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -266,6 +266,7 @@ module.exports = {
'advanced/impression-data',
'advanced/custom_activation_strategy',
'user_guide/environments',
+ 'reference/feature-toggles',
'advanced/feature_toggle_types',
'advanced/toggle_variants',
'user_guide/projects',
diff --git a/website/static/img/create-toggle-add-constraint.png b/website/static/img/create-toggle-add-constraint.png
new file mode 100644
index 0000000000..fbf57faf62
Binary files /dev/null and b/website/static/img/create-toggle-add-constraint.png differ
diff --git a/website/static/img/create-toggle-add-segment.png b/website/static/img/create-toggle-add-segment.png
new file mode 100644
index 0000000000..a0e0b24f96
Binary files /dev/null and b/website/static/img/create-toggle-add-segment.png differ
diff --git a/website/static/img/create-toggle-add-strategy.png b/website/static/img/create-toggle-add-strategy.png
new file mode 100644
index 0000000000..74900789b3
Binary files /dev/null and b/website/static/img/create-toggle-add-strategy.png differ
diff --git a/website/static/img/create-toggle-add-variants.png b/website/static/img/create-toggle-add-variants.png
new file mode 100644
index 0000000000..2fd9b41cc3
Binary files /dev/null and b/website/static/img/create-toggle-add-variants.png differ
diff --git a/website/static/img/create-toggle-edit-strategy.png b/website/static/img/create-toggle-edit-strategy.png
new file mode 100644
index 0000000000..57abd21fa0
Binary files /dev/null and b/website/static/img/create-toggle-edit-strategy.png differ
diff --git a/website/static/img/create-toggle-enable-env.png b/website/static/img/create-toggle-enable-env.png
new file mode 100644
index 0000000000..6f9c7cada5
Binary files /dev/null and b/website/static/img/create-toggle-enable-env.png differ
diff --git a/website/static/img/create-toggle-new-toggle.png b/website/static/img/create-toggle-new-toggle.png
new file mode 100644
index 0000000000..6d390e37fa
Binary files /dev/null and b/website/static/img/create-toggle-new-toggle.png differ
diff --git a/website/static/img/create_feature_toggle_button.png b/website/static/img/create_feature_toggle_button.png
deleted file mode 100644
index 9534bde7e2..0000000000
Binary files a/website/static/img/create_feature_toggle_button.png and /dev/null differ
diff --git a/website/static/img/create_feature_toggle_list.png b/website/static/img/create_feature_toggle_list.png
deleted file mode 100644
index db27d21859..0000000000
Binary files a/website/static/img/create_feature_toggle_list.png and /dev/null differ
diff --git a/website/static/img/create_feature_toggle_save.png b/website/static/img/create_feature_toggle_save.png
deleted file mode 100644
index 3bbab68a18..0000000000
Binary files a/website/static/img/create_feature_toggle_save.png and /dev/null differ
diff --git a/website/static/img/create_feature_toggle_userIds.png b/website/static/img/create_feature_toggle_userIds.png
deleted file mode 100644
index 874b743772..0000000000
Binary files a/website/static/img/create_feature_toggle_userIds.png and /dev/null differ