Product DocsMenu

Creating and Using a Sitecore Mapping File

By default, the Sitecore connector uses a built-in mapping shown below to determine what metadata from your original Sitecore documents are associated with fields for the documents in the Coveo index.

<?xml version="1.0" encoding="utf-8" ?>
<Mappings>
  <Version>1</Version>
  <Mapping type="versioneditem">
    <Title>%[Name]</Title>
    <Body>%[Description]</Body>
    <Fields>
      <Field name="creationdate">%[Created]</Field>
      <Field name="iscontentitem">%[IsContentItem]</Field>
      <Field name="ishidden">%[Hidden]</Field>
      <Field name="ismediaitem">%[IsMediaItem]</Field>
      <Field name="isreadonly">%[ReadOnly]</Field>
      <Field name="language">%[Language]</Field>
      <Field name="languages">%[Languages]</Field>
      <Field name="modificationdate">%[Updated]</Field>
      <Field name="owner">%[CreatedBy]</Field>
      <Field name="parentid">%[ParentID]</Field>
      <Field name="revision">%[Revision]</Field>
      <Field name="templateid">%[TemplateID]</Field>
      <Field name="templatename">%[TemplateName]</Field>
      <Field name="updatedby">%[UpdatedBy]</Field>
      <Field name="version">%[Version]</Field>
      <Field name="versions">%[Versions]</Field>
      <Field name="workflowstate">%[WorkflowState]</Field>
    </Fields>
  </Mapping>
</Mappings>  

Note: The built-in mapping includes only the standard Sitecore metadata, none of your Sitecore custom or business metadata.

The connector however retrieves all metadata. If you create and assign to your Sitecore source a field set that includes custom fields for which the Metadata Name parameter exactly matches the Sitecore metadata names, they will be mapped automatically (see Adding or Modifying Custom Fields). It is therefore recommended to extend your Sitecore source field set to include matching fields for all useful metadata (see Modifying the Field Set Used by a Source).

You can create and use a custom mapping file to tailor the mappings to your custom fields to specific templates.

To create and use a custom mapping file

  1. Using an administrator account, connect to the Coveo Master server.

  2. Using a text editor:

    1. Create an XML file respecting the mapping file schema (see Standard Mapping File Schema) as illustrated in the following commented example:

      <?xml version="1.0" encoding="utf-8" ?>
      <Mappings><!-- Review the XML Schema to view the available fields and attributes -->
        <Version>1</Version><!-- Mandatory node to identify the mapping file version. Do not modify. -->
        <CommonMapping><!-- Optional. Any Mapping defined within this section applies to all documents. -->
          <Title>%[title]</Title>
      	<Fields>
      	  <Field name="CustomCoveoField">%[SitecoreField]</Field>
      	</Fields><!-- Map a custom Coveo field to a Sitecore metadata. -->
        </CommonMapping>
        <Mapping type="versioneditem"><!-- Optional. This is a specific mapping. The fields and elements described apply to items of type "versionitem" -->
          <Body>
      	  <![CDATA[
      		<html>
      			<body style=\"font-family:'verdana`;font-size:10px\">
      			  %[Description]
      			</body>
      		</html>
      	  ]]>
      	</Body>
          <PrintableUri>http://www.coveo.com</PrintableUri>
          <Fields>
            <Field name="field1">This is a custom field</Field>
          </Fields>
        </Mapping>
        <DefaultMapping> <!-- Optional. The default mapping applies exclusively to all items that are not mapped to a specific mapping -->
          <ClickableUri>www.clickableuri.com</ClickableUri>
        </DefaultMapping>
      </Mappings>  

      Note: If you want to modify a versioneditem, you must create a CommonMapping, or create a Mapping for each templateid in Sitecore and put the template GUID in the mapping type.

      Important: When a mapping file is specified in a source and an HTML body is specified for some or all items, the Extract Html Content option is not taken into account for these items. The crawler gets HTML from the mapping file body, not from the HTML rendered by Sitecore. You can use the mapping file and the Extract Html Content option by removing the <body> section of the mapping file.

    2. Specify field mappings in the following format:

      <Field name="CoveoIndexFieldName">%[SiteCoreItemFieldName]</Field>

      Example: The mapping <Field name="creationdate">%[Created]</Field> instructs the connector to copy the value of the Created Sitecore metadata and paste it in the creationdate Coveo index field for each indexed document.

      Note: The value that you enter between %[...] must be the Sitecore field name as it appears in the Sitecore item, not the Sitecore field information appearing in a template.

    3. When you chose to use foreign keys to allow incremental refresh to detect referenced item changes (see About Foreign Keys), you must define the foreign key fields for the key and the value in the mapping file.

      Example: A Sitecore site presents music artists. The Artist item type is the only one containing both the artist ID and the artist name. All other item types (Song, Albums, Discography...) only contain the artist ID. For these item types, the artist name can be rendered by reference.

      In the following mapping file excerpt for this site, a specific mapping is defined for the template of Artist items (885063B0-3451-4B6C-98E3-5AB502C80B36) and the Sitecore ID metadata is mapped to the Artist index field to be used as the key field of the foreign key. Similarly, the Sitecore Name metadata is mapped to the ArtistName index field to be used as is the foreign key value field.

      <Mapping type="885063B0-3451-4B6C-98E3-5AB502C80B36"><!-- Optional. Set  foreign key fields for the template of a given document type.  -->
      <Fields>
        <Field name="Artist">%[ID]</Field>
        <Field name="ArtistName">%[Name]</Field>
      </Fields>
      </Mapping>  

      Tip: When you want to restrict a <mapping> to a specific template, the GUID to use for the type attribute correspond to the value of the Item ID parameter for the template in Sitecore (see Finding the ID of a Sitecore Template Item).

    4. Save the file using a name of your choice in the [Index_Path]\Config folder.

      Example: C:\CES7\Config\MySitecoreMapping.xml

  3. Instruct the connector to use this configuration file for a source by adding the path of the mapping file to the Mapping File source parameter (see Standard Mapping File Schema).

What's Next?

Ensure that the field set assigned to your Sitecore source contains the custom fields defined in your mapping file (see Adding a Field Set and Adding or Modifying Custom Fields).

Consider creating and using a configuration file (see Creating and Using a Sitecore Configuration File).

People who viewed this topic also viewed