[[actions-slack]]
==== Slack Action

A watch <<actions, action>> that can connect to a https://slack.com/[Slack] server and send
messages to users and/or channels of a specific team.


[[configuring-slack-actions]]
===== Configuring Slack Actions

You configure slack actions in a watch's `actions` array. Action-specific attributes are
specified using the `slack` keyword.

The following snippet shows a simple slack action definition:

[source,json]
--------------------------------------------------
"actions" : {
  "notify-slack" : { <1>
    "transform" : { ... }, <2>
    "throttle_period" : "5m", <3>
    "slack" : {
      "to" : [ "#admins", "@chief-admin" ], <4>
      "message" : {
        "text" : "Encountered  {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)" <5>
      }
    }
  }
}
--------------------------------------------------

<1> The id of the action
<2> An optional <<transform, transform>> to transform the payload before executing the `webhook` action
<3> An optional <<actions-ack-throttle, throttle period>> for the action (5 minutes in this example)
<4> The users and/or channels where the message is sent to
<5> The content of the message.

Before using the `slack` action in a watch, Watcher's internal Slack service needs to be configured. This
Service enable the configuration of multiple slack accounts. A Slack Account defines the following:

* `name` -              (required) uniquely identifies the account. Slack actions may specify the name of the account with which
                        the messages should be sent.
* `url` -               (required) the incoming webhook URL provided by slack
* `message_defaults` -  (optional) a set of settings to define the default settings of the messages that are sent via this account

Here's an example settings for Slack service:

[source,yaml]
--------------------------------------------------
watcher.actions.slack.service:
  default_account: team1
  account:
    team1:
      url: https://hooks.slack.com/services/XXXXXXX/XXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXX
      message_default:
        from: watcher
    team2:
      url: https://hooks.slack.com/services/YYYYYYY/YYYYYYYY/YYYYYYYYYYYYYYYYYYYYYYY
      message_default:
        from: watcher
--------------------------------------------------

[[configuring-slack-messages]]
===== Configuring Slack Messages

Slack provides powerful notification API that enables sending reach messages to the users and channels. The
following table describes the different attributes that can be used when configuring the messages in the action.

[[slack-message-attributes]]
.Slack Message Attributes
[options="header"]
|======
| Name                    |Required   | Default         | Description
| `from`                  | no        | the watch id    | The name that will appear as the sender of the notification
| `to`                    | yes       | -               | The channels/s and/or user/s that the notification should go to.
                                                          Channel names must start with a `#` and user names must start with `@`.
| `icon`                  | no        | -               | An icon can be associated with the message (accepts publicly available URL to the icon)
| `text`                  | yes       | -               | The main text/content of the message.
| `attachments`           | no        | -               | Enables creating rich formatted sections in the message. The syntax for attachments
                                                          follows the syntax as defined by the slack APIs. You can read more about attachments
                                                          and their definition syntax https://api.slack.com/docs/attachments[here].
| `dynamic_attachments`   | no        | -               | define an attachment template that enables adding attachments dynamically based
                                                          on the current payload (see bellow).
|======

Here is an example for how it looks like as part of the action definition:

[source,json]
--------------------------------------------------
"actions" : {
  "notify-slack" : {
    "throttle_period" : "5m",
    "slack" : {
      "account" : "team1",
      "message" : {
        "from" : "watcher",
        "to" : [ "#admins", "@chief-admin" ],
        "text" : "System X Monitoring",
        "attachments" : [
          {
            "title" : "Errors Found",
            "text" : "Encountered  {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)",
            "color" : "danger"
          }
        ]
      }
    }
  }
}
--------------------------------------------------

[[slack-dynamic-attachment]]
.Dynamic Attachments

As shown in the previous section, the "attachments" array in the slack message enables sending rich formatted messages
to channels and users. Each attachment has its own formatting, and multiple of those can belong to a single message.

Dynamic attachments enables creating these message attachments dynamically based on the current watch payload. For example,
if the watch input executes a search with date histogram aggregation, dynamic attachments can reference the histogram
buckets in the payload and build and attachment per bucket. For example,

[source,json]
--------------------------------------------------
"input" : {
  "search" : {
    "request" : {
      "body" : {
        "aggs" : {
          "users_per_month" : {
            "date_histogram" : {
              "field" : "@timestamp",
              "interval" : "1m"
            }
          }
        }
      }
    }
  }
},
...
"actions" : {
  "notify-slack" : {
    "throttle_period" : "5m",
    "transform" : { <1>
      "script" : "return [ items : ctx.payload.hits.aggs.users_per_month.buckets.collect { [ month : it.key_as_string, count : it.doc_count, color : it.doc_count < 100 ? 'danger' : 'good' ] }]"
    },
    "slack" : {
      "account" : "team1",
      "message" : {
        "from" : "watcher",
        "to" : [ "#admins", "@chief-admin" ],
        "text" : "System X Monitoring",
        "dynamic_attachments" : {
          "list_path" : "ctx.payload.items"
          "attachement_template" : {
            "title" : "{{month}}", <2>
            "text" : "Users Count: {{count}}",
            "color" : "{{color}}"
          }
        }
      }
    }
  }
}
--------------------------------------------------

<1> Transforms the payload to a list where each item in the list holds the month, user count for that month, and the color
    representing the sentiment with that count (good or bad/danger)
<2> The parameter place holders refer to attributes in each item of the list above.