GoogleCalendarTools is a command-line application written in Java. It uses the Google Calendar API to process larger amounts of Calendar entries which is tedious to do in Google Calendar or on a Smartphone.
I have calendar entries dating back to the year 2000 on my Google Calendar. My smartphone only syncs past events one year back. I wanted to have all my calendar entries also synced to my smartphone. Looking for a solution I came across this and this. There, the solution is sketched as exporting all the calendar entries and re-importing them.
I did this but I imported them on the smartphone instead of using the Web UI. I don’t know if it makes a difference or not if this is done on the Web Google Calendar itself but after importing them I had about 8000 duplicates. To get rid of this mess I was looking for a solution that could be scripted. I found this post and experimented with some App Scripts.
I quickly learned that it would be easier for me to use the Java Calendar API for this. This is how this tool was born.
In order to use this application it is necessary to enable the Google Calendar API for your account, create a Google Cloud project and download a client configuration file (named credentials.json or similar).
You can follow the steps outlined in this Java Quickstart guide. In step 1 there is a button to create a new Cloud Platform project and automatically enable the Google Calendar API. Download the client configuration and save it for later. As an alternative you can do these steps manually in the Google Cloud Console.
GoogleCalendarTools supports the following functionality:
-
Listing the calendars of your account. This is useful to get the calendar ID associated with the calendars. You need them for the other commands. The primary calendar can be used without knowing the real ID by using the artifical ID
primary. This is also the default for all commands needing a calendar ID when non is passed to the tool. -
Listing events of a calendar. There is an option to switch between summary or detailed results.
-
Touching calendars entries. This changes the summary of the calendar entry and reverts that change again. This will mark the calendar entry as being changed and it will thus be synched (to a smartphone for example) even if it is way back in the past.
-
Deleting calendar entries. This is useful for batch-deleting entries.
-
Moving calendar entries. This allows for moving calendar entries from one calendar to another (e.g. from private to work calendar).
-
Removing the color associated with a calendar entry. Each Google Calendar has a color associated with it. This color can be overriden on each calendar entry. Use this command to reset the custom color for calendar entries.
-
The tool batches API requests. You can set the batch size being used. Each API call inside a batch counts as a separate request against the quota though.
-
The calendar ID to read from can be set.
-
When a command is used that will modify calendar entries, the tool will first read entries from the calendar specified (to get the IDs of the entries that should be modified). In a second phase the entries are manipulated. You can tell the tool to do a dry-run to make sure the correct entries will be processed. In dry-run mode no manipulations will be done.
-
The client configuration file must be passed to the tool.
-
Google APIs have a rate limit / quota. By default currently 500 API calls per 100 seconds are allowed. A rate limit to use can be set (number of API calles per second). There is a way to increase the quota but it never worked for me when I tried (tips are welcome).
-
A read-timeout for API calls can be specified.
GoogleCalendarTools uses Picocli to parse the command line and a RateLimiter to make sure the API call quota is not overrun. In addition it support automatic retries with exponential backoff in case of API errors. The Gradle Shadow plugin is used to build an uber JAR.
-
Clone the repository
-
Make sure a Java SDK version 8 is available
-
Run
./gradlew build
-
Run the generated application from directory
libsby invoking
java -jar google-calendar-tools-{version}-all.jar
-
You can also unpack the generated distribution archives
build\distributions\google-calendar-tools-shadow-1.0.0.tarandbuild\distributions\google-calendar-tools-shadow-1.0.0.zipand start the application using the batch scripts provided in thebinsubdirectory of the archive. -
When you run the tool for the first time you will need to grant access to your Google Account to the application. For this, a browser window will open where you do that. Once, permissions have been granted, the tokens used by the tool are stored in a subdirectory named tokens. If this directory is deleted, you will need to grant access rights again.
The samples assume the file credentials.json is placed in the same directory as the tool.
The sample uses a specific calendar (-c) and restricts the calendar entries being processed to be between 2005-09-29 (-s) and 2018-07-31 (-e).
-f=credentials.json -r=3 -t=10000 [email protected] touch -s=2005-09-29 -e=2018-07-31"
The sample uses the default (primary) calendar.
The target calendar of the move operation is specified (-t).
Only calendar entries between 2006-05-01 (-s) and 2006-10-16 (-e) are processed.
In addition, only entries that contain the keyword IOD (-k) are processed.
The --timed-events option tells the tool to not process events with a specific time specified but only all-day-events.
-f=credentials.json move -s=2006-05-01 -e=2006-10-16 -k=IOD --timed-events=false [email protected]
The sample uses the default (primary) calendar.
Only calendar entries between 2000-05-01 (-s) and 2019-10-16 (-e) are processed.
In addition, only entries that contain the keyword Timereport (-k) are deleted.
-f=credentials.json delete -s=2000-05-01 -e=2019-10-16 -k=Timereport
The sample uses the default (primary) calendar.
Only calendar entries between 2000-05-01 (-s) and 2019-10-16 (-e) are processed.
A batch size of 30 is used (-b).
This will cause the API call to retrieve the calendar entries to also return the same number of entries per call.
The output will be detailed (-d).
-f=credentials.json -b=30 list -s=2000-05-01 -e=2019-10-16 -d
The sample uses a specific calendar (-c).
Only calendar entries between 2001-10-12 (-s) and 2019-10-16 (-e) are processed.
In addition, only entries that contain the phrase False Color (-k) are processed.
Only entries that are currently set to the color 16A765 (HEX notation) (-c) are processed.
-f=credentials.json [email protected] removeColor -s=2001-10-12 -e=2019-10-16 -k="False Color" -c=16A765
You can force colored console output by passing -Dpicocli.ansi=true to the JVM in case the color-capability of your shell is not recognized automatically.
For more information about the capabilities of picocli refer to picocli.info website.