diff --git a/connectors/google-calendar/Google Calendar Connector/image 1.png b/connectors/google-calendar/Google Calendar Connector/image 1.png new file mode 100644 index 00000000..b632e29f Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 1.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 10.png b/connectors/google-calendar/Google Calendar Connector/image 10.png new file mode 100644 index 00000000..4a955885 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 10.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 11.png b/connectors/google-calendar/Google Calendar Connector/image 11.png new file mode 100644 index 00000000..22fe0fd2 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 11.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 12.png b/connectors/google-calendar/Google Calendar Connector/image 12.png new file mode 100644 index 00000000..19debdca Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 12.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 13.png b/connectors/google-calendar/Google Calendar Connector/image 13.png new file mode 100644 index 00000000..5b1c12cf Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 13.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 14.png b/connectors/google-calendar/Google Calendar Connector/image 14.png new file mode 100644 index 00000000..b008ccd7 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 14.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 15.png b/connectors/google-calendar/Google Calendar Connector/image 15.png new file mode 100644 index 00000000..35a7ddb9 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 15.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 16.png b/connectors/google-calendar/Google Calendar Connector/image 16.png new file mode 100644 index 00000000..a0240861 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 16.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 17.png b/connectors/google-calendar/Google Calendar Connector/image 17.png new file mode 100644 index 00000000..a651c879 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 17.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 2.png b/connectors/google-calendar/Google Calendar Connector/image 2.png new file mode 100644 index 00000000..100ed1cf Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 2.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 3.png b/connectors/google-calendar/Google Calendar Connector/image 3.png new file mode 100644 index 00000000..32c2d11d Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 3.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 4.png b/connectors/google-calendar/Google Calendar Connector/image 4.png new file mode 100644 index 00000000..7fe1e143 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 4.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 5.png b/connectors/google-calendar/Google Calendar Connector/image 5.png new file mode 100644 index 00000000..0a743921 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 5.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 6.png b/connectors/google-calendar/Google Calendar Connector/image 6.png new file mode 100644 index 00000000..74ed7e5a Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 6.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 7.png b/connectors/google-calendar/Google Calendar Connector/image 7.png new file mode 100644 index 00000000..5c70e056 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 7.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 8.png b/connectors/google-calendar/Google Calendar Connector/image 8.png new file mode 100644 index 00000000..da77a642 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 8.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image 9.png b/connectors/google-calendar/Google Calendar Connector/image 9.png new file mode 100644 index 00000000..2b03a493 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image 9.png differ diff --git a/connectors/google-calendar/Google Calendar Connector/image.png b/connectors/google-calendar/Google Calendar Connector/image.png new file mode 100644 index 00000000..a55d18f2 Binary files /dev/null and b/connectors/google-calendar/Google Calendar Connector/image.png differ diff --git a/connectors/google-calendar/README.md b/connectors/google-calendar/README.md index 34952579..3a7fe72c 100644 --- a/connectors/google-calendar/README.md +++ b/connectors/google-calendar/README.md @@ -5,3 +5,217 @@ name: Google Calendar redirects: - googlecalendar --- +## Introduction + +**Google Calendar** is Google's cloud-based calendaring service, deeply integrated across Google Workspace — including Gmail, Meet, and Drive. + +Connecting Google Calendar to **Moveworks Agent Studio** brings these capabilities directly into the AI assistant — employees can search calendar events, check availability, book and manage meetings, and find available rooms, all through their AI Assistant. + +This guide walks through setting up the OAuth 2.0 Authorization Code (User Consent Auth) flow to connect Google Calendar with Agent Studio. For a full list of available API resources, refer to the [Google Calendar API documentation](https://developers.google.com/calendar/api/guides/overview). + +--- + +## Prerequisites + +### Google Requirements + +- A **Google Cloud project** with the **Google Calendar API** enabled +- Google Workspace admin privileges to configure the OAuth consent screen +- Access to the [Google Cloud Console](https://console.cloud.google.com/) — specifically **APIs & Services → Credentials** +- A Google Workspace tenant with Google Calendar enabled for your users + +### Moveworks Requirements + +- Agent Studio admin access in your Moveworks tenant ([grant access guide](https://help.moveworks.com/docs/manage-roles-and-permissions-for-moveworks-applications#add-an-application-admin)) + +--- + +## OAuth 2.0 with Authorization Code (User Consent Auth) Setup + +Use this flow for actions performed in the context of the authenticated end user. Each user will authorize the integration once, and Moveworks will act on their behalf using their delegated permissions. + +--- + +### Step 1: Create or Select a Google Cloud Project + +1. Go to the [Google Cloud Console](https://console.cloud.google.com/) and sign in as a Google Workspace administrator. +2. In the top navigation bar, click the project dropdown and select an existing project, or click **New Project** to create a dedicated one (e.g., Moveworks Marketplace). + + ![image.png](Google%20Calendar%20Connector/image.png) + + +--- + +### Step 2: Enable the Google Calendar API + +1. In the left-hand menu, navigate to **APIs & Services → Library**. + + ![image.png](Google%20Calendar%20Connector/image%201.png) + +2. Search for **Google Calendar API** and click on it from the results (the first one in the list). + + ![image.png](Google%20Calendar%20Connector/image%202.png) + +3. Click **Enable**. You will be redirected to the API overview page once it is enabled. + + ![image.png](Google%20Calendar%20Connector/image%203.png) + + +--- + +### Step 3: Configure the OAuth Consent Screen + +**Note:** If you are working in an existing Google Cloud project that already has the OAuth consent screen configured, you can skip to Step 4. If this is a fresh project, complete this step first. + +In the left-hand menu, navigate to **APIs & Services → OAuth consent screen**. This will take you into the **Google Auth Platform**, where the consent screen settings are split across three sections: **Branding**, **Audience**, and **Data Access**. + +### Branding + +1. Navigate to **Branding**. +2. Fill in the following required fields: + + + | Field | Recommended Value | + | --- | --- | + | App name | Moveworks Calendar Connector (or any other name) | + | User support email | Your IT or admin team email address | + | Developer contact information | Your IT or admin team email address | +3. Click **Save**. + + ![image.png](Google%20Calendar%20Connector/image%204.png) + + +### Audience + +1. Navigate to **Audience**. +2. Under **User Type**, select **Internal** — this restricts access to users within your Google Workspace organization only. + + ![image.png](Google%20Calendar%20Connector/image%205.png) + + **Note:** Selecting "Internal" means only users within your Google Workspace tenant can authorize the app. This is the recommended setting for enterprise integrations and avoids the need for Google's external app verification process. + +3. Click **Save**. + +### Data Access + +1. Navigate to **Data Access**. +2. Click **Add or Remove Scopes.** For example, for most of the calendar plugins, you need the following scope: + + + | Scope | Access Level | Required For | + | --- | --- | --- | + | `https://www.googleapis.com/auth/calendar` | Full | If read + write access is required together | + + ![image.png](Google%20Calendar%20Connector/image%206.png) + +3. Click **Update**, then **Save**. + +--- + +### Step 4: Create OAuth 2.0 Credentials + +1. Navigate to **APIs & Services → Credentials**. +2. Click **+ Create Credentials** and select **OAuth client ID**. + + ![image.png](Google%20Calendar%20Connector/image%207.png) + +3. Fill in the following fields: + + + | Field | Value | + | --- | --- | + | Application type | Web application | + | Name | Moveworks Calendar Connector (or your preferred name) | + | Authorized redirect URIs | `https://{{tenant}}.moveworks.com/auth/oauthCallback` | + + ![image.png](Google%20Calendar%20Connector/image%208.png) + +4. Click **Create**. +5. A dialog will appear showing your **Client ID.** Open the API client again for **the Client Secret**. Copy and securely store both values — you will need them in Step 6. + +--- + +### Step 5: Confirm Your OAuth Endpoints + +Google's OAuth 2.0 endpoints are standardized and do not vary by tenant. Use the following values when configuring the Moveworks connector in the next step: + +| Endpoint | URL | +| --- | --- | +| Authorization URL | `https://accounts.google.com/o/oauth2/v2/auth` | +| Token URL | `https://oauth2.googleapis.com/token` | + +--- + +### Step 6: Configure the Moveworks HTTP Connector + +1. In Agent Studio, go to **HTTP Connectors → Create**. +2. Fill in the connector fields: + - **Connector Name:** `Google_Calendar_Authcode_Flow` (or your preferred name) + - **Base URL:** `https://www.googleapis.com` + + ![image.png](Google%20Calendar%20Connector/image%209.png) + + - **Auth Config:** `Oauth2` + - **Oauth2 Grant Type:** `Authorization Code Grant` + - **Authorization URL:** `https://accounts.google.com/o/oauth2/v2/auth` + - **Client ID:** Your Client ID from Step 4 + - **Client Secret:** Your Client Secret from Step 4 + - **Authorization Code Grant Scope:** `https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly offline_access` + *(Adjust the scope to match the permissions required by the plugins you are enabling.)* + + ![image.png](Google%20Calendar%20Connector/image%2010.png) + + - **Authorization Request Query Parameters** + + + | **Key** | **Value** | + | --- | --- | + | access_type | offline | + | prompt | consent | + + ![image.png](Google%20Calendar%20Connector/image%2011.png) + + - **Authorization Code Grant Revoke Access Token Options Revoke Access Token Authentication:** `Revoke access token with Request Body` + - **Oauth2 Token URL:** `https://oauth2.googleapis.com/token` + + ![image.png](Google%20Calendar%20Connector/image%2012.png) + +3. Click **Save**. + +--- + +### Step 7: Test the User Consent Connector + +1. In Agent Studio, navigate to a new **HTTP Action**. +2. Fill in the following fields: + - **Connector:** Select **Inherit from existing connector** and choose the connector created in Step 6. + - **Action Name:** `Get Primary Calendar` (or your preferred name) + - **Endpoint URL:** `/calendar/v3/calendars/primary` + - **Method:** `GET` + + ![image.png](Google%20Calendar%20Connector/image%2013.png) + +3. Click **Test**. You will be prompted to **Generate New Access Token**. Click it. + + + ![image.png](Google%20Calendar%20Connector/image%2014.png) + +4. A Google sign-in window will appear — select an account or enter your Google Workspace credentials to authenticate. + + ![image.png](Google%20Calendar%20Connector/image%2015.png) + +5. When prompted, review and accept the permission consent screen. + + ![image.png](Google%20Calendar%20Connector/image%2016.png) + +6. After successful login, you will be redirected back to Moveworks with a confirmation that authentication was successful. +7. Click **Test** again. A `200` response confirms the connector is working. + + ![image.png](Google%20Calendar%20Connector/image%2017.png) + + +--- + +## Congratulations! + +You've successfully connected Google Calendar to Moveworks Agent Studio using the OAuth 2.0 Authorization Code (User Consent) flow. Your connector is now ready to support Google Calendar plugins on the Moveworks AI Assistant. \ No newline at end of file diff --git a/plugins/google-calendar-book-meeting/Book a Meeting/image.png b/plugins/google-calendar-book-meeting/Book a Meeting/image.png new file mode 100644 index 00000000..353b8192 Binary files /dev/null and b/plugins/google-calendar-book-meeting/Book a Meeting/image.png differ diff --git a/plugins/google-calendar-book-meeting/README.md b/plugins/google-calendar-book-meeting/README.md new file mode 100644 index 00000000..5b1e137c --- /dev/null +++ b/plugins/google-calendar-book-meeting/README.md @@ -0,0 +1,187 @@ +--- +availability: INSTALLABLE +installation_asset_uuid: 01417f3b-3b4d-4405-9303-0399ddae4e45 +description: Create a meeting, invite attendees, and add a video link in one go. +name: Book a Meeting +purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Book+a+meeting+on+Google+Calendar+with+Sarah+about+the+Q4+Roadmap+for+30+minutes+tomorrow+at+10+AM.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ESearching+for+employees+named+%3Cb%3ESarah%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22moveworks%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+two+people+named+%3Cb%3ESarah%3C%2Fb%3E.+Which+one+should+I+invite%3F%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ESarah+Jenkins%3C%2Fb%3E+%28Finance+Manager%29%3C%2Fli%3E%3Cli%3E%3Cb%3ESarah+Miller%3C%2Fb%3E+%28Product+Lead%29%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Sarah+Miller%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EOkay%2C+I%27ve+prepared+the+calendar+invitation%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ESubject%3A%3C%2Fb%3E+Q4+Roadmap%3C%2Fli%3E%3Cli%3E%3Cb%3EAttendees%3A%3C%2Fb%3E+Sarah+Miller%3C%2Fli%3E%3Cli%3E%3Cb%3EDate%3A%3C%2Fb%3E+Tomorrow%2C+October+24%3C%2Fli%3E%3Cli%3E%3Cb%3ETime%3A%3C%2Fb%3E+10%3A00+AM+-+10%3A30+AM%3C%2Fli%3E%3Cli%3E%3Cb%3EPlatform%3A%3C%2Fb%3E+Google+Meet%3C%2Fli%3E%3C%2Ful%3E%3Cp%3E%3Cstrong%3EReady+to+send+this+out%3F%3C%2Fstrong%3E%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Send+Invite%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Edit+Details%22%2C%22style%22%3A%22outlined%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Send+Invite%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ECreating+the+calendar+event+in+%3Cb%3EGoogle+Calendar%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EDone%21+I%27ve+scheduled+the+meeting+and+sent+the+invitation+to+%3Cb%3ESarah+Miller%3C%2Fb%3E.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Q4+Roadmap+Meeting%22%7D%5D%7D%5D%7D%5D%7D +solution_tags: +- Finance - Other +- HR - Other +- IT +- Productivity +- Sales +systems: +- google-calendar +--- + +# Description + +Book a meeting directly from your AI Assistant — set the time, invite attendees, add a description, and include a video call link, all in one conversation. + +# User Experience Preview + +Please refer to the following [**Purple Chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Book+a+meeting+on+Google+Calendar+with+Sarah+about+the+Q4+Roadmap+for+30+minutes+tomorrow+at+10+AM.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ESearching+for+employees+named+%3Cb%3ESarah%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22moveworks%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+two+people+named+%3Cb%3ESarah%3C%2Fb%3E.+Which+one+should+I+invite%3F%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ESarah+Jenkins%3C%2Fb%3E+%28Finance+Manager%29%3C%2Fli%3E%3Cli%3E%3Cb%3ESarah+Miller%3C%2Fb%3E+%28Product+Lead%29%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Sarah+Miller%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EOkay%2C+I%27ve+prepared+the+calendar+invitation%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ESubject%3A%3C%2Fb%3E+Q4+Roadmap%3C%2Fli%3E%3Cli%3E%3Cb%3EAttendees%3A%3C%2Fb%3E+Sarah+Miller%3C%2Fli%3E%3Cli%3E%3Cb%3EDate%3A%3C%2Fb%3E+Tomorrow%2C+October+24%3C%2Fli%3E%3Cli%3E%3Cb%3ETime%3A%3C%2Fb%3E+10%3A00+AM+-+10%3A30+AM%3C%2Fli%3E%3Cli%3E%3Cb%3EPlatform%3A%3C%2Fb%3E+Google+Meet%3C%2Fli%3E%3C%2Ful%3E%3Cp%3E%3Cstrong%3EReady+to+send+this+out%3F%3C%2Fstrong%3E%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Send+Invite%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Edit+Details%22%2C%22style%22%3A%22outlined%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Send+Invite%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ECreating+the+calendar+event+in+%3Cb%3EGoogle+Calendar%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EDone%21+I%27ve+scheduled+the+meeting+and+sent+the+invitation+to+%3Cb%3ESarah+Miller%3C%2Fb%3E.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Q4+Roadmap+Meeting%22%7D%5D%7D%5D%7D%5D%7D) for a sample conversational experience between a user and the AI Assistant for this plugin. + +# Prerequisites + +Before installing and using the **Book a Meeting** plugin, ensure the following requirements are met. + +### 1. Google Calendar Connector + +This plugin requires an active **Google Calendar connector** configured with the OAuth 2.0 Authorization Code (User Consent Auth) flow. + +- If you have not already set up the connector, follow the [**Google Calendar Connector Guide**](https://marketplace.moveworks.com/connectors/google-calendar) before proceeding. +- The connector must be fully configured and tested before installing this plugin. + +### 2. Zoom Connector (Optional) + +If you want the plugin to automatically create a Zoom meeting link when booking, a **Zoom connector** must also be configured. + +- If you do not have a Zoom connector, the plugin will still book the meeting in Google Calendar — it just won't attach a video conferencing link. +- To set up the Zoom connector, follow the [**Zoom Connector Guide**](https://claude.ai/chat/005dca93-ffec-40c2-82a4-7f1284f9a0aa#). + +### 3. Plugin Installation + +Once the connector is ready, follow the [**plugin installation documentation**](https://help.moveworks.com/docs/ai-agent-marketplace-installation) for steps on how to install and activate the plugin in Agent Studio. + +### 4. Google Workspace System Requirements + +### a. End User Permissions + +To book a meeting through this plugin, end users must have: + +- A licensed Google Workspace account with Google Calendar enabled +- Permission to create events on their own primary calendar + +Note: The plugin automatically retrieves the authenticated user's timezone from their Google Calendar settings and applies it when creating the event. No manual setup is required. + +### b. API Permissions + +The Google Calendar connector uses **delegated permissions** to create calendar events on behalf of the authenticated user. The following permission is required for this plugin: + +| Permission | Purpose | +| --- | --- | +| `https://www.googleapis.com/auth/calendar` | Create and update calendar events on the user's primary calendar | + +# Implementation Details + +This plugin works by making a sequence of API calls to book the meeting in Google Calendar and, if Zoom is selected as the video conferencing provider, create a Zoom meeting and attach the link to the calendar event. + +### Visual Representation of How the Plugin Works + +![image.png](Book%20a%20Meeting/image.png) + +### API Details + +This plugin uses up to four API calls depending on whether Zoom is selected as the video conferencing provider. + +### API #1: Get User's Primary Calendar + +Retrieves the authenticated user's primary calendar details, including their timezone. This is used to correctly set the event start and end times in the user's local timezone. + +```bash +curl --request GET \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' +``` + +--- + +### API #2: Create Calendar Event + +Creates the meeting in the authenticated user's primary Google Calendar with all the provided details — title, description, attendees, recurrence, visibility, and event type. + +```bash +curl --request POST \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' \ + --data '{ + "summary": "{{event_title}}", + "description": "{{event_description}}", + "start": {"dateTime": "{{start_date_time}}", "timeZone": "{{user_time_zone}}"}, + "end": {"dateTime": "{{end_date_time}}", "timeZone": "{{user_time_zone}}"}, + "attendees": [{"email": "{{attendee_email}}", "optional": false}, ...], + "recurrence": ["{{recurrence_rules}}"], + "transparency": "{{show_as}}", + "visibility": "{{visibility}}", + "eventType": "{{event_type}}" + }' +``` + +**Input Arguments:** + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `start_date_time` | string | Yes | Start time in ISO 8601 format, excluding timezone. Example: `2025-12-20T10:00:00` | +| `end_date_time` | string | Yes | End time in ISO 8601 format, excluding timezone. Example: `2025-12-20T10:30:00` | +| `user_time_zone` | string | Yes | The user's timezone in IANA format, retrieved from API #1. Example: `America/Los_Angeles` | +| `event_title` | string | Yes | Title of the event | +| `event_description` | string | No | Description or agenda for the event | +| `required_attendees` | list of strings | No | Email addresses of required attendees. Does not include the current user | +| `optional_attendees` | list of strings | No | Email addresses of optional attendees. Does not include the current user | +| `recurrence_rules` | list of strings | No | Recurrence rules in iCal RFC 5545 format. Example: `RRULE:FREQ=WEEKLY;INTERVAL=2`. Defaults to one-time event if not provided | +| `show_as` | string | Yes | Calendar status — `opaque` (busy) or `transparent` (free). Defaults to `opaque` | +| `visibility` | string | Yes | Event visibility — `default` or `private`. Defaults to `default` | +| `is_all_day` | boolean | Yes | Whether the event is an all-day event. Defaults to `false` | +| `event_type` | string | Yes | Type of event — `default`, `focusTime`, or `outOfOffice`. Defaults to `default` | + +**Key nuances:** + +- The current user is automatically added as the organizer — they do not need to be included in the attendees list. +- For `focusTime` and `outOfOffice` event types, attendees are not added even if provided. + +### API #3: Create Zoom Meeting *(conditional — only runs if Zoom is selected)* + +If the user requests a Zoom link, a Zoom meeting is created using the Zoom connector before the calendar event is updated. + +```bash +curl --request POST \ + --url 'https://api.zoom.us/v2/users/me/meetings' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' \ + --data '{ + "topic": "{{meeting_title}}", + "type": 1 + }' +``` + +### API #4: Update Calendar Event with Zoom Link *(conditional — only runs if Zoom is selected)* + +After the Zoom meeting is created, the calendar event is updated via a PATCH request to embed the Zoom join link, meeting ID, and passcode in the event description. + +```bash +curl --request PATCH \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events/{{event_id}}' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'If-Match: {{etag}}' \ + --header 'Content-Type: application/json' \ + --data '{ + "description": "{{zoom_details}}", + "location": "{{zoom_join_url}}" + }' +``` + +Now that you understand how the plugin works under the hood, let's walk through what it can and can't do. We recommend reading both sections before going live to ensure the best experience for your users. + +# What Is In Scope for This Plugin? + +This plugin supports the following capabilities: + +- Book a one-time or recurring meeting on the authenticated user's primary Google Calendar +- Add required and optional attendees by name or email address. +- Attach a **Zoom meeting link** automatically if Zoom is selected as the video conferencing provider. +- Create **Focus Time** and **Out of Office** blocks in addition to standard meetings. +- Support **all-day events.** +- Set event visibility (`default` or `private`) and calendar status (`busy` or `free`). + +# What Is Out of Scope for This Plugin? + +This plugin does **not** support the following: + +- Google Meet is not currently supported as a video conferencing option — only Zoom or no video link. +- Optional attendees are not currently supported — all attendees are added as required +- Booking on behalf of another user's calendar — events are always created on the authenticated user's primary calendar. +- Updating or cancelling an existing meeting — handled by separate Update a Meeting and Cancel a Meeting plugins. +- Adding rooms to a meeting - needs Recommend Rooms plugin to be enabled as well. \ No newline at end of file diff --git a/plugins/google-calendar-cancel-meeting/Cancel a Meeting/image.png b/plugins/google-calendar-cancel-meeting/Cancel a Meeting/image.png new file mode 100644 index 00000000..fcebbe8e Binary files /dev/null and b/plugins/google-calendar-cancel-meeting/Cancel a Meeting/image.png differ diff --git a/plugins/google-calendar-cancel-meeting/README.md b/plugins/google-calendar-cancel-meeting/README.md new file mode 100644 index 00000000..57073514 --- /dev/null +++ b/plugins/google-calendar-cancel-meeting/README.md @@ -0,0 +1,160 @@ +--- +availability: INSTALLABLE +installation_asset_uuid: 9daa51ea-27f6-4dee-bc8a-fa980cdc089f +description: Cancel a one-time or recurring meeting and notify attendees automatically. +name: Cancel a Meeting +purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Cancel+my+meeting+with+Sarah+Miller+about+the+Q4+Roadmap+tomorrow.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ESearching+for+calendar+events+with+%3Cb%3ESarah+Miller%3C%2Fb%3E+on+%3Cb%3EGoogle+Calendar%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+the+following+meeting+tomorrow%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EEvent%3C%2Fstrong%3E%3A+Q4+Roadmap%3C%2Fli%3E%3Cli%3E%3Cstrong%3ETime%3C%2Fstrong%3E%3A+10%3A00+AM+-+10%3A30+AM%3C%2Fli%3E%3Cli%3E%3Cstrong%3EOrganizer%3C%2Fstrong%3E%3A+You%3C%2Fli%3E%3Cli%3E%3Cstrong%3EAttendees%3C%2Fstrong%3E%3A+Sarah+Miller%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EAre+you+sure+you+want+to+cancel+this+event%3F%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Yes%2C+cancel+it%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Edit+Details%22%2C%22style%22%3A%22outlined%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Yes%2C+cancel+it%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ECancelling+the+meeting+in+%3Cb%3EGoogle+Calendar%3C%2Fb%3E+and+notifying+attendees...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+cancelled+the+%3Cstrong%3EQ4+Roadmap%3C%2Fstrong%3E+meeting+and+removed+it+from+your+calendar.+Sarah+Miller+has+been+notified.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Q4+Roadmap+Meeting+%28Cancelled%29%22%7D%5D%7D%5D%7D%5D%7D +solution_tags: +- Finance - Other +- HR - Other +- IT +- Productivity +- Sales +systems: +- google-calendar +--- + +# Description + +Cancel a meeting directly from your AI Assistant — remove it from your calendar or cancel it for all attendees, with support for one-time and recurring events. + +# User Experience Preview + +Please refer to the following [**Purple Chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Cancel+my+meeting+with+Sarah+Miller+about+the+Q4+Roadmap+tomorrow.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ESearching+for+calendar+events+with+%3Cb%3ESarah+Miller%3C%2Fb%3E+on+%3Cb%3EGoogle+Calendar%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+the+following+meeting+tomorrow%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EEvent%3C%2Fstrong%3E%3A+Q4+Roadmap%3C%2Fli%3E%3Cli%3E%3Cstrong%3ETime%3C%2Fstrong%3E%3A+10%3A00+AM+-+10%3A30+AM%3C%2Fli%3E%3Cli%3E%3Cstrong%3EOrganizer%3C%2Fstrong%3E%3A+You%3C%2Fli%3E%3Cli%3E%3Cstrong%3EAttendees%3C%2Fstrong%3E%3A+Sarah+Miller%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EAre+you+sure+you+want+to+cancel+this+event%3F%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Yes%2C+cancel+it%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Edit+Details%22%2C%22style%22%3A%22outlined%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Yes%2C+cancel+it%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ECancelling+the+meeting+in+%3Cb%3EGoogle+Calendar%3C%2Fb%3E+and+notifying+attendees...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+cancelled+the+%3Cstrong%3EQ4+Roadmap%3C%2Fstrong%3E+meeting+and+removed+it+from+your+calendar.+Sarah+Miller+has+been+notified.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Q4+Roadmap+Meeting+%28Cancelled%29%22%7D%5D%7D%5D%7D%5D%7D) for a sample conversational experience between a user and the AI Assistant for this plugin. + +# Prerequisites + +Before installing and using the **Cancel a Meeting** plugin, ensure the following requirements are met. + +### 1. Google Calendar Connector + +This plugin requires an active **Google Calendar connector** configured with the OAuth 2.0 Authorization Code (User Consent Auth) flow. + +- If you have not already set up the connector, follow the [**Google Calendar Connector Guide**](https://marketplace.moveworks.com/connectors/google-calendar) before proceeding. +- The connector must be fully configured and tested before installing this plugin. + +### 2. Plugin Installation + +Once the connector is ready, follow the [**plugin installation documentation**](https://help.moveworks.com/docs/ai-agent-marketplace-installation) for steps on how to install and activate the plugin in Agent Studio. + +### 3. Google Workspace System Requirements + +### a. End User Permissions + +To cancel a meeting through this plugin, end users must have: + +- A licensed Google Workspace account with Google Calendar enabled +- Organizer access to the event they want to cancel + +**Note:** If the authenticated user is not the organizer of the event, the AI Assistant will warn them that the cancellation will only remove the event from their own calendar and will not affect other attendees. It will also suggest declining the event instead. + +### b. API Permissions + +The Google Calendar connector uses **delegated permissions** to cancel calendar events on behalf of the authenticated user. The following permission is required for this plugin: + +| Permission | Purpose | +| --- | --- | +| `https://www.googleapis.com/auth/calendar` | Delete and update calendar events on the user's primary calendar | + +# Implementation Details + +This plugin works by first identifying the event, then branching based on whether the event is a one-time event or part of a recurring series, and applying the appropriate cancellation. The diagram below gives a high-level picture of that flow, followed by a breakdown of each step. + +### Visual Representation of How the Plugin Works + +![image.png](Cancel%20a%20Meeting/image.png) + +### API Details + +This plugin uses up to five API calls depending on whether the event is recurring. + +### API #1: Get Calendar Events for Time Range + +Based on the user's description in conversation, the AI Assistant searches the user's calendar within a relevant time range to identify the event they want to cancel. + +```bash +curl --request GET \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin={{start_date_range}}&timeMax={{end_date_range}}&singleEvents=true&orderBy=startTime&maxResults=350' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' +``` + +### API #2: Get Current Event by ID + +Retrieves the latest state of the event to be cancelled, including whether it belongs to a recurring series. This determines which cancellation path is taken. + +```bash +curl --request GET \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events/{{event_id}}' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' +``` + +### API #3: Cancel Event + +Deletes the event from Google Calendar. For a one-time event or a single instance of a recurring event, only that specific occurrence is deleted. For a recurring event where the user wants to cancel all instances, the entire series is deleted. All attendees are notified of the cancellation automatically. + +```bash +curl --request DELETE \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events/{{event_id}}' \ + --header 'Authorization: Bearer {{access_token}}' +``` + +**Key nuances:** + +- For a single event, the specific instance ID is used. +- For recurring events, the `recurringEventId` (master series ID) is used, which deletes the entire series. +- Google Calendar sends cancellation notifications to all attendees automatically. + +### API #4: Get Series Master Event + +If the user chooses to cancel this and all following instances of a recurring series (not all instances), the master series event is fetched to retrieve its recurrence rules. + +```bash +curl --request GET \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events/{{recurring_event_id}}' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' +``` + +### API #5: Truncate Recurring Series + +Rather than deleting events, this patches the master series with the new `UNTIL` date to end the recurrence just before the selected instance. This cancels all future occurrences from that point forward without affecting past instances. + +```bash +curl --request PATCH \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events/{{series_master_event_id}}?sendUpdates=all' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'If-Match: {{etag}}' \ + --header 'Content-Type: application/json' \ + --data '{ + "recurrence": ["{{updated_recurrence_rules}}"] + }' +``` + +**Key nuances:** + +- This approach ends the series rather than deleting individual instances, which is consistent with how Google Calendar handles "cancel from here" for recurring events. +- The `If-Match` header uses the `etag` from API #4 to prevent race condition issues. +- `sendUpdates=all` ensures all attendees are notified of the cancellation. + +Now that you understand how the plugin works under the hood, let's walk through what it can and can't do. We recommend reading both sections before going live to ensure the best experience for your users. + +# What Is In Scope for This Plugin? + +This plugin supports the following capabilities: + +- Cancel a one-time event from the authenticated user's primary Google Calendar +- Cancel a recurring event with three deletion policies: + - **This event only** — cancels just the selected instance + - **This and all following events** — ends the recurring series from the selected instance forward + - **All events** — cancels the entire recurring series +- Notify all attendees of the cancellation automatically + +# What Is Out of Scope for This Plugin? + +This plugin does **not** support the following: + +- Cancelling events the authenticated user does not own — the event will only be removed from their own calendar, not from other attendees' calendars. The AI Assistant will warn the user and suggest declining the event instead +- Cancelling events on calendars other than the authenticated user's primary calendar +- Undoing a cancellation once confirmed — deleted events cannot be recovered through this plugin \ No newline at end of file diff --git a/plugins/google-calendar-lookup-availability/Find Availability/image.png b/plugins/google-calendar-lookup-availability/Find Availability/image.png new file mode 100644 index 00000000..d6be1fe8 Binary files /dev/null and b/plugins/google-calendar-lookup-availability/Find Availability/image.png differ diff --git a/plugins/google-calendar-lookup-availability/README.md b/plugins/google-calendar-lookup-availability/README.md index 918ca1e8..df201838 100644 --- a/plugins/google-calendar-lookup-availability/README.md +++ b/plugins/google-calendar-lookup-availability/README.md @@ -1,8 +1,9 @@ --- -availability: IDEA -description: A plugin that returns open slots in Google Calendar. -name: Look up Calendar Availability -purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22startTimestamp%22%3A%2211%3A43+AM%22%2C%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Can+you+find+mutual+availability+with+Ajay+for+a+meeting%3F%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3E%E2%9C%85+Working+on+%3Cb%3EMutual+Availability+%3C%2Fb%3E%3Cbr%3E%E2%8F%B3+Calling+Plugin+%3Cb%3ELookup+Calendar+Availability%3C%2Fb%3E%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22richText%22%3A%22I%27ve+found+a+couple+of+time+slots+for+you+and+Ajay%3A%3Cbr%3E%3Cb%3EOption+1%3A%3C%2Fb%3E+May+10%2C+10%3A00+AM+-+11%3A00+AM%3Cbr%3E%3Cb%3EOption+2%3A%3C%2Fb%3E+May+12%2C+2%3A00+PM+-+3%3A00+PM%3Cbr%3EWould+you+like+to+book+one+of+these+meeting+times%3F%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Please+choose+an+option%3A%22%7D%2C%7B%22richText%22%3A%22%3Cb%3EBook+Meeting%3C%2Fb%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22style%22%3A%22filled%22%2C%22buttonText%22%3A%22Book+Option+1%22%7D%2C%7B%22style%22%3A%22outlined%22%2C%22buttonText%22%3A%22Book+Option+2%22%7D%2C%7B%22style%22%3A%22outlined%22%2C%22buttonText%22%3A%22View+More+Options%22%7D%5D%7D%5D%7D%5D%7D +availability: INSTALLABLE +installation_asset_uuid: 310b98af-3bc1-41d5-9678-12e1ccb20a37 +description: Find a time that works for everyone before scheduling a meeting. +name: Find Availability +purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Find+a+45-minute+slot+for+a+meeting+with+Jordan+Smith+and+Sarah+Jenkins+tomorrow+between+1+PM+and+5+PM.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ESearching+for+Jordan+Smith+and+Sarah+Jenkins...%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+two+people+matching+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E+in+your+directory.+Which+one+would+you+like+to+check%3F%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22moveworks%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Marketing%29%22%7D%2C%7B%22connectorName%22%3A%22moveworks%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Sales%29%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22The+one+in+Marketing.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ERetrieving+calendar+schedules+for+Jordan+Smith+and+Sarah+Jenkins+from+%3Cb%3EGoogle+Calendar%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+checked+the+calendars+for+%3Cstrong%3EJordan+Smith%3C%2Fstrong%3E+and+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E.+Here+are+the+suggested+45-minute+windows+for+tomorrow%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E1%3A00+PM+-+1%3A45+PM%3C%2Fli%3E%3Cli%3E3%3A30+PM+-+4%3A15+PM%3C%2Fli%3E%3Cli%3E4%3A15+PM+-+5%3A00+PM%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EYou+can+use+these+times+to+coordinate+your+meeting+invite+in+%3Cstrong%3EGoogle+Calendar%3C%2Fstrong%3E.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Jordan+Smith%22%7D%2C%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Marketing%29%22%7D%5D%7D%5D%7D%5D%7D solution_tags: - Finance - Other - HR - Other @@ -12,3 +13,174 @@ solution_tags: systems: - google-calendar --- + +# Description + +Find the best time to meet by checking availability across multiple attendees — so you can schedule meetings faster without the back and forth. + +# User Experience Preview + +Please refer to the following [**Purple Chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Find+a+45-minute+slot+for+a+meeting+with+Jordan+Smith+and+Sarah+Jenkins+tomorrow+between+1+PM+and+5+PM.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ESearching+for+Jordan+Smith+and+Sarah+Jenkins...%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+two+people+matching+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E+in+your+directory.+Which+one+would+you+like+to+check%3F%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22moveworks%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Marketing%29%22%7D%2C%7B%22connectorName%22%3A%22moveworks%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Sales%29%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22The+one+in+Marketing.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ERetrieving+calendar+schedules+for+Jordan+Smith+and+Sarah+Jenkins+from+%3Cb%3EGoogle+Calendar%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+checked+the+calendars+for+%3Cstrong%3EJordan+Smith%3C%2Fstrong%3E+and+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E.+Here+are+the+suggested+45-minute+windows+for+tomorrow%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E1%3A00+PM+-+1%3A45+PM%3C%2Fli%3E%3Cli%3E3%3A30+PM+-+4%3A15+PM%3C%2Fli%3E%3Cli%3E4%3A15+PM+-+5%3A00+PM%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EYou+can+use+these+times+to+coordinate+your+meeting+invite+in+%3Cstrong%3EGoogle+Calendar%3C%2Fstrong%3E.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Jordan+Smith%22%7D%2C%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Marketing%29%22%7D%5D%7D%5D%7D%5D%7D) for a sample conversational experience between a user and the AI Assistant for this plugin. + +# Prerequisites + +Before installing and using the **Find Availability** plugin, ensure the following requirements are met. + +### 1. Google Calendar Connector + +This plugin requires an active **Google Calendar connector** configured with the OAuth 2.0 Authorization Code (User Consent Auth) flow. + +- If you have not already set up the connector, follow the [**Google Calendar Connector Guide**](https://marketplace.moveworks.com/connectors/google-calendar) before proceeding. +- The connector must be fully configured and tested before installing this plugin. + +### 2. Plugin Installation + +Once the connector is ready, follow the [**plugin installation documentation**](https://help.moveworks.com/docs/ai-agent-marketplace-installation) for steps on how to install and activate the plugin in Agent Studio. + +### 3. Google Workspace System Requirements + +### a. End User Permissions + +To find availability through this plugin, users must already have access to view calendar data in Google Workspace — the same access required to view calendars in Google Calendar. + +At a minimum, end users must have: + +- A licensed Google Workspace account with Google Calendar enabled +- Permission to view their own calendar + +Note: Event times are automatically displayed in the user's timezone as configured in their Google account. No manual setup is required. + +**Looking up another user's calendar:** + +A user can only retrieve another user's calendar events if one of the following is true: + +- The other user has **explicitly shared their calendar** with the authenticated user in Google Calendar, with at least a `reader` role (full event details) or `freeBusyReader` role (free/busy only, no event details) +- Your **Google Workspace admin has configured org-wide internal calendar sharing**, which sets a default sharing policy across all calendars in the domain — this is the most common reason users can look up colleagues' calendars without explicit sharing + +**Note:** The level of event detail returned depends on the access role granted. A `freeBusyReader` role will only return free/busy status, not event titles or details. Check with your Google Workspace admin to confirm your organization's sharing policy.. + +### b. API Permissions + +The Google Calendar connector uses **delegated permissions** to retrieve calendar data on behalf of the authenticated user. The following permission is required for this plugin: + +| Permission | Purpose | +| --- | --- | +| `https://www.googleapis.com/auth/calendar` | Read calendar events and free/busy information for the user and attendees | + +# Implementation Details + +This plugin works by making a sequence of API calls and running a custom script to compute overlapping free time across all attendees. The diagram below gives a high-level picture of that flow, followed by a breakdown of each step. + +### Visual Representation of How the Plugin Works + +![image.png](Find%20Availability/image.png) + +### API Details + +This plugin uses four API calls and one custom script. + +### API #1: Get Authenticated User's Timezone + +Retrieves the timezone of the authenticated user from their Google Calendar settings. This is used to correctly interpret the search window provided by the user. + +```bash +curl --request GET \ + --url 'https://www.googleapis.com/calendar/v3/users/me/settings/timezone' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' +``` + +### API #2: Get Free/Busy Information + +Retrieves busy time blocks for all attendees within the specified time range. This is the core availability check — it returns only when each attendee is busy, not the details of their events. + +```bash +curl --request POST \ + --url 'https://www.googleapis.com/calendar/v3/freeBusy' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' \ + --data '{ + "timeMin": "{{start_datetime}}", + "timeMax": "{{end_datetime}}", + "timeZone": "{{time_zone}}", + "items": [{"id": "{{email}}"}, ...] + }' +``` + +**Input Arguments:** + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `emails` | list of strings | Yes | List of attendee email addresses to check availability for | +| `start_datetime` | string | Yes | Start of the search range in ISO 8601 format. Example: `2026-01-26T00:00:00-08:00` | +| `end_datetime` | string | Yes | End of the search range in ISO 8601 format. Example: `2026-01-31T00:00:00-08:00` | +| `time_zone` | string | No | Timezone in IANA format, retrieved from API #1. Example: `America/Los_Angeles` | + +**Key nuances:** + +- The free/busy API returns **only busy time blocks** — it does not return event titles, organizers, or any other event details, regardless of calendar sharing settings. +- If an attendee's calendar is not accessible (e.g. not shared), their busy data will be empty and they will appear fully available. This is a known limitation of the Google Calendar free/busy API. + +### API #3: Get Calendar Metadata for Each Attendee + +Retrieves timezone and calendar metadata for each attendee. This is run in parallel for all attendees and is used to correctly localize displayed times per participant. + +```bash +curl --request GET \ + --url 'https://www.googleapis.com/calendar/v3/calendars/{{user_email_addr}}' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' +``` + +**Input Arguments:** + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `user_email_addr` | string | Yes | The email address of the attendee whose calendar metadata is being retrieved | + +### API #4: Get Calendar Events for Each Attendee + +Retrieves full event details for each attendee within the search window. This is run in parallel alongside API #3 and is used to enrich conflict suggestions with event context (e.g. event title, whether the attendee is the organizer, response status). + +```bash +curl --request GET \ + --url 'https://www.googleapis.com/calendar/v3/calendars/{{email}}/events?timeMin={{start_date_range}}&timeMax={{end_date_range}}&singleEvents=true&orderBy=startTime&maxResults=350' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' +``` + +**Input Arguments:** + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `email` | string | Yes | The email address of the attendee whose events are being retrieved | +| `start_date_range` | string | Yes | Start of the time range in ISO 8601 format. Example: `2026-01-26T00:00:00-08:00` | +| `end_date_range` | string | Yes | End of the time range in ISO 8601 format. Example: `2026-01-31T00:00:00-08:00` | + +**Key nuances:** + +- This API call is the same as used in the **Search Calendar Events** plugin. Event details are subject to the same calendar sharing permissions. +- Up to **350 events** are retrieved per attendee per request. + +The AI Assistant uses these API outputs to suggest the best meeting times — prioritizing all-clear slots, and explaining trade-offs for slots with minor conflicts. + +Now that you understand how the plugin works under the hood, let's walk through what it can and can't do. We recommend reading both sections before going live to ensure the best experience for your users. + +# What Is In Scope for This Plugin? + +This plugin supports the following capabilities: + +- Find overlapping free time across multiple attendees within a specified date range +- Suggest **all-clear slots** where all attendees are fully available +- Suggest **slots with minor conflicts**, with context about whose meeting would be affected and whether it could be moved +- Support attendees across **multiple timezones**, with times displayed in each participant's local timezone +- Default meeting duration is **30 minutes** if not specified by the user + +# What Is Out of Scope for This Plugin? + +This plugin does **not** support the following: + +- Booking or creating the meeting — handled by a separate Book a Meeting plugin. +- Attendees whose calendars are not accessible will appear fully available — the plugin cannot flag inaccessible calendars. +- Users with a very high volume of events in the requested time range may receive incomplete conflict data, as the events API is limited to returning a maximum of 350 events per attendee per request. +- Availability across attendees outside your Google Workspace organization may be incomplete, depending on external calendar sharing settings. diff --git a/plugins/google-calendar-search-calendar-events/README.md b/plugins/google-calendar-search-calendar-events/README.md new file mode 100644 index 00000000..f7a03614 --- /dev/null +++ b/plugins/google-calendar-search-calendar-events/README.md @@ -0,0 +1,119 @@ +--- +availability: INSTALLABLE +installation_asset_uuid: 1c1b66a7-3576-4ef8-9437-d076a9cce5a5 +description: See what's on your calendar for any time range, for yourself or shared calendars. +name: Search Calendar Events +purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22What%27s+on+my+calendar+for+tomorrow+morning%3F%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Checking+your+%3Cb%3EGoogle+Calendar%3C%2Fb%3E+for+tomorrow%2C+October+24th...%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EYou+have+3+events+tomorrow+morning%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3E9%3A00+AM%3C%2Fstrong%3E%3A+Engineering+Standup%3C%2Fli%3E%3Cli%3E%3Cstrong%3E10%3A30+AM%3C%2Fstrong%3E%3A+1%3A1+with+%3Ci%3EJordan+Smith%3C%2Fi%3E%3C%2Fli%3E%3Cli%3E%3Cstrong%3E11%3A30+AM%3C%2Fstrong%3E%3A+Project+Titan+Kickoff%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Engineering+Standup%22%7D%2C%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%221%3A1+with+Jordan+Smith%22%7D%2C%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Project+Titan+Kickoff%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Find+my+next+meeting+with+Sarah+about+the+budget+review.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Searching+for+users+named+%5C%22Sarah%5C%22...%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+a+few+people+named+%5C%22Sarah%5C%22+you+frequently+meet+with.+Which+one+did+you+mean%3F%3C%2Fp%3E%3Cul%3E%3Cli%3ESarah+Jenkins+%28Finance%29%3C%2Fli%3E%3Cli%3ESarah+Miller+%28Product%29%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Sarah+Jenkins%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Fetching+meeting+details+from+%3Cb%3EGoogle+Calendar%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+found+your+next+meeting+with+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E+regarding+the+budget.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EMeeting%3A%3C%2Fstrong%3E+FY25+Budget+Alignment%3C%2Fli%3E%3Cli%3E%3Cstrong%3ETime%3A%3C%2Fstrong%3E+Friday%2C+Oct+25+at+2%3A00+PM%3C%2Fli%3E%3Cli%3E%3Cstrong%3ELocation%3A%3C%2Fstrong%3E+Google+Meet%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22FY25+Budget+Alignment%22%7D%5D%7D%5D%7D%5D%7D +solution_tags: +- Productivity +systems: +- google-calendar +--- + +# Description + +Search and retrieve calendar events so you can quickly check what's ahead, stay on top of your schedule, and make decisions with full context. + +# User Experience Preview + +Please refer to the following [**Purple Chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22What%27s+on+my+calendar+for+tomorrow+morning%3F%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Checking+your+%3Cb%3EGoogle+Calendar%3C%2Fb%3E+for+tomorrow%2C+October+24th...%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EYou+have+3+events+tomorrow+morning%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3E9%3A00+AM%3C%2Fstrong%3E%3A+Engineering+Standup%3C%2Fli%3E%3Cli%3E%3Cstrong%3E10%3A30+AM%3C%2Fstrong%3E%3A+1%3A1+with+%3Ci%3EJordan+Smith%3C%2Fi%3E%3C%2Fli%3E%3Cli%3E%3Cstrong%3E11%3A30+AM%3C%2Fstrong%3E%3A+Project+Titan+Kickoff%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Engineering+Standup%22%7D%2C%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%221%3A1+with+Jordan+Smith%22%7D%2C%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Project+Titan+Kickoff%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Find+my+next+meeting+with+Sarah+about+the+budget+review.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Searching+for+users+named+%5C%22Sarah%5C%22...%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+a+few+people+named+%5C%22Sarah%5C%22+you+frequently+meet+with.+Which+one+did+you+mean%3F%3C%2Fp%3E%3Cul%3E%3Cli%3ESarah+Jenkins+%28Finance%29%3C%2Fli%3E%3Cli%3ESarah+Miller+%28Product%29%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Sarah+Jenkins%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Fetching+meeting+details+from+%3Cb%3EGoogle+Calendar%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+found+your+next+meeting+with+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E+regarding+the+budget.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EMeeting%3A%3C%2Fstrong%3E+FY25+Budget+Alignment%3C%2Fli%3E%3Cli%3E%3Cstrong%3ETime%3A%3C%2Fstrong%3E+Friday%2C+Oct+25+at+2%3A00+PM%3C%2Fli%3E%3Cli%3E%3Cstrong%3ELocation%3A%3C%2Fstrong%3E+Google+Meet%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22FY25+Budget+Alignment%22%7D%5D%7D%5D%7D%5D%7D) for a sample conversational experience between a user and the AI Assistant for this plugin. + +## Prerequisites + +Before installing and using the **Search Calendar Events** plugin, ensure the following requirements are met. + +### 1. Google Calendar Connector + +This plugin requires an active **Google Calendar connector** configured with the OAuth 2.0 Authorization Code (User Consent Auth) flow. + +- If you have not already set up the connector, follow the [**Google Calendar Connector Guide**](https://marketplace.moveworks.com/connectors/google-calendar) before proceeding. +- The connector must be fully configured and tested before installing this plugin. + +### 2. Plugin Installation + +Once the connector is ready, follow the [**plugin installation documentation**](https://help.moveworks.com/docs/ai-agent-marketplace-installation) for steps on how to install and activate the plugin in Agent Studio. + +### 3. Google Workspace System Requirements + +### a. End User Permissions + +To search calendar events through this plugin, users must already have access to view calendar data in Google Workspace — the same access required to view events in Google Calendar. + +At a minimum, end users must have: + +- A licensed Google Workspace account with Google Calendar enabled +- Permission to view their own calendar + +Note: Event times are automatically displayed in the user's timezone as configured in their Google account. No manual setup is required. + +**Looking up another user's calendar:** + +A user can only retrieve another user's calendar events if one of the following is true: + +- The other user has **explicitly shared their calendar** with the authenticated user in Google Calendar, with at least a `reader` role (full event details) or `freeBusyReader` role (free/busy only, no event details) +- Your **Google Workspace admin has configured org-wide internal calendar sharing**, which sets a default sharing policy across all calendars in the domain — this is the most common reason users can look up colleagues' calendars without explicit sharing + +**Note:** The level of event detail returned depends on the access role granted. A `freeBusyReader` role will only return free/busy status, not event titles or details. Check with your Google Workspace admin to confirm your organization's sharing policy. + +### b. API Permissions + +The Google Calendar connector uses **delegated permissions** to retrieve calendar data on behalf of the authenticated user. The following permission is required for this plugin: + +| Permission | Purpose | +| --- | --- | +| `https://www.googleapis.com/auth/calendar` | Read and retrieve the user's calendar events | + +## Implementation Details + +This plugin works by making a single API call to retrieve calendar events for a user within a specified time range. + +### Visual Representation of How the Plugin Works + +![image.png](Search%20Calendar%20Events/image.png) + +### API Details + +This plugin uses one Google Calendar API call. + +### API: Get Calendar Events for Time Range + +Retrieves all calendar events for a specified user within a given time range. Uses the `events` endpoint which returns event instances including recurring events within the requested window. + +```bash +curl --request GET \ + --url 'https://www.googleapis.com/calendar/v3/calendars/{{email}}/events?timeMin={{start_date_range}}&timeMax={{end_date_range}}&singleEvents=true&orderBy=startTime&maxResults=350' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' +``` + +**Input Arguments:** + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `email` | string | Yes | The email address of the user whose calendar is being retrieved. Use `primary` to retrieve the authenticated user's own calendar. Example: `john.doe@company.com` | +| `start_date_range` | string | Yes | Start of the time range in ISO 8601 format with timezone offset. Example: `2026-01-26T00:00:00-08:00` | +| `end_date_range` | string | Yes | End of the time range in ISO 8601 format with timezone offset. Example: `2026-01-31T00:00:00-08:00` | + +**Key nuances:** + +- The plugin retrieves up to **350 events** per request. For users with a very high volume of events in the requested range, results may be incomplete. +- Event times are returned in the timezone specified in the event itself. The AI Assistant will display times in the user's local timezone. + +Now that you understand how the plugin works under the hood, let's walk through what it can and can't do. We recommend reading both sections before going live to ensure the best experience for your users. + +## What Is In Scope for This Plugin? + +This plugin supports the following capabilities: + +- Retrieve calendar events for the **authenticated user** within a specified time range +- Retrieve calendar events from **calendars shared with the authenticated user**, provided access has been granted in Google Calendar +- Returns event details including subject, start and end time, location, organizer, attendees, video call link, and response status +- Supports retrieval of `default`, `focusTime`, and `outOfOffice` event types + +## What Is Out of Scope for This Plugin? + +This plugin does **not** support the following: + +- Finding availability or suggesting meeting times — handled by a separate **Find Availability** plugin +- Accessing calendars that have not been shared with the authenticated user in Google Calendar +- Users with a very high volume of events in the requested time range may receive incomplete results, as the API is limited to returning a maximum of **350 events** per request \ No newline at end of file diff --git a/plugins/google-calendar-search-calendar-events/Search Calendar Events/image.png b/plugins/google-calendar-search-calendar-events/Search Calendar Events/image.png new file mode 100644 index 00000000..686ac9bb Binary files /dev/null and b/plugins/google-calendar-search-calendar-events/Search Calendar Events/image.png differ diff --git a/plugins/google-calendar-update-meeting/README.md b/plugins/google-calendar-update-meeting/README.md new file mode 100644 index 00000000..ea630df1 --- /dev/null +++ b/plugins/google-calendar-update-meeting/README.md @@ -0,0 +1,209 @@ +--- +availability: INSTALLABLE +installation_asset_uuid: b7ba7501-39af-42c3-9488-649c49556c06 +description: Updates an existing Google Calendar meeting — reschedule, edit details, manage attendees, or update your response status. +name: Update a Meeting +purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Can+you+change+the+time+for+the+Q4+Roadmap+meeting+tomorrow+to+2+PM%3F+I+also+want+to+add+Dave+Chen.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3EFinding+the+%3Cstrong%3EQ4+Roadmap%3C%2Fstrong%3E+meeting+in+%3Cstrong%3E+Google+Calendar%3C%2Fstrong%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ESearching+for+%3Cstrong%3EDave+Chen%3C%2Fstrong%3E%3C%2Fp%3E%22%2C%22connectorName%22%3A%22moveworks%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EOkay%2C+I%27ve+found+the+meeting+and+%3Cb%3EDave+Chen%3C%2Fb%3E+%28Engineering+Manager%29.+I%27ll+update+the+calendar+event+with+the+following+changes%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ETime%3A%3C%2Fb%3E+10%3A00+AM+%E2%86%92+2%3A00+PM+%2830+minutes%29%3C%2Fli%3E%3Cli%3E%3Cb%3EAdd+Attendee%3A%3C%2Fb%3E+Dave+Chen%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EShould+I+send+the+updated+invitation%3F%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EYes%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3EUpdating+meeting+details+in+%3Cstrong%3EGoogle+Calendar%3C%2Fstrong%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EAll+set%21+I%27ve+updated+the+%3Cb%3EQ4+Roadmap%3C%2Fb%3E+meeting+and+notified+the+attendees+of+the+new+time.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Q4+Roadmap+Meeting%22%7D%5D%7D%5D%7D%5D%7D +solution_tags: +- Finance - Other +- HR - Other +- IT +- Productivity +- Sales +systems: +- google-calendar +--- + +# Description + +Update an existing meeting on your Google Calendar — reschedule, add or remove attendees, change the title or description, update your response status, or modify recurring event settings, all through your AI Assistant. + +# User Experience Preview + +Please refer to the following [**Purple Chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Can+you+change+the+time+for+the+Q4+Roadmap+meeting+tomorrow+to+2+PM%3F+I+also+want+to+add+Dave+Chen.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3EFinding+the+%3Cstrong%3EQ4+Roadmap%3C%2Fstrong%3E+meeting+in+%3Cstrong%3E+Google+Calendar%3C%2Fstrong%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ESearching+for+%3Cstrong%3EDave+Chen%3C%2Fstrong%3E%3C%2Fp%3E%22%2C%22connectorName%22%3A%22moveworks%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EOkay%2C+I%27ve+found+the+meeting+and+%3Cb%3EDave+Chen%3C%2Fb%3E+%28Engineering+Manager%29.+I%27ll+update+the+calendar+event+with+the+following+changes%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ETime%3A%3C%2Fb%3E+10%3A00+AM+%E2%86%92+2%3A00+PM+%2830+minutes%29%3C%2Fli%3E%3Cli%3E%3Cb%3EAdd+Attendee%3A%3C%2Fb%3E+Dave+Chen%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EShould+I+send+the+updated+invitation%3F%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EYes%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3EUpdating+meeting+details+in+%3Cstrong%3EGoogle+Calendar%3C%2Fstrong%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22google-calendar%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EAll+set%21+I%27ve+updated+the+%3Cb%3EQ4+Roadmap%3C%2Fb%3E+meeting+and+notified+the+attendees+of+the+new+time.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22google-calendar%22%2C%22citationTitle%22%3A%22Q4+Roadmap+Meeting%22%7D%5D%7D%5D%7D%5D%7D) for a sample conversational experience between a user and the AI Assistant for this plugin. + +# Prerequisites + +Before installing and using the **Update a Meeting** plugin, ensure the following requirements are met. + +### 1. Google Calendar Connector + +This plugin requires an active **Google Calendar connector** configured with the OAuth 2.0 Authorization Code (User Consent Auth) flow. + +- If you have not already set up the connector, follow the [**Google Calendar Connector Guide**](https://marketplace.moveworks.com/connectors/google-calendar) before proceeding. +- The connector must be fully configured and tested before installing this plugin. + +### 2. Plugin Installation + +Once the connector is ready, follow the [**plugin installation documentation**](https://help.moveworks.com/docs/ai-agent-marketplace-installation) for steps on how to install and activate the plugin in Agent Studio. + +### 3. Google Workspace System Requirements + +### a. End User Permissions + +To update a meeting through this plugin, end users must have: + +- A licensed Google Workspace account with Google Calendar enabled +- Organizer or editor access to the event they want to update + +**Notes:** + +1. If the authenticated user is not the organizer of the event, they can still update their own **response status** (accept, decline, tentative). However, changes to the event itself — such as rescheduling, updating the title, or modifying attendees — will not be reflected for other attendees. The AI Assistant will warn the user if they attempt to update an event they do not own. +2. The plugin automatically retrieves the authenticated user's timezone when rescheduling an event. No manual setup is required. + +### b. API Permissions + +The Google Calendar connector uses **delegated permissions** to update calendar events on behalf of the authenticated user. The following permission is required for this plugin: + +| Permission | Purpose | +| --- | --- | +| `https://www.googleapis.com/auth/calendar` | Read and update calendar events on the user's primary calendar | + +# Implementation Details + +This plugin works by making a sequence of API calls to retrieve the current event state, handle recurring event logic if applicable, and apply the requested updates. The diagram below gives a high-level picture of that flow, followed by a breakdown of each step. + +### Visual Representation of How the Plugin Works + +![image.png](Update%20a%20Meeting/image.png) + +### API Details + +This plugin uses up to seven API calls depending on whether the event is recurring and how the update policy is set. + +### API #1: Get Calendar Events for Time Range + +Before any updates are made, the plugin first needs to identify which event the user wants to update. Based on the user's description in conversation, the AI Assistant searches the user's calendar within a relevant time range and presents matching events for the user to confirm. + +```bash +curl --request GET \\ + --url '}&timeMax={{end_date_range}}&singleEvents=true&orderBy=startTime&maxResults=350' \\ + --header 'Authorization: Bearer {{access_token}}' \\ + --header 'Content-Type: application/json' +``` + +### API #2: Get User's Primary Calendar + +Retrieves the authenticated user's primary calendar details, including their timezone. This only runs if the user is rescheduling the event, so the new start and end times can be correctly anchored to their local timezone. + +```bash +curl --request GET \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' +``` + +### API #3: Get Current Event by ID + +Retrieves the latest state of the event to be updated, including its current attendees, etag, recurrence ID, and timing. This ensures the update is applied to the most recent version of the event and prevents overwriting concurrent changes. + +```bash +curl --request GET \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events/{{event_id}}' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' +``` + +### API #4: Get Series Master Event + +If the event being updated is part of a recurring series, the master event is fetched using the `recurringEventId` from API #2. This is needed to retrieve the series recurrence rules when handling recurring meetings. + +```bash +curl --request GET \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events/{{recurring_event_id}}' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' +``` + +### API #5: Truncate Original Recurring Series + +Google Calendar doesn't have a native "split series" operation. When a user wants to update "this and all following" events, the only way to achieve it is to first end the original series just before the selected instance. + +After the cutoff is calculated, the original recurring series is updated via PATCH to apply the new `UNTIL` date, ending the series just before the selected instance. + +```bash +curl --request PATCH \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events/{{series_master_event_id}}?sendUpdates=all' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'If-Match: {{etag}}' \ + --header 'Content-Type: application/json' \ + --data '{ + "recurrence": ["{{updated_recurrence_rules}}"] + }' +``` + +### API #6: Clone Event as New Series Start + +Once the original series is truncated, a brand new recurring series needs to be created starting from the selected instance. This new series is what the updates are then applied to. + +```bash +curl --request POST \ + --url 'https://www.googleapis.com/calendar/v3/calendars/primary/events' \ + --header 'Authorization: Bearer {{access_token}}' \ + --header 'Content-Type: application/json' \ + --data '{{cloned_event_body}}' +``` + +### API #7: Apply Updates to the Event + +The final PATCH applies all requested changes to the target event. Depending on the recurring event update policy, the target is either the single instance, the new cloned series, or the master series event. + +```bash +curl --request PATCH \\ + --url '}?sendUpdates=all' \\ + --header 'Authorization: Bearer {{access_token}}' \\ + --header 'If-Match: {{etag}}' \\ + --header 'Content-Type: application/json' \\ + --data '{ + "summary": "{{event_title}}", + "description": "{{event_description}}", + "start": {"dateTime": "{{new_start_date_time}}", "timeZone": "{{user_time_zone}}"}, + "end": {"dateTime": "{{new_end_date_time}}", "timeZone": "{{user_time_zone}}"}, + "attendees": [...] + }' +``` + +**Input Arguments:** + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `event_id` | string | No | The event ID in Google Calendar | +| `etag` | string | Yes | Version identifier for the event — required to prevent race condition issues | +| `title` | string | No | The event title | +| `event_description` | string | No | New description for the event. Fully replaces the existing description | +| `start` | object | No | New start time — `dateTime` in ISO 8601 and `timeZone` in IANA format | +| `end` | object | No | New end time — `dateTime` in ISO 8601 and `timeZone` in IANA format | +| `attendees` | list of objects | No | Full attendee list including response status. Anyone not included will be removed | +| `location_display_name` | string | No | Display name of the meeting location | +| `recurrence` | list of strings | No | Recurrence rules in iCal RFC 5545 format | + +**Key nuances:** + +- The `If-Match` header uses the event's `etag` to prevent race condition issues. If the event was modified between the read and the update, the request will fail safely. +- The `sendUpdates=all` query parameter ensures all attendees are notified of any changes via email. +- When updating attendees, the full attendee list must be provided — anyone not included will be removed. The plugin handles this by merging the existing attendee list with additions and removals before sending the update. +- Updating the event description **fully replaces** the existing description. The AI Assistant will merge the new content with the existing description where appropriate. + +Now that you understand how the plugin works under the hood, let's walk through what it can and can't do. We recommend reading both sections before going live to ensure the best experience for your users. + +# What Is In Scope for This Plugin? + +This plugin supports the following capabilities: + +- Reschedule an event to a new start and end time +- Update the event title or description +- Add or remove attendees by name or email address +- Update the authenticated user's response status (accept, decline, tentative) +- Modify recurring events with three update policies: + - **This event only** — updates just the selected instance + - **This and all following events** — splits the series and updates all instances from this point forward + - **All events** — updates the entire recurring series + +# What Is Out of Scope for This Plugin? + +This plugin does **not** support the following: + +- Optional attendees are not currently supported — all attendees are added as required +- Updating events the authenticated user does not own — response status can still be updated, but event changes will not be visible to other attendees. +- Changing the video conferencing provider (e.g. replacing a Zoom link) — the existing link is preserved as-is. +- Cancelling or deleting an event — handled by a separate **Cancel a Meeting** plugin. \ No newline at end of file diff --git a/plugins/google-calendar-update-meeting/Update a Meeting/image.png b/plugins/google-calendar-update-meeting/Update a Meeting/image.png new file mode 100644 index 00000000..69dabaf1 Binary files /dev/null and b/plugins/google-calendar-update-meeting/Update a Meeting/image.png differ