Log Case Assist Events

Coveo Relevance Cloud Developer System Administrator Product Documentation

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

Note

In the Coveo for Salesforce environment, we recommend using the Coveo Quantic Case Assist components, which can log usage analytics events for you and greatly simplify your implementation in general.

Alternatively, outside of the Salesforce environment, we recommend using the dedicated Coveo Headless Case Assist controllers, which can log usage analytics events for you and also wrap Customer Service API calls, simplifying your implementation.
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, some of the 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 Implementation guidelines

Enter Interface

ticket_create_start

Enter the Interface

Fill a Field

ticket_field_update

fieldName

Fill a Field

Rate a Document Suggestion

suggestion_rate

rate, suggestionId, responseId, suggestion

Rate a Document Suggestion

Select a Field Suggestion

ticket_classification_click

classificationId, responseId, fieldName, classification

Select a Case Classification

Select a Document Suggestion

suggestion_click

suggestionId, responseId, suggestion

Select a Document Suggestion

Click Next Step

ticket_next_stage

Move to the Next Step

Submit Ticket

ticket_create

id

Submit a Ticket

Cancel Ticket

ticket_cancel

reason

Cancel a Ticket

You should use the coveo.analytics.js library to log those events.

Use the Analytics Library

The coveo.analytics.js script exposes methods that allow you to log Case Assist events to the Coveo Usage Analytics (Coveo UA) service. Once you have initialized the script, you can log Case Assists events by registering the Case Assist action, registering the ticket state and finally 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 and classification 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
    }
});

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.analytics.js 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>);
</script>

Where you replace <COVEO_API_KEY> by an API Key or a search token with the Push access level on the Analytics Data domain and the Allowed access level on the Impersonate domain.

1: Register a Case Assist Action

To set the action, use the following command:

coveoua('svc:setAction', <ACTION>, <BODY>)
Example
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
    },
});

2: Register a Ticket

To set the ticket content, use the following command:

coveoua('svc:setTicket', <BODY>);
Example
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 following command:

coveoua('send', 'event', 'svc', <TYPE>, {'searchHub': <SEARCH_HUB>});

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 usage analytics event.

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.

Example
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, some of the action and ticket information is required.

Note

To log a Case Assist event, the coveo.analytics.js script checks the localStorage for the visitor ID. If there’s no visitor ID in the localStorage, it creates one. To optimize UA reporting, it’s important that all your sources of UA events use the same visitor ID value. For information on how to manage visitor IDs, see Integrate a Coveo VisitorIdAccessor Lightning Component.

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

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

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

Example
coveoua("svc:setAction", "suggestion_rate", {
    rate: 0.75,
    suggestionId: "0064770b2e4788f42dfd277b384c6e24cef82b04",
    responseId: "7d8f0s7d-8fhd-3jdh-897f-d79skdnf7g3l",
    suggestion: {
        documentUri: "http://www.salesforce.com/org:organization/object:Solution/record:5013h000000tPmnAAE",
        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.

Example
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
    }
});
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, register a suggestion_click action. Provide all available ticket information in the ticket payload.

Example
coveoua("svc:setAction", "suggestion_click", {
    suggestionId: "929332b2e4788f42dfd277b384c6e24cef82b73",
    responseId: "7d8f0s7d-8fhd-3jdh-897f-d79skdnf7g3l",
    suggestion: {
        documentUri: "http://www.salesforce.com/org:organization/object:Solution/record:5013h000000tPmnAAE",
        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", {
    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"});

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.

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

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

Example
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:

    • documentUri (String, Required)

      The URI of the selected document.

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

suggestion_click

When the user selects a document 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:

    • documentUri (String, Required)

      The URI of the selected document.

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

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

Example
"Electrical"

custom (Object, Optional)

A custom object containing parameters of your choice.

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

description (Object, Optional)

The description of the support case.

Example
"My GC110 electrical panel is cutting off intermittently"

subject (String, Optional)

The subject of the support case.

Example
"GC110 malfunction"

id (String, Optional)

Required when registering a ticket_create action.

The unique identifier of the created ticket.

Example
"5003000000D8cuI"

What’s Next?