Upgrade Data Exchange Framework on-prem

Abstract

How to upgrade Data Exchange Framework in an on-prem Sitecore installation.

Starting with Sitecore Experience Platform (SXP) version 10.2, you can upgrade from any previous Data Exchange Framework (DEF) version directly to DEF version 7.0.

Important

Starting with Sitecore 10.2, you must upgrade all modules, including the DEF connector module, as part of the overall Sitecore upgrade process.

This topic assumes you are upgrading Sitecore from a previous release to Sitecore 10.2 and DEF 7.0.

Before you can upgrade DEF to version 7.0, you must:

To upgrade DEF you must clean up your Sitecore databases. This is a one-time operation that you must perform when you upgrade from a previous version of Data Exchange Framework (DEF). Then you can install the new version of DEF on top of the old version.

Note

In Sitecore 10.1 and earlier, DEF items were stored in the databases. Starting with Sitecore 10.2 DEF items are stored as resources instead.

To upgrade DEF:

  1. Follow the Sitecore 10.2.0 Upgrade Guide for Sitecore Experience Platform to install and set up the Sitecore.UpdateApp tool.

  2. Download the Data Exchange Framework Upgrade resources package, and extract it to a local directory, keeping the folder structure intact.

  3. Navigate to the Data Exchange Framework Upgrade resources.1.0.0\<version>\Data\Items folder for the version you are upgrading from. Copy the .dat files that are included in the core, master, and web folders to the corresponding folder paths under \Sitecore.UpdateApp\. For example:

    • Copy the Data\Items\core\items.core.def.dat file, and paste it in the \Sitecore.UpdateApp\Data\Items\core folder.

    • Copy the Data\Items\master\items.master.def.dat files and paste it in the \Sitecore.UpdateApp\Data\Items\master folder.

    • Copy the Data\Items\web\items.web.def.dat file, and paste it in the \Sitecore.UpdateApp\Data\Items\web folder.

    Note

    Each folder under the path \Sitecore.UpdateApp\Data\Items\ now contains two files, that is, the file you just copied and the items.<master/web/core>.dat file.

  4. Open the Data Exchange Framework Upgrade resources 1.0.0\<version>\Data\ folder.

  5. In the Data folder, navigate to the Items\core\localization folder, copy all the .dat files, and paste them in the \Sitecore.UpdateApp\Data\Items\core\localization folder.

  6. In the Data folder, navigate to the Items\master\localization folder, copy all the .dat files, and paste them in the \Sitecore.UpdateApp\Data\Items\master\localization folder.

  7. In the Data folder, navigate to the Items\web\localization folder, copy all the .dat files, and paste them in the \Sitecore.UpdateApp\Data\Items\web\localization folder.

  8. In the Sitecore.UpdateApp\App_config folder, update the ConnectionStrings.config file with the connections to your databases. If you do not have a security database, use the connection to the core database for the security connection string.

    Note

    If you have more than one Web database, you must repeat Step 8 for every Web database.

    You must update the connection string to each Web database as you run the tool, and not change the connection strings to the other databases.

  9. Follow the steps in the Upgrade Guide for Sitecore Experience Platform to run the update tool. Check the logs in the Data\logs folder for detailed information about any modified items that were skipped by the clean up. The update tool displays the number of items it removed in the command prompt window. For example:

    Command prompt window displaying the number of items removed by the update tool
  10. On all the servers where you have DEF installed, follow the instructions in Installing Data Exchange Framework to install the new version of DEF on top of the old version.