GroupAvail is a Gmail Workspace Add On that searches users' calendars then generates and inserts a formatted list of shared available dates and times into the Gmail message body. The list can then be edited and shared with external customers and partners in the email. Editable text, as shown below, is inserted wherever the cursor is located when the add-on is run:
Available Times (ET)
** Mon (May 1) :**
09:00 am to 11:30 am
12:00 pm to 01:00 pm
** Tue (May 2) :**
09:00 am to 09:30 am
11:30 am to 01:30 pm
04:00 pm to 05:00 pm
This README provides both a high-level overview of usage when installed, and instructions for developers to get started, update, test, debug, deploy and monitor the GroupAvail Gmail AddOn.
Users typically install GroupAvail from the organization's Workspace Marketplace. Developers can also install it to their individual Gmail account. Instructions below describe the developer configuration, installation and deployment processes.
Once installed, a blue calendar image button is added to the bottom of the Gmail Compose window like this:
After entering "To:", "Cc:" and "Bcc:" email addresses (from their organization) into the GMail compose window fields, push the blue button and a pop-up box will prompt the user for more information like this:
After providing the paremeters in the form to update any calendars to search, specify date/time range, timezone and more, selecting the "Insert Availability" button will directly insert the formated schedule availability into the email body wherever the cursor is when the steps above were initiated.
The GroupAvail Add-On also works in users' mobile Gmail application. Instead of starting with a blue icon in the Gmail compose window tray, a menu item "Insert from GroupAvail" is added to the Gmail App Compose menu (the three vertical dots in the upper right corner of the screen.) When the GroupAvail menu item is selected, the behavior of the mobile add-on is identical to the web based version except that native mobile UI look and feel for date and time pickers are used.
The screenshots below show the location of the menu, menu item, then the form and appearance when run.
GroupAvail captures no data except for diagnostic logging and (optionally) Google Analytics for usage. In its logging, GroupAvail makes use of Cloud Logging from Apps Script for diagnostic purposes with the following notable details:
- GroupAvail does not log any user identities, email addresses or meeting descriptions (details are redacted for user email addresses and the description length for meeting descriptions in case matching to specific user supplied data is required outside of the log data.)
- GroupAvail logged debug data includes the user request data (minus identities/email addresses), meeting time slots to allow diagnostics for issues that users report.
- For Google Analytics data when enabled, the analytics ID must be set up for the organization using GroupAvail. When analytics are used, user identiy is not included in the tracking (only the following event occurances and their date/time: Add-On Installation, Add-On removal and Execution of a GroupAvail availability search.)
- GroupAvail currently only supports American and European time zones and date/time formatting output options. The user interface and all output current supports English only.
- Based on conventions in the the initially deployed groups using GroupAvail, the available time search assumes that unaccepted invitations are to be included in available time (unlike the Free/Busy view which treats unaccepted calendar entries as blocked.)
- Start and end times are rounded to the nearest 15 minute interval - Blocked times will be either made later (start time rounded up) or earlier (end time rounded down) to establish availability.
- Schedulee's calendar "Working Hours" settings are not used to limit availability (the Calendar API does not currently make these calendar settings available.) Start end end times are based on GroupAvail parameters only.
- When the email content usees "@" or "+" email addresses to add recipients, an evident defect in either GMail Smart Compose or the Workspace Add On CardService causes the Add On to insert the schedule availability content inside of and above the "+" (or "@") email address. A work around is to move the cursor above the email address(s) entry before launching GroupAvail, and cut/paste the output to the desired location in the email body.
Development of GroupAvail is much the same as any other Apps Script project, with the addition of configuration and deployment steps needed to support installing and running GroupAvail as a Workspace AddOn (as described below) and privileges set up for permission acceptance by users for Calendar and Gmail API access.
First, a few notes on files within the project:
Environment.jscontains global Javascript variables that you will need to tailor to your deployment environment. This includes the domain, error message text, image locations, location of "about" content and more.appsscript.jsonis a manifest that specifies properties for the Add On deployment including Workspace trigger connections to Apps Script functions, security Oauth scopes and related declarations (to allow the user to see and accept required privileges) and information describing how the Add On is to appear in the Gmail interface. This file name and its json specified parameters are prescribed by AppsScript deployment tooling and partially managed in the IDE’s project properties (e.g. GCP project and Cloud Logging settings).GmailAddOn.js: The AddOn UI and triggers that perform capture of user parameters and drive the operation of the actions.GroupAvailLib.js: Includes the core functions that perform the calendar search/merge and extraction of shared availability time for specified users and date/time parameters.TimeSupport.js: Library of supporting functions that handle timezone mapping and differences/conversions in time/date format in the Calendar API, the Addon API and Javascript.TestCases.js: A small set of javascript stubs used during development to incremental build/test portions of the app. Its future could include a more rigorous set of test cases/assertions and ensure better code coverage..claspignore: defines files that are not to be pushed to the Apps Script IDE. Clasp push failes when artifacts, like this README.md file, are included in the directory without this file.
There are two ways to copy GroupAvail code into the Apps Script IDE from this repo. The first is to set up a project in Apps Script IDE and copy/paste the code into the project via the IDE editor. The second is to use clasp, an open source command line tool based on Node.js. Both approaches are described below.
To get started with the current release using the IDE, first create a new Apps Script project. Then manually create each of ".js" files in the Apps Script IDE for the files in this repo. You also will need to enable Show "appsscript.json" manifest file in editor in the Project Settings. Simply copy/paste the Apps Script code and appscript.json contents into each of the files. You will also need to make updates to Environment.js to specify your environment. You may need to update appscript.json file with other environment specific configuration information that includes details of the permissions required by the add on when deployed to Gmail.
You will need to have Node.js and clasp installed as a prerequisite. Instructions for how to ensure the correct Node.js version is installed and the steps to install clasp are available here:
https://developers.google.com/apps-script/guides/clasp
https://codelabs.developers.google.com/codelabs/clasp/#0
You will also need to configure Apps Script to enable use of the API here. https://script.google.com/home/usersettings?pli=1
Next, you can log clasp into Apps Script
clasp login
A browser tab will open with an authentication prompt. After clicking "Allow", the clasp command line wil have an authenticated URL to use for the commands and API.
In the directory where the GroupAvail repo has been cloned.
clasp create --type standalone GroupAvail
Modify Environment.js to your org or individual values. This can also be done in the Apps Script IDE before deploying the app.
And to push the files into App Script:
clasp push
Note that some files are not valid for pushing to Apps Script and not pushed as a result of inclusion in .claspignore.
Once the project is pushed, you can open it in the IDE, deploy to your Gmail envirnment and test (and later publish for all users in your organization's Marketplace if desired.)
At a minumum, you will need to change WORKSPACE_DOMAIN and DOMAINREGEX to match your Worspace environment. These variables are used to match and filter Gmail addresses for access to the Calendar API only for users in your domain.
Optionally, you can include internal site URLs for users, change the error message and configure a Google Analytics ID to track usage.
There are two options for interactive test/development depending on the feature/bug being worked on.
- As a test deployment to your Gmail client: You can install and test the head version of the code as a "Test Deployment" in your connected Gmail account. Select "Deploy", then "Test Deployments" and then "Done" to connect the head version of the code to your Gmail runtime (after a hard refresh of the browser tab). The blue calendar logo will appear at the bottom of the compose window and you can interactively test, modify and view log messages in the IDE in parallel to use in Gmail.
- Interactively in the IDE: A crude collection of test drivers are in TestCases.js. You can select which test case to run at the top of the editor and use either “Run” or “Debug” as needed. In the current code base, the tests are not developed as a comprehensive suite with test correctness assertions, but as stubs that can run specific functions within the Add-On code base without deploying and running the App in Gmail.
You may want to consider how to manage thesimple version string is specified at the top of Environment.js. This string is available in the user interface and in log messages to view end-user version deployed to help you know what is running for users when deployed through your marketplace.
After satisfactory testing using TestCases.js stubs and running the head version in your personal Gmail environment, you will next need to create a production deployment in the Apps Script editor. To start, select “Deploy” (more detail on Deployment is provided here.)
Next, select “New Deployment” from the Deploy menu.
Add a description of the deployment for future IDE reference (this string is not displayed to users.)
Click on the “Deploy” button.
After this step, you will be presented with a long **Deployment ID **string that you must copy and save for later use as described in the Google Cloud project deployment process here.
Log On to your Google Cloud account and navigate to the GroupAvailProd project using the options at the top of the menu (you will separately need to be granted access to the project prior this step.)
Search for **“Google Workspace Marketplace SDK” **in the search bar.
Select “MANAGE”
And then “API CONFIGURATION”
Update the deployment ID with the new deployment identifier from Apps Script Deployment in the field as shown below.
\
Paste the new ID from the Deployment in the Apps Script Editor (Deployment creation is outlined in this section)
Scroll to the bottom of the page and click Save \
A hard browser refresh on the tab/window running Gmail will force the latest deployment to load to the client runtime.
Refresh Button
Users can verify the GroupAvail version running in their Gmail environment by drafting an email and initiating a GroupAvail session. Check the version at the bottom of the GroupAvail pop-up input form to verify that the proper version is running (see the GroupAvail site at GroupAvail for release notes.)
TODO: more to come
A one-pixel image Google Analytics tracker URL can be embedded in the user input form to gather usage statistics. You can set up your own GA project and specify the ID in the Environment file. To disable analytics tracking, the tracker ID can be set to "NONE" which is the default.
The Apps Script code is also instrumented with selected Logging statements (which are routed to Cloud Logging by the Apps Script runtime). Logs are available in the GCP project used above.
No user specific information is collected (including emails of users/schedulees and calendar entry subjects.)