| Table of Contents |
|---|
Preparations to use Slack for alerting
General information
In order to communicate with Slack in any way, an app must be created, which resides in its associated (development) workspace.
In this stage, the app is a "local", so called single-workspace app (for internal use only).
Later on, the app can be made public and distributed among several other workspaces upon need.
As opposed to single-workspace apps, distributed apps require OAuth 2.0 authorization flow implemented, because of access token generation for each workspace and user on the fly.
The distribuition process can be circumvented, if each and every workspace admin creates a dedicated local app to use with the Email This Issue app. In this guide, we’ll follow this path.
...
Next, we’ll show you, how to configure a Slack app for use with Email This Issue for Jira (this is always required). After that, we give you some tips to better understand the principles of the Slack Web API and Messaging, in order to construct more customized requests upon need.
Manual creation and configuration of a Slack app [required]
Since no programmatical authorization flow has been implemented so far, company Jira/JETI/Slack admins need to prepare Slack in order to integrate it manually with Email This Issue for Jira. In this case, a pre-configured “local” Slack app can be linked to the Email This Issue for Jira app by providing some important auth and config data on the alerting configuration page.
...
| Info |
|---|
To retrieve the channel ID easily, open the web UI of the selected Slack workspace (in a browser) and read out the ID of the respective channel from the URL (after clicking on the channel, of course). Alternatively, also the Slack web API can be used to get to the same result, e.g. by executing the request using cURL. |
Calling the Web API [supplementary]
There is a dedicated method chat.postMessage in the Web API to post messages into a channel (this is referred to as the Sevice URL above).
The body part is to be sent as an 'attachments' or 'blocks' argument (JSON array).
Permission scopes required
chat:write: to post messages into a channel (where the bot/user is member, has access to)
channels:read: to list info about public channels, as we shall explicitly provide the channel's ID (extracted from the response of conversations.list call)
groups:read: to list info about private channels, as we shall explicitly provide the channel's ID (extracted from the response of conversations.list call)
...
chat:write.public: shall only be added if the app should post messages to any public channels, without explicitly adding it (“inviting”) to the channel beforehand (or an equivalent act is to add the app to the workspace in general)
Troubleshooting
Typical authorization-related errors due to incorrect permissions or missing prerequisites:
...
Important to know, that if a permission scope was granted once, the administrator cannot revoke such a broader scope with simple re-installation of the app with more restricted scopes. To achieve this, the full app access shall be revoked and re-granted.
Messaging [supplementary]
If you are about to define a full-custom message template on your own (instead of relying on the built-in one), a good starting point can be to study the official documentation on messaging.
...
| Code Block | ||
|---|---|---|
| ||
curl -X POST -H 'Authorization: Bearer xoxb-AAAAAAAAAAAAA-BBBBBBBBBBBBB-CCCCCCCCCCCCCCCCCCCCCCCC' -H 'Content-type: application/json' \
--data '{"channel":"C01QZLFBK71","text":"This is a sample message from JETI."}' https://slack.com/api/chat.postMessage |
Preparations to use OpsGenie for alerting
First of all, you need to have a Cloud instance, where the OpsGenie app is activated.
...
| Note |
|---|
The geological location of your instance will also impact the URL of the OpsGenie API (see later): Please keep in mind that the Service URL in the auto-generated template has to be adjusted accordingly. |
Basic configuration [required]
The first step is to make Email This Issue for Jira able to authenticate with OpsGenie. To achieve this, you have to acquire an API key. This can be done in two ways:
...
| Warning |
|---|
There is a possibility of misconfiguration: when adding a new API key via the Settings / API key management option, the generated key could not be used for creating alerts. As a consequence, it is highly recommended to start the integration process from the Teams tab. |
...
Creating alerts with custom content [supplementary]
Although Email This Issue for Jira provides you with a general-purpose template to create alerts in OpsGenie, you may want to further customize the posted request. Some information can be found here on this topic.
...