README.md

Ballerina Slack Connector

Slack is a channel-based messaging platform. With Slack, people can work together more effectively, connect all their software tools and services, and find the information they need to do their best work — all within a secure, enterprise-grade environment.

This connector allows you to access the Slack Web API and Slack Events API through Ballerina. It provides the capability to query information from and perform some actions in a Slack workspace.

For more information, go to the modules.

• slack

Overview

Slack is a collaboration platform for teams, offering real-time messaging, file sharing, and integrations with various tools. It helps streamline communication and enhance productivity through organized channels and direct messaging.

Setup guide

Step 1: Sign in to Slack

1. To use the Slack Connector you need to be signed in to Slack. If you haven't created an account already, you can create it here.

   

Step 2: Create a new Slack application

1. Navigate to your apps in Slack API and create a new Slack app.

   

2. Provide an app name and choose a workspace of your choice.

   

3. Click on the "Create App" button.

Step 3: Add scopes to the token

1. Once the application is created, go to the "Add Features and Functionality" section and click on "Permissions" to set the token scopes.

   

2. In the User Token Scopes section set the following token scopes.

   

3. Install the application to workspace.

   

4. Copy the OAuth token that is generated upon installation.

   

Quickstart

To use the slack connector in your Ballerina application, modify the .bal file as follows:

Step 1: Import the module

Import the slack module.

import ballerinax/slack;

Step 2: Instantiate a new connector

Assign the OAuth token obtained to the variable token, and then initialize a new instance of the slack client by passing the token.

configurable string token = ?;

slack:Client slack = check new({
    auth: {
        token
    }
});

Step 3: Invoke the connector operation

Now, utilize the available connector operations.

Send a Text Message to General Channel

slack:ChatPostMessageResponse postMessageResponse = check slack->/chat\.postMessage.post({channel: "general", text: "hello"});

Step 4: Run the Ballerina application

bal run

Examples

The Slack connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:

1. Automated Summary Report - This use case demonstrates how the Slack API can be utilized to generate a summarized report of daily stand up chats in the general channel.

2. Survey Feedback Analysis - This use case demonstrates how the Slack API can be utilized to perform a company-wide survey by creating a dedicated channel to receive and track feedback replies.

Build from the source

Prerequisites

1. Download and install Java SE Development Kit (JDK) version 17. You can download it from either of the following sources:

   • Oracle JDK
   • OpenJDK

   Note: After installation, remember to set the JAVA_HOME environment variable to the directory where JDK was installed.

2. Download and install Ballerina Swan Lake.

3. Download and install Docker.

   Note: Ensure that the Docker daemon is running before executing any tests.

4. Export Github Personal access token with read package permissions as follows,

   export packageUser=<Username>
   export packagePAT=<Personal access token>

Build options

Execute the commands below to build from the source.

1. To build the package:

   ./gradlew clean build

2. To run the tests:

   ./gradlew clean test

3. To build the without the tests:

   ./gradlew clean build -x test

4. To run tests against different environment:

   ./gradlew clean test -Pgroups=<Comma separated groups/test cases>

5. To debug package with a remote debugger:

   ./gradlew clean build -Pdebug=<port>

6. To debug with the Ballerina language:

   ./gradlew clean build -PbalJavaDebug=<port>

7. Publish the generated artifacts to the local Ballerina Central repository:

   ./gradlew clean build -PpublishToLocalCentral=true

8. Publish the generated artifacts to the Ballerina Central repository:

   ./gradlew clean build -PpublishToCentral=true

Contributing to Ballerina

As an open source project, Ballerina welcomes contributions from the community.

For more information, go to the contribution guidelines.

Code of conduct

All contributors are encouraged to read the Ballerina Code of Conduct.

Useful links

• Discuss the code changes of the Ballerina project in [email protected].
• Chat live with us via our Discord server.
• Post all technical questions on Stack Overflow with the #ballerina tag.