Ostatnio zainteresowałem się tematem w jaki sposób można stworzyć aplikację wykorzystującą popularny wśród programistów komunikator Slack. Zacząłem drążyć temat aż natknąłem się na framework o nazwie Bolt. Dzięki niemu jesteśmy w stanie naprawdę szybko stworzyć taką aplikację i to właśnie to chciałbym zaprezentować w tym artykule. Spróbujemy krok po kroku przejść przez taki proces korzystając przy tym z systemu Windows.

Aplikacja witająca użytkownika

Naszym celem będzie napisanie programu, który przekaże nam w komunikatorze wiadomość z naszym imieniem o ile zostanie ono podane. W innym przypadku poprosi nas o podanie imienia jako argumentu. Należy zacząć od utworzenia projektu, w moim przypadku będzie to projekt oparty o Maven. W pliku pom.xml musimy dodać niezbędne zależności.

    ...

    <dependencies>
        <dependency>
            <groupId>com.slack.api</groupId>
            <artifactId>bolt</artifactId>
            <version>1.12.1</version>
        </dependency>
        <dependency>
            <groupId>com.slack.api</groupId>
            <artifactId>bolt-servlet</artifactId>
            <version>1.12.1</version>
        </dependency>
        <dependency>
            <groupId>com.slack.api</groupId>
            <artifactId>bolt-jetty</artifactId>
            <version>1.12.1</version>
        </dependency>
    </dependencies>
</project>

bolt oraz bolt servlet są niezbędne do działania naszej aplikacji. Natomiast jeżeli nie będziemy korzystali z żadnego innego webowego frameworka jak np. Spring Boot należy dodać jeszcze bolt-jetty. Dzięki niemu nasz program zostanie uruchomiony na serwerze HTTP o nazwie Jetty.

Teraz musimy napisać kawałek kodu, w którym utworzymy komendę wykorzystywaną w Slacku. Z tego powodu inicjalizujemy zmienną typu App i wywołujemy na niej metodę command przekazując nazwę komendy oraz jej obsługę w postaci lambdy. Następnie tworzymy obiekt SlackAppServer, aby uruchomić serwer HTTP.

package pl.devcezz;

import com.slack.api.bolt.App;
import com.slack.api.bolt.jetty.SlackAppServer;

public class MyApp {

    public static void main(String[] args) throws Exception {
        var app = new App();

        app.command("/hello", (req, ctx) -> {
            String text = req.getPayload().getText();
            if (text != null && !text.isEmpty()) {
                return ctx.ack(
                    ":tada: Yeah! Nice to meet you, " + text + "! :tada:"
                );
            } else {
                return ctx.ack("Please type your name. :sob:");
            }
        });

        var server = new SlackAppServer(app);
        server.start();
    }
}

Zabawa z ustawieniami

Skoro napisaliśmy kod naszej aplikacji teraz musimy ją jakoś uruchomić. Zanim to zrobimy należy ustawić wartości dla dwóch zmiennych środowiskowych: SLACK_SIGNING_SECRET oraz SLACK_BOT_TOKEN. Pierwszą z nich otrzymamy tworząc testowy workspace i rejestrując w nim aplikację. Logujemy się, więc do Slacka na stronie slack.com (użyłem do tego Google Auth) i klikamy 'Create Another Workspace’. Jeżeli mamy zainstalowaną aplikację desktopową Slacka na Windowsie możemy przejść przez ten proces właśnie w niej lub wykorzystać do tego przeglądarkę.

• 

• 

Teraz możemy przejść do konfiguracji naszej aplikacji. Wchodzimy, więc na api.slack.com/apps, wybieramy przycisk 'Create an App’, a następnie opcję 'From scratch’. Podajemy nazwę aplikacji i wybieramy dla jakiego workspace ma ona zostać stworzona.

• 

Przewijamy w dół do sekcji 'App Credentials’. W niej znajdujemy niezbędny dla nas token o nazwie 'Signing Secret’, wystarczy go sobie wyświetlić i skopiować.

• 

SLACK_BOT_TOKEN otrzymujemy natomiast wybierając na tej samej stronie co przed chwilą zakładkę 'Install App’. Dostajemy informację, że musimy dodać chociaż jedno uprawnienie, aby zainstalować aplikację. Klikamy, więc w link ukryty pod słowami 'permission scope’ i przechodzimy do sekcji 'Scopes’. Tutaj dla 'Bot Token Scopes’ dodajemy uprawnienie 'chat:write’ i wracamy jeszcze raz do zakładki 'Install App’. Teraz jesteśmy w stanie wybrać 'Install to Workspace’. Na następnym ekranie zostaniemy poproszeni o nadanie uprawnień naszej aplikacji do stworzonego workspace. Potwierdzamy dzięki czemu uzyskamy token 'Bot User OAuth Token’, który będzie wartością dla zmiennej środowiskowej SLACK_BOT_TOKEN .

• 

• 

• 

Pora na uruchomienie aplikacji

Skoro nasza aplikacja korzysta z Maven to wykorzystajmy to. Otwórzmy konsolę i będąc w głównym katalogu naszej aplikacji Javowej wywołajmy następujące polecenia.

export SLACK_SIGNING_SECRET="$(slack signing secret)"
export SLACK_BOT_TOKEN="$(slack bot token)"

mvn compile exec:java -Dexec.mainClass="pl.devcezz.MyApp"

Dwa pierwsze wiersze ustawią nam niezbędne zmienne środowiskowe, które opisałem wcześniej. Następnie skompilujemy nasz kod wykorzystując Maven i uruchomimy naszą aplikację wskazując, gdzie znajduje się główna klasa. Po zaciągnięciu odpowiednich bibliotek aplikacja powinna uruchomić się prawidłowo.

• 

Zalecane jest jeszcze, aby skorzystać z projektu ngrok. Dzięki niemu udało mi się wyłapać błąd 401 okazujący się mało intuicyjnym komunikatem ’/hello failed with the error „dispatch_failed”’. W przypadku Windows musimy utworzyć konto na ngrok, ściągnąć wymagany zip, rozpakować go, wejść do utworzonego katalogu i w nim otworzyć konsolę. Następnie podajemy dwie komendy.

./ngrok authtoken $(ngrok token)
./ngrok http 3000

• 

• 

Wybraliśmy port 3000, ponieważ jest to domyślny port dla serwera Jetty. Przechodząc na stronę dashboard.ngrok.com/endpoints/status dostajemy adres URL, pod którym mapowany jest 'localhost:3000′. Musimy go skopiować, aby jeszcze skonfigurować komendę obsługującą naszą aplikację. Należy zaznaczyć, że przy każdym uruchomieniu komendy ./ngrok http 3000 będziemy uzyskiwać nowe adresy URL. Ma to znaczenia dla ostatniego kroku.

• 

Ustawienie komendy w Slack

Wracamy do ustawień aplikacji na stronie Slacka. Przechodzimy tym razem do zakładki 'Slash Commands’ i wybieramy przycisk 'Create New Command’. Konieczne jest podanie nazwy komendy, którą użyjemy w Slack, URL do obsługi żądania oraz opis. UWAGA! Przy podawaniu URL kopiujemy adres uzyskany z aplikacji ngrok i dodajemy jeszcze do niego '/slack/events’ na końcu.

• 

• 

Na koniec wchodzimy do zakładki 'Install App’, wybieramy 'Reinstall to Workspace’ i potwierdzamy. Warto tutaj podkreślić, że za każdym wywołaniem komendy ./ngrok http 3000 generowany jest nowy adres URL, który musimy podmienić w skonfigurowanej przed chwilą komendzie.

Jeżeli wszystko zadziała zgodnie z planem to przechodząc do Slacka i wpisując polecenie /hello powinniśmy dostać komunikat 'Please type your name. ’. Jeżeli natomiast podany '/hello DevCezz’ otrzymamy ’ Yeah! Nice to meet you, DevCezz! ’.

• 

W przypadku, gdy coś pójdzie nie tak możemy skorzystać dobrodziejstw ngrok. Przechodzimy pod adres http://localhost:4040/inspect/http w przeglądarce i możemy sprawdzić jakie odpowiedzi otrzymaliśmy od serwera Slacka. W moim przypadku, jak wspomniałem wcześniej, otrzymywałem błąd 401, ponieważ zapomniałem ustawić zmiennych środowiskowych wykorzystując polecenie export.

• 

Podsumowanie

Uważam, że ta zabawa ma potencjał. Dzięki niej możemy stworzyć aplikację służącą do powiadamiania nas o jakiś wydarzeniach wykorzystując inny kanał wiadomości jakim jest popularny Slack. Istnieje również możliwość zamiany serwera Jetty na Spring Boot. Zachęcam do przestudiowania przykładu znajdującego się pod adresem slack.dev/java-slack-sdk/guides/getting-started-with-bolt, a dokładniej pod nagłówkiem ’OK, What about Spring Boot?’. Możemy również wykorzystać API Slacka to stworzenia klienta zamiast aplikacji jak w tym wpisie, jednak to być może zostawię sobie na inny artykuł.