Migrate from uMarketingSuite

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.

1. Execute the prerequisites check using the following query:

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

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

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

Step 5: Update the database

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:

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.

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
  }
}

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>"
    }
  }
}

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.

Custom firewall changes

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

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.