Update HipChat README and minor fixes to plugin

plugins/hipchat/README.md

@@ -1,35 +1,61 @@
 HipChat Plugin
-================
+==============
 
 Send HipChat messages for new alerts.
 
-If you have jinja2 installed you can customize the message sent.
+If you have the Python Jinja2 package installed you can customize the
+HipChat message format.
+
+For help, join [![Gitter chat](https://badges.gitter.im/alerta/chat.png)](https://gitter.im/alerta/chat)
 
 Installation
 ------------
 
+Clone the GitHub repo and run:
+
     $ python setup.py install
 
+Or, to install remotely from GitHub run:
+
+    $ pip install git+https://github.com/alerta/alerta-contrib.git#subdirectory=plugins/hipchat
+
+Note: If Alerta is installed in a python virtual environment then plugins
+need to be installed into the same environment for Alerta to dynamically
+discover them.
 
 Configuration
 -------------
 
-```
-HIPCHAT_ROOM = '123456'
-HIPCHAT_API_KEY =  'xzxzxzxzxzxzxxzxzxzzx'
-```
+Add `hipchat` to the list of enabled `PLUGINS` in `alertad.conf` server
+configuration file and set plugin-specific variables either in the
+server configuration file or as environment variables.
 
-If you have jinja2 available you can try customizing the message like this:
-```
-HIPCHAT_ROOM = '123456'
-HIPCHAT_API_KEY =  'xzxzxzxzxzxzxxzxzxzzx'
-HIPCHAT_SUMMARY_FMT = '<b>[{{ alert.status|capitalize }}]</b> [{{ alert.severity|upper }}] Event {{ alert.event }} on <b>{{ alert.resource }}</b> <a href="{{ config.DASHBOARD_URL }}/#/alert/{{ alert.id }}">{{ alert.id[:8] }}</a>'
+```python
+PLUGINS = ['hipchat']
+HIPCHAT_ROOM = 'alerts'
+HIPCHAT_API_KEY =  'W4Dll5plS0qrqXCpPwjwzF9pO2TJI2Oou9Xaq8je'
 DASHBOARD_URL = 'http://try.alerta.io'
 ```
 
-The HIPCHAT_SUMMARY_FMT is a jinja2 template string and accepts any jinja2 syntax. You have 2 variables in the environment, 'alert' for all alert details and 'config' for access to the alerta configuration.
+The `HIPCHAT_SUMMARY_FMT` configuration variable is a Jinja2 template
+string and accepts any Jinja2 syntax. The formatter has access to two
+variables in the template environment, 'alert' for all alert details
+and 'config' for access to the alerta configuration.
+
+If you have Jinja2 available you can try customizing the message like
+this:
+
+```python
+HIPCHAT_SUMMARY_FMT = '<b>[{{ alert.status|capitalize }}]</b> [{{ alert.severity|upper }}] Event {{ alert.event }} on <b>{{ alert.resource }}</b> <a href="{{ config.DASHBOARD_URL }}/#/alert/{{ alert.id }}">{{ alert.id[:8] }}</a>'
+```
 
 References
 ----------
 
-HipChat room notification API: https://www.hipchat.com/docs/apiv2/method/send_room_notification
+  * HipChat room notification API: https://www.hipchat.com/docs/apiv2/method/send_room_notification
+  * Jinja2 templating language for Python: http://jinja.pocoo.org/docs/dev/
+
+License
+-------
+
+Copyright (c) 2016 Nick Satterly. Available under the MIT License.

plugins/hipchat/alerta_hipchat.py

@@ -12,15 +12,13 @@ LOG = logging.getLogger('alerta.plugins.hipchat')
 HIPCHAT_URL = 'https://api.hipchat.com/v2'
 HIPCHAT_ROOM = os.environ.get('HIPCHAT_ROOM') or app.config['HIPCHAT_ROOM']  # Room Name or Room API ID
 HIPCHAT_API_KEY = os.environ.get('HIPCHAT_API_KEY') or app.config['HIPCHAT_API_KEY']  # Room Notification Token
-
-HIPCHAT_SUMMARY_TEMPLATE = None
 HIPCHAT_SUMMARY_FMT = os.environ.get('HIPCHAT_SUMMARY_FMT') or app.config.get('HIPCHAT_SUMMARY_FMT', None)  # Message summary format
-if HIPCHAT_SUMMARY_FMT:
-    try:
-        from jinja2 import Template
-        HIPCHAT_SUMMARY_TEMPLATE = Template(HIPCHAT_SUMMARY_FMT)
-    except Exception as e:
-        LOG.error('Jinja template error: {}, template functionality will be unavailable'.format(e))
+DASHBOARD_URL = os.environ.get('DASHBOARD_URL') or app.config.get('DASHBOARD_URL', '')
+
+try:
+    from jinja2 import Template
+except Exception as e:
+    LOG.error('HipChat: ERROR - Jinja template error: %s, template functionality will be unavailable', e)
 
 
 class SendRoomNotification(PluginBase):
@@ -33,23 +31,33 @@ class SendRoomNotification(PluginBase):
         if alert.repeat:
             return
 
-        url = '%s/room/%s/notification' % (HIPCHAT_URL, HIPCHAT_ROOM)
+        if HIPCHAT_SUMMARY_FMT:
+            try:
+                template = Template(HIPCHAT_SUMMARY_FMT)
+            except Exception as e:
+                LOG.error('HipChat: ERROR - Template init failed: %s', e)
+                return
 
-        summary = None
-        if HIPCHAT_SUMMARY_TEMPLATE:
             try:
                 template_vars = {
                     'alert': alert,
                     'config': app.config
                 }
-                summary = HIPCHAT_SUMMARY_TEMPLATE.render(**template_vars)
+                summary = template.render(**template_vars)
             except Exception as e:
-                LOG.error('Summary template rendering error: {}'.format(e))
-
-        if not summary:
-            summary = "<b>[%s] %s %s - <i>%s on %s</i></b> <a href=\"http://try.alerta.io/#/alert/%s\">%s</a>" % (
-                alert.status.capitalize(), alert.environment, alert.severity.capitalize(), alert.event, alert.resource,
-                alert.id, alert.get_id(short=True)
+                LOG.error('HipChat: ERROR - Template render failed: %s', e)
+                return
+        else:
+            summary = ('<b>[{status}] {environment} {service} {severity} - <i>{event} on {resource}</i></b> <a href="{dashboard}/#/alert/{alert_id}">{short_id}</a>').format(
+                status=alert.status.capitalize(),
+                environment=alert.environment.upper(),
+                service=','.join(alert.service),
+                severity=alert.severity.capitalize(),
+                event=alert.event,
+                resource=alert.resource,
+                alert_id=alert.id,
+                short_id=alert.get_id(short=True),
+                dashboard=DASHBOARD_URL
             )
 
         if alert.severity == 'critical':
@@ -69,21 +77,21 @@ class SendRoomNotification(PluginBase):
             "notify": True,
             "message_format": "html"
         }
-
         LOG.debug('HipChat payload: %s', payload)
 
+        url = '%s/room/%s/notification' % (HIPCHAT_URL, HIPCHAT_ROOM)
         headers = {
             'Authorization': 'Bearer ' + HIPCHAT_API_KEY,
             'Content-type': 'application/json'
         }
 
-        LOG.debug('HipChat sending notification to %s', url)
+        LOG.debug('HipChat: Notification sent to %s', url)
         try:
             r = requests.post(url, data=json.dumps(payload), headers=headers, timeout=2)
         except Exception as e:
-            raise RuntimeError("HipChat connection error: %s", e)
+            raise RuntimeError("HipChat: ERROR - %s", e)
 
-        LOG.debug('HipChat response: %s - %s', r.status_code, r.text)
+        LOG.debug('HipChat: %s - %s', r.status_code, r.text)
 
     def status_change(self, alert, status, text):
         return

plugins/hipchat/setup.py

@@ -1,7 +1,7 @@
 
 from setuptools import setup, find_packages
 
-version = '0.3.1'
+version = '0.3.2'
 
 setup(
     name="alerta-hipchat",
@@ -14,7 +14,8 @@ setup(
     packages=find_packages(),
     py_modules=['alerta_hipchat'],
     install_requires=[
-        'requests'
+        'requests',
+        'jinja2'
     ],
     include_package_data=True,
     zip_safe=True,