Mapping rule syntax reference

This is for:

Developer System Administrator

A mapping rule is a string used to instruct the indexing pipeline mapping stage to populate a given index field with a value. See Coveo indexing pipeline for details. You define mapping rules when adding or editing a mapping in the Coveo Administration Console. See Manage source mappings for more information.

Mapping addition dialog

A mapping rule can consist of one or more metadata name placeholders in the following format: %[metadataName]. A placeholder is recognized and interpreted by the indexing pipeline mapping stage as a value to retrieve within the system metadata.

Note

The Salesforce Knowledge metadata names for Knowledge specific fields are prefixed by Kav_.

For Example, to map the custom Details__c field, you would need to enter %[Kav_Details__c].

You can specify two arguments inside the tag: the name of the metadata to use and, optionally, the origin of the metadata. Specify the metadata origin using the following syntax: %[metadataName:origin].

The allowed origin values are as follows:

  • crawler: The metadata value set during the crawling stage

  • Pre-conversion script name - The metadata value set during a specific pre-conversion script

  • converter: The metadata value set during the processing stage

  • mapping: The metadata value set during the mapping stage

  • Post-conversion script name - The metadata value set during a specific post-conversion script

Example

You have a metadata named employeeID extracted in the indexing pipeline crawling stage and you want to populate the index field AuthorID, so you enter one of the following rules:

  • %[employeeID]

  • %[employeeID:crawler] (when the metadata has multiple origins)

Note

When your metadata includes a colon, you must be careful when formatting your rule because the keyword following the last colon is interpreted as the metadata origin. Therefore, if you want to keep the colon in your metadata name, you must include an origin in the placeholder to disambiguate the rule format.

Examples:

  • In %[foo:title], foo is interpreted as the metadata name and title as the metadata origin.

  • In %[foo:title:crawler], foo:title is interpreted as the metadata name and crawler as the metadata origin.

Mapping rules aren’t limited to a single metadata item. You can create rules with multiple metadata names and mix the metadata names with text.

Example

Miss %[firstName] %[lastName]

Mapping rule evaluation

You may add more than one rule on the same field as a fallback, to make sure that your items are indexed with a value.

Coveo evaluates the rules in the order they appear. If the first rule is resolved with a result that’s not empty, Coveo saves this result in the desired field. Conversely, if no value is extracted, Coveo evaluates the next rule, and so on.

If none of the rules produce a non-empty value, the field value is considered empty and doesn’t appear in the item metadata.

Example

You add the following mapping rules to the field author:

  • %[fullname]

  • %[firstName] %[lastName]

  • Anonymous

If the metadata fullname doesn’t exist on a given item, Coveo gets an empty value when evaluating the first rule. Therefore, it considers the second rule. If firstName and/or lastName are non-empty, Coveo indexes the resulting value. Conversely, if the second rule yields no result, Coveo evaluates the third rule, which is a plain string, as a last resort. This rule produces the string "Anonymous", which Coveo indexes. In Coveo’s index, the item metadata therefore contains: author: Anonymous.

Item title selection

You can add or edit mapping rules to determine which metadata Coveo should use as the item title. The default common mapping rule selects the title extracted during the crawling stage (%[title:crawler]). See Coveo indexing pipeline for details.

When you want to add or edit item title selection rules, the available options are the following:

  • %[detectedtitle:converter]

    Selects the title detected during the processing stage using text analysis.

    Note

    To establish the title, Coveo uses key sentences and a list of concepts found to be the most important in the text of the item.

  • %[title:converter]

    Selects the title extracted from the binary item or the file system during the processing stage.

    Examples

    • For a Microsoft Word item, the embedded title

    • For a web page, the value between the title tags (<title></title>)

    Note

    If the converter metadata is empty, Coveo selects the title extracted during the crawling stage (%[title:crawler]).

  • %[title:crawler]

    Selects the title extracted during the crawling stage, which is usually the item file name.

    Example

    The subject of an email

  • %[title]

    Selects the title extracted during the processing stage (%[title:converter]).

    Note

    If the converter metadata is empty, Coveo selects the title extracted during the crawling stage (%[title:crawler]).

Populate index field with multiple values

You can populate an index field with multiple values by using an array as your corresponding metadata.

Note

The following procedure is only compatible with string fields.

  1. On the Fields (platform-ca | platform-eu | platform-au) page of the Administration Console, locate the field you would like to populate with multiple values.

  2. In the Multi-Value Facet column, verify whether multi-value facets are enabled for this field. If the option isn’t enabled:

    1. Select the designated field, and then click Edit in the Action bar.

    2. In the Edit a Field panel, at the lower-left side, select the Multi-Value Facet checkbox, and then click Save.

  3. When creating a new mapping rule for the designated field, use the following format: %[metadataName]. If the corresponding piece of metadata is an array containing multiple values, the index field is populated with each value in the array.