GITBOOK-1: Engage 17 release notes

cornehoskam · gitbook-bot · commit d12bcdd5aff1 · 2025-11-28T10:15:29.000Z
diff --git a/17/umbraco-engage/release-notes.md b/17/umbraco-engage/release-notes.md
@@ -15,3 +15,17 @@ If you are upgrading to a new major version, check the breaking changes in the [
 ## Release History
 
 Below are the release notes for Umbraco Engage 17, detailing all changes in this version.
+
+#### [17.0.1](https://www.nuget.org/packages/Umbraco.Engage/17.0.1) (November 27th 2025)
+
+* Resolves a 500 Internal Server Error that occurred when creating or saving a new or existing A/B test.
+
+#### [Engage Forms 17.0.0](https://www.nuget.org/packages/Umbraco.Engage.Forms) (November 27th 2025)
+
+* Adds the ability to store a visitor's unique key instead of the numeric ID when using the **Analytics Visitor ID** Form Field.
+
+#### [17.0.0](https://www.nuget.org/packages/Umbraco.Engage/17.0.0) (November 27th 2025)
+
+The major release of Engage V17 is here, including support for Umbraco Forms and Commerce add-ons. This release also introduces Deploy support for Engage, making it easier to move your setup between environments. You can transfer configuration items such as segments, personas, journey steps, and goals, while analytics data remains safely in each environment.
+
+This release includes many automatic migrations and changes to the database structure. See [version-specific-upgrade-notes.md](upgrading/version-specific-upgrade-notes.md "mention")for more information.
diff --git a/17/umbraco-engage/tutorials/set-up-your-first-ab-test.md b/17/umbraco-engage/tutorials/set-up-your-first-ab-test.md
@@ -177,7 +177,7 @@ You can now edit the content item in split view. Only fields that have been conf
 3. Add an optional description to the variant.
 4. Add custom CSS and JavaScript.
 
-<figure><img src="../.gitbook/assets/engage-a-b-test-edit-variant-custom (2).png" alt=""><figcaption></figcaption></figure>
+<figure><img src="../.gitbook/assets/engage-a-b-test-edit-variant-custom (1).png" alt=""><figcaption></figcaption></figure>
 
 5. **Preview** the changes.
 6. **Save** the changes.
diff --git a/17/umbraco-engage/upgrading/migrate-from-umarketingsuite.md b/17/umbraco-engage/upgrading/migrate-from-umarketingsuite.md
@@ -7,18 +7,18 @@ description: >-
 # Migrate from uMarketingSuite
 
 {% hint style="warning" %}
-Since the latest version of uMarketingSuite runs on Umbraco 13, upgrading to Umbraco Engage involves two steps:&#x20;
+Since the latest version of uMarketingSuite runs on Umbraco 13, upgrading to Umbraco Engage involves two steps:
 
 1. **Migrate from uMarketingSuite to Umbraco Engage** (while still on Umbraco 13).
-2. **Upgrade Umbraco CMS and Umbraco Engage** from version 13 to version 16.
+2. **Upgrade Umbraco CMS and Umbraco Engage** from version 13 to version 17.
 
-**Important:** This migration guide does **not** cover the upgrade process from Umbraco 13 to 16. For guidance on upgrading Umbraco CMS, see the [Version Specific Upgrades](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/upgrading/version-specific#id-13.latest-to-the-latest-version) article in the Umbraco CMS Documentation.
+**Important:** This migration guide does **not** cover the upgrade process from Umbraco 13 to 17. For guidance on upgrading Umbraco CMS, see the [Version Specific Upgrades](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/upgrading/version-specific#id-13.latest-to-the-latest-version) article in the Umbraco CMS Documentation.
 {% endhint %}
 
-Migrating directly from uMarketingSuite on Umbraco 13 to Umbraco Engage on Umbraco 16 is technically possible. However, it is recommended to split the process:
+Migrating directly from uMarketingSuite on Umbraco 13 to Umbraco Engage on Umbraco 17 is technically possible. However, it is recommended to split the process:
 
-* First, use this guide to migrate from uMarketingSuite to Umbraco Engage while still on Umbraco 13.&#x20;
-* Then, upgrade both the CMS and the Engage package to version 16.
+* First, use this guide to migrate from uMarketingSuite to Umbraco Engage while still on Umbraco 13.
+* Then, upgrade both the CMS and the Engage package to version 17.
 
 {% hint style="warning" %}
 Upgrade to the latest version of uMarketingSuite before starting the migration.
@@ -198,8 +198,8 @@ You can find additional information on migrating the add-on packages for Umbraco
 <summary>UI Changes</summary>
 
 * The uMarketingSuite folder within `App_Plugins` has been renamed from `uMarketingSuite` to `Umbraco.Engage`. This folder is no longer stored on disk due to the use of the `Umbraco.Engage.StaticAssets` package.
-* The Umbraco Forms add-on folder within `App_Plugins` has been renamed from `uMarketingSuite.UmbracoForms` to `Umbraco.Engage.Forms`.  This folder is no longer stored on disk due to changes in version 16 of the `Umbraco.Engage.Forms` package.
-* The Cockpit Partial View has been moved from `Partials/uMarketingSuite/Cockpit` to `Partials/Umbraco.Engage/Cockpit`.  This file is no longer stored on disk due to the use of the `Umbraco.Engage.StaticAssets` package.
+* The Umbraco Forms add-on folder within `App_Plugins` has been renamed from `uMarketingSuite.UmbracoForms` to `Umbraco.Engage.Forms`. This folder is no longer stored on disk due to changes in version 16 of the `Umbraco.Engage.Forms` package.
+* The Cockpit Partial View has been moved from `Partials/uMarketingSuite/Cockpit` to `Partials/Umbraco.Engage/Cockpit`. This file is no longer stored on disk due to the use of the `Umbraco.Engage.StaticAssets` package.
 
 </details>
 
diff --git a/17/umbraco-engage/upgrading/version-specific-upgrade-notes.md b/17/umbraco-engage/upgrading/version-specific-upgrade-notes.md
@@ -13,3 +13,30 @@ When upgrading to a new minor or patch version, learn about the changes in the [
 {% endhint %}
 
 ## Breaking changes
+
+### 17.0.0 (Umbraco Engage v17 Launch)
+
+With the introduction of Engage version 17, breaking changes have been introduced to accommodate the transition between multiple major versions of the core CMS.
+
+#### Database Changes
+
+Three database structure changes have been introduced in the transition from Engage v16 to v17. The first is the migration to userKeys instead of userIds. All references to Umbraco users in Engage tables have now been updated to use the unique key of that user instead.
+
+The same applies to all references to Umbraco user groups in Engage tables. They have also been updated to use the unique key of that user group instead.
+
+The last update involves a change to the `[umbracoEngageAbTestingAbTestVariant]` table, which now contains a new column `[redirectNodeKey]` , which contains a NodeKey used for Split URL A/B Tests.
+
+#### Public Services
+
+Engage v17 introduces new overloads of public-facing service methods to allow the use of keys where previously numeric IDs were expected, resolving [issue #23](https://github.com/umbraco/Umbraco.Engage.Issues/issues/23). These overloads have been added to the following services:
+
+* IAbTestingVisitorService
+* IGoalService
+* IPersonaService
+* ICustomerJourneyService
+
+This means that these services work without the use of magic numbers that are environment-dependent, and instead allow for the use of a key that is shared between environments. This also marks the introduction of `Engage.Deploy` for Engage v17 to allow for the transferring of goals, personas, customer journeys, and A/B tests, adding even more use cases to these service changes.
+
+#### Nullability
+
+Engage v17 enables strict nullable reference types across all projects. This may cause compilation warnings/errors if you're extending or implementing Engage interfaces.&#x20;
