Sending Context Information in Salesforce Lightning

The instructions provided in this section apply to Salesforce Lightning. To learn how to add custom context information in Salesforce Classic see Send Custom Context Information.

Sending context information in the search requests and Coveo Usage Analytics (Coveo UA) events originating from a Coveo-powered interface in Salesforce lets you better adapt the search experience to your user’s browsing behaviors.

Among other things, you may want to leverage context to:

Send Custom Context Without Resorting to Custom Code

Coveo Lightning components allow you to send custom context information without having to write custom code (see Adding Server-Side Coveo Lightning Component Configuration).

This option adds a group to all events coming from your Lightning component.

Adding Object Context in the Salesforce Lightning Console

On the default Coveo Insight Panel and Full Search Lightning Components, you can specify any object context using the desired field values on the component’s Record Fields box.

  1. In Salesforce, access your Lightning Application (e.g., Lightning Service Console, Sales), and then open any record (e.g., Case, Opportunity, Account).

  2. At the top right of the page, click Settings Cogwheel icon, and then select Edit Page.

  3. On the Lightning App Builder page that opens, click the desired component to open the settings panel on the right-hand side of your screen.

  4. In the settings panel, locate the Record Fields box.

    Lightning App builder and record fields

  5. In the Record Fields box, add the fields you want to use as context using their api names in the format of <OBJECT>_<FIELD> (e.g. Case_Productversion__c). Then click Save. For more information, see Common Context Fields by Object Type.

Common Context Fields by Object Type

The following table provides examples of fields that are useful to contextualize search. The Record fields column indicates the value to set depending on the object type.

Object type Record fields
Account Account_Description
Case Case_Subject, Case_Description
Opportunity Opportunity_Name, Opportunity_Description

While the Subject and Description fields are used by default, you may want to declare other fields to better contextualize the search experience.

You can easily find the formatted field names in your Salesforce organization through the Object Manager. Access the desired object, and then select the Fields & Relationships tab.

In the Fields & Relationships tab, use the format of the desired field as written in the Field Name column.

fields-and-relationships

To declare the field, you must prefix the field name by the name of the object as follows:

<OBJECT_NAME>_<FIELD_NAME>

Where you replace:

<OBJECT_NAME> with the name of the object

<FIELD_NAME> with the name of the field as written in the Field Name column.

Adding Parent Record Fields

Coveo for Salesforce 3.36 (July 2018)

Parent records, up to five levels, can be attached to the object context. In the Record Fields, write the desired parent record field using the following syntax:

SObjectName_ParentRecord.Field
  • Case_Account.Id

  • Case_Account.Owner.Name

  • Case_Account.Owner.Phone

  • Case_Contact.Account.Owner.Name

  • Case_CustomObject__c

  • Case_CustomObject__r.CustomField__c

  • Case_CustomObject__r.OtherCustomObject__c

  • Case_CustomObject__r.OtherCustomObject__r.Name

Separate each parent record field by a comma.

Adding Context With Custom Code

  • The instructions provided in this section apply to Salesforce Lightning. To learn how to add custom context information in Salesforce Classic see Send Custom Context Information.

  • If you want to send context information that comes from a server-side request, see addPreInitPromise method.

You may also want to add custom context, such as user context, to better adapt the search experience to the current user.

Users are authenticated on your product documentation site. From their profiles, you can determine their roles relative to your products (i.e., end-user, administrator, or developer). This means that user role could be a good custom context.

Often, for similar queries (e.g., entering only a feature name), users with different roles have different intentions and are looking for different kinds of information:

  • Developers - Search for instructions on how to customize the product with code samples.

  • Administrators - Search for installation and configuration articles.

  • End users - Search for instructions on how to use the product.

Step 1: Create a Custom SearchUI Lightning Component

To send custom context along with the search requests and Coveo Usage Analytics (Coveo UA) events originating from a Coveo-powered interface in Salesforce, you must customize the Coveo for Salesforce components.

You can achieve this by creating a custom SearchUI Lightning Component.

  1. Create a new Lightning Component using the Salesforce Developer Console.

  2. In the Salesforce Developer Console, in the component CMP file that was created in the previous step, enter code that references the SearchUI Lightning Component.

     <!-- LightningComponent.cmp -->
     <aura:component access="global" implements="flexipage:availableForRecordHome">
       <aura:handler name="init" value="{!this}" action="{!c.doInit}" />
       <CoveoV2:SearchUI name="CoveoSearchUI" aura:id="<COVEO_COMPONENT_AURA_ID>"></CoveoV2:SearchUI>
     </aura:component>
    

    Where you replace <COVEO_COMPONENT_AURA_ID> with the component’s aura ID (e.g., CoveoAgentPanel).

  3. Save the component.

Step 2: Create a Controller for Your Custom SearchUI Lightning Component

Now that you have created your custom SearchUI Lightning Component, you must create a controller to add the script that handles the custom context.

  1. In the Salesforce Developer Console, on the right-hand side of the screen, under your custom Lightning Component, select Controller.

  2. In the file that opens, paste the following script:

     ({
       doInit : function(component, event, helper) {
           const <MY_FUNCTION> = function() {
               return "<CONTEXT_KEY>"
           }
           // Get the Coveo Lightning Component.
           var <COVEO_COMPONENT_NAME> = component.find('<COVEO_COMPONENT_AURA_ID>');
           // Get the Coveo SearchUI base component.
           var coveoSearchUI = <COVEO_COMPONENT_NAME>.get('v.searchUI');
           // Register this to be executed before the search-ui initialization.
           coveoSearchUI.registerBeforeInit(function (cmp, rootInterface, Coveo) {
               // Register an handler on the "buildingQuery" event.
               coveoSearchUI.proxyAddEventListener('buildingQuery', function (e, args) {
                   // Add your context dictionary
                   args.queryBuilder.addContext({
                       "<CONTEXT_KEY>": <CONTEXT_VALUE>()
              });
           });
         });
       }
    })
    

    Where you replace:

    • <MY_FUNCTION> with the function that captures the context value to retrieve (e.g., getUserRole).

    • <CONTEXT_KEY> with the key of the key-value pair that defines the context to retrieve (e.g., userRole).

    • <COVEO_COMPONENT_NAME> with the name of the Coveo Lightning Component (e.g., coveoAgentPanel).

    • <COVEO_COMPONENT_AURA_ID> with the component’s aura ID (e.g., CoveoAgentPanel).

    • <CONTEXT_VALUE> with the value of the key-value pair that defines the context to retrieve (e.g., getUserRole).

    You want to add the user’s user role in a Coveo SearchUI component. Therefore, you enter the following code in the component JS file:

     ({
       doInit : function(component, event, helper) {
         const getUserRole = function() {
             return "userRole"
         }
         // Get the Coveo SearchUI Component.
         var coveoSearchUI = component.find('<COVEO_COMPONENT_AURA_ID>');
         // Register this to be executed before the search-ui initialization.
         coveoSearchUI.registerBeforeInit(function (cmp, rootInterface, Coveo) {
             // Register an handler on the "buildingQuery" event.
             coveoSearchUI.proxyAddEventListener('buildingQuery', function (e, args) {
                 // Add your context dictionary
                 args.queryBuilder.addContext({
                     "userRole": getUserRole()
           });
         });
       });
      }
    })
    
  3. Save the component.

Step 3: Integrate the Component

Now that you have created a component that sends custom context, you must drag and drop it in the desired Lightning record pages or communities.

Step 4: Test the Component

Once the custom component has been integrated on the desired interface, you should check if the added custom context is properly sent in the search requests originating from your custom component.

  1. Access the object or community in which the component is integrated.

  2. Access your browser developer tools, and then select the Network tab.

  3. In the custom component, perform a query.

  4. In your browser developer tools, in the Network tab, under the Name column, select the latest request to the Search API. It should contain /rest/search/v2.

  5. In the Headers tab of the search request, in the Form Data section, ensure that the context entry contains the desired context.

In the following search request, the userLanguage is sent as a context:

Request to the Search API showing custom context

Send Custom Events With the Coveo JavaScript Search Framework

When implementing a custom Salesforce Lightning component that uses the Coveo JavaScript Search Framework, you may want to:

To understand the available options and methods for your specific components or use cases, you may want to review the following reference documentation:

To add context to standard or custom events, you need to:

Ensure that you have enough custom dimensions left before implementing your code (see Coveo for Salesforce Edition Comparison).

Sharing Dimensions Across Events

To add Dimensions common to any event recorded, use the changeAnalyticsCustomData event of the Analytics component.

The example below adds dimensions to the metaDataAsString object similar to username as the key and caseContext.username as the value. You need to declare these Dimensions within the Coveo Platform (see Manage Dimensions on Custom Metadata).

$('#CoveoBoxboxid').on('changeAnalyticsCustomData', function(e, args) {
    args.metaObject.username = caseContext.username;
    args.metaObject.caseid = caseContext.id;
    args.metaObject.casesubject = caseContext.subject.toLowerCase();
    args.metaObject.casenumber = caseContext.number;
    args.metaObject.caselanguage = caseContext.lang;
    args.metaObject.casestatus = caseContext.status;
});
Recommended Articles