Salesforce Slack Starter Kit (Server to Server Integration)

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

Current Limitation

Multiple salesforce org connections to a single Slack workspace are not supported. Note that FOYER will support this feature.

About the Project

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.

App Architecture

System Architecture

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.

Heroku App <-> Salesforce

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.

Heroku App <-> Slack

The Heroku App connects to Slack using Bolt.js.

Prerequisites

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)

Setup Steps

Configuring Slack App

1. Open https://api.slack.com/apps/new and choose "From an app manifest"
2. Choose the workspace you want to install the application to
3. Copy the contents of manifest.yml into the text box that says *Paste your manifest code here* and click Next
4. Review the configuration and click Create
5. Now click Install App on the left menu. Then click the Install to Workspace button and then click on Allow

Running the Scaffolding Script

The scripts/deploy.js script scaffolds all the entities needed for the sample app to work. These are the steps followed:

Scratch Org Creation:

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.

Generation of certificate needed for JWT Bearer flow

We generate a private key and digital certificate to set up the JWT Bearer flow for authentication.

ConnectedApp deployment

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.

Heroku App creation and deployment of Bolt Node.js app

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

Running the script

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

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

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

Setting Heroku Instance in your Slack App

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 replace heroku-app with your actual heroku domain name. Note at the end of this step your url should look like https://<heroku-domain>.herokuapp.com/slack/events

Directory Structure

├── 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

How to Build and Deploy Code

• For Salesforce metadata synchronization use sfdx force:source:pull to retrieve and sfdx force:source:push to deploy metadata from orgs to local project folder force-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

Local Development

• For local Development, first make sure to deploy the app on Heroku as listed in the section above.
• Next perform the steps below:

1. 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 };
2. 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
3. Populate the .env file with SLACK_APP_TOKEN variable obtained in previous step
4. cd into apps/slack-salesforce-starter-ap folder cd apps/slack-salesforce-starter-app
5. Run npm install
6. Run node app.js

At this point you should see the Node.js app recieving events from Slack directly in VSCode terminal.

How to Test the Salesforce Connection

1. Run the Global Shortcut command Whoami that ships with the app as shown in the below screenshot

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

Considerations for Production app

• For a production application change the SF_LOGIN_URL from 'https://test.salesforce.com' to https://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 and client 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.

Troubleshooting

• 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

Further Reference

• Bolt Family of SDKs
• Block Builder