Configuring a Salesforce Source

Members of the Administrators and Content Managers built-in groups can index any searchable Salesforce object and field. The source can be public or secured, depending on the selected Salesforce content types (see Salesforce Security in Your Coveo Organization).

Source Features Summary

Features Supported Additional information
Salesforce versions API 51 All objects from the latest supported API or below can be indexed. Objects that use an API version higher than the latest supported API can't be indexed (see Standard Objects).
Searchable content types
  • Standard/custom objects and fields

  • Chatter feed items and files

  • Multilingual Knowledge base articles and attachments

  • CRM content (binary files such as PDF)

Content update operations Refresh Takes place every 15 minutes by default.

A rescan or a rebuild is required to retrieve:

  • Attached and detached KB articles from cases.

  • Deleted KB articles.

  • Deleted KB articles that have reached the archived status.

  • Non-replicable deleted objects such as deleted ContentVersion (CRM Content and Chatter files) attachments and other items.

  • Changes that occurred more than 30 days ago since the last refresh (a scheduled refresh triggers a rescan).

  • Permission changes for a profile, permission set, object sharing, or object security level.

Content security options Users following system permissions1

Doesn't support the following security aspects:

  • IP-based permissions

  • Field level security

  • Shared personal groups (not reported by the Salesforce API)

  • Frozen users

  • Knowledge item permissions (see Limitations)

Note: Poorly implemented Apex Managed Sharing can generate large amounts of record sharing. In such cases, records may be rejected by the index.

Specific identities2

1: The Users following system permissions content security option is the equivalent of Determined by source permissions in other sources.

2: The Specific identities content security option is the equivalent of Source creator in other sources.

Creating a Dedicated Salesforce Crawling User

To crawl your Salesforce content and index it in a Coveo index, you must create a dedicated Salesforce crawling user.

  • Although the Modify All Data permission is no longer a requirement for the crawling user, you can continue to use this permission if it’s part of your existing configuration.

  • Keep in mind that the Modify All Data permission only provides the Modify Metadata Through Metadata API Functions, View All Data, and View Setup and Configuration permissions and that the crawling user must comply with all the requirements listed in this section.


Your dedicated Salesforce crawling user must comply with the following requirements:

  • Must not be an employee’s account. If the person leaves the company or changes role, the account could be terminated or have its permissions changed. This could break the connectivity to Coveo or affect indexing.

  • Must only be used by a single Coveo Salesforce source. If you have multiple sources, we strongly recommend creating a dedicated Salesforce crawling user for each different source.

  • Must have the API Enabled permission to call Salesforce APIs.

  • Must have the Knowledge User permission to index Classic Knowledge articles.

    This permission doesn’t apply when Lightning Knowledge is enabled.

  • Must have the Manage Sharing permission to access the object sharing settings that are required to index securities.

  • Must have the Modify Metadata Through Metadata API Functions permission because it’s the minimum permission that’s required to use the Salesforce Metadata API. This API is used to index Salesforce item permissions. It’s also used to retrieve case settings, sharing settings, and other Salesforce setup configuration information.

  • Must have the Query All Files permission to index all the ContentVersion records in your Salesforce organization.

    • The crawling user must be a member of each library that contains the ContentVersion records you want to index.

    • Without the Query All Files permission, only the ContentVersion records that have been specifically shared with the crawling user will be indexed.

    • This permission is required even if your crawling user has the Modify All Data or View All Data permissions.

  • Must have access to all the Salesforce objects you want to query in your Salesforce organization. We strongly recommend giving the user View All Data permission.

  • Must have access to all the fields you want to index in each Salesforce object. Make sure to validate the field-level security settings in your Salesforce organization.

  • Must have the View all Users and the View All Profiles permissions to view all users and profiles, regardless of their object sharing settings. These permissions are also used to correctly index document securities.

  • Must have the View Setup and Configuration permission to view the basic security objects (e.g., Roles, Profiles, and Permission Sets) and the object sharing configuration. It’s also used to correctly index document securities.

Permissions Quick Reference

This table provides a summary of the permissions that must be set for the crawling user depending on the Salesforce objects you want to index.

Permissions Objects
Service Cloud Content Knowledge Chatter1
API Enabled
Knowledge User2
Manage Sharing3
Modify All Data4 Optional Optional Optional Optional
Modify Metadata Through Metadata API Functions
Query All Files5
View All Data Recommended Recommended Recommended Recommended
View All Profiles
View All Users
View Setup and Configuration

1: To view the Chatter feed items created inside a community, a user must also be a member of that community (see Permissions).

2: The Knowledge User permission is required to index Classic Knowledge articles only. It doesn’t apply when Lightning Knowledge is enabled.

3: The Manage Sharing permission is required even if your crawling user has the Modify All Data permission.

4: Although the Modify All Data permission is no longer a requirement for the crawling user, you can continue to use this permission if it’s part of your existing integration.

5: The Query All Files permission is required even if your crawling user has the Modify All Data or the View All Data permissions.

See Objects for more information on the Service Cloud, Content, Knowledge, and Chatter objects.


The procedure for creating a dedicated Salesforce crawling user is twofold:

Step 1: Create a Salesforce Profile Dedicated to the Coveo User

  1. Log in to your Salesforce organization using an Administrator account.

  2. On the Setup page, enter Profiles in the Quick Find box, then select Profiles.

  3. On the Profiles page, click New Profile.

  4. On the Clone Profile page:

    1. In the Existing Profile box, select an existing profile such as Read Only to be used as a template for the new profile according to the permissions you want to grant to the crawler.

      Take note of the User License (e.g., Salesforce). You will need it in Step 2: Create a Salesforce User Dedicated to Coveo.

    2. In the Profile Name box, enter a name, such as CoveoCrawler.

    3. Click Save.

  5. In the page for your new profile, click Edit and in the Administrative Permissions section, set the following permissions. If you have enabled the Enhanced Profile User Interface, click System Permissions, and then click Edit to set the following permissions.

    1. Ensure that the API Enabled permission is selected.

    2. Select the Manage Sharing, Modify Metadata Through Metadata API Functions, View All Data, View All Users, View All Profiles, and View Setup and Configuration permissions.

    3. Select the Query All Files permission if you want to index all the ContentVersion objects in your Salesforce organization. If you have enabled the Enhanced Profile User Interface, you must access the App Permissions section to set this permission.

    4. Click Save.

Step 2: Create a Salesforce User Dedicated to Coveo

  1. On the Setup page, enter Users in the Quick Find box, and then select Users.

  2. On the All Users page, click New User.

  3. On the New User page:

    1. Fill the required fields.

    2. In the User License box, ensure that the license matches the license of your newly created profile (e.g., Salesforce).

      See the name of the User License you wrote down in Step 1: Create a Salesforce Profile Dedicated to the Coveo User.

    3. In the Profile box, select your newly created profile.

    4. When indexing Knowledge content, ensure that Knowledge User is checked (see Knowledge User Access).

    5. Click Save.

Additional Considerations

  • When deploying in several environments (e.g., development, staging, production), we strongly recommend that you create and use separate dedicated Salesforce crawling users for each environment, as well as one for each different Salesforce source.

    Otherwise, when Coveo accesses your Salesforce organization with the same user credentials too many times, Salesforce returns an INVALID_QUERY_LOCATOR error message, as follows:

      Error with ID 'SALESFORCE_INVALID_QUERY': invalid query locator (INVALID_QUERY_LOCATOR) - This error can occur if a user is used more than once for sources that run in parallel. To avoid this error, make sure to use only one user per source or alternate the refresh schedule of your sources.
  • Optionally, as an additional security measure, in the Login IP Ranges section, select or create a login IP range to restrict the accessibility for this profile (see IP Addresses to Allowlist).

Leading Practices

When creating a Salesforce source, you should follow certain practices to index all of your required content without overloading the Salesforce API or creating unwanted items in your index. Optimally, choosing what to index improves the search experience and prevents performance issues.

When an object contains many fields, use the pre-defined and custom filter above the table to find fields more easily.

When you have the required privileges, you can include many types of Salesforce content to your Coveo organization. Each type covers different Salesforce objects and fields. You can decide who can access the source content.

The number of items that a source processes per hour (crawling speed) depends on various factors, such as network bandwith and source configuration. See About Crawling Speed for information on what can impact crawling speed, as well as possible solutions.

Add or Edit a Salesforce Source

When adding or editing a Salesforce source, follow the instructions below.

“Add a Salesforce Source” Window

When adding a source, you must first authenticate with Salesforce in the Add a Salesforce Source window to allow Coveo to access your content.

Your source authentication access token can potentially expire and become invalid. See Update an Access Token for information on how to update an expired access token.

  1. Select Salesforce Production or Salesforce Sandbox depending on where you created your organization.

  2. Enter the credentials of your Salesforce crawling user and log in.

“Configuration” Tab

In the Add/Edit a Salesforce Source panel, the Configuration tab is selected by default. It contains your source’s general and authentication information, as well as other parameters.


General Information

Source Name

Enter a name for your source.

A source name can’t be modified once it’s saved, therefore be sure to use a short and descriptive name, using letters, numbers, hyphens (-), and underscores (_). Avoid spaces and other special characters.

Optical Character Recognition (OCR)

If you want Coveo to extract text from image files or PDF files containing images, select the appropriate check box. OCR-extracted text is processed as item data, meaning that it’s fully searchable and will appear in the item Quick View. See Enable Optical Character Recognition for details on this feature.

Since the OCR feature is available at an extra charge, you must first contact Coveo Sales to add this feature to your organization license. You can then enable it for your source.

Schema Version

Select the Schema Service version you want to use. Options are:

  • The Current (default) version is the most up-to-date version of the schema. It works with the most recent Salesforce Integration packages and provides a more powerful source configuration user interface. It’s the only version that supports child relationships by default.

  • The Legacy version was the first version of the schema introduced in Cloud V2. It uses field naming compatible with older Salesforce Integration package versions and is no longer receiving feature enhancements.

  • Don’t change this option unless you’re instructed to do so by the Coveo Support team.

  • The schema version can’t be changed once the source has been built. To change the schema version, you must delete your source and add it again.


You can select the objects you want to index in your source:

Alternatively, click Select Specific Objects Manually to index Chatter feeds, related files, or to find any object from your Salesforce organization, as well as its fields and relationships.

“Content Security” Tab

  • Before changing the security of your Salesforce source, ensure that it doesn’t violate any third-party contracts.

  • Changing this setting may expose sensitive content publicly.

Select who will be able to access the source items through a Coveo-powered search interface:


Allows all end users to access the content of this source, regardless of whether they’re anonymous or authenticated.

Specific Identities

Only the specified identities are allowed to see the source content. This option is similar to the Source creator option in other sources.

Enter the following information:

  1. Click the Add identity drop-down menu, and then add an identity.

  2. In the Security identity provider drop-down menu, select the existing provider used to secure the desired identity.

  3. In the Identity type drop-down menu, select the identity type (User or Group) of the identity you want to be allowed to see the source content.

  4. In the Identity input, enter the account name of the user or group.

  5. Optionally, in the Additional info input, add identity information, written in JSON, about the user or group outside the account name.

  6. Click Add.

  7. Repeat this procedure to add more identities.

Users Following System Permissions

This is the default and most secure option. It only allows anonymous and authenticated users to see search results for items to which they have access within Salesforce.

This option is the equivalent of the Determined by source permissions option in other sources.

To prevent INVALID_QUERY_LOCATOR errors, which occurs when Coveo accesses your Salesforce organization with the same user credentials too many times, only select the Users following system permissions option when you have secured content.

  1. Select an identity provider: Allows you to select the identity provider from an existing source.

    When you select an existing security identity provider, ensure that the identities extracted by this provider can be matched with the identities retrieved from the source system.

    For example, while you create a second Salesforce source retrieving the content from the same organization, you select the identity provider of the first Salesforce source.

  2. Create a new one: Creates a new identity provider based on your selected Salesforce organization. If this is the first Salesforce source in your organization, we recommend that you select this option.

“Salesforce Organization” Tab

This tab displays the name and type of the Salesforce organization you index. It also shows the email address with which you logged in to connect your Salesforce organization with Coveo.

“Access” Tab

In the Access tab, determine whether each group and API key can view or edit the source configuration (see Understand Resource Access):

  1. In the Access Level column, select View or Edit for each available group.

  2. On the left-hand side of the tab, if available, click Groups or API Keys to switch lists.


  1. Do one of the following to finish adding or editing your source:

    • When you want to save your source configuration changes without starting a build/rebuild, such as when you know you want to do other changes soon, click Add Source/Save.

      On the Sources page, you must click Launch build or Launch rebuild in the source Status column to add the source content or to make your changes effective, respectively.

    • When you’re done editing the source and want to make changes effective, click Add and Build Source/Save and Rebuild Source.

      Back on the Sources page, you can review the progress of your source addition or modification.

    Once the source is built or rebuilt, you can review its content in the Content Browser.

  2. Optionally, consider editing or adding mappings.

    You can only manage mapping rules once you build the source (see Refresh, Rescan, or Rebuild Sources).

Rebuilding is required to take into account changes made to the field mapping rules. If you don’t rebuild, changes will only apply to new or modified items.

Salesforce Security in Your Coveo Organization

The security of your Salesforce content is maintained in your Coveo organization. When you create a Salesforce source in your Coveo organization, the Salesforce security model is replicated by indexing not only the content but also the permissions associated with that content. This means that with Coveo for Salesforce, when an end user looks at information pulled from Salesforce, they only see what they’re allowed to see in Salesforce. For more information, see Content Security.

Bill is a customer support agent in a company. Like his customer support colleagues, in Salesforce, Bill has access to Accounts, Contacts, and Cases, but not to Campaigns, Leads, Opportunities, and Forecasts.

When Bill accesses a Coveo Insight Panel or the Coveo expanded view, the Salesforce results presented only include content from Accounts, Contacts, and Cases. If he was granted access to private objects in Salesforce, content from these records would also be included.


Coveo supports several securities, but has some limitations including, but not limited to:

  • Restriction Rules

    Coveo for Salesforce doesn’t currently support the Restriction Rules functionality that was introduced in the Salesforce Winter ‘22 Release.

    To avoid data leaks, we strongly advise against applying restriction rules to the content indexed by your Coveo Salesforce sources at this time.

  • Shared personal groups aren’t supported

    A user can share content with a personal group. These sharing permissions can’t be indexed because they’re currently not reported by the Salesforce API. The consequence is that members of the personal group won’t see the shared content in Coveo organization results. This limitation is therefore not a security hole.

  • Field level security isn’t supported

    For Enterprise, Unlimited, and Developer Salesforce editions, visibility of individual fields can be granted or denied to users or groups to fine-tune the access control in a permission set or a profile. The Coveo organization index doesn’t include this information. The consequence is that a user that is denied access to a field could see the content of this field in the Coveo organization results. Note however that this is also the case for Salesforce search results (see the Salesforce item Field-Level Security Overview).

  • Login IP address and hours restrictions aren’t supported

    The Coveo organization index doesn’t contain restrictions on login IP address or hours configured in Salesforce. The consequence is that your Salesforce users can access the Coveo organization search interfaces and review Salesforce content from any IP address at any time.

  • Frozen users aren’t supported

    The users that are frozen using the Freeze button aren’t denied access to the search (see Freezing User Accounts).

  • Knowledge Base (KB) record access based on Data Categories:

    In Salesforce, if you rely on Data Categories to control KB record access, note that these permissions can’t be indexed as this information isn’t available from the Salesforce API. Consequently, in search results, all users can see all KB articles under all data categories.

    When using Sharing for Lightning Knowledge, Coveo automatically supports permissions set on Online, Draft, and Archived articles.

  • When the organization-wide default is set to Controlled by Parent, a maximum master-detail relationship depth of two levels is supported (see Sharing Default Access Settings).

    When you index a sub-detail object, the detail parents are correctly determined but the master parents are considered public because there are three levels (master-detail-subdetail).

About Objects and Fields

In Coveo for Salesforce, you often need to reference specific Salesforce objects and fields, either in result templates, in a search interface, or in custom code you want to implement.

This page explains the way Coveo transforms the Salesforce objects and fields, so you can reference them more easily in Coveo.

For more information on how to create queries using objects and fields, see Coveo Query Syntax.

Salesforce Object Reference

The Salesforce object names stay the same. You can refer to them by using the following syntax.


Where you replace <YOUR_SALESFORCE_OBJECT> by the name of the Salesforce object.

Ensure that you use the Salesforce object API name (see Standard Objects and Custom Objects).

Salesforce Field Reference

Coveo adapts the Salesforce field names to ease the implementation and avoid potential confusion with other non-Salesforce fields.

The best and most accurate way of knowing the exact Coveo name for a Salesforce field, as well as its value for a given item, is to access the Content Browser in your Coveo organization.

Remember to add the @ symbol when referring to a field (see Coveo Query Syntax).

  1. Access the Content Browser page of the Coveo Administration Console.
  2. In the Source facet on the left, select the Salesforce source you want to inspect.
  3. In the Object Type facet, select the Salesforce object associated to the item or field you want to inspect.

  4. To ensure that you can see all available items, select the Preferences button () at the end of the search bar, and check the View all content box.

  5. Click one of your items in the result list, and then click Properties.

You should now have access to the Coveo field name of each of your items, along with its associated value for the selected item.

Coveo for Salesforce Field Syntax

As a general rule, all Salesforce fields are transformed the following way:

sf + Relationship + Salesforce API Field Name

  • sf

    Indicates the field is a Salesforce field.

  • Relationship

    Indicates the parent or child object associated to the field.

    When referring to a parent object, the singular form of the object name is used.

    When referring to a child object, the plural form of the object name is used.

    When the object is a top-level field (has no parent or child relationship), this value is skipped.

    • Since Account is a parent of Case, the field Name from the Account object associated to a case is sfAccountName

    • The Subject field for all the Case objects on an Account is sfCasesSubject

    • The Status field of the Case object is a top-level field, meaning its field is sfStatus

  • Salesforce API Field Name

    Indicates the Salesforce API field name (see Find the API name of a field).

    Remember that custom fields end with __c.

About Object Relationship

Since Coveo fields take the object relationship into account in its syntax, you may want to understand that relationship when referring to those fields.

Top-Level Fields

Top-level fields are fields that are directly associated to an object.

Formula fields are considered top-level fields.

Parent Relationship Fields

The parent relationship is only available when querying a child object (e.g., Case). Parent relationship fields have a many-to-one relationship where multiple child records (e.g., Cases) can be associated to the same parent record (e.g., Account).

The Account object is a parent of the Case object, as cases belong to an account.

Child Relationship Fields

The child relationship is only available when querying a parent object (e.g., Account). Child relationship fields have a one-to-many relationship where a single parent record (e.g., Account) can be associated to multiple child records (e.g., Cases).

The Account object has a Cases child relationship that lists all the cases for any particular account.

When referencing a child relationship in a query, they’re expected to return many values.

  1. You can use expressions such as @YourChildRelationshipField==value to match documents for which a multi-value field contains the specified value.

  2. When used in facets, each value will appear on a separate line and can be filtered on independently.

  3. When retrieved in query results, the field value will be a string merging all the values, separated by semicolons.

Advanced Configuration of a Salesforce Source

When you have the required privileges, you can also fully control which Salesforce objects and fields are indexed. This is useful when you have custom objects that need to be searchable.

  1. Access your Coveo organization (see Log in to Coveo).

  2. On the Sources page of the Coveo Administration Console, click the Salesforce source you want to customize, and then, in the Action bar, click Edit.

  3. In the Configuration tab of the Edit a Salesforce Source panel, select the Salesforce objects and fields you want to index.


    • Your custom objects are only displayed when you have enabled its Allow Search field in Salesforce (see Manage Custom Objects).

    • You can browse your fields using a pager instead of scrolling down to the end. If your source is a Legacy source, you won’t see the parent and child relationships in your panel.

    • You can also select a field and click Parent relationship or Child relationship to see the associated fields. The breadcrumb at the top of the table helps you to know exactly what you selected.


  4. To edit a source field, access the Fields page.

    To edit field mappings, you must access the Edit the Mappings of a Source panel.

  5. To manage conditions on the objects to index, click the object, and then, in the Action bar, click Conditions.

  6. To change the body field of your Salesforce objects, see View or Edit a Salesforce Object Body.

  7. To finish adding or editing your source, do one of the following:

    • Click Save when you want to save your source configuration changes without starting a rebuild, such as when you know you want to do other changes soon.

    • Click Save and Rebuild Source when you’re done editing the source and want to make changes effective.

      Back on the Sources page, you can review the progress of your Salesforce source modification.

  8. Once the source is rebuilt, you can review its content in the Content Browser.

Managing Conditions Applied to an Object

You can index items only when they meet specific conditions, which can reduce the size of your index.

This is useful when you have many object records that should be excluded when they don’t meet specific criteria.

Access the Panel

  1. Log in to Coveo, if not already done.

  2. If not already in the Add/Edit a Salesforce Source panel, do one of the following to access the panel:

    • To add a source, in the main menu, under Content, select Sources > Add Source > Salesforce. In the Configuration tab, click Or Select Specific Objects Manually.

    • To edit a source, in the main menu, under Content, select Sources > source row > Edit in the Action bar.

  3. Select the check box of a Salesforce object on which you want to add or edit conditional indexing.

  4. At the top of the object list, select Conditions.


    The Manage Conditions Applied to an Object panel is displayed.

Add Conditions to a Salesforce Source

  1. In the Manage Conditions Applied to an Object panel, under Conditions, enter the appropriate information:

    1. (When editing a Knowledge base object only) Select one or more of the following publish statuses of knowledge articles to include: Online (published), Archived, and Draft.


      By default, only Online (published) articles are indexed. More than one status can be selected. However, if you select Draft, one knowledge article can appear several times in many versions in search results (see Salesforce Knowledge Articles).

    2. In the Select a field drop down menu, select the Object field you want to use as part of your condition.

    3. In the Select an operator drop down menu, depending on the selected field, select one of the available operators:

      For more information on the operators, see Comparison Operators.

      The only added operator is NOT LIKE, which acts as the opposite of the LIKE operator.

      • Equals

      • Not equals

      • Less than

      • Less than or equals to

      • Greater than

      • Greater than or equals to

      • Like

      • Not like

      • In

      • Not in

      • Includes

      • Excludes

    4. In the remaining field, enter the field value to respect.

      If you selected the Excludes operator, you can enter many values in a single entry using the following syntax ('value1','value2').

      Remember to enter string values in single quotes and to respect the ISO 8601 format for datetime values (e.g., 2017-08-21T20:09:26+00:00 ).

  2. Once you’re satisfied with your condition, click Add to add it to your source. The condition should be added underneath.


  3. Once you have entered all the conditions1 you want on your source, click Apply Changes.

    The changes will be effective once you have saved and rebuilt your source.

    1: If you’ve added many indexing conditions to your source, only the objects satisfying all the conditions are indexed.

Manage Conditions in a Salesforce Source

  1. In the Manage Conditions Applied to an Object panel, you can also perform the following actions:

    • To edit an existing condition, change the values of your condition.

    • To remove only one condition, click Remove next to the condition to remove.

    • To remove all conditions, click Remove All Conditions.

  2. When you’re done, click Apply changes.

    The changes will be effective once you have saved and rebuilt your source.

View or Edit a Salesforce Object Body

You can change what’s indexed as the body of your object by defining a mapping rule for the body field.

The body of your object is used both as the excerpt and as the Quickview of an item in your search interface. For more detailed information, see Excerpt Component and Quickview Component. The body mapping documentation for non-Salesforce sources also contains details on the mapping process, Quick View, and excerpt.

  1. On the Sources page of the Coveo Administration Console, click the Salesforce source you want to customize, and then, in the Action bar, click Edit.

  2. In the Configuration tab of the Edit a Salesforce Source panel, select the object of which you want to change the body, and then click Body.


  3. Under Rule, enter your new body. Keep in mind the following:

    • You can enter content to be treated as HTML, given you enter it inside an <html> element.

    • You can display Salesforce field values by using the following syntax: %[<SALESFORCE_FIELD_NAME>].

      Where you replace <SALESFORCE_FIELD_NAME> with the Salesforce field API name.

      You want to change your Account object to display the account description, account number, and account phone number.

      Under Rule, you enter the following mapping rule:

      <html><div>Description: %[Description]</div><div>Account Number: %[AccountNumber]</div><div>Phone Number: %[Phone]</div></html>

    • You can find the API name of the Salesforce field in the Salesforce Field column, in italics.

  4. Once you’re satisfied with the content of the body, click Apply Changes.

What’s Next?

You may manually edit the JSON configuration, but be warned that improperly configuring the JSON will make your source fail to build.

For more information on the different JSON configurations you can perform on your Salesforce source, see JSON Salesforce Objects.

What's Next for Me?