Reveal Central Slack Connector Setup

Slack Connector Prerequisites

Overview

Reveal Hold supports integration with Slack for data collection. This document describes the prerequisites for integrating Reveal Hold with Slack.

Information Required for Integration

Reveal Hold Slack connectors integrate with Slack through APIs and require a service account.

Create Slack ORG Token

Follow the steps given below to generate an Org API Token.

1. Go to https://api.slack.com/apps  and click the Create an App button.

   

   Figure: Create a Slack App Modal

2. In the modal that appears, enter the App Name and select a Workspace that belongs to your Org from the dropdown. (Any workspace can be chosen from the list. It does not matter which one is chosen).

   

3. Click the Create App button to proceed. You can see App credentials after Creating the App as below.

   

4. Go to OAuth & Permissions in the left navigation menu. Scroll down to the Redirect URLs section and click the Add New Redirect URL option.

5. Enter https://localhost in the input box and click Add. Then click Save URLs.

   

   Figure: OAuth Tokens and Redirect URLs

   

   

6. Scroll down to the Scopes section. The appropriate scopes can be added to the app from this section. Add the appropriate scopes to the User/Bot Token Scopes section. The required scopes For Org APP include:

   1. Bot Token Scopes:

      1. users:read.email

      2. users:read

      3. channels:read

      4. groups:read

      5. im:read

      6. mpim:read

      7. channels:history

      8. Groups:history

      9. im:history

      10. Mpim:history

      11. files:read

   2. User Token Scopes

      1. users:read.email

      2. users:read.email

      3. users:read

      4. channels:read

      5. groups:read

      6. im:read

      7. mpim:read

      8. channels:history

      9. Groups:history

      10. im:history

      11. Mpim:history

      12. files:read

      13. admin.legal_holds:write

      14. admin.legal_holds:read

      15. admin.teams:read

      16. discovery:read

      

      Figure: User Token Scopes

      

7. Now that proper Permission Scopes and OAuth Redirect URLs have been configured for the app, the app distribution needs to be activated. This is a necessary step to activate the app on an Org level to generate the token. Go to Manage Distribution in the left navigation and scroll down to the Share your App with Other Workspaces section.

   

   Figure: Share App with Workspaces

8. Click on Remove Hard Coded Information to expand the field and access the last required checkbox. Check the box that says I’ve reviewed and removed any hard-coded information.

   

   Figure: Remove Hard Coded Information

9. Click on Org Level Apps under Features and enable org-readiness button to allow the feature to install app on organizational level.

   

   Figure: Enabling Org-readiness App Feature

10. Verify that all four green tick marks are available next to the required steps under the Share Your App with Other Workspaces section. The Activate Public Distribution button should become enabled. Click on the button to active public distribution and the page will reload.

    

    Figure: Activate Public Distribution

11. After the page reloads, copy the Shareable URL.

    

    Figure: Shareable URL

12. Open a new incognito/private browser window and log into the enterprise grid URL <organization-domain>.enterprise.slack.com using the Org Owner credentials. Org Owner login is needed in most cases to install the app to the Enterprise Grid Org.

13. From the Workspace Directory landing page, click the Launch in Slack button to open any workspace in a new tab.

    

    Figure: Workspaces Directory

14. After logging in and loading a workspace, open an additional browser tab and enter the Shareable URL (copied in step 11) into the browser’s address bar to initiate the OAuth handshake that will install the app on Org. On the OAuth page, verify that the dropdown in the upper right corner of the installation screen reflects the Enterprise Grid Organization and not an individual workspace within the organization. Click Allow once it is confirmed.

    

    Figure: Allow Access to Org Workspace

15. Once the OAuth process is completed the user is redirected back to the localhost. The page will most likely show a 404 error. However, this is expected and the needed information is in the URL address bar. Copy and save the value for code from the URL. Do not include the preceding equal sign (=) nor the terminating ampersand (&).

    

    Figure: LocalHost

16. Navigate back to the Basic Information section in the left navigation of the Slack App and copy the Client ID and Client Secret.

    

    Figure: Basic Information

17. Build a URL string using the three pieces of information that have been collected so far: Code, Client ID and the Client Secret (copied from steps 14 and 15).

    https://slack.com/api/oauth.v2.access?code=8351753648.22312133905.eb189 d3a499f74989c3ba9bf6aa9c7802616df9dd87015be638bd5fb793128ce&client_id=1

    6115454624.23409468640&client_secret=63f4fc0bee2d0eaa2fa83c7a25bed7de

    Be sure to replace only the bold sections in the URL above with the appropriate values. The other elements such as the base URL, argument names, and symbols should remain as presented above.

18. Paste the newly built URL into a new browser tab and press enter.

19. Once the OAuth process is complete, a page appears with the following example response:

    {"ok":true,"access_token":"xoxp-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXX","scope":"admin,identify","user_id":"WXXXXXXXX","tea m_name":"Org Sandbox","team_id":"TXXXXXXXX","enterprise_id":"EXXXXXXXX"}

20. The access_token value (xoxp-*) in the response is the Org API token. Store this token securely.