Kentico NewsletterMigrator

NewsletterMigrator is a command-line utility which helps you to preserve Kentico marketing emails and templates after the upgrade to Kentico 11.

Introduction

As you may have noticed in the upgrade instructions, the upgrade process does not preserve the content of marketing emails and email templates. In other words, after your application is upgraded to Kentico 11, you are no longer able to view sent marketing emails or edit drafts which had been created before the upgrade. Statistics of sent emails are still available.

In Kentico 11, the data layer of email marketing objects was significantly refactored with numerous breaking changes. For example, marketing email template content was originally divided into four parts (Style sheets, Header, Body, Footer), whereas after upgrade there is only one field where the whole email template content persists. Marketing email content structure is completely different in Kentico 11. Moreover, region placeholder format has changed, widgets and widget zones were introduced, etc. There are multiple approaches on how to recover marketing emails and templates but none is perfect. If one was selected and applied during upgrade, it wouldn't be appropriate for all customers' projects. Therefore, the upgrade utility doesn't recover marketing emails automatically.

Before you run the utility

• Prepare connection strings both to Kentico DB before upgrade and upgraded Kentico DB.
  • Assure that you backed up your project and database as advised in Kentico upgrade instructions.
  • You will need to restore the database backup on your own.
  • Connection strings should also contain Initial catalog (ie. DB name).
• Backup the upgraded database.

Installation

• Download the latest binaries from Releases.
• Unzip the archive to any location of your choice.

Usage

1. Enter connection strings to NewsletterMigrator.exe.config file.
2. Open command prompt at the location where there archive was unzipped and run NewsletterMigrator.exe.

Manual steps after migration (required)

• Re-sign macros on your Kentico 11 instance.
• Revise emails and make appropriate changes so that they look the same as before.
• Write your own widgets which best fit the needs of your marketers and replace the temporary ones (see Preparing email widgets in Kentico documentation).

Technical details

How does NewsletterMigrator recover marketing email templates

1. Blends TemplateHeader, TemplateBody, TemplateFooter and TemplateStylesheetText column content into a single column TemplateCode.
2. Adds the content of TemplateStylesheetText as an inline styles (<link> tag) right before closing </head> tag.
3. Converts region placeholders to widget zone format, i.e., $$name:100:200$$ becomes just $$name$$.

How does NewsletterMigrator recover marketing email content

1. Parses original email content to obtain all regions and their content.
2. Creates a temporary email widget, with a single property Code, for each site and assigns it to all marketing email templates.
   • Output of the widget is the raw content of Code property.
3. Inserts one temporary widget per zone in the marketing email templates and populates the Code property of the widget with data from the particular region of the original email.

How restrict objects which are affected by the utility

You may want to restrict the utility to updating just a subset of all marketing emails and their templates. The configuration allows you to define filtering condition for both emails and templates separately. The filtering condition is SQL expression and represents a part of WHERE clause of the query which is used to select data from respective tables (Newsletter_NewsletterIssue, Newsletter_EmailTemplate). To define issues filter, edit NewsletterMigrator.exe.config, scan for <add key="issuesFilter" ... > element and enter given expression as a value of its value attribute. To define templates filter, proceed the same as for issues filter but modify <add key="templatesFilter" ...> element instead.

Example: Let's migrate only objects from the site with ID = 3

<appSettings>
   <add key="issuesFilter" value="IssueSiteID = 3" />
   <add key="templatesFilter" value="TemplateSiteID = 3" />
</appSettings>

Notes about restricting emails and templates:

• Any column of respective DB table or sub-query can be used in the filter condition.
• Be aware that if you restrict templates you need to restrict issues as well.
• If you restrict issues you don't have to restrict templates necessarily.

Notes

• Do not re-run the utility if it fails or doesn't terminates normally. In such case, restore upgraded DB from the backup.
• The utility doesn't modify the codebase.
• The utility accesses the database directly, i.e., not through Kentico API.
• The utility accesses following DB tables:
  • Newsletter_NewsletterIssue
  • Newsletter_EmailTemplate
  • Newsletter_EmailWidget
  • Newsletter_EmailWidgetTemplate
• The utility only works with versions 10 and 11 of Kentico database.