Configure External Action from Gainsight

Introduction to APIs

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 you cannot access. You ask a Sales person to get you the required size. The Sales person honors your request and gets you the required apparel with the required size. 

In the above example, the Sales person 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 can be defined as a messenger which 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.

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 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, you can now select OAuth 2.0 as the authorization method to establish the connection and then setup parameters for this authorization mechanism.

Operations on APIs  

You can perform the following operations by 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 can be considered as an endpoint URL. 
• Method: The Operation to be performed by the API. This can 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 can be 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. You can see that data is present in key-value format.

Overview 

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

Prerequisites

• To establish a connection to the external system, one of the authentication methods (specified above) must be used. This configuration can be performed from the Custom Connectors widget in the Connectors page.
• Once you establish a connection with the external application, you can configure the API message, as required. Once you finalize your API structure, you can use the API in the Call External API action type. The API configuration can be performed from the External Actions page in Gainsight. The API format and structure can be 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 use custom Connections:

1. Navigate to Administration > Connectors 2.0.
2. Click Custom Connector.
3. Click Create Connection. The Create a Connection window is displayed.

4. Perform the following tasks:

   1. In the Connection Name field, enter a name for the connection.
   2. From the Authorization Type drop-down menu, select either Basic or Token Based or OAuth authorization.

• Basic Authorization: This authorization method uses the traditional User ID and Password to authenticate the connection. Optionally, you can also provide key value pairs in Headers. You can provide multiple headers, if required. You must also specify the Get URL of the target application.
• Token Based Authorization: This authorization method uses a header based key value pair to perform authorization. You can provide multiple headers, if required. You must also specify the Get URL of the target application.
• OAuth 2.0 Authorization: This authorization method uses Access Tokens. An Access Token is a string representing the granted permissions.
  • Client Secret: Provide the client secret from the external application.
  • Client ID: Provide the Client ID from the external application.
  • Access token URL: Provide the access token that is given in the external service API documentation.
  • Authorization URL:  Provide the authorization URL that is given in the external API documentation.
  • Content Type: Select the content type that is compatible with the external authorization provider.
  • 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.

Note: You can also select None as the Authorization type. This provides direct access to the application.

5. (Optional) Enter a description for the connection.
6. Click TEST CONNECTION to verify your connection to the target application. 
7. Click SAVE.

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

Configure External Actions

Once you setup a connection to an external application, you can 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 for you to configure. 

For example, if Slack is the external connector configured, you can 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. You can 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: You can 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: 

{“text” :  “ {{ Message }} ” } 

Key: text, Value: {{Message}}

Additional Resources

For more information about how to use the Call External API action in Rules Engine, refer to the Call External API Action Type article.

For more information about how to use the Call External API action in Programs, refer to the Call API Action Type in Programs article.

For more information about using the Call External API action type in Rules Engine to create Zendesk Tickets automatically, refer to the Create Zendesk Tickets from Call External API Action Type article. 

For more information about using the Call External API action type in Rules Engine to post messages to Slack automatically, refer to the Post Messages to Slack with Call External API Action Type article.