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 (UA) 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, 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

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

Select a document suggestion

suggestion_click

suggestionId, responseId, suggestion

Move to the next step

ticket_next_stage

Submit a ticket

ticket_create

id

Cancel a ticket

ticket_cancel

reason

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

Use the analytics library

The Coveo analytics library exposes methods that let you log Case Assist events to the Coveo UA service. Once you have 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, 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 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 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 UA 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 library checks the browser’s local storage for a visitor ID. If there’s no visitor ID in local storage, 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 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.

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

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

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