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ł.