Upgrading to Kentico 11

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

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 11. See Server and hosting requirements for details.

The upgrade must be performed on a machine with a working Internet connection.

Note: The upgrade must be applied to complete projects that use the standard folder structure (the CMS and Lib sub folders) and names of key files (the solution file, csproj project file, web.config, packages.config, GlobalAssemblyInfo.cs). 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 10, 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.

The same requirement applies even if you are only updating to a newer patch version by applying a hotfix to the upgraded project.

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.

• If your project uses .NET 4.5.2 or older, the upgrade sets the project’s version to 4.6 (the minimum .NET version supported by Kentico 11).
• The upgrade integrates required third-party libraries by installing the following NuGet packages into the Kentico project (and their dependencies):
  • AjaxControlToolkit 17.1.1.0
  • AjaxMin 5.14.5506.26202
  • AngleSharp 0.9.9
  • AWSSDK.S3 3.1.9
  • Castle.Windsor 4.0.0
  • Facebook 6.4.2
  • GlobalLink.Connect 4.18.3.1
  • Microsoft.AspNet.WebApi.WebHost 5.2.3
  • Microsoft.Azure.Search 3.0.2
  • Microsoft.SharePointOnline.CSOM 16.1.6621.1200
  • Mono.Cecil 0.9.6.1
  • Newtonsoft.Json 7.0.1
  • NuGet.Core 2.14.0
  • PayPal 1.8.0
  • System.Data.HashFunction.CRC 1.8.2.2
  • WindowsAzure.Storage 7.2.0

• 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 11 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 11 remain in the file system, with an added .deleted extension. These files are not included in the CMSApp project in web application projects.
• 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 the previous version 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).

Email marketing

• Kentico 11 sites have a maximum limit on the number of created email feeds, based on the used License Edition (5 newsletters for Kentico CMS Base, 10 newsletters for Kentico CMS Ultimate, unlimited newsletters and email campaigns for Kentico EMS). See the Email marketing page for detailed information.
• Kentico 11 sites have a maximum limit on the number of marketable recipients for each email feed, based on the used License Edition (500 for Kentico CMS Base, 5000 for Kentico CMS Ultimate, unlimited for Kentico EMS).
• The upgrade does not preserve the content of existing marketing emails and email templates. The templates and emails need to be created again after the upgrade using the new email builder functionality.

E-commerce

• Kentico 11 sites have a maximum limit on the number of enabled products (SKUs), based on the used License Edition. Initially, the limit is 100 for Kentico CMS Base, 500 for Kentico CMS Ultimate, and unlimited for Kentico EMS. After evaluating feedback from partners and clients, Kentico has decided to release hotfix 11.0.15, which increases the limits (500 for Kentico CMS Base, unlimited for Kentico CMS Ultimate and Kentico EMS). See the Products page for detailed information.
• The overall customization model was changed for many types of e-commerce functionality. If your project contains e-commerce customizations, you may need to perform significant updates of your code as part of the upgrade. We recommend reading the E-commerce customizations section and the other related steps after the upgrade.
• Orders in Kentico 11 use a different data structure and calculation model than in previous versions. As a result, the upgrade of existing orders is not fully supported – the final price totals of orders remain the same as before the upgrade, but you may notice inconsistencies when viewing the details of upgraded orders or the values of specific columns in the COM_Order or COM_OrderItem database tables (item prices, various subtotals, discounts, etc.). If you need to keep archives of existing orders with full details, we recommend exporting the order data to an external system or file before you perform the upgrade.
• Donation products (SKUs) are no longer supported in Kentico 11. For all existing donation products, the upgrade changes the product representation value from Donation to Standard product. Values of donation-specific properties are lost (Minimum donation, Maximum donation, Allow private donation). See Collecting donations to learn about the current recommendations for managing donations.
• Flat value order discounts are no longer supported (use the new gift cards for this purpose). The upgrade procedure transforms all existing flat order discounts to percentage-based and disables them.
• The data structure and configuration of Product coupons changes significantly in Kentico 11. The upgrade transfers existing product coupon data, but skips global product coupons (no longer supported) and coupons assigned to products using the All products except for these option. See the E-commerce - Product coupons section in the steps before the upgrade.
• Kentico 11 stores the default payment gateway provider classes (PayPal, Authorize.NET, Customer credit) in a different assembly and namespace (CMS.Ecommerce). The upgrade automatically updates all payment methods that use the original class locations.

Installing the upgrade procedure

1. Download the Kentico 11 upgrade.
2. Run Upgrade_10_0_11_0.exe.
3. Install the upgrade procedure (the installer places the upgrade into the C:\Program Files\Kentico\11.0\Upgrade100_110 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 11
• Provides recommendations for each occurrence of invalid code
• Can automatically convert the majority of code to the Kentico 11 API

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

Required .NET Compiler Platform

Kentico 11 requires the .NET Compiler Platform (“Roslyn”) compiler to run. Installations of Kentico 10 or newer contain the Microsoft.CodeDom.Providers.DotNetCompilerPlatform NuGet package by default, which provides the required functionality.

However, if your project is upgraded from Kentico 9 or older, you may be missing the package. In these cases, you need to install the package before applying 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.2 or newer).

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.

Email marketing – Email and template content

The upgrade does not preserve the content of existing marketing emails and email templates. For templates, the TemplateBody, TemplateStylesheetText, TemplateHeader and TemplateFooter columns are removed from the Newsletter_EmailTemplate database table and replaced by the new TemplateCode column.

If you want to transfer your existing email and template content, you need to back it up before starting the upgrade. After the upgrade is complete, use the content to create new templates and emails for your email campaigns and newsletters (based on the new email builder functionality).

E-commerce – Single tax per product, department, and shipping option

Kentico 11 allows assigning of only one tax per product, department, and shipping option. If you have multiple taxes assigned to any of the specified objects, change your tax class settings so that the final tax amount corresponds with the previous state.

For example, if you use tax A with the amount set to 5% and tax B with the amount set to 10%, both assigned to your products, create a new tax with the amount set to 15% and assign just this new tax to your products.

If you leave multiple taxes assigned to products, departments or shipping options, the upgrade procedure leaves only one of the taxes assigned to each object and the final tax amount will be different from the original state.

E-commerce – Product coupons

The data structure and configuration of Product coupons changes significantly in Kentico 11. The upgrade transfers existing product coupon data, but does not process global product coupons (no longer supported) and coupons assigned to products using the All products except for these option.

To ensure that all product coupon data is preserved correctly through the upgrade, perform the following in the Product coupons application:

• For any global product coupons, recreate the same coupon on all sites in the system.
• For any product coupons using the All products except for these option on the Products tab, switch to Only the following products and adjust the product selection correspondingly.

Notes:

• For product coupons assigned to products that have variants, the upgrade replaces the assigned base product with all available product variants. If necessary, you can adjust the product assignment of coupons after the upgrade.
• After the upgrade, the Product coupons application and the related objects require the Read discounts and Modify discounts permissions for the E-commerce module, instead of the Read data and Modify data permissions. Assign the given permissions to the appropriate roles to ensure that your users retain access to product coupons.

Removed web parts

The upgrade removes the following web parts:

• Flash(together with the Flash widget)
• Donate
• Donations
• Newsletter archive
• Quick time
• Search engine results highlighter
• Search accelerator (for IE8 and higher)
• WMP video

You need to replace or remove instances of these web parts on your site’s page templates. Use the following process:

1. Open the Web parts application.
2. Select the given web part and view the Usage tab.
3. Remove or replace any occurrences of the web part on your site.
4. If a web part is used by a widget or inherited web part, perform these steps for the given components (use the Widgets application for widgets).

After you remove or replace all occurrences of a web part, we strongly recommend that you delete it in the Web parts application.

Applying the upgrade

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

Note: Before you run the upgrade utility, close any instances of Visual Studio where the target Kentico solution is opened.

1. Open the folder where you installed the upgrade.

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

3. Enter the path to your Kentico 10 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).

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 11, 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 does not 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 11 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 11 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:
    1. Edit the new web.config and transfer over any customizations and the connection string from the original web.config.
    2. Move your original web.config to a different location.
    3. 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\11.0\Upgrade100_110 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 11, 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.

E-commerce customizations

Kentico 11 introduces significant changes in the e-commerce functionality and API. You may need to update any related custom code or components after performing the upgrade.

• The type of all API members that store or return prices and other monetary values was changed from double to decimal (affects object properties, method parameters and return types, etc.).

• The overall customization model was changed for many types of e-commerce functionality. Instead of inheriting from provider classes and overriding methods, you now need to create and register custom implementations of appropriate interfaces. See E-commerce customization model to learn more.

• If you perform shopping cart calculations in your custom code, you now need to explicitly call the ShoppingCartInfo.Evaluate() method. The Evaluate() method must also be called after setting ShoppingCartInfo properties that affect the calculation results.

• The API for implementing custom payment gateways was revised (without backward compatibility). Any custom payment gateways need to be rewritten for Kentico 11. See Creating a custom payment gateway.

• If you have customized the evaluation or application of Buy X Get Y discounts :

  • For custom classes that inherit from MultiBuyDiscountsEvaluator, you need to perform the following:
    • Update your class’s code according to the new signatures of the virtual methods in the base class.
    • Register your class as the implementation of the IMultiBuyDiscountsEvaluator interface using the RegisterImplementation assembly attribute (instead of registering the class in a custom inherited MultiBuyDiscountInfoProvider ).
    • Verify that your customization works as intended with the updated e-commerce functionality.
  • If you have a custom inherited MultiBuyDiscountsApplicator class, you need to revise the entire customization. In these scenarios, we recommend implementing your custom discount functionality as a separate step (IShoppingCartCalculator implementation) in the overall shopping cart calculation process. See Customizing the shopping cart calculation for more information.

InfoProvider customizations

The default InfoProvider classes in Kentico 11 no longer contain virtual GetInfoInternal, SetInfoInternal and DeleteInfoInternal methods (in most cases). For any custom providers inheriting from a default InfoProvider class that contain overrides of these methods, override the following methods instead:

• GetInfoById (and/or GetInfoByCodeName, GetInfoByGuid)
• SetInfo
• DeleteInfo

NuGet package consolidation

If your project uses a higher Target framework than .NET Framework 4.6, we strongly recommend that you consolidate the target framework version for all installed NuGet packages:

1. Open your Kentico project in Visual Studio.

2. Open the Package Manager Console (under Tools > NuGet Package Manager).

3. Run the following Update-Package command:

   Copy

   
   
   
    Update-Package -reinstall
   
   
    

The command reinstalls all NuGet packages with the appropriate target framework version for your project.

Assembly references

Kentico 11 brings the following assembly changes:

• CMS.DataProviderSQL.dll merged into CMS.DataEngine.dll
• CMS.FileSystemStorage.dll merged into CMS.IO.dll

You need to remove any manually added references from custom projects to the old assemblies. If necessary, add new references to the assemblies into which the code was merged. The changes do not impact the related API and namespaces (CMS.DataProviderSQL and CMS.FileSystemStorage).

Security code form control

In Kentico 11, the Security code form control is implemented by a class within the CMS.FormEngine.Web.UI assembly. The upgrade removes the original ~/CMSFormControls/Captcha/SecurityCode.ascx user control file.

If your project contains custom web forms or user controls that use the original SecurityCode.ascx file, you need to remove the related @ Register directives. You can continue using the <cms:SecurityCode> control from the CMS.FormEngine.Web.UI assembly.

If you have customized the ~/CMSFormControls/Captcha/SecurityCode.ascx file, it remains in the project with the .deleted extension. To continue using your modified security code control, remove the .deleted extension and register the file as a custom form control.

Kentico 11 setup files

The upgrade converts your web projects to version 11, 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 11 web projects.

To obtain the installer and setup files for Kentico 11:

1. Download the Kentico 11 installer.
2. Run Kentico_11_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

Important: This step must be performed before you apply any hotfixes to the upgraded project.

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.

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_100_110.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 11 licenses for the domains used by your sites:

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

Macros

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

1. Sign 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.

51Degrees device detection

51Degrees device detection is no longer included in Kentico 11 by default, and is replaced by the functionality of the .NET Framework HttpBrowserCapabilities class. If you want to continue using device macros (on the live site, in device profiles, in transformations, etc.), you have two options:

• Utilize the system’s default functionality (properties of the HttpBrowserCapabilities class)

  • Update your device macros from the CurrentDevice.<property> format to: CurrentDevice.Data[“<property>”]
  • Use properties of the HttpBrowserCapabilities class. Some of the original 51Degrees properties may not be available and some may be named differently.– OR –

• Integrate 51Degrees through NuGet packages

  • Update your device macros from the CurrentDevice.<property> format to: CurrentDevice.Data[“<property>”]
  • Alternatively, register a custom CurrentDevice class and use the original macro format.

Additionally, the Current device is mobile and Current device max screen size is in range macro rules were removed. If you need to replace them, integrate 51Degrees and create your own custom rules. You also need to update and re-save any existing macro condition fields that use the given rules.

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.).

E-commerce – Getting the final price of purchases

After upgrading, the system stores the final price of purchases in the new GrandTotal field of shopping cart objects instead of the TotalPrice field. The TotalPrice field remains available, but does not include reductions from gift cards.

The change affects both the API and macro expressions. We recommend that you replace occurrences of the TotalPrice field with GrandTotal in:

• Any custom code working with ShoppingCartInfo objects (use the GrandTotal property instead of TotalPrice)
• Macros accessing the total price from the shopping cart, for example: {% EcommerceContext.CurrentShoppingCart.GrandTotal %}
• Macros accessing the total price in invoices or order notification email templates, for example: {% GrandTotal.Format(Currency.CurrencyFormatString) %}

E-commerce – Product price transformations

Kentico 11 introduces many changes that affect the processing of product prices. After applying the upgrade, you need to check the transformations used on your site and replace any invalid code for getting product prices and other related values.

The supported signatures of the following ASCX transformation methods were changed. See Reference - Transformation methods for details.

• GetSKUPrice
• GetSKUFormattedPrice
• GetSKUListPrice
• GetSKUFormattedListPrice
• GetSKUPriceSaving
• GetSKUFormattedPriceSaving

Most of the methods can now only be called without parameters. The parameters from previous versions are no longer necessary – the methods always calculate with any catalog discounts that apply and taxes are handled according to the site’s Prices include tax setting. If you wish to load price values from custom columns, you need to customize the system as described in Customizing product prices (the customizations apply to transformation methods).

For Text / XML type transformations, we recommend replacing occurrences of the GetPrice macro method with the GetSKUPrice method. See Reference - Macro methods.

E-commerce – Invoice and email notification templates

Item tax transformations

Kentico 11 no longer stores or displays tax values separately for individual items in shopping carts and orders (only the total overall tax). Instead, entire sites can be configured to include taxes directly in the prices of items (using the Prices include tax setting ).

If you use custom transformations for ContentTable data in invoices or e-commerce email templates, you may need to remove transformation code that works with tax values (the UnitTotalTax, TotalTax, UnitTotalTaxInMainCurrency and TotalTaxInMainCurrency data fields).

Tax summaries

The ContentTaxesTable and ShippingTaxesTable macro objects are no longer available in the context of invoices or e-commerce email templates.

After upgrading, you need to update your store’s invoice configuration and email templates (if custom) to use the new TaxSummary object instead. If you use custom transformations to format the tax items, you also need to update their code to use the new properties available for the items within TaxSummary:

Product coupons and Buy X Get Y discounts

The DiscountCoupon macro object and OrderRelatedDiscountSummaryItems macro collection are no longer available in the context of invoices or e-commerce email templates.

If you display detailed information about applied product coupons or Buy X Get Y discounts, update your store’s invoice configuration and email templates to use the DiscountSummary property, which you can access in the transformations applied to individual order items within the ContentTable data.

The DiscountSummary collection contains items with Name and Value properties (the name of the applied product coupon or Buy X Get Y discounts, and its total discount value for the given order item).

E-commerce – Shopping cart totals

After upgrading, the Shopping cart totals web part no longer supports the following options for its Total to display property:

• Products excl. tax total
• Products tax total
• Shipping excl. tax total
• Shipping tax total
• Buy X Get Y and Order discounts total
• Buy X Get Y and Order discounts summary
• Discounts total

Any instances of the web part using the removed options will not display any content. You need to re-configure the web parts and set the Total to display property to the Products total , Shipping total or Order discounts total options instead.

The Products total and Shipping total values now automatically include tax (or not) according to the site’s Prices include tax setting . The web part no longer provides a way to display the product or shipping portion of the tax, only the overall Tax total for the entire shopping cart.

Buy X Get Y discounts are now applied to individual shopping cart items, not the entire cart. For more information about displaying discount totals and summaries on shopping cart pages, see Displaying shopping cart details on pages.

E-commerce – Coupon codes

Kentico 11 allows customers to enter multiple coupon codes when making purchases.

The web part that allows customers to enter coupon codes on pages was renamed from Discount coupon to Coupon codes and now requires a transformation to display the applied coupon codes. When upgrading sites that contain the web part, you need to:

1. Prepare a suitable transformation for displaying coupon codes according to your site’s design. See Working with coupon codes for more information.
2. Configure every instance of the Coupon codes web part and assign the transformation.

Additionally, t he ShoppingCartCouponCode and HasUsableCoupon properties of shopping cart objects, and the OrderCouponCode property of order objects were removed. The change affects both the API and macro expressions. If you used these properties to display coupon codes on your site’s pages, we recommend displaying the related discounts instead as described in Displaying shopping cart details on pages.

E-commerce – Tax classes for products under workflow

Kentico 11 allows assigning of only one tax per product.

The upgrade procedure cannot automatically handle that tax class assignment for products under workflow, which store the related data in the page version history. The tax class may be displayed as (none) for such products. We recommend checking any products under workflow and manually assigning an appropriate tax class.

E-commerce – Order discount macro conditions

The upgrade makes the following changes to the default order discount macro rules:

• Shopping cart contains product and Shopping cart contains products – removed. Use the new Order contains products rule instead.
• Total weight of order is under – macro condition updated.

If you use the removed or updated macro rules in the conditions of existing discounts, you need to update and re-save the conditions.

For any custom order discount rules, you need to update the Condition macro code to reflect the following changes:

• The ShoppingCart object is no longer available when writing order discount rule conditions. Instead, the macro context directly provides properties related to the shopping cart or order calculation, such as Currency, Customer, PaymentOption, ShippingOption, GrandTotal, etc.
• To check whether an order contains specific products, call the Data.ContainsProducts macro method.

E-commerce – PayPal payment gateway

Kentico 11 changes the functionality of the default PayPal payment provider. See Configuring PayPal to learn about the new requirements, configuration steps, and settings.

The following is a summary of the changes:

• The provider now requires a PayPal Business account and an associated PayPal REST API app (create and manage apps in the PayPal Developer Portal).

• Settings in Settings -> E-commerce -> Payment Gateways -> PayPal:

  • The original Business setting was removed.
  • New required settings for entering the Client ID and Client secret API credentials of the PayPal REST API app.
  • The Return URL and Cancel return URL settings are now always required.
  • New Transaction type setting that allows you to use either direct payments or authorization with delayed capture.
  • The original Notify URL setting was removed (the provider no longer utilizes Instant Payment Notification).
  • To perform test payment transactions, set the new Account type setting to Sandbox and use Sandbox API credentials.

• The new PayPal payment execution web part must be placed onto the page specified by the Return URL setting.

• The Payment gateway URL property no longer has any effect for payment methods that use the default PayPal provider.

• The default PayPal provider no longer utilizes Instant Payment Notification and the ~/CMSModules/Ecommerce/CMSPages/PayPalIPN.aspx system page was removed. If you require payment notifications for any custom functionality or integrations, you need to configure the related options for your PayPal Business account and implement the required handlers (either within the Kentico web project or a custom project).

E-commerce – Authorize.Net payment gateway

Kentico 11 changes the functionality of the default Authorize.Net payment provider. See Configuring Authorize.NET to learn about the new requirements, limitations and configuration steps.

The following is a summary of the changes:

• Your website must use HTTPS and the server (IIS) must support the TLS 1.2 protocol.

• The default Authorize.Net provider can only process payments correctly for a single currency (every Authorize.Net account is configured to use one specific currency in the Authorize.Net Merchant Interface). If your store uses multiple currencies:

  • Important: The system always sends price values to Authorize.Net in the currency selected by the customer for the given order (shopping cart). If this currency is different than the one configured for your Authorize.Net account, the customer will be charged an incorrect (unconverted) amount of money.
  • You can customize the system to offer the Authorize.Net payment method to customers only if they have the appropriate currency selected – follow the general approach described in Making payment methods dependent on shipping options.

• You need to update the Payment gateway URL property of your Authorize.Net payment method:

  • For real payments on production websites: https://api.authorize.net/xml/v1/request.api
  • For test transactions (sandbox account): https://apitest.authorize.net/xml/v1/request.api

• Settings in Settings -> E-commerce -> Payment Gateways -> Authorize.NET:

  • The Use test mode setting was removed. To perform test payment transactions, use the API login and Transaction key of a Sandbox account and the appropriate Payment gateway URL for the payment method.
  • New Transaction type setting that allows you to use either direct authorize and capture transactions or authorization with delayed capture.

Browser-specific CSS styles

The browser-related CSS classes that the system automatically assigns to the <body> element of pages work differently in Kentico 11:

• Browser version classes are not assigned at all
• Browser type classes may be different than in previous versions (the HttpBrowserCapabilities class of the .NET Framework is now used for browser detection)

See Browser and language-specific styles for more information.

If your website uses custom CSS that relies on the <body> browser classes, you need to update your stylesheets.

Multi-factor authentication

The multi-factor authentication in Kentico 11 no longer supports the original Kentico Authenticator mobile application. Instead, passcodes can be generated by any authenticator application using the Time-based One-time Password Algorithm (TOTP). See Configuring multi-factor authentication for details.

The upgrade resets the multi-factor secret key (token) of each user. If your website has users who sign-in with multi-factor authentication, inform them that they need to set up a different authenticator application for generating passcodes, for example Google Authenticator. The system displays a new secret key during each user’s first sign-in, which can be used to initialize an authenticator application.

Translation services

Translations.com service

When upgrading sites with an already set up translation project using the Translations.com service, you need to contact a Translations.com representative and inform them about the upgrade to Kentico 11. Translations.com will update the configuration of your Project Director.

Microsoft Translator service

The authentication process for the Microsoft translator service changed, as the service moved from Microsoft DataMarket to Microsoft Azure. If your website already uses the Microsoft translator service, follow the instructions at Machine translation - Microsoft Translator to properly configure the service. 

REST authentication hash values

Kentico 11 generates authentication hash values differently for REST URLs containing a virtual directory. If your site’s URL contains a virtual directory and you use REST requests with hash authentication, you need to generate new authentication hashes in the Settings application and replace the values in your requests.

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\11.0\Upgrade100_110 by default), and copy the CMS\CMS\CMSSiteUtils\Import\Upgrade_100_110.zip file into the CMS\CMSSiteUtils\Import folder of the new Kentico 11 project.
7. Perform all relevant steps after the upgrade.