Events Framework

Overview

Gainsight Events Framework allows you to create events, which can be used in Programs and Rules Engine. Events can be defined as triggers that are a result of some other activity.

Following are some use cases where the Event framework can be used:

• A Program can be triggered to send a survey to participants when there is a Zendesk ticket or Salesforce case is closed.
• A program can be triggered to send a welcome email when a new user creates an account in a non-Gainsight system.
• A notification email is sent whenever a participant responds to a survey.
• An event can be the completion of a data load that could subsequently be used to trigger a rule in Rules Engine.

In Rules Engine, using the Schedule Type as Event, you can run the rule using cURL command. cURL command is a handy way to trigger a rule outside of Gainsight. In a broader sense, it enables you to integrate rules deeper with non-Gainsight services if you have developer support.

This article explains how to create a Topic and an Event in the Topic from the Gainsight Administration page. Gainsight uses an Event triggered by a publisher in the following subscribers:

• Rule Scheduler: When an Event is triggered by publisher and reaches Gainsight, configured rule starts executing. Event acts as a scheduler in this use case.
• JO Program - Participant configuration: When an Event is triggered by publisher and reaches Gainsight, new participants are added to the published program, as per field mappings configured in the Event in Gainsight.

The Events framework includes the following components:

• Publisher: Sender of the event is defined as the publisher. For example: In the CSAT Survey model for Programs, Zendesk or Salesforce can be the publisher of the case closure event for every case that is closed.
• Subscribers:  Subscribers are the processing entities/applications that decide which action should be taken when an event occurs. Gainsight controls which applications can act as available subscribers to the events sent by the publishers. Programs and Rules are the available subscribers.
• Topic and Event: Topics can be defined as a logical separation between similar events. Events are defined within a Topic and represent a specific occurrence. For example, the events “Ticket Closed” and “Ticket Reopened” can belong to the topic “Zendesk Tickets”. You can create a maximum of 20 Topics, and 100 Events in each Topic.

Event API Contract

Following is the sample Event Processing API contract, that can help Admins with extensive experience with scripting or developers who script the Event API calls on how to send Events to Gainsight:

https://app.gainsight.com/v1.0/api/eventManager/event

{ 
"hello":"world"
}

{
 "result": true,
 "data": {
   "eventId": "259d8882-8b13-4ded-b2b0-39c43359739d"
 },
 "message": "Successfully received event, please keep the event Id for further reference",
 "messages": [   "Successfully received event, please keep the event Id for further reference"
 ]
}

{
 "result": false,
 "errorCode": "1001",
 "errorDesc": "Oops, something went wrong! Please contact Tech Support to report. ",
 "requestId": "4e1f3665-eb88-4017-8dff-2c8d400c9111",
 "message": "Event is not registered",
 "messages": [
   "Event is not registered"
 ]
}

Register as Publisher

You can register the sender of Events (any other system infrastructure) from Gainsight. Gainsight generates a unique key for this registration which is used while configuring the publisher. This key is always unique for a specific org and should be kept secured.

Perform the following actions to register the sender of events as Publisher:

1. Open the following link in a web browser:
   https://<Salesforce instance url>/apex/JBCXM__EventsV2#/events-dashboard/topics/list

Or navigate to Administration > Events.

2. Click Register As Publisher to generate a unique key which is used to register the current org in any other system infrastructure, from which events are sent to Gainsight. This key is used while configuring the publisher. This key is always unique for a specific org and should be kept secured.
3. Click the show shared secret key gear icon and copy the key any time.

Create Events 

You can create a Topic and add similar Events in a Topic. Topics provide you with a mechanism to separate your events according to your business needs. You can create a maximum of 20 Topics per org and add a maximum of 100 Events in each Topic.

Program Events Workflow

A sample workflow of events in Programs is depicted in the following diagram:

The above diagram specifies how a case closure event in Salesforce or Ticket closure event in Zendesk is published to the respective subscribers. (You can also watch this 8-min. video for a walkthrough of how to setup an event as a participant source in Programs.)

The use case here is: A user wants to send out a ticket satisfaction survey right after a ticket is closed. This can be achieved by setting up a trigger once the ticket is closed, and sending this information to the Program using the Events framework. The various processes that take place when a trigger is set up are explained below:

1. You create a topic + event using the steps provided in the Create an Event section.

Create the event with the following details:
Event Name: Ticket closure
Event Version: 1.0
Event Structure: Fields in the Event structure:

• ContactEmail
• ContactName
• CompanyName
• SFDCAccountId
• SFDCContactId

2. When the Zendesk ticket is closed, the event is published to the topic by the publisher. The recommended approach is to use a trigger created on the Zendesk ticket system, which in turn calls the API by passing the required information as part of the POST call. Same is the case when a Salesforce Case is closed, a trigger is created on the SFDC Case object, which in turn calls the API.
   Notes:

• To make an Event call from Salesforce, a new site should be added to the Remote Site settings as a allow listing item.
• In case of Event call from a Salesforce org, your use case and Salesforce org determine the exact configurations needed for the script. Because this scripting is handled through Salesforce, Gainsight does not have an exhaustive list of scripting examples for every org. Gainsight recommends Salesforce Admins with extensive experience scripting in the Salesforce developer console handle scripting configurations.
• In case of Event call from Zendesk system, your use case and Zendesk org determine the exact configurations needed for the script. Gainsight recommends system Admins handle required scripting configurations in Zendesk.

3. The topic receives the posted event as part of the above mentioned trigger and broadcasts it to the subscribers. Subscribers in this case are Programs.
4. The Programs feature then receives the case/ticket closure events and processes them to add new participants in the Program configuration and send emails to these new participants. To validate, you can check if the participants have been added inside the Program.

Note: Only after the Program is published by configuring the participant source as an event (see image above), events that are generated from the Zendesk system or SFDC case trigger are eligible to be processed. Each event received by Programs adds new participants, based on the unique criteria selected.

Salesforce Apex Class for GSEvents 

You can create Events to Gainsight from Salesforce by using Salesforce Apex Class and trigger them to Gainsight system. Before creating Gainsight Events in Salesforce, add https://ep.gainsight.com to your Salesforce Remote sites. To learn more on how to add Remote sites, refer to the Configure Remote Site Settings Salesforce article.

To create GSEvents from Salesforce:

1. Create a Salesforce Apex Class. To learn more on how to create a Salesforce Apex Class, refer to the Simple Class to understand Apex Salesforce article.
2. Copy the GSEvent structure from below and customize to your specific Event.

public class GSEvents{


@future(callout=true)
public static void calloutFromFuture(string records, string sharedSecret, string tenantId, string eventName,string topicName, string eventVersion){
System.debug('Welcome to Apex Case Closure Trigger!');
Http http = new Http();
HttpRequest request = new HttpRequest();
request.setEndpoint('https://ep.gainsight.com/api/v0.1/eventManager/event');
request.setMethod('POST');




request.setHeader('sharedSecret',sharedSecret);
request.setHeader('tenantId',tenantId);
request.setHeader('eventName',eventName);
request.setHeader('topicName',topicName);
request.setHeader('eventVersion',eventVersion);
request.setHeader('Content-Type','application/json');
request.setHeader('Accept','application/json');





Map<String,Object> data = new Map<String,Object>();
    data.put('participantInformationList',JSON.deserializeUntyped(records));
    
    request.setBody(JSON.serialize(data));
    HttpResponse response = http.send(request);
    if (response.getStatusCode() != 201) {
    System.debug('The status code returned was not expected: ' +
        response.getStatusCode() + ' ' + response.getStatus());
    } else {
    System.debug(response.getBody());
    }
}


}

The following GSEvent sample structure request of Salesforce trigger is used for generating an event when the status of a Case is changed to Escalated:

trigger CaseClosure on Case (after update) {
{


string eventName = ‘copy_value_from_gainsight_events_page’;
string  eventVersion = 'copy_value_from_gainsight_events_page';
string topicName = 'copy_value_from_gainsight_events_page';
string tenantId = ‘contact your csm to get your tenantId’;
string sharedSecret=‘’copy_value_from_gainsight_events_page;


if(Trigger.isUpdate)
{
    List<Map<string,Object>> records = new List<Map<String,Object>>();
    List<String> caseids = new List<String>();
    for(Case updatedCase : Trigger.new) 
    {
        if(updatedCase.status.equals('Escalated')) 
        {
            caseids.add(updatedCase.Id);
        }
    }
       List<case> cases = [Select CaseNumber, Contact.Name, ContactEmail, AccountId, Subject, Reason, Account.Name, Type from Case where id in :caseids];
    for(Case updatedCase : cases)
    {
       Map<String,Object> record = new Map<String,Object>();
       record.put('Recipient Email', updatedCase.ContactEmail);
       record.put('Account Id', updatedCase.AccountId);
       record.put('Account Name', updatedCase.Account.Name);
       record.put('Case Number', updatedCase.CaseNumber);
       record.put('Reason', updatedCase.Reason);
       record.put('Type', updatedCase.Type);
       record.put('Contact',updatedCase.Contact.Name);
       record.put('Subject',updatedCase.Subject);
       records.add(record);
    }
    if(records.size() > 0) {
    GSEvents.calloutFromFuture(JSON.serialize(records), sharedSecret,tenantId, eventName,topicName,eventVersion); }
}

Additional Resources 

• For more information on mapping, refer Add Participants to a Program.
• For more information on Remote Site Settings and how you can add a new site, refer to the Add External Sites in Remote Site Settings section in the Onboarding Step 1: Install Gainsight & Configure article.