Skip to content

Commit 0850408

Browse files
sofietoftsofietoft
authored
Merge pull request #6583 from umbraco/engage/mergeMigrationArticle
Merge existing article with technical article
2 parents be6513d + 4364574 commit 0850408

File tree

2 files changed

+284
-1
lines changed

2 files changed

+284
-1
lines changed

‎13/umbraco-engage/tutorials/how-to-create-a-persona.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,4 +64,4 @@ Here you have the option to set different parameters:
6464
* **The expiration type**. Specify whether the implicit persona scoring expires. This can be set to 'never' when it does not expire or can be set to a number of days or sessions.
6565
* **The maximum points to score**. Specify the maximum number of points that can be scored per persona per item.
6666

67-
By adjusting these settings you can tweak the performance of the Umbraco uMS algorithm.
67+
By adjusting these settings you can tweak the performance of the Umbraco Engage algorithm.

‎13/umbraco-engage/upgrading/migrate-from-umarketingsuite.md‎

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,286 @@ Did you build your own segments, added custom goal triggering etc. then have a c
5353
### **Any custom firewall changes?**
5454

5555
If the /umbraco/umarketingsuite/ path was previously allowed, this needs to change to /umbraco/engage/
56+
57+
---
58+
59+
This guide provides a step-by-step approach to migrating a default uMarketingSuite solution to Umbraco Engage.
60+
61+
{% hint style="warning" %}
62+
Upgrade to the latest version of uMarketingSuite before continuing with the migration.
63+
64+
You can upgrade your installation by installing the [latest version](https://www.nuget.org/packages/uMarketingSuite/) on top of the existing one.
65+
{% endhint %}
66+
67+
You can find additional information on migrating the add-on packages for UmbracoForms, Commerce & Headless in the [Further Migrations section](./#further-migrations) of this article.
68+
69+
## Key changes
70+
71+
Before outlining the exact steps, there are a few key changes to be aware of.
72+
73+
These changes will dictate the steps to take in the process of migrating to Umbraco Engage.
74+
75+
Before getting started, it is worth noting that going from uMarketingSuite to Umbraco Engage is not a direct upgrade.
76+
The changes are significant enough that it is more akin to a migration.
77+
78+
### Project, Package, and Namespace changes
79+
80+
| uMarketingSuite | Umbraco Engage |
81+
|------------------------------|-------------------------------|
82+
| uMarketingSuite.Core | Umbraco.Engage.Core |
83+
| uMarketingSuite.Web | Umbraco.Engage.Web |
84+
| uMarketingSuite.Business | Umbraco.Engage.Infrastructure |
85+
| uMarketingSuite.Data | Umbraco.Engage.Data |
86+
| uMarketingSuite.Common | Umbraco.Engage.Common |
87+
| uMarketingSuite.UmbracoForms | Umbraco.Engage.Forms |
88+
| uMarketingSuite.Headless | Umbraco.Engage.Headless |
89+
| uMarketingSuite.Commerce | Umbraco.Engage.Commerce |
90+
| uMarketingSuite | Umbraco.Engage |
91+
92+
<details>
93+
94+
<summary>C# Class changes</summary>
95+
96+
* Namespace changes as documented above.
97+
* All classes containing the `uMarketingSuite` keyword are now updated to `UmbracoEngage`.
98+
* Examples: `UMarketingSuiteApplicationComposer` is now `UmbracoEngageApplicationComposer`, and `AddMarketingApiDocumentation` is now `AddEngageApiDocumentation`
99+
</details>
100+
101+
<details>
102+
103+
<summary>Database changes</summary>
104+
105+
* All Database tables, keys, constraints and indexes containing the `uMarketingSuite` keyword are now updated to `umbracoEngage`.
106+
* Example: `uMarketingSuiteAnalyticsPageview` is now `umbracoEngageAnalyticsPageview`
107+
108+
</details>
109+
110+
<details>
111+
<summary>JavaScript changes</summary>
112+
113+
* All scripts & Asset Paths containing the `uMarketingSuite` keyword have renamed to `umbracoEngage`.
114+
* Example: `/Assets/uMarketingSuite/Scripts/uMarketingSuite.analytics.js` is now `/Assets/umbraco.Engage/Scripts/umbracoEngage.analytics.js`
115+
* All script extension points containing the `ums` keyword have been renamed to `umbEngage`.
116+
* Example: Custom client-side events like `ums("send", "event", "<Category name>", "<Action>", "<Label>")` are now `umbEngage("send", "event", "<Category name>", "<Action>", "<Label>")`
117+
118+
</details>
119+
120+
<details>
121+
122+
<summary>UI Changes</summary>
123+
124+
* The uMarketingSuite folder within `App_Plugins` has been renamed from `uMarketingSuite` to `Umbraco.Engage`.
125+
* The Umbraco Forms addon folder within `App_Plugins` has been renamed from `uMarketingSuite.UmbracoForms` to `Umbraco.Engage.Forms`.
126+
* The Cockpit Partial View has been moved from `Partials/uMarketingSuite/Cockpit` to `Partials/Umbraco.Engage/Cockpit`.
127+
128+
</details>
129+
130+
<details>
131+
132+
<summary>Umbraco & Configuration Changes</summary>
133+
134+
* The Section and corresponding user permission `uMarketingSuite` has been renamed to `Engage`.
135+
* The Media Folder `uMarketingSuite` has been renamed to `Engage`.
136+
* The Data Types and corresponding Data Type Folder with the `uMarketingSuite` keyword have been renamed to `Engage`.
137+
* The Segments for Content Variations (Personalization & A/B Testing) have been renamed from `umarketingsuite` to `engage`.
138+
* Using a new `appsettings.json` key existing installations can enable the legacy naming scheme to maintain compatibility with existing segments.
139+
* The `appsettings.json` key `uMarketingSuite` has been renamed to `Engage`.
140+
* Example: `uMarketingSuite:Settings:Enabled` is now `Engage:Settings:Enabled`
141+
</details>
142+
143+
## Step 1: Prerequisites Check
144+
145+
In this first step, you need to check the Database state to see if the existing data can be migrated to Umbraco Engage.
146+
147+
{% hint style="info" %}
148+
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.
149+
{% endhint %}
150+
151+
1. Execute the prerequisites check using the following query:
152+
```LINK TO Step-1-Prerequisites.sql file```
153+
2. Verify that uMarketingSuite & uMarketingSuite addon version checks return the expected results.
154+
3. Verify that the uMarketingSuite table integrity check returns the expected results.
155+
156+
The result should look like this:
157+
```
158+
---Running Version Pre-Requisite Checks for uMarketingSuite to Umbraco Engage Migration---
159+
✔️ Detected uMarketingSuite version 2.6.1 or higher
160+
✔️ Detected uMarketingSuite.UmbracoCommerce version 2.0.0 or higher
161+
✔️ Detected uMarketingSuite.UmbracoForms version 2.0.0 or higher
162+
---Running Integrity Pre-Requisite Checks for uMarketingSuite to Umbraco Engage Migration---
163+
✔️ The [uMarketingSuiteAnalyticsGoalCompletion] table is in a valid state to be upgraded.
164+
✔️ The [uMarketingSuiteAnalyticsPageEvent] table is in a valid state to be upgraded.
165+
---Finished running Pre-Requisite Checks. Please verify if all 5 checks succeeded before proceeding---
166+
```
167+
If any of these checks return a failure, please resolve the issue before proceeding with the migration.
168+
169+
## Step 2: Replace dependencies
170+
171+
In this second step, you will replace all existing uMarketingSuite dependencies with Umbraco Engage dependencies.
172+
173+
1. (If applicable) Take a backup of any custom implementation of uMarketingSuite-specific files you want to reuse.
174+
175+
2. Remove any installed uMarketingSuite packages (including UmbracoForms, Commerce, and Headless) from your project:
176+
177+
```bash
178+
dotnet remove package uMarketingSuite
179+
dotnet remove package uMarketingSuite.Headless
180+
dotnet remove package uMarketingSuite.UmbracoForms
181+
dotnet remove package uMarketingSuite.Commerce
182+
```
183+
184+
3. Delete the `App_Plugins\*` folder for uMarketingSuite (and if applicable `uMarketingSuite.UmbracoForms`):
185+
186+
```bash
187+
rmdir /s App_Plugins\uMarketingSuite
188+
rmdir /s App_Plugins\uMarketingSuite.UmbracoForms
189+
```
190+
4. Delete the `Assets\uMarketingSuite` folder.
191+
192+
```bash
193+
rmdir /s Assets\uMarketingSuite
194+
```
195+
196+
5. Delete the `Partials\uMarketingSuite` folder.
197+
198+
```bash
199+
rmdir /s Views\Partials\uMarketingSuite
200+
```
201+
6. Delete the existing license file in the `config\uMarketingSuite` folder.
202+
203+
7. Delete the existing `appsettings-schema.uMarketingSuite.json` file from the root of the project.
204+
205+
8. Install `Umbraco.Engage`:
206+
207+
```bash
208+
dotnet add package Umbraco.Engage
209+
```
210+
211+
9. Install Umbraco Engage add-on packages that were previously removed (If applicable).
212+
213+
```bash
214+
dotnet add package Umbraco.Engage.Headless
215+
dotnet add package Umbraco.Engage.Forms
216+
dotnet add package Umbraco.Engage.Commerce
217+
```
218+
219+
## Step 3: Update namespaces and entity names
220+
221+
Based on the [Key Changes](./#key-changes) outlined above 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.
222+
223+
## Step 4: Update the database
224+
225+
{% hint style="warning" %}
226+
Only proceed if all the prerequisites checks in Step 1 have passed.
227+
{% endhint %}
228+
229+
In this step, you will update the database for Umbraco Engage.
230+
231+
1. Backup your database(s).
232+
2. Rename the uMarketingSuite database tables, keys, constraints, and indexes using the following query:
233+
234+
`LINK TO Step-2-Migrate-UMS-Tables.sql file`
235+
236+
3. Update the Umbraco database tables to rename the following uMarketingSuite properties:
237+
* The `uMarketingSuite` Media folder,
238+
* The `uMarketingSuite` Data Types & Data Type Folder,
239+
* The `uMarketingSuite` User Group Permissions,
240+
* The Migration State KeyValue State for `uMarketingSuite`, `uMarketingSuite.UmbracoForms`, and `uMarketingSuite.UmbracoCommerce`.
241+
242+
`LINK TO Step-3-Migrate-Umbraco-Data.sql file`
243+
244+
4. Validate that no errors occurred and all tables were updated successfully. No queries should return that 0 rows were updated.
245+
246+
## Step 5: Finalizing the migration
247+
248+
1. Delete any `obj`/`bin` folders in your projects to ensure a clean build.
249+
2. Recompile all projects and ensure all dependencies are restored correctly.
250+
3. Add your new Umbraco.Engage license key to the `appSettings.json` file:
251+
252+
```json
253+
"Umbraco": {
254+
"Licenses": {
255+
"Umbraco.Engage": "YOUR_LICENSE_KEY"
256+
}
257+
}
258+
```
259+
260+
4. Configure Umbraco Engage to use the legacy segment naming scheme:
261+
262+
```json
263+
"Engage": {
264+
"Settings": {
265+
"UseLegacySegmentNames": true
266+
}
267+
}
268+
```
269+
270+
271+
{% hint style="warning" %}
272+
273+
The naming scheme for segments within content variations has changed from `umarketingsuite` to `engage`.
274+
275+
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 becomes inaccessible and incompatible with the new naming scheme.
276+
277+
{% endhint %}
278+
279+
5. (Optional) Set the `Engage:Analytics:VisitorCookie:LegacyCookieName` configuration if uMarketingSuite was using a different visitor cookie name setting than the default `uMarketingSuiteAnalyticsVisitorId`:
280+
281+
```json
282+
"Engage": {
283+
"Analytics": {
284+
"VisitorCookie": {
285+
"LegacyCookieName": "<Your-Custom-uMarketingSuite-Visitor-Cookie>"
286+
}
287+
}
288+
}
289+
```
290+
291+
{% hint style="info" %}
292+
293+
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 of existing visitors.
294+
295+
{% endhint %}
296+
297+
6. Run the project.
298+
299+
## Further Migrations
300+
301+
### uMarketingSuite.UmbracoForms
302+
303+
If you are using the uMarketingSuite.UmbracoForms package, all the submissions linked to visitors have been migrated using the scripts in Step 4.
304+
305+
Existing Forms, including those that use the uMarketingSuite-provided VisitorId field, do not require additional action.
306+
307+
You can install the Umbraco Engage UmbracoForms add-on package using the following command:
308+
309+
```bash
310+
dotnet add package Umbraco.Engage.Forms
311+
```
312+
313+
### uMarketingSuite.Headless
314+
315+
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.
316+
317+
The v1 Engage APIs (v13.0.0 of Umbraco Engage) maintain the same functionality as the v1 uMarketingSuite APIs.
318+
For more details on the API, please refer to the Swagger documentation provided by Umbraco Engage.
319+
320+
You can install the Umbraco Engage Headless add-on package using the following command:
321+
322+
```bash
323+
dotnet add package Umbraco.Engage.Headless
324+
```
325+
326+
### uMarketingSuite.Commerce
327+
328+
If you are using the uMarketingSuite.Commerce package, all the commerce data has been migrated to Umbraco Engage using the scripts in Step 4.
329+
330+
You can install the Umbraco Engage Commerce addon package using the following command:
331+
332+
```bash
333+
dotnet add package Umbraco.Engage.Commerce
334+
```
335+
336+
### uMarketingSuite.ContentBlocks
337+
338+
The uMarketingSuite.ContentBlocks add-on package has been deprecated since version 2.0.0 of uMarketingSuite and is not available for Umbraco Engage.

0 commit comments

Comments
 (0)