---
title: Send context information in Salesforce Lightning
slug: '3290'
canonical_url: https://docs.coveo.com/en/3290/
collection: coveo-for-salesforce
source_format: adoc
---
# Send context information in Salesforce Lightning
> **Note**
>
> 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](https://docs.coveo.com/en/399/).

Sending context information in the search requests and [Coveo Analytics](https://docs.coveo.com/en/182/) [Coveo Analytics events](https://docs.coveo.com/en/260/) 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 [Coveo Analytics dimensions](https://docs.coveo.com/en/258/) and use them to build meaningful [reports](https://docs.coveo.com/en/266/) adapted to your business realities.
* Reference context in [query ranking expressions (QREs)](https://docs.coveo.com/en/1472/) and [query pipeline conditions](https://docs.coveo.com/en/2793/).
* Train [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) 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 [Add a server-side Coveo Lightning Aura component configuration](https://docs.coveo.com/en/1162/)).

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](https://docs.coveo.com/en/1028/) and [Full Search](https://docs.coveo.com/en/1096/) Lightning components, you can specify any object context using the desired field values on the component's **Record Fields** box.

. In Salesforce, access your Lightning Application (for example, Lightning Service Console, Sales), and then open any record (for example, Case, Opportunity, Account).
. At the top right of the page, click **Setup** ![Cogwheel icon in Salesforce](https://docs.coveo.com/en/assets/images/coveo-for-salesforce/cogwheel.png), and then select **Edit Page**.

. On the **Lightning App Builder** page that opens, click the desired component to open the settings panel on the right side of your screen.
. In the settings panel, locate the **Record Fields** box.

. 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).

#### 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`
|===

> **Note**
>
> 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**](https://help.salesforce.com/articleView?id=extend_click_find_objectmgmt_lex.htm&type=5).
> Access the desired object, and then select the **Fields & Relationships** tab.
> 
> On the **Fields & Relationships** tab, use the format of the desired field as written in the **Field Name** column.
> 
> 
> 
> 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


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:

```xml
SObjectName_ParentRecord.Field
```

**Examples**

* `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`

> **Note**
>
> Separate each parent record field by a comma.

## Adding context with custom code

> **Notes**
>
> * 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](https://docs.coveo.com/en/399/).
> * To send context information that comes from a server-side request, see [addPreInitPromise method](https://docs.coveo.com/en/1375#addpreinitpromise).

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

**Example**

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

Often, for similar queries (for example, 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 Analytics](https://docs.coveo.com/en/182/) [events](https://docs.coveo.com/en/260/) 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](https://docs.coveo.com/en/1375/).

. [Create a new Lightning Component](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_create_devconsole.htm) using the Salesforce Developer Console.
. 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](https://docs.coveo.com/en/1375/).


**Example**

[,xml]
```
 <!-- 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`).
. 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.

. In the Salesforce Developer Console, on the right side of the screen, under your custom Lightning Component, select **Controller**.
. In the file that opens, paste the following script:

```javascript
 ({
   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](https://docs.coveo.com/en/1209/) (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`).


**Example**

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:

```javascript
 ({
   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()
       });
     });
   });
  }
})
```

. Save the component.

### Step 3: Integrate the component

Now that you've created a component that sends custom context, you must drag it to the desired [Lightning record pages](https://docs.coveo.com/en/1031/) or [communities](https://docs.coveo.com/en/1193/).

### 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.

. Access the object or community in which the component is integrated.
. [Access your browser developer tools](https://docs.coveo.com/en/2994#access-your-browser-developer-tools), and then select the **Network** tab.
. In the custom component, perform a query.
. In your browser developer tools, on the **Network** tab, under the **Name** column, select the latest request to the Search API.
It should contain `/rest/search/v2`.
. On the **Payload** tab of the search request, in the **Form Data** section, ensure that the **context** entry contains the desired context.


**Example**

In the following search request, the `userLanguage` is sent as a 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](https://docs.coveo.com/en/365#send-your-own-ua-events)

OR

* Modify the standard [JavaScript Search Framework events](https://docs.coveo.com/en/417/)

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](https://docs.coveo.com/en/1045/)
* [Coveo JavaScript Search Framework - Reference Documentation](https://coveo.github.io/search-ui/globals.html)

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

* [Modify the metadata to send with Coveo Analytics events](https://docs.coveo.com/en/365#modify-the-metadata-to-send-with-coveo-analytics-events)

AND

* Add custom [usage analytics dimensions](https://docs.coveo.com/en/1904/) in Coveo to allow reporting on the associated metadata


> **Important**
>
> Ensure that you have enough custom dimensions left before implementing your code (see [Analytics](https://docs.coveo.com/en/l2590456#analytics)).

## Sharing dimensions across events

To add Dimensions common to any event recorded, use the [changeAnalyticsCustomData](https://docs.coveo.com/en/417#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](https://docs.coveo.com/en/1522/)).

**Example**

[,javascript]
```
$('#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 [Coveo Analytics reports](https://docs.coveo.com/en/266/) based on the custom context, you must create [dimensions](https://docs.coveo.com/en/258/) that let you include the custom information in your [dashboards](https://docs.coveo.com/en/256/) and [explorers](https://docs.coveo.com/en/261/).
See [Manage dimensions on custom metadata](https://docs.coveo.com/en/1522/) for information on how to create UA dimensions based on the custom context.