Migrate from uMarketingSuite

This guide provides a step-by-step approach to migrating a default uMarketingSuite solution to Umbraco Engage.

Upgrade to the latest version of uMarketingSuite before continuing with the migration.

You can upgrade your installation by installing the latest version on top of the existing one.

Tutorial Content

• Step 1: Set up a local environment

• Step 2: Prerequisites Check

• Step 3: Replace NuGet packages and dependencies

• Step 4: Update analytics scripts, cockpit, and custom code

• Step 5: Update the database

• Step 6: Finalizing the migration

• Step 7: Validate the migration

• Step 8: Upgrade additional environments

• Overview of the key changes in paths, scripts, namespaces, etc.

Step 1: Set up a local environment

The first step is to migrate from uMarketingSuite to Umbraco Engage in a local environment. This will be done using a copy of your production environment.

1. Backup your database from the production environment.

2. Restore the database locally.

Step 2: Prerequisites Check

In this step, you need to check the Database state to see if the existing data can be migrated to Umbraco Engage.

Are you using separate databases for uMarketingSuite and Umbraco? In that case, run the first group of checks on the Umbraco database and the second group of checks on the uMarketingSuite database.

1. Execute the prerequisites check using the following query:

5KB

Prerequisites-Checks.sql

Run this script on your locally restored database to prepare for the migration.

1. Verify that uMarketingSuite & uMarketingSuite addon version checks return the expected results.

2. Verify that the uMarketingSuite table integrity check returns the expected results.

If any of these checks return a failure, please resolve the issue before proceeding with the migration.

The result should look like this:

---Running Version Pre-Requisite Checks for uMarketingSuite to Umbraco Engage Migration---
✔️ Detected uMarketingSuite version 2.6.1 or higher
✔️ Detected uMarketingSuite.UmbracoCommerce version 2.0.0 or higher
✔️ Detected uMarketingSuite.UmbracoForms version 2.0.0 or higher
---Running Integrity Pre-Requisite Checks for uMarketingSuite to Umbraco Engage Migration---
✔️ The [uMarketingSuiteAnalyticsGoalCompletion] table is in a valid state to be upgraded.
✔️ The [uMarketingSuiteAnalyticsPageEvent] table is in a valid state to be upgraded.
---Finished running Pre-Requisite Checks. Please verify if all 5 checks succeeded before proceeding---

If any of these checks return a failure, please resolve the issue before proceeding with the migration.

Step 3: Replace NuGet packages and dependencies

In this second step, you will replace all existing uMarketingSuite dependencies with Umbraco Engage dependencies.

1. Make a backup of any custom implementation of uMarketingSuite-specific files you want to reuse.

2. Remove the installed uMarketingSuite package from your project

dotnet remove package uMarketingSuite

1. Remove the other uMarketingSuite packages (if applicable) from your project:

dotnet remove package uMarketingSuite.Headless
dotnet remove package uMarketingSuite.UmbracoForms
dotnet remove package uMarketingSuite.Commerce

1. Delete the App_Plugins\* folder for uMarketingSuite (and if applicable uMarketingSuite.UmbracoForms):

rmdir /s App_Plugins\uMarketingSuite
rmdir /s App_Plugins\uMarketingSuite.UmbracoForms

1. Delete the Assets\uMarketingSuite folder.

rmdir /s Assets\uMarketingSuite

1. Delete the Partials\uMarketingSuite folder.

rmdir /s Views\Partials\uMarketingSuite

1. Delete the existing license file in the config\uMarketingSuite folder.

2. Delete the existing appsettings-schema.uMarketingSuite.json file from the root of the project (if exists).

3. Install Umbraco.Engage:

dotnet add package Umbraco.Engage

1. Install any Umbraco Engage add-on packages that were previously removed.

dotnet add package Umbraco.Engage.Headless
dotnet add package Umbraco.Engage.Forms
dotnet add package Umbraco.Engage.Commerce

Step 4: Update analytics scripts, cockpit, and custom code

Based on the Key Changes below update all uMarketingSuite references to the new Umbraco Engage alternatives. Ensure you update any Views/Partials that also reference these. This includes the different uMarketingSuite clientside scripts (like the analytics & ga4-bridge) and the Cockpit.

Please find below an overview of the changes to the default scripts in a uMarketingSuite installation:

• Rename scripts & Asset Paths containing the uMarketingSuite keyword to:

  • Assets/Umbraco.Engage/Scripts/umbracoEngage.analytics.js

  • Assets/Umbraco.Engage/Scripts/umbracoEngage.ga4-bridge.js

  • Assets/Umbraco.Engage/Scripts/umbracoEngage.blockerdetection.js

• The Cockpit partial view has been moved, and any references should be changed to:

  • Partials/Umbraco.Engage/Cockpit

• If you are tracking custom events please make sure to update the calls to the send event method:

  • ums("send", "event", "<Category name>", "<Action>", "<Label>")

    is now:

    umbEngage("send", "event", "<Category name>", "<Action>", "<Label>")

Custom code

Did you build custom segments, add custom goal triggering, change the module permissions (cookie consent), or something similar? Check which namespaces, classes, and entities have been changed in the Key Changes section below.

Key changes

Below you will find the key changes to be aware of.

You can find additional information on migrating the add-on packages for UmbracoForms, Commerce & Headless in the Further Migrations section of this article.

Project, Package, and Namespace changes

uMarketingSuite	Umbraco Engage
uMarketingSuite.Core	Umbraco.Engage.Core
uMarketingSuite.Web	Umbraco.Engage.Web
uMarketingSuite.Business	Umbraco.Engage.Infrastructure
uMarketingSuite.Data	Umbraco.Engage.Data
uMarketingSuite.Common	Umbraco.Engage.Common
uMarketingSuite.UmbracoForms	Umbraco.Engage.Forms
uMarketingSuite.Headless	Umbraco.Engage.Headless
uMarketingSuite.Commerce	Umbraco.Engage.Commerce
uMarketingSuite	Umbraco.Engage

JavaScript changes

• The Asset Paths containing the uMarketingSuite keyword have renamed to Umbraco.Engage.

• The scripts containing the uMarketingSuite keyword have renamed to umbracoEngage.

  • Example: /Assets/uMarketingSuite/Scripts/uMarketingSuite.analytics.js is now /Assets/Umbraco.Engage/Scripts/umbracoEngage.analytics.js

• All script extension points containing the ums keyword have been renamed to umbEngage.

  • Example: Custom client-side events like ums("send", "event", "<Category name>", "<Action>", "<Label>") are now umbEngage("send", "event", "<Category name>", "<Action>", "<Label>")

UI Changes

• The uMarketingSuite folder within App_Plugins has been renamed from uMarketingSuite to Umbraco.Engage.

• The Umbraco Forms addon folder within App_Plugins has been renamed from uMarketingSuite.UmbracoForms to Umbraco.Engage.Forms.

• The Cockpit Partial View has been moved from Partials/uMarketingSuite/Cockpit to Partials/Umbraco.Engage/Cockpit.

Umbraco & Configuration Changes

• The Section and corresponding user permission uMarketingSuite has been renamed to Engage.

• The Media Folder uMarketingSuite has been renamed to Engage.

• The Data Types and corresponding Data Type Folder with the uMarketingSuite keyword have been renamed to Engage.

• The Segments for Content Variations (Personalization & A/B Testing) have been renamed from umarketingsuite to engage.

  • Using a new appsettings.json key existing installations can enable the legacy naming scheme to maintain compatibility with existing segments.

• The appsettings.json key uMarketingSuite has been renamed to Engage.

  • Example: uMarketingSuite:Settings:Enabled is now Engage:Settings:Enabled

C# Class changes

• Namespace changes as documented above.

• All classes containing the uMarketingSuite keyword are now updated to UmbracoEngage.

  • Examples: UMarketingSuiteApplicationComposer is now UmbracoEngageApplicationComposer, and AddMarketingApiDocumentation is now AddEngageApiDocumentation

Database changes

• All Database tables, keys, constraints and indexes containing the uMarketingSuite keyword are now updated to umbracoEngage.

  • Example: uMarketingSuiteAnalyticsPageview is now umbracoEngageAnalyticsPageview

Step 5: Update the database

Only proceed if all the prerequisites checks in Step 2 have passed.

In this step, you will update the database for Umbraco Engage.

1. Back up your database(s).

2. Rename the uMarketingSuite database tables, keys, constraints, and indexes using the following query:

42KB

Migrate-uMS-Tables.sql

Run this script on the database to rename all uMarketingSuite tables to Umbraco Engage.

These database changes should be executed in < 10 seconds as sp_rename is used and no existing data is touched.

1. Update the Umbraco database tables with the script below to rename the following uMarketingSuite properties:

   • The uMarketingSuite Media folder,

   • The uMarketingSuite Data Types & Data Type Folder,

   • The uMarketingSuite User Group Permissions,

   • The Migration State KeyValue State for uMarketingSuite, uMarketingSuite.UmbracoForms, and uMarketingSuite.UmbracoCommerce.

5KB

Migrate-Umbraco-Data.sql

Run this script to migrate all the Umbraco data.

1. Validate that no errors occurred and all tables were updated successfully. No queries should return that 0 rows were updated.

Step 6: Finalize the migration

1. Delete any obj/bin folders in your projects to ensure a clean build.

2. Recompile all projects and ensure all dependencies are restored correctly.

3. Contact Umbraco Support for a license key.

   • Look for the speech bubble in the bottom right corner of your screen at umbraco.com.

   • Click it, and you can open a new support request.

4. Add your new Umbraco Engage license key to the appSettings.json file:

"Umbraco": {
  "Licenses": {
    "Umbraco.Engage": "YOUR_LICENSE_KEY"
  }
}

1. Configure Umbraco Engage to use the legacy segment naming scheme:

"Engage": {
  "Settings": {
    "UseLegacySegmentNames": true
  }
}

The naming scheme for segments within content variations has changed from umarketingsuite to engage.

It is required to enable the UseLegacySegmentNames setting on all environments to maintain compatibility with existing segments. Without it, any personalization or A/B test created using uMarketingSuite will fail to work and become inaccessible and incompatible with the new naming scheme.

1. [Optional] Set the Engage:Analytics:VisitorCookie:LegacyCookieName configuration if uMarketingSuite was using a different visitor cookie name setting than the default uMarketingSuiteAnalyticsVisitorId:

"Engage": {
  "Analytics": {
    "VisitorCookie": {
      "LegacyCookieName": "<Your-Custom-uMarketingSuite-Visitor-Cookie>"
    }
  }
}

Umbraco Engage will automatically convert cookies previously set by uMarketingSuite to the new cookie name. This setting is only required if you have a custom cookie name set in uMarketingSuite. It will ensure a smooth transition in tracking existing visitors.

1. Run the project.

Step 7: Validate the migration

With the migration complete, there are a few more steps to ensure everything continues to work as expected.

1. Validate the new license:

   • Go to Settings -> Licenses in the backoffice and click Validate.

2. Generate the reporting data:

   • Go to Engage -> Settings -> Configuration in the backoffice and click the Regenerate button. Depending on the number of page views in the database this could take a while.

3. Use the Troubleshooting Installs guide to verify that everything works as expected.

Step 8: Upgrade additional environments

You have now verified that everything works as expected in the local environment. It is time to upgrade the production environment and any additional environments.

Repeat the steps below for each environment that needs to be migrated.

1. Stop the site.

2. Run the Prerequisites Check on the database.

3. Execute Step 5 on the database

4. Create a backup of the website.

5. Deploy the updated code from the migrated local environment.

6. Start the site.

7. Validate the new license, if this has not happened already:

   • Go to Settings -> Licenses in the backoffice and click Validate.

8. Generate the reporting data

   • Go to Engage -> Settings -> Configuration in the backoffice and click the Regenerate button. Depending on the number of page views in the database this could take a while.

9. Use the Troubleshooting Installs guide to verify that everything works as expected.

If the site is hosted on Umbraco Cloud, stopping and starting the site is not necessary.

Custom firewall changes

If the /umbraco/umarketingsuite/ path was previously allowed, this needs to change to /umbraco/engage/.

Are you having issues updating? Contact the support team via the chat on umbraco.com.

Further Migrations

uMarketingSuite.UmbracoForms

If you are using the uMarketingSuite.UmbracoForms package, all the submissions linked to visitors have been migrated using the scripts in Step 4.

Existing Forms, including those that use the uMarketingSuite-provided VisitorId field, do not require additional action.

You can install the Umbraco Engage UmbracoForms add-on package using the following command:

dotnet add package Umbraco.Engage.Forms

uMarketingSuite.Headless

If you are using the uMarketingSuite.Headless package, applications that use the uMarketingSuite API will need to be updated. This needs to happen to be able to use the new Umbraco Engage API, accessible via the /umbraco/engage/api/ routes.

The v1 Engage APIs (v13.0.0 of Umbraco Engage) maintain the same functionality as the v1 uMarketingSuite APIs. For more details on the API, please refer to the Swagger documentation provided by Umbraco Engage.

You can install the Umbraco Engage Headless add-on package using the following command:

dotnet add package Umbraco.Engage.Headless

uMarketingSuite.Commerce

If you are using the uMarketingSuite.Commerce package, all the commerce data has been migrated to Umbraco Engage using the scripts in Step 4.

You can install the Umbraco Engage Commerce addon package using the following command:

dotnet add package Umbraco.Engage.Commerce

uMarketingSuite.ContentBlocks

The uMarketingSuite.ContentBlocks add-on package has been deprecated since version 2.0.0 of uMarketingSuite and is unavailable for Umbraco Engage.