Hi there,

Over the past months I’ve been working on multiple Sitecore 8.2 to Sitecore 9.3 upgrades where Data Exchange Framework was involved. These upgrades even had as a result that I forked the Sitecore.DataExchange.Gutters project on Github, which gives you a couple of nice Gutters for the Sitecore Data Exchange Framework, and which I upgraded being compliant with Sitecore 9.3 and Sitecore 10 (blogged about that here and here).

In this short blogpost I would like to describe a couple of quick things I’ve encountered with each upgrade from DEF 1.4.1 to 4.0.0 (for Sitecore 9.3) and might save you some time when doing a DEF upgrade. In the post below I’m not going through any breaking code changes, you’ll notice these when you upgrade your NuGet reference to the latest DEF version of 4.0.0 and compile the project, but in this blogpost I’m going to update you on some DEF item configurations you have to do to run your old pipeline steps successfully.

The first one is the fact that a couple of templates changed the fieldtype for certain fields, that point to a list of Pipeline Context Storage Locations, from type Droplist to a Droplink. Since Sitecore changed the type, the storage of the value in Sitecore is different. A Droplist stores the name of the items. It allows the editors to select one value from the dropdown list. Droplist is similar to Droplink, the only difference is – Droplist stores the item name while the Droplink stores the ID of the item.

Here’s the list of template and fields that got changed from a Droplist to a Droplink:

  • ‘Can Resolve Identifier’ template – {496C871D-B223-441E-B657-B5D1B2398EA1}, Field: ‘IdentifierObjectLocation’ – {010E5D89-6409-4FBC-843B-CEB84C8ED3BB}
  • ‘Base Resolve Object Pipeline Step’ template – {279D5594-DA4A-49F6-A4FF-2CF04EEFE84C}, Field: ‘ResolvedObjectLocation’ – {5C061C42-FF86-4F43-B5AD-831DC03DC77D}
  • ‘Iterate Data and Run Pipelines Pipeline Step’ template – {0FD90877-C5A1-4A9A-B7D5-A8469CFA89B1}, Field: ‘DataLocation’ – {44AC03A6-54F0-42CA-9FD3-ACAA2A898A75}

So when having existing Pipeline steps, that inherit the above base templates, and are serialized as a development artifact with Unicorn or TDS, you will immediately notice that these pipeline steps throw errors when you run the corresponding Pipeline Batch. In the content editor these items will display the ‘The field contains a value that is not in the selection list’ message beneath these fields. Make sure to update these pipeline steps with the correct GUID of the Pipeline Context Storage Location.

As a recommendation I would advise you to search in your .item files (TDS) or .yml files (Unicorn) for ‘Pipeline Context Source’ or ‘Pipeline Context Target’ to quickly find the Sitecore DEF items you need to adjust to their respective Pipeline Context Storage Location GUID.

The second one is that the Update Sitecore Item Pipeline Step template – {B384FB2D-FBEF-4A8E-9572-FA5FB9F75A7D} got a new field called ‘ItemLocation’ – {53CA50C3-F968-47D4-B19F-9EF305F99403}. Unfortunately this template standard values didn’t set the ‘ItemLocation’ field value by default to the GUID of the ‘Pipeline Context Target’ item. When having a custom pipeline that is of this type, make sure to fill in the ItemLocation, else the values of the mapping won’t be written into the Sitecore item field that is created or updated. For more information see the ‘Add a pipeline step to update the target item’ on the Sitecore DEF documentation site.

If you want to get a good overview of a Sitecore Data Exchange Framework synchronization process, make sure to check out (even if it’s on Sitecore 8.2 with DEF 2.0) Neil Killen’s blogpost or do the Walkthrough: synchronizing data from a text file to Sitecore.

Happy upgrading and happy Sitecore-ing…

–Robbert