HipChat Responder user guide - snowplow-archive/sauna GitHub Wiki

HOME > GUIDE FOR ANALYSTS > RESPONDERS > HIPCHAT RESPONDER USER GUIDE

This responder has not yet been implemented.

See also: HipChat Responder setup guide

• 1. Overview
• 2. Responder actions
  • 2.1 Send room notification (real-time)
    • 2.1.1 Overview
    • 2.1.2 Command format
    • 2.1.3 Example command
    • 2.1.4 Response algorithm
    • 2.1.5 Usage examples
      • 2.1.5.1 Kinesis stream

This responder lets you communicate with your colleagues or partners via the HipChat messaging platform.

Currently this responder only supports one action:

This responder command lets you send a notification to a room in HipChat. This responder command uses the HipChat API version 2.

Like all real-time responder actions, this action is triggered by a well-structured JSON command being received by a compatible observer.

The command must be configured using a self-describing JSON Schema which validates against this Schema:

iglu:com.hipchat.sauna.commands/send_room_notification/jsonschema/1-0-0

Here is an example command:

{
    "schema": "iglu:com.hipchat.sauna.commands/send_room_notification/jsonschema/1-0-0",

    "data": {
        "roomIdOrName": "Devops",
        "color": "YELLOW",
        "message": "HipChat is awesome!",
        "notify": true,
        "messageFormat": "TEXT"
    }
}

Where:

• roomIdOrName is the ID or URI-encoded name of the room
• color is the background color for the message
• message is the actual body or text of the message
• notify is whether this message should trigger a user notification, taking into account each recipient's notification preferences
• messageFormat is whether HipChat should treat the message as text or HTML

Sauna will take each command and:

1. Validate it as a valid send room notification command
2. If it is not valid, this will be reported to any configured Sauna loggers
3. If it is valid, Sauna will attempt to send the notification using the HipChat API version 2
4. If the API reports success, this will be reported to any configured Sauna loggers
5. If the API reports failure, this will be reported to any configured Sauna loggers but no retry will be attempted

In the case of failure, we do not attempt retry, even in the case of us temporarily exceeding API rate limits, because this could block other non-HipChat-related commands in the observed stream from executing.

Assuming that the Amazon Kinesis Observer receives the following command:

{
  "schema": "iglu:com.snowplowanalytics.sauna.commands/command/jsonschema/1-0-0",
  "data": {
    "envelope": {
      "schema": "iglu:com.snowplowanalytics.sauna.commands/envelope/jsonschema/1-0-0",
      "data": {
        "commandId": "9dadfc92-9311-43c7-9cee-61ab590a6e81",
        "whenCreated": "2017-01-02T19:14:42Z",
        "execution": {
          "semantics": "AT_LEAST_ONCE",
          "timeToLive": null
        },
        "tags": {}
      }
    },
    "command": {
      "schema": "iglu:com.hipchat.sauna.commands/send_room_notification/jsonschema/1-0-0",
      "data": {
        "roomIdOrName": "Devops",
        "color": "YELLOW",
        "message": "HipChat is awesome!",
        "notify": true,
        "messageFormat": "TEXT"
      }
    }
  }
}

And assuming that the current time is within 20 minutes (1,200,000 ms) of 2017-01-02T19:14:42Z, then:

• Sauna will ask HipChat to send a plaintext message "HipChat is awesome!" to its Devops chatroom, to be written against a yellow background and notifying all recipients
• Whether or not the notification was successfully sent by HipChat wil be reported to any configured Sauna loggers