Product DocsMenu

Defining a Sitecore Mapping File for the Legacy Connector

Deprecated

Sitecore metadata can be organized in various ways. Depending on how the metadata is organized, it might be difficult for the Sitecore connector to retrieve all the fields that compose a Sitecore item.

Example: A single Sitecore item can be composed of multiple fields as well as multiple references to other Sitecore items. Those referenced items can also have many fields and references, etc.

This topic explains how you can write an XML mapping file which can be used to map metadata fields to CES fields. You can also use this file to modify the way referenced Sitecore field values are resolved.

Example: You can change the clickable URL of indexed elements using a mapping file when the Index if no Layout source option is enabled (see Index if no Layout).

The following code presents a basic XML structure of a mapping file.

<?xml version="1.0" encoding="utf-8" ?>
<Sitecore>
  <CommonMappings>
    <Fields>
      <FieldName>mapping value</FieldName>
    </Fields>
  </CommonMappings>
  <Mapping template="{00000000-0000-0000-0000-000000000000}">
    <Fields>
      <FieldName>mapping value</FieldName>
    </Fields>
  </Mapping>
  <Mapping item="{00000000-0000-0000-0000-000000000000}">
    <Fields>
      <FieldName>mapping value</FieldName>
    </Fields>
  </Mapping>
  <Ignore template="{00000000-0000-0000-0000-000000000000}">
  <Ignore item="{00000000-0000-0000-0000-000000000000}"> 

<CommonMappings>

Defines field mappings that apply to all Sitecore items.

<Mapping>

Defines field mappings that apply to all Sitecore items that use the templates specified in the template attribute. Field mapping can also be applied directly on items by specifying the item attribute. Templates and items are identified by their Sitecore ID (GUID) and separated by a pipe (|) character. If both attributes are set, only the template attribute is considered. It is a better approach to set mappings on templates rather than on items.

<Ignore>

Specifies templates and items that should be ignored by the connector. Templates and items are identified by their Sitecore ID (GUID). Each entry accepts only one template or item. If both attributes are set, only the template attribute is considered.

<FieldName>

Defines the field targeted by the mapping. The name of the entry corresponds to the name of the Coveo system or custom field defined in the field set used by the source.

mapping value

This value is the mapping itself. It is composed of free text and metadata tags. The connector supports different metadata tag syntaxes:

  • %[<metadata>]

  • %{<metadata>:<mapping value>}

  • @[<fully_qualified_class_name>].

The metadata tag syntaxes are illustrated in the following examples.

Example: The following mapping tells the connector to set the Title field of a document with the value of the _CESSCDisplayName metadata. This applies to all Sitecore documents. It is possible to browse the item hierarchy using the referenced metadata fields.
<?xml version="1.0" encoding="utf-8" ?>
<Sitecore>
  <CommonMappings>
    <Fields>
      <Title>%[_CESSCDisplayName]</Title>
      <Body>%[Description]</Body>
    </Fields>
  </CommonMappings>
</Sitecore> 
Example: A Sitecore item is based on the Book template. This template defines a Contributor field which is a reference to a Person item somewhere else in the content tree. The Person item contains several fields, including the Firstname and the Lastname fields.

Here are the different possibilities:

  • The mapping file is left as is, so the metadata Contributor is ignored. This is the default connector behavior.

  • The Index the document’s metadata source parameter is selected, so the Contributor metadata is indexed and contains a reference to the Person item (GUID).

  • The mapping file is updated such that the Firstname and Lastname fields are concatenated to form the full name of the contributor, which is then put into the Contributor custom field.

    <?xml version="1.0" encoding="utf-8" ?>
    <Sitecore>
      <Mapping template="{AF0AD32B-8188-45E0-B354-5226F41D801B}"> <!--BookTemplate-->
        <Fields>
          <Contributor>%[Contributor.Lastname], %[Contributor.Firstname]</Contributor>
        </Fields>
      </Mapping>
    </Sitecore> 
    

    When the field Contributor is a multiple value reference (i.e., the book might have more than one contributor), the user can tell the connector to concatenate the values by using the following mapping syntax %{<metadata>:<mapping value>}:

    <?xml version="1.0" encoding="utf-8" ?>
    <Sitecore>
      <Mapping template="{AF0AD32B-8188-45E0-B354-5226F41D801B}"> <!--BookTemplate-->
        <Fields>
          <Contributors>%{Contributor:%[Lastname], %[Firstname]}</Contributors>
        </Fields>
      </Mapping>
    </Sitecore>

Multiple value references can be organized by template.

Example: In the Nicam demo site (default demo website installed with Sitecore), a camera contains a field called Accessories. These accessories are built from different templates: Lenses, Flash, or Other Accessories.

To organize the value references by template, use the following syntax %{<metadata|template ID1|template ID2|…>:<mapping value>}. Template IDs must be used without the curly brackets {, }:

<?xml version="1.0" encoding="utf-8" ?>
<Sitecore>
 <Mapping template="{B072B7C7-6F3F-4316-B8D7-010629AEBEF1}"> <!--SLR-->
  <Fields>
   <Accessories>%[Accessories.Title]</Accessories>
   <Lenses>%{Accessories|8FAC8E12-7459-43F8-97E8-1BC6840B9226:%[Title],%[Focal length]}</Lenses >
   <Flash>%{Accessories|95681CF6-3635-49EC-A09A-CC548FA62389:%[Title],%[Guide number]}</Flash>
   <Misc>%{Accessories|A93FA2C4-3AE4-45C2-8C3F-EFA7E129537E:%[Title]}</Misc>
  </Fields>
 </Mapping>
</Sitecore> 

Finally, the mapping can be handled programmatically by using the @[<fully_qualified_class_name>] syntax. The connector can then use a custom class to resolve a field value if none of the out-of-the-box mapping solutions match your needs. Although this can be a slower approach (the connector has no control over code execution inside the class), it is a very powerful way to resolve mappings when complex rules apply.

Example: A Sitecore item has the following fields: long description, short description, title and name. Only the name is required in Sitecore, but you want to use the long description as well as the short description if one of them is present. If not, you will use the title before the name.
<?xml version="1.0" encoding="utf-8" ?>
<Sitecore>
  <Mapping template="{AF0AD32B-8188-45E0-B354-5226F41D801B}"> 
    <Fields>
      <Description>@[MyNamespace.MyDescResolver, MyAssembly]</Description >
    </Fields>
  </Mapping>
</Sitecore> 

This is the code of the class contained in MyAssembly.dll used to resolve the description field:

using System;
using System.Collections;
using System.Collections.Generic;
using Coveo.CES.CustomCrawlers.Sitecore.ContentService;
using Coveo.CES.CustomCrawlers.Sitecore.Interfaces;

namespace MyNamespace {

public class MyDescResolver: ISitecoreMappingResolver
{
    [CLSCompliant(false)]
    public string ResolveMapping(ContentItemMeta p_Meta, 
                                 Hashtable p_ProcessedMeta,
                                 List<string> p_MediaReferences)
    {
        string desc = null;
        string shortdesc = null;
        string title = null;

        foreach (ContentItemField field in p_Meta.Fields) {
            if (field.Name == "long description") {
                desc = field.Value.StringValue;
	            } else if (field.Name == "short description") {
                shortdesc = field.Value.StringValue;
	            } else if (field.Name == "title") {
                title = field.Value.StringValue;
	            }
        }

        return desc ?? shortdesc ?? title ?? p_ProcessedMeta["_CESSCName"].ToString();
    }
}
} //namespace 

The class must implement the ISitecoreMappingResolver interface. Your assembly will have to reference Coveo.CES.CustomCrawlers.Sitecore.dll, after which you only need to implement the ResolveMapping method. This method has the following parameters:

  • ContentItemMeta: The Sitecore metadata of the item.

  • Hashtable: The already processed system metadata (see About Sitecore Metadata with the Legacy Connector).

  • List<string>: The list of media items referenced by the items. This list can be modified if required.

Note: Mapping values are case-sensitive. If the Sitecore field is called Short Description, the following syntax does not work:
<?xml version="1.0" encoding="utf-8" ?>
<Sitecore>
  <Mapping template="{AF0AD32B-8188-45E0-B354-5226F41D801B}"> 
    <Fields>
      <ShortDesc>%[short description]</ShortDesc > <!—No field will match-->
    </Fields>
  </Mapping>
</Sitecore>
People who viewed this topic also viewed