Skip to main content
Gainsight Inc.

Events Framework

  1. Last updated
  2. Save as PDF 
Gainsight NXT

 

The images and videos in this article are soon going to be updated as per the new UI.

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.

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: <gainsight-domain>/v1/ui/eventsV2#/events-dashboard/topics/list

Or navigate to Administration > Events.

Events_API_1.png

  1. 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.
  2. Click the show shared secret key gear icon and copy the key any time.

Events_API_2.png

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.

Create a Topic

Perform the following actions to create a Topic:

  1. Click + New Topic in the TOPICS page. Add New Topic dialog appears.
  2. Enter the following details in the Add New Topic dialog:
  • Topic Name: Enter the exact name of the topic which is used while configuring the publisher. For example, you can create a topic named “Tickets Closed” for events related to the operation when Tickets are closed. Ticket Satisfaction Survey is sent when a customer’s support ticket is closed as an event under the Tickets Closed topic.
  • Description (Optional)

  1. Click SAVE. A new Topic is created.

Create a Topic.gif

  1. (Optional) Click the Edit Description icon to edit the description at any time.

4. Edit Description.gif

Create an Event

Perform the following actions to create an Event:

  1. Click the Configure Events button in a Topic or navigate to the Events tab and select the required Topic.

Navigation_to_Create_Event.gif

  1. Click + Create New Event.
  2. Enter the following details to create an Event:
  • Event Name: Enter the exact name of the event which is used while configuring the publisher. For example, If you want to create an event for a ticket satisfaction survey to be sent whenever a support ticket is closed, you can name it as “Ticket Closed for Reporting Issue”.
    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.
  • Version: Assign a version number. Versions are useful when there are similar events, but with different structures and you need to track them separately. For example: The “Ticket 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 events (1.0 and 1.1) are treated as two different events.
  • Topics: Select the required Topic in which you want to create an event.
  • Description: (Optional) Write a description of the event.

Create New Event.gif

  1. Structure: Click + Add New to add fields that are passed in the Event API call by Publisher. 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: ContactEmail from the structure specified below is used for mapping to the Recipient Email Address field of the participant.
  2. Enter multiple field names as shown below:
    1. Enter exact Name of the field which is passed in the Event API call.
    2. Select Datatype of the field. Event framework supports selecting five data types, String, Number, Boolean, Date, and DateTime.
    3. Click Save Structure Item.
    4. Click the Add Event Field button to add another Event field to the structure.

  3. Click Save.

Notes:

  • You can add a new Event field at any time later according to your configurations in the publisher event and Participant configuration in the Program, but you cannot edit or delete the existing fields in the event structure.
  • Event structure is not required for Events that can be consumed as schedulers in Rules Engine.

Add Event Fields.gif

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

JO_Field_mappings.png

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

Resolve Event Fields

This feature helps you to resolve records from the sender of the Event to records stored in the Gainsight objects. You can perform this by mapping fields added in the event structure with fields from the Gainsight Standard objects, Person, User, Company, and Relationship, as required.

You can resolve event fields with Gainsight, but the dependent Gainsight applications (consumers) of this feature are currently in development. Journey Orchestrator honors the resolution of Event Fields functionality in the Event Framework. This helps admins resolve records from the sender of the Event to records stored in Gainsight objects.

With the help of the resolving Event Fields functionality, admins can take the following actions:

  • Select lookup fields for event source filters while:

    • Creating Event Fields
    • Adding Events as a source
    • Using Event Fields in Conditional Wait 

  • Map lookup fields in the Mapping Participant Sources section for the selected event source.

To apply this configuration:

  1. Click the Resolve event fields checkbox. You can see target Gainsight objects from the events fields, Person, Company, Relationship, GS User (CSM,Other User).
  2. Select the option, Person to apply field mappings between Event fields and Gainsight Person object as shown below:
    1. Select Event field on the left dropdown and field from the Gainsight Person object.
    2. Click + to add multiple field mappings.
    3. Select the checkbox to Resolve to Company Person via Person. This resolves a person record to the corresponding record in the Company Person using Company Person ID field.
    4. Select the checkbox to Resolve to Company via Company Person. This resolves a record from the Company Person object to the corresponding record in Company using Company ID field.
    5. Select the checkbox to Resolve to GS User via Company. This resolves a record from the Company object to the corresponding record in the User object using CSM field.
      Note: Similar resolutions can be applied on the Relationship Entity as well. You can select checkboxes to resolve from Person to Relationship Person, from Relationship Person to Relationship, from Relationship to GS User.
  3. Select the option, Company to apply field mappings between Event fields and Company object as shown below:
    1. Select Event field on the left dropdown and field from the Company object.
    2. Click + to add multiple field mappings.
    3. Select the checkbox to Resolve to GS User via Company. This resolves a record from the Company object to the corresponding record in the User object using CSM field.
  4. Select the option, Relationship to apply field mappings between Event fields and Relationship object as shown below:
    1. Select Event field on the left dropdown and field from the Relationship object.
    2. Click + to add multiple field mappings.
    3. Select the checkbox to Resolve to GS User via Relationship. This resolves a record from the Relationship object to the corresponding record in the User object using CSM field.
  5. Select the option, GS User to apply field mappings between Event fields and User object as shown below:
    1. Select Event field on the left dropdown and field from the User object.
    2. Click + to add multiple field mappings.
  6. Click Save.

Resolve_Event_Fields.gif

Note: You can apply resolution from Event fields to single Gainsight objects directly including the Person, Company, Relationship, or User objects. You can also apply resolution to another standard object through the current object as explained above. For example, you can resolve event fields to Company Person through Person, Company through Company Person, etc.

Manage an Event

After an Event is created, you can edit, delete, test the Event, and view Events Logs. Following are the available options to manage an Event:

  • View Event Structure: Click this button on a specific Event to view Event Structure (list of added Event fields) directly on the Event list page.
  • Edit Event: Click this button to edit an existing Event. Once an Event is created, you can edit the Description, add new Event fields to the Structure, and apply or change Resolution of Event fields.

8. Manage an Event.gif

  • Test Event: Click this button to test an existing Event. You can test an Event using two Publishing types: Test Event or Publish Event.
    • Test Event: Select this option and click Submit to test an event. Current Event is successfully tested and shows results in the Response field. If you think there are any issues in the Event, you can use eventId from Response and share with Gainsight Support to debug the event.
    • Publish Event: Select this option and click Submit to publish an event to the Subscribers manually. This executes a Rule or orchestrates a Program to new participants where the Event is configured.

Test an Event.gif

  • Event Logs: Click this button to see Test Events, Publish Events in a graphical form against time and the list of Event Logs in a tabular form. Test Events and Published Events are identified with Red and Green color spikes on the graph respectively. You can test any Event again from the logs by clicking the Retest an event button. After retesting, graph and table for the list of events are updated as shown below:

10. Event Logs.gif

  • Delete Event: Click this button to delete a specific Event.

Program Events Workflow

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

11..png

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

  1. 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.
  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/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.

Participants_Configuration_Select_Event.png

13. Participants_Configuration_Source_(Events).png

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.

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    1. Events Framework- Admin Guide