| 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.
Now, let's call the local (or distributed) Slack app JETI notification assistant.
For authentication and authorization, Slack employs app tokens (sort of app keys), which are long-lived bearer tokens associated with registered apps (and bound to a single workspace, where the app is installed => for each and every app installation in new workspaces, a different access token is generated for that particular workspace).
Apps do not require to obtain temporary access tokens with the help of a refresh token, but they can use their permanent app token until it'll be revoked.
Access token expires only:
if a workspace owner fully uninstalls the app
if users individually remove their configurations
if the account of the user who initially authenticated the Slack app is deactivated
App tokens can be retrieved either by manually installing the app in a workspace (via the Slack App Management UI => https://api.slack.com/apps/{app-id}/general, this can be used to access client id and client secret) or programmatically, as a result of an automated OAuth authorization flow ("OAuth dance").
Slack defines different types of tokens and access modes, respectively. We'll need the bot token type, as JETI notification assistant acts as a bot user (kind of technical account, i.e. it does not act in the name of a real user, but it has its own identity). In this case, the access token is called Bot User OAuth Token.
To achieve the desired funtionality - i.e. to post messages to a particular Slack channel - we have basically two possible solutions: either do it via Web API (a REST-like interface with lots of available methods) or via webhooks (a dedicated endpoint to communicate something specific). The alerting feature in Email This Issue for Jira is built on top of the more sophisticated Web API.
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.
To create and prepare a Slack app for use with Email This Issue, follow this guide:
As an organizational Slack admin, visit the Slack app management/config page, then click on the Create New App button.
Create a Slack app (the new, not the classic one) in a specific workspace (aka "team"). Pick an appropriate name (e.g. “JETI notification assistant”) and select the workspace of your organization.
Create a bot user (i.e. the respective access token) for your app with appropriate permission scopes, configured for Web API usage.
Install app into the associated workspace, complete authorization.
Obtain the bot user access token (copy it from the app config page: https://api.slack.com/apps/{app-id}/install-on-team)
Use the credentials from step 4 to configure a Slack connection in JETI (if you are not the Jira / Email This Issue admin of your organization, then cosult with her): provide both the access token and the target channel name
The following screenshots were taken to help in the orientation on the Slack app management/config page, while following the steps above.
Arriving at the app creation screen:
...
Add OAuth permission scopes on the OAuth & Permissions screen:
...
The installation/re-installation of the app (including the subsequent authorization flow) can be initiated from the Install App screen:
...
After having a working Slack app in place, the app needs to be added to the target channel (via invitation or by mentioning the app in the conversation within the given channel), let it be a private or public channel.
Normally, only the channel name is displayed on the Slack UI, regardless whether it is a native app or the web client. However, the administrator need to provide the channel ID in place of the channel name on the webhook configuration form (the reason behind it is that a channel name can be changed, while the channel ID is constant in time (invariant), therefore renaming the channel in the background won’t affect the operation of previously configured webhooks).
| 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)
Optional:
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:
"not_in_channel": if the app was neither added to the target channel beforehand, nor chat:write.public scope was granted (if the target channel is a public channel)
"channel_not_found": in case a private channel is the target channel and the app was not previously added as a member
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.
What’s important to know is that messages are sent as a JSON body. As a conseqence, the Content-type header must be set to application/json, furthermore the Authorization header shall be set, too.
How the messaage payload is constructed, depends on the chosen formatting and how we want to enrich the posted message (either the content or the appearance of it). There are different levels of formatting and associated techniques to construct simple or more richer messages. More info on this topic can be found here.
To compose custom content:
the old way (using predefind fields and optionally attachments): Message Builder
the new way (using blocks and optionally attachments) - this is the preferred one: Block Kit Builder
Headers:
Content-type: application/json (automatically added)
HTTP Authorization header {Bot-User-OAuth-Token}
Message payload (JSON body):
Limitations: text fields: max. 4000 chars, full message: max. 40000 chars (in blocks: 2000 chars)
Relevant reading on formatting:
For long sections or not that important details in the message, the auto expand/collapse fuctionality can be used, too.
There is an auto expand/collapse mode in Slack, but applies only to one specific type of content, which is text attachments, but not but not to any kind of block elements. Rule sctivation condition: 700+ chars or 5+ lines of text
Without using (the half deprecated) attachments, there is currently no way to hide possible long (and disturbing) parts of a message, except for defining a button with an absolute link or using file attachments.
A simple example (posting a short plain text):
| 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.
To achieve this on an already existing Atlassian site, you can create a Jira Service Management project, then create a team and add OpsGenie integration. For example, if your site URL is https://{your-atlassian-site}.atlassian.net, then the OpsGenie app will be accessible via the following link: https://{your-atlassian-.site}.app.opsgenie.com/alert/list
The alternative option is to register a new OpsGenie account in an independent way (not starting from a Jira project). In this case, a new Atlassian Cloud site will be automatically set up for you (of course, without Jira integration in place).
At this stage, we have some complications. If you opted for data storage in the EU, then the URL of your OpsGenie will contain an extra “.eu” segment, like https://{your-atlassian-.site}.app.eu.opsgenie.com/alert/list
| 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:
By using the default integration configuration:
In Settings / Configured Integrations select the Default API entry:
...
Create a new integration configuration:
In Settings / Integration List select the API option:
...
| Note |
|---|
For Free and Essentials plans, the integrations can only be added from the Team Dashboards, as seen in the image below. |
...
API Integration documentation: https://docs.opsgenie.com/docs/api-integration
| 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.
Headers:
Content-type: application/json (automatically added)
Authorization: GenieKey <api key>
Message payload (JSON body):
The request body may be enriched with the following fields that will be parsed by OpsGenie, while creating the alert based on the incoming request:
...
Field
...
Mandatory
...
Description
...
Limit
...
message
...
| Status | ||||
|---|---|---|---|---|
|
...
Message of the alert
...
130 characters
...
alias
...
| Status | ||||
|---|---|---|---|---|
|
...
This field is used for alert de-duplication. When there is an open alert with the same alias, no new alert is created, only a counter will be incremented. After closing this alert, and there is a new alert with the same alias sent in, a new alert will be created.
...
512 characters
...
description
...
| Status | ||||
|---|---|---|---|---|
|
...
Description field of the alert that is generally used to provide detailed information about the alert.
...
15 000 characters
...
tags
...
| Status | ||||
|---|---|---|---|---|
|
...
Tags of the alert.
...
20 x 50 characters
...
details
...
| Status | ||||
|---|---|---|---|---|
|
...
Map of key-value pairs to use as custom properties of the alert.
...
8 000 characters total
...
entity
...
| Status | ||||
|---|---|---|---|---|
|
...
Entity field of the alert that is generally used to specify, to which domain the alert is related.
...
512 characters
...
priority
...
| Status | ||||
|---|---|---|---|---|
|
...
Priority level of the alert. Possible values are P1, P2, P3, P4 and P5. Default value is P3.
...
| Expertisefinder redirect | ||||||||
|---|---|---|---|---|---|---|---|---|
|