From b9c97f43ef92fd1391e0065820470761857c99bf Mon Sep 17 00:00:00 2001 From: Niloth P <20315308+Niloth-p@users.noreply.github.com> Date: Mon, 14 Apr 2025 18:20:03 +0530 Subject: [PATCH] integration-docs: Update the Google Calendar integration doc. --- zulip/integrations/google/doc.md | 222 ++++++++++++++++++++++++------- 1 file changed, 171 insertions(+), 51 deletions(-) diff --git a/zulip/integrations/google/doc.md b/zulip/integrations/google/doc.md index e9a21b3af..e65c30493 100644 --- a/zulip/integrations/google/doc.md +++ b/zulip/integrations/google/doc.md @@ -1,72 +1,192 @@ -Get Google Calendar reminders in Zulip! This is a great way to see -your reminders directly in your Zulip feed. +# Zulip Google Calendar integration -1. {!download-python-bindings.md!} +Get Zulip notifications for your Google Calendar events! - This bot should be set up on a trusted machine, because your API - key is visible to local users through the command line or config - file. +### Create Zulip bot for Google Calendar notifications -1. Next, follow the instructions for **Step 1** at - [this link](https://developers.google.com/google-apps/calendar/quickstart/python) - to get a `client_secret` file. Save this file as `client_secret.json` - to your `~/` directory. +{start_tabs} -1. Next, install the latest Google API Client for Python by following the - instructions on the - [Google website](https://developers.google.com/api-client-library/python/start/installation). +1. {!create-a-generic-bot.md!} -1. In Zulip, go to your click on the cog in the top right corner, and - then clicking on **Personal settings**. +1. [Download your bot's `zuliprc` file][download-zuliprc]. Either save it + as `.zuliprc` in your `~/` directory, or use the `--config-file` option + to specify the path to your bot's `zuliprc`. -1. Click on the tab that’s labeled **Account & privacy** and click on - **Manage your API key**. Enter your password if prompted, and - download the `zuliprc` file. Save this file as `.zuliprc` to your `~/` - directory. +[download-zuliprc]: /api/configuring-python-bindings#download-a-zuliprc-file - ![Download zuliprc file](/static/images/integrations/google/calendar/001.png) +1. _(optional)_ To configure the bot, add a **`google-calendar`** section + to the `zuliprc` file: -1. Run the `get-google-credentials` with this command: + ``` + [google-calendar] + interval=30 + channel=core-team + topic=scheduled events + ``` - python /usr/local/share/zulip/integrations/google/get-google-credentials + Alternatively, you'll be able to pass command-line arguments to the + integration script. See [configuration options](#configuration-options) + for the list of available options. -1. It should open up a browser and ask you for certain permissions. Give - Zulip access, and move on to the next step. If it doesn’t open a - browser, follow the instructions in the terminal window. +{end_tabs} -1. Now, all that’s left to do is to run the `gcal-bot` script, in the - same directory as the `get-google-credentials` script, with the - necessary parameters: +### Set up Google OAuth Client ID - python /usr/local/share/zulip/integrations/google/gcal-bot --user foo@zulip.com +{start_tabs} - The `--user` flag specifies the user to send the reminder to. +!!! tip "" -1. Don’t close the terminal window with the bot running (you can use - `screen` if needed). You will only get reminders if the bot is still - running. + A free Google account is sufficient for this integration; a Google + service account is not required. -{!congrats.md!} +1. In the Google Cloud console, go to + **Menu > Google Auth platform > [Branding][branding-menu]**. Click + **Create project**. + +1. If you see a message that says **Google Auth platform not configured yet**, + click **Get Started**, and fill the form with the following details. + + - Under **App Information**, set **App name** to a name of your choice + (e.g., `Zulip calendar integration`). Set **User support email** to + your email address from the dropdown. Click **Next**. + - Under **Audience**, select **External**, and click **Next**. + - Under **Contact Information**, enter your email address, and click + **Next**. + - Under **Finish**, review and agree to the + **Google API Services User Data Policy**. Click **Continue**, and + click **Create**. + +1. Go to the **[Clients][clients-menu]** tab. Click **Create Client**. + Select **Application type > Desktop app**. Set **Name** to a name of + your choice (e.g., `Zulip`), and click **Create**. + +1. Click the **Download JSON** button. You can save the downloaded JSON + file as `client_secret.json` in your `~/` directory. If you wish to save + the file to a different path, make sure to pass that path to the + `tokens-file` configuration option. Click **OK** to close the dialog. + +1. Go to the **[Audience][audience-menu]** tab. Under **Test users**, click + **+ Add Users**. Enter the email address corresponding to your Google + Calendar, and click **Save**. + +[branding-menu]: https://console.cloud.google.com/auth/branding +[clients-menu]: https://console.cloud.google.com/auth/clients +[audience-menu]: https://console.cloud.google.com/auth/audience + +{end_tabs} + +### Run the integration script + +{start_tabs} + +1. Download and + [install the Zulip Python API](/api/installation-instructions) with: + + `pip install zulip` + +1. Install the requirements for the integration script with: + + `python {{ integration_path }}/google-calendar --provision` + +1. Run the integration script with: + + `python {{ integration_path }}/google-calendar` + + Authorize access in the browser window that opens, to allow the Zulip + bot to view your Calendar. If you've set `noauth_local_webserver` to + true, follow the terminal prompts instead, and paste the resulting + authorization code. + +1. _(optional)_ Pass command-line arguments to reconfigure the integration. + The command-line arguments override the corresponding settings in the + `.zuliprc` file. + + `python {{ integration_path }}/google-calendar --interval 30 --channel core-team --topic "scheduled events"` + + See [configuration options](#configuration-options) for the list of + available options. + +1. You can restart the integration at any time by re-running the + integration script. You will get notifications as long as the terminal + session with the bot remains open. Consider using `supervisord` or a + similar tool for managing a production process. -![Calendar demo](/static/images/integrations/google/calendar/003.png) +!!! tip "" -## Supported parameters + Newly added calendar events may take up to 10 minutes to generate + notifications. + +{end_tabs} + +### Configuration options + +The integration can be configured by: + +- Passing command-line arguments to the integration script. +- Editing the `google-calendar` section of the `zuliprc` file. + +The configuration settings in `zuliprc` will be overridden by the +corresponding command-line options, if both are used. + +The integration script accepts the following configuration options: + +- `interval`: How many minutes in advance you want reminders delivered. + The default value is 30 minutes. + +- `channel`: The name of the Zulip channel you want to receive + notifications in. By default, messages are sent as direct messages to the + bot's owner. + +- `topic`: The name of the Zulip topic you want to receive notifications + in. This option is ignored if the `channel` option is unspecified. If the + `channel` option is specified, the default topic is "calendar-reminders". + +- `client-secret-file`: The path to the file containing the client secret. + By default, the client secret file is assumed to be at + `~/client_secret.json`. + +- `tokens-file`: The path to the file where the OAuth tokens are stored. By + default, the tokens file is generated at `~/google-tokens.json` when the + integration is first run, and is rewritten every hour. + +- `noauth-local-webserver`: This option stops the integration script from + starting a local webserver for receiving OAuth tokens. The default + authorization process runs a local web server, which requires a browser on + the same machine. For non-interactive environments and machines without + browser access, e.g., remote servers, this option allows manual + authorization. The authorization URL is printed, which the user can copy + into a browser, copy the resulting authorization code, and paste back into + the command line. + +- `calendar`: The `calendar ID` of the Google calendar to get events from. + By default, the `primary` calendar is used. + +- `format-message`: The template for the message that is sent to Zulip. This + Python f-string supports Markdown, and can use the following variables: + `start`, `end`, `title`, `description`, `calendar_link`, `location`, + `google_meet_link`. + + !!! warn "" + + **Note:** The `title`, `description`, `location`, and + `google_meet_link` variables are optional for Google Calendar + events, and hence may be empty. Empty fields are displayed as + "{No title}", "{No description}", "{No location}", and "{No link}" + in the message template. + + The default message template takes the following form when all the event + field variables are non-empty. + + `The event [{title}]({calendar_link}), at {location}, is from {start} to {end}.\n> {description}\n\n[Join call]({google_meet_link}).` + +{!congrats.md!} -There are two optional flags that you can specify when running this -script: +![Google Calendar integration](/static/images/integrations/google/calendar/001.png) -* `--calendar`: This flag specifies the calendar to watch from the - user’s Google account. By default, this flag is set to a user’s - primary or default calendar. To specify a calendar, you need the - calendar ID which can be obtained by going to Google Calendar and - clicking on the wedge next to the calendar’s name. Click on settings - in **Calendar settings** in the drop down, and look for the **Calendar - Address** section. Copy the **Calendar ID** from the right side of the - page and use that as the value for this flag. +### Related documentation -![Specify a calendar](/static/images/integrations/google/calendar/002.png) +- [Google's documentation on configuring the OAuth consent screen][consent-screen] +- [Google's documentation on setting up OAuth Client IDs][client-secret] -* `--interval`: This flag specifies the interval of time - in - minutes - between receiving the reminder, and the actual event. For - example, an interval of 30 minutes would mean that you would receive a - reminder for an event 30 minutes before it is scheduled to occur. +[consent-screen]: https://developers.google.com/workspace/calendar/api/quickstart/python#configure_the_oauth_consent_screen +[client-secret]: https://developers.google.com/workspace/calendar/api/quickstart/python#authorize_credentials_for_a_desktop_application