SKA Slack Integration

Environment

To develop a Slack app, it is recommended to create your own Slack workspace and test against it.

Marvin Use Case

If the Slack app you are working on is Marvin itself, then you can use a pre-made Slack app named Marvin-Test to conduct your code changes, without the need for setting up your own Slack workspace.

In that case, you should use the following .env variables from the Marvin-Test app.

SLACK_BOT_TOKEN=...
SLACK_SIGNING_SECRET=...

Following the steps in this repository README, start your local testing with make development and expose it outside your local development machine. You can do so using ngrok for instance: ngrok http 3000

Change the various Marvin-Test endpoints to point at your local deployment (i.e.: https://da0dd48a7db7.ngrok.io/jira/support/slack/events)

You should now have the Marvin-Test Slack app connected to your local development.

Slack Bolt API

This plugin was developed using a FastAPI implementation of the Slack Bolt framework. The documentation is available on a thorough tutorial.

Note that our plugin uses asynchronous methods, which are available as part of the Bolt SDK.

Example apps are available on the Bolt Github repository.

Plugin Features

This plugin uses two integration points for Slack: the Slack Events API, and the Message Shortcuts integration.

Slack Events

The Bolt API listens on the /slack/events/ endpoint, and redirects all traffic through this endpoint. On Slack, we can however configure certain Slack Events to trigger specific functionality. For more information, visit the Slack documentation on Events.

For this example app we listen for the @mention of the bot and respond with a simple message.

Message Shortcuts

Slack provides two different shortcuts: a Global shortcut menu, and a Message shortcut menu. For the Jira Support Issue plugin, the idea was to use the message contents to generate some of the contents of the Jira issue automatically, so that the user can have a pre-populated form and quickly submit the data to Jira. It therefore made more sense to use the Message Shortcut.

A modal is opened using the list of users that is used for populating the drop-down menu, for authorization checking first (the user opening the modal should be on the list of users on the sheet). This list of users is created using a Google Sheet as external data source (see below section). The list of projects in which the is also populated from this spreadsheet.

Google Sheets

The Google Sheets API provides a rudimentary data source for management of the list of users and projects that can be assigned and populated with Jira tickets, respectively. The API Key and Sheet ID are both stored as environment variables and called in the handler.

For the Marvin Slack app you can request permission to acess the spreadsheet here.

Plugin implementation

The plugin basically follows the architecture of the SKA CICD framework, but since the Bolt API is also a framework in itself, it is easy to get confused. The plugin has the normal routers and models directories. All requests are handled by the endpoints declared under routers/jira_support_ticket. The asynchronous call to the SlackAppHandler is awaited, and the internal authentication with Slack is handled by the Bolt API.

Important to note is Slack’s requirement to get a response from the Web service within three seconds. This is accomplished by the ack() calls found in all the methods in /models/slack_handler.py.

The APIs created to integration with Jira etc are imported and used as with all other plugins.