[RELEASE] Google Calendar, Task, and Gmail Search and Gmail Notification Device

Google Calendar, Task, and Gmail Search integrates Hubitat Elevation with your Google Calendar, Tasks, Reminders, and Gmail to automate triggers based on items found matching your search criteria:

  • Optionally toggle a child virtual switch
  • Send Push, SMS, and TTS Notifications
  • Run Rule Machine rule actions

Gmail email notification devices can also be created with this application which will allow you to send email notifications directly from your Hubitat Elevation hub using the Google APIs without requiring a "middle man" server.

Special thanks to Mike Nestor and Anthony Pastor, members of the SmartThings Community, who originally created this app and @cometfish for porting their code to work on HE in 2019. I have taken this code and refactored it to make it simpler for my personal needs and hope it is useful for others. I have purposely published the code in the HubitatCommunity GitHub repository in hopes that this remains community code and others contribute to it as well.

Differences from SmartThings/Original Ported Version
  • Simpler solution using a switch instead of presence and contact sensor
    • Ability to set a default value of the switch that is used when there is no calendar entry. The switch will toggle from that value if there is a calendar event match. This is useful if you prefer the switch to be of a certain value in dependent rules and apps or viewing on a dashboard.
    • Simple Automation, Motion Lighting, etc apps allow restrictions based on the state of a switch and the GCal Switch can be used for those restrictions.
  • Original version uses Google Search features to find matching events and in my own use of it had many problems where an event was linked that shouldn't have been.
    • This version moved the processing of the search string match to HE.
    • Added ability to search location as well for a match.
  • Ability to enter multiple search strings separated by commas for the same switch:
    • By default the search string entered will be matched to the google calendar title/location using a starts with match
    • A contains search can be entered by inserting an asterisk within the search string. For example to match both Kids No School and Kids Late School, simply enter Kids*School

This app allows you to create "search triggers" that will query Google Calendar, Tasks and Gmail for items that match a defined search string:

  • Each Search Trigger child app will optionally create a virtual switch that will toggle based on results of the query
  • Within the switch you can set a default value of the switch that is used when there is no calendar entry and the switch will toggle from that value if there is a calendar match. This is useful if you prefer the switch to be of a certain value in dependent rules and apps or viewing on a dashboard.
  • Ability to enter multiple search strings separated by commas for the same search
    • By default the search string entered will be matched to the google item using a starts with match
    • A contains search can be entered by inserting an asterisk within the search string. For example to match both Kids No School and Kids Late School, simply enter Kids*School
  • Set the search range of the query. By default, items from the time of search through the end of the current day are collected. Adjust this setting to expand the search to the end of the following day or a set number of hours from the time of search.
  • Scheduling:
    • Once Per Day at designated time
    • Every N Hours
    • Every N Minutes
    • Cron Expression
    • Utilize Rule Machine rules to invoke the "refresh" command on your GCal Switch by a set interval and perform the same action.
  • Additional Actions
    • Send notifications with dynamic content from the matched Google item
    • Run rule actions based on the schedule of the Google Item. This is useful when you choose not to create a child switch.
    • Dynamically control a defined list of switches from text within the Google item.
      • For example: 'Turn off bedroom fan and turn on bedroom overhead lights, bedroom lamps, and bedroom tv' to turn off and on several switches
      • Basically you set a list of switches that you would want to control via dynamic text and then in your Calendar Events, Tasks, or Gmail you can use text to describe the switches you wish to toggle. The app will match the name to your switch list and perform those actions.
      • Added support for International users by entering the translations for "on" and "off"
  • Dashboard Support
    • The child switch driver includes the Pushable Button capability allowing you to add the switch to a Hubitat Dashboard via button template. Pushing the button will immediately query Google for new items matching the parent GCal Search Trigger's search criteria.

Example:

I have personally found this useful for the following scenarios:

  • Kids School Holidays - where switches will remain off when mode changes to Day
  • Parent Traveling - where the house will shut down differently based on one parent traveling
  • Guests - guest room lights will not turn off if a guest is staying over
  • USPS Holidays - mailbox alert to remind myself and neighbors that no mail will arrive today

Code and Installation Instructions:

26 Likes

Version History:

Version 1
  • v1.0.0: Initial Release
  • v1.1.0: Added ability to search the location attribute of a calendar entry within a calendar search trigger.
    • Use case example: I have a motion sensor that turns on the lights in my crawl space and off after a set period of time once there is no active motion. Twice a year my HVAC company comes for preventative maintenance and they complain the lights are turning off on them. I now have a GCal Switch that queries my calendar for an entry where the location is "Crawl" and will turn on the switch that will disable this motion lighting app.
  • v1.2.0: Now support toggling switch at scheduled future time based on calendar event start and end times.
    • If a calendar event match is found and the start time is after the current time, a trigger will be scheduled to toggle the switch at the calendar event start and end times.
    • Each time refresh and poll are executed, any scheduled are removed and re-evaluated based on the calendar events and search criteria.
    • Only files you need to update are the parent GCal Search app and the GCal Switch driver
  • v1.2.1: Fixed a few bugs with scheduling of future events.
  • v1.3.0
    • Calendar names will now default to the "summaryOverride" value if available. This is a custom name applied to the calendar within Google.
    • Based on popular request, searches can now be periodic every N hours, every N minutes, or via Cron expression string along with previous once a day.
    • Only files you need to update are the parent GCal Search app and the GCal Search Trigger child app
  • v1.4.0: Added offset preference for start and end times so that the switch can toggle N number of minutes before/after event start and/or end dates based on request.
  • v1.4.1:
    • Fixed bug and error in log when an offset was null in the search trigger app
    • Added ability to perform an exact match search where you prefix your search string with "="
    • Added ability to turn off case sensitive matching
    • Cleaned up help text within the GCal Search Trigger app
    • All files have been updated in GitHub
Version 2
  • v2.0.0:
    • Added necessary files to integrate this with Hubitat Package Manager for installation and updates. Install and updates can now be done via HPM.
    • Added ability to configure the end date for the calendar query. Options include end of current day, end of next day, or a set number of hours from the current time. Request from halfrican.ak
    • Improved UI formatting and instructional text within the parent and child apps.
  • v2.1.1:
    • Fixed bug with all day events and dates where calendar timezone doesn't match hub timezone. Thanks mikee385 for the pull request!
    • Added logic to adjust the eventEndTime if there are sequential events that match the search string. This prevents the switch from turning off and on between events if periodic schedule is set. Thanks mikee385 for the suggestion here.
    • HPM updated with new manifest so you should be prompted to update.
  • v2.2.1:
    • This release will require that you open one of the Search Trigger child apps and click done to save settings for caching purposes.
    • Fixed bug with Number of Hours from Current Time preference not showing.
    • Refactored caching functionality to work with Search range preferences.
    • Caching may have been used before that didn't contain all events. Reworded instructions a bit to be clearer.
    • HPM updated with new manifest so you should be prompted to update.
  • v2.2.2: Fixed a bug that was reported with an error that occurred on a new install. HPM has been updated.
  • v2.2.3:
    • Fixed bug with caching of events.
    • Fixed bug with getting end date of search range and cast error. If required endTimeHours preference is not set for some reason, it will default to end of current day.
    • Added toggle to hide offset preferences to help reduce confusion on this optional feature.
  • v2.3.1:
    • Added an option to use Google Query Matching. By default calendar event matching is done by the HE hub and it allows multiple search strings. Caching of events is not supported when using Google query matching.
    • Added ability to prefix search words with a "-" (minus) to exclude events with this word in the title or location. Thanks neerav.modi
    • Added ability to exclude All Day Events (default is to include) Thanks neerav.modi
    • Added ability to set whether sequential events will expand the scheduling of when the child switch turns off. If this is turned off, the switch will turn off 1 minute in advance of calendar event end time to ensure the toggle can happen. You can override this via the Event End Offset setting.
    • Added ability to toggle/sync additional switches. A list of switches can be designated to synchronize and a list of switches can be designated to reverse the switch state as the child calendar switch is toggled. Thanks rakeshg
  • v2.4.1 Added the following new preferences in the GCal Search Trigger app:
    • Delay toggle to event start: By default the switch will toggle based on the matching Event Start Time. If this setting is set to false, the switch will toggle at the time a match by this search trigger. The switch will continue to toggle again based on the Event End Time.
    • Date Format: You can now choose the Date format for dates set within the child GCal Switch. By default the time format set within the hub settings will be used however you may choose "Other" and enter your own custom date/time format.
    • Thanks sburke781 for the suggestions!
  • v2.5.1:
    • New Feature: If Event End Offset is entered, this amount of time will be included when querying for new calendar events. For example if you entered an offset of 30 minutes so the switch stays on 30 additional minutes, during a calendar search an additional -30 minutes is added to the query so that any events that just ended 30 minutes ago are still included so the switch will not turn off. This is useful for frequent periodic queries. Thanks andrewL.
    • Bug Fix: The "Expand end date for sequential events" included in v2.X only worked for HE based event matching. Corrected the code to also work when Google Query Matching is enabled.
    • HPM updated with new manifest so you should be prompted to update.
  • v2.5.2
    • New Feature: If match is an All Day Event and the 'Expand end date for sequential events' is turned on, it will add a second to the Event End Timestamp so it can match potential next events and prevent the switch from toggling prematurely. Thanks rakeshg
    • HPM updated with new manifest so you should be prompted to update.
  • v2.5.3: Fixed a bug with syncing additional switches and the matched event is multi-day. Thanks rvrolyk!
Version 3
  • v3.1.0: Major Update! For existing installations, please follow these upgrade instructions.
    • Complete rewrite of the OAuth code. After upgrading
      • Your existing calendar searches should continue to work if you don't have time to follow the steps above immediately after upgrading. Please note that you will not be able to edit existing search triggers until you do complete the upgrade steps.
      • You will need to setup a new Web application credential in the Google Console and reauthorize GCal Search
    • Extended search capabilities to also include Google Tasks and Google Reminders
    • Child switch is now optional
    • Added Additional Actions to invoke Notifications and run Rule Machine actions directly from a search trigger
    • Thank you maxnet21 for your ideas about tasks and help testing.
  • v3.1.1
    • Fixed bug with trigger notifications sending the offset date instead of the actual date. Thank you lpakula for letting me know!
    • Added next matched item details at the top of the search trigger app. This is especially useful when you don't have a child switch where you can see what the search trigger is matching against.
  • v3.1.2
    • Fixed issue with additional actions firing for every periodic update if a Google item match is found.
    • Added option to toggle Rule Private Boolean for calendar events at start and end of event.
  • v3.2.0
    • Added ability to dynamically control a defined list of switches from text within the Google Calendar event, task and reminder. For example: 'Turn off bedroom fan and turn on bedroom overhead lights, bedroom lamps, and bedroom tv' to turn off and on several switches
    • Added description text logging to child GCal switch
    • Additional error handling if OAuth hasn't been enabled on the parent GCal Search app
    • Added ability to rename the parent GCal Search app. This is useful if you wish to search multiple Google Accounts where multiple installations if this app are required.
  • v3.2.1-2
    • Completing a reminder will now complete all past due reminders matching search criteria. This is useful for daily repeating tasks that don't always get completed and stack up. The taskID on the child switch will reflect multiple IDs separated by comma.
  • v3.2.3
    • Fixed issue with Additional Actions not running or running multiple times if polling is set frequently and item hasn't changed. Thanks JamesTX10
  • v3.2.4
    • Fixed an issue with Unparseable date error as well as error when including eventAllDay in Additional Action Messages. Thanks danabw
  • v3.3.0
    • Added new 'Include details from all matching items?' preference: default value is off but when enabled Additional Actions Notifications will include details from all matching items. Thanks danabw for the idea.
    • Added Calendar Event description to the child GCal switch. Thanks Darwin for the idea.
    • Improved code to prevent errors during version upgrades and clicking done on the parent GCal Search app is no longer required
  • v3.3.1
    • During a new install, the parent GCal Search app forces you to click Done so the app shows up in the installed app list.
    • Enhanced the Additional Actions code to ensure that actions are scheduled at the correct times and aren't duplicated. Thank you es_ferret for bringing this issue to my attention and helping with testing.
  • v3.3.2
    • Fixed bug where scheduled jobs still triggered when the search trigger was paused. Thank you es_ferret for letting me know about this!
  • v3.4.0-1 - Calendar Event Reminder Inclusion
    • Reminder value can also be used as a dynamic start offset to modify the scheduled start either X minutes before or after the event start time.
    • Added reminder notification option for calendar events - found in the Additional Action Preferences section.
    • See post 400 below on how to set a default reminder value for all events within your Google calendars. Individual events can have an override as well.
  • v3.4.2
    • Fixed an issue with additional action notifications duplicating notifications if an event attribute changed that wasn't part of the message. Thank you es_ferret for letting me know about this!
  • v3.5.0
    • Added search capabilities for Gmail. Like calendar, tasks, and reminders automations can be fired based on finding a matching email.
    • Added Gmail Notification Device driver which will allow you to send Gmail messages directly from the hub using the Google APIs.
  • v3.5.1
    • Changed instructional verbiage based on community suggestions thanks danabw
    • Updated Gmail Notification Device section to use new table format for displaying existing devices and adding new ones
    • Create Notification Device button now displays after entering name and email address to reduce confusion
  • v3.5.2-3
    • Fixed NullPointerException error when the title/subject of a Google item is blank. Will now default to 'none' if one isn't set.
  • v3.5.4
    • Added Pushable Button capability to the GCal Switch driver to allow a refresh to be invoked from a HE Dashboard via push command. Thanks nfd0800 for the idea!
  • v3.5.5-6
    • Fixed info logging in the child GCal Switch where it defaulted to using the device name and not label. If a device label is set it will use it instead.
    • Removed PERSONAL label from Gmail search. Thought this was a default label but after working with pgagne I realized it is not so removed it.
    • Added better instructions for Gmail searches and changed a few default values when adding new Gmail search triggers
  • v3.5.7
    • Fixed issue with Gmail search and use of custom labels. Thanks mboisson
  • v4.0.0
    • Re-release of Gmail Integration as I should have upped the version number when I added it months ago
    • Added search capabilities for Gmail. Like calendar, tasks, and reminders automations can be fired based on finding a matching email.
    • Added Gmail Notification Device driver which will allow you to send Gmail messages directly from the hub using the Google APIs.
      • When creating a new Gmail Notification Device you must set a default subject and recipient email to use with notifications sent with this device.
      • The Recipient (To) can dynamically be set via the notification message. Multiple recipients can be included separated by a semicolon
      • The Subject of the email can be dynamically set within the notification message.
      • Files from the hub's File Manager can be included in Gmail notification messages as an attachment if specified within the notification message. Thank you to albertjmulder for the idea and DubbyDad for further encouragement to add this feature.
      • Please see the instructional text within the parent GCal Search app for use and example of this feature.
    • Added Pushable Button capability to the GCal Switch driver to allow a refresh to be invoked from a HE Dashboard via push command.
  • v4.1.0
    • Fixed NullPointerException error in parent GCal Search app - thank you Aggolden for reporting this bug
    • Added the ability to include emoji's within Gmail notification email subjects - thank you albertjmulder for the suggestion
    • Added the ability to specify a from Display Name within Gmail notification messages. For example Hubitat <email@gmail.com> - thank you albertjmulder for the suggestion
      • New optional preference added to the Gmail notification driver
      • Ability to dynamically set from display name in the notification message with "From:" prefix
  • v4.2.0
    • Fixed issue sending txt files via Gmail notification device - thank you bbacon19 for reporting this bug
  • v4.3.0
    • Added the ability to parse text from Google items and update Hub Variables with those values. For example Airbnb includes the renter's last 4 digits of their phone number and that can be parsed from the calendar event to update a Hub Variable with that value. Then a rule can add it to a lock at a scheduled time. Thank you salieri for the suggestion!
  • v4.4.0
    • Fixed bug to address situation when hub and target Google Calendar are set to different time zones. - thank you salieri for reporting this bug
    • If a GCal Search Trigger has a child switch, the Last Refreshed text at the very top will be a clickable link so you can quickly navigate to that child device.
    • A new 'Use offset for start and end timestamps' preference was added to the GCal Switch driver that will control whether the eventStartTime and eventEndTime attributes use the offset timestamps versus the actual event timestamps. Thanks salieri for the suggestion!
    • Added 'Debug authentication' setting to the parent GCal Search app that controls debug logging of the authentication to the Google APIs since this can contain sensitive information if shared. This defaults to false.
    • Child GCal Search Trigger now passes its app label to the parent GCal Search app so you can distinguish debug logging if multiple search triggers are scheduled at the same time.
  • v4.4.1
    • Added new 'Include hub's timezone in calendar query' preference that makes the change made in v4.4.0 optional. Default is disabled. Thanks lpakula for reporting the issue.
    • Added setting to toggle the switches controlled by Additional Actions Control switches at the scheduled end of the calendar event.
  • v4.4.2
    • Fixed a NullPointerException error when searching for Gmail messages. Thank you pgagne for reporting this bug.
  • v4.4.3
    • Fixed NullPointerException error after enabling a child switch on an existing search trigger. Thanks bbacon19 for reporting this!
    • Fixed 'bad character in base64 value on line 1184 (method getNextMessages)' error when parsing Gmail emails. Thanks pgagne for reporting this!
    • Fixed issue when running Rule Machine rules at calendar event end and private boolean not getting set prior to rule actions running again.
  • v4.4.4
    • Fixed NullPointerException when search finds no results from Google. Thanks bbacon19 for reporting this!
    • Added error handling for HttpHostConnectException errors (internet outages) where previous found item will continue working throughout outage based on previous gathered details. Thanks salieri for reporting this!
  • v4.5.0
    • Added new nextEvent attribute to the child switch to provide details of next events found from calendar searches. Setting added in the search trigger to define what detail is included. Thanks domsim00 for the idea
    • Google deprecated Reminders and migrated this functionality to Tasks. Removed the reminder code from this app and if you had previously setup a Reminder search it will no longer work and an error will be logged notifying you of that.
      • Unfortunately the Google task API doesn't expose the time of a due date (defaults to midnight) so this is a step back in functionality.
      • Please see this Issue Tracker from 2019 and vote to have due date time added to the Task API
    • Refactored the error handling when the hub is having challenges reaching the Google APIs or if they are slow and timeout. Any existing items found will continue to be processed based on previous gathered data. Thanks salieri for reporting this!
  • v4.5.1
    • Fixed NullPointerException error when using Additional Action Notifications. Thanks themarkwilliams for reporting this!
  • v4.6.0
    • Added ability to turn on and off other existing switches in the Additional Actions settings. A child switch is no longer required to do so. If this was setup previously, the upgrade process will move the settings to Additional Actions. Thanks @mboisson for the suggestion!
    • Added the ability to enter '\n' within a Gmail notification message which will cause a carriage return within the email sent. In recent versions HTML is automatically stripped so this is a work around for new lines within email notifications. Thanks @bpkeeber for the idea!
    • When selecting switches in the various Additional Actions settings, the filter box is now available to quickly find specific switches.
  • v4.6.1
    • Fixed NullPointerException while loading the parent GCal Search app when a Gmail Notification device is disabled. Thank you dpanagiotou for reporting this!
    • Added additional error handling in the upgradeSettings app to prevent errors. Thank you rakeshg for reporting this!
  • v4.6.2
    • Fixed issue with Additional Actions Control Switches where switches listed were toggling at the event scheduled event even though the setting was set to false. Thank you @kbo5000 for reporting this bug!
  • v4.6.3
    • Fixed issue in Search Triggers where 'Enable descriptionText logging' wasn't available for all Additional Action options. Thanks @a.mcdear for reporting this!
    • Added option to disable toggling of switches at the end of a calendar event when using Additional Action Toggle Switches capability. Thanks @a.mcdear for suggesting this!
11 Likes

This is interesting. Didn't Google change things in regards to access to api?

Not that I am aware of. While creating the documentation I used a few of my gmail accounts to test this and all work fine. The app will never be officially published by Google and it’s used for personal use. My primary account has worked for over 5 years now.

1 Like

I'll have to check it out.

How does this differ from the one ported by @cometfish? I was using that before covid…

Summarized it here:

1 Like

Excellent work!

2 Likes

Seems like I can finally shed my dependence on IFTTT now. I have been running that service for this purpose.

2 Likes

Would this work for a public Google calendar rather than my own?

(The city of Columbus makes public their trash/recycling calendar, and I'd like to be able to integrate it with my Hubitat. I'm new, so I can't post links. Add a dot gov for the domain 311.columbus/AddrLookupnew.aspx)

If you can subscribe to that public calendar in your own google calendar you should be able to use it.

3 Likes

Hey neighbor! (Also a Columbus resident).
You can input your address on that page and get a calendar that can be added to your Google Calendar. Then you can use this like normal!

V1.1 posted to Github that allows querying the location attribute of a calendar entry. Please see details in post 2 above.

1 Like

Based in the UK I have been looking for this for ages, thank you to everyone who contributed to this.

I have installed the Driver code but cannot see how to add the Apps code, is it possible there is a video online to show the full process? I am happy to contribute ( pay ) for assistance.
Many thanks
Paul

Apps are similar process as Drivers but in a different section. Here is a Docs article on how to do it:
https://docs.hubitat.com/index.php?title=How_to_Install_Custom_Apps

There are two apps and here are the import URLs to make it easier:
Parent App: https://raw.githubusercontent.com/HubitatCommunity/Google_Calendar_Search/main/Apps/GCal_Search.groovy
Child App: https://raw.githubusercontent.com/HubitatCommunity/Google_Calendar_Search/main/Apps/GCal_Search_Trigger.groovy

Thank you Ritchie

I appreciate your time as will investigate this later.

Kindest regards
Paul

1 Like

I got as far as creating the Google API Client ID but could not see where to create the Google API Client Secret

I am happy to pay for someone's time on this, I want to be able to

  1. Read the diary for today
  2. Another routine reads it for 90 days from today
  3. Another reads it for 30 days from today and if keywords exist such as "reserved" or "wedding" then to have Echo Speaks ( installed and working ) to alert me to the content so I can take action.

The logic is that I have an online diary booking system that brings in our accommodation bookings, we mark off our accommodation in the hope of getting a wedding so the word "reserved" will appear in the diary. Within three months it's unlikely we will get a wedding booking in so I then want to release the room.

On the day I really want Alexa to notify me at intervals of the pending appointments.

Many thanks
Paul

Does this have a "power meter" like gcal. gcal takes up quite a lot of state size because of the power meter. All I need is a virtual switch. it's how I've always used gcal anyway. I just don't like the constant on/off power meter.

Sorry for being obtuse, but what are you asking? Not following the correlation between power and a calendar :rofl:

IDK but it is a thing lol.