Log case assist events

This is for:

Developer System Administrator

This article lays out the different actions involved in the Case Assist workflow and which usage analytics events to log for each of them.

Note

In the Coveo for Salesforce environment, we recommend that you use the Coveo Quantic Case Assist components, which can simplify your implementation by logging UA events for you.

Outside of the Salesforce environment, we recommend that you use the dedicated Coveo Headless Case Assist controllers, which can simplify your implementation by logging UA events and wrapping Customer Service API calls for you.
Case Assist event flow

You need to log each user interaction with your Case Assist interface. At each one, specify the action and as much ticket information as possible. In some events, certain action and ticket information is required. The following summary table lists the action type for each event and, when required, the necessary action and ticket payload parameters, as well as a link to the corresponding implementation guidelines.

Event Action type Required action payload parameters Required ticket payload parameters

Enter the interface

ticket_create_start

Fill a field

ticket_field_update

fieldName

Rate a document suggestion

suggestion_rate

rate, suggestionId, responseId, suggestion

Select a field suggestion

ticket_classification_click

classificationId, responseId, fieldName, classification, autoSelection

Select a document suggestion

documentSuggestionClick [1]

actionCause, clientId, contentIDKey, contentIDValue, documentPosition, documentTitle, documentUrl, language, originContext, originLevel1, searchQueryUid, sourceName, userAgent

suggestion_click (Deprecated)

suggestionId, responseId, suggestion

Select document suggestion quick view

documentSuggestionQuickview [2]

actionCause, clientId, contentIDKey, contentIDValue, documentPosition, documentTitle, documentUrl, language, originContext, originLevel1, searchQueryUid, sourceName, userAgent

Move to the next step

ticket_next_stage

Submit a ticket

ticket_create

id

Cancel a ticket

ticket_cancel

reason

1. This action is available as of the Coveo UA library v2.30.45 release. It replaces the deprecated suggestion_click action.

2. This action is available as of the Coveo UA library v2.30.45 release. It replaces the fromQuickview parameter key in the deprecated suggestion_click action.

You should use the Coveo UA library to log these events.

Use the Coveo UA library

The Coveo UA library exposes methods that let you log Case Assist events to the Coveo UA service. Once you’ve initialized the library, you can log Case Assists events by registering the Case Assist action, registering the ticket state, and sending the event.

Example

A user selects a case classification suggestion. You tag the action as a ticket_classification_click and set the classificationId, responseId, fieldName, classification, and autoSelection parameters in the action payload.

coveoua("svc:setAction", "ticket_classification_click", {
    classificationId: "sd8cn3d8-d9n3-s7cb-4knd-d9cnal3njd8c",
    responseId: "123e4567-e89b-12d3-a456-426614174000",
    fieldName: "category",
    classification: {
        value: "Electrical",
        confidence: 0.76
    },
    autoSelection: "false"
});

You also set the updated ticket data.

coveoua("svc:setTicket", {
    subject: "GC110 malfunction",
    description: "My GC110 electrical panel is cutting off intermittently",
    category: "Electrical",
    custom: {
        visitorAge: 18,
        rewardsMember: true
    }
});

Finally, you send the event.

coveoua('send', 'event', 'svc', 'click', {'searchHub': 'case_assist_interface'});

(Prerequisite) Initialize the library

To be able to invoke the Coveo UA library, include the following <script> tag in the target page.

<script>
  (function(c,o,v,e,O,u,a){
  a='coveoua';c[a]=c[a]||function(){(c[a].q=c[a].q|| []).push(arguments)};
  c[a].t=Date.now();u=o.createElement(v);u.async=1;u.src=e;
  O=o.getElementsByTagName(v)[0];O.parentNode.insertBefore(u,O)
  })(window,document,'script','https://static.cloud.coveo.com/coveo.analytics.js/2/coveoua.js')

  coveoua('init', '<COVEO_API_KEY>', 'https://<ORG_ID>.analytics.org.coveo.com');
</script>

Where you replace:

1: Register a Case Assist action

To set the action, use the coveoua('svc:setAction', <ACTION>, <BODY>) command:

coveoua('svc:setAction', 'ticket_classification_click', {
    classificationId: "d8cn3d8-d9n3-s7cb-4knd-d9cnal3njd8c",
    responseId: "123e4567-e89b-12d3-a456-426614174000",
    fieldName: "category",
    classification: {
        value: "Electrical",
        confidence: 0.76
    },
    autoSelection: "true",
});

2: Register a ticket

To set the ticket content, use the coveoua('svc:setTicket', <BODY>) command:

coveoua('svc:setTicket', {
    subject: "GC110 malfunction",
    description: "My GC110 electrical panel is cutting off intermittently",
    category: "Electrical",
    custom: {
        visitorAge: 18,
        rewardsMember: true
    }
});

3: Send an event

To send an event, use the coveoua('send', 'event', 'svc', <TYPE>, {'searchHub': <SEARCH_HUB>}) command, where:

  1. <TYPE> can be either of the following:

    1. 'flowStart': Used when the user enters your Case Assist interface.

    2. 'click': Used when the user interacts within your Case Assist interface.

  2. <SEARCH_HUB> (optional) indicates the name or identifier of the Case Assist interface from which the event originates. When specified, this parameter populates the originLevel1 metadata of the resulting UA event.

    Note

    As a best practice, we recommend specifying the searchHub.

You don’t need to worry about the other three parameters (send, event, and svc), as they don’t change in the context of Case Assist.

coveoua('send', 'event', 'svc', 'click', {'searchHub': 'case_assist_interface'});

Case Assist events

You should log every user interaction in the Case Assist workflow. For each one, you must specify the action and you should specify as much ticket information as possible. In some events, specific action and ticket information is required.

Note

To log a Case Assist event, the Coveo UA library checks the browser’s local storage for a client ID. If there’s no client ID in local storage, it creates one. To optimize UA reporting, it’s important that all your sources of UA events use the same client ID value. For information on how to manage client IDs, see Integrate a Coveo ClientIdAccessor Lightning component.

Enter the interface

When the user enters your Case Assist interface, register a ticket_create_start action. If you already have some information on the ticket, provide it in the ticket payload.

coveoua("svc:setAction", "ticket_create_start");
coveoua("svc:setTicket", {
    custom: {
        "visitorAge": 18,
        "rewardsMember": true
    }
});
coveoua("send", "event", "svc", "flowStart", {"searchHub": "case_assist_interface"});

Fill a field

If the user fills a field, register a ticket_field_update action and specify the updated ticket information in the ticket payload.

coveoua("svc:setAction", "ticket_field_update", {
    fieldName: "category"
});
coveoua("svc:setTicket", {
    category: "Electrical",
    custom: {
        "visitorAge": 18,
        "rewardsMember": true
    }
});
coveoua("send", "event", "svc", "click", {"searchHub": "case_assist_interface"});

Rate a document suggestion

If the user rates a document suggestion, register a suggestion_rate action and provide all available ticket information in the ticket payload.

coveoua("svc:setAction", "suggestion_rate", {
    rate: 0.75,
    suggestionId: "0064770b2e4788f42dfd277b384c6e24cef82b04",
    responseId: "7d8f0s7d-8fhd-3jdh-897f-d79skdnf7g3l",
    suggestion: {
        documentUriHash: "gizDGrXcVñbV7mñy",
        documentTitle: "GC3000 Series Propane Generator Ignition",
        documentUrl: "http://www.salesforce.com/org:organization/object:Solution/record:5013h000000tPmnAAE",
        documentPosition: 1
    }
});
coveoua("svc:setTicket", {
    category: "Electrical",
    custom: {
        "visitorAge": 18,
        "rewardsMember": true
    }
});
coveoua("send", "event", "svc", "click", {"searchHub": "case_assist_interface"});

Select a case classification

If the user selects a case classification that you provided, register a ticket_classification_click action and specify the updated ticket information in the ticket payload.

coveoua("svc:setAction", "ticket_classification_click", {
    classificationId: "d8cn3d8-d9n3-s7cb-4knd-d9cnal3njd8c",
    responseId: "123e4567-e89b-12d3-a456-426614174000",
    fieldName: "category",
    classification: {
        value: "Electrical",
        confidence: 0.76
    },
    autoSelection: "false",
});
coveoua("svc:setTicket", {
    subject: "GC110 malfunction",
    description: "My GC110 electrical panel is cutting off intermittently",
    category: "Electrical",
    custom: {
        visitorAge: 18,
        rewardsMember: true
    }
});
coveoua("send", "event", "svc", "click", {"searchHub": "case_assist_interface"});

Select a document suggestion

If the user selects a document suggestion that you provided, send a documentSuggestionClick action.

Important
Important

The documentSuggestionClick action, which is a Coveo Usage Analytics click event, is available as of the Coveo UA library v2.30.45 release. It replaces the deprecated suggestion_click action.

 
coveoua('send', 'click',
{
    anonymous: false,
    clientId: "489aa3e3-aed2-4563-8e81-62bb73178a56",
    actionCause: "documentSuggestionClick",
    documentPosition: 2,
    documentTitle: "GC3000 Series Propane Generator Ignition",
    documentUrl: "http://www.salesforce.com/org:organization/object:Solution/record:5013h000000tPmnAAE",
    language: "en",
    originContext: "CaseAssist",
    originLevel1: "CaseAssistFlow",
    originLevel2: "default",
    searchQueryUid: "df60b2fb-c276-49ae-b704-2ee45609f3a6",
    sourceName: "AnswersCloud",
    userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.181 Safari/537.36",
    customData: {
        contentIDKey: "permanentid",
        contentIDValue: "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960"
    }
});

Select the document suggestion quick view

If the user selects the document suggestion quick view button, send a documentSuggestionQuickview action.

Important
Important

The documentSuggestionQuickview action, which is a Coveo Usage Analytics click event, is available as of the Coveo UA library v2.30.45 release. It replaces the fromQuickview parameter key in the deprecated suggestion_click action.

 
coveoua('send', 'click',
{
    anonymous: false,
    clientId: "489aa3e3-aed2-4563-8e81-62bb73178a56",
    actionCause: "documentSuggestionQuickview",
    documentPosition: 2,
    documentTitle: "GC3000 Series Propane Generator Ignition",
    documentUrl: "http://www.salesforce.com/org:organization/object:Solution/record:5013h000000tPmnAAE",
    language: "en",
    originContext: "CaseAssist",
    originLevel1: "CaseAssistFlow",
    originLevel2: "default",
    searchQueryUid: "df60b2fb-c276-49ae-b704-2ee45609f3a6",
    sourceName: "AnswersCloud",
    userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.181 Safari/537.36",
    customData: {
        contentIDKey: "permanentid",
        contentIDValue: "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960"
    }
});

Move to the next step

If the user moves to the next page of your case creation flow, register a ticket_next_stage action and specify all available ticket information in the ticket payload.

coveoua("svc:setAction", "ticket_next_stage");
coveoua("svc:setTicket", {
    category: "Electrical",
    custom: {
        "visitorAge": 18,
        "rewardsMember": true
    }
});
coveoua("send", "event", "svc", "click", {"searchHub": "case_assist_interface"});

Cancel a ticket

If the user cancels their ticket creation, register a ticket_cancel action. Provide all available ticket information in the ticket payload.

coveoua("svc:setAction", "ticket_cancel", {
    reason: "Solved"
});
coveoua("svc:setTicket", {
    subject: "GC110 malfunction",
    description: "My GC110 electrical panel is cutting off intermittently",
    category: "Electrical",
    custom: {
        visitorAge: 18,
        rewardsMember: true
    }
});
coveoua("send", "event", "svc", "click", {"searchHub": "case_assist_interface"});

Submit a ticket

If the user creates a ticket, register a ticket_create action and specify all available ticket information in the ticket payload. In particular, specify the id in the ticket payload.

coveoua("svc:setAction", "ticket_create");
coveoua("svc:setTicket", {
    subject: "GC110 malfunction",
    description: "My GC110 electrical panel is cutting off intermittently",
    category: "Electrical",
    id: "5003000000D8cuI",
    custom: {
        visitorAge: 18,
        rewardsMember: true
    }
});
coveoua("send", "event", "svc", "click", {"searchHub": "case_assist_interface"});

Case Assist actions reference

ticket_create_start

When the user enters your Case Assist interface.

ticket_field_update

When the user fills a field.

Payload:

  • fieldName (String, Required)

    The name of the field updated by the user.

suggestion_rate

When the user rates a document suggestion you provide.

Payload:

  • rate (Float between 0 and 1, Required)

    The rating of the document suggestion, where 0 means terrible and 1 means perfect.

  • suggestionId (String, Required)

    The permanent identifier (fields.permanentid in the Service API response) of the rated document.

  • responseId (String, Required)

    The unique identifier (responseId in the Service API response) of the document suggestion response.

  • suggestion (Object, Required)

    The object describing the selected suggestion. It contains the following parameters:

    • documentUriHash (String, Required)

      The hashed URI of the selected document.

    • documentUrl (String, Required)

      The URL of the selected document.

    • documentTitle (String, Required)

      The title of the selected document.

    • documentPosition (Integer greater than or equal to 1, Required)

      The 1-based position of the selected document in the array of suggested documents.

ticket_classification_click

When the user selects a case classification.

Payload:

  • classificationId (String, Required)

    The unique identifier (id in the Service API response) of the selected case classification suggestion.

  • responseId (String, Required)

    The unique identifier (responseId in the Service API response) of the case classification response.

  • fieldName (String, Required)

    The name of the field for which the user selected a classification.

  • classification (Object, Required)

    The object which describes the selected classification suggestion. If provided, this object must contain the following parameters:

    • value (String, Required)

      The field value of the selected classification suggestion.

    • confidence (Float between 0 and 1, Required)

      The confidence value of the selected classification suggestion.

  • autoSelection (Boolean, Required)

    A flag indicating whether the update was triggered by an automatic selection. For example, if a value is automatically selected because it has the highest confidence, set this parameter to true.

documentSuggestionClick

Important
Important

This action is a Coveo Usage Analytics click event. It’s available as of the Coveo UA library v2.30.45 release, and it replaces the deprecated suggestion_click action.

When the user selects a document suggestion.

Payload:

Tip

See Log click events for more information about the following payload parameters.

  • actionCause (String, Required)

    The identifier of the user action that caused the search interface to log a click event, for example, if the user selects a document suggestion, the actionCause would be documentSuggestionClick.

  • clientId (String, Required)

    A Globally Unique Indentifier (GUID) which represents the current user. See What’s the clientId? for details.

  • contentIDKey (String, Required)

    The name of a field in the index that uniquely identifies the item.

  • contentIDValue (String, Required)

    The value of the field selected as contentIDkey.

  • documentPosition (Integer greater or equal to 1, Required)

    The 1-based position of the selected document in the array of suggested documents.

  • documentTitle (String, Required)

    The title of the selected document.

  • documentUrl (String, Required)

    The URL of the selected document.

  • language (String, Required)

    The language of the search interface from which the click event originates.

  • originContext (String, Optional)

    The origin of the event. Used to specify the deployment from which the user performs the action.

    Example
    {
    ...
    originContext: "CaseAssist",
    ...
}

  • originLevel1 (String, Required)

    The name or identifier of the search interface from which the event originates. If unspecified and the request is authenticated with a search token, the service tries to extract the search hub value from the access token that authenticated the request to log a search event.

  • originLevel2 (String, Optional)

    The name or identifier of the tab from which the click event originates.

  • originLevel3 (String, Optional)

    The URL of the page that redirected the browser to the search interface from which the click event originates (that is, document.referrer).

  • searchQueryUid (String, Required)

    The unique identifier (responseId in the Service API response) of the query that caused the Case Assist interface to log a click event.

  • sourceName (String, Required)

    The @source of the document that was clicked.

  • userAgent (String, Required)

    Information about the browser and operating system of the user who caused the search interface to log a click event.

suggestion_click

Important
Important

Deprecated. As of the Coveo UA library v2.30.45 release, this action has been replaced by the documentSuggestionClick action.

When the user selects a suggestion.

Payload:

  • suggestionId (String, Required)

    The permanent identifier (fields.permanentid in the Service API response) of the selected document.

  • responseId (String, Required)

    The unique identifier (responseId in the Service API response) of the document suggestion response.

  • suggestion (Object - Required)

    The object describing the selected suggestion. It contains the following parameters:

    • documentUriHash (String, Required)

      The hashed URI of the selected document.

    • documentUrl (String, Required)

      The URL of the selected document.

    • documentTitle (String, Required)

      The title of the selected document.

    • documentPosition (Integer greater or equal to 1, Required)

      The 1-based position of the selected document in the array of suggested documents.

    • fromQuickview (Boolean, Optional)

      Important
      Important

      Deprecated. As of the Coveo UA library v2.30.45 release, this parameter key has been replaced by the documentSuggestionQuickview action.

      Whether the user selected the document suggestion quick view button.

documentSuggestionQuickview

Important
Important

This action is a Coveo Usage Analytics click event. It’s available as of the Coveo UA library v2.30.45 release, and it replaces the fromQuickview parameter key in the deprecated suggestion_click action.

When a user selects the document suggestion quick view button.

Payload:

Tip

See Log click events for more information about the following payload parameters.

  • actionCause (String, Required)

    The identifier of the user action that caused the search interface to log a click event, for example, if the user selects the document suggestion quick view button, the actionCause would be documentSuggestionQuickview.

  • clientId (String, Required)

    A Globally Unique Indentifier (GUID) which represents the current user. See What’s the clientId? for details.

  • contentIDKey (String, Required)

    The name of a field in the index that uniquely identifies the item.

  • contentIDValue (String, Required)

    The value of the field selected as contentIDkey.

  • documentPosition (Integer greater or equal to 1, Required)

    The 1-based position of the selected document in the array of suggested documents.

  • documentTitle (String, Required)

    The title of the selected document.

  • documentUrl (String, Required)

    The URL of the selected document.

  • language (String, Required)

    The language of the search interface from which the click event originates.

  • originContext (String, Optional)

    The origin of the event. Used to specify the deployment from which the user performs the action.

    Example
    {
    ...
    originContext: "CaseAssist",
    ...
}

  • originLevel1 (String, Required)

    The name or identifier of the search interface from which the event originates. If unspecified and the request is authenticated with a search token, the service tries to extract the search hub value from the access token that authenticated the request to log a search event.

  • originLevel2 (String, Optional)

    The name or identifier of the tab from which the click event originates.

  • originLevel3 (String, Optional)

    The URL of the page that redirected the browser to the search interface from which the click event originates (that is, document.referrer).

  • searchQueryUid (String, Required)

    The unique identifier (responseId in the Service API response) of the query that caused the Case Assist interface to log a click event.

  • sourceName (String, Required)

    The @source of the document that was clicked.

  • userAgent (String, Required)

    Information about the browser and operating system of the user who caused the search interface to log a click event.

ticket_next_stage

When the user proceeds to the next stage in your Case Assist interface.

ticket_cancel

When the user cancels the ticket they were creating.

Payload:

  • reason (String, Required)

    Possible values:

    • "Quit": When the user simply cancels or leaves the interface.

    • "Solved": When the user cancels after clicking a button to the effect that they have solved their case.

ticket_create

When the user creates the ticket. There’s no action payload to log, but be sure to log the id in the ticket payload.

Ticket payload reference

category (String, Optional)

The category of the support case.

"Electrical"

custom (Object, Optional)

A custom object containing parameters of your choice.

{
  "visitorAge": 18,
  "rewardsMember": true
}

description (Object, Optional)

The description of the support case.

"My GC110 electrical panel is cutting off intermittently"

subject (String, Optional)

The subject of the support case.

"GC110 malfunction"

id (String, Optional)

Required when registering a ticket_create action.

The unique identifier of the created ticket.

"5003000000D8cuI"

What’s next?