Feature Flag Migration Playbook by mintlify[bot] · Pull Request #95 · mixpanel/docs

mintlify · 2026-07-14T14:24:56Z

Summary

This update introduces a new guide for migrating feature flags and experiments from other platforms to Mixpanel. It outlines a five-part process to ensure a smooth transition, covering exposure events, configurations, and verification.

Changes

Added guides/strategic-playbooks/feature-flag-migration-playbook.mdx.
Included new images: images/FeatureFlagSetup.png, images/ExperimentSetup.png, and images/ExperimentSetupMetrics.png.
Integrated the new playbook into the docs.json navigation structure.

Mintlify

10 threads from 1 user in Mintlify

guides/strategic-playbooks/feature-flag-migration-playbook.mdx
- Russell Loube: "feature gate" here instead, since these are all flag types view comment
- Russell Loube: Main risk IMO is that it's impossible for us to maintain the same variant assignment for visitors in the third-party ... view comment
- Russell Loube: Would be good to link to [https://docs.mixpanel.com/docs/experiments#implementation-for-experimentation](https://docs... view comment
- Russell Loube: Looks like they do have dynamic configs as well: [https://docs.growthbook.io/features/configs](https://docs.growthboo... view comment
- Russell Loube: They released ability to track decisions events for "Targeted Deliveries" (non-experiment rollouts, optionally with f... view comment
- Russell Loube: You can add "variables" to your flag in Optimizely and define data types, including JSON: [https://support.optimizely... view comment
- Russell Loube: Since "key" is a loaded term, would recc rewording this view comment
- Russell Loube: Would be great to also link to relevant API doc pages for more details: [https://docs.mixpanel.com/reference/overview... view comment
- Russell Loube: Would change to "will result" b/c there's no way we could maintain variant assignments Every vendor uses some hashing... view comment
- Russell Loube: IMO it'd be good to add link to our MCP server with commentary that it can help with flag implementation. LLM with ou... view comment

- Updated docs/what-is-mixpanel.mdx - Created images/FeatureFlagSetup.png - Created images/ExperimentSetup.png - Created images/ExperimentSetupMetrics.png - Created guides/strategic-playbooks/feature-flag-migration-playbook.mdx - Updated docs.json Mintlify-Source: dashboard-editor

kurbycchua

Overall comment is we need to make sure we fact check these as we do not want a customer ending up in messing up their experiment / FF data in mixpanel. Migrating the exposure of $experiment_started I find it the easy part, the challenging part is the Experiment report and the FF report of which underlying drives the analysis and the gates

- Updated docs/what-is-mixpanel.mdx - Updated guides/strategic-playbooks/feature-flag-migration-playbook.mdx Mintlify-Source: dashboard-editor

- Updated guides/strategic-playbooks/feature-flag-migration-playbook.mdx Mintlify-Source: dashboard-editor

kurbycchua · 2026-07-17T03:37:05Z

                      "guides/strategic-playbooks/onboarding-playbook/beyond-onboarding"
                    ]
                  },
+                  "guides/strategic-playbooks/feature-flag-migration-playbook",


@amymadden-bit more of a nitpick on this... depending on how we want to position this the actual content has a title of "Migrating Your Feature Flags and Experiments to Mixpanel" but the menu says "Feature Flag Migration Playbook" Also since the content is also covering feature flag that are NOT related to experiments - that's another angle to consider.

@kurbycchua fair point, it's a bit long but I updated to "Feature Flag & Experiments Migration Playbook" (I think.... I did it in mintlify so hopefully it pulled over)

- Updated guides/strategic-playbooks/feature-flag-migration-playbook.mdx Mintlify-Source: dashboard-editor

kurbycchua · 2026-07-20T08:35:39Z

+
+## Step 1. Migrate past experiment exposure events
+
+An exposure event records that a user was enrolled in an experiment, and was bucketed into an experiment variant. To keep your historical data, export your existing exposure events from your current vendor and ingest them to Mixpanel as `$experiment_started` events. 


@xinlintanmp @amymadden-bit nitpick: This statement "An exposure event records that a user was enrolled in an experiment, and was bucketed into an experiment variant." might imply to readers that exposure events (ie feature gate, dynamic config) not related to experiments need not be migrated.

kurbycchua · 2026-07-20T08:37:15Z

+sidebarTitle: "Feature Flag & Experiments Migration Playbook"
+---
+
+This guide walks through migrating your feature flags and experiments to Mixpanel from another platform. It's for teams currently running flags and experiments on a third-party vendor who want to consolidate that work in Mixpanel instead.


@amymadden-bit does this read better: This guide walks through migrating your feature flags and experiments hosted in another platform into Mixpanel.

As Customer Education we should envision to review para / sentences to help easy reading, an idea for a claude skill perhaps?

kurbycchua · 2026-07-20T08:41:13Z

+
+### Export exposure events from your vendor
+
+Most vendors have a dedicated exposure event you can export. You can usually export them directly from the UI or by using the vendor API.


@xinlintanmp @amymadden-bit We should state that Mixpanel minimally requires these 4 information for an exposure event?

kurbycchua · 2026-07-20T08:42:35Z

+
+#### E**quivalent events**
+
+Each vendor's exposure event corresponds to a different Mixpanel event depending on whether it came from a feature gate, an experiment, or a dynamic config. Use this table to find the equivalent for your setup:


@xinlintanmp @amymadden-bit so are we saying here "corresponds to a different Mixpanel event" that there are different exposure events on Mixpanel side? Can be confusing perhaps?

Should we just say "Each vendor has its own definition of exposure event and they can be mapped to Mixpanel's exposure event depending on the Mixpanel Feature Flag type (i.e., feature gate, an experiment, or a dynamic config)

kurbycchua · 2026-07-20T09:00:14Z

+By the end of this, your flags and experiments will be set up in Mixpanel, your historical results will carry over, and your application code will be evaluating flags through Mixpanel rather than your old provider.
+
+<Note>
+  This guide is a reusable template. The steps below are vendor-agnostic. To migrate from a provider (Statsig, LaunchDarkly, Optimizely, Firebase Remote Config, VWO, GrowthBook, or any OpenFeature setup), substitute that vendor's export API in each "Export" step — the Mixpanel side stays the same.


@xinlintanmp @amymadden-bit Don't think we covered Firebase Remote Config, VWO although it is mentioned here

kurbycchua · 2026-07-20T09:29:26Z

+
+Each vendor's exposure event corresponds to a different Mixpanel event depending on whether it came from a feature gate, an experiment, or a dynamic config. Use this table to find the equivalent for your setup:
+
+| Mixpanel Feature Flag Type | Statsig Equivalent | LaunchDarkly Equivalent | Optimizely Equivalent | GrowthBook Equivalent |


@xinlintanmp In all honesty this table with the exception of Statsig is quite confusing to me, but since unless I try to validate where this is coming from I have no way of knowing their correctness.

Example what are we saying in the following
For LaunchDarkly

feature event within Experiment=true (streaming); evaluation_events rows with experiment_iteration_id (warehouse)

feature event (boolean flag eval)

feature event (multivariate/JSON flag eval)

I use Gemini in an attempt to try to understand what these are saying, linking here for reference:
-Statsig: https://docs.statsig.com/integrations/event_webhook#event-format
-LaunchDarkly: https://launchdarkly.com/docs/integrations/data-export/warehouse-schema-reference#evaluation-events and https://launchdarkly.com/docs/integrations/data-export/schema-reference#feature-events

Optimizely: https://docs.developers.optimizely.com/experimentation-data/docs/event-api-getting-started#activate-users

GrowthBook: https://docs.growthbook.io/app/event-forwarder#experiment-view-events

kurbycchua · 2026-07-20T09:31:15Z

+
+Transform each exported exposure row into a Mixpanel `$experiment_started` event and send it through the **Mixpanel Import API**.
+
+The two required properties are **Experiment name** and **Variant name**. Keep the original exposure timestamp so historical analysis is accurate, and include a unique `$insert_id` so re-runs don't create duplicates.


@xinlintanmp @amymadden-bit this can be confusing: Under "
Export exposure events from your vendor" we list 4 bullets and here we say "The two required properties are Experiment name and Variant name" which means distinct_id, timestamp, $insert_id can be optional? We need to make sure we are careful with how to word things in a playbook

kurbycchua · 2026-07-20T09:31:40Z

+	"properties": {
+		"distinct_id": "alice@example.com", // enrollment ID
+		"time": 1709275888, // Timestamp
+		"$insert_id": "exp_4821_alice_1709275888",


@xinlintanmp maybe a comment like //prevent re-run duplicates

kurbycchua · 2026-07-20T09:33:02Z

+
+### Export configurations from your vendor
+
+Use your vendor's management API to export each configuration. Ensure you list and fetch definitions for feature gates, experiments, and dynamic configurations. 


@xinlintanmp @amymadden-bit Are we sure that all vendors can provide "management API to export each configuration."

kurbycchua · 2026-07-20T09:39:56Z

+  "status": "enabled",
+  "data_group_id": null,
+  "serving_method": "client",
+  "experiment_id": 12345,


@xinlintanmp @amymadden-bit We didn't really explain these? My guess is they should be tied to the id returned when creating the experiment? This is why I think it's important to have an engineer review these examples?

experiment_id

is_experiment_active

kurbycchua · 2026-07-20T09:46:30Z

+}
+```
+
+## Step 3. Continue setup in the Mixpanel UI


@xinlintanmp @amymadden-bit I personally feel this section is confusing, we suddenly jump to the UI without linking how those API calls from the previous section are related to this section. Example

Do I search for the experiment that I created using the API and then do the UI configuration - unclear if I am someone reading this that has no idea yet how MIxpanel UI for experiments + FF works

This "Once you have imported the $experiment_started events into Mixpanel, you need to create a corresponding Mixpanel Experiment report" Didn't I create an Experiment and FF already using API does this mean I am creating another duplicate?

kurbycchua

See additional comments, I have resolved those that were updated. This is a more detailed read from me and I literally took a longer time trying to push my shoes into someone who is reading this for the first time and trying to figure out how to migrate. It's a good start but I feel it needs more meet to be a playbook

mintlify Bot requested review from a team as code owners July 14, 2026 14:24

mintlify Bot requested review from caracheng and hywel-mixpanel July 14, 2026 14:24

mintlify Bot deployed to staging July 14, 2026 14:27 View deployment

hywel-mixpanel requested changes Jul 14, 2026

View reviewed changes

Comment thread docs/what-is-mixpanel.mdx

re-add buttons

5dad299

mintlify Bot deployed to staging July 14, 2026 19:26 View deployment

hywel-mixpanel approved these changes Jul 14, 2026

View reviewed changes

kurbycchua reviewed Jul 15, 2026

View reviewed changes

Merge branch 'main' into amymadden-ffmigration

e80d6d6

mintlify Bot deployed to staging July 15, 2026 06:53 View deployment

mintlify Bot added 2 commits July 16, 2026 10:04

Updated mintlify pages

35431c1

- Updated docs/what-is-mixpanel.mdx - Updated guides/strategic-playbooks/feature-flag-migration-playbook.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

63856b9

- Updated guides/strategic-playbooks/feature-flag-migration-playbook.mdx Mintlify-Source: dashboard-editor

mintlify Bot deployed to staging July 16, 2026 10:06 View deployment

mintlify Bot deployed to staging July 16, 2026 10:07 View deployment

Updated mintlify pages

f9595ef

- Updated guides/strategic-playbooks/feature-flag-migration-playbook.mdx Mintlify-Source: dashboard-editor

mintlify Bot deployed to staging July 17, 2026 02:17 View deployment

kurbycchua reviewed Jul 17, 2026

View reviewed changes

Comment thread guides/strategic-playbooks/feature-flag-migration-playbook.mdx Outdated

xinlintanmp added 2 commits July 17, 2026 16:36

Updated mintlify pages

f07f10a

- Updated guides/strategic-playbooks/feature-flag-migration-playbook.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

6026ebe

- Updated guides/strategic-playbooks/feature-flag-migration-playbook.mdx Mintlify-Source: dashboard-editor

mintlify Bot deployed to staging July 17, 2026 08:38 View deployment

mintlify Bot deployed to staging July 17, 2026 08:40 View deployment

Updated mintlify pages

53c3d34

- Updated guides/strategic-playbooks/feature-flag-migration-playbook.mdx Mintlify-Source: dashboard-editor

mintlify Bot deployed to staging July 17, 2026 08:42 View deployment

Updated mintlify pages

34018de

- Updated guides/strategic-playbooks/feature-flag-migration-playbook.mdx Mintlify-Source: dashboard-editor

mintlify Bot deployed to staging July 17, 2026 14:59 View deployment

kurbycchua reviewed Jul 20, 2026

View reviewed changes

Merge branch 'main' into amymadden-ffmigration

b9feae0

mintlify Bot deployed to staging July 20, 2026 09:57 View deployment


		## Step 1. Migrate past experiment exposure events

		An exposure event records that a user was enrolled in an experiment, and was bucketed into an experiment variant. To keep your historical data, export your existing exposure events from your current vendor and ingest them to Mixpanel as `$experiment_started` events.


		### Export exposure events from your vendor

		Most vendors have a dedicated exposure event you can export. You can usually export them directly from the UI or by using the vendor API.


		#### Equivalent events

		Each vendor's exposure event corresponds to a different Mixpanel event depending on whether it came from a feature gate, an experiment, or a dynamic config. Use this table to find the equivalent for your setup:


		Each vendor's exposure event corresponds to a different Mixpanel event depending on whether it came from a feature gate, an experiment, or a dynamic config. Use this table to find the equivalent for your setup:

		\| Mixpanel Feature Flag Type \| Statsig Equivalent \| LaunchDarkly Equivalent \| Optimizely Equivalent \| GrowthBook Equivalent \|


		Transform each exported exposure row into a Mixpanel `$experiment_started` event and send it through the Mixpanel Import API.

		The two required properties are Experiment name and Variant name. Keep the original exposure timestamp so historical analysis is accurate, and include a unique `$insert_id` so re-runs don't create duplicates.


		### Export configurations from your vendor

		Use your vendor's management API to export each configuration. Ensure you list and fetch definitions for feature gates, experiments, and dynamic configurations.

Uh oh!

Conversation

mintlify Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Mintlify

Uh oh!

Uh oh!

kurbycchua left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kurbycchua Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kurbycchua Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kurbycchua Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kurbycchua left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mintlify Bot commented Jul 14, 2026 •

edited

Loading

kurbycchua Jul 17, 2026 •

edited

Loading

kurbycchua Jul 20, 2026 •

edited

Loading

kurbycchua Jul 20, 2026 •

edited

Loading