diff --git a/templates/zephyr/api.html b/templates/zephyr/api.html index fbaf8d2399..f792d664bb 100644 --- a/templates/zephyr/api.html +++ b/templates/zephyr/api.html @@ -20,16 +20,21 @@

Installation instructions

This package uses distutils, so you can just run python setup.py install after downloading.

+

 

-

You can find your API key and allocate new API keys for - bots/integrations that you run on your settings page. - Create ~/.humbugrc and add the following text to - it:

+

API Keys

+

You can create bots on your settings page. + Once you have a bot, you can use its email and API key to send messages.

+

Create a bot:

+ +

Look for the bot's email and API key:

+ +

If you prefer to send messages as your own user, you can find your API key also on your settings page.

+

When using our python bindings, you must specify the user and API key. Alterantively, if you don't, it will look for these credentials in ~/.humbugrc, which you can create as follows:

[api]
-key=API_KEY
-email=EMAIL_ADDRESS
+key=BOT_API_KEY
+email=BOT_EMAIL_ADDRESS

Don't want to make it yourself? Humbug already integrates with lots of services.

@@ -56,7 +61,7 @@ to pull out the resulting HTML :)

Stream message

curl https://humbughq.com/api/v1/messages \
-    -u YOUR_EMAIL:YOUR_API_KEY \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
     -d "type=stream" \
     -d "to=Denmark" \
     -d "subject=Castle" \
@@ -65,7 +70,7 @@ to pull out the resulting HTML :)
 
 
Private message

 
curl https://humbughq.com/api/v1/messages \
-    -u YOUR_EMAIL:YOUR_API_KEY \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
     -d "type=private" \
     -d "to=wdaher@humbughq.com" \
     -d "content=I come not, friends, to steal away your hearts."
@@ -77,7 +82,9 @@ to pull out the resulting HTML :)
 
#!/usr/bin/env python
 
 import humbug
-client = humbug.Client()
+# Keyword arguments 'email' and 'api_key' are optional if you are using ~/.humbugrc
+client = humbug.Client(email="othello-bot@example.com",
+                       api_key="a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5")
 
 stream_message = {
     "type": "stream",
@@ -105,15 +112,19 @@ to pull out the resulting HTML :)
         
You can use humbug-send (found in bin/ in the tarball) to easily send Humbugs from the command-line, providing the message to be sent on STDIN.
 
 
Stream message

-
humbug-send --stream Denmark --subject Castle

+
humbug-send --stream Denmark --subject Castle \
+--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5

 
 
Private message

-
humbug-send wdaher@humbughq.com
+
humbug-send wdaher@humbughq.com --user othello-bot@example.com \
+--api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5
 

 
 
Passing in the message on the command-line

 
If you'd like, you can also provide the message on the command-line with the -m flag, as follows:

-
humbug-send --stream Denmark --subject Castle -m "Something is rotten in the state of Denmark."
+
humbug-send --stream Denmark --subject Castle \
+-m "Something is rotten in the state of Denmark." \
+--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5
 

 
       

diff --git a/templates/zephyr/api_content.json b/templates/zephyr/api_content.json
index 493ef9a957..6d6563900f 100644
--- a/templates/zephyr/api_content.json
+++ b/templates/zephyr/api_content.json
@@ -1,7 +1,7 @@
 [
     {
         "endpoint": "GET /v1/messages/latest", 
-        "example_response": "
{ \"messages\" : [ { \"client\" : \"website\",\n        \"content\" : \"hi\",\n        \"content_type\" : \"text/x-markdown\",\n        \"display_recipient\" : [ { \"email\" : \"wdaher@humbughq.com\",\n              \"full_name\" : \"Waseem Daher\",\n              \"short_name\" : \"wdaher\"\n            },\n            { \"email\" : \"othello@humbughq.com\",\n              \"full_name\" : \"Othello, Moor of Venice\",\n              \"short_name\" : \"othello\"\n            }\n          ],\n        \"gravatar_hash\" : \"948fcdfa93dd8986106032f1bad7f2c8\",\n        \"id\" : 400,\n        \"recipient_id\" : 101,\n        \"sender_email\" : \"othello@humbughq.com\",\n        \"sender_full_name\" : \"Othello, Moor of Venice\",\n        \"sender_short_name\" : \"othello\",\n        \"subject\" : \"\",\n        \"timestamp\" : 1365532669,\n        \"type\" : \"private\"\n      } ],\n  \"msg\" : \"\",\n  \"result\" : \"success\",\n  \"update_types\" : [ \"new_messages\" ]\n}\n
", 
+        "example_response": "
{ \"messages\" : [ { \"client\" : \"website\",\n        \"content\" : \"hi\",\n        \"content_type\" : \"text/x-markdown\",\n        \"display_recipient\" : [ { \"email\" : \"wdaher@humbughq.com\",\n              \"full_name\" : \"Waseem Daher\",\n              \"short_name\" : \"wdaher\"\n            },\n            { \"email\" : \"othello-bot@humbughq.com\",\n              \"full_name\" : \"Othello, Moor of Venice\",\n              \"short_name\" : \"othello-bot\"\n            }\n          ],\n        \"gravatar_hash\" : \"948fcdfa93dd8986106032f1bad7f2c8\",\n        \"id\" : 400,\n        \"recipient_id\" : 101,\n        \"sender_email\" : \"othello-bot@humbughq.com\",\n        \"sender_full_name\" : \"Othello, Moor of Venice\",\n        \"sender_short_name\" : \"othello-bot\",\n        \"subject\" : \"\",\n        \"timestamp\" : 1365532669,\n        \"type\" : \"private\"\n      } ],\n  \"msg\" : \"\",\n  \"result\" : \"success\",\n  \"update_types\" : [ \"new_messages\" ]\n}\n
",
         "returns": [
             [
                 "messages", 
@@ -21,7 +21,7 @@
         ], 
         "example_request": {
             "python": "
client.get_messages()\n
", 
-            "curl": "
curl -G http://api.humbughq.com/v1/messages \\\n -u you@example.com:a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \\\n -d \"last=102345\"\n
"
+            "curl": "
curl -G http://api.humbughq.com/v1/messages \\\n -u othello-bot@example.com:a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \\\n -d \"last=102345\"\n
"
         }
     }, 
     {
@@ -54,7 +54,7 @@
         ], 
         "example_request": {
             "python": "
\nclient.send_message({\n    \"type\": \"private\",\n    \"to\": \"wdaher@humbughq.com\",\n    \"content\": \"I come not, friends, to steal away your hearts.\"\n})\nclient.send_message({\n    \"type\": \"stream\",\n    \"to\": \"Denmark\",\n    \"subject\": \"Castle\",\n    \"content\": \"Something is rotten in the state of Denmark.\"\n})\n
\n", 
-            "curl": "
Stream message
\n
curl https://humbughq.com/api/v1/messages \\\n    -u YOUR_EMAIL:YOUR_API_KEY \\\n    -d \"type=stream\" \\\n    -d \"to=Denmark\" \\\n    -d \"subject=Castle\" \\\n    -d \"content=Something is rotten in the state of Denmark.\"\n
\n
Private message
\n
curl https://humbughq.com/api/v1/messages \\\n    -u YOUR_EMAIL:YOUR_API_KEY \\\n    -d \"type=private\" \\\n    -d \"to=wdaher@humbughq.com\" \\\n    -d \"content=I come not, friends, to steal away your hearts.\"\n
"
+            "curl": "
Stream message
\n
curl https://humbughq.com/api/v1/messages \\\n    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \\\n    -d \"type=stream\" \\\n    -d \"to=Denmark\" \\\n    -d \"subject=Castle\" \\\n    -d \"content=Something is rotten in the state of Denmark.\"\n
\n
Private message
\n
curl https://humbughq.com/api/v1/messages \\\n    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \\\n    -d \"type=private\" \\\n    -d \"to=wdaher@humbughq.com\" \\\n    -d \"content=I come not, friends, to steal away your hearts.\"\n
"
         }
     }
 ]
\ No newline at end of file
diff --git a/templates/zephyr/integrations.html b/templates/zephyr/integrations.html
index 9ff3e74d1c..1052f32d32 100644
--- a/templates/zephyr/integrations.html
+++ b/templates/zephyr/integrations.html
@@ -22,14 +22,19 @@
     for thee! (Or for a team member of yours, I guess.)

 
     
Getting started

+    
Many of these integrations are available in
+    our API bindinds. You may either send messages as
+    yourself or use a bot which you can create. Both options are managed at your
+    settings page.

 
-    
First, for most integrations you'll need
-    to download and install our API bindings on the
-    machine where the service runs.

+    
Create a bot:
+    

 
-    
Next, please visit your settings page and
-    create a Humbug bot for the integration you are setting
-    up. Each bot gets its own name and API key.

+    
Look for the bot's email and API key:
+    

+
+    
You might want to take this moment to ensure that this bot's
+    email address exists on your company's email server.

 
     
Then, follow the integration instructions below for the service
     you are interested in. It's as easy as that! If you run into any
@@ -60,10 +65,10 @@
     

       
Beanstalk

      
Humbug supports both SVN and Git notifications from Beanstalk. In the beanstalk web application, go to the Setup page, and choose the Integrations tab.
-     Choose the Webhooks integration from the list presented. Make sure to replace the @ in your email address with %40,
+     Choose the Webhooks integration from the list presented. Make sure to replace the @ in the bot's email address with %40,
      as Beanstalk's website will incorrectly refuse to parse a username containing a @.

 
-     
In the URL field, enter https://email:api_key@humbughq.com/api/v1/external/beanstalk:

+     
In the URL field, enter https://bot_email:bot_api_key@humbughq.com/api/v1/external/beanstalk:

       
 
       
Congratulations! You're done!
 Whenever you do a
@@ -89,17 +94,19 @@
 namespace :notify do
   desc "Post a message to Humbug that we've deployed"
   task :humbug do
-    # this will post to Humbug as the user defined in ~/.humbugrc
-    run_locally "echo ':beers: I just deployed to #{stage}! :beers:' | humbug-send --stream commits --subject deployments || true"
+    # this will post to Humbug as the user defined in
+    # ~/.humbugrc if you omit --user and --api-key
+    run_locally "echo ':beers: I just deployed to #{stage}! :beers:' | humbug-send \
+    --user capistrano-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
+    --stream commits --subject deployments || true"
   end
 end
 

 
       
Some notes:

       
    
-        
  • Make sure you've created a
-      filled-out ~/.humbugrc on your Capistrano
-      machine.
    • 
+        
  • If you prefer to not use --user and --api-key above, you can fill out ~/.humbugrc on your Capistrano
+      machine. For instructions on how to write that file, see the API page.
    • 
         
  • You may need to change the deploy above to
         another step of your deployment process, if you'd like the
         notification to fire at a different time.
    • 
@@ -127,7 +134,7 @@
       specify the email address and API key for your Git bot:
    
 
 
-
    HUMBUG_USER = "git@example.com"
+
    HUMBUG_USER = "git-bot@example.com"
 HUMBUG_API_KEY = "0123456789abcdef0123456789abcdef"
    
 
       
    You can also specify which pushes will result in
@@ -287,7 +294,7 @@ following, to the stream commits with a subject that matches the re
         For self-contained JIRA installations, this will be atlassian-jira/WEB-INF/classes/, but this may be different in your deployment.
    
         Edit the constants at the top of org/humbug/jira/HumbugListener.groovy
         and fill them with the appropriate values:
-
    String humbugEmail = "jira-notifications@example.com"
+
    String humbugEmail = "jira-notifications-bot@example.com"
 String humbugAPIKey = "0123456789abcdef0123456789abcdef"
 String humbugStream = "JIRA"
 String issueBaseUrl = "https://jira.COMPANY.com/browse/"
@@ -318,8 +325,8 @@ following, to the stream commits with a subject that matches the re
       server:
    
 
 
    [api]
-email=NAGIOS_EMAIL_ADDRESS
-key=NAGIOS_API_KEY
+email=NAGIOS_BOT_EMAIL_ADDRESS
+key=NAGIOS_BOT_API_KEY
 
    
 
       
    Copy integrations/nagios/humbug_nagios.cfg
@@ -438,7 +445,7 @@ key=NAGIOS_API_KEY
       notification messages to go (by default,
       stream trac):
    
 
-
    HUMBUG_USER = "trac-notifications@example.com"
+
    HUMBUG_USER = "trac-notifications-bot@example.com"
 HUMBUG_API_KEY = "0123456789abcdef0123456789abcdef"
 STREAM_FOR_NOTIFICATIONS = "trac"
 TRAC_BASE_TICKET_URL = "https://trac.example.com/ticket"
    
diff --git a/zephyr/static/images/api/bot-key.png b/zephyr/static/images/api/bot-key.png
new file mode 100644
index 0000000000..1d3daa6156
Binary files /dev/null and b/zephyr/static/images/api/bot-key.png differ
diff --git a/zephyr/static/images/api/create-bot.png b/zephyr/static/images/api/create-bot.png
new file mode 100644
index 0000000000..48601e4518
Binary files /dev/null and b/zephyr/static/images/api/create-bot.png differ