Docly

Slack Integration

Estimated reading: 4 minutes

This document walks through the steps required to install a Stemma Slack application in your workspace.

Prerequisite

Stemma does not publish the Stemma Slack application to the Slack Marketplace. To install this application for your workspace, you need to create a new application using an application manifest file.

If you have an application manifest file, make sure you have it handy before you begin. If you don’t have a manifest file, you can copy and paste the following into a file:

_metadata:
  major_version: 1
  minor_version: 1
display_information:
  name: Stemma
  description: Help you enrich your metadata directly via Slack
  background_color: "#0a1930"
features:
  bot_user:
    display_name: Stemma
    always_online: true
  slash_commands:
    - command: /stemma
      url: https://{SUBDOMAIN}.stemma.ai/api/stemma/slack/v1/slash/help
      ## Replace {SUBDOMAIN} with your Stemma subdomain.
      description: Learn how StemmaBot works
      usage_hint: help
      should_escape: false
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - channels:history
      - channels:read
      - chat:write
      - commands
      - groups:history
      - groups:read
      - links:read
      - links:write
      - users:read
      - users:read.email
settings:
  event_subscriptions:
    request_url: https://{SUBDOMAIN}.stemma.ai/stemma/slack/events
    ## Replace {SUBDOMAIN} with your Stemma subdomain.
    bot_events:
      - app_mention
      - link_shared
      - member_joined_channel
      - message.channels
      - message.groups
      - team_join
  interactivity:
    is_enabled: true
    request_url: https://{SUBDOMAIN}.stemma.ai/api/stemma/slack/v1/interactivity
    ## Replace {SUBDOMAIN} with your Stemma subdomain.
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

Save the file with any prefix and in any location you like, but make sure:

  • The filename has the suffix .yaml.
  • You replace {SUBDOMAIN} with your Stemma subdomain.

Steps

Step 1: Verify your application manifest file

Make sure that at least the following properties in the application manifest file match your Stemma endpoint:

  • features → slash_commands → url:
  • settings → event_subscriptions → request_url
  • settings → interactivity → request_url

Step 2: Create and install your Stemma Slack application

Create a new application using the application manifest file.

a. Navigate to: https://api.slack.com/apps, and click Create an App.

b. You will be prompted to select a method to create a Slack Application. Select From an app manifest, and choose the workspace in which you want to install the Stemma Slack application.1088

c. Paste in your manifest file. Make sure you select the YAML format, and paste in the contents of the file (see Prerequisite above).1088

d. Click Next and verify the scopes and events the Stemma Bot is requesting. Finally, click Create to install the application to your workspace.

Step 3: Provide Signing Secret and Bot Token to Stemma

To secure the communication between Slack and Stemma, you need to provide Stemma with the Signing Secret and Bot User OAuth Token of your newly installed Stemma Slack application:

  • Signing Secret:
    • You can find the Signing Secret on the Basic Information page, in the App Credentials section.

2144

  • Bot User OAuth Token:
    • You can find this token on the OAuth & Permissions page, in the OAuth Tokens for Your Workspace section.

2364

Now provide the Signing Secret and Bot User OAuth Token to Stemma:

  1. Navigate to the Admin tab of the Stemma UI and choose Connections and Add New Connection:
  1. In the pop-up window, choose Slack as the Connection type, provide a Connection Name, and then in the dialog box enter the Bot Token and Signing Secret.
  2. When you are finished, click Save Connection.

Step 4: Receive confirmation from Stemma

Stemma will use the information you provide to integrate your Slack workspace with your Stemma Instance. Once you get the confirmation, you should be able to type /Stemma help in Slack to see usage help for the Stemma Slack application.

Step 5: Make sure to add an app icon 😊

Under the Stemma (Slack Application) basic information Tab, add the Stemma icon in the “Display Information” section. Users will be much more likely to use the bot if it’s easy to identify.1024

(Nice to have) Please invite Stemma team member(s) to a shared test channel

At this point, you have the Stemma Slack application installed within your Slack workspace. In order to verify if things are working just fine with no errors, you can create a temporary shared channel and invite a couple of members from the Stemma team to that channel.

For information about using Stemma with Slack, see Using the Stemma Bot in Slack.