Salesforce Knowledge Extension : Salesforce and QUIP integration using REST API

Thought Process behind this implementation

Hi all, it has been long time since I posted something. So, today’s topic is bit interesting - how Someone can use Quip REST API from salesforce and as it is a new add-on functionality, so the number information is limited on the authentication mechanism. I will be trying to explain this with a business use case, so that in future someone can relate their requirements very easily.

Use Case

We have a quip Template in place which is currently storing the Account Plan related data for that account. As we have so many numbers of Accounts in the Org, it is very difficult to search those documents in Quip portal once those are created. So, the next thought came into our mind to keep those documents in a proper logical way, that could be anything based on how your current Accounts are being segregated. The folder name would be your Account Name, by which you quip user can easily recognize the document. Now it is very difficult to create those folders manually, so somehow, we should manage to create those Folders via some automation by implementing Quip REST API. The possible scenario would when user will be generating the document in salesforce, the folder Should be created on that action itself.

Let say we are having a field at Account object name is Type having three options, those are: -

· Customer

· Prospect

· Other

Now these are the predefined valued so we can create those folders beforehand in Quip Portal , but we don’t know which Account is going to have which type , so the Account Folder under each Type will be created dynamically.

Please refer the below snap for your better understanding: -

How Architecture works behind

1. Create the folder structure colored as blue mentioned in the above diagram.

2. Automation API and Admin API.

3. To create New API Key on Your Quip Site.

4. Grant a Quip Admin API Access for the User which will be used to call Rest API service from Salesforce.

5. Authorization can be done by to ways, to get the access token, those are: -

a. Use Postman to get the access token.

b. User your visual force page to get the access token.

6. Once you have the access token, you can call the rest API service defined by QUIP based on your needs.

Process to implement

· Automation API and Admin API

The automation API allows you to make API calls on threads that the user has access to, and Admin API allows access to all threads against the entire site. Admin also has few additional endpoints around Events API, Governance policies, quarantine, admin roles, etc. As for the token generation, we can use the /dev/token URL

for automation and we can have the domain authentication for an admin API token.

· To create New API Key on Your Quip Site

As discussed, first we need to create the API key in quip portal.

Navigate to the Admin Portal > Settings > Integrations > New API Key.

To stay organized, select a name for the key that will make it obvious what it was used for. It will look like below: -

· Grant a Quip Admin API Access for the User which will be used to call Rest API service from Salesforce.

1. Go to the Admin Console > Site Settings > Admin Roles.

2. Select Create New Role

3. Name Role and select your desired permissions for each category, including Admin API Access > Edit.

4. Assign this Role to the Admin or Admins you would like to be able to manage API Access.

5. That admin will see a new section in the Site Settings page of their admin console.

6. Click Grant Access to provide access to a user entering email and access level.

7. To edit or revoke access using the dropdown menu from the right of the user row.

· Access Token Generation

1. There is a concept of Dev Toke, which is basically nothing but act like an access toke, but it’s only for developer to test their functionality only, It’s user specific and developer should only use this for testing purpose only. We do not need to perform the second (above) step to achieve this. Please adjust the quip portal URL to get the dev token: -

https://xxx.quip.com/dev/token

Now you can use it as access token to hit the QUIP rest API resources.

2. Use Postman to get the access token: -

Pull the latest and download and open Postman. https://www.getpostman.com/downloads/

Step by step instructions to download and install can be found here - https://www.guru99.com/postman-tutorial.html

a.) Once postman in installed, create a new request –

b.) Create a name for the request and select a collection or folder to save these requests.

c.) Now, let us connect postman to your Quip instance.

Click on Auth and select OAuth 2.0 and click on Get new access token.

d.) Grant Type= Authorization code.

· Callback URL: https://platform.quip.com

· Authorize URL: https://platform.quip.com/1/oauth/login

· Access Token URL: https://platform.quip.com/1/oauth/access_token

· Quip Client ID (Already generated in Process implementation section)

· Quip Client Secret (Already generated in Process implementation section).

e.) You will see the login to Quip. Give your login information and you are ready to us the API.

Calling Quip Rest API endpoints based on the requirement: -

Once you will have the access token and security token, we just need to follow the documentation to call the respective API end points based on the requirements.

Please refer the below generic function which can be called from another trigger or Apex class:

/*
  Method Name : createNewFolder
  Input Parameters : accName, parent folder Id (which created earlier).
  purpose : It will take account name and parent folder id as a parameter and using rest api call created the new folder at th quip portal.
 */

public static void createNewFolder(string accName, String parentFolderId) {
	try{           
		if(parentFolderId != null && accName != null){
			HttpRequest req2 = new HttpRequest();
			req2.setMethod('POST');
			
			// End point for creating new folder
			req2.setEndpoint('https://platform.quip.com/1/folders/new');
			//Access toke which we already got using postman
			String authHeader = 'Bearer '+access_token;
			req2.setHeader('Authorization', authHeader);
			//the parameters should be pass within the body
			String body2 = 'title='+accName+'&parent_id='+parentFolderId;
			req2.setBody(body2);
			Http http2 = new Http();
			HTTPResponse res2 = http2.send(req2);
			System.debug(res2.getBody());			
		}
	}Catch(System.CalloutException e){
		System.debug('Error-' + e.getMessage());   
	}
}

· Note: -

Quip provides two standard roles - Site Admin and Super Admin. Out of those, only Super Admin role will have the provision to create custom roles.

Quip is only offering OAuth 2.0 Web Server Flow for authorization which needs user intervention to generate the access token and in our use case we do not have the provision for user intervention. We had a discussion with Quip technical team, and they agreed that for now they don’t have any server-to-server authorization mechanism and we should generate the access token beforehand either using postman or using other component (you can use visual force page as well)

The access token is valid for 30 days and refresh token is valid for 10years, so we recommend constantly generating new access tokens every 28 days or so using the token endpoint. The dev token for automation API is valid for 365 days unless new tokens are generated invalidating the older one.

References:

Quip/Dev

Friday, July 2, 2021

Salesforce and QUIP integration using REST API