ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is...

16
Email Campaign Manager ECM 1.3.3 to ECM 2.0 Upgrade Instructions Rev: March 12, 2013 Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved. Email Campaign Manager ECM 1.3.3 to ECM 2.0 Upgrade Instructions Instructions for upgrading ECM from version 1.3.3 to 2.0

Transcript of ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is...

Page 1: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

Email Campaign Manager ECM 1.3.3 to ECM 2.0 Upgrade Instructions Rev: March 12, 2013

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Email Campaign Manager

ECM 1.3.3 to ECM 2.0 Upgrade Instructions Instructions for upgrading ECM from version 1.3.3 to 2.0

Page 2: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

Email Campaign Manager

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 2 of 16

Table of Contents

Introduction.............................................................................................................................................. 3

Installing the Upgrade Tool ..................................................................................................................... 4

Using the ECM Upgrade Tool ................................................................................................................. 5

Accessing the Upgrade Tool ............................................................................................................... 5

Performing the Upgrade Process ........................................................................................................ 5

Install Prerequisites .......................................................................................................................... 5

Install Update Package .................................................................................................................... 7

Analyze and Install the Package ...................................................................................................... 8

Post Installation Steps ................................................................................................................... 13

Service Message Names ............................................................................................................... 14

Upgrade Process Architecture........................................................................................................... 14

Manager Root Structure................................................................................................................. 14

Target Audiences and Recipient Lists ........................................................................................... 15

Messages ....................................................................................................................................... 15

ABN Test ........................................................................................................................................ 16

Page 3: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

ECM 1.3.3 to ECM 2.0 Upgrade Instructions

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 3 of 16

Introduction

This document describes the ECM upgrade tool that lets you upgrade your ECM installation from version 1.3.3 to version 2.0.

The upgrade tool leads you through the following steps:

Install Prerequisites

On this step, the upgrade tool checks the prerequisites and backs up the Sitecore.EmailCampaign.config file and some items.

Install Update Package

On this step, the upgrade tool installs the new items required by ECM 2.0.

Upgrade Items

On this step, the upgrade tool makes changes to items and restructures them to match the ECM 2 architecture.

Note We recommend that you back up all Sitecore databases and the Sitecore instance before starting the upgrade tool, because this upgrade is a non-revertible procedure.

Ensure that you performed the package compatibility analysis which helps you to identify potential problems and resolve them in advance before proceeding to the upgrade actions. You can save the list of potential problems in an XML file and review them later.

Since the upgrade tool is a standard ASP.NET web application, you can install update packages remotely without direct access to the Sitecore server.

When the automatic upgrade process is finished, you need to perform the post installations steps which are generally a small amount of manual tasks, such as merging the changes in

Sitecore.EmailCampaign.config file and specifying the sender’s name and address on a

Manager Root.

Page 4: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

Email Campaign Manager

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 4 of 16

Installing the Upgrade Tool

Prerequisites

SPEAK must be installed for the upgrade process to work.

If you do not have SPEAK installed, the ECM upgrade tool will give you the following warning:

Installation Procedure

Use the Sitecore Installation Wizard to install the ECM Upgrade Tool. To open the Installation Wizard, select:

Sitecore, Development Tools, Installation Wizard.

Or:

Sitecore, Control Panel, Administration, Install a Package.

Page 5: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

ECM 1.3.3 to ECM 2.0 Upgrade Instructions

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 5 of 16

Using the ECM Upgrade Tool

Accessing the Upgrade Tool

To access the ECM upgrade tool, enter the following URL in your browser:

http://<your_host_name>/sitecore/admin/UpgradeTool.aspx

If prompted, enter your credentials to access the Sitecore instance.

Note Before running the upgrade tool, you must ensure that no message dispatches are in processing or paused state. If such messages are present in the installation that you are trying to update, the tool will give you a warning. You must resolve the issues by stopping the dispatch processes or waiting until they are completed and then restart the ECM upgrade process.

If you expect users to access the ECM upgrade tool remotely, you should allow anonymous access to

the /sitecore/admin/UpgradeTool.aspx file in IIS.

Performing the Upgrade Process

This section describes the steps of the upgrade process.

Install Prerequisites

On this step, the tool backs up the Sitecore.EmailCampaign.config file and the Target

Audience ECM templates and prepares the Sitecore instance for the update package installation. For more information about what templates the tool backs up, see Section Upgrade Process Details.

Before proceeding with this step, we recommend to backup your databases and the Web.config file.

If you have modified your Sitecore.EmailCampaign.config file, the upgrade tool will back it up

automatically and display the name of the backup file on the Install Prerequisites step. You will need

to merge the changes to the new Sitecore.EmailCampaign.config file manually after the

Page 6: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

Email Campaign Manager

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 6 of 16

upgrade process is finished.

Click Install Prerequisites and the upgrade tool starts installing the prerequisites.

This includes the following:

Backing up the Sitecore.EmailCampaign.config file.

Creates a copy of the Target Audience template at the following location:

/sitecore/templates/Email Campaign/Upgrade Tool Temp Folder/Target Audience

and assigns this template to all items that had the Target Audience template previously. This is necessary since the tool will remove the original Target Audience template on the subsequent steps.

Page 7: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

ECM 1.3.3 to ECM 2.0 Upgrade Instructions

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 7 of 16

When the tool completes this process, it displays the following message:

The next step is to install the update package.

Install Update Package

The upgrade tool contains the update package that includes the new items required for ECM 2.0.

Click Install update package to start the update package installation.

Review Package Information

After you click Install update package, the ECM upgrade tool displays the Review package information page.

Page 8: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

Email Campaign Manager

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 8 of 16

On this page you can view the package metadata and read the readme text. Click the Analyze and install the package button to proceed to the next step.

Analyze and Install the Package

This page lets you analyze the installation process to identify potential problems and install the package.

Click Install to install the package immediately without analyzing for potential conflicts.

Analyzing the Update Package

Click Analyze to perform an analysis of the installation process to identify potential problems that can occur during the installation. The upgrade tool does not make any changes to the Sitecore instance during this action.

The tool displays the progress bar and the number of processed actions.

Page 9: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

ECM 1.3.3 to ECM 2.0 Upgrade Instructions

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 9 of 16

Click More information to view the detailed information:

You can review the analysis information messages or download them as a file by clicking the Download as File link.

To continue, click the Analysis result button which will allow you to review the potential problems that were identified by the wizard.

Analysis Result

On this page you can review potential problems that will occur during the installation.

We strongly recommend to review the analysis messages before continuing the installation.

Page 10: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

Email Campaign Manager

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 10 of 16

There are several types of messages: errors, collisions, warnings and information messages. Each message type is marked by a colored square:

red for errors.

blue for collisions.

yellow for warnings.

grey for information messages.

Errors, collisions and warnings are considered as potential problems and you should pay attention to them.

At the top of the page you can see the information bar. The color of the information bar indicates the importance of problems that were found during the analysis.

At the bottom of the page you can see overall statistics and a link which allows you to download all the messages in the grid as an XML file.

When you are ready to install the package, click Install the package.

Installing the Package

When you click Install the package, the ECM upgrade tool displays the Installing the update package page.

Some update packages contain files that must be updated on the file system. The ASP.NET process may not have enough security permissions to update the files. In this case the ECM upgrade tool will skip these files and inform the user about the problems by showing the installation details page with

Page 11: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

ECM 1.3.3 to ECM 2.0 Upgrade Instructions

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 11 of 16

the appropriate error message:

To fix problems with file installation, click Fix the installation errors. You will be informed about further steps to complete the installation.

After you fix the problems, click Resume the installation to compete the installation.

We strongly recommend that you follow the instructions on how to fix the errors before resuming the installation, otherwise your upgraded Sitecore installation may not be fully supported and you might experience problems with errors or broken functionality in the system.

Page 12: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

Email Campaign Manager

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 12 of 16

When your installation is completed, the upgrade tool displays the Installation Completed page.

Additional Step

At the bottom of the Installation Completed page you see the Additional step required section. Click the link in this section and the upgrade tool will open the Email Campaign Upgrade Tool page in a new window.

On this step, the ECM upgrade tool changes the item structure of ECM 1.3.3 to match the architecture of ECM 2.0.

Page 13: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

ECM 1.3.3 to ECM 2.0 Upgrade Instructions

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 13 of 16

This page informs you that the upgrade tool will modify the Engagement Plan. If you created any custom Engagement Plan states in ECM 1.3.3, you will have to move them manually after the installation.

Note Make sure that no dispatches are in the Processing or Paused state before proceeding with this step.

Note If you have not backed up your Sitecore databases and Web.config file before starting the upgrade process, do this before proceeding with this step.

Click Upgrade Items when you are ready to proceed.

When the tool finishes upgrading the items, it displays the following page:

This is the last step of the ECM upgrade tool. When it is finished, proceed to the post installation steps.

Post Installation Steps

After installing the update package, you should perform the following post installation steps.

Move the settings from the Sitecore.EmailCampaign.config_XXXXXX file that the tool

created to the new actual Sitecore.EmailCampaign.config file.

Start the ECM module using the Sitecore Desktop and set the following properties for each Manager Root:

From Name

From Address

Page 14: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

Email Campaign Manager

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 14 of 16

Reply To

Service Message Names

During the item upgrade process, the ECM upgrade tool moves all Service messages to the

Converted/Service Messages/<Target Audience> folder.

To make sure that users do not confuse service messages from different Target Audience items from

ECM 1.3, the upgrade tool adds [<Target Audience name>] prefixes to Service message

names.

The new names have the following format: [<Target Audience name>] <Service message name>

Upgrade Process Architecture

This section describes the actions that the ECM upgrade tool performs during the upgrade process.

The following sections describe changes related to specific areas and components of ECM.

Manager Root Structure

During the upgrade process, the ECM upgrade tool makes the following changes related to the Manager Root structure:

Converts the structure of each Manager Root to match the structure of ECM 2.0.

If possible, the tool reuses the existing Manager Root items instead of creating new ones to preserve original item IDs.

Moves all Target Audience items to the Recipient Lists folder.

Creates a Subscription Message type item for each Target Audience and associates it with the corresponding recipient list.

Assigns a standard set of message templates to the new items and copies field values from the original Default Message Header and Analytics sections.

Creates the Converted folder under the Messages folder. Moves all items from the Sent folder to the Converted folder.

Moves all messages from the Drafts, Scheduled, Processing folders to the Converted folder

and puts them in the <currentMonth> folder.

Moves all Service messages to the Converted/Service Messages/<Target

Audience> folder.

To make sure that users don’t confuse service messages from different Target Audience

items in ECM 1.3, the upgrade tool adds [<Target Audience name>] prefixes to Service

message names.

The new names have the following format: [<Target Audience name>] <Service message name>

If a Manager Root name contains the hyphen (“-“) character, the tool remove it from the name. For instance, a Manager Root named E-mail Campaign in ECM 1.3 becomes Email Campaign in ECM 2.0.

Page 15: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

ECM 1.3.3 to ECM 2.0 Upgrade Instructions

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 15 of 16

Target Audiences and Recipient Lists

During the upgrade process, the ECM upgrade tool makes the following changes related to Target Audiences and Recipient Lists:

Creates a Subscription type item for each Target Audience preserving the insert options.

Moves the insert options of the Drafts folder item to corresponding Subscription type items.

To move field values from Target Audience items in ECM 1.3 to new items in ECM 2.0, the upgrade tool does the following:

o Creates a temporary copy of the Target Audience template.

o Changes the template of all Target Audience items to the temporary one.

o Replaces all references to the old Target Audience template with references to the temporary one.

o Installs the ECM update package.

o Copies Target Audience field values to fields in appropriate items.

o Changes the template of all Target Audience items to the Recipient List template.

o Deletes the temporary Target Audience template.

Maps the Target Audience fields using the following mappings:

o Message Header section – fields in a message item.

o Dispatch Notification section – fields in a message item.

o Message Context section – fields in a message item.

o Analytics section – fields in a message type item, fields in a message item.

o DSN section – fields in a manager root item.

If there are several Target Audience items under a single Manager Root item, the tool copies only the first non-empty DSN section. The tool clears the Notification Gathering setting.

Messages

During the upgrade process, the ECM upgrade tool makes the following changes related to messages:

Changes all standard messages to Triggered messages and makes them Active.

Changes all non-standard messages to Subscription messages and associates them with the appropriate recipient lists.

Sets the correct states on messages.

Copies the From Name/Address and Reply To values from Target Audience items to

message items.

Sets all required message item fields.

Correct message subjects:

o Finds Set Page Title renderings.

o Find their Datasource fields.

o Copies the subject from the item referenced in Datasource to the message’s root item.

o Clears the Datasource field of the Set Page Title rendering.

Page 16: ECM 1.3.3 to ECM 2.0 Upgrade Instructions - SDN 1.3.3 to ECM 2.0 Upgrade Instructions Sitecore® is a registered trademark. All other brand and product names are the property of their

Email Campaign Manager

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2013 Sitecore. All rights reserved.

Page 16 of 16

Changes templates of One-column, Two-column and Newsletter messages to the AB Test Message template.

For each Pre-Existing Page item with a Newsletter Root item inside:

o Adds a Process Personalization Tokens sublayout to the Newsletter Root item.

o Add the Target Item rendering to the Newsletter Root item.

Replaces the $targetaudience$ token with the $recipientlist$ token in all service messages.

A/B-n Test

During the upgrade process, the ECM upgrade tool makes the following changes related to A/B-n Test:

Creates a new variant of a message root item for each subject (in all languages). Created variants differ only by subjects.

For all messages that are not sent:

o Deletes the old subject item.

o Removes a subject test in the Test Lab.

o Removes an MV test from the Set Page Title rendering.

o Clears the Datasource property of the Set Page Title rendering.