| expertisefinder-redirect |
|---|
...
|
...
|
...
|
...
|
Thank you for visiting our old product documentation site. Note that we
...
no longer store or update our documentation here.
...
Please navigate to our new documentation site and update your bookmarks accordingly. If you're looking for the former content
...
| 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.
...
of
...
this
...
To create and prepare a Slack app for use with Email This Issue, follow this guide:
...
page,
...
click
...
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.
...
...
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):
...
| language | bash |
|---|
...