Skip to main content
Gainsight Inc.

Configure External Action from Gainsight

The Call External API allows you to establish a connection with external systems from within Gainsight and request action from the external system via an API. In this case, Gainsight is the source system and the external application to which you connect, is the target system.

You can use the External Actions while creating a Rules Engine Action and while configuring a Program from Journey Orchestrator.

Business Use Cases:

  • You can create a rule which posts messages to Slack when an opportunity is won. This message helps teams know the details of a newly won opportunity. In this case, Gainsight is the source application and Slack is the target application. The method used is POST (posting a new message to Slack).
  • You can create a rule which fetches all of your escalations from a CSV file or from an S3 bucket and creates JIRA tickets for each of the escalations. In this case, Gainsight is the source application and JIRA is the target application. The method used is POST (creating new JIRA tickets).

Overview

An Application Programming Interface (API) is a set of routines, tools, and protocols that assist you in building software applications. APIs pave the way for two software applications to interact with each other.

API in Layman's Terms: Consider that you visit an apparel store. You are looking for a shirt in size X-large. However, the store only has the required apparel in medium size. The required X-large size is present in a warehouse which cannot be accessed. You ask a Salesperson to get you the required size. The Salesperson honors your request and gets you the required apparel with the required size.

In the above example, the Salesperson is the API. You are the first system and the warehouse is the second system. As defined above, an API facilitates interaction between two systems; the system which requests information (you), and the system which serves the required information.

In technical terms, an API is defined as a messenger that accepts requests from a system (source system), forwards this request to the required system (target system), collects the response, and returns the response to the first system.

The Call External API allows you to establish a connection with external systems from within Gainsight and request action from the external system via an API. In this case, Gainsight is the source system and the external application to which you connect, is the target system.

You can use the External Actions while creating a Rules Engine Action and while configuring a Program from Journey Orchestrator.

Business Use Cases:

  • Lets you create a rule which posts messages to Slack when an opportunity is won. This message helps teams know the details of a newly won opportunity. In this case, Gainsight is the source application and Slack is the target application. The method used is POST (posting a new message to Slack).
  • Lets you create a rule which fetches all of your escalations from a CSV file or from an S3 bucket and creates JIRA tickets for each of the escalations. In this case, Gainsight is the source application and JIRA is the target application. The method used is POST (creating new JIRA tickets).

API Authorization Methods

To receive information from the target system, the source system must authenticate itself. There are four authentication methods:

  • URL Based Authentication: This method requires you to know the URL of the target system. No secret code or password is needed in this method. In the above apparel example, you need to just know the address of the warehouse. The warehouse does not have any locking system.
  • User Name and Password Authentication: In this method, the source system must provide the credentials to authenticate itself. In the above apparel example, you need to have the Key (Username and Password in API) of the warehouse to access the contents of the warehouse.
  • Token Based Authentication: In this method, the source system provides a token as a means of authenticating itself. This token is generally a key-value pair. In the above apparel example, the shopping store sends out an email to you which has a piece of information (say token). You need to show this token to the warehouse guardian to get access to the warehouse.
  • OAuth 2.0 Authentication: OAuth 2.0 protocol allows you to grant secure and limited third-party access to your assets without having to expose your credentials. When you create a connection to an external application, select OAuth 2.0 as the authorization method to establish the connection and then setup parameters for this authorization mechanism.

Operations on APIs

Perform the following operations using APIs:

  • Receive Data (GET): Get refers to the process in which the source system receives information from the target system. In the apparel example, if you (source system) wish to get any particular cloth from the warehouse (target system), you perform a get operation.
  • Create New Data (POST): When the source system posts some information in the target system, a POST operation is said to be executed. In the apparel example, if a supplier (source system) wants to push new apparels to the warehouse (target system), a POST operation is said to be executed.
  • Update Data (PUT): When the source system updates some data in the target system, a PUT operation is said to be executed. In the apparel example, if a tailor (source system) alters the size of some apparels from the warehouse (target system), a PUT operation is said to be executed.
  • Delete Data (DELETE): When the source system deletes some data from the target system, a delete operation is said to be performed. In the apparel example, if the warehouse owner (source system) discards some damaged apparels from the warehouse (target system), a delete operation is said to be performed.

Components of an API Message

When the source system requests data from the target system via an API, the API message has the following components:

  • Endpoint URL: This is the URL of the target system from which data is being requested. In the apparel example, the address of the warehouse is considered as an endpoint URL.
  • Method: The Operation to be performed by the API; either be GET, POST, PUT, or DELETE.
  • Header: Header refers to some specific attention or request made by the source system.  In the apparel example, you may wish to buy apparel of a specific brand which is an example of a header.
  • Data: The actual data requested through the API. Data is generally present in the form of key-value pairs. The following image displays API data. The data is present in key-value format.

API Message.png

Prerequisites

  • To establish a connection to the external system, one of the authentication methods (specified above) must be used. Perform this configuration from the Custom Connectors widget in the Connectors page.
  • Once you establish a connection with the external application, configure the API message, as required. Once you finalize your API structure, use the API in the Call External API action type. Perform the API configuration from the External Actions page in Gainsight. The API format and structure is obtained from the external system. Generally, external systems (like slack, Zendesk) expose their APIs on their website.

Configure Custom Connectors

Gainsight has introduced custom connectors in the Connectors 2.0 page. You can use a custom Connector to establish a connection to an external application. Once the connection is established, you can create actions for the external application on the External Actions page.

When you create a connection to an external application, you must specify the Authorization method used to establish the connection and then setup parameters for this authorization mechanism. Gainsight recommends you to create only a single connection to an external system. You can then create multiple actions on the connection, as needed.

To create custom Connections:

  1. Navigate to Administration > Connectors 2.0
  2. Click Create Connection. The Create Connection window appears.
  3. Search and select for the Custom Connector in the dropdown menu.
  4. Enter the following details:
    1. Connection Name: Enter a name for the Connection in this field.
    2. From the Authorization Type drop-down menu, select either Basic or Token Based or OAuth 2.0 authorization.
      • Basic: This authorization method uses the traditional User Name and Password to authenticate the connection. Enter the following details:
        • User Name: Enter the username of the target application in this field.
        • Password: Enter the password of the target application in this field.
        • Headers: Provide the Key and Value pair(s) in the Headers field. If required, you can provide multiple headers by clicking the + icon. Click the X icon to delete a header.
        • (Optional) Description: Enter a description for the connection.
        • GET URL: Specify the GET URL of the target application in this field.
        • Click Test Connection to verify your connection to the target application.
        • Click Save.
      • Token Based: This authorization method uses a header based key value pair to perform authorization. Enter the following details:
        • Headers: Provide the Key and Value pair(s) in the Headers field. If required, you can provide multiple headers by clicking the + icon. Click the X icon to delete a header.
        • (Optional) Description: Enter a description for the connection.
        • GET URL: Specify the GET URL of the target application in this field.
        • Click Test Connection to verify your connection to the target application.
        • Click Save.
      • OAuth 2.0: This authorization method uses Access Tokens. An Access Token is a string representing the granted permissions. Enter the following details:
        • Content Type: Select the content type that is compatible with the external authorization provider.
        • Redirect URL: This is the callback URL that you will be redirected to, after your application is authorized. It is used to extract the authorization code or access token. The callback URL should match the one you use during the application registration process. The URL is present by default and if required, you can copy it using the copy icon.
        • Authorization URL: Provide the authorization URL that is given in the external API documentation.
        • Access Token URL: Provide the access token that is given in the external service API documentation.
        • Client ID: Provide the Client ID from the external application.
        • Client Secret: Provide the client secret from the external application.
        • Scope: Provide the permission scopes of the connection.

          Note: The permissions represented by the Access Token, in OAuth 2.0 terms are known as scopes. When an application authenticates with Auth0, it specifies the scopes it wants. If those scopes are authorized by the user, then the Access Token will represent these authorized scopes.
        • (Optional) Description: Enter a description for the connection.
        • Click Authorize, to validate the connection.

Admins can also use the Edit option to edit the custom connectors configured if required

Configure External Actions

Once you set up a connection to an external application, create actions on the External Actions page. Once you create an action here, this action can be used in the Rules engine action type field and JO. The External Actions page has five sections to configure.

For example, if Slack is the external connector configured, create action types such as ‘Post to Slack’ or ‘Create a New Slack channel’.

The actions created for Slack connector can be used in the Call External API Action Type. The “Call External API” action allows Gainsight to interact with external applications and perform actions that are configured in the External Actions page. Use the configured action types to automate day to day activities like posting messages to Slack, creating or updating status to the Zendesk tickets, creating JIRA tickets, and so on.

Important:Connect and configure Actions only to the external applications that support and provide API documentation.

To access the External Actions page:

  1. Navigate to Administration > External Actions.
  2. Click Create Action.

    External Actions.png

The various sections present in the External Action page are:

Basic Information

In this section, enter the details in the following fields:

Prerequisite: Refer to the external application’s API documentation for specific action, to collect the required parameters, for configuring the External Action in Gainsight. These API parameters are required to connect Gainsight through an API to the external application and pass details to perform the required action.

  1. Select a Connector: Select the connector that you have created in the Connectors 2.0 page, for which you want to create an action.
  2. Action Name: Enter a name for the action.
  3. Method and URL: Select an HTTP Method and enter the Endpoint URL from external application’s API documentation, specific to the action that you are configuring.

Note: Admins can also use tokens or variables in the URL to make it a dynamic URL.

Payload

API's use payloads to exchange data structures which are too large to be handled as parameters. External Actions in Gainsight supports two types of payloads:

  • Plain: Enter the payload details by copying from the application’s API documentation in the format specified. (Ex: json format)

    payload.png

  • To create a field from the token entered in this section, add the token in double curly braces as shown below:

    }Message.png

  • x-www-form-urlencoded: Enter Key, Value pairs as defined by the application’s API Documentation. Any token inserted in this section is parsed as a field. Click + to add more Key, Value pairs.

    Message_2.png

payload (2).png

Note: To escape double quote(") and backslash(\) from parsing, use backslash(\) as prefix. No need to add a prefix for other characters.

In this section, enter the key-value pair for header information as defined in the API documentation. Admins can also add multiple key-value pairs as shared by external application’s API documentation. Tokens (Values) that you enter here will be parsed as fields in the Fields section as explained in the previous step.

headers info.png

Fields

In the Fields section, the list of fields that you see is automatically parsed from the URL, Payload, and Headers. Settings icon adjacent to the field, to set the data type of the field (Ex: String, Date, DateTime, etc.) as shown below.

When you use the Call External API action type in Rules Engine, the fields displayed in the Fields section are populated as target fields. Ingest values into these fields from your dataset.

Advanced Configuration Information

In this section, admins can set a limit for the Max Retries Limit field. The numeric value specified in this field represents the number of times that the system retries if the action fails. By default, this value is set to 3 and the maximum limit must not exceed 5.

advanced config info.png

Click Create to save the Action.

advanced config info (1).png

Admins can also click Test to test the actions added and click the Edit option to edit the details of the configured action.

In this case, a ticket is created in Zendesk when you test the action.

 

  • Was this article helpful?