Sunday 2 April 2017

XML provider for Sitecore Data Exchange Framework 1.3 - Part 2

Leave a Comment
In the previous blog post, I have explained about Sitecore Data Exchange Framework 1.3 and how to build XML provider for Data Exchange Framework. In this blog post, I’ll explain how to create and populate Sitecore items from the contents of a XML stream using XML provider for Data Exchange Framework 1.3.

I’ve created a XML file from this web address that contains information about different Music CDs. Each CD node in the XML file represents a single music CD. Each CD will be represented in Sitecore as an item. The synchronization process will read the music CDs information from the XML file and create Sitecore items for each. If a Sitecore item already exists for a CD in the file, the Sitecore item will be updated with the information from the file.
<CATALOG>
 <CD>
  <TITLE>Empire Burlesque</TITLE>
  <ARTIST>Bob Dylan</ARTIST>
  <COUNTRY>USA</COUNTRY>
  <COMPANY>Columbia</COMPANY>
  <PRICE>10.90</PRICE>
  <YEAR>1985</YEAR>
 </CD>
 <CD>
  <TITLE>Hide your heart</TITLE>
  <ARTIST>Bonnie Tyler</ARTIST>
  <COUNTRY>UK</COUNTRY>
  <COMPANY>CBS Records</COMPANY>
  <PRICE>9.90</PRICE>
  <YEAR>1988</YEAR>
 </CD>
</CATALOG>

Using XML provider for Data Exchange Framework 1.3

  1. Make sure that Data Exchange Framework 1.3 Sitecore package and Sitecore Provider for Data Exchange Framework 1.3 Sitecore package are installed in your Sitecore 8.2 instance.   
  2. Download XML Provider for Sitecore Data Exchange Framework-1.3 Sitecore package and install in your Sitecore 8.2 instance.
  3. Create a XML file. I’ve uploaded one sample XML file here. You may place this file wherever you want, but it must be accessible from your Sitecore server.
  4. In Sitecore, open Content Editor. Navigate to sitecore > system > Data Exchange. Create a new item using Empty Data Exchange Template and name it as XML Provider CD Catalog Tenant.

  5. Tick the checkbox for field Enabled.

  6. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Endpoints/Providers. An endpoint is needed to identify the source file within the synchronization process. First we must create the folder into which XML system endpoints can be added. Create new item using template XML Systems Endpoints Root. This template is a command template. It does not prompt for the item name. The command template assigns the item name automatically.

  7. Next we must add an endpoint to the folder. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Endpoints/Providers/XML System. Create a new XML System Endpoint and name it as CD Catalog XML System Endpoint.

  8. In XML Path field, enter the path of XML file. I’ve placed XML file into root folder of website. The path can be either a local XML file or a web address returning XML Data (http or https).
  9. In XML Node Name field, enter name of XML node which will be used to get a collection of matching nodes from XML Data.  I’ve entered CD as XML Node Name.


  10. Add Value Accessor Set for Source. The source object is a XML Node <CD> which holds the child nodes <TITLE>, <ARTIST>, <COUNTRY>, <COMPANY>, <PRICE> and <YEAR>. The value accessor set defines the values that are available in XML Node <CD>. First we must create the folder into which the value accessor set can be added. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Data Access/Value Accessor Sets/Providers. Create new item using template XML System Value Accessor Sets Root. This template is a command template. It does not prompt for the item name. The command template assigns the item name automatically.

  11. Next we must add a value accessor set to the folder. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Data Access/Value Accessor Sets/Providers/XML System. Create new XML Element Value Accessor Set and name it as CD Catalog Information Fields.

  12. Next we must add value accessor items to the value accessor set. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Data Access/Value Accessor Sets/Providers/XML System/CD Catalog Information Fields. Create Value Accessor items for child nodes <TITLE>, <ARTIST>, <COUNTRY>, <COMPANY>, <PRICE> and <YEAR> using XML Element Value Accessor template. Enter Child Node name in XML Element Name field.



  13. Create Template for Target. A Sitecore template is needed to represent the data that is read from the file. Items based on this template are created using the data that is read from the file. Navigate to /sitecore/templates/User Defined. Create new template CD Catalog Item as shown below:
     
  14. Add Folder to hold new Sitecore Items. The result of the synchronization process is that Sitecore items will be created for each XML Node <CD> in the XML file that is read. A parent item is needed for these new Sitecore items. In Content Editor, navigate to /sitecore/Content. Create new folder and name it as CD Catalog.

  15. Add Endpoint for Target. An endpoint is needed to identify the Sitecore database within the synchronization process. First we must create the folder into which file system endpoints can be added. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Endpoints/Providers. Create new Sitecore Endpoints Root item. This template is a command template. It does not prompt for the item name. The command template assigns the item name automatically.

  16. Next we must add an endpoint to the folder. Create new item using Sitecore Item Model Repository Endpoint and name it as Sitecore Database Endpoint.

  17. Add Value Accessor Set for Target. The target object is a Sitecore item. The value accessor set defines the fields that can be set on the item. First we must create the folder into which the value accessor set can be added. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Data Access/Value Accessor Sets/Providers. Create new Sitecore Value Accessor Sets Root item. This template is a command template. It does not prompt for the item name. The command template assigns the item name automatically.

  18. Next we must add a value accessor set to the folder. Create new item using template Sitecore Item Field Value Accessor Set and name it as CD Catalog Information Item.

  19. Next we must add value accessor items to the value accessor set. These represent the fields that can be set on the Sitecore item that is the target object in the mapping process. Create Value Accessor items for Sitecore item fields TITLE, ARTIST, COUNTRY, COMPANY, PRICE and YEAR using Sitecore Item Field Value Accessor template. Set field value to corresponding field of Target Sitecore item template.

  20. Add Value Mapping Set. The value mapping set is where you associate each value accessor from the source object with one from the target object. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Value Mapping Sets. Add new Value Mapping Set and name it as XML CD Catalog Data to Sitecore CD Catalog Item.

  21. Navigate to /sitecore/system/Data Exchange/XML CD Catalog Tenant/Value Mapping Sets/XML CD Catalog Data to Sitecore CD Catalog Item and create value mapping item to associate each value accessor from the XML object with one from the target Sitecore object.

  22. Add Pipeline to Sync Single Record from Source. The synchronization process we are modeling consists of two pipelines. The first pipeline reads data from a source object, which is a XML file. The second pipeline handles a single XML node <CD> from the XML source. The first pipeline calls the second pipeline, we must configure the second pipeline before we can configure the first. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Pipelines. Create new pipeline and name it as CD Catalog XML Data to CD Catalog Sitecore Item Sync Pipeline.

  23. Add Pipline Step to Resolve Target Item. The first pipeline step determines whether or not a Sitecore item already exists for the XML Node <CD> from the XML file. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Pipelines/CD Catalog XML Data to CD Catalog Sitecore Item Sync Pipeline. Create new item using template Resolve Sitecore Item Pipeline Step and name it as Resolve CD Catalog Information Item.

  24. Set the following field values of Resolve CD Catalog Information Item:

  25. Add Pipeline Step to Apply Mappings. The second pipeline step applies the value mapping set we configured in Add Value Mapping Set. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Pipelines/CD Catalog XML Data to CD Catalog Sitecore Item Sync Pipeline. Create new item using Apply Mapping Pipeline Step template and name it as Apply Mapping.
  26. Set the following field value:
  27. Add Pipeline Step to Update Sitecore Item. The target object represents a Sitecore item, but it is not, itself, a Sitecore item. The actual Sitecore item must be updated. A pipeline step must be configured in order for this to happen. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Pipelines/CD Catalog XML Data to CD Catalog Sitecore Item Sync Pipeline. Create new item using Update Sitecore Item Pipeline Step template and name it as Update Sitecore Item.

  28. Set the following field value:

  29. Make sure the pipeline steps are in the following order:
    a.    Resolve CD Catalog Information Item
    b.    Apply Mapping
    c.    Update Sitecore Item

  30. Add Pipeline to Read Source. We just configured the pipeline CD Catalog XML Data to CD Catalog Sitecore Item Sync Pipeline, which handles a single XML node <CD> from a XML file. Now we must configure the pipeline that reads the data from the file, and handles each XML node <CD> by passing it to CD Catalog XML Data to CD Catalog Sitecore Item Sync Pipeline. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Pipelines. Create a new pipeline and name it as Read CD Catalog Information from XML Data Pipeline.

  31. Add Pipeline Step to Read from Source. The first pipeline step reads the text file configured in the endpoint. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Pipelines/Read CD Catalog Information from XML Data Pipeline. Create a new item using template Read XML Data Pipeline Step and name it as Read XML Data.

     
  32. Set the following field value:

  33. Add Pipeline Step to Iterate Data from Source. The second pipeline step iterates the data from the XML field. For each row, another pipeline is run. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Pipelines/Read CD Catalog Information from XML Data Pipeline. Create new item using Iterate Data and Run Pipelines Pipeline Step template and name it as Iterate Rows from XML Data and Run Pipeline.

  34. Set the following field value:

  35. Make sure the pipeline steps are in the following order:
    a.    Read XML Data
    b.    Iterate Rows from XML Data and Run Pipeline

  36. Add Pipeline Batch. A pipeline batch is used to run pipelines. A pipeline batch can be run manually, through the Sitecore task scheduler or through the Data Exchange Framework API. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Pipeline Batches. Create new item using template Pipeline Batch and name it as CD Catalog Information XML Data to CD Catalog Information Item Sync Pipeline Batch.

  37. Set the following field value:

  38. Test Pipeline Batch. The pipeline batch is ready to run. Navigate to /sitecore/system/Data Exchange/XML Provider CD Catalog Tenant/Pipeline Batches/CD Catalog Information XML Data to CD Catalog Information Item Sync Pipeline Batch. In the Content Editor ribbon, click Run Pipeline Batch.
  39. Click OK.
  40. In the pipeline batch summary you should see messages like the following:

  41. In Content Tree, you see 26 items at /sitecore/content/CD Catalog location.

  42. Each CD Catalog item should have its fields populated. The following is an example of Big Willie style item.

Note:
  • If you change the XML file and run the pipeline batch again, the Sitecore items will be updated.
  • If you remove a XML node <CD> from the XML File, the corresponding Sitecore item will not be deleted. We did not implement any logic to do this.
  • If we change the identifier value (Title field in our XML example) for an existing XML node <CD>, a new Sitecore item will be created.
  • In addition, the identifier value in the XML file must be unique. Duplicate identifiers will result in duplicate Sitecore items and not all of the duplicate Sitecore items will be synchronized.
  • If you change a field value on a Sitecore item, that value will be overwritten the next time the pipeline batch is run. In order for changes to the Sitecore item to result in the text file being updated, we must extend XML provider.
  • One thing that is important to realize is that this implementation is a very simple example and is by no means fool-proof. The code as it is would be useful in cases where you have control over the XML files that are provided.  This provider might not work as expected if you have nested child nodes in XML document but you can extend the provider as per your requirement. Source code is already available on GitHub
  • Sample test tenant Sitecore package can be downloaded from here.
  • Provider is available on Sitecore Marketplace as well.
Comments and suggestions are most welcome. Happy coding!

0 comments :

Post a Comment