Sending context information in Salesforce Lightning

Sending context information in Salesforce Lightning

This is for:

Developer System Administrator

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:

• Create usage analytics dimensions and use them to build meaningful reports adapted to your business realities.

• Reference context in query ranking expressions (QRE) and query pipeline conditions.

• Train Coveo Machine Learning (Coveo ML) models on specific use cases.

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 (for example, Lightning Service Console, Sales), and then open any record (for example, Case, Opportunity, Account).

2. At the top right of the page, click Setup , 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 side of your screen.

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

   

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> (for example, 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.

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

Adding context with custom code

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

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 (for example, CoveoAgentPanel).

3. Save the component.

Step 2: Create a controller for your custom SearchUI Lightning component

Now that you’ve 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 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 (for example, getUserRole).

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

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

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

   • <CONTEXT_VALUE> with the value of the key-value pair that defines the context to retrieve (for example, 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’ve 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 Payload tab of the search request, in the Form Data section, ensure that the context entry contains the desired 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:

• Send your own UA events

  OR

• Modify the standard JavaScript Search Framework events

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

• Coveo for Salesforce components reference

• Coveo JavaScript Search Framework - Reference Documentation

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

• Modify the metadata to send with UA events

  AND

• Add custom usage analytics dimensions in Coveo to allow reporting on the associated metadata

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 Coveo (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;
});

Leverage custom context

Once the custom context is properly sent in search requests and in Coveo UA, you’ll likely want to use this information in UA reports.

To create UA reports based on the custom context, you must create UA dimensions that lets you include the custom information in your dashboards and explorers. See Manage dimensions on custom metadata for information on how to create UA dimensions based on the custom context.

Is this article useful?

You can close this window or leave a comment below.

Very useful Not really

Can you tell us more about your experience today?

Comments (optional)

Need help with our product? Please open a support case for expert assistance. Use this feedback option to comment on the article only.

Submit

Is this article useful?

You can close this window or leave a comment below.

Very useful Not really

Can you tell us more about your experience today?

Comments (optional)

Need help with our product? Please open a support case for expert assistance. Use this feedback option to comment on the article only.

Submit