acmutd / calendar-converter

Convert the ACM event spreadsheet to ics

calendar-converter

A script to automatically convert ACM UTD's event spreadsheet to the iCalendar format, so it can be displayed as a calendar (like in someone's Google Calendar or on acmutd.co/events).

How it works

Using GitHub Actions, this script runs every 24 hours. The core of the script is given by the few lines at the end:

fetchSpreadsheet()
  .then(spreadsheetToEvents)
  .then(eventsToIcs)
  .then(console.log)

It is a pipeline that

1. Fetches the spreadsheet data using the Google Sheets API
2. Converts the raw data (which is just any[][]) to a more structured schema (Event[])
3. Produces a string in the iCalendar format from that array of Events using the ics package
4. Sends that string to stdout

The output of the script is redirected to a file which is then committed and pushed to the ics branch of this repository. The calendar can then be accessed with the raw link to that file (which we have a vanity link for: https://content.acmutd.co/events).

The remaining details are explained in comments in the source code.

Set up

For the script to run correctly, some set up is necessary in both Google Workspace (G Suite) and GitHub Actions.

Google Workspace

The script fetches data using the Google Spreadsheet API. As such, it requires authorization to access the spreadsheet. This requires

1. A GCP project with the Google Sheets API enabled (note for ACM officers: this is the "Calendar Converter" project)
2. A service account on that project
3. Sharing the spreadsheet with the service account (the service account has an email address which you can share to like normal)

GitHub Actions

The script utilizes two Environment secrets which must be set before running:

• EVENT_SPREADSHEET_ID: The ID of the event spreadsheet. This can be found in the URL to the sheet (https://docs.google.com/spreadsheets/d/THIS_IS_THE_ID/)
• GCP_SA_KEY: The service account authentication key. It should be the raw JSON string (i.e., not a file name). See setup-gcloud for more info.

Local Development

Clone the repo, run npm install, build with npm run build, run with npm run start. It might be more convenient to run the compiler in watch mode which can be done with npm run build -- --watch.

The same Google Workspace set up process described above is required. The EVENT_SPREADSHEET_ID environment variable is the same, but Google API authentication will work differently. Instead of the GCP_SA_KEY variable, export a GOOGLE_APPLICATION_CREDENTIALS variable which has that path to the service account key json file (as opposed to the GCP_SA_KEY variable, this is a file path, not the raw JSON string).

Getting the Service Account JSON

• Open GCP and navigate to the Calendar Converter project
• Open up the IAM page and navigate to the Service Accounts tab
• Select the calendar convert service key and open up the Keys tab
• Click Add Key and set it to be JSON
• It will automatically download a .json file which you can place in the root of the project
• You can rename the file to bee calendar-converter.json which is included in the .gitignore

The environement variables can then be set as follows:

$ export EVENT_SPREADSHEET_ID=<INSERT ID HERE>
$ export GOOGLE_APPLICATION_CREDENTIALS=<INSERT PATH TO JSON FILE>