Manage source mappings

Index Content Coveo Relevance Cloud Developer System Administrator Product Documentation

Members with the required privileges can add and edit mappings.

mappings define what Coveo index fields contain for each source item. This information typically comes from item metadata, but can also be a specific value for all source items.

A Coveo source needs mapping instructions to associate the repository metadata values with appropriate index fields.

Feature Push source All other source types

Default mappings

x

check

Automatically created mappings

When matching metadata[1] and Coveo index field names

1. Metadata names are case sensitive.

x

Manually created mappings

  • When metadata names and destination field names are different

  • When the same value must be set for all source items
Notes

Access the "Edit the Mappings of a Source" panel

  1. Log in to Coveo (platform-ca | platform-eu | platform-au) as a member of a group with the required privileges to manage sources in the target Coveo organization.

  2. In the main menu on the left, under Content, select Sources.

  3. On the Sources (platform-ca | platform-eu | platform-au) page, click the source for which you want to manage mappings, and then click More > Manage mappings in the Action bar.

  4. In the Edit the Mappings of a Source panel, the Common tab is shown by default. Other tabs are Specific and JSON.

Alternatively, you can also access the panel from the View Metadata subpage.

"Common" tab

The Common tab displays mappings that apply to all source item types.

The information you can review in this tab is the following:

"Specific" tab

The Specific tab displays mappings that only apply to certain source item types.

The information you can review in this tab is the following:

"JSON" tab

The JSON tab shows the source mapping rules in JSON format. Any modification made in the Common and Specific tabs automatically updates the JSON accordingly, and vice versa. You can review this raw source configuration for troubleshooting purposes, but you can also modify the configuration itself.

The content displayed in the JSON tab is similar to that in the Mappings tab of the Edit a Source JSON Configuration panel. Therefore, the following instructions apply to both panels:

Access the "JSON" tab

  1. On the Sources (platform-ca | platform-eu | platform-au) page, click the source for which you want to manage mappings, and then click More > Manage mappings in the Action bar.

  2. In the Edit the Mappings of a Source panel, select the JSON tab.

Manage mappings

Add an item type

Adding an item type allows you to apply a mapping rule only to items of this specific type, rather than to all source item types.

  1. In the Edit the Mappings of a Source panel, click the Add dropdown menu, and then select Item type.

  2. In the Add an Item Type dialog, click the dropdown menu and select or create an item type, and then click Add Type.

  3. In the Edit the Mappings of a Source panel:

    • If you’re done managing items or mapping rules, click Save and Rebuild.

      OR

    • If you want to add or edit other items or mapping rules, click Save.

      Notes

      • Clicking Save defers the source rebuild operation, which is necessary to apply changes. Since a source with several millions of items may take weeks to rebuild, choosing the Save option when possible prevents stressing the Coveo and system server resources. It’s therefore recommended to click Save when you plan on making additional changes in the short term, and then to click Save and Rebuild once you’re ready to update your source.

      • item types with no associated mapping rules are deleted when you save your changes.

  4. If you clicked Save, back on the Sources (platform-ca | platform-eu | platform-au) page, under the source Status column, click Launch rebuild when you’re ready or wait for the next scheduled source rebuild to make the changes effective.

Add or edit a mapping rule

The following procedure lets you apply a mapping rule to your source or edit an existing mapping rule.

  1. Access the mapping addition/editing dialog:

    • To add a mapping rule: in the Edit the Mappings of a Source panel, click the Add dropdown menu, and then select Mapping.

      OR

    • To edit a mapping rule, in the Edit the Mappings of a Source panel:

      1. Access the "Common" tab or the "Specific" tab.

      2. In the Common or Specific tab, click the desired mapping rule, and then click Edit in the Action bar.

  2. In the mapping addition/editing dialog:

    1. Under Field, select the field to which the mapping rule should apply:

      • Click the dropdown menu and select the desired field to which the mapping rule should apply. You can also start typing the desired field name to filter your options.

        Note

        You can edit most of the fields in the list by clicking Edit Field.

        OR

      • Click Add Field to add a new field.

    2. Under Apply to, click All items (common) or Specific item types to determine to which items the mapping rule should apply.

    3. (If you selected Specific item types) Select the item types to which the mapping should apply. You can also add missing item types.

    4. Under Rules, enter the mapping rule to apply to the selected items.

    5. Click Apply if you’re adding a mapping rule, and Save if you’re editing a mapping rule.

  3. In the Edit the Mappings of a Source panel:

    • If you’re done adding and editing mapping rules, click Save and Rebuild.

      OR

    • If you want to add or edit other mapping rules, click Save.

      Note

      Clicking Save defers the source rebuild operation, which is necessary to apply changes. Since a source with several millions of items may take weeks to rebuild, choosing the Save option when possible prevents stressing the Coveo and system server resources. It’s therefore recommended to click Save when you plan on making additional changes in the short term, and then to click Save and Rebuild once you’re ready to update your source.

  4. If you clicked Save, back on the Sources (platform-ca | platform-eu | platform-au) page, under the source Status column, click Launch rebuild when you’re ready or wait for the next scheduled source rebuild to make the changes effective.

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.

Edit an item type name

  1. In the Edit the Mappings of a Source panel, access the "Specific" tab.

  2. In the Specific tab, click the desired item type, and then click Edit in the Action bar.

  3. In the Edit an Item Type dialog, edit the item type name, and then click Save.

  4. Back in the Edit the Mappings of a Source panel:

    • If you’re done adding and editing items and mapping rules, click Save and Rebuild.

      OR

    • If you want to add or edit other items and mapping rules, click Save.

      Note

      Clicking Save defers the source rebuild operation, which is necessary to apply changes. Since a source with several millions of items may take weeks to rebuild, choosing the Save option when possible prevents stressing the Coveo and system server resources. It’s therefore recommended to click Save when you plan on making additional changes in the short term, and then to click Save and Rebuild once you’re ready to update your source.

  5. If you clicked Save, back on the Sources (platform-ca | platform-eu | platform-au) page, under the source Status column, click Launch rebuild when you’re ready or wait for the next scheduled source rebuild to make the changes effective.

Rebuild source to take account of mapping rule changes

Once you’re done adding or editing mapping rules, in the Edit the Mappings of a Source panel, click Save and Rebuild to apply your changes.

What’s next?

Ensure that your mapping works as expected in the Content Browser. See Fields tab for details.