232 lines
10 KiB
Plaintext
232 lines
10 KiB
Plaintext
|
[[configuring-hipchat]]
|
||
|
=== Configuring Watcher to Send Messages to HipChat
|
||
|
|
||
|
You can configure Watcher to use the HipChat APIs to send messages to HipChat rooms and users.
|
||
|
Watcher supports both the HipChat v2 and v1 APIs.
|
||
|
|
||
|
[[hipchat-account]]
|
||
|
==== Configuring HipChat Accounts
|
||
|
You configure the accounts Watcher can use to communicate with HipChat in your `elasticsearch.yml`
|
||
|
configuration file. Each account configuration has a unique name and specifies a HipChat API profile
|
||
|
and the authentication information needed to access the APIs. You can also specify message defaults,
|
||
|
such the default message text and color.
|
||
|
|
||
|
Watcher provides three HipChat API profiles:
|
||
|
|
||
|
<<hipchat-api-integration,integration>> :: Sends messages to a specific room using HipChat's
|
||
|
v2 API https://www.hipchat.com/docs/apiv2/method/send_room_notification[Send room notification].
|
||
|
<<hipchat-api-user, user>> :: Sends messages as a particular user through the HipChat v2 API.
|
||
|
Enables you to send messages to arbitrary rooms or users.
|
||
|
<<hipchat-api-v1, v1>> :: Sends messages to rooms using HipChat's v1 API
|
||
|
https://www.hipchat.com/docs/api/method/rooms/message[rooms/message].
|
||
|
|
||
|
NOTE: The `v1` profile is provided because it is simple to set up and the HipChat v1 API is familiar
|
||
|
to many users. However, HipChat has deprecated the v1 API and is encouraging users to migrate to
|
||
|
v2. Both the `integration` and `user` profiles are based on the HipChat v2 API.
|
||
|
|
||
|
If you configure multiple HipChat accounts, you either need to configure a default HipChat account
|
||
|
or specify which account the notification should be sent with in the <<actions-hipchat, hipchat>>
|
||
|
action. You set `default_account` in `watcher.actions.hipchat.service` to specify a default account.
|
||
|
|
||
|
To configure HipChat accounts, set the `watcher.actions.hipchat.service` property in
|
||
|
`elasticsearch.yml`. For example:
|
||
|
|
||
|
[source,yaml]
|
||
|
--------------------------------------------------
|
||
|
watcher.actions.hipchat.service:
|
||
|
default_account: hipchat-account1
|
||
|
account:
|
||
|
hipchat-account1:
|
||
|
profile: v1
|
||
|
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
|
||
|
message_defaults:
|
||
|
color: purple
|
||
|
format: text
|
||
|
hipchat-account2:
|
||
|
profile: integration
|
||
|
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
|
||
|
room: mission-control
|
||
|
message_defaults:
|
||
|
color: gray
|
||
|
format: text
|
||
|
--------------------------------------------------
|
||
|
|
||
|
See the following sections information about using each profile type.
|
||
|
|
||
|
[[hipchat-api-integration]]
|
||
|
===== Using the HipChat Integration Profile
|
||
|
|
||
|
You can use the `integration` profile to send messages to specific rooms. When you set an
|
||
|
account's profile to `integration`, Watcher sends the messages through HipChat's v2
|
||
|
https://www.hipchat.com/docs/apiv2/method/send_room_notification[Send room notification] API.
|
||
|
|
||
|
When you use the `integration` profile, you need to configure a separate HipChat account in
|
||
|
Watcher for each room you want to send messages--the account configuration contains a
|
||
|
room-specific authentication token. Alternatively, you can use the <<hipchat-api-user, `user`>>
|
||
|
or <<hipchat-api-v1, `v1`>> profile to send messages to multiple rooms.
|
||
|
|
||
|
NOTE: The `integration` profile only supports sending messages to rooms, it does not
|
||
|
support sending private messages. To notify a particular HipChat user, create an account
|
||
|
that uses the <<hipchat-api-user, `user`>> profile.
|
||
|
|
||
|
Before you can configure an account that uses the `integration` profile, you need to generate a
|
||
|
room-specific authentication token through the HipChat admin console:
|
||
|
|
||
|
. Log in to http://hipchat.com[hipchat.com] or your HipChat server as a group administrator.
|
||
|
. Go to *Group admin > Rooms*.
|
||
|
. Click the name of the room you want to send messages to.
|
||
|
. Click the *Tokens* link.
|
||
|
. Enter a name for the token in the *Label* field.
|
||
|
+
|
||
|
image::images/hipchat-generate-room-token.jpg[]
|
||
|
. Select the *Send Notification* scope.
|
||
|
. Click *Create*.
|
||
|
. Copy the generated token so you can paste it into your HipChat account configuration in
|
||
|
`elasticsearch.yml`.
|
||
|
+
|
||
|
image::images/hipchat-copy-room-token.jpg[]
|
||
|
|
||
|
To configure a HipChat account that uses the `integration` profile, you must:
|
||
|
|
||
|
. Set the `type` to `integration`.
|
||
|
. Set `room` to the name of the room you want to send messages to.
|
||
|
. Set `auth_token` to the room-specific authentication token.
|
||
|
|
||
|
For example, the following snippet configures an account called `notify-monitoring` that
|
||
|
sends messages to the `monitoring` room.
|
||
|
|
||
|
[source,yaml]
|
||
|
--------------------------------------------------
|
||
|
watcher.actions.hipchat.service:
|
||
|
account:
|
||
|
notify-monitoring:
|
||
|
profile: integration
|
||
|
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
|
||
|
room: monitoring
|
||
|
--------------------------------------------------
|
||
|
|
||
|
You can also specify defaults for the notification messages. For the complete list of attributes,
|
||
|
see <<hipchat-account-attributes, HipChat Account Attributes>>.
|
||
|
|
||
|
[[hipchat-api-user]]
|
||
|
===== Using the HipChat User Profile
|
||
|
|
||
|
You can use the `user` profile to send messages to rooms as well as individual HipChat users.
|
||
|
When you set an account's profile to `user`, Watcher sends messages as a particular user
|
||
|
through the HipChat v2 API.
|
||
|
|
||
|
Before you can configure an account that uses the `user` profile, you need to:
|
||
|
|
||
|
. Add a HipChat user for Watcher. Watcher sends messages via this HipChat user account, so
|
||
|
keep that in mind when setting the user name.
|
||
|
. Create an API token for the Watcher user:
|
||
|
.. Log in to HipChat as the Watcher user.
|
||
|
.. Go to `https://<hipchat-server>/account/api`. For example, `https://www.hipchat.com/account/api`.
|
||
|
.. Confirm the user password.
|
||
|
.. Enter a name for the token in the *Label* field.
|
||
|
+
|
||
|
image::images/hipchat-generate-user-token.jpg[]
|
||
|
. Select the *Send Notification* and *Send Message* scopes.
|
||
|
. Click *Create*.
|
||
|
. Copy the generated token so you can paste it into your HipChat account configuration in
|
||
|
`elasticsearch.yml`.
|
||
|
+
|
||
|
image::images/hipchat-copy-room-token.jpg[]
|
||
|
|
||
|
To configure a HipChat account that uses the `user` profile, you must:
|
||
|
|
||
|
. Set the `type` to `user`.
|
||
|
. Set `user` to the email address associated with the Watcher user.
|
||
|
. Set `auth_token` to the Watcher user's authentication token.
|
||
|
|
||
|
For example, the following snippet configures an account called `notify-monitoring` that
|
||
|
sends messages to the `monitoring` room.
|
||
|
|
||
|
[source,yaml]
|
||
|
--------------------------------------------------
|
||
|
watcher.actions.hipchat.service:
|
||
|
account:
|
||
|
notify-monitoring:
|
||
|
profile: user
|
||
|
user: watcher-user@example.com
|
||
|
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
|
||
|
--------------------------------------------------
|
||
|
|
||
|
You can also specify defaults for the notification messages. For the complete list of attributes,
|
||
|
see <<hipchat-account-attributes, HipChat Account Attributes>>.
|
||
|
|
||
|
[[hipchat-api-v1]]
|
||
|
===== Using the HipChat v1 Profile
|
||
|
|
||
|
You can use the `v1` profile to send messages to particular rooms.
|
||
|
When you set an account's profile to `v1`, Watcher sends the messages through HipChat's v1
|
||
|
https://www.hipchat.com/docs/api/method/rooms/message[rooms/message] API.
|
||
|
|
||
|
WARNING: The `v1` profile uses a deprecated API that is expected to be removed by HipChat in the
|
||
|
future.
|
||
|
|
||
|
The `v1` profile only supports sending messages to rooms, it does not
|
||
|
support sending private messages. To notify a particular HipChat user, create an account
|
||
|
that uses the <<hipchat-api-user, `user`>> profile.
|
||
|
|
||
|
Before you can configure an account that uses the `v1` profile, you need to generate a `v1` API
|
||
|
token:
|
||
|
|
||
|
. Log in to your HipChat server as a group admin.
|
||
|
. Go to `https://<hipchat-server>/admin/api`. For example, `https://hipchat.com/admin/api`.
|
||
|
. Confirm your admin password.
|
||
|
. Select the *Notification* type.
|
||
|
+
|
||
|
image::images/hipchat-generate-v1-token.jpg[]
|
||
|
. Enter a name for the token in the *Label* field.
|
||
|
. Click *Create*.
|
||
|
. Copy the generated token so you can paste it into your HipChat account configuration in
|
||
|
`elasticsearch.yml`.
|
||
|
+
|
||
|
image::images/hipchat-copy-v1-token.jpg[]
|
||
|
|
||
|
To configure a HipChat account that uses the `user` profile, you simply:
|
||
|
|
||
|
. Set the `type` to `v1`.
|
||
|
. Set `auth_token` to the v1 authentication token you generated.
|
||
|
|
||
|
For example, the following snippet configures an account called `notify-monitoring`:
|
||
|
|
||
|
[source,yaml]
|
||
|
--------------------------------------------------
|
||
|
watcher.actions.hipchat.service:
|
||
|
account:
|
||
|
notify-monitoring:
|
||
|
profile: v1
|
||
|
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
|
||
|
--------------------------------------------------
|
||
|
|
||
|
You can also specify defaults for the notification messages. For the complete list of attributes,
|
||
|
see <<hipchat-account-attributes, HipChat Account Attributes>>.
|
||
|
|
||
|
[[hipchat-account-attributes]]
|
||
|
==== HipChat Account Attributes
|
||
|
|
||
|
|======
|
||
|
| Name |Required | Default | Description
|
||
|
| `profile` | yes | - | The HipChat account profile to use:
|
||
|
`integration`, `user`, or `v1`.
|
||
|
| `auth_token` | yes | - | The authentiation token to use to access
|
||
|
the HipChat API.
|
||
|
| `host` | no | api.hipchat.com | The HipChat server hostname.
|
||
|
| `port` | no | 443 | The HipChat server port number.
|
||
|
| `room` | no | _ | The room you want to send messages to.
|
||
|
Must be specified if the `profile` is set
|
||
|
to `integration`. Not valid for the
|
||
|
`user` or `vi` profiles.
|
||
|
| `user ` | no | - | The HipChat user account to use to send
|
||
|
messages. Specified as an email
|
||
|
address. Must be specified if the
|
||
|
`profile` is set to `user`. Not valid for
|
||
|
the `integration` or `v1` profiles.
|
||
|
| `message.format` | no | `html` | The format of the message: `text` or `html`.
|
||
|
| `message.color` | no | `yellow` | The background color of the notification in
|
||
|
the room
|
||
|
| `message.notify` | no | `false` | Indicates whether people in the room should be
|
||
|
actively notified
|
||
|
|======
|