Lessons Learned Building a Slack App for PubSub+ Event Portal
Slack has become the de facto standard messaging platform and workplace communication tool. Slack’s instant messaging and other communications capabilities, combined with add-ons that make it easy to integrate it with other workplace tools, make it a part of many enterprises’ IT stacks. Its ease of use and reliability stand out, and the fact that it’s a playful, fun tool means it has an adoption rate that’s incredible compared to any other tool in an enterprise.?
At Solace, we wanted to integrate with Slack a new version of our event portal, called PubSub+ Event Portal. PubSub+ Event Portal lets users create, catalog, reuse and manage event streams and event-driven applications throughout their lifecycle. Architects, developers, and data scientists use Event Portal to work on and access these resources associated with event-driven architecture, but with different needs and purposes.
Since Slack is such a widely-used tool for collaboration, it made sense to build a Slack app that integrates it with PubSub+ Event Portal to let users access and manage these assets without leaving Slack itself. This is the genesis of “why” we wanted to expose PubSub+ Event Portal capabilities via Slack. My goal with this post is to explain the “how” part of the journey in achieving that, sharing a few lessons I learned along the way.
With the recent release of version 2.0, PubSub+ Event Portal API tokens allow users to authenticate and authorize access to specific resources. Every user must have an API token granting them access to resources and permitted operations on those resources. As an extension, the desired Slack app would have to facilitate registration of such tokens for use when issuing API requests to PubSub+ Event Portal on behalf of the user.
Slack App Development Frameworks?
Slack offers a range of SDKs, frameworks, and construction tools to fast-track the development of applications. In addition, it has community-developed libraries to assist when using languages like C#, Go, .NET, and many others.
They even offer a foundational framework for Slack apps called Bolt that lets you build Slack apps in a flash in JavaScript, Python, and Java. Bolt handles much of the foundational setup so you can focus on your app's functionality. Out of the box, Bolt includes:
__________________________________________________________________
You can build the app from scratch using frameworks or use the SDKs to cut down on the boilerplate code. I chose Slack’s Bolt framework for JavaScript since I was familiar with it, and wanted to build the app quickly.
Requirements for our App
In planning out an app to integrate PubSub+ PubSub+ Event Portal with Slack, our requirements were straightforward:
1.????We needed each Slack user to be able to
2.????We wanted to give users a quick and easy way to retrieve objects from PubSub+ Event Portal
3.????We wanted to automatically unfurl PubSub+ Event Portal URLs to present a preview of the resources within Slack.
4.????We also wanted to make the tool more interactive by providing drilldown actions based on the output of a slash command or URL unfurl, such as:
The journey of building the Solace Slack app followed the steps listed below, with notes on observations and lessons learned in the process. This should not be treated as best practice, but as reference points for you to be aware of and hopefully make the right choices.
Developing the Solace Slack App
Assuming you have signed into your Slack account, a Slack app can be created by simply providing an app name and a development workspace. Note that the app is available only in the specified Slack workspace and is not yet distributed – meaning not available publicly. Distributing the app requires certain pre-steps, which we will discuss later.
?Slack offers many powerful features for you to choose from:?
Incoming Webhooks: Post messages from external sources into Slack.
Interactive Components: Add components like buttons and select menus to your app’s interface and create an interactive user experience
Slash Commands: Allow users to perform app actions by typing commands in Slack
Event Subscriptions: Make it easy for your app to respond to activity in Slack
Bots: Allow users to interact with your app through channels and conversations?
__________________________________________________________________________
As you can see, each of these features shapes up your Slack app’s interface and the types of interactions – choose and configure the desired features that are appropriate to your requirements.
Our primary goal was to expose PubSub+ Event Portal resources on Slack – query and present a visual representation of the PubSub+ Event Portal resource – so I chose the following features for my Slack app: Interactive Components, Slash Commands, and Event Subscriptions.
Interactive Components
A request URL is a public URL where Slack can send HTTP POST requests with information about events, interactions, and other happenings inside your Slack workspace.
When a message is posted, a button is clicked, a dialog is submitted, or a user interacts with your app?using another interactive feature, Slack will send relevant information about that event to this Request URL with details on the user who initiated the event, channel where the event occurred and other contextual information.
This should be a secured, public URL endpoint. The received request will be delivered to the app’s action and event listeners, which implement the necessary logic (such as querying PubSub+ Event Portal) and Slack blocks (a series of components that can be combined to create visually rich interactive messages).
__________________________________________________________________
In the initial stages of development, you may run the app on your local machine (laptop or desktop) like I did. No worries: I suggest you use the socket mode to get started, or use the ngrok tool to create a publicly accessible URL. You can find more information here. Then once the app is ready for distribution, update the request URL with the public URL where the app can be reached.
Slash Commands
Slash commands?allow users to invoke your app by typing a string into the message composer box. A submitted slash command will cause a payload of data to be sent from Slack to the associated app. The app can then respond using the context provided by that payload.
These commands are the entry points for complex workflows, integrations with external services, or even simple message responses. Slack has a list of in-built commands like?/topic?and?/remind (here's a list?of Slack slash commands).
__________________________________________________________________
Either you can create individual slash commands serving specific requirements or build a single slash command supporting an arguments scheme to specify the request context. In our case, we made a single slash command /solace with an argument scheme to set the context.
/solace [resource-type] [name: resource-name] [domain: domain-name] [sort: ASC|DESC] [shared: true|false]
Event Subscriptions
Slack follows the model of “don’t call us, we’ll call you.” By that I mean events generated from the activities on Slack are automatically delivered to a request URL. Typically, this would be the same URL you configured on interactive components, but it could be different if you want separation and scaling of processing.?
Slack’s events API makes it easy to build apps that respond to activities in Slack. All you need is a?Slack app?and a secure endpoint to send the events to.
__________________________________________________________________
The absence of correct subscriptions would make it appear as if your code is not working, and you may end up spending time troubleshooting, potentially a non-issue. Therefore, I suggest that before starting you familiarize yourself with the list of event types supported by Slack and identify the ones that your app would be interested in implementing the functionality.
Bot Events
Apps can subscribe to receive events the bot user has access to (like new messages in a channel). Adding events to this list will automatically update the necessary?OAuth scope for the app.
__________________________________________________________________
I realized that subscriptions without appropriate OAuth permission would result in errors on the event and action listeners, so I suggest you review the permissions list to make sure yours match the permissions required by the subscribed events.
Events on Behalf of Users
You might also be interested in events-related users who have authorized the app and the conversations they are part of. Mostly this would be around when a user sent a message to the Slack app or posted a direct message in a channel. Slack will automatically update the necessary?OAuth scope for the app.
__________________________________________________________________
Any subscription without appropriate OAuth permission would result in errors on the event and action listeners. Review the permissions list to ensure that they match the permissions required by the subscribed events.
App Unfurl Domains
Slack URL unfurl action involves identifying URLs (specifically, URL domains of interest) and posting link_shared event to the app.
领英推荐
Note that the app will receive events for any subdomain or path of the selected domains or hosts. Ports are ignored, so requests on any port will trigger an event. Using IP addresses is not allowed.?
For the Solace Slack app, a domain name solace.cloud would cover the need as it can capture standard PubSub+ Event Portal URLs (console.solace.cloud) and other custom PubSub+ Event Portal URLs (customer-name.solace.cloud).
__________________________________________________________________
Be aware of the limitation on the number of domains supported by Slack. Ensure that you specify the URLs of interest correctly in the app configuration and subscribe to the link_shared event.
Bots
Allow users to interact with the app through channels and conversations.
The home tab serves the purpose of providing documentation/intro to the app as well as any configuration requirements related to the app as a pre-requisite.?
For the Solace Slack app, we needed to acquire the PubSub+ Event Portal REST API token and PubSub+ Event Portal domain before the app was enabled for the user. The home tab is built with a dialog to facilitate capturing and posting these critical details to the app.
Redirect URLs
OAuth lets a user install the app in any Slack workspace. At the end of the OAuth flow, the app gains an access token necessary to invoke Slack APIs, receive events, and access other features.
?Familiarize yourself with the OAuth flow and implement it, without which the application cannot be distributed. Refer to reference implementation for guidance.
Scopes & Tokens
The following Slack parameters are required on the app to create a Bolt app and connect to Slack APIs. Please note these parameters from the app configuration and store them in a .env file that the app will load on startup.
You must capture these values and pass them as part of the app constructor in the Bolt code.
__________________________________________________________________
Any unauthorized access or leak would make your app vulnerable; store it securely. In the app, do not expose them in the code or documentation – use environment variables to supply these values to the application at runtime or using other appropriate facilities.
Maintaining Application State (if required)
As mentioned earlier, a slack user must register a valid EP REST API token, and the app needs to pass along this token on every request. It must be stored and looked up for the user at run time while responding to Slack commands and interactions. Similarly, the OAuth also requires the tokens to be stored to authenticate users.
__________________________________________________________________
For prototyping purposes, a simple file-based database is sufficient. Choose an appropriate database with consideration for the number of users, usage, and performance requirements.
Slack Layout Blocks
Blocks are a series of components that can be combined to create visually rich and compellingly interactive messages. A response to Slack from the Slack app is in the form of blocks decorated in a nice layout. Slack restricts supporting up to 50 blocks in each message and 100 blocks in modals and home tabs.
If you ever need more blocks, you will have to chunk them into multiple messages and post them to slack. If designed correctly, you can align this with the pagination scope of your backend logic. Be cautioned not to split a logical message context into multiple blocks, which may make it unfriendly aesthetically.
Solace Slack app’s responses were built from PubSub+ Event Portal API responses, typically a series of objects. Designed the layout and block construction scheme aligned with the API pagination facility and provided buttons for navigation. It worked out well for us.
__________________________________________________________________
A great starting point would be Building with Block Kit and sample templates for a quick start.
Ephemeral Messages
Slack API supports posting messages that are visible to all in the channel or only to the user who posted the message. A regular posting of a message is straightforward and a chat.postMessage API would do the job. However, an ephemeral message would require an invocation of respond callback with explicit mention of response_type as ephemeral or the chat.postEphemeral API.
Analyze and identify the cases that require ephemeral versus regular message responses so that you can get them coded correctly during development.
App Manifest
Slack offers a manifest system to create, configure and copy your Slack apps easily. Manifests are YAML-formatted configurations bundles that can be used to make changes to app configuration on a simple text/YAML editor and update the deployed app.
__________________________________________________________________
Make use of this feature to back up your app configuration periodically. It will also come in handy to make changes quickly without going to the UI.
Deploying the Solace Slack App
Local Deployment without Distribution
On localhost, you could complete the app development and testing with the Sockets Mode facility. However, this would not allow external users to install/access the app, as you cannot distribute the app. This would get a demo app for you; that’s about it.
Plan and prepare for deployment options involving hosting, secured endpoints, domain names (as necessary), etc., ahead of time.
Local Deployment with Distribution
Using ngrok, turn off the socket mode and update the Request URL of Interactivity, Event Subscriptions, and Slash Command settings with the ngrok-provided secured URL. Though the app will be running on your local machine, users can now install and access the App via the ngrok-provided URL.
This will help you to distribute the app for users in your workspace – but the performance will be sub-optimal because of the network roundtrips.
Cloud Deployment with Distribution
The Slack app must be hosted on an appropriate hosting service for distribution. Here, you can find the services often used to host Slack integration and apps.
Each provider offers different options and prerequisites; review them and choose the one that is appropriate for your requirements.
Our final deployment setup is as follows.
Check out the GitHub source of the Solace Slack app for implementation.
Refer to the user and installation guide to gain more insights on implementation. Also, check out the quick intro video of the Slack app for PubSub+ Event Portal.
Conclusion
Building great user experiences on Slack requires a good understanding of your audience and use cases. Based on that, formulate message guidelines and user interactions. If there is any external dependency or application integration, create a good onboarding experience factoring in the dependent requirements. The good news is that Slack app development can be an iterative process, and the process of app deployment and testing is the friendliest you would ever encounter. Always keep in mind the aspects of data and communication security to conform to your organization's policies, compliance requirements, and user expectations.
Other posts you might be interested in: