Sample Apex SDK for Slack App

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

Prerequisites 

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

Download the Sample App 

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.

Tip

Create a Slack App 

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.

    1_metadata:
2    major_version: 1
3    minor_version: 1
4display_information:
5    name: Apex Example App
6features:
7    app_home:
8        home_tab_enabled: true
9        messages_tab_enabled: false
10        messages_tab_read_only_enabled: false
11    bot_user:
12        display_name: apex-end-to-end-example-app
13        always_online: true
14    shortcuts:
15        - name: apex create record
16          type: message
17          callback_id: apex-create-record-message
18          description: apex create record global
19        - name: apex create record
20          type: global
21          callback_id: apex-create-record-global
22          description: Create a record with Apex
23         - name: apex reactions get
24           type: message
25           callback_id: apex-reactions-get
26           description: Retrieve reactions for a message with the ReactionsGet api
27    slash_commands:
28        - command: /apex-create-record
29          url: https://slack-apps.salesforce.com:9443/a/<your-app-ID>
30          description: Create a record with Apex
31          should_escape: false
32        - command: /apex-view-record
33          url: https://slack-apps.salesforce.com:9443/a/<your-app-ID>
34          description: View a record with Apex
35          should_escape: false
36        - command: /apex-find-opp-by-account-id
37          url: https://slack-apps.salesforce.com:9443/a/<your-app-ID>
38          description: view opportunities by accountId
39          should_escape: false
40oauth_config:
41    redirect_urls:
42        - https://auth.slack-apps.salesforce.com/slack_oauth_callback/<your-app-ID>
43    scopes:
44        user:
45            - channels:read
46        bot:
47            - chat:write
48            - commands
49            - channels:history
50            - groups:history
51            - im:history
52settings:
53    event_subscriptions:
54        bot_events:
55            - app_home_opened
56            - app_uninstalled
57            - channel_rename
58            - group_rename
59            - reaction_added
60            - reaction_removed
61            - tokens_revoked
62        request_url: https://slack-apps.salesforce.com:9443/a/<your-app-ID>
63    interactivity:
64        is_enabled: true
65        message_menu_options_url: https://slack-apps.salesforce.com:9443/a/<your-app-Id>
66        request_url: https://slack-apps.salesforce.com:9443/a/<your-app-ID>
67    org_deploy_enabled: false
68    socket_mode_enabled: false
69    token_rotation_enabled: false

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.

Important

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.

Note

Configure the Sample App 
  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().

Tip

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.

Explore the Sample App 

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.

Tip

The sample app demonstrates the following areas.

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

Slash Commands 

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

1commands:
2  /apex-create-record:
3    action:
4      definition: apex__action__CommandDispatcherCreateRecord
5    title: Create Record Command
6    description: Create a record using a slack command.
7  /apex-view-record:
8    action:
9      definition: apex__action__CommandDispatcherViewRecord
10    title: View Record Command
11    description: View record details by objectApiName and recordId.
12# More shortcut definitions here

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

Global Shortcuts 

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

1globalShortcuts:
2  apex-create-record-global:
3    action:
4      definition: apex__action__ShortcutDispatcherCreateRecord
5    title: Create Record Global Shortcut
6    description: Create a record using a slack global shortcut.

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.

Message Shortcuts 

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

1messageShortcuts:
2  apex-create-record-message:
3    action:
4      definition: apex__action__ShortcutDispatcherCreateRecord
5    title: Create Record Message Shortcut
6    description: Create a record using a slack message shortcut.

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.

Events 

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

1events:
2  app_home_opened:
3    action:
4      definition: apex__action__EventDispatcherAppHomeOpened
5    title: Example event handler for app_home_opened
6    description: event fires when a user opens the home tab.
7# More event definitions here

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.

Run Test Suite 

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:

1sf apex run test --suite-names ApexExampleEndToEndTestSuite

To run the Apex test suite with coverage:

1sf apex run test --suite-names ApexExampleEndToEndTestSuite --code-coverage --result-format human

See the apex run test command.

Tip

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

Beta Feature

This feature is not generally available. It is not part of your purchased Services. This feature is subject to change, may be discontinued with no notice at any time in SFDC’s sole discretion, and SFDC may never make this feature generally available. Make your purchase decisions only on the basis of generally available products and features. This feature is made available on an AS IS basis and use of this feature is at your sole risk.

Apex SDK for Slack (Beta)
Documentation Changelog
Get Started
Enable Slack for Salesforce Beta
Set Up Your Development Environment
Set Up Your SFDX Project
Deploy a Slack App
Sample Apex SDK for Slack App
Work with Salesforce Orgs and Users
Build Slack Apps
Test Slack Apps
Distribute Slack Apps
Component Reference
Metadata API
Tooling API
Apex