Sample Apex SDK for Slack App

The sample app includes a variety of view definitions and Apex handlers to demonstrate its core functionalities.

Before you download the sample app, make sure you've set up the prerequisites.

There are several versions of the sample app.

  • apex-end-to-end-example-v5.zip: This file has new changes.

    • Added the TestEventDispatcherEventExample test example
    • Added the ActionDispatcherViewSelectedRecord class that handles the onsubmit event on the view_oppportunities_by_account view definition.
    • Fixed the ApexSlackApp.slackapp app definition for the reaction_added and reaction_removed events.

  • apex-end-to-end-example-v4.zip: This file has new changes.

    • Replaced the field component with mrkdwn.
    • Added the EventDispatcherEventExample class to demonstrate event support.
    • Added the test suite ApexEndToEndTestSuite.
    • Added test classes TestDataProviderAccountLookup, TestDataProviderOpportunityLookup, and TestDataProviderSObjectRecord.
    • Deleted TestOpportunityLookupDataProvider.
    • Renamed RecordDataProvider to EventDispatcherAppHomeOpened.
    • Renamed the following test classes.
      • TestAppHomeOpened is now TestEventDispatcherAppHomeOpened
      • TestCreateRecordDispatcher is now TestShortcutDispatcherCreateRecord
      • TestReactionsGetShortcutDispatcher is now TestShortcutDispatcherReactionsGet
      • TestViewOppByAccountCommandDispatcher is now TestCommandDispatcherViewOppByAccount
      • TestViewRecordCommandDispatcher is now TestCommandDispatcherViewRecord.
    • Renamed the following action dispatchers.
      • CreateRecordCommandDispatcher is now CommandDispatcherCreateRecord
      • CreateRecordShortcutDispatcher is now ShortcutDispatcherCreateRecord
      • ViewOppByAccountCommandDispatcher is now CommandDispatcherViewOppByAccount
      • ViewRecordCommandDispatcher is now ShortcutDispatcherReactionsGet.

  • apex-end-to-end-example-v3.zip: This file has new changes.

    • Added a test suite for the Apex handlers.
    • Added example classes OpportunityLookupDataProvider and ViewOppByAccountCommandDispatcher to demonstrate how to use the Select Component using List<Slack.Option> and List<Slack.OptionGroup>.

  • apex-end-to-end-example-v2.zip: Added a ReactionsGetResponse example

  • apex-end-to-end-example.zip

After you download the sample app, unzip the file, and move the content of the force-app folder into your SFDX project.

After setting up your prerequisites, create a Slack app to work with your sample app.

  1. Create an app on api.slack.com and use the following app manifest.

The app_uninstalled and tokens_revoked events are required if you expect to disconnect your Slack app from an org and reconnect to a different org. See Org Connections.

An app manifest enables you to create, configure, and copy your Slack apps easily. If you see an error while saving the manifest, check your indentation. For the manifest schema, see Create and configure apps with manifests.

  1. Install the app to your workspace.
  2. Update the app manifest with your app ID.

Alternatively, update your app ID via the OAuth & Permissions page. Under Redirect URLs, replace <your-app-id> with the app ID on the Basic Information page.
  1. From your local SFDX directory, open slackapp/ApexSlackApp.slackapp-meta.xml.
  • Replace the appKey, appToken, clientKey, clientSecret, and signingSecret with values from the app you created on api.slack.com. The app Key (as App Id), client Key (as Client Id), client key, and client secret are available on the app's Basic Information page at api.slack.com.
  • Generate the app token under App-Level Tokens.
  1. Make sure the commands, shortcuts, and events defined in ApexSlackApp.slackapp match the values in your app manifest on api.slack.com.
  • If you're installing your app to a shared workspace, prefix your commands with a unique identifier in both places. This identifier ensures your commands don't break if another user installs a second example app to the same workspace.

To use a different name for your app besides "ApexSlackApp," you can change the name of the .slackapp and .slackapp-meta.xml files, like myApp.slackapp and myApp.slackapp-meta.xml. Update any references to your app name in apex classes. For example in EventDispatcherAppHomeOpened, replace Slack.App.ApexSlackApp.get() with Slack.App.myApp.get().

Next, you can deploy your sample app to a scratch org using sf project deploy start. If you haven't set up a scratch org, see Create a Scratch Org.

After you push your sample app to a scratch org, you can test the commands in your Slack workspace as discussed in this section.

For example, when you run /apex-create-record the first time, you get a prompt to connect your Salesforce org. Click the link and log in with your scratch org's username and password. After you successfully connect your Salesforce org, run your command again.

To see your username, run sf org list. To generate a password, run sf org generate password --target-org <yourusername>@example.com.

The sample app demonstrates the following areas.

  • Slash Commands
  • Global Shortcuts
  • Message Shortcuts
  • Events
  • Test Suite

The ApexSlackApp.slackapp file configures these commands and the Apex actions they call.

/apex-create-record calls the CommandDispatcherCreateRecord Apex class to open a modal using the create_record view definition.

/apex-view-record calls the CommandDispatcherViewRecord Apex class to open a modal to view record details for Accounts, Contacts, or Opportunities using the corresponding view definitions: view_account, view_contact, or view_opportunity.

The CommandDispatcherViewRecord Apex class extends Slack.SlashCommandDispatcher to handle the slash command that's registered with the Slack app.

For example, you can enter a command like /apex-view-record Account 00Bxx0000029bnsEAA and the Apex action returns a modal described by the view_account definition.

The ApexSlackApp.slackapp file configures a global shortcut and its Apex action.

The apex-create-record-global global shortcut calls the ShortcutDispatcherCreateRecord Apex class to open a modal using the create_record view definition.

The ShortcutDispatcherCreateRecord Apex class extends Slack.ShortcutDispatcher to handle the global and message shortcuts that are registered with the Slack app.

To test out the global shortcut, press the shortcuts button in the message composer or from within search in your Slack workspace. For more information, see Shortcuts.

The ApexSlackApp.slackapp file configures a message shortcut to call an Apex action.

The apex-create-record-message message shortcut calls the ShortcutDispatcherCreateRecord Apex class to open a modal using the create_record view definition.

The ShortcutDispatcherCreateRecord Apex class extends Slack.ShortcutDispatcher to handle the slash command registered with the Slack app.

To test out the message shortcut, go to the overflow menu on a message. If the shortcut isn't available on the menu, click "More message shortcuts..." and find the shortcut by typing it in the search field in your Slack workspace.

The ApexSlackApp.slackapp file configures the app_home_opened event to call an Apex action.

When a user clicks into the App Home tab, the EventDispatcherAppHomeOpened Apex class returns the app_home view definition.

The EventDispatcherAppHomeOpened Apex class extends Slack.EventDispatcher to handle the app_home_opened event.

The example app includes an implementation of the test harness. The ApexExampleEndToEndTestSuite test suite in force-app/main/default/testSuites contains tests for commands, shortcuts, and event handlers in the example app that are currently supported by the test harness.

To run the Apex test suite:

To run the Apex test suite with coverage:

See the apex run test command.

Alternatively, run the test suite in the Developer Console after logging into the scratch org.