Move how to create a feature flag

website/docs/feature-flag-tutorials/use-cases/how-to-create-feature-toggles.md

@@ -0,0 +1,51 @@
+---
+title: Create a feature flag
+description: 'This guide shows you how to create feature flags in Unleash and how to add constraints, segments, variants, and more.'
+slug: /how-to-create-feature-flag
+---
+
+[Feature flags](../reference/feature-toggles) are a foundational component of Unleash, enabling you to manage features dynamically. This guide details the process of creating and configuring feature flags within Unleash. You'll learn how to create flags, define activation strategies, enable them, and optionally refine their behavior with constraints, segments, and variants.
+
+This guide focuses on the Unleash Admin UI, but you can also use the [Admin API](/reference/api/unleash/create-feature) to create, update, and manage feature flags.
+
+## Create a feature flag
+
+To create a feature flag in the Admin UI, do the following:
+
+1. Go to a project and click **Create feature flag**.
+2. Enter a unique name for the flag and click **Create feature flag**.
+
+## Add an activation strategy
+
+[Activation strategies](/reference/activation-strategies) determine how and for whom a feature flag is enabled within a specific environment (for example, development, or production). To add an activation strategy to your feature flag in the Admin UI, do the following:
+
+1. Go to a feature flag, and select the [environment](/reference/environment) where you want to configure the flag.
+2. Click **Add strategy** for that environment.
+3. In the **General** tab, select your rollout percentage. Optionally, you can set the strategy status to **Inactive** if you don't yet want the strategy to be exposed.
+4. Click **Save strategy**.
+
+## Enable the feature flag in an environment
+
+To enable the feature flag in an environment, use the main environment toggle to enable the flag in the environment. This ensures that the feature flag is evaluated using the rules of its activation strategies and the provided [Unleash context](/reference/unleash-context).
+
+## Refine targeting with constraints and segments
+
+[Strategy constraints](/reference/activation-strategies#constraints) and [segments](../reference/segments) allow you to apply fine-grained filters to your activation strategies, ensuring they only activate for users and applications matching specific criteria. You can add constraints or segments when creating or editing an existing activation strategy.
+
+1. Go to the feature flag and the environment containing the strategy you want to modify and click the **Edit strategy**.
+2. In the Targeting Tab, click **Add constraint**.
+3. To define the constraint, add a context field, an operator, and values to compare against.
+4. Add more constraints if needed, and click **Save strategy**.
+
+[Segments](/reference/segments) work similarly to constraints, but they are a reusable set of constraints that you define once and can reuse across flags.
+
+### Configure strategy variants
+
+[Variants](../reference/feature-toggle-variants) give you the ability to further target your users and split them into groups of your choosing, such as for A/B testing.
+
+1. Go to the feature flag and the environment containing the strategy you want to modify and click the **Edit strategy**.
+2. In the **Variants** tab, click **Add variant**.
+3. Enter the variant name and an optional payload.
+4. Optionally, click **Add variant** again to add more variants.
+5. Toggle **Custom percentage** for fixed weights, if required.
+6. Click **Save strategy**.

website/docs/how-to/how-to-create-feature-toggles.md

@@ -1,144 +0,0 @@
----
-title: How to create a feature flag
-description: 'This guide shows you how to create feature flags in Unleash and how to add constraints, segments, variants, and more.'
-slug: /how-to-create-feature-flag
----
-
-[Feature flags](../reference/feature-toggles) 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 flags 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.
-
-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.
-
-This guide is split into three sections:
-
-1. [Prerequisites](#prerequisites): you need these before you can create a flag.
-2. [Required steps](#required-steps): all the required steps to create a flag and activate it in production.
-3. [Optional steps](#optional-steps): optional steps you can take to further target and configure your feature flag and its audience.
-
-## Prerequisites
-
-To perform all the steps in this guide, you will need:
-
-- A running Unleash instance
-- A project to hold the flag
-- A user with an **editor** or **admin** role OR a user with the following permissions inside the target project:
-  - **[project-level permissions](../reference/rbac#project-permissions)**
-    - create feature flags
-  - **[environment-level permissions](../reference/rbac#environment-permissions)**
-    - create/edit variants[^1]
-    - create activation strategies
-    - update activation strategies
-    - enable/disable flags
-
-:::info roles
-
-Refer to [the documentation on role-based access control](../reference/rbac) for more information about the available roles and their permissions.
-
-:::
-
-## Required steps
-
-This section takes you through the required steps to create and activate a feature flag. It assumes that you have all the prerequisites from the previous section done.
-
-### Step 1: Create a flag {#step-1}
-
-:::tip API: create a flag
-
-Use the [Admin API endpoint for creating a feature flag](/reference/api/legacy/unleash/admin/features-v2#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.
-
-:::
-
-In the project that you want to create the flag in, use the "new feature flag" button and fill the form out with your desired configuration. Refer to the [feature flag reference documentation](../reference/feature-toggles) for the full list of configuration options and explanations.
-
-![](/img/create-toggle-new-toggle.png)
-
-### Step 2: Add a strategy {#step-2}
-
-:::tip API: Add a strategy
-
-Use the [API for adding a strategy to a feature flag](/reference/api/legacy/unleash/admin/features-v2#add-strategy). You can find the configuration options for each strategy in the [activation strategy reference documentation](../reference/activation-strategies).
-
-:::
-
-Decide which environment you want to enable the flag in. Select that environment and add an activation strategy. Different activation strategies will act differently as described in the [activation strategy documentation](../reference/activation-strategies). The configuration for each strategy differs accordingly. After selecting a strategy, complete the steps to configure it.
-
-![](/img/create-toggle-add-strategy.png)
-
-### Step 3: Enable the flag {#step-3}
-
-:::tip API: Enable a flag
-
-Use the [API for enabling an environment for a flag](/reference/api/legacy/unleash/admin/features-v2#enable-env) and specify the environment you'd like to enable.
-
-:::
-
-Use the environments flags to switch on the environment that you chose above. Depending on the activation strategy you added in the previous step, the flag should now evaluate to true or false depending on the Unleash context you provide it.
-
-![](/img/create-toggle-enable-env.png)
-
-## Optional steps
-
-These optional steps allow you to further configure your feature flags 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](../reference/activation-strategies#constraints) and [segments reference documentation](../reference/segments) for more information.
-
-To add constraints and segmentation, use the "edit strategy" button for the desired strategy.
-
-![](/img/create-toggle-edit-strategy.png)
-
-#### 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 flag or at any point thereafter.
-
-:::
-
-:::tip API: Add constraints
-
-You can either [add constraints when you add the strategy](/reference/api/unleash/add-feature-strategy) or [PUT](/reference/api/unleash/update-feature-strategy) or [PATCH](/reference/api/unleash/patch-feature-strategy) the strategy later.
-
-:::
-
-In the strategy configuration screen for the strategy that you want to configure, use the "add constraint" button to add a strategy constraint.
-
-![](/img/create-toggle-add-constraint.png)
-
-#### 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](/reference/api/unleash/update-feature-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.
-
-![](/img/create-toggle-add-segment.png)
-
-### Add variants
-
-:::info
-
-This can be done at any point after you've created your flag.
-
-:::
-
-:::tip API: add variants
-
-Use the [create variants endpoint](/reference/api/unleash/overwrite-feature-variants) to create or overwrite existing variants in all environments. The payload should be your desired variant configuration.
-
-:::
-
-[Variants](../reference/feature-toggle-variants) 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 flag overview page, select the variants tab. Use the "new variant" button to add the variants that you want.
-
-![](/img/create-toggle-add-variants.png)
-
-[^1]: Prior to Unleash 4.21, "create/edit variants" was a project-level permission instead of an environment-level permission.

website/docs/using-unleash/troubleshooting/flag-not-returned.md

@@ -7,8 +7,8 @@ By default, these endpoints will not return feature flags that are not enabled.
 The first thing to look into is to validate that the feature is well configured and then check the token used from the SDK because it determines the set of accessible features. Last, verify that the context you're providing contains all the required data.
 
 1. Check that the feature is properly enabled: 
-    1. Verify that the feature has a strategy associated to it that will return true for your context (ref: [add a strategy](/how-to-create-feature-flag#step-2))
-    2. Verify that the feature has been enabled in the environment used by the client application (ref: [enabling a feature flag](/how-to-create-feature-flag#step-3))
+    1. Verify that the feature has a strategy associated to it that will return true for your context (ref: [add a strategy](/reference/actication-strategies))
+    2. Verify that the feature has been enabled in the environment used by the client application (ref: [enabling a feature flag](/reference/feature-toggles))
 2. Check that your token is of the right [type](/reference/api-tokens-and-client-keys.mdx). To connect to the Frontend API, Edge or Proxy, you need to use a [Front-end token](/reference/api-tokens-and-client-keys#frontend-tokens)
 3. Check that your token has access to the feature flag. The **token access configuration is immutable post-creation** and defines the set of features that the token can access. The different [parts of a token](/reference/api-tokens-and-client-keys#api-token-format) determine what projects and environment can be accessed:
     1. **Access to all projects (current and future)** - Tokens with a leading asterisk will provide access to all projects in a particular environment. For example, the token `*:production:xyz123etc...` will provide access to flags in the production environment of all projects.

website/sidebars.ts

@@ -86,6 +86,10 @@ const sidebars: SidebarsConfig = {
                         id: 'feature-flag-tutorials/use-cases/gradual-rollout',
                     },
                     items: [
+                        {
+                            type: 'doc',
+                            id: 'feature-flag-tutorials/use-cases/how-to-create-feature-toggles',
+                        },
                         {
                             type: 'category',
                             label: 'Use Cases',
@@ -683,7 +687,6 @@ const sidebars: SidebarsConfig = {
                                 slug: '/how-to/misc',
                             },
                             items: [
-                                'how-to/how-to-create-feature-toggles',
                                 'how-to/how-to-schedule-feature-releases',
                                 'how-to/how-to-synchronize-unleash-instances',
                             ],