Add server-side Coveo Lightning component configuration

This is for:

Developer System Administrator

Coveo for Salesforce 2.15 (February 2016)

You may need to securely inject mandatory filter expressions, additional identities, or analytics groups to the search token used by your Coveo Lightning component. You can add secure server-side configuration to do that using the Advanced Server-Side Configuration panel. Because this configuration is stored server-side and encrypted in the search token, it can’t be accessed, seen, or modified by users or client-side code.

Your Coveo organization index includes a Salesforce Knowledge source that contains articles for internal and external audiences. You add a server-side mandatory expression to the search token to filter out internal articles from search results showed in the community search to prevent internal articles from showing in the community search results.

Adding a server-side Coveo Lightning component configuration

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

  2. In Salesforce, set the permissions for the Coveo Lightning Settings object:

    1. Access the Profiles page:
      With Salesforce Lightning With Salesforce Classic
      Under Administration, select Users > Profiles. Under Administer, select Manage Users > Profiles.

    2. Next to the selected profile, click Edit. On the appropriate users profile(s) who should be able to change the object configuration:

      1. At the object level, grant all permissions by selecting a profile and accessing the Custom Object Permissions section.

      2. At the field level, select the Visible and clear Read-only checkboxes for the Configuration and Site Name fields in the Custom Field-Level Security section.

    3. On the appropriate users profile(s) who will use the Coveo Lightning component, grant only read permissions to the object and its fields.

  3. Access the Salesforce Experience Builder.

  4. At the upper-right corner of the page, click Preview to ensure that you can interact with the Coveo Lightning components.

  5. Access the Advanced Server-Side Configuration panel:
    With Coveo for Salesforce v3.25+ With Coveo for Salesforce V3
    At the upper-right corner of the component, click the cogwheel icon, and then select Advanced Configuration.

    		At the upper-left corner of the component, click the cogwheel icon, and then select Advanced Lightning Configuration.

    Changing options on the Advanced Server-Side Configuration panel generates a special configuration in the CoveoLightningSettings__c custom object.

    The object and the field should be accessible (in read-only) by all users of the site.

    The object and the field should be writable only by a user with an administrative role in Salesforce.

    If the object isn’t configured correctly, there will be an Unsufficient read access to Coveo Lightning Configuration object error page.

  6. In the Advanced Server-Side Configuration panel, specify the information to inject in the search token (see Using the server-side configuration parameters).

    The panel may appear above the search interface.

    1162-advanced-config

  7. Click Save.

    These configurations are saved in a Salesforce custom object (CoveoLightningSettings__c). This object MUST be properly configured in Salesforce for security reasons.

    This means that the object MUST be readable by all the user of the site, and MUST be writable only by administrative users in your Salesforce instance.

    Each site in your Salesforce instance can contain a different configuration, and each Coveo component in each site can contain a different configuration.

    The Name attribute on the Coveo Lightning component is used to determine which configuration should be applied to which component (see Base Lightning component - name and Searchbox Lightning component - name).

    For a given site:

    • If you have no configuration for any Coveo component, then a search token with no special configuration will be sent to the Lightning components

    • If you have a configuration for a Coveo component (using the name as the key), then a search token will be sent to the corresponding components.

    • If you have a configuration for at least one Coveo component (using the name as the key), then ALL components on your site must also contain a configuration. This can be the exact same configuration. It must however be explicitly configured for each and every component in your site. Otherwise, any component that aren’t configured will refuse to initialize and will output the following error message: No configuration for the current Component.

Using the server-side configuration parameters

  • You should test your configuration changes to ensure that the Coveo Lightning component behaves as expected.

  • When using more than one Coveo Lightning component, as soon as one of them has a server-side configuration, you must also create a server-side configuration for each of them.

Coveo Lightning components with no server-side configuration won’t initialize, instead showing the following message:

Unknown page name for current site configuration
Access the Configuration page installed with the Coveo package.

Query expression

In the Query expression box, enter the desired query expression to inject in the search token (see Query syntax). All queries made from this Coveo Lightning component include this filter. This query is included in all queries, and can’t be overridden by client code.

You want to ensure that only the Salesforce Knowledge articles that have an Online status appear in search results by adding the following expression:

@sfkbpublishstatus==Online

In the Coveo Administration Console, you can use the Content Browser to test your expression performance (see Inspect Search Result Items).

Search hub

Coveo for Salesforce 4.23 (March 2022)

In the Search hub box, enter the search hub to enforce in the search token.

This search hub has priority over the search hub that’s specified in the Experience Builder. If no value is specified in the Search hub box, then the search hub that’s specified in the Experience Builder will be enforced in the search token.

Anonymous User

This determines the user identity to be used when a user that isn’t logged in uses Coveo components.

You created the anonymous@myorganization.com guest user profile that you want to use whenever non-connected users interact with the Coveo components.

In the Anonymous User section, you enter the guest user e-mail:

anonymous@myorganization.com

Additional user identities

In the Additional user identities box, enter one or more identities to inject in the search token. Separate your identities using semicolons. All queries made from this Coveo Lightning component include the specified identities, and its associated search results items for which the specified identities have read permissions.

You can fully specify your identity using the following parameters (see Globals Class):

  • name: the actual user (or group) name, as defined in the security provider, typically an email.

    The Coveo Lightning component name property value is used as the key to identify the server-side configuration for each component (see Integrate Coveo components in an Experience Cloud site). When using the Coveo standalone search box, you must therefore ensure that its name property is the same as its associated search component, so the same settings are applied.

  • provider: the security provider name, by default Email Security Provider.

    In a Coveo organization, the identities associated with cloud-based content sources are typically resolved with email addresses, which are used as an internal SSO.

    Contact Coveo Support when you need to know the other security provider names available in your Coveo organization.

  • type: user or group

You can enter only the name without the key when the default provider and type are appropriate. Otherwise, specify all parameters with values other than the default.

One of your Coveo organization source contains items that are meant to be public and for which the dummy user anonymous@everyone.com has access. You want all community users (authenticated or not) to be able to see these items. You enter the anonymous@everyone.com identity.

Usage analytics group

In the Usage analytics group box, enter one or more usage analytics group names to which you want to associate the current user and inject in the search token. Separate your groups using semicolons (see Group).

You want the analytics of your Coveo component to be sent using the custom group Sales, for easier classification and searchability in Usage Analytics.

Under Usage Analytics Group, you enter Sales.

If you’re a developer and you want meaningful usage analytics group information, you could write custom code to detect if the current user is authenticated or not. If so, you should test if they belong to particular repository groups, and then set the usage analytics group accordingly. In such case, you would need to select Bypass above settings to rather generate the search token from a custom Apex class.

Select the Bypass above settings to rather generate the search token from a custom Apex class only when a developer added custom code to generate a search token. The page will simply not initialize if you select this option and no custom code takes care of generating the search token.

In many cases, you will want to have the same configuration for all Coveo Lightning components in your community. You can, however, leave all parameters empty and click Save to create an empty server-side configuration.

For more information on how to fix this issue, see Unknown page for the current site configuration error with Coveo Lightning components.

Bypass above settings to rather generate the search token from a custom Apex class

Checking this box bypasses the settings and uses a custom Apex class.

To learn how to create a custom Apex class, see Send Apex context to a JavaScript Search interface.

What’s next?

Under the hood, the Advanced Configuration panel uses the generateSearchToken method that a developer can use to dynamically customize and generate the search token. To learn how to generate your own search token, see Generating a custom search token for Lightning components.