From 998d7d1227f1deaa7300ab5149a40dabd61a4df5 Mon Sep 17 00:00:00 2001 From: Jay <159848059+jayacryl@users.noreply.github.com> Date: Wed, 17 Jul 2024 16:52:41 -0400 Subject: [PATCH] docs(slack) overhauled setup instructions and screenshots (#10922) Co-authored-by: John Joyce --- docs-website/sidebars.js | 19 +- docs/actions/actions/slack.md | 2 +- docs/incidents/incidents.md | 2 +- .../managed-datahub-overview.md | 5 +- docs/managed-datahub/observe/assertions.md | 2 +- docs/managed-datahub/saas-slack-setup.md | 113 ----------- docs/managed-datahub/slack/saas-slack-app.md | 59 ++++++ .../managed-datahub/slack/saas-slack-setup.md | 176 ++++++++++++++++++ .../subscription-and-notification.md | 7 +- 9 files changed, 260 insertions(+), 125 deletions(-) delete mode 100644 docs/managed-datahub/saas-slack-setup.md create mode 100644 docs/managed-datahub/slack/saas-slack-app.md create mode 100644 docs/managed-datahub/slack/saas-slack-setup.md diff --git a/docs-website/sidebars.js b/docs-website/sidebars.js index e58dbd4d99b0b..8e48062af6d4d 100644 --- a/docs-website/sidebars.js +++ b/docs-website/sidebars.js @@ -209,11 +209,6 @@ module.exports = { }, items: [ "docs/managed-datahub/welcome-acryl", - { - type: "doc", - id: "docs/managed-datahub/saas-slack-setup", - className: "saasOnly", - }, { type: "doc", id: "docs/managed-datahub/approval-workflows", @@ -247,6 +242,20 @@ module.exports = { }, ], }, + { + Slack: [ + { + type: "doc", + id: "docs/managed-datahub/slack/saas-slack-setup", + className: "saasOnly", + }, + { + type: "doc", + id: "docs/managed-datahub/slack/saas-slack-app", + className: "saasOnly", + }, + ], + }, { "Operator Guide": [ { diff --git a/docs/actions/actions/slack.md b/docs/actions/actions/slack.md index bdea1c479e8aa..a89439825d2da 100644 --- a/docs/actions/actions/slack.md +++ b/docs/actions/actions/slack.md @@ -138,7 +138,7 @@ In the next steps, we'll show you how to configure the Slack Action based on the #### Managed DataHub -Head over to the [Configuring Notifications](../../managed-datahub/saas-slack-setup.md#configuring-notifications) section in the Managed DataHub guide to configure Slack notifications for your Managed DataHub instance. +Head over to the [Configuring Notifications](../../managed-datahub/slack/saas-slack-setup.md#configuring-notifications) section in the Managed DataHub guide to configure Slack notifications for your Managed DataHub instance. #### Quickstart diff --git a/docs/incidents/incidents.md b/docs/incidents/incidents.md index 578571289cd2e..41b4df10b7828 100644 --- a/docs/incidents/incidents.md +++ b/docs/incidents/incidents.md @@ -427,5 +427,5 @@ These notifications are also able to tag the immediate asset's owners, along wit

-To do so, simply follow the [Slack Integration Guide](docs/managed-datahub/saas-slack-setup.md) and contact your Acryl customer success team to enable the feature! +To do so, simply follow the [Slack Integration Guide](docs/managed-datahub/slack/saas-slack-setup.md) and contact your Acryl customer success team to enable the feature! diff --git a/docs/managed-datahub/managed-datahub-overview.md b/docs/managed-datahub/managed-datahub-overview.md index 087238097dd9f..4efc96eaf17a7 100644 --- a/docs/managed-datahub/managed-datahub-overview.md +++ b/docs/managed-datahub/managed-datahub-overview.md @@ -56,7 +56,8 @@ know. | Monitor Freshness SLAs | ❌ | ✅ | | Monitor Table Schemas | ❌ | ✅ | | Monitor Table Volume | ❌ | ✅ | -| Validate Table Columns | ❌ | ✅ | +| Monitor Table Column Integrity | ❌ | ✅ | +| Monitor Table with Custom SQL | ❌ | ✅ | | Receive Notifications via Email & Slack | ❌ | ✅ | | Manage Data Incidents via Slack | ❌ | ✅ | | View Data Health Dashboard | ❌ | ✅ | @@ -115,7 +116,7 @@ Fill out ## Additional Integrations -- [Slack Integration](docs/managed-datahub/saas-slack-setup.md) +- [Slack Integration](docs/managed-datahub/slack/saas-slack-setup.md) - [Remote Ingestion Executor](docs/managed-datahub/operator-guide/setting-up-remote-ingestion-executor.md) - [AWS Privatelink](docs/managed-datahub/integrations/aws-privatelink.md) - [AWS Eventbridge](docs/managed-datahub/operator-guide/setting-up-events-api-on-aws-eventbridge.md) diff --git a/docs/managed-datahub/observe/assertions.md b/docs/managed-datahub/observe/assertions.md index b74d524dff1bd..e63d051a0096b 100644 --- a/docs/managed-datahub/observe/assertions.md +++ b/docs/managed-datahub/observe/assertions.md @@ -38,7 +38,7 @@ If you opt for a 3rd party tool, it will be your responsibility to ensure the as ## Alerts -Beyond the ability to see the results of the assertion checks (and history of the results) both on the physical asset’s page in the DataHub UI and as the result of DataHub API calls, you can also get notified via [slack messages](/docs/managed-datahub/saas-slack-setup.md) (DMs or to a team channel) based on your [subscription](https://youtu.be/VNNZpkjHG_I?t=79) to an assertion change event. In the future, we’ll also provide the ability to subscribe directly to contracts. +Beyond the ability to see the results of the assertion checks (and history of the results) both on the physical asset’s page in the DataHub UI and as the result of DataHub API calls, you can also get notified via [Slack messages](/docs/managed-datahub/slack/saas-slack-setup.md) (DMs or to a team channel) based on your [subscription](https://youtu.be/VNNZpkjHG_I?t=79) to an assertion change event. In the future, we’ll also provide the ability to subscribe directly to contracts. With Acryl Observe, you can get the Assertion Change event by getting API events via [AWS EventBridge](/docs/managed-datahub/operator-guide/setting-up-events-api-on-aws-eventbridge.md) (the availability and simplicity of setup of each solution dependent on your current Acryl setup – chat with your Acryl representative to learn more). diff --git a/docs/managed-datahub/saas-slack-setup.md b/docs/managed-datahub/saas-slack-setup.md deleted file mode 100644 index 1b98f3a30773a..0000000000000 --- a/docs/managed-datahub/saas-slack-setup.md +++ /dev/null @@ -1,113 +0,0 @@ -import FeatureAvailability from '@site/src/components/FeatureAvailability'; - -# Configure Slack For Notifications - - - -## Install the DataHub Slack App into your Slack workspace - -The following steps should be performed by a Slack Workspace Admin. -- Navigate to https://api.slack.com/apps/ -- Click Create New App -- Use “From an app manifest” option -- Select your workspace -- Paste this Manifest in YAML. Suggest changing name and `display_name` to be `DataHub App YOUR_TEAM_NAME` but not required. This name will show up in your slack workspace -```yml -display_information: - name: DataHub App - description: An app to integrate DataHub with Slack - background_color: "#000000" -features: - bot_user: - display_name: DataHub App - always_online: false -oauth_config: - scopes: - bot: - - channels:read - - chat:write - - commands - - groups:read - - im:read - - mpim:read - - team:read - - users:read - - users:read.email -settings: - org_deploy_enabled: false - socket_mode_enabled: false - token_rotation_enabled: false -``` - -Confirm you see the Basic Information Tab - -![](https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/integrations/slack/slack_basic_info.png) - -- Click **Install to Workspace** -- It will show you permissions the Slack App is asking for, what they mean and a default channel in which you want to add the slack app - - Note that the Slack App will only be able to post in channels that the app has been added to. This is made clear by slack’s Authentication screen also. -- Select the channel you'd like notifications to go to and click **Allow** -- Go to DataHub App page - - You can find your workspace's list of apps at https://api.slack.com/apps/ - -## Generating a Bot Token - -- Go to **OAuth & Permissions** Tab - -![](https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/integrations/slack/slack_oauth_and_permissions.png) - -Here you'll find a “Bot User OAuth Token” which DataHub will need to communicate with your slack through the bot. -In the next steps, we'll show you how to configure the Slack Integration inside of Acryl DataHub. - -## Configuring Notifications - -> In order to set up the Slack integration, the user must have the `Manage Platform Settings` privilege. - -To enable the integration with slack -- Navigate to **Settings > Integrations** -- Click **Slack** -- Enable the Integration -- Enter the **Bot Token** obtained in the previous steps -- Enter a **Default Slack Channel** - this is where all notifications will be routed unless -- Click **Update** to save your settings - - - -To enable and disable specific types of notifications, or configure custom routing for notifications, start by navigating to **Settings > Notifications**. -To enable or disable a specific notification type in Slack, simply click the check mark. By default, all notification types are enabled. -To customize the channel where notifications are send, click the button to the right of the check box. - - - -If provided, a custom channel will be used to route notifications of the given type. If not provided, the default channel will be used. -That's it! You should begin to receive notifications on Slack. Note that it may take up to 1 minute for notification settings to take effect after saving. - -## Sending Notifications - -For now we support sending notifications to -- Slack Channel ID (e.g. `C029A3M079U`) -- Slack Channel Name (e.g. `#troubleshoot`) -- Specific Users (aka Direct Messages or DMs) via user ID - -By default, the Slack app will be able to send notifications to public channels. If you want to send notifications to private channels or DMs, you will need to invite the Slack app to those channels. - -## How to find Team ID and Channel ID in Slack - -- Go to the Slack channel for which you want to get channel ID -- Check the URL e.g. for the troubleshoot channel in OSS DataHub slack - -![](https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/integrations/slack/slack_channel_url.png) - -- Notice `TUMKD5EGJ/C029A3M079U` in the URL - - Team ID = `TUMKD5EGJ` from above - - Channel ID = `C029A3M079U` from above - -## How to find User ID in Slack - -- Go to user DM -- Click on their profile picture -- Click on View Full Profile -- Click on “More” -- Click on “Copy member ID” - -![](https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/integrations/slack/slack_user_id.png) \ No newline at end of file diff --git a/docs/managed-datahub/slack/saas-slack-app.md b/docs/managed-datahub/slack/saas-slack-app.md new file mode 100644 index 0000000000000..5e16fed901e72 --- /dev/null +++ b/docs/managed-datahub/slack/saas-slack-app.md @@ -0,0 +1,59 @@ +import FeatureAvailability from '@site/src/components/FeatureAvailability'; + +# Slack App Features + + + +## Overview +The DataHub Slack App brings several of DataHub's key capabilities directly into your Slack experience. These include: +1. Searching for Data Assets +2. Subscribing to notifications for Data Assets +3. Managing Data Incidents + +*Our goal with the Slack app is to make data discovery easier and more accessible for you.* + +## Slack App Commands +The command-based capabilities on the Slack App revolve around search. + +### Querying for Assets +You can trigger a search by simplying typing `/acryl my favorite table`. +

+ Example of an in-Slack Acryl search command being performed. +

+ +Right within Slack, you'll be presented with results matching your query, and a handful of quick-actions for your convenience. +

+ Example of search results being displayed within Slack. +

+ +By selecting **'More Details'** you can preview in-depth information about an asset without leaving Slack. +

+ Example of search results being displayed within Slack. +

+ +### Subscribing to be notified about an Asset +You can hit the **'Subscribe'** button on a specific search result to subscribe to it directly from within Slack. +

+ Example of search results being displayed within Slack. +

+ + +## Manage Data Incidents +Some of the most commonly used features within our Slack app are the Incidents management capabilities. +The DataHub UI offers a rich set of [Incident tracking and management](https://datahubproject.io/docs/incidents/incidents/) features. +When a Slack member or channel receives notifications about an Incident, many of these features are made accessible right within the Slack app. + +When an incident is raised, you will recieve rich context about the incident in the Slack message itself. You will also be able to `Mark as Resolved`, update the `Priorty`, set a triage `Stage` and `View Details` - directly from the Slack message. +

+ Example of search results being displayed within Slack. +

+ +If you choose to `Mark as Resolved` the message will update in-place, and you will be presented with the ability to `Reopen Incident` should you choose. +

+ Example of search results being displayed within Slack. +

+ + +## Coming Soon +We're constantly working on rolling out new features for the Slack app, stay tuned! + diff --git a/docs/managed-datahub/slack/saas-slack-setup.md b/docs/managed-datahub/slack/saas-slack-setup.md new file mode 100644 index 0000000000000..6db6a77c3a1f3 --- /dev/null +++ b/docs/managed-datahub/slack/saas-slack-setup.md @@ -0,0 +1,176 @@ +import FeatureAvailability from '@site/src/components/FeatureAvailability'; + +# Configure Slack For Notifications + + + +## Install the DataHub Slack App into your Slack workspace + + +### Video Walkthrough +
+ +### Step-by-step guide +The following steps should be performed by a Slack Workspace Admin. +1. Navigate to [https://api.slack.com/reference/manifests#config-tokens](https://api.slack.com/reference/manifests#config-tokens) +2. Under **Managing configuration tokens**, select **'Generate Token'** +

+ +

+3. Select your workspace, then hit **'Generate'** +

+ +

+4. Now you will see two tokens available for you to copy, an *Access Token* and a *Refresh Token* +

+ +

+5. Navigate back to your DataHub [Slack Integration setup page](https://longtailcompanions.acryl.io/settings/integrations/slack), and paste the tokens into their respective boxes, and click **'Connect'**. +

+ +

+6. You will be automatically re-directed to Slack to confirm DataHub Slack App's permissions and complete the installation process: +

+ +

+7. Congrats 🎉 Slack is set up! Now try it out by going to the **Platform Notifications** page +

+ +

+8. Enter your channel in, and click **'Send a test notification'** +

+ +

+ +Now proceed to the [Subscriptions and Notifications page](https://datahubproject.io/docs/managed-datahub/subscription-and-notification) to see how you can subscribe to be notified about events on the platform, or visit the [Slack App page](saas-slack-app.md) to see how you can use DataHub's powerful capabilities directly within Slack. + + + +## Sending Notifications + +For now, we support sending notifications to +- Slack Channel Name (e.g. `#troubleshoot`) +- Slack Channel ID (e.g. `C029A3M079U`) +- Specific Users (aka Direct Messages or DMs) via user ID + +By default, the Slack app will be able to send notifications to public channels. If you want to send notifications to private channels or DMs, you will need to invite the Slack app to those channels. + +## How to find Team ID and Channel ID in Slack +:::note +We recommend just using the Slack channel name for simplicity (e.g. `#troubleshoot`). +::: + +**Via Slack App:** +1. Go to the Slack channel for which you want to get a channel ID +2. Click the channel name at the top +

+ +

+3. At the bottom of the modal that pops up, you will see the Channel ID as well as a button to copy it +

+ +

+ +**Via Web:** +1. Go to the Slack channel for which you want to get a channel ID +2. Check the URL e.g. for the troubleshoot channel in OSS DataHub Slack +![](https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/integrations/slack/slack_channel_url.png) + +3. Notice `TUMKD5EGJ/C029A3M079U` in the URL + - Team ID = `TUMKD5EGJ` from above + - Channel ID = `C029A3M079U` from above + +## How to find User ID in Slack + +**Your User ID** +1. Click your profile picture, then select **'Profile'** +

+ +

+2. Now hit the **'...'** and select **'Copy member ID'** +

+ +

+ +**Someone else's User ID** +1. Click their profile picture in the Slack message +

+ +

+2. Now hit the **'...'** and select **'Copy member ID'** +

+ +

diff --git a/docs/managed-datahub/subscription-and-notification.md b/docs/managed-datahub/subscription-and-notification.md index 81648d4298ec1..0e456fe415b2c 100644 --- a/docs/managed-datahub/subscription-and-notification.md +++ b/docs/managed-datahub/subscription-and-notification.md @@ -5,7 +5,10 @@ import FeatureAvailability from '@site/src/components/FeatureAvailability'; DataHub's Subscriptions and Notifications feature gives you real-time change alerts on data assets of your choice. -With this feature, you can set up subscriptions to specific changes for an Entity – and DataHub will notify you when those changes happen. Currently, DataHub supports notifications on Slack, with support for Microsoft Teams and email subscriptions forthcoming. +With this feature, you can set up subscriptions to specific changes for an Entity – and DataHub will notify you when those changes happen. Currently, DataHub supports notifications on Slack and Email, with support for Microsoft Teams forthcoming. + +Email will work out of box. For installing the DataHub Slack App, see: +👉 [Configure Slack for Notifications](slack/saas-slack-setup.md)

@@ -16,7 +19,7 @@ As a user, you can subscribe to and receive notifications about changes such as ## Prerequisites -Once you have [configured Slack within your DataHub instance](saas-slack-setup.md), you will be able to subscribe to any Entity in DataHub and begin recieving notifications via DM. +Once you have [configured Slack within your DataHub instance](slack/saas-slack-setup.md), you will be able to subscribe to any Entity in DataHub and begin recieving notifications via DM. To begin receiving personal notifications, go to Settings > "My Notifications". From here, toggle on Slack Notifications and input your Slack Member ID. If you want to create and manage group-level Subscriptions for your team, you will need [the following privileges](../../docs/authorization/roles.md#role-privileges):