Update Desk.com webhook integration.

Updates the HTML docs to match changes to the Desk.com website,
including all new screenshots for the custom action workflow.

Tests four types of messages that could be sent as notifications from
Desk.com. Desk.com allows an account administrator to send any text
in a custom action, so there isn't a standard format.

Custom actions send URL-encoded POST data, the test fixtures contain
URL-encoded text like what could be sent by a custom action configured
as described in the Zulip Integrations documentation to post a new
message to a stream. (See also #2169, errors in this documentation.)

New zerver.tests.webhooks.test_deskdotcom.DeskDotComHookTests:

* Static text: minimal plain text string
* Case updated: activity alert with link to a Desk.com case and message
* Unicode text Italian: activity alert with message in Italian
* Unicode text Japanese: activity alert with message in Japanese

Each posts a new message in the deskdotcom stream.

Tested on Ubuntu 14.04. I created the fixtures with Emacs, I would
appreciate if someone can check that the Italian and Japanese messages
look ok. I used the same text for a live test and it displayed correctly.

Fixes #2031

templates/zerver/integrations.html

@@ -515,26 +515,31 @@
       <ul>
           <li><b>Name</b>: Zulip</li>
           <li><b>Authentication Method</b>: Basic Auth</li>
-          <li><b>URL</b>: <code>{{ external_api_uri_subdomain }}/v1/external/desk</code></li>
+          <li><b>URL</b>: <code>{{ external_api_uri_subdomain }}/v1/external/deskdotcom</code></li>
           <li><b>User name</b>: <em>your bot's user name, e.g.</em> <code>desk-bot@yourdomain.com</code></li>
           <li><b>Password</b>: <em>your bot's API key</em></li>
       </ul>
 
       <img src="/static/images/integrations/desk/002.png" />
 
-      <p>From here, add a new action. You'll do this for every action you
-      want a notification on Zulip for:</p>
+      <p>Click Create to save your settings. From the next screen, click Add
+      Action add a new action. You'll do this for every action you want a
+      notification on Zulip for. (To add another action later, look for your
+      custom action on the Apps page under "Installed Apps."</p>
+
       <img src="/static/images/integrations/desk/003.png" />
 
       <p>Let's say you want a notification each time a case is updated. Put
-      in a descriptive name like "Announce case update", and copy-paste
-      this to the "Appended URL path":</p>
+      in a descriptive name like "Announce case update", select "POST a string to a URL"
+      for Action Type, and copy-paste this to the "Appended URL path":</p>
       {% raw %}
       <p><code>?stream=desk&amp;topic={{case.id}}:+{{case.subject}}</code></p>
       {% endraw %}
       <p>The "appended URL path" will be the same for every notification —
       it makes sure the notification goes to the appropriate stream and topic
-      within Zulip. Next, copy this template Zulip message into "Message to
+      within Zulip. </p>
+
+      <p>Next, copy this template Zulip message into "Message to
       POST":</p>
       {% raw %}
       <pre><code
@@ -545,33 +550,50 @@
 * Customer: {{customer.name}}
 * Company: {{customer.company}}
 * Description: {{case.description}}</code></pre>
-      <p>You don't need to edit that. All the funny-looking stuff inside
-      <code>{{</code> and <code>}}</code>
+      <p>You don't need to edit that, although you may if you wish. All
+      the funny-looking stuff inside <code>{{</code> and <code>}}</code>
       will be filled in by Desk.com for each event. The dialog should look
       like this:</p>
       {% endraw %}
+
       <img src="/static/images/integrations/desk/004.png" />
 
-      <p>Save it, and then click "On" next to the action to enable it. This
-      is important — actions are turned off by default!</p>
+      <p>Click Add Action to save, and then on the next screen click the slider
+      next to the action to enable it. This is important — actions are turned off
+      by default!</p>
+
+      <img src="/static/images/integrations/desk/005.png" />
 
       <p>Now you need to create a rule that triggers this action. Desk.com's
       support center has a
       <a href="https://support.desk.com/customer/portal/articles/1376">lengthy
           article on rules</a>, but in short, click on "Cases" up at the top,
       "Rules" on the left side, and then the specific event you want to notify
-      on — in our example, "Case Updated". Add a rule with a name like "Notify
-      Zulip of case update". Click on "Add Action", select "Trigger an App
-      Action", and select "Zulip: Announce case update". Set "Enabled" to
-      "Yes". The rule should look like this:</p>
-      <img src="/static/images/integrations/desk/005.png" />
+      on — in our example, "Inbound Interaction". </p>
+
+      <img src="/static/images/integrations/desk/006.png" />
+
+      <p>Select the types of interaction you want your rule to apply to,
+      such as Chat. Specify the name and click on "Add Rule."</p>
+
+      <img src="/static/images/integrations/desk/007.png" />
+
+      <p>In the next screen, provide the details. First, click Add Actions to
+      display the rule actions. Select "Trigger an App Action" in the dropdown, and
+      then the name of the custom action you created earlier when the the second
+      dropdown appears. You can add additional "All" or "Any" conditions if desired.
+      Also select when the rule should run (if not "Anytime") and enable it.</p>
+
+      <img src="/static/images/integrations/desk/008.png" />
 
       <p>Finally, click Update.</p>
 
       <p><b>Congratulations! You're done!</b><br /> When a case is updated,
       you'll see a notification like the following, to the stream
       <code>desk</code>, with a topic that matches the case's subject name:</p>
-      <img class="screenshot" src="/static/images/integrations/desk/006.png" />
+
+      <img class="screenshot" src="/static/images/integrations/desk/009.png" />
+
     </div>
 
 

zerver/fixtures/deskdotcom/deskdotcom_case_updated.txt

@@ -0,0 +1 @@
+stream=deskdotcom&topic=case%20updated%20notification&data=Case+2+updated.+Link%3A+%3Ca+href%3D%27https%3A%2F%2Fdeskdotcomtest.desk.com%2Fweb%2Fagent%2Fcase%2F2%27%3EI+have+a+question%3C%2Fa%3E

zerver/fixtures/deskdotcom/deskdotcom_static_text.txt

@@ -0,0 +1 @@
+stream=deskdotcom&topic=static%20text%20notification&data=This%20is%20a%20custom%20action.

zerver/fixtures/deskdotcom/deskdotcom_unicode_text_italian.txt

@@ -0,0 +1 @@
+stream=deskdotcom&topic=case%20updated%20notification&data=Case+2+updated.+Link%3A+%3Ca+href%3D%27https%3A%2F%2Fdeskdotcomtest.desk.com%2Fweb%2Fagent%2Fcase%2F2%27%3EIl+mio+hovercraft+è+pieno+di+anguille.%3C%2Fa%3E

zerver/fixtures/deskdotcom/deskdotcom_unicode_text_japanese.txt

@@ -0,0 +1 @@
+stream=deskdotcom&topic=case%20updated%20notification&data=Case+2+updated.+Link%3A+%3Ca+href%3D%27https%3A%2F%2Fdeskdotcomtest.desk.com%2Fweb%2Fagent%2Fcase%2F2%27%3E私のホバークラフトは鰻でいっぱいです%3C%2Fa%3E

zerver/tests/webhooks/test_deskdotcom.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+from six import text_type
+from zerver.lib.test_classes import WebhookTestCase
+
+# Tests for the Desk.com webhook integration.
+#
+# The stream name must be provided in the url-encoded test fixture data,
+# and must match STREAM_NAME set here.
+#
+# Example:
+#
+# stream=deskdotcom&topic=static%20text%20notification&data=This%20is%20a%20custom%20action.
+#
+
+class DeskDotComHookTests(WebhookTestCase):
+    STREAM_NAME = 'deskdotcom'
+    URL_TEMPLATE = "/api/v1/external/deskdotcom"
+    FIXTURE_DIR_NAME = 'deskdotcom'
+
+    def test_static_text_message(self):
+        # type: () -> None
+
+        expected_subject = u"static text notification";
+        expected_message = u"This is a custom action.\n";
+
+        self.send_and_test_stream_message('static_text', expected_subject, expected_message,
+                                          content_type="application/x-www-form-urlencoded",
+                                          **self.api_auth(self.TEST_USER_EMAIL))
+
+    def test_case_updated_message(self):
+        # type: () -> None
+        expected_subject = u"case updated notification";
+        expected_message = (u"Case 2 updated. "
+           u"Link: <a href='https://deskdotcomtest.desk.com/web/agent/case/2'>"
+           u"I have a question</a>\n")
+
+        self.send_and_test_stream_message('case_updated', expected_subject, expected_message,
+                                          content_type="application/x-www-form-urlencoded",
+                                          **self.api_auth(self.TEST_USER_EMAIL))
+
+    def test_unicode_text_italian(self):
+        # type: () -> None
+
+        expected_subject = u"case updated notification"
+        expected_message = (u"Case 2 updated. "
+            u"Link: <a href='https://deskdotcomtest.desk.com/web/agent/case/2'>"
+            u"Il mio hovercraft è pieno di anguille.</a>\n")
+
+        self.send_and_test_stream_message('unicode_text_italian', expected_subject, expected_message,
+                                          content_type="application/x-www-form-urlencoded",
+                                          **self.api_auth(self.TEST_USER_EMAIL))
+
+    def test_unicode_text_japanese(self):
+        # type: () -> None
+
+        expected_subject = u"case updated notification"
+        expected_message = (u"Case 2 updated. "
+            u"Link: <a href='https://deskdotcomtest.desk.com/web/agent/case/2'>"
+            u"私のホバークラフトは鰻でいっぱいです</a>\n")
+
+        self.send_and_test_stream_message('unicode_text_japanese', expected_subject, expected_message,
+                                          content_type="application/x-www-form-urlencoded",
+                                          **self.api_auth(self.TEST_USER_EMAIL))
+
+
+    def get_body(self, fixture_name):
+        # type: (text_type) -> text_type
+        return self.fixture_data("deskdotcom", fixture_name, file_type="txt")