Upgrading to Kentico 10

This page provides instructions for upgrading Kentico projects from version 9 to 10.

1. Check the prerequisites and Upgrade overview
2. Install the upgrade procedure
3. Perform the required steps before the upgrade
4. Apply the upgrade to your Kentico project
5. Perform the required steps after the upgrade

Prerequisites

Before you start the upgrade, please make sure that your environment fulfills the requirements of Kentico 10. See Server and hosting requirements for details.

Note: The upgrade must be applied to complete projects that use the standard folder structure (the solution file, GlobalAssemblyInfo.cs, the CMS and Lib sub-folders). You cannot directly upgrade web site deployments of the CMS folder – first upgrade the original complete project and then create a new deployment.

Upgrading across multiple versions

If you are upgrading from a Kentico version lower than 9, you need to go through a separate upgrade procedure for each version. Check the instructions for each upgrade version, and perform the required steps before and after the upgrade.

For each version, you always need to open the upgraded website in a browser before starting the upgrade for the next version and verify that the site loads correctly. During the first request after the upgrade, the system performs certain tasks required to finish the upgrade, including the import of new objects.

Upgrade overview

The following is a summary of the most important changes that the upgrade performs. To learn how to replace any removed features or components that you use, see the linked documentation or the required steps before and after the upgrade on this page.

• Custom files in the original project are transferred to the upgraded project.
• Customized Kentico files are preserved (does not apply if you choose to overwrite all files when applying the upgrade):
  • For each customized file, the upgrade creates the new Kentico 10 version (with the .new extension). You need to manually transfer your customizations to the new files and then replace the original ones.
  • Customized files that no longer exist in Kentico 10 remain in the file system, with an added .deleted extension. These files are not included in the CMSApp project in web application projects.
• For web application projects, the upgrade merges the content of the CMSApp_AppCode project into the main CMSApp project. The CMSApp_AppCode project is removed from the solution (if custom files were not added). See Customizations in the CMSApp_AppCode project for more information.
• If your Kentico project uses Windows authentication (integrated security) for its database connection, the database upgrade scripts automatically set the Default schema of the database user matching the current Windows account (i.e. the user who runs the upgrade utility) to the schema used by the objects in your Kentico database (dbo by default).
• The upgrade disables web farm and continuous integration functionality. You can re-enable the features after you complete the upgrade.

Class fields

• The upgrade overwrites the form definitions of the default fields of system classes and their alternative forms. Custom fields from version 9 are transferred over.

Default objects

• The upgrade procedure imports new versions of the following default objects (overwrites existing objects):
  • Web parts
  • Web part layouts
  • Widgets
  • Reports
  • Time zones
• The default Form control objects are overwritten (both the source files and form control objects in the system).

E-commerce

• Buy X Get Y discounts now store their priority based on their order in the discount listing in the Buy X Get Y discounts application.
  • The upgrade automatically changes the priority based on their priority values in Kentico 9.
  • After the upgrade, you will see the Buy X Get Y discounts ordered based on their previous priority values.
  • In the database, the priority (and order) is now saved as an integer.
• Store managers can no longer manage only specific departments. If you used department managers, the managers will have access to all departments after the upgrade.

On-line marketing

• The Abuse report, Accept initiated chat request, Accept automatically initiated chat request, Chat request support, Chat request support using offline form, Customer registration, Joining a group, Leaving a group and User contribution activity types are not supported in Kentico 10.

  • The upgrade automatically converts the activity types to custom.
  • The system no longer logs activities of these types.

• After the upgrade, personas, scoring, account statuses, contact statuses, contact roles and contact groups are converted from site-specific to global objects. Objects that have the same code name on different sites will obtain a SiteID suffix. The code name change may break existing macro conditions that use the given objects.

  • The upgrade changes the persona object code name to PersonaCodeName_SiteID.
  • The upgrade changes the scoring object code name to ScoreCodeName_SiteID.
  • The upgrade changes the account status object code name to AccountStatusCodeName_SiteID.
  • The upgrade changes the contact status object code name to ContactStatusCodeName_SiteID.
  • The upgrade changes the contact role object code name to ContactRoleCodeName_SiteID.
  • The upgrade changes the contact group object code name to ContactGroupCodeName_SiteID.

• After the upgrade, email templates of the Automation email type are converted from site-specific to global objects. As a result, it is only possible to create a global email template of the Automation email type. The code name of Automation email templates will obtain the SiteID suffix. The code name change may break existing macro conditions that use the given object, and affect the email template based Send email steps in your marketing automation processes.

  • The upgrade changes the code name of Automation email template to AutomationEmailTemplateCodeName_SiteID.

• The upgrade removes the Opt-out list setting for choosing between Opt-out list is shared between all sites and Opt-out list is separate for each site options. If you have previously selected the Opt-out list is separate for each site option, the recipients of your marketing emails will be unsubscribed from all email campaigns and newsletters on all sites.

• The upgrade removes newsletter recipients that were added as personas, roles, subscribers, and users. If you need to retain the existing subscribers, see On-line marketing - Keeping original subscribers.

• The upgrade stops all running campaigns and removes reports from all campaigns due to major changes in the campaign architecture.

• After the upgrade, the Contact management module can no longer be separated from the Kentico system by removing the On-line marketing module.

  • The upgrade makes contacts and static contact groups available in the Kentico CMS edition.

• The upgrade removes the fields for collecting the ContactAddress2, ContactHomePhone, ContactLastLogon, ContactSalutation, ContactTitleAfter, ContactTitleBefore and ContactWebSite data. The deletion of the mentioned fields may break existing macro conditions that use the given columns as parameters, affect your marketing automation processes that contain the Set contact property steps with the Address 2, Home phone, Last logon,* Salutation,* Title after, Title before and Web URL parameters, and break the mapping of the removed contact fields to forms, Salesforce leads, customers, and users.

• After the upgrade, it is only possible to merge contacts automatically. The upgrade removes the bindings between contacts or accounts that were merged before the upgrade. As a result, these contacts and accounts behave as not merged objects. Their activities and memberships are moved to the respective parent contacts or accounts.

• The upgrade removes the OnlineMarketingFunctions class from the public API. If you have used the class in your transformations, these transformations will not work after the upgrade. You can replace the removed class by implementing a custom class that uses the functionality of the ISubscriptionService, IUnsubscriptionProvider and ActivityInfoProvider classes.

Installing the upgrade procedure

1. Download the Kentico 10 upgrade.
2. Run Upgrade_9_0_10_0.exe.
3. Install the upgrade procedure (the installer places the upgrade into the C:\Program Files\Kentico\10.0\Upgrade90_100 folder by default).

Steps before you start the upgrade

Custom code analysis

If your project contains any custom code (including virtual objects such as transformations), we strongly recommend using the Kentico code upgrade tool before you start the upgrade procedure.

Download the tool from the API Changes page on the DevNet portal. See Upgrading custom code to learn more.

The tool has the following functionality:

• Detects custom code that is no longer valid in version 10
• Provides recommendations for each occurrence of invalid code
• Can automatically convert the majority of code to the Kentico 10 API

The code upgrade tool’s output will help you update your custom code after you perform the upgrade.

Deployment mode and Source control

If your system stores virtual objects on the file system (due to enabled deployment mode or source control options), you need to return the files to the database before performing the upgrade.

You can re-enable deployment mode or source control after you finish the upgrade.

Staging, integration and export tasks

If your project uses staging or the integration bus, you need to synchronize all staging and integration tasks before starting the upgrade procedure. Synchronization of existing tasks from older Kentico versions may fail after you perform the upgrade. To perform the synchronization, use the Staging or Integration bus applications.

If you have the Settings -> Versioning & Synchronization -> Staging -> Log export tasks setting enabled, the system logs delete tasks when objects are deleted. These tasks can then be included in export packages and used to delete objects on other instances during the import. The data of logged delete tasks is NOT updated during upgrades, so existing tasks may not work correctly after you upgrade to a newer version.

We recommend clearing all delete tasks before you start the upgrade – go to Sites -> View export history -> Tasks and click Delete all tasks.

Object version history and recycled objects

The upgrade does NOT update the data of:

• Deleted objects in the Recycle bin
• Previous versions of objects

After you perform the upgrade, it may not be possible to correctly restore or roll back certain types of objects from the recycle bin or version history. Before you start the upgrade, we recommend reviewing the content of your recycle bin and version history:

1. Recover any data that you wish to use after the upgrade.
2. Permanently delete the remaining data.

Macro security

To successfully complete the upgrade, you will need to re-sign all macros after applying the upgrade. The upgrade procedure also re-signs the macros within certain object types automatically.

This can potentially be a security vulnerability, so we strongly recommend checking your system for invalid macros before you start the upgrade:

1. In the System application, select the Macros -> Report tab.
2. Enable Report problems and click Search.

If you detect any macros that have invalid signatures or are otherwise suspicious, fix or delete them. For more information, see Working with macro signatures.

Large database tables and timeouts

If some of your database tables contain very large amounts of data, timeout problems can occur when applying the database upgrade or during the processing of the first request after the upgrade. This may prevent the upgrade procedure from finishing successfully.

To avoid timeout-related issues, you can either increase the timeout settings of your SQL server for the duration of the upgrade, or try to clear unnecessary data.

For example, contact management features can generate a very large volume of contact and activity data on high‑traffic websites (in the OM_Contact and OM_Activity tables). You can trim down the data by running automatic deletion of contacts that meet certain conditions and are no longer relevant.

Full-text search for Kentico database tables

If you are using full-text search catalogs for any Kentico database tables, you need to remove the catalogs before starting the upgrade. The procedure drops and recreates indexes for most tables. You can set up the full-text search again after the upgrade is complete.

E-commerce – Invoice attachments

Since adding attachments to site invoices is removed in Kentico 10, move your attachments to a different place (for example, to the media library).

SalesForce replication scheduled task

The SalesForce replication scheduled task is no longer site-specific, but global only. If you have used the customized SalesForce replication scheduled tasks for your sites, back up the settings of customized tasks.

• The upgrade deletes all site-specific SalesForce replication scheduled tasks.
• The upgrade creates a scheduled task with the default settings, which is global now.

On-line marketing – Adding the On-line marketing module

In case you have not already installed the On-line marketing module, add the module to your Kentico system to ensure that the upgrade process runs correctly. You may uninstall the On-line marketing module after the successful upgrade.

On-line marketing – Removing the Campaign hits widget

Kentico 10 does not contain the campaign.dayreport.graph chart displayed by the Campaign hits widget in the Marketing overview application anymore. However, the upgrade does not remove the widget, therefore the widget displays an error message.

Remove the widget from user dashboards in the Marketing overview application or inform your users to remove the widget from their dashboards.

On-line marketing – Removing the Campaign reports

The upgrade removes all Campaign reports. However, if you saved any Campaign reports in the Reporting application in the Web analytics -> Campaign category, you need to delete the saved reports.

On-line marketing – Removing the Unsubscription request web part

The upgrade removes the obsolete Unsubscription request web part. If you used the web part on your site, you need to remove the web part instances from your pages and page templates. You also need to delete the web part in the Web parts application.

To allow users to cancel their subscription, use unsubscription links in your emails or the {% UnsubscribeLink|(resolver)subscriber %} macro on source pages for page-based newsletters .

On-line marketing – Removing the Update from Data.com action step

The upgrade removes the Update from Data.com action step. If you used the action step in your marketing automation processes, you need to remove these action steps from the existing automation processes.

The Data.com integration stopped working as of 1st September 2016, because Data.com terminated third party access to their API.

On-line marketing – Replacing the removed fields by custom fields

If you need to keep collecting the data that was previously gathered by the removed Address 2, Home phone, Last logon, Salutation, Title after, Title before and Web URL fields, you can create custom fields that will collect the data instead. Replace the removed fields with the custom fields in the following:

• Marketing automation processes containing the Set contact property steps with the Address 2, Home phone, Last logon, Salutation, Title after, Title before and Web URL parameters
• Mapped Address 2, Home phone, Last logon, Salutation, Title after, Title before and Web URL contact fields to forms, Salesforce leads, customers, and users
• Macro conditions using ContactAddress2, ContactHomePhone, ContactLastLogon, ContactSalutation, ContactTitleAfter, ContactTitleBefore and ContactWebSite parameters

On-line marketing – Running the SQL script to keep the Address 2 data

If you need to keep the ContactAddress2 data that was previously gathered by the removed Address 2 field, run the following SQL script against your Kentico database:

UPDATE OM_Contact
SET ContactAddress1 = CASE
    WHEN (ContactAddress1 IS NOT NULL AND ContactAddress1 <> '') THEN CONCAT(ContactAddress1, ', ', ContactAddress2)
    ELSE ContactAddress2
END
WHERE ContactAddress2 IS NOT NULL AND ContactAddress2 <> ''

The SQL script merges the ContactAddress2 and ContactAddress1 data into the ContactAddress1 data, which is now being gathered by the Address field.

On-line marketing – Keeping original subscribers

If you need to keep the original subscribers (added either as personas, roles, subscribers, or users), perform the following steps for individual types of subscribers.

Subscribers and users

1. Get a list of the specific type of subscribers by running the following SQL script against your Kentico database.

   • For subscribers

     Copy

     
     
     
       SELECT * FROM [Newsletter_Subscriber] WHERE [SubscriberType] IS NULL
     
     
       

   • For users

     Copy

     
     
     
       SELECT * FROM [Newsletter_Subscriber] WHERE [SubscriberType] = 'cms.user'
     
     
       

2. For each entry in the list:
   1. Check that a matching contact exists in the OM_Contact database table by comparing values in the ContactEmail column to values in the SubscriberEmail column.
      • Note that the email addresses of the cms.user subscriber type are stored in the Email column of the CMS_User database table.
   2. If a matching contact does not exist, create a new contact that uses values from the SubscriberEmail, SubscriberFirstName, and SubscriberLastName columns.
   3. Update the subscriber entry to use om.contact as the SubscriberType, and respective contact ID as the SubscriberRelatedID.

Personas and roles

1. Get a list of the subscribers added as personas and roles by running the following SQL script against your Kentico database.

   Copy

   
   
   
    SELECT * FROM [Newsletter_Subscriber] WHERE [SubscriberType] = 'personas.persona' OR [SubscriberType] = 'cms.role'
   
   
    

2. Create condition-based contact groups for roles and personas:

   1. Open the Contact groups application in Kentico.
   2. Create a New contact group and enable the Condition-based contact group option.
   3. Edit the Macro conditionfor the contact group.
   4. Use either Contact is in persona or Contact is in role macro rule and select personas or roles based on the subscriber type.

3. Assign the contact groups to a newsletter.

Applying the upgrade

We strongly recommend using the Kentico Upgrade Utility to perform the upgrade automatically.

1. Open the folder where you installed the upgrade.

2. Run the Kentico Upgrade Utility (Upgrade.exe).

3. Enter the path to your Kentico 9 web project folder (you can select a folder using the Browse button).

4. Use the utility to back up your project files and/or database if you have not done so already.

5. Select whether you want to upgrade files, the database or both. To successfully perform the upgrade, you need to update both the project files and the database. Only change the settings in special scenarios (for example when performing part of the process manually).

   Important: If you use a separated on-line marketing database, you need to disable the SQL script part of the upgrade:

   1. Click Switch to advanced mode.
   2. Clear the SQL script checkbox.Run the SQL scripts manually after the upgrade utility updates the project files (see Upgrading separated on-line marketing databases below).
   Warning: If you enable the Overwrite all files option in advanced mode, the upgrade replaces all project files with the default Kentico 10 files, regardless of customizations. This includes the web.config file, which you need to configure again after applying the upgrade.

6. On web application projects, the upgrade utility rebuilds the solution at the end of the upgrade by default. If your project contains custom code that is no longer supported in Kentico 10, or has certain modules uninstalled, the rebuild will not be successful. You can disable the Rebuild web project option on customized projects, and perform the rebuild manually once you update the project after the upgrade.

7. Choose a method of taking the project offline and bringing it back online.

8. Click Next to start the upgrade procedure.

9. After the upgrade finishes, click Next to view any conflicts of customized files that occurred during the upgrade process. By default, the upgrade utility doesn’t overwrite modified files in order to preserve your customizations (unless you enabled the Overwrite all files option in the upgrade utility):

   • For each customized file, the upgrade creates the new Kentico 10 version (with the .new extension). You need to manually transfer your customizations to the new files and then replace the original ones.
   • Customized files that no longer exist in Kentico 10 remain in the file system, with an added .deleted extension. These files are not included in the CMSApp project in web application projects.

10. The upgrade attempts to automatically update your project’s web.config file (unless you enabled the Overwrite all files option in the upgrade utility). The process may fail if your web.config contains certain types of customizations. In this case, a new web.config file is created in the web project’s CMS folder with the .new extension. You need to:

    • Edit the new web.config and transfer over any customizations and the connection string from the original web.config.
    • Move your original web.config to a different location.
    • Rename web.config.new to web.config.

Close the upgrade utility.

Upgrading separated on-line marketing databases

If your project uses a separated on-line marketing database, you need to manually run the upgrade SQL scripts after updating the project files:

1. Open the upgrade installation directory (C:\Program Files\Kentico\10.0\Upgrade90_100 by default).

2. Expand the SQL\Separation folder.

3. Manually run the script files in the following order:

   1. separated.sql (against the separated on-line marketing database)
   2. default.sql (against your main Kentico database)

Once the databases are successfully upgraded, continue with the steps after the upgrade.

Steps after performing the upgrade

After you apply the upgrade to your project, please check the following sections and perform the required actions. Go through the sections in the listed order.

API changes

You need to update your custom code according to the new API of Kentico 10, including:

• Custom or customized code files in the web project
• Virtual objects in Kentico, such as transformations and page layouts

Use the output of the Kentico code upgrade tool (described in Custom code analysis) to find occurrences of invalid code and recommendations on how to fix or replace them.

Tip: Enable Deployment mode and fix the code of virtual objects in the corresponding physical files. This makes it easier to update the code of virtual objects according to the output of the code upgrade tool. Disable deployment mode to return the updated virtual objects back into the database.

You can also search for specific API resolutions on the DevNet portal.

Automated tests

The upgrade removes the CMS.Tests library from the Kentico project. If you have any automated tests that utilize the library (for base classes etc.), you need to perform the following steps:

1. Open your Kentico solution in Visual Studio.

2. If you use separate testing projects, you need to manually remove any references to the original CMS.Tests library.

   If you have custom tests directly within the Kentico CMSApp project or the App_Code folder of web site projects, you do not need to remove references. The upgrade automatically deletes references to removed libraries within the Kentico projects.

3. Install the Kentico.Libraries.Tests NuGet package into the projects that contain your tests. The package provides a replacement for the original testing API.

4. Verify that your tests work as expected with the new version of the testing API.

Customizations in the CMSApp_AppCode project

For web application installations, the upgrade attempts to merge the CMSApp_AppCode project into the main CMSApp project.

If you customized the CMSApp_AppCode project, you may need to perform additional steps after the upgrade:

• No customizations – all files are moved into the CMSApp project and CMSApp_AppCode is removed from the solution. No manual steps are required apart from rebuilding the CMSApp project (this may be done automatically as part of the upgrade procedure).
• Customized default files – both customized and unchanged files are moved into the CMSApp project and CMSApp_AppCode is removed from the solution. We recommend testing the custom functionality after you finish the remaining steps of the upgrade.
• Added custom files – if you have added custom files into the CMSApp_AppCode project, it remains in the solution. All default files are moved to the CMSApp project and only the custom files remain. We recommend that you move any classes into a custom Class Library project (assembly), include any other files (web forms, user controls, web services, etc.) into the main CMSApp project, and then remove CMSApp_AppCode.

Customized device profile files

Kentico 10 changes the code name of the Device profiles module from CMS.DeviceProfile to CMS.DeviceProfiles. The change affects the names of the related module folders within the project:

• CMS\App_Data\CMSModules\DeviceProfile
• CMS\CMSModules\DeviceProfile
• CMS\CMSWebParts\DeviceProfile

The upgrade performs the following changes:

• New folders named DeviceProfiles are created in the same general locations, containing the Kentico 10 versions of the related files.
• If you have customized or replaced any of the default files (for example the 51degrees.dat or devices.xml files in CMS\App_Data\CMSModules\DeviceProfile), the files remain in the old DeviceProfile folders, with the .deleted extension added.

To preserve your customizations, you need to:

1. Move your customized files to the new DeviceProfiles folder.
2. Remove the .deleted extension for each file and merge your customizations with the new content if necessary.
3. Delete all old DeviceProfile folders.

Custom mime types

The App_Data/mimetypes.txt file used to register custom media types was removed in Kentico 10. If you had any custom media types registered in the mimetypes.txt file, you need to register them by calling MimeTypeHelper.AddRule(string mimetype, string extension) in the OnInit() method of a custom module class.

using CMS;
using CMS.DataEngine;
using CMS.Helpers;

...

// Initializes your module. Called when the application starts.
protected override void OnInit()
{
    base.OnInit();

    // Registers the mime type for a custom module class
    MimeTypeHelper.AddRule("application/x-doom", ".wad");
}

...

Custom forum layouts

Kentico 10 requires a different approach for creating custom forum layouts in the CMS\CMSModules\Forums\Controls\Layouts folder.

If your project contains one or more custom forum layouts, you need to move the layout folders up one level in the file system and modify the Forum layout selector form control. See Customizing forum design for more information.

Kentico 10 setup files

The upgrade converts your web projects to version 10, but does not provide the associated setup files (i.e. the Kentico program files that are separate from individual web projects). The setup files contain external utilities, sample files, and allow you to install new Kentico 10 web projects.

To obtain the installer and setup files for Kentico 10:

1. Download the Kentico 10 installer.
2. Run Kentico_10_0.exe.
3. Read and accept the License Terms and Conditions and click Custom installation.
4. Select Install only program files and click Install.

Clearing session state data

Objects that are stored in the server-side session state may have a different structure in the upgraded version. The changes may cause errors for users who access the upgraded site with outdated session data.

If your application uses a session state mode that preserves data through application restarts (StateServer, SQLServer or Custom), you need to manually clear any existing session data after you perform the upgrade:

• StateServer – restart the session state service.
• SQLServer – delete the content of the session state database.
• Custom – depends on the implementation of the custom storage provider.

Running the website - First request

Open the upgraded website in a browser. When handling the first request (i.e. on application start), the system performs certain tasks required to finalize the upgrade. Processing of the first request may take longer than usual.

The first request also includes the automatic import of new web part, widget, report and time zone objects.

Important: Once the website loads, log in to the administration interface and open the Event log application. Check for the presence of any errors or exceptions between the Upgrade - Start and Upgrade - Finish events:

• If you find errors related to the object import, open the Sites application, click Import site or objects and try to import the upgrade_90_10_0.zip package manually.
• If any other errors are present or if the log does not contain the Upgrade - Finish event at all, the upgrade may not be fully applied. Please contact Kentico support and provide the details of the errors.

Licenses

You need to add Kentico version 10 licenses for the domains used by your sites:

1. In the Kentico administration interface, open the Licenses application.
2. Delete the old version 9 licenses.
3. Click New license to add your licenses for version 10

Macros

To ensure that macros and the administration interface work correctly after the upgrade:

1. Log in to the Kentico administration interface as a global administrator.
2. Open the System application.
3. Select the Macros -> Signatures tab.
4. Enable the Sign all macros option.
5. Click Update macro signatures.

The system resigns all macros. The new security signatures of all macros contain the username of your administrator account.

Validate that all macros in the system work correctly:

1. In the System application, select the Macros -> Report tab.
2. Enable Report problems and click Search.

For more information, see the Macro expressions chapter.

Recursive macros

By default, macros in version 10 do not resolve recursively (if the result of a macro contains further macro expressions, they are not resolved). If your website contains any macros that need to be resolved recursively, add the (recursive)true macro parameter to the given expressions.

For example, macros that require recursive resolving may be present in email notification templates.

Password reset email templates

Kentico 10 always requires email approval when resetting forgotten passwords. After submitting password reset requests, users now receive emails based on the Membership - Change password request email template, and the Membership - Forgotten password template is no longer used.

If your website previously used the password reset functionality without email approval and a modified or custom Membership - Forgotten password email template, you need to transfer your custom content to the Membership - Change password request template.

Additionally, a new Send password reset confirmation email setting (found under Settings -> Security & Membership -> Passwords) was introduced. Enabled by default, this feature sends users an additional email upon a successful password reset. This email is based on the Membership - Password reset confirmation email template. If you want to use this feature and use customized email templates, you need to customize this template accordingly.

User password change email templates

Kentico 10 now uses two different email templates when changing a user’s password through the Users application’s Password tab, or the Customers application’s Login details tab. If you generate a new password for a user, the system uses the Membership - Changed password email template. If you manually change the password for a user, the system uses a new Membership - Password reset confirmation email template.

If your website previously used a custom or modified version of the Membership - Changed password email template and you use the change password functionality, you need to transfer your customization to the Membership - Password reset confirmation email template .

On-line marketing macros

After the upgrade, the Contact has opened specified email campaign in the last X days, Contact has visited the specified page in the last X days, Contact has voted in the specified poll, Contact is in community group, Contact is in role and Contact is subscribed to a specified email campaign macro rules no longer use code name parameters, but GUIDs. The change of code name parameter to GUID will break your existing macro conditions that use these macro rules. The values in the affected macro rules need to be selected again and re-saved.

The upgrade also updates the code of the following macro rules:

• Activity ‘External search’ performed for keyword
• Activity ‘Internal search’ performed for keyword

The upgrade also changes the display names of the following macro rules:

• The Contact has opened specified email campaign in the last X days macro rule is renamed to Contact has opened the specified email feed in the last X days.
• The Contact is subscribed to a specified email campaign macro rule is renamed to Contact is subscribed to the specified newsletter.

If you use these macro rules in the conditions of automation process triggers, you need to re-save the conditions.

Scoring and persona rules

Due to performance optimizations, Kentico 10 removes several fields from the configuration of scoring or persona rules based on certain types of activities.

• Page visit and Landing page activities no longer provide the Query string field in the activity details.
• Internal search and External search activities no longer provide the following fields:
  • Search provider – can be replaced by adding conditions for the URL referrer field.
  • Search key word – can be replaced by changing the Rule type to Macro and using the Contact has searched for specified keywords macro rule in the condition.

If your website used rules with conditions for the removed fields, you need to evaluate whether the rules are still relevant. Either delete the rules or update their activity details as required.

Web farms

The upgrade procedure automatically disables web farm functionality. If your Kentico instance runs on a web farm, you need to enable web farms after you complete the upgrade.

We recommend that you enable the web farm on one server or instance and after that you add the remaining servers to the web farm.

1. In the Kentico administration interface, open the Settings application.
2. Expand the Versioning & Synchronization -> Web farm category.
3. Select the Web farm mode:
   • Automatic – if you wish to let the system handle the configuration of web farms servers.
   • Manual – if you need to control the web farm manually. See Configuring web farm servers.
4. Click Save.

UI personalization

If you have UI personalization enabled for your site, we recommend reviewing the settings for all available roles. You may wish to enable access to new UI elements added by the upgrade (applications, tabs, etc.).

Customized extender files

Kentico 10 moves many of the default extender classes from public files in the Kentico project’s App_Code (or Old_App_Code) folder into compiled libraries. Extenders adjust the behavior or content of specific pages in the Kentico administration interface.

If you have modified one of the default extender files that was moved to a library, your customizations will no longer apply to the administration interface. In such cases, the modified extender file remains in the original location, but the related UI element uses the default extender from the library instead.

To re-apply your extender customizations after the upgrade, choose one of the following solutions:

• Find the UI element that originally used the extender in the Modules application. Customize the element and assign your modified extender class on the Properties tab.

  Customizing the default UI elements is not recommended in general, but may be the easiest option in this scenario.

  Note: The system may overwrite your UI element customizations when upgrading or hotfixing to a newer versions. We recommend maintaining a list of any UI elements that you customize, so you can check if your extender settings were overwritten and assign them again if necessary.

  – OR –

• Create a custom module in the Modules application and add UI elements that copy the settings of the original UI elements. Then assign your custom extenders on the Properties tab and use the resulting interface instead of the original.

E-commerce – Shipping options and payment methods

The upgrade procedure removes binding of shipping options and payment methods. If you used this feature, you can customize Kentico to achieve the same result. See Making payment methods dependent on shipping options.

E-commerce – The EcommerceTransformationFunctions class moved

The EcommerceTransformationFunctions class was moved to the CMS.Ecommerce.Web.UI library/namespace. If your website uses ASCX transformations that call methods from this class, you need to update the namespace in the transformation code.

This also applies to the default samples sites upgraded to Kentico 10.

On-line marketing – Configuring marketing automation steps

The upgrade changes contacts to global objects. As a result, you need to manually set the site and email feed parameters in the Send campaign email step properties and the site and newsletter parameters in the Newsletter subscription step properties of all your marketing automation processes that you intend to use. You also need to manually set the site parameter in the Log custom activity step properties of all your processes that you intend to use.

• The upgrade also renames the Send campaign email action step to Send marketing email.

On-line marketing – Localized email campaign and newsletter display names

Email campaigns and newsletters in Kentico no longer provide a localizable display name (using macros). If you used email campaigns or newsletters with a localization resource string, the display name will no longer be evaluated.

Change the email campaign’s or newsletter’s display name so that it is displayed as required.

On-line marketing – Rebuilding contact groups and recalculating scoring and persona rules

If you used the removed ContactAddress2, ContactHomePhone, ContactLastLogon, ContactSalutation, ContactTitleAfter, ContactTitleBefore and ContactWebSite columns as parameters in your macro conditions, it is possible that your condition-based contact groups, scoring and persona rules are not up-to-date. Therefore, we recommend that you rebuild your condition-based contact groups, and recalculate your scoring and persona rules.

On-line marketing – Relative activity URLs

In Kentico 10, activity URLs can only be absolute. If you used any scoring or persona condition rules with a relative activity URL, change the URL to absolute and resave the rule.

On-line marketing – Roles with on-line marketing permissions

As the permission model of the Contact management module was changed in Kentico 10, the upgrade removes these permissions from all roles.

If you used these permissions, assign them again based on the new model. See Configuring on-line marketing permissions for more information.

On-line marketing – Salesforce integration performance

The upgrade modifies database indexes related to on-line marketing in order to optimize performance for the most typical scenarios. The index changes may have a negative effect if you actively use the Saleforce integration to replicate Kentico contacts into Salesforce leads (with a large number of contacts in the database).

In these cases, we recommend manually creating a database index with the following columns on the OM_Contact database table:

1. ContactSalesForceLeadID
2. ContactSalesForceLeadReplicationDisabled
3. ContactSalesForceLeadReplicationSuspensionDateTime

The index should be non-clustered and non-unique. See the Create Nonclustered Indexes article for more information.

Localized form display names

Forms in Kentico no longer provide a localizable display name (using macros). If you used forms with a localization resource string, the display name will no longer be evaluated.

Change the form’s display name so that it is displayed as required.

Compilation performance

Newly installed Kentico 10 projects contain CodeDOM providers that use the .NET Compiler Platform (“Roslyn”) compiler. This improves the compilation performance of the project and significantly speeds up the first load time of the website.

To avoid potential conflicts, the upgrade procedure does not automatically add the CodeDOM providers into existing projects. However, we recommend installing the providers manually after you perform the upgrade:

1. Open your Kentico solution in Visual Studio.
2. Right-click the main web project in the Solution Explorer and select Manage NuGet Packages.
3. Install the Microsoft.CodeDom.Providers.DotNetCompilerPlatform NuGet package (version 1.0.1 or newer).

Upgrading source code instances

Kentico does not provide an upgrade package for source code instances. We recommend using the following process if you need to upgrade a source code project:

1. Obtain the new version of the source code solution.
2. Install the upgrade procedure.
3. Perform any relevant steps before the upgrade.
4. Merge all customizations from your old source code solution into the new one.
   • This mainly includes updates of custom API, verification of its relevance in the new version, and testing.
5. Apply the database upgrade.
6. Open the upgrade installation directory (C:\Program Files\Kentico\10.0\Upgrade90_100 by default), and copy the CMS\CMS\CMSSiteUtils\Import\Upgrade_90_100.zip file into the CMS\CMSSiteUtils\Import folder of the new Kentico 10 project.
7. Perform all relevant steps after the upgrade.