Skip to main content
Gainsight Inc.

Events API

Overview

The Gainsight Events Framework allows you to create events, which can be used in Programs and Rules Engine. Events can be defined as activities that are triggered as a result of some other activity. For example, the Events framework can be used when a Program needs to be triggered on the case closed event for SF Cases. Another example of an event is a notification email that is sent whenever a participant responds to a survey. An example of an event would 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, event-based triggering of a rule enables you to integrate rules deeper with non-Gainsight services if you have developer support.

The Events framework has the following components:

  • Publisher: The sender of the event is defined as the publisher. For example: In the CSAT Survey model for Programs, Salesforce or Zendesk will be the publisher of the case closure event for every case that is closed.
  • Subscribers:  Subscribers are the processing entities/applications that decide what 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 is the first available subscriber; Gainsight will be adding more subscribers in the future.
  • 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 “Case Closed” and “Case Reopened” can belong to the topic “Case”.

Create an Event

Perform the following steps to create an event:

  1. Open the following link in a web browser: 

https://<Salesforce instance url>/apex/Administration#Administration-EventsFramework

Events Framework Image 1.png

  1. Click the ENABLE AS PUBLISHER button to enable the org to use the Events framework. A key is generated which will be used while configuring the publisher.
  2. Click the Show List of Topics pane.
  3. Enter a name in the CREATE TOPIC field and click it to create a topic. Topics provide you with a mechanism to separate your events as per your business needs. For example, you can create a topic named “Survey” for events related to the Survey operation. A notification email sent when a customer responds to the survey can be created as an event under the Survey topic.

     Create Topic.png

Note: If topics are already created, select a topic from the list.

  1. Click on the topic name that you have created. The List of Events page is displayed.

List of Events page.png

  1. Click the Create Event pane. You can also search for existing events if they are already created.
  2. In the Event Name field, enter a name for the event. For example, If you want to create an event for a case satisfaction survey to be sent whenever a case is closed, you can name it as “Case Closed Survey”.

Note: A single topic cannot have more than one event with the same name. However, you can create events with the same name if they belong to different topics and solve different business problems.

  1. In the Version field, enter a version for the event. Versions are useful when there are similar events, but with different structure and you need to track them separately. For example: The “Case Closed Survey” can be configured with the same name, but using different versions whenever there is a change in the structure. If there is a case closure event with 1.0 as the version, and there is a need to update the structure of the event, another event with version 1.1 can be created without losing the details of the 1.0 event. Both the events (1.0 and 1.1) are treated as two different events.
  2. In the Content Type field, enter the type of content. Content Type specifies the data format supported. Currently, the supported values for Content Type are application/json and Text.
  3. In the Structure field, enter the structure associated with the event. Structure defines the sample format of an event so that subscribers of an event can consume it. In Programs, it is used for mapping to the participant fields. For example: Recipient Email from the structure specified below is used for mapping to the recipient email field of the participant.

Sample event for Programs

Event Name: Case closure

Event Version: 1.0

Content Type: application/json

Event Structure: {"headers":["Recipient Email","Account Id","Account Name","Case Number","Reason","Language","Closed Date"]}

Contract Mandatory: False

Notes:

  • The fields that are added in the Event Structure are available for mapping to standard fields in the Programs > Participants Configuration page. If you want to map additional fields to standard fields, you can update the Event Structure with the additional field. For more information on mapping, see the Adding Participants to a Program article. 

Standard Fields Mapping.png

  • It is mandatory to follow the above event structure while defining an event for Programs.
  • The size of the structure for an event should not exceed 400 KB.
  1. Set the Contract Mandatory field to false. If there is a Contract Id associated with any specific event, then you can set the Contract Id to true which mandates the value to be passed while posting the event. Contact support@gainsight.com to get further details on this.
  2. Click CREATE EVENT. The event is created and added to the topic. The events created can be consumed by Programs. For example, events created here will be listed while adding the participant source configurations in Programs.

Note: If there is a requirement to delete an existing event and create the same event again, Gainsight recommends that you do not delete the existing event, instead create a new event with a different version.

Program Events Workflow

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

Workflow of events in Program .png

The above diagram specifies how a case closure event in Salesforce is published to its 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 case satisfaction survey right after a case is closed. This can be achieved by setting up a trigger once the case 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. Create a topic + event using the steps provided in the Create an Event section.

Create the event with the following details:

Event Name: Case closure

Event Version: 1.0

Content Type: application/json

Event Structure: { "headers":["Recipient Email","Account Id","Account  Name","Case Number","Reason","Language","Closed Date"] }

Contract Mandatory: False

  1. When the Salesforce case is closed, the event is published to the topic by the publisher. The recommended approach is to use a trigger created on the SFDC case object, which in turn calls the API by passing the required information as part of the POST call.
  • A sample SFDC case trigger script is listed here. If you need help in configuring the script, please contact support@gainsight.com.
  • A new site in the Remote Site settings must be added. For more information about what is 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.
  1. 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.
  2. The Programs feature then receives the case events and processes them to add as participants and send further emails. To validate, you can check if the participants have been added inside the Program.

Participants Configuration_Select Event.png

Participants Configuration_Source (Events).png

Note: Only after the Program is published by configuring the participant source as an event (see screenshots above), the events that are generated from the SFDC case trigger are eligible to be processed. Each event received by Programs turns into a participant, based on the unique criteria selected.

Sample SFDC Case Trigger

trigger Caseclosure on Case (after update) {

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 == 'Closed') {

       System.debug('triggering call out');

       caseids.add(updatedCase.Id);

     }

   }

List<case> cases = [Select CaseNumber,ContactEmail,AccountId,ClosedDate,Reason, Account.Name, Contact.Language__c from Case where Id in :caseids];

     for(Case updatedCase : cases) {

       Map<String,Object> record = new Map<String,Object>();

       String prefLanguage = updatedCase.Contact.Language__c;

       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('Language', updatedCase.Contact.Language__c);

       record.put('Closed Date',updatedCase.ClosedDate);

       records.add(record);

  }

   Map<String,String> headers = new Map<String,String>();

   Map<String,Object> data = new Map<String,Object>();

   data.put('participantInformationList',records);

   data.put('eventName','Case Closure');

   data.put('topicName','SFDC Case');

data.put('eventVersion','1.0');

// post the event

JBCXM.GlobalAPI.asyncCallMDA('/api/aoevents/postEvent','POST',JSON.serialize(data),headers);

}

}

 

  • Was this article helpful?