Upgrade to Optimizely Feature Experimentation from Optimizely Full Stack

Optimizely Feature Experimentation has been the default experience for projects and Free Rollouts accounts since its launch in February 2021. Feature Experimentation offers a simplified workflowworkflow, modelmodel, and APIAPI for experimenting with and delivering experiences to your end users. It also provides a significantly more performant editing and management experience when working with feature flags at scale. See Key concepts and differences in Feature ExperimentationKey concepts and differences in Feature Experimentation. 

You do not need to update your code to call the new Optimizely Feature Experimentation SDK methods. After your project is migrated, legacy SDK methods such as activate will still work. See Updated API methodsUpdated API methods in the Optimizely Feature Experimentation developer documentation for more.

You can migrate your existing Optimizely Full Stack Experimentation archived and unarchived legacy projects. Before migrating a legacy Full Stack project to Feature Experimentation, Optimizely scans your project to check for edge cases that might make it ineligible for migration. 

After migration, you should delete old bookmarked URLs to your Full Stack projects and experiments. Accessing these old projects and changing an already migrated Full Stack project will not be reflected in your new Feature Experimentation project.

The following sections list functionality available in Optimizely Full Stack Experimentation today but are not yet complete in Optimizely Feature Experimentation. These items are not technical blockers and do not prevent you from migrating to Feature Experimentation. If the functionality listed below is essential to your project, you may consider delaying your migration to Feature Experimentation:

If your legacy Full Stack Experimentation project contains a Feature Test with an off variation, the variations remain off in your migrated project. Having off variations does not block you from upgrading, but you should assess what to do with your off variations before migrating. To check:

In Optimizely Feature Experimentation, you no longer toggle feature test variations on and off. Instead, you can use the one default off variation across all rules. Because of this, you cannot turn the Off variation back On after migrating. However, you could try the following possible solutions:

If your Full Stack (Legacy) projects contain users with a restricted editor or restricted publisher role, they are migrated to the normal editor or publisher roles after migration. See Feature Experimentation collaborator rolesFeature Experimentation collaborator roles. 

To view your collaborators, go to Settings > Collaborators.

Optimizely Feature Experimentation has a new REST API that replaces a subset of the existing Optimizely API's functionality. If you currently manage the configuration of legacy Full Stack projects, features, or experiments using the REST API, you may need to update your code to use the Feature Experimentation API. Migrating before making required updates may result in broken functionality. See the following API reference documentation for information:

The following integrations are not completed yet:

If you upgrade to Optimizely Feature Experimentation now, you will lose the Jira and Salesforce integration functionality. See application and migrationapplication and migration information.

See also how existing experiment results are migratedhow existing experiment results are migrated before moving to Optimizely Feature Experimentation.

The following sections review the eligibility check and list steps to take if your project is ineligible to migrate. 

Your Full Stack project cannot upgrade to Optimizely Feature Experimentation if you use a version of the Java SDK before version 3.6 or Android SDK before version 3.7. 

Ask a developer to check which version of the SDK your project is using. The Java SDKJava SDK and Android SDKAndroid SDK versions are set in the project's build.gradle file. 

To address this scenario, update the Java SDK to version 3.6 or higher or Android SDK to version 3.7 or higher. The Java and Android SDKs are distributed through Maven Central. 

For information, see:

Your project cannot upgrade to Optimizely Feature Experimentation if your legacy Full Stack Experimentation project contains a single feature flag used in two (or more) separate feature tests with duplicate variable keys.

To check to see if your project is ineligible to migrate to Optimizely Feature Experimentation due to this scenario:

Example of ineligible setup

In the following example, there are two experiments:

The Full Stack project cannot be upgraded because the experiments:

Yellow button experiment

New homepage button

In Optimizely Feature Experimentation, variations are shared across rules in a flag, making it easy to reuse variations across your rules. This is a notable difference from the legacy Optimizely Full Stack Experimentation, where variations are scoped to a single Experiment. 

During a migration, if a feature is used in multiple feature tests, all feature tests become A/B test rules within the flag. Further, all of the variations from the feature tests become variations within the flag. Optimizely cannot migrate the variations while maintaining backward compatibility if the legacy feature tests have colliding variation keys.

With the Yellow Button experiment and the New homepage button, the two feature tests share the same variation keys. 

To resolve this issue, you can change the variation keys so that they are unique across features.

If your Optimizely Full Stack Experimentation project contains multiple rules per feature and the Everyone rule has its traffic allocation percentage set at any value except 0 or 100, you cannot migrate.

To check to see if your project is ineligible to migrate to Optimizely Feature Experimentation due to this scenario:

In Full Stack Experimentation, the default Everyone rule is evaluated last and has an adjustable traffic allocation.

Optimizely Feature Experimentation has a similar default rule that is evaluated last, but you only select a variation and do not set the traffic allocation. The remaining traffic is automatically delivered to the selected variation.  

Delivering Off variation in Feature Experimentation to remaining traffic

That difference in behavior means you cannot migrate feature flags in this state while maintaining backward compatibility. 

This happens because Optimizely went from N rules in Full Stack Experimentation to N+1 in Feature Experimentation. This is currently needed because Feature Experimentation does not let you control the traffic allocation on the last Everyone else rule, so Optimizely cannot map an Everyone targeted rollout rule to the Everyone else flags rule. Any targeted rollout features with a traffic value besides 0% or 100% for the Everyone rule will confront this issue.

To address this scenario, you can take the following action.

If your current Full Stack Experimentation project contains the following scenario, you cannot migrate your project to Optimizely Feature Experimentation. You must remove users from the allowlist to bring the user count to 50 or fewer.

To check to see if your project is ineligible to migrate to Optimizely Feature Experimentation due to this scenario:

In Optimizely Feature Experimentation, you are permitted to have 50 users added to the allowlist 50 users added to the allowlist. 

To address this scenario, remove users from the allowlist to bring the user count to 50 or fewer. 

If your current Full Stack Experimentation project contains a feature test with a variation named off, you cannot migrate.

To check to see if your project is ineligible to migrate to Optimizely Feature Experimentation due to this scenario:

To address this scenario, on the Variations tab: