--- schema_version: "1" id: dff42b53d4688a1a25fc5ded0d6cbac9ce275d80c4bd163f87edaba8e4fcd260 title: Sample Apex SDK for Slack App collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/salesforce-slack-sdk/apex-slack-sdk/guides/setup-install-app.md canonical_url: https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/setup-install-app.html source_site: developer.salesforce.com content_type: documentation content_hash: f092d7bec3c2ac0532d2ac61903cacf1dd16568491cc61cc57dbe9c1cef81f64 products: - Apex SDK for Slack (Beta) --- # 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. - [Set Up Your Development Environment](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/setup-your-env.md) - [Set Up Your SFDX Project](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/run-sfdx.md) ## Download the Sample App There are several versions of the sample app. - [apex-end-to-end-example-v5.zip](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/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](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/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](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/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` and `List`. - [apex-end-to-end-example-v2.zip](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/apex-end-to-end-example-v2.zip): Added a [`ReactionsGetResponse`](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/apex_ref/apex_ref_reactions.md#reactionsgetrequest-class) example - [apex-end-to-end-example.zip](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/apex-end-to-end-example.zip) **tip:** After you download the sample app, unzip the file, and move the content of the `force-app` folder into your SFDX project. ## 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](https://api.slack.com/apps) and use the following app manifest. ```yaml _metadata: major_version: 1 minor_version: 1 display_information: name: Apex Example App features: app_home: home_tab_enabled: true messages_tab_enabled: false messages_tab_read_only_enabled: false bot_user: display_name: apex-end-to-end-example-app always_online: true shortcuts: - name: apex create record type: message callback_id: apex-create-record-message description: apex create record global - name: apex create record type: global callback_id: apex-create-record-global description: Create a record with Apex - name: apex reactions get type: message callback_id: apex-reactions-get description: Retrieve reactions for a message with the ReactionsGet api slash_commands: - command: /apex-create-record url: https://slack-apps.salesforce.com:9443/a/ description: Create a record with Apex should_escape: false - command: /apex-view-record url: https://slack-apps.salesforce.com:9443/a/ description: View a record with Apex should_escape: false - command: /apex-find-opp-by-account-id url: https://slack-apps.salesforce.com:9443/a/ description: view opportunities by accountId should_escape: false oauth_config: redirect_urls: - https://auth.slack-apps.salesforce.com/slack_oauth_callback/ scopes: user: - channels:read bot: - chat:write - commands - channels:history - groups:history - im:history settings: event_subscriptions: bot_events: - app_home_opened - app_uninstalled - channel_rename - group_rename - reaction_added - reaction_removed - tokens_revoked request_url: https://slack-apps.salesforce.com:9443/a/ interactivity: is_enabled: true message_menu_options_url: https://slack-apps.salesforce.com:9443/a/ request_url: https://slack-apps.salesforce.com:9443/a/ org_deploy_enabled: false socket_mode_enabled: false token_rotation_enabled: false ``` **important:** 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](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/orgs-multi.md). 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](https://api.slack.com/reference/manifests). 1. Install the app to your workspace. 2. Update the app manifest with your app ID. **note:** Alternatively, update your app ID via the **OAuth & Permissions** page. Under **Redirect URLs**, replace `` with the app ID on the **Basic Information** page. ## 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](https://api.slack.com/apps). 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](https://api.slack.com/apps). - Generate the app token under **App-Level Tokens**. 2. Make sure the commands, shortcuts, and events defined in `ApexSlackApp.slackapp` match the values in your app manifest on [api.slack.com](https://api.slack.com/apps). - 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. **tip:** 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](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/run-sfdx.md#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. **tip:** To see your username, run `sf org list`. To generate a password, run `sf org generate password --target-org @example.com`. 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. ```yaml commands: /apex-create-record: action: definition: apex__action__CommandDispatcherCreateRecord title: Create Record Command description: Create a record using a slack command. /apex-view-record: action: definition: apex__action__CommandDispatcherViewRecord title: View Record Command description: View record details by objectApiName and recordId. # 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`](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/apex_ref/apex_ref_dispatchers.md#slashcommanddispatcher-class) 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. ```yaml globalShortcuts: apex-create-record-global: action: definition: apex__action__ShortcutDispatcherCreateRecord title: Create Record Global Shortcut 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`](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/apex_ref/apex_ref_dispatchers.md#shortcutdispatcher-class) 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](https://uisf-docs.herokuapp.com/salesforce-slack-sdk/guide/actions_interact.html). ### Message Shortcuts The `ApexSlackApp.slackapp` file configures a message shortcut to call an Apex action. ```yaml messageShortcuts: apex-create-record-message: action: definition: apex__action__ShortcutDispatcherCreateRecord title: Create Record Message Shortcut 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`](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/apex_ref/apex_ref_dispatchers.md#shortcutdispatcher-class) 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](https://api.slack.com/events/app_home_opened) to call an Apex action. ```yaml events: app_home_opened: action: definition: apex__action__EventDispatcherAppHomeOpened title: Example event handler for app_home_opened description: event fires when a user opens the home tab. # 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`](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/apex_ref/apex_ref_dispatchers.md#eventdispatcher-class) to handle the `app_home_opened` event. ### Run Test Suite The example app includes an implementation of the [test harness](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/test/test.md). 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: ```bash sf apex run test --suite-names ApexExampleEndToEndTestSuite ``` To run the Apex test suite with coverage: ```bash sf apex run test --suite-names ApexExampleEndToEndTestSuite --code-coverage --result-format human ``` **tip:** See the [apex run test](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_apex_commands_unified.htm#cli_reference_apex_run_test_unified) command. Alternatively, run the test suite in the Developer Console after logging into the scratch org.