Configure External Action from Gainsight

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.

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. Use a custom Connector to establish a connection to an external application. Once the connection is established, 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 and 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. From the dropdown menu, search and select for the Custom Connector.
   
    
4. Enter the details in the following fields:
   1. Connection Name: Enter a name for the connection.
   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.
        • Password: Enter the password of the target application.
        • Headers: Provide the Key and Value pair(s) in the Headers field. 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.
        • 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. 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.
        • 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 details in the following fields:
        • 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 to copy it, use 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.
          
           
5. Click Authorize, to validate the connection.

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

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.
   
   

The various sections present in the External Action page are:

Additional Resources

For more information about Gainsight APIs, refer to the following articles:

• Call External API Action Type
• Call API Action Type in Programs
• Create Zendesk Tickets from Call External API Action Type
• Post Messages to Slack with Call External API Action Type