integrations: Add ClickUp integration.

Creates an incoming webhook integration for ClickUp.
The main use case is getting notifications when new ClickUp
items such as task, list, folder, space, goals are created,
updated or deleted.

Fixes zulip#26529.

zerver/lib/integrations.py

@@ -384,6 +384,23 @@ def __init__(self, name: str, *args: Any, **kwargs: Any) -> None:
     WebhookIntegration("buildbot", ["continuous-integration"]),
     WebhookIntegration("canarytoken", ["monitoring"], display_name="Thinkst Canarytokens"),
     WebhookIntegration("circleci", ["continuous-integration"], display_name="CircleCI"),
+    WebhookIntegration(
+        "clickup",
+        ["project-management"],
+        display_name="ClickUp",
+        config_options=[
+            WebhookConfigOption(
+                name="clickup_api_key",
+                description="Your ClickUp API key",
+                validator=check_string,
+            ),
+            WebhookConfigOption(
+                name="team_id",
+                description="Your ClickUp team id",
+                validator=check_string,
+            ),
+        ],
+    ),
     WebhookIntegration("clubhouse", ["project-management"]),
     WebhookIntegration("codeship", ["continuous-integration", "deployment"]),
     WebhookIntegration("crashlytics", ["monitoring"]),
@@ -716,6 +733,7 @@ def __init__(self, name: str, *args: Any, **kwargs: Any) -> None:
     "buildbot": [ScreenshotConfig("started.json")],
     "canarytoken": [ScreenshotConfig("canarytoken_real.json")],
     "circleci": [ScreenshotConfig("github_job_completed.json")],
+    "clickup": [ScreenshotConfig("task_moved.json")],
     "clubhouse": [ScreenshotConfig("story_create.json")],
     "codeship": [ScreenshotConfig("error_build.json")],
     "crashlytics": [ScreenshotConfig("issue_message.json")],

zerver/webhooks/clickup/__init__.py

@@ -0,0 +1 @@
+

zerver/webhooks/clickup/callback_fixtures/get_folder.json

@@ -0,0 +1,14 @@
+{
+    "id": "457",
+    "name": "Lord Foldemort",
+    "orderindex": 0,
+    "override_statuses": false,
+    "hidden": false,
+    "space": {
+        "id": "789",
+        "name": "Space Name",
+        "access": true
+    },
+    "task_count": "0",
+    "lists": []
+}

zerver/webhooks/clickup/callback_fixtures/get_goal.json

@@ -0,0 +1,33 @@
+{
+    "goal": {
+        "id": "e53a033c-900e-462d-a849-4a216b06d930",
+        "name": "hat-trick",
+        "team_id": "512",
+        "date_created": "1568044355026",
+        "start_date": null,
+        "due_date": "1568036964079",
+        "description": "Updated Goal Description",
+        "private": false,
+        "archived": false,
+        "creator": 183,
+        "color": "#32a852",
+        "pretty_id": "6",
+        "multiple_owners": true,
+        "folder_id": null,
+        "members": [],
+        "owners": [
+            {
+                "id": 182,
+                "username": "Pieter CK",
+                "email": "[email protected]",
+                "color": "#7b68ee",
+                "initials": "PK",
+                "profilePicture": "https://attachments-public.clickup.com/profilePictures/182_abc.jpg"
+            }
+        ],
+        "key_results": [],
+        "percent_completed": 0,
+        "history": [],
+        "pretty_url": "https://app.clickup.com/512/goals/6"
+    }
+}

zerver/webhooks/clickup/callback_fixtures/get_list.json

@@ -0,0 +1,49 @@
+{
+    "id": "124",
+    "name": "Listener",
+    "orderindex": 1,
+    "content": "Updated List Content",
+    "status": {
+        "status": "red",
+        "color": "#e50000",
+        "hide_label": true
+    },
+    "priority": {
+        "priority": "high",
+        "color": "#f50000"
+    },
+    "assignee": null,
+    "due_date": "1567780450202",
+    "due_date_time": true,
+    "start_date": null,
+    "start_date_time": null,
+    "folder": {
+        "id": "456",
+        "name": "Folder Name",
+        "hidden": false,
+        "access": true
+    },
+    "space": {
+        "id": "789",
+        "name": "Space Name",
+        "access": true
+    },
+    "inbound_address": "add.task.124.ac725f.31518a6a-05bb-4997-92a6-1dcfe2f527ca@tasks.clickup.com",
+    "archived": false,
+    "override_statuses": false,
+    "statuses": [
+        {
+            "status": "to do",
+            "orderindex": 0,
+            "color": "#d3d3d3",
+            "type": "open"
+        },
+        {
+            "status": "complete",
+            "orderindex": 1,
+            "color": "#6bc950",
+            "type": "closed"
+        }
+    ],
+    "permission_level": "create"
+}

zerver/webhooks/clickup/callback_fixtures/get_space.json

@@ -0,0 +1,52 @@
+{
+    "id": "790",
+    "name": "the Milky Way",
+    "private": false,
+    "statuses": [
+        {
+            "status": "to do",
+            "type": "open",
+            "orderindex": 0,
+            "color": "#d3d3d3"
+        },
+        {
+            "status": "complete",
+            "type": "closed",
+            "orderindex": 1,
+            "color": "#6bc950"
+        }
+    ],
+    "multiple_assignees": false,
+    "features": {
+        "due_dates": {
+            "enabled": false,
+            "start_date": false,
+            "remap_due_dates": false,
+            "remap_closed_due_date": false
+        },
+        "time_tracking": {
+            "enabled": false
+        },
+        "tags": {
+            "enabled": false
+        },
+        "time_estimates": {
+            "enabled": false
+        },
+        "checklists": {
+            "enabled": true
+        },
+        "custom_fields": {
+            "enabled": true
+        },
+        "remap_dependencies": {
+            "enabled": false
+        },
+        "dependency_warning": {
+            "enabled": false
+        },
+        "portfolios": {
+            "enabled": false
+        }
+    }
+}

zerver/webhooks/clickup/callback_fixtures/get_task.json

@@ -0,0 +1,63 @@
+{
+    "id": "string",
+    "custom_id": "string",
+    "custom_item_id": 0,
+    "name": "Tanswer",
+    "text_content": "string",
+    "description": "string",
+    "status": {
+        "status": "in progress",
+        "color": "#d3d3d3",
+        "orderindex": 1,
+        "type": "custom"
+    },
+    "orderindex": "string",
+    "date_created": "string",
+    "date_updated": "string",
+    "date_closed": "string",
+    "creator": {
+        "id": 183,
+        "username": "Pieter CK",
+        "color": "#827718",
+        "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
+    },
+    "assignees": ["string"],
+    "checklists": ["string"],
+    "tags": ["string"],
+    "parent": "string",
+    "priority": "string",
+    "due_date": "string",
+    "start_date": "string",
+    "time_estimate": "string",
+    "time_spent": "string",
+    "custom_fields": [
+        {
+            "id": "string",
+            "name": "string",
+            "type": "string",
+            "type_config": {},
+            "date_created": "string",
+            "hide_from_guests": true,
+            "value": {
+                "id": 183,
+                "username": "Pieter CK",
+                "email": "[email protected]",
+                "color": "#7b68ee",
+                "initials": "PK",
+                "profilePicture": null
+            },
+            "required": true
+        }
+    ],
+    "list": {
+        "id": "123"
+    },
+    "folder": {
+        "id": "456"
+    },
+    "space": {
+        "id": "789"
+    },
+    "url": "https://app.clickup.com/XXXXXXXX/home",
+    "markdown_description": "string"
+}

zerver/webhooks/clickup/doc.md

@@ -0,0 +1,88 @@
+# Zulip ClickUp integration
+
+Get Zulip notifications for your ClickUp space!
+
+!!! tip ""
+
+    [Zapier](./zapier) is usually a simpler way to integrate ClickUp
+    with Zulip.
+
+{start_tabs}
+
+1. {!create-channel.md!}
+
+1. {!create-an-incoming-webhook.md!}
+
+1. {!generate-webhook-url-basic.md!}
+
+1. Collect your ClickUp **Team ID** by going to your ClickUp home view.
+    The URL should look like `https://app.clickup.com/<TEAM_ID>/home`.
+    Note down the `<TEAM_ID>`.
+
+1. Collect your ClickUp **Client ID** and **Client Secret** by following these steps:
+
+    - Go to your [ClickUp API menu][1] and click **Create an App**.
+
+    - You will be prompted for **Redirect URL(s)**, enter the URL for your Zulip organization.
+        e.g., `{{ zulip_url }}`.
+
+    - Note down the **Client ID** and **Client Secret**
+
+1.  You're now going to need to run a ClickUp configuration script from a
+    computer (any computer) connected to the internet. It won't make any
+    changes to the computer.
+
+    Make sure you have a working copy of Python. If you're running
+    macOS or Linux, you very likely already do. If you're running
+    Windows you may or may not.  If you don't have Python, follow the
+    installation instructions [here][2].
+
+    !!! tip ""
+
+        You do not need the latest version of Python; anything 2.7 or
+        higher will do.
+
+1. Download [zulip-clickup.py][3].
+
+    !!! tip ""
+
+        <kbd>Ctrl</kbd> + <kbd>s</kbd> or <kbd>Cmd</kbd> + <kbd>s</kbd>
+        on that page should work in most browsers.
+
+1. Run the `zulip-clickup.py` script in a terminal, after replacing the all caps
+   arguments with the values collected above.
+
+    ```
+    python zulip-clickup.py --clickup-team-id CLICKUP_TEAM_ID \
+                            --clickup-client-id CLICKUP_CLIENT_ID \
+                            --clickup-client-secret CLICKUP_CLIENT_SECRET \
+                            --zulip-webhook-url "ZULIP_WEBHOOK_URL"
+    ```
+
+    !!! warn ""
+
+        **Note**: Make sure that you wrap the webhook URL generated above
+        in quotes when supplying it on the command-line, as shown above.
+
+1. Follow the instructions in the terminal and keep an eye on your browser as you
+   will be redirected to a ClickUp authorization page.
+
+{end_tabs}
+
+{!congrats.md!}
+
+![](/static/images/integrations/clickup/001.png)
+
+### Related documentation
+
+- [Zapier ClickUp integration][4]
+
+{!webhooks-url-specification.md!}
+
+[1]: https://app.clickup.com/settings/team/clickup-api
+
+[2]: https://realpython.com/installing-python/
+
+[3]: https://raw.githubusercontent.com/zulip/python-zulip-api/main/zulip/integrations/clickup/zulip_clickup.py
+
+[4]: https://zapier.com/apps/clickup/integrations#zap-template-list

zerver/webhooks/clickup/fixtures/folder_created.json

@@ -0,0 +1,5 @@
+{
+  "event": "folderCreated",
+  "folder_id": "96772212",
+  "webhook_id": "7fa3ec74-69a8-4530-a251-8a13730bd204"
+}

zerver/webhooks/clickup/fixtures/folder_deleted.json

@@ -0,0 +1,5 @@
+{
+  "event": "folderDeleted",
+  "folder_id": "96772212",
+  "webhook_id": "7fa3ec74-69a8-4530-a251-8a13730bd204"
+}

zerver/webhooks/clickup/fixtures/folder_updated.json

@@ -0,0 +1,5 @@
+{
+  "event": "folderUpdated",
+  "folder_id": "96772212",
+  "webhook_id": "7fa3ec74-69a8-4530-a251-8a13730bd204"
+}

zerver/webhooks/clickup/fixtures/goal_created.json

@@ -0,0 +1,5 @@
+{
+  "event": "goalCreated",
+  "goal_id": "a23e5a3d-74b5-44c2-ab53-917ebe85045a",
+  "webhook_id": "d5eddb2d-db2b-49e9-87d4-bc6cfbe2313b"
+}

zerver/webhooks/clickup/fixtures/goal_deleted.json

@@ -0,0 +1,5 @@
+{
+  "event": "goalDeleted",
+  "goal_id": "a23e5a3d-74b5-44c2-ab53-917ebe85045a",
+  "webhook_id": "d5eddb2d-db2b-49e9-87d4-bc6cfbe2313b"
+}

zerver/webhooks/clickup/fixtures/goal_updated.json

@@ -0,0 +1,5 @@
+{
+  "event": "goalUpdated",
+  "goal_id": "a23e5a3d-74b5-44c2-ab53-917ebe85045a",
+  "webhook_id": "d5eddb2d-db2b-49e9-87d4-bc6cfbe2313b"
+}

zerver/webhooks/clickup/fixtures/list_created.json

@@ -0,0 +1,5 @@
+{
+  "event": "listCreated",
+  "list_id": "901601848935",
+  "webhook_id": "7fa3ec74-69a8-4530-a251-8a13730bd204"
+}

zerver/webhooks/clickup/fixtures/list_deleted.json

@@ -0,0 +1,5 @@
+{
+  "event": "listDeleted",
+  "list_id": "901601848935",
+  "webhook_id": "7fa3ec74-69a8-4530-a251-8a13730bd204"
+}