--- title: Mapping rule syntax reference slug: '1839' canonical_url: https://docs.coveo.com/en/1839/ collection: index-content source_format: adoc --- # Mapping rule syntax reference A [mapping](https://docs.coveo.com/en/217/) rule is a string used to instruct the [indexing pipeline](https://docs.coveo.com/en/184/) mapping stage to populate a given index [field](https://docs.coveo.com/en/200/) with a value. See [Coveo indexing pipeline](https://docs.coveo.com/en/1893/) for details. You define mapping rules when adding or editing a mapping in the [Coveo Administration Console](https://docs.coveo.com/en/183/). See [Manage source mappings](https://docs.coveo.com/en/1640/) for more information. ![Mapping addition dialog](https://docs.coveo.com/en/assets/images/index-content/apply-mapping.png) A mapping rule can consist of one or more [metadata](https://docs.coveo.com/en/218/) 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](https://docs.coveo.com/en/2684#crawling) stage * Pre-conversion script name - The metadata value set during a specific pre-conversion script * `converter`: The metadata value set during the [processing](https://docs.coveo.com/en/2684#processing) stage * `mapping`: The metadata value set during the [mapping](https://docs.coveo.com/en/2684#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, 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, 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](https://docs.coveo.com/en/1893/) 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 (``) > **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. . On the [**Fields**](https://platform.cloud.coveo.com/admin/#/orgid/content/fields/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/fields/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/fields/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/fields/)) page of the Administration Console, locate the field you would like to populate with multiple values. . In the [**Multi-value facet**](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) column, check whether the field has this option enabled. If the option isn't enabled: .. Select the designated field, and then click **Edit** in the Action bar. .. In the **Edit a Field** panel, at the lower-left side, select the **Multi-Value Facet** checkbox, and then click **Save**. . 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.