> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementary-data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack setup for Elementary CLI

Elementary Slack integration includes sending [Slack alerts](https://docs.elementary-data.com/oss/guides/alerts/send-slack-alerts.md) on failures in dbt tests and models, and the option to distribute the [data observability report](https://docs.elementary-data.com/oss/guides/generate-report-ui.md) as a message attachment.

## Token vs Webhook

There are two integration options: Token or Webhook.
Both methods let you receive alerts from Elementary, but there are several features that are only supported in one of the two.
Below is features support comparison table, to help you select the integration method.

> [!NOTE]
>
> If possible, Token is the preferred way. It allows more flexibility and
> supports more features than Webhook.

| Slack integration | Elementary alerts | Elementary report | Multiple channels | Slack workflows |
| - | - | - | - | - |
| Token | ✅ | ✅ | ✅ | ❌ |
| Webhook | ✅ | ❌ | ❌ | ✅ |

## Slack integration setup

First create a Slack app:

> [accordion] Create a Slack App
>
> ## 1. Create a Slack app
>
> Go to the [Slack page to create apps](https://api.slack.com/apps?new_app=1) and create a new app (from scratch).
> Call it "[Elementary](#slack-app-display)" and connect it to the workspace of your choice.
>
> ![Slack app](https://res.cloudinary.com/mintlify/image/upload/v1659304879/elementary/slack-app_zpn7jc.png)
>
> ## 2. Optional - Slack app display
>
> To change the display of the Elementary slack app, scroll down on the Slack app basic information page to the 'Display Information' section:
>
> ![Slack display](https://res.cloudinary.com/diuctyblm/image/upload/v1690367739/slack_app_customize_movkxg.png)
>
> Here is the Elementary icon for your use (click to download):
>
> [![](https://res.cloudinary.com/diuctyblm/image/upload/v1690367713/elementary_alert_dzibc7.png)](https://docs.elementary-data.com/pics/elementary_app.png)

Based on the method you selected, create a [token or webhook](https://docs.elementary-data.com/oss/deployment-and-configuration/slack.md#token-vs-webhook):

> [accordion] Create Slack Token
>
> ## 1. Create a Slack token
>
> Go to the "OAauth & Permissions" page for your newly-created app, and add the following scopes under "Bot Token Scopes":
>
> * `channels:join` - Join public channels in a workspace
> * `channels:read` - View basic information about public channels in a workspace
> * `chat:write` - Send messages as \<app>
> * `files:write` - Upload, edit, and delete files as \<app>
> * `users:read` - View people in a workspace
> * `users:read.email` - View email addresses of people in a workspace
> * `groups:read` - View basic information about private channels that your slack app has been added to
> * `usergroups:read` - View user groups in a workspace (optional, needed only to [tag user groups](https://docs.elementary-data.com/oss/guides/alerts/alerts-configuration.md#tagging-owners-and-subscribers-on-slack) in alerts)
>
> ![Slack scopes](https://res.cloudinary.com/diuctyblm/image/upload/v1695889115/slack-app-permissions-new_bysiso.png)
>
> ## 2. Install app at your Workspace
>
> At the "OAuth & Permissions" page, press on "Install to Workspace" in order to generate Slack token:
>
> ![Slack OAuth](https://res.cloudinary.com/mintlify/image/upload/v1659304881/elementary/slack-oauth_g6p5jj.png)

> [accordion] Create Slack Webhook
>
> ## Create a webhook
>
> Go to the 'Incoming Webhooks' page for your newly-created app and toggle 'Activate Incoming Webhooks' to turn it on. Then click on 'Add New Webhook to Workspace':
>
> ![Slack webhook](https://res.cloudinary.com/mintlify/image/upload/v1659304882/elementary/slack-webhook_gwjkte.png)
>
> Select the channel that the notifications will be posted to:
>
> ![Slack channel](https://res.cloudinary.com/mintlify/image/upload/v1659304879/elementary/slack-channel_snyrwb.png)

Lastly, pass the token / webhook to the CLI as a param or in the `config.yml` file:

> [accordion] Slack config as CLI params
>
> ## Token:
>
> Use the Slack token when you execute edr monitor using the option `-st, --slack-token` and `-ch, --slack-channel-name`:
>
> ```shell theme={null}
> edr monitor --slack-token <your_slack_token> --slack-channel-name <slack_channel_to_post_at>
> ```
>
> ## Webhook:
>
> Use the webhook URL when you execute edr monitor using the option `-s, --slack-webhook`:
>
> ```shell theme={null}
> edr monitor --slack-webhook <your_slack_webhook_url>
> ```

> [accordion] Slack config as in config.yml
>
> The CLI reads the Slack integration from a file, copy it into a file called config.yml.
> Create it here: `HOME_DIR/.edr/config.yml`
>
> Here is the format in the yml itself:
>
> ## Token:
>
> ```yml config.yml theme={null}
> slack:
>   token: <your_slack_token>
>   channel_name: <slack_channel_to_post_at>
>   group_alerts_by: <"table"> or <"alert">
>
> # optional #
> timezone: <optional_timezone_for_timestamps>
> ```
>
> ## Webhook:
>
> ```yml config.yml theme={null}
> slack:
>   notification_webhook: <your_slack_webhook_url>
>   group_alerts_by: <"table"> or <"alert">
>   # optional #
>   workflows: false
>
> # optional #
> timezone: <optional_timezone_for_timestamps>
> ```

***

## Slack Workflows

If you use [Slack Workflows](https://slack.com/features/workflow-automation), add the following configuration to your `config.yml` under the slack tag:

```yml config.yml theme={null}
slack:
  notification_webhook: <your_slack_webhook_url>
  workflows: true
```

This flag `workflows: true` changes the format in which edr sends Slack alerts to the key-value pairs format supported by Slack Workflows.
The alert keys can be used to build a [Slack workflow](https://slack.com/help/articles/360053571454-Set-up-a-workflow-in-Slack).

The alert format is:

```json theme={null}
{
  "alert_description": str,
  "table_name": str,
  "detected_at": str,
  "type": str,
  "description": str
}
```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.