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
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.
Backup your database from the production environment.
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.
Execute the prerequisites check using the following query:
Verify that uMarketingSuite & uMarketingSuite addon version checks return the expected results.
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:
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.
Make a backup of any custom implementation of uMarketingSuite-specific files you want to reuse.
Remove the installed uMarketingSuite package from your project
Remove the other uMarketingSuite packages (if applicable) from your project:
Delete the
App_Plugins\*
folder for uMarketingSuite (and if applicableuMarketingSuite.UmbracoForms
):
Delete the
Assets\uMarketingSuite
folder.
Delete the
Partials\uMarketingSuite
folder.
Delete the existing license file in the
config\uMarketingSuite
folder.Delete the existing
appsettings-schema.uMarketingSuite.json
file from the root of the project (if exists).Install
Umbraco.Engage
:
Install any Umbraco Engage add-on packages that were previously removed.
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
Only proceed if all the prerequisites checks in Step 2 have passed.
In this step, you will update the database for Umbraco Engage.
Back up your database(s).
Rename the uMarketingSuite database tables, keys, constraints, and indexes using the following query:
These database changes should be executed in < 10 seconds as sp_rename is used and no existing data is touched.
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
, anduMarketingSuite.UmbracoCommerce
.
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
Delete any
obj
/bin
folders in your projects to ensure a clean build.Recompile all projects and ensure all dependencies are restored correctly.
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.
Add your new Umbraco Engage license key to the
appSettings.json
file:
Configure Umbraco Engage to use the legacy segment naming scheme:
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.
[Optional] Set the
Engage:Analytics:VisitorCookie:LegacyCookieName
configuration if uMarketingSuite was using a different visitor cookie name setting than the defaultuMarketingSuiteAnalyticsVisitorId
:
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.
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.
Validate the new license:
Go to Settings -> Licenses in the backoffice and click Validate.
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.
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.
Stop the site.
Run the Prerequisites Check on the database.
Execute Step 5 on the database
Create a backup of the website.
Deploy the updated code from the migrated local environment.
Start the site.
Validate the new license, if this has not happened already:
Go to Settings -> Licenses in the backoffice and click Validate.
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.
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:
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:
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:
uMarketingSuite.ContentBlocks
The uMarketingSuite.ContentBlocks add-on package has been deprecated since version 2.0.0 of uMarketingSuite and is unavailable for Umbraco Engage.
Last updated