diff --git a/README.md b/README.md index 09293fe..a2eff9e 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ A Google Calendar plugin for Mattermost. ## Documentation -[About](https://docs.mattermost.com/about/mattermost-google-calendar-integration.html) | [Setup](https://docs.mattermost.com/about/setup-mattermost-google-calendar-plugin.html) | [Configuration settings](https://docs.mattermost.com/configure/plugins-configuration-settings.html#google-calendar) | [Usage](https://docs.mattermost.com/collaborate/use-mattermost-google-calendar-plugin.html) +[About]() | [Set up]() | [Configure]() | [Use]() ## Features @@ -40,7 +40,6 @@ A Google Calendar plugin for Mattermost. 2. When the build process finishes the plugin tarball will be available at `dist/com.mattermost.gcal-$(VERSION).tar.gz` 3. In your Mattermost Server, go to **System Console > Plugin Management** and upload the `.tar.gz` file to install the plugin. - ## Acknowledgments * [Hossein Ahmadian-Yazdi](https://github.com/hahmadia) for the previous version of the Google Calendar plugin: diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..84192df --- /dev/null +++ b/docs/about.md @@ -0,0 +1,13 @@ +# Mattermost Google Calendar integration + +The Mattermost Google Calendar integration enables a two-way integration between Mattermost and Google Calendar. With this integration, you can: + +- Create and schedule events, invite guests, and post reminders in channels. +- Schedule a daily summary of your events, or review your events today, tomorrow, or this week. +- Receive an event reminder 5 minutes before a meeting via direct message and linked channel message. +- Automatically set your user status as Away or Do Not Disturb during scheduled events. + +See the following documentation to install and use Mattermost Google Calendar integration: +- [Set up]() the Mattermost Google Calendar integration +- [Configure]() the Mattermost Google Calendar integration +- [Use]() the Mattermost Calendar integration diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..123b9a5 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,23 @@ +# Configure the Mattermost Google Calendar integration + +In Mattermost, configure [Mattermost Google Calendar integration]() by going to **System Console > Plugin Management > Google Calendar**, entering the following values, and selecting **Save**. + +- **Enable Plugin**: Select `true` to enable the plugin for your Mattermost instance. Default `false`. +- **Admin User IDs**: Specify the user IDs who are authorized to manage the plugin in addition to Mattermost system admins. Separate multiple user IDs with commas. Go to **System Console > User Management > Users** to obtain a user’s ID. +- **Copy plugin logs to admins, as bot messages**: The level of detail in log events for the plugin. Can be one of: **None**, **Debug**, **Info**, **Warning**, or **Error**. +- **Display full context for each admin log message**: Specify whether full context is displayed for log messages. +- **Encryption key**: Generate an encryption key used to store data in the database. Regenerating this value forces users to re-link their Google Calendars in Mattermost. +- **Google Application Client ID**: Paste the **Client ID** value from the Google Cloud Console. +- **Google Client Secret**: Paste the **Client Secret** value from the Google Cloud Console. + +## Troubleshooting + +If your Mattermost users encounter issues when connecting calendars, creating events, inviting guests to events, or linking channels, we recommend restarting the plugin as a Mattermost system admin. + +1. Go to **System Console > Plugins > Plugin Management**. + +2. Under **Installed Plugins**, scroll to the **Google Calendar** section, select **Disable**, then wait for the **State** to change to **Not running**. + +3. Select **Enable** and wait for the **State** to change to **Running**. + +See the [Mattermost Google Calendar integration usage]() documentation to learn how to use the Mattermost Google Calendar integration. diff --git a/docs/enable-google-cloud-console-google-calendar-api.png b/docs/enable-google-cloud-console-google-calendar-api.png new file mode 100644 index 0000000..2b53435 Binary files /dev/null and b/docs/enable-google-cloud-console-google-calendar-api.png differ diff --git a/docs/enable-google-cloud-console-google-people-api.png b/docs/enable-google-cloud-console-google-people-api.png new file mode 100644 index 0000000..02e59a7 Binary files /dev/null and b/docs/enable-google-cloud-console-google-people-api.png differ diff --git a/docs/google-cloud-console-OAuth-client-created.png b/docs/google-cloud-console-OAuth-client-created.png new file mode 100644 index 0000000..70b4c8d Binary files /dev/null and b/docs/google-cloud-console-OAuth-client-created.png differ diff --git a/docs/google-cloud-console-OAuth-consent-screen.png b/docs/google-cloud-console-OAuth-consent-screen.png new file mode 100644 index 0000000..d965e70 Binary files /dev/null and b/docs/google-cloud-console-OAuth-consent-screen.png differ diff --git a/docs/google-cloud-console-apis.png b/docs/google-cloud-console-apis.png new file mode 100644 index 0000000..04cbe28 Binary files /dev/null and b/docs/google-cloud-console-apis.png differ diff --git a/docs/google-cloud-console-app-information.png b/docs/google-cloud-console-app-information.png new file mode 100644 index 0000000..9f8154b Binary files /dev/null and b/docs/google-cloud-console-app-information.png differ diff --git a/docs/google-cloud-console-authorized-redirect-uris.png b/docs/google-cloud-console-authorized-redirect-uris.png new file mode 100644 index 0000000..b1306cd Binary files /dev/null and b/docs/google-cloud-console-authorized-redirect-uris.png differ diff --git a/docs/google-cloud-console-create-project.png b/docs/google-cloud-console-create-project.png new file mode 100644 index 0000000..4df9f1a Binary files /dev/null and b/docs/google-cloud-console-create-project.png differ diff --git a/docs/google-cloud-console-developer-contact-information.png b/docs/google-cloud-console-developer-contact-information.png new file mode 100644 index 0000000..9976df2 Binary files /dev/null and b/docs/google-cloud-console-developer-contact-information.png differ diff --git a/docs/google-cloud-console-new-project.png b/docs/google-cloud-console-new-project.png new file mode 100644 index 0000000..24b2d1c Binary files /dev/null and b/docs/google-cloud-console-new-project.png differ diff --git a/docs/google-cloud-console-web-application.png b/docs/google-cloud-console-web-application.png new file mode 100644 index 0000000..dcd414b Binary files /dev/null and b/docs/google-cloud-console-web-application.png differ diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..1b39e97 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,76 @@ +# Set up the Mattermost Google Calendar integration + +Setting up the [Mattermost Google Calendar integration]() requires the following 3 steps: + +1. Mattermost admin: Install the Google Calendar plugin on your Mattermost instance. +2. Google admin: Create a Google Calendar service by creating a Google Cloud project. +3. Mattermost admin: Configure the Mattermost Google Calendar plugin. + +Once setup is complete, see the get started documentation to learn how to use this integration. + +## Install the Mattermost Google Calendar plugin + +To install the Mattermost Google Calendar plugin on your Mattermost server: + +1. Log in to your Mattermost workspace as a system administrator. +2. Download the latest version of the plugin binary release compatible with Mattermost v8.x and later. + +**Tip**: If you are using an earlier version of Mattermost, follow the Mattermost Product Documentation to [upgrade to Mattermost v8.x](https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html) or later. + +## Create a Google Calendar service + +1. In a browser, as a Google admin, create a project in the Google Cloud Console by going to `https://console.cloud.google.com/`. +2. Select the project option in the top left corner of the screen, then select **New Project** option in the top right corner of the popup window. + + ![In Google Cloud Console, select New Project to create up a new project.](google-cloud-console-create-project.png) + + ![Use Google Cloud Console to set up a new project.](google-cloud-console-new-project.png) + +3. When your project is created, go to **APIs & Services** to search for and enable the following 2 services: + + - **Google Calendar API**: Used for anything related to the calendar and events. + + - **Google People API**: Used to link your Mattermost account to your Google account. + + ![In Google Cloud Console, select APIs & Services to search for services to enable.](google-cloud-console-apis.png) + + ![In Google Cloud Console, search for and enable the Google Calendar API.](enable-google-cloud-console-google-calendar-api.png) + + ![In Google Cloud Console, search for and enable the Google People API.](enable-google-cloud-console-google-people-api.png) + +4. Choose how to configure and register the application by selecting the user type as **Internal** or **External**, then select **Create**. + + ![On the OAuth consent screen, configure and register the application as internal or external.](google-cloud-console-OAuth-consent-screen.png) + +5. When prompted, set the following app information: + + - **App name**: `Google Calendar Mattermost Plugin` + - **User support email** + - **Developer contact information** + - Populate the remaining fields as needed. + + ![Configure the consent screen app name and user support email.](google-cloud-console-app-information.png) + + ![Configure the consent screen developer contact information.](google-cloud-console-developer-contact-information.png) + +6. Under **Credentials**, create new OAuth 2.0 credentials by selecting **Create Credentials > OAuth client ID**. + + - Under **Application type**, select **Web Application**. + - Under **Authorized redirect URIs** add `https://(MM_SITE_URL)/plugins/com.mattermost.gcal/oauth2/complete` and replace `MM_SITE_URL` with your Mattermost Server **Site URL**. + + ![Under Credentials, select Web application.](google-cloud-console-web-application.png) + + ![Configure the authorized redirect URI for Mattermost.](google-cloud-console-authorized-redirect-uris.png) + +7. Once the OAuth client is created, make a copy of the **Client ID** and **Client Secret** values for the configuration step. + +![Copy the Client ID and Client secret values. You'll need these values in the configuration step.](google-cloud-console-OAuth-client-created.png) + +See the [Mattermost Google Calendar integration configuration]() documentation to configure the Mattermost Google Calendar integration. + +## Get help + +If you face any issues while installing the Mattermost Google Calendar plugin, you can either: + +- Open a new issue in this [Mattermost Google Calendar GitHub repository](https://github.com/mattermost/mattermost-plugin-google-calendar/issues/new). +- Or, create a new topic in [our peer-to-peer troubleshooting forum](https://forum.mattermost.com/c/trouble-shoot/16). diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..e079b50 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,50 @@ +# Use the Mattermost Google Calendar integration + +The Mattermost Google Calendar plugin enables you to manage events using a two-way integration between Mattermost and Google Calendar without leaving Mattermost. + +## Connect your Google Calendar account to Mattermost + +To use the Mattermost Google Calendar plugin, you must connect your Google Calendar account to Mattermost. You only need to complete this step once. + +1. Log into Mattermost using your credentials. +2. Enter the Mattermost slash command `/gcal connect` in the message text field, and select **Send**. +3. When prompted, select the link to open a new browser window and connect your Google Calendar account to Mattermost. +4. Choose your Google account and enter your Google credentials if you’re not already logged in. +5. Select **Allow**. + +Mattermost confirms when you’ve successfully connected your account. You can close the browser window and return to Mattermost. + +## Customize your Google Calendar plugin + +Mattermost prompts you to configure the plugin based on your personal preferences with the following options. You only need to complete this step once. + +- **Update status**: The plugin can update your [Mattermost availability](https://docs.mattermost.com/preferences/set-your-status-availability.html#set-your-availability) when you have an event scheduled. +- **Get Confirmation**: You can manually confirm every availability change, or the plugin can update your availability automatically. + - If you select Yes, Mattermost confirms your availability update 5 minutes before each event starts. You’ll also be prompted to change your availability back to Online once an event ends. + - Select No to enable the plugin to update your availability automatically. +- **Receive notifications during meetings**: During an event, your availability can be set to Away or No Not Disturb when you’re in a meeting. + - Set your availability to **Away** to clearly communicate to others in Mattermost that you’re unavailable. You’ll continue to receive desktop, email, and push notifications based on your Mattermost notification preferences. + - Set your availability to **Do Not Disturb** to disable all desktop, email, and push notifications. +- **Receive reminders**: You can choose to receive an event reminder 5 minutes before a meeting in a direct message. +- **Daily summary**: You can get a daily summary of your events delivered in a direct message. + +## Create a calendar event + +1. Using a web browser or the desktop app, select a channel name to access additional channel options. +2. Select **Create calendar event**. +3. Specify a subject, date, start time, and end time for the event. You can optionally specify additional event details, including location, guest invitations, description, and a channel where event reminders will be posted. +4. Select **Create**. + +**Notes**: + +- You can invite guests to the event by username if they’ve already connected their Google Calendar account to the Mattermost server, or alternatively by their email address. +- Once you’ve invited guests to an event, guests must accept the event invitation to receive event reminders based on how they’ve customized their Google Calendar plugin preferences. +- When you create an event, it’s based on your timezone. Guests see event details based on their timezone in direct message reminders, but channel reminders display using the event creator’s timezone. + +## Review your upcoming events + +You can use the following Mattermost slash commands to review your upcoming Google Calendar events without leaving Mattermost. +- See a summary of today’s events by entering the slash command `/gcal today` in the message text field. +- See a summary of tomorrow’s events by entering the slash command `/gcal tomorrow` in the message text field. +- See a summary of the week’s events by entering the slash command `/gcal viewcal` in the message text field. +- Update your plugin preferences any time by entering the Mattermost slash command `/gcal settings` in the message text field.