CalSync

CalSync will automatically synchronize Monday.com boards to Google Calendar.

It will search a configured Monday.com workspace for up to 500 boards that have columns with titles: Date, Status, Accept, Norm, Remote, Office (hardcoded in lib/cal_sync/monday_client.ex)

It will then search for up to 500 events per board, starting from a week ago, filter out entries based on a formula in lib/cal_sync/monday_client/row.ex, then compare them against the configured Google Calendar's events and insert or delete the events as needed. The sync will be performed:

• 15 minutes after startup (hardcoded in lib/cal_sync/application.ex)
• 6 hours after each full sync (hardcoded in lib/cal_sync/application.ex)
• 60 seconds after a Monday.com 'column changed' webhook event is received - it will update a single board (hardcoded in lib/cal_sync/controller.ex)

Configuration

For end users, only the webhook configuration should be necessary to perform. This application and the Google account should be set up by the server administrator.

Monday.com webhook configuration

Webhooks are necessary in order to inform CalSync about changes made to the board, so it can perform a sync when they happen.

To add a webhook, navigate to a board you want to sync and click Integrate.

Find and choose the webhook integration.

Add to board the When any column changes, send a webhook hook.

Enter the public CalSync webhook endpoint URL, choose connect and then add.

Google Service Account and calendar sharing

Go to Google Cloud Console, create a new resource and add the Google Calendar API to it. Navigate to Credentials section of the resource, create a new Service Account and download the service account credentials file. Path to this file must be provided to CalSync through the GOOGLE_APPLICATION_CREDENTIALS variable.

To grant our service account access to the calendar, add its e-mail like so:

Our sharing settings should then look like this:

The service account must now accept the invitation, which is done automatically by CalSync when the calendar ID is provided to it via the GOOGLE_VACATION_CALENDAR_ID and GOOGLE_REMOTE_WORK_CALENDAR_ID environment variables. You can find the correct ID in calendar settings, and it will look like this:

Server configuration

In order to run this program, you must configure these environment variables:

• GOOGLE_APPLICATION_CREDENTIALS GOOGLE_VACATION_CALENDAR_ID GOOGLE_REMOTE_WORK_CALENDAR_ID - see this section
• MONDAY_API_KEY - this can be either the developer or admin API key. Refer to Monday.com's documentation on how to obtain it.
• MONDAY_WORKSPACE_ID - ID of the workspace itself in which CalSync will attempt to look for relevant boards. You can find it by first navigating to the right workspace through here:

And the workspace ID can be found in the highlighted part of the URL:

• HTTP_PORT environment variable can be provided to change on which port the webhook receiver server should listen on (default: 4000).

• USE_COLORS environment variable will make CalSync assign different event colors per status.

Development

This repository contains a Nix devshell with necessary dependencies. With Nix installed, it can be built and entered with:

nix develop

Otherwise, you'll need Elixir 1.17 or newer.

To run the development build, install the dependencies and start the program.

mix deps.get
iex -S mix

Building

This repository contains a Nix package recipe for production builds, which can be created with:

nix build .#

However, mix releases should also work.

Deployment

This repository contains a Nixos module to ease deployment. It can be used like so:

{
  # add CalSync flake to your inputs
  inputs.calsync.url = "git+ssh://gitea@git.mtj.pl/paweld/calsync.git";

  # ensure that calsync is an allowed argument to the outputs function
  outputs = { self, nixpkgs, calsync }: {
    nixosConfigurations.yourHostName = let system = "x86_64-linux";
    in nixpkgs.lib.nixosSystem {
      modules = [
        # load the CalSync NixOS module
        calsync.nixosModules.${system}.calsync
        ({ pkgs, ... }: {
          # configure the calsync module
          services.calsync = {
            enable = true;
            port = 4001;
            # take extra care to not include these files in the globally readable /nix/store
            # as they contain secrets
            googleCredentialsJsonPath = "/run/keys/google_service_account_credentials.json";
            # check the flake.nix file for expected environment variables
            environmentFile = "/run/keys/calsync_environment";
          };
        })
      ];
    };
  };
}

For a complete example, including secure secret management with agenix, integration with nginx and deployment with deploy-rs, see the nixos-config repository.