Integrate with Slack for Alerts and Warning notifications
=========================================================

Integrate CodeScene with Slack to receive a notification when a CodeScene analysis is run.
The notification includes all Alerts and Warnings, giving you an easy way of sharing critical
information with the whole team.
You can subscribe to both _full_ analysis and _delta_ analysis notifications.

  **Act upon Alerts and Warnings**: Code Health declines are handled by planning Goals inside CodeScene. With a Goal,
  the alert will go away and be auto-supervised in your build pipeline and/or pull requests.

Here's an example of a notification message in :numref:`slack-notification-ex-1`.

.. figure:: slack-notification-ex-1.png
   :alt: Slack notification message example
   :name: slack-notification-ex-1

   Slack notification message example

You can choose the types of notifications you get (e.g. analysis error, 'Danger' alert, etc.)
in the configuration.

**There are two configurations:**

* Global - applies to all projects
* Per-project - overrides the global config for a specific project


Global Configuration
---------------------

CodeScene administrators can customize notifications in the global configuration on the `Notifications` tab.
As a minimum, you need to set `Slack API Connection Settings` to make it possible for project admins (architects)
to use their own settings.

Here's an annotated example:

.. figure:: slack-notifications-global.png
   :alt: Example of slack notifications global config
   :name: slack-notifications-global

   Example of slack notifications global config

First, `CodeScene host URL` must be set properly in the System tab if you want to receive proper links to your analyses' results.
Make sure that the protocol, the host and the port are all correct.


Slack API Connection Settings - Slack Application Setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You need to create a new Slack API application first.

Go to https://api.slack.com/apps and click the `Create New App` button.
Give it a descriptive name like `CodeScene Notifications`, choose your slack workspace and click `Create App`.

.. figure:: slack-app-setup-1.png
   :alt: Slack application setup: Create the app
   :name: slack-app-setup-create-app

When the app is created go to the `OAuth & Permissions` tab in the left panel, navigate to the `Bot Token Scopes` section
and add the `chat:write` permission and `chat:write:public` (if you want to post a message to a channel your slack app isn't a member of).

.. figure:: slack-app-setup-2.png
   :alt: Slack application setup: Add OAuth scopes
   :name: slack-app-setup-oauth-scopes

   Slack application setup: Add OAuth scopes

If you have proper permissions, you can then `Install App to Workspace` at the top of the page.
Otherwise you need to ask your Slack admins for approval.

After a successful installation a new OAuth token is generated.
Copy and paste the token into the `Slack API token` field in the `Slack API Connection Settings` section.


Notifications Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

First fill in the **recipient**, that is the name of a channel (or a user) where the notifications should be sent.
Use `#channel-name`, e.g. `#codescene-notifications`.
If you want to send notifications to a specific user, then prepend `@` to the username, e.g. `@juraj.martinka` (for sending notifications to the slack user `juraj.martinka`).
The field can be empty if you only wish to receive notifications for specific projects.

Then select a set of events that trigger a notification.
Select all the events if you wish to get a notification on any analysis run or select a subset if you're only
interested in those specific events.
This will apply to all projects - if you want to receive notifications only for specific projects
then unselect all the options and override them in the project specific configuration.

Note: When an analysis produces results (such as alerts (Danger, Warning, Improvement) or non-recovarable error)
that matches some of the selected events you'll get a message containing all the generated information.
E.g. you may select to receive a notification only when a *Danger* alert is generated.
But when an analysis generates a Danger alert you may get other alerts (like warnings or improvements)
if they were generated as a result of the same analysis (see an example at the top of this page).

.. figure:: slack-notification-settings.png
   :alt: Slack notification settings - recipient and set of events
   :name: slack-notification-settings

   Slack notification settings - recipient and set of events

Once you have everything configured click `Save Slack Notifications Settings`.

You are now ready to run an analysis and recieve your first notification!


Per-project Configuration
-------------------------

You can choose to override the global notification settings for specific projects.

Go to project settings -> *Notifications* and click `Override Global Slack Notifications settings.`
Fill in the recipient, select set of events that should generate a notification for this specific project
and click `Save Slack Notifications settings`.


.. figure:: slack-notifications-project.png
   :alt: Slack notifications - per-project settings override global settings
   :name: slack-notifications-project

   Slack application setup: Add OAuth scopes

You must specify both recipient and a proper set of events if you want to receive the notifications.
E.g. if you leave recipient empty then the default recipient from the global configuration won't be used!
However, if you *don't override* the settings at all (the checkbox at the top is unchecked),
both recipient and set of events are taken from the global configuration.

You can also use these settings to "turn off" all the notifications if your CodeScene admin set the global configuration
such that all the projects receive notifications by default.
You simply choose "Override" and unselect all the notification events.


Delta Analysis Notifications
----------------------------

Since version 4.3.4, CodeScene can send Slack notifications when a delta analysis fails a quality gate
such as a goal violation or code health degradation. 

This notification is off by default and you can enable it in `Slack Notification Settings`:

.. figure:: slack-notifications-delta.png
   :alt: Slack notifications - delta failed quality gate
   :name: slack-notifications-delta      

   Slack notifications - delta failed quality gate

