Slack Connection

In this page we go through the process of creating a Resources Slack connection.

Create Slack App

First, you will need to navigate to Slack api to create an app with a name and a Slack domain. Here we walk through creating a simple slack app which allows a bot to post a message to a user.

Tip: We suggest setting up your Slack app on a development workspace first.

Navigate to Slack's Your Apps page and click Create an App.
Enter an App Name, for example, ScriptRunner Integration.
Choose your Development Slack Workspace.
You'll need to either sign in to your workspace or create a new workspace to add it as your development workspace.
Navigate to OAuth & Permissions and click Add an OAuth Scope under Bot Token Scopes.
These scopes tell your app the permissions that it has access to, such as sending messages or viewing rooms.
For example, add the im:write scope if you want your Slack bot to post a message to a user. You can edit this later to add extra permissions, such as chat:write and chat:write:public to post to a channel.
Once you have added at least one scope, navigate to App Home.
Click Edit to change the Display Name and Default username for your bot (the app uses the bot user to post in the workspace).
The Display Name is the name that will be displayed on Slack when a message is sent.
Click Save.
Navigate back to the OAuth and Permissions tab and click Install to Workspace to install the app.
The Bot Oauth Access Token now displays at the top of the OAuth & Permissions page.
This is the token the feature needs to send messages, click the Copy button.

Set up the Slack Resource

Navigate to ScriptRunner → Resources → Add New Item → Slack Connection.
Provide a name for the connection in Connection Name. For example, slack or if you use multiple workspaces use the workspace name.
Enter the Bot OAuth Token for your Slack workspace in Token.
Tip: For help getting your Bot OAuth Token see Create a Slack App above.
Note: The token provided can be viewed by administrators.
Click Preview to validate the connection using the token provided.
Click Add. Your Slack connection is now configured.
To test the connection, navigate to ScriptRunner → Script Console.
Use the simple script below to test that the bot can post to a user and/or a channel.
CAUTION: We recommend you test your slack connection using your own user details, or set up a test slack room.
When sending a message to a Slack channel the scope chat:write is required… for a public channel chat:write_public is required. To send a direct message the scope users:read.email is required.
1
2
3
4
5
6
7
import com.onresolve.scriptrunner.slack.SlackUtil SlackUtil.message( "slack", // Identifier you provided when creating the resource "acme-developers", // channel name or ID, or user email "Hi, this is the message text" // Message text )
Tip: Accepted values for the channel argument (the second argument) are public or private channel name (or ID), or a user's email address, or ID, to send a direct message.
The full list of allowed parameters that can be used to format your Slack messages can be found here.
Note: Remember that a Slack bot requires certain scopes to message a user and/or channel. If these test scripts fail, check the Bot Token Scopes under OAuth&Permissions for your Slack app.
- chat:write: send messages to channels
- chat:write.public: send messages to channels the bot user isn't a member of.
- files:write: upload files
- users:read and users:read.email: send direct messages to a user
- chat:write.customize: send messages as bot user with a customized username and avatar

Slack Examples

Having set up your Slack connection, you can now use it in your ScriptRunner scripts using the resource Connection Name.

Using Blocks and Attachments

The following example sends a message using blocks and attachments. In this case the message text provided is used as a fallback option.

import com.onresolve.scriptrunner.slack.SlackUtil

SlackUtil.message("slack",
    "acme-developers",
    "This is the fallback message text",
    [
        username   : "ScriptRunner Bot",
        blocks     : [
            [
                type: 'section',
                text: [
                    type: 'plain_text',
                    text: 'Message text'
                ]
            ]
        ],
        attachments: [
            [
                pretext: 'Introductory text',
                text   : 'Text message as part of attachment'
            ],
        ]
    ]
)

Tip: Use the block kit builder to preview your messages.

Uploading a File

Upload file to a Slack channel. Scope files:write is required. You can either upload a file to a channel (if the bot user is part of this channel) or to a specific user:

import com.onresolve.scriptrunner.slack.SlackUtil

SlackUtil.upload("slack",
    "acme-developers",
    new File("/tmp/file.txt"),
    [
        text           : 'Fallback text',
        initial_comment: 'Comment about the file being uploaded',
    ]
)

Note: To send an attachment the app must be added to the channel, which you can do by clicking the Add apps link from the channel details, then the More menu.

Tip: The full list of allowed parameters can be found here.

In a Post Function

As another example, you can add the following to a post function to send a message to the project manager with the issue priority and summary after it is created.

import com.onresolve.scriptrunner.slack.SlackUtil

SlackUtil.message("slack",
 "acme-developers",
 "${issue.priority.name} priority issue created: *${issue.summary}*"
)