Blog Series: Unlocking xDB – Vol: #2  

Referenced Sitecore Version: Sitecore 8.1U3 – 8.2

---

---

Using List Manager’s CSV Upload to Create xDB Contacts with Custom Fields

Welcome back to Unlocking xDB! In the last blog post, we went through the process of creating a custom facet for contacts stored in xDB. Building upon our example, the Marketing Data facet that we want to maintain with contacts needs to be populated. One  way to populate this information is to upload your contact information by using a CSV file. This can be extremely useful if you want to seed xDB with a large number of contacts.

Overview

While this blog post is targeted on Sitecore 8.1U3 and 8.2, it’s worth noting that the following process to accomplish this task was introduced in Sitecore 8.1 Update 2.  Prior to Update 2, in  order to do this, was a much more convoluted and near impossible.

The process to adjust Sitecore to upload CSV files with custom fields, is relatively simple. In fact, it’s really only 2 or 3 steps.  However, some of this is working with Speak Applications. Out of scope of this blog post is providing insight into how List Manager SPEAK UI application works. I recommend following along with Martina Welanders’s 6 Part SPEAK Series for a great introduction to SPEAK.

The process consists of the following steps:

1. Prepare the CSV File
2. Add Fields to the Import Dialog Wizard
3. Add a Pipeline Processor
4. Import the CSV File

Step 1: Prepare the CSV File

Following along with our previous example, I’ve setup my CSV file to include my two Marketing Data fields, as well as the default fields used in the importer.  Here is what our CSV file looks like:

Walking through the CSV file we have 5 fields:

1. First_Name – OOTB Field
2. Last_Name – OOTB Field
3. Email – OOTB Field
4. CustomerId – New Field
5. Segment – New Field

A Quick Word About Identifiers in xDB

If you recall from the last blog post, I showed a snippet of a document from xDB. If you recall seeing an email address as the stated identifier, you’d be recalling correctly.  In case you forgot, here it is:

The reason I call this out is that an xDB Contact record can only have ONE identifier field.  This is basically the only field, besides the Document Guid, that Sitecore uses to identify a contact. Default functionality suggests that the Identifier is an email address as shown above. However, you’ll soon see that you can specify a DIFFERENT field as the Identifier when doing CSV uploads.  This provides an opportunity to use an identifier different from an email address. If your scenario needs or requires this configuration, you’ll want to make sure that you include this field into the CSV file. For the purposes of the example of this post, we will be utilizing the email address as our identifier.

Step 2: Add Fields to List Manager’s Import Dialog Wizard

Let’s start with an understanding of how List Manager works out of the box.  To start, launch Sitecore and click on List Manager in the dashboard. Once there, click on the big blue Create button in  the top left.  You’ll see a couple different options.  For these example, we’ll be focusing on Import contacts without creating a list but the functionality carries through for creating lists too.

A Brief Interruption To Show How to Use the CSV Uploader

Clicking on the “Import Contacts” option opens up the Import Dialog Wizard. Below is a gallery of the out of the box screens that you’ll see. I’ll walk through these.

This slideshow requires JavaScript.

1. Click on  Browse for a file.
2. It will open  up a file window to select a file.
3. Once  you select, it provides you an option to set a name. This name is  not used inn the “Import Only” option. But if we were creating a list, this would end up being the name of the list.
4. Click Upload File
5. It’ll upload the file.
   1. Protip: I’ve run into a wide range of issues with the upload button.  If you are having issues, try the following fixes:
      1. If you are getting a red error box, see Sitecore 8.1 List Manager – CSV Upload Error
      2. If it’s just not doing anything, and giving you Console issues:
         1. Check File system permissions for Application Pool User
         2. Log out of Sitecore, refresh  browsers, try again.
6. Click Next
7. This screen shows the field mapping screen. This is the screen we want to change. Also note the message at the top about the identifier. Clicking this check box will reveal an extra field (See Circle 9 and 10).
8. Note here the standard fields that get mapped out of the box.
9. Note the Identifier Field as discussed above.
10. Okay, let’s uncheck this field.
11. Choose the appropriate field from the drop down for each field.  The drop down will read from the 1st line of the CSV file for Headers.
12. Click Next
13. The message on the last screen at the top is just a reminder that the contacts and any created lists will not immediately show up until indexing finishes.
14. Finally, note the number of contacts that were update.
    1. Note: If a xDB Contact is currently logged in, and you are trying to make an update to their record, the Contact record is considered locked, and the CSV uploader will not update. And no, it won’t even queue.
15. Click Finish and you are done.

We Now Return To Normal Programming

So now that I’m confident you know how to use List Manager to upload a CSV file, let’s continue adding custom fields.  Here’s the fun part:

1. Log Into Sitecore
2. Click Desktop
3. Switch the Database to Core.
   1. Yup, we’ll be editing the Core database.
   2. All items associated to SPEAK UI Applications are always kept in  the Core database.
4. Navigate to the following Path: /sitecore/client/Applications/List Manager/Dialogs/ImportWizardDialog/PageSettings/TabControl Parameters/Map/ImportModel
5. Here you’ll see the following Items:
   1. 
6. These Items are based on the template ImportModelField
7. Looking at one of these fields, we see the following
   1. 
8. Note the syntax of the Datafield.
   1. facet: Name of the Facet you want to save to.
   2. property: Attribute Name from  Facet/Element Implementation. (Protip:  Make sure you use the exact same value as the constant that was created for the attribute in the previous blog)
9. Alright, so Duplicate as many times as you need in order to create the additional fields you need. In our example, we’ll do this twice.
10. Go ahead and do that, I’ll wait right here.
11. 
12. We’ve now created two additional fields, and you’ll see that the facet has been named Marketing Data which is what we named our facet in the Facet patch config.
13. Other Fields On This Item
    1. FieldName – Set this to the field that’s related in your CSV File.
       1. This is not a requirement, but helps with Automapping.
    2. DataField – explained above. Case matters.
    3. Required – If the field is required or not. If this is marked, and the value is not in the CSV file, the contact will be skipped.
    4. AutoMap/AutoMapSource – Check these if you want the importer to attempt to automatically map the CSV source field names to the FieldName on the item.
14. Okay, let’s stop here. Because Step 2 is done!

Step 3: Add a Pipeline Processor

This is going to be the easiest step ever, because the processor is already created. All you need to do is create a patch config to reference a new processor.

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
	<sitecore>
		<pipelines>
      <group groupName="analytics.bulk.contact">
        <pipelines>
          <updateFields>
            <processor type="Sitecore.ListManagement.Analytics.Data.Bulk.Contact.Pipelines.UpdateFields.DeepCopyFacet`1[[SitecoreHacker.Sandbox.Facets.IMarketingData, SitecoreHacker.Sandbox]], Sitecore.ListManagement.Analytics">
                <param desc="facetName">Marketing Data</param>
              </processor>
          </updateFields>
        </pipelines>
      </group>
		</pipelines>
	</sitecore>
</configuration>

1. Change the type to the interface of your IFacet
2. Change the description  of the facetName.

Step 4: Import the CSV File through List Manager

1. Now head back to the CSV Import Wizard in  List Manager: (Protip: Make sure you switch back to Master database)
   1. 
   2. Notice that the new fields mappings now show.
   3. Also note the order of the fields.  The order of these mappers is directly related to the order of the items in  the Core database that we just added.
2. Select the appropriate field names out of the drop down box for each of these fields, and press next.
3. And if everything goes well, you’ll see that contacts were updated!
   1. 

1. We are done! We have now mapped our custom CSV fields to our Custom xDB Contact Facet.

Validating Our Contacts and Facets

Now that we’ve imported our CSV, let’s take a peek into xDB MongoDB and see if our facet was populated.  If everything works right, and you’ve followed these blog posts to the letter, you’ll see what I see:

And that’s it!

Unlocking xDB Continues

In the next installment of Unlocking xDB, we’ll explore the conversion of Sitecore Contacts to xDB Contacts and take a peek at what it will take to carry over custom profile fields into implemented custom facets.