From b9946ee35c4c444ee6550b5c2fd2d75854a0c28c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nuno=20G=C3=B3is?= Date: Fri, 22 Sep 2023 23:19:17 +0100 Subject: [PATCH] docs: Unleash Slack App integration (#4801) https://linear.app/unleash/issue/2-1235/docs-slack-app-integration-documentation This adds a new reference doc for the new Unleash Slack App integration and marks the previous Slack integration as deprecated. As a side-effect this PR also fixes an issue where we wouldn't be able to delete tags with special characters. --------- Co-authored-by: David Leek Co-authored-by: Thomas Heartman --- .../actions/useFeatureApi/useFeatureApi.ts | 6 +- src/lib/addons/slack-app-definition.ts | 2 - .../reference/integrations/integrations.md | 8 ++- .../docs/reference/integrations/slack-app.md | 63 ++++++++++++++++++ website/docs/reference/integrations/slack.md | 10 ++- website/sidebars.js | 1 + ...ck_addon_tags.png => slack-addon-tags.png} | Bin 7 files changed, 84 insertions(+), 6 deletions(-) create mode 100644 website/docs/reference/integrations/slack-app.md rename website/static/img/{slack_addon_tags.png => slack-addon-tags.png} (100%) diff --git a/frontend/src/hooks/api/actions/useFeatureApi/useFeatureApi.ts b/frontend/src/hooks/api/actions/useFeatureApi/useFeatureApi.ts index 8bd77729c2b1..4340616588e9 100644 --- a/frontend/src/hooks/api/actions/useFeatureApi/useFeatureApi.ts +++ b/frontend/src/hooks/api/actions/useFeatureApi/useFeatureApi.ts @@ -196,8 +196,12 @@ const useFeatureApi = () => { type: string, value: string ) => { + const encodedTagPath = `${encodeURIComponent( + type + )}/${encodeURIComponent(value)}`; + // TODO: Change this path to the new API when moved. - const path = `api/admin/features/${featureId}/tags/${type}/${value}`; + const path = `api/admin/features/${featureId}/tags/${encodedTagPath}`; const req = createRequest(path, { method: 'DELETE', }); diff --git a/src/lib/addons/slack-app-definition.ts b/src/lib/addons/slack-app-definition.ts index e246f25690f2..c71b0446fc37 100644 --- a/src/lib/addons/slack-app-definition.ts +++ b/src/lib/addons/slack-app-definition.ts @@ -11,7 +11,6 @@ import { FEATURE_STRATEGY_ADD, FEATURE_METADATA_UPDATED, FEATURE_PROJECT_CHANGE, - FEATURE_VARIANTS_UPDATED, FEATURE_POTENTIALLY_STALE_ON, FEATURE_ENVIRONMENT_VARIANTS_UPDATED, } from '../types/events'; @@ -62,7 +61,6 @@ const slackAppDefinition: IAddonDefinition = { FEATURE_STRATEGY_UPDATE, FEATURE_STRATEGY_ADD, FEATURE_METADATA_UPDATED, - FEATURE_VARIANTS_UPDATED, FEATURE_PROJECT_CHANGE, FEATURE_POTENTIALLY_STALE_ON, ], diff --git a/website/docs/reference/integrations/integrations.md b/website/docs/reference/integrations/integrations.md index 9cfece40b05a..1d96c1de5165 100644 --- a/website/docs/reference/integrations/integrations.md +++ b/website/docs/reference/integrations/integrations.md @@ -24,7 +24,7 @@ Unleash currently supports the following integrations out of the box: - [Jira Cloud](jira-cloud-plugin-usage.md) - Allows you to create, view and manage Unleash feature flags directly from a Jira Cloud issue - [Jira Server](jira-server-plugin-usage.md) - Allows you to create and link Unleash feature flags directly from a Jira Server issue - [Microsoft Teams](teams.md) - Allows Unleash to post updates to Microsoft Teams. -- [Slack](slack.md) - Allows Unleash to post updates to Slack. +- [Slack App](slack-app.md) - The Unleash Slack App posts messages to the selected channels in your Slack workspace. - [Webhook](webhook.md) - A generic way to post messages from Unleash to third party services. :::tip Missing an integration? Request it! @@ -33,6 +33,12 @@ If you're looking for an integration that Unleash doesn't have at the moment, yo ::: +## Deprecated integrations + +These integrations are deprecated and will be removed in a future release: + +- [Slack](slack.md) - Allows Unleash to post updates to Slack. Please try the new [Slack App](slack-app.md) integration instead. + ## Community integrations Our wonderful community has also created the following integrations: diff --git a/website/docs/reference/integrations/slack-app.md b/website/docs/reference/integrations/slack-app.md new file mode 100644 index 000000000000..e83da6684dd9 --- /dev/null +++ b/website/docs/reference/integrations/slack-app.md @@ -0,0 +1,63 @@ +--- +title: Slack App +--- + +import Figure from '@site/src/components/Figure/Figure.tsx' + +:::info Availability + +The Slack App integration was introduced in **Unleash 5.5**. + +::: + +The Slack App integration posts messages to a specified set of channels in your Slack workspace. The channels can be public or private, and can be specified on a per-flag basis by using [Slack tags](#tags). + +## Installation {#installation} + +To install the Slack App integration, follow these steps: + +1. Navigate to the *integrations* page in the Unleash admin UI (available at the URL `/integrations`) and select "configure" on the Slack App integration. +2. On the integration configuration form, use the "install & connect" button. +3. A new tab will open, asking you to select the Slack workspace where you'd like to install the app. +4. After successful installation of the Unleash Slack App in your chosen Slack workspace, you'll be automatically redirected to a page displaying a newly generated access token. +5. Copy this access token and paste it into the `Access token` field within the integration settings. + +By default, the Unleash Slack App is granted access to public channels. If you want the app to post messages to private channels, you'll need to manually invite it to each of those channels. + +## Configuration {#configuration} + +The configuration settings allow you to choose the events you're interested in and whether you want to filter them by projects and environments. You can configure a comma-separated list of channels to post the configured events to. These channels are always notified, regardless of the event type or the presence of [Slack tags](#tags). + +#### Events {#events} + +You can choose to trigger updates for the following events: + +- feature-created +- feature-metadata-updated +- feature-project-change +- feature-archived +- feature-revived +- feature-strategy-update +- feature-strategy-add +- feature-strategy-remove +- feature-stale-on +- feature-stale-off +- feature-environment-enabled +- feature-environment-disabled +- feature-environment-variants-updated +- feature-potentially-stale-on + +#### Parameters {#parameters} + +The Unleash Slack App integration takes the following parameters. + +- **Access token** - This is the only required property. After successful installation of the Unleash Slack App in your chosen Slack workspace, you'll be automatically redirected to a page displaying a newly generated access token. You should copy this access token and paste it into this field. +- **Channels** - A comma-separated list of channels to post the configured events to. These channels are always notified, regardless of the event type or the presence of a Slack tag. + +## Tags {#tags} + +Besides the configured channels, you can choose to notify other channels by tagging your feature flags with Slack-specific tags. For instance, if you want the Unleash Slack App to send notifications to the `#general` channel, add a Slack-type tag with the value "general" (or "#general"; both will work) to your flag. This will ensure that any configured events related to that feature flag will notify the tagged channel in addition to any channels configured on the integration-level. + +To exclusively use tags for determining notification channels, you can leave the "channels" field blank in the integration configuration. Since you can have multiple configurations for the integration, you're free to mix and match settings to meet your precise needs. Before posting a message, all channels for that event, both configured and tagged, are combined and duplicates are removed. + +
diff --git a/website/docs/reference/integrations/slack.md b/website/docs/reference/integrations/slack.md index 4e2aa4c51147..86e0e9bd5b40 100644 --- a/website/docs/reference/integrations/slack.md +++ b/website/docs/reference/integrations/slack.md @@ -1,8 +1,14 @@ --- id: slack -title: Slack +title: Slack (deprecated) --- +:::caution Deprecation notice + +This Slack integration is deprecated and will be removed in a future release. We recommend using the new [Slack App](./slack-app.md) integration instead. + +::: + > This feature was introduced in _Unleash v3.11.0_. The Slack integration allows Unleash to post Updates when a feature toggle is updated. To set up Slack, you need to configure an incoming Slack webhook URL. You can follow [Sending messages using Incoming Webhooks](https://api.slack.com/incoming-webhooks) on how to do that. You can also choose to [create a slack app for Unleash](https://api.slack.com/apps), which will provide you with additional functionality to control how Unleash communicates messages on your Slack workspace. @@ -48,6 +54,6 @@ Unleash Slack integration takes the following parameters. The Slack integration also defined the Tag type "slack". You may use this tag to override which Slack channel Unleash should post updates to for this feature toggle. -![Slack Tags](/img/slack_addon_tags.png) +![Slack Tags](/img/slack-addon-tags.png) In the picture you can see we have defined two slack tags for the "new-payment-system" toggle. In this example Unleash will post updates to the **#notifications** and **#random** channel. diff --git a/website/sidebars.js b/website/sidebars.js index 21b4a8d1f233..5795144fa6c6 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -347,6 +347,7 @@ module.exports = { 'reference/integrations/jira-cloud-plugin-usage', ], }, + 'reference/integrations/slack-app', 'reference/integrations/slack', 'reference/integrations/teams', 'reference/integrations/webhook', diff --git a/website/static/img/slack_addon_tags.png b/website/static/img/slack-addon-tags.png similarity index 100% rename from website/static/img/slack_addon_tags.png rename to website/static/img/slack-addon-tags.png