Skip to content

Commit b9c97f4

Browse files
Niloth-pNiloth-p
committed
integration-docs: Update the Google Calendar integration doc.
1 parent 0f80500 commit b9c97f4

File tree

1 file changed

+171
-51
lines changed
  • zulip/integrations/google

1 file changed

+171
-51
lines changed

‎zulip/integrations/google/doc.md‎

Lines changed: 171 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,192 @@
1-
Get Google Calendar reminders in Zulip! This is a great way to see
2-
your reminders directly in your Zulip feed.
1+
# Zulip Google Calendar integration
32

4-
1. {!download-python-bindings.md!}
3+
Get Zulip notifications for your Google Calendar events!
54

6-
This bot should be set up on a trusted machine, because your API
7-
key is visible to local users through the command line or config
8-
file.
5+
### Create Zulip bot for Google Calendar notifications
96

10-
1. Next, follow the instructions for **Step 1** at
11-
[this link](https://developers.google.com/google-apps/calendar/quickstart/python)
12-
to get a `client_secret` file. Save this file as `client_secret.json`
13-
to your `~/` directory.
7+
{start_tabs}
148

15-
1. Next, install the latest Google API Client for Python by following the
16-
instructions on the
17-
[Google website](https://developers.google.com/api-client-library/python/start/installation).
9+
1. {!create-a-generic-bot.md!}
1810

19-
1. In Zulip, go to your click on the cog in the top right corner, and
20-
then clicking on **Personal settings**.
11+
1. [Download your bot's `zuliprc` file][download-zuliprc]. Either save it
12+
as `.zuliprc` in your `~/` directory, or use the `--config-file` option
13+
to specify the path to your bot's `zuliprc`.
2114

22-
1. Click on the tab that’s labeled **Account & privacy** and click on
23-
**Manage your API key**. Enter your password if prompted, and
24-
download the `zuliprc` file. Save this file as `.zuliprc` to your `~/`
25-
directory.
15+
[download-zuliprc]: /api/configuring-python-bindings#download-a-zuliprc-file
2616

27-
![Download zuliprc file](/static/images/integrations/google/calendar/001.png)
17+
1. _(optional)_ To configure the bot, add a **`google-calendar`** section
18+
to the `zuliprc` file:
2819

29-
1. Run the `get-google-credentials` with this command:
20+
```
21+
[google-calendar]
22+
interval=30
23+
channel=core-team
24+
topic=scheduled events
25+
```
3026
31-
python /usr/local/share/zulip/integrations/google/get-google-credentials
27+
Alternatively, you'll be able to pass command-line arguments to the
28+
integration script. See [configuration options](#configuration-options)
29+
for the list of available options.
3230
33-
1. It should open up a browser and ask you for certain permissions. Give
34-
Zulip access, and move on to the next step. If it doesn’t open a
35-
browser, follow the instructions in the terminal window.
31+
{end_tabs}
3632
37-
1. Now, all that’s left to do is to run the `gcal-bot` script, in the
38-
same directory as the `get-google-credentials` script, with the
39-
necessary parameters:
33+
### Set up Google OAuth Client ID
4034
41-
python /usr/local/share/zulip/integrations/google/gcal-bot --user [email protected]
35+
{start_tabs}
4236
43-
The `--user` flag specifies the user to send the reminder to.
37+
!!! tip ""
4438
45-
1. Don’t close the terminal window with the bot running (you can use
46-
`screen` if needed). You will only get reminders if the bot is still
47-
running.
39+
A free Google account is sufficient for this integration; a Google
40+
service account is not required.
4841
49-
{!congrats.md!}
42+
1. In the Google Cloud console, go to
43+
**Menu > Google Auth platform > [Branding][branding-menu]**. Click
44+
**Create project**.
45+
46+
1. If you see a message that says **Google Auth platform not configured yet**,
47+
click **Get Started**, and fill the form with the following details.
48+
49+
- Under **App Information**, set **App name** to a name of your choice
50+
(e.g., `Zulip calendar integration`). Set **User support email** to
51+
your email address from the dropdown. Click **Next**.
52+
- Under **Audience**, select **External**, and click **Next**.
53+
- Under **Contact Information**, enter your email address, and click
54+
**Next**.
55+
- Under **Finish**, review and agree to the
56+
**Google API Services User Data Policy**. Click **Continue**, and
57+
click **Create**.
58+
59+
1. Go to the **[Clients][clients-menu]** tab. Click **Create Client**.
60+
Select **Application type > Desktop app**. Set **Name** to a name of
61+
your choice (e.g., `Zulip`), and click **Create**.
62+
63+
1. Click the **Download JSON** button. You can save the downloaded JSON
64+
file as `client_secret.json` in your `~/` directory. If you wish to save
65+
the file to a different path, make sure to pass that path to the
66+
`tokens-file` configuration option. Click **OK** to close the dialog.
67+
68+
1. Go to the **[Audience][audience-menu]** tab. Under **Test users**, click
69+
**+ Add Users**. Enter the email address corresponding to your Google
70+
Calendar, and click **Save**.
71+
72+
[branding-menu]: https://console.cloud.google.com/auth/branding
73+
[clients-menu]: https://console.cloud.google.com/auth/clients
74+
[audience-menu]: https://console.cloud.google.com/auth/audience
75+
76+
{end_tabs}
77+
78+
### Run the integration script
79+
80+
{start_tabs}
81+
82+
1. Download and
83+
[install the Zulip Python API](/api/installation-instructions) with:
84+
85+
`pip install zulip`
86+
87+
1. Install the requirements for the integration script with:
88+
89+
`python {{ integration_path }}/google-calendar --provision`
90+
91+
1. Run the integration script with:
92+
93+
`python {{ integration_path }}/google-calendar`
94+
95+
Authorize access in the browser window that opens, to allow the Zulip
96+
bot to view your Calendar. If you've set `noauth_local_webserver` to
97+
true, follow the terminal prompts instead, and paste the resulting
98+
authorization code.
99+
100+
1. _(optional)_ Pass command-line arguments to reconfigure the integration.
101+
The command-line arguments override the corresponding settings in the
102+
`.zuliprc` file.
103+
104+
`python {{ integration_path }}/google-calendar --interval 30 --channel core-team --topic "scheduled events"`
105+
106+
See [configuration options](#configuration-options) for the list of
107+
available options.
108+
109+
1. You can restart the integration at any time by re-running the
110+
integration script. You will get notifications as long as the terminal
111+
session with the bot remains open. Consider using `supervisord` or a
112+
similar tool for managing a production process.
50113
51-
![Calendar demo](/static/images/integrations/google/calendar/003.png)
114+
!!! tip ""
52115
53-
## Supported parameters
116+
Newly added calendar events may take up to 10 minutes to generate
117+
notifications.
118+
119+
{end_tabs}
120+
121+
### Configuration options
122+
123+
The integration can be configured by:
124+
125+
- Passing command-line arguments to the integration script.
126+
- Editing the `google-calendar` section of the `zuliprc` file.
127+
128+
The configuration settings in `zuliprc` will be overridden by the
129+
corresponding command-line options, if both are used.
130+
131+
The integration script accepts the following configuration options:
132+
133+
- `interval`: How many minutes in advance you want reminders delivered.
134+
The default value is 30 minutes.
135+
136+
- `channel`: The name of the Zulip channel you want to receive
137+
notifications in. By default, messages are sent as direct messages to the
138+
bot's owner.
139+
140+
- `topic`: The name of the Zulip topic you want to receive notifications
141+
in. This option is ignored if the `channel` option is unspecified. If the
142+
`channel` option is specified, the default topic is "calendar-reminders".
143+
144+
- `client-secret-file`: The path to the file containing the client secret.
145+
By default, the client secret file is assumed to be at
146+
`~/client_secret.json`.
147+
148+
- `tokens-file`: The path to the file where the OAuth tokens are stored. By
149+
default, the tokens file is generated at `~/google-tokens.json` when the
150+
integration is first run, and is rewritten every hour.
151+
152+
- `noauth-local-webserver`: This option stops the integration script from
153+
starting a local webserver for receiving OAuth tokens. The default
154+
authorization process runs a local web server, which requires a browser on
155+
the same machine. For non-interactive environments and machines without
156+
browser access, e.g., remote servers, this option allows manual
157+
authorization. The authorization URL is printed, which the user can copy
158+
into a browser, copy the resulting authorization code, and paste back into
159+
the command line.
160+
161+
- `calendar`: The `calendar ID` of the Google calendar to get events from.
162+
By default, the `primary` calendar is used.
163+
164+
- `format-message`: The template for the message that is sent to Zulip. This
165+
Python f-string supports Markdown, and can use the following variables:
166+
`start`, `end`, `title`, `description`, `calendar_link`, `location`,
167+
`google_meet_link`.
168+
169+
!!! warn ""
170+
171+
**Note:** The `title`, `description`, `location`, and
172+
`google_meet_link` variables are optional for Google Calendar
173+
events, and hence may be empty. Empty fields are displayed as
174+
"{No title}", "{No description}", "{No location}", and "{No link}"
175+
in the message template.
176+
177+
The default message template takes the following form when all the event
178+
field variables are non-empty.
179+
180+
`The event [{title}]({calendar_link}), at {location}, is from {start} to {end}.\n> {description}\n\n[Join call]({google_meet_link}).`
181+
182+
{!congrats.md!}
54183
55-
There are two optional flags that you can specify when running this
56-
script:
184+
![Google Calendar integration](/static/images/integrations/google/calendar/001.png)
57185
58-
* `--calendar`: This flag specifies the calendar to watch from the
59-
user’s Google account. By default, this flag is set to a user’s
60-
primary or default calendar. To specify a calendar, you need the
61-
calendar ID which can be obtained by going to Google Calendar and
62-
clicking on the wedge next to the calendar’s name. Click on settings
63-
in **Calendar settings** in the drop down, and look for the **Calendar
64-
Address** section. Copy the **Calendar ID** from the right side of the
65-
page and use that as the value for this flag.
186+
### Related documentation
66187
67-
![Specify a calendar](/static/images/integrations/google/calendar/002.png)
188+
- [Google's documentation on configuring the OAuth consent screen][consent-screen]
189+
- [Google's documentation on setting up OAuth Client IDs][client-secret]
68190
69-
* `--interval`: This flag specifies the interval of time - in
70-
minutes - between receiving the reminder, and the actual event. For
71-
example, an interval of 30 minutes would mean that you would receive a
72-
reminder for an event 30 minutes before it is scheduled to occur.
191+
[consent-screen]: https://developers.google.com/workspace/calendar/api/quickstart/python#configure_the_oauth_consent_screen
192+
[client-secret]: https://developers.google.com/workspace/calendar/api/quickstart/python#authorize_credentials_for_a_desktop_application

0 commit comments

Comments
 (0)