Before looking into this project, we recommend you look into FOYER (currently in pilot for ISVs). Be sure to check back Salesforce developer blog regularly for announcements on future milestones of FOYER. If you want to become part of the pilot, contact your technical account manager.
If you decide to build a custom Slack App integrated with Salesforce from scratch, this project can help you get started.
This project assumes you want to use a single Salesforce user (Integration user) for performing all data operations in Salesforce from Slack.
If your project requirements is to map a Salesforce user to a Slack user and run Slack App in the Salesforce user context, check out salesforce-slack-starter-kit
Multiple salesforce org connections to a single Slack workspace are not supported. Note that FOYER will support this feature.
This project helps you to create an opinionated minimum scaffold for building a Slack Apps that integrates Salesforce data using Bolt SDK (Node.js version) and jsforce.
The scaffolded app follows the monorepo approach. It contains a Slack App implemented using Bolt SDK (Node.js) and it also setups the needed Salesforce data and metadata for managing users and authentication. The scaffold provides configuration files to host and run the app on Heroku.
Most of Salesforce and Heroku setup tasks are automated to cut down a number of manual configurations required to set up development environments.
We also configure environment variables required for local development, debugging, and testing.
The image below shows the systems involved in the application.
Heroku acts as middleware and hosts the Node.js app that connects to Slack APIs (through Bolt) and Salesforce APIs (through jsforce). You can watch this short video to get familar with the app system architecture.
The needed configuration for connecting to Slack and Salesforce is securely managed through Heroku environment variables.
The scaffolded app uses jsforce and the OAuth 2.0 JWT Bearer Flow for Server-to-Server Integration flow to connect to Salesforce. This flow allows Slack to authorize Salesforce servers to access data without interactively logging in each time the Salesforce and Slack exchange information.
We do not store any data on Heroku app. The Heroku app is designed to be stateless.
The Heroku App connects to Slack using Bolt.js.
To be able to run this project you will need:
git
(download here)node
>= 14 (download here)- Salesforce Dev Hub
- If you don't have one, sign up for a Developer Edition org and then follow the instructions to enable Dev Hub.
sfdx
CLI >= sfdx-cli/7.129.0 (download here)- Heroku account (signup)
heroku
CLI (download here)
- Open https://api.slack.com/apps/new and choose "From an app manifest"
- Choose the workspace you want to install the application to
- Copy the contents of manifest.yml into the text box that says
*Paste your manifest code here*
and click Next - Review the configuration and click Create
- Now click Install App on the left menu. Then click the Install to Workspace button and then click on Allow
The scripts/deploy.js
script scaffolds all the entities needed for the sample app to work. These are the steps followed:
The script creates a Salesforce scratch org using the provided dev hub. The script also deploys the source code and the associated metadata (an object to store authorized user's tokens) to Salesforce. This is the object that helps handle user mappings and authentication. Finally, it assigns a permission set to the user, and saves the user login details in Heroku environment variables. This will be the integration user used in the JWT Bearer flow.
We generate a private key and digital certificate to set up the JWT Bearer flow for authentication.
The JWT Bearer flow need a connected app to be deployed to Salesforce. In the case of JWT bearer flow, a consumer key and a digital certificate is needed. All these configuration values are setup in the connected app, that we deploy to Salesforce.
Finally, we create a Heroku app, setup all the needed configuration variables and deploy the Bolt Node.js app.
We also write the configuration variables to a .env file for local development
To run the scaffolding script follow these instructions:
$ sfdx auth:web:login -d -a DevHub # Authenticate using your Dev Hub org credentials (only needed if using JWT bearer flow)
$ heroku login # Login with your Heroku account (or create one)
$ git clone https://github.com/developerforce/salesforce-slack-starter-kit
$ cd salesforce-slack-starter-kit/scripts
$ npm install
$ cd ..
$ node scripts/deploy.js
-
During the set up process, the script will prompt you to enter value for
SLACK_BOT_TOKEN
. To enter this value open your apps configuration page from this list, click OAuth & Permissions in the left hand menu, then copy the value in Bot User OAuth Token and paste into terminal. -
The script will prompt you for slack signing secret
SLACK_SIGNING_SECRET
. To enter this value open your apps configuration page from this list, click Basic Information and scroll to the section App Credentials and click show button and copy the Signing Secret and paste into terminal.
This is the last step, you will need to enter the current Heroku Instance url in Slack App.
- To enter this value open your apps configuration page from this list, click App Manifest. Find the
request_url
fields in the manifest and modify it to replaceheroku-app
with your actual heroku domain name. Note at the end of this step your url should look likehttps://<heroku-domain>.herokuapp.com/slack/events
├── force-app # Folder that holds Salesforce metadata types
├── scripts
| ├── deploy # Scripts to automate scratch org creation, heroku
| | #environment
│ ├── deploy.js # Automated Deploy script launch file
│ └── templates # Template for Connected apps setup
├── apps
├── slack-salesforce-starter-app # Node.js Slack app
├── config # Configs for Slack app
|── listeners # Modules to listen event for actions,
| # shotcuts and view events in Slack
|── middleware # Middleware for Salesforce
| # Authentication using OAuth 2.0 Web based flow
|── routes # Route for OAuth callback
|
├── app.js # Main file for Slack app launch
├── user-interface # User Interface folder for Home page
| # Modals and Messages in Block Kit format
|
├── salesforcelib # Folder for Salesforce related code
├── connect.js # Module to establish Salesforce connection
├── manifest.YAML # Slack app manifest file
├── Procfile # Heroku Procfile for deployment
-
For Salesforce metadata synchronization use
sfdx force:source:pull
to retrieve andsfdx force:source:push
to deploy metadata from orgs to local project folderforce-app
-
For the Bolt Node.js app use the steps below:
- cd into apps/slack-salesforce-starter-ap folder
cd apps/slack-salesforce-starter-app
- add git remote to app repo using
heroku git:remote -a <heroku app name>
- run
git push heroku main
to push code to Heroku
- cd into apps/slack-salesforce-starter-ap folder
- For local Development, first make sure to deploy the app on Heroku as listed in the section above.
- Next perform the steps below:
- Navigate to config file, and enable socket mode by uncommenting the socketMode and appToken in config file.
const slack = { ...... port: process.env.PORT || 3000, socketMode: true, appToken: process.env.SLACK_APP_TOKEN };
- Generate an App Level Token in the Slack App by navigating to your Slack app at api.slack.com and scrolling to the section App-Level Tokens
- Populate the .env file with
SLACK_APP_TOKEN
variable obtained in previous step - cd into apps/slack-salesforce-starter-ap folder
cd apps/slack-salesforce-starter-app
- Run
npm install
- Run
node app.js
At this point you should see the Node.js app recieving events from Slack directly in VSCode terminal.
- Run the Global Shortcut command
Whoami
that ships with the app as shown in the below screenshot
- Successful connection output is similar to screenshot below
Note: the command can fail the first time you execute it if you are using Free Tier of heroku app as dynos sleep if left ideal. Restart the app to resume.
-
For a production application change the
SF_LOGIN_URL
from 'https://test.salesforce.com' tohttps://login.salesforce.com
-
Generate the private key and certificates using open SSL as documented in the Salesforce (docs)[https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_key_and_cert.htm] and change environment variables in Heroku to use new
private key
,consumer key
andclient secret
obtained from the connected app in Salesforce. -
Heroku Free Dynos sleeps if left idle. For Production application we recommend you look into other types of Dynos.
- Connected apps activation takes couple minutes. In case the app fails with a 400 error for JWT auth, wait for 2 minutes and give a retry.
- If the app is failing, tail Heroku logs to see any errors