Google Calendar Integration Guide

Overview

The Google Calendar integration allows your NINA workflows to connect with Google Calendar for event and calendar management. This integration enables you to create, retrieve, update, and delete calendar events, as well as check calendar availability, all directly from your workflows.

Status

At present, our integration supports core functionalities related to calendar event management and availability checking. However, there are still several areas not covered by this integration, mainly:

• Calendar Management: Creation and modification of calendars.
• Access Control Lists: Management of calendar sharing and permissions.
• Settings: Configuration of calendar settings.
• Colors: Management of calendar and event colors.
• Free/Busy: Comprehensive free/busy queries across multiple calendars.

Credential Configuration

Before using the Google Calendar integration in your workflows, you need to configure credentials for authentication. The NINA platform supports OAuth2 authentication for Google Calendar:

Authentication Methods

OAuth2 Authentication

Field	Description	Example
Client ID	OAuth2 client ID	123456789012-abc123def456.apps.googleusercontent.com
Client Secret	OAuth2 client secret	GOCSPX-abc123def456ghi789jkl
Scope	OAuth2 scopes	https://www.googleapis.com/auth/calendar
Auth URL	Authorization URL	https://accounts.google.com/o/oauth2/auth
Access Token URL	Access token URL	https://oauth2.googleapis.com/token

If you need multiple scopes add them one after another separated by space:

https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events.readonly

How to set up OAuth2:

1. Go to the Google Cloud Console
2. Create a new project (or select an existing one)
3. Navigate to "APIs & Services" > "Credentials"
4. Configure the OAuth consent screen:
   • Select User Type (Internal or External)
   • Add app information and developer contact details
   • Add the Google Calendar API scope (https://www.googleapis.com/auth/calendar)
5. Create OAuth client ID credentials:
   • Select "Web application" as the application type
   • Add authorized redirect URIs:
     • For POC environment: https://poc.zynap.com/api/v1/oauth2/callback
     • For Production environment: https://platform.zynap.com/api/v1/oauth2/callback
   • Note your Client ID and Client Secret
6. Enable the Google Calendar API in "APIs & Services" > "Library"

Creating a Google Calendar Credential

1. Navigate to the Credentials section in NINA
2. Click Add New Credential
3. Fill in the credential details:
   • Name: A descriptive name (e.g., "Google Calendar Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Google Calendar"
   • Fill in the authentication fields (Client ID, Client Secret, etc.)
4. Click Create to verify credentials, this will lead to a Google Authentication page to confirm the access that is needed.

Supported Resources and Operations

The Google Calendar integration supports the following resources and operations:

Event

Operation	Description
Create	Creates a new calendar event
Get	Retrieves details of a specific event
Get All	Retrieves multiple events from a calendar
Update	Updates an existing event
Delete	Deletes an event

Calendar

Operation	Description
Availability	Checks availability during a specified time period

Parameter Merging

The Google Calendar integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the Google Calendar Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When a Google Calendar Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• The combined parameters are used to execute the Google Calendar operation

Example: Creating Calendar Events

Basic Event Creation

Below is an example of creating a basic calendar event:

Node Configuration:

{
  "resource": "event",
  "operation": "create",
  "parameters": {
    "calendarId": {
      "mode": "id",
      "value": "primary"
    },
    "summary": "Project Status Meeting",
    "start": "2024-06-15T10:00:00Z",
    "end": "2024-06-15T11:00:00Z",
    "additionalFields": {
      "description": "Weekly project status review meeting",
      "location": "Conference Room A",
      "sendNotifications": true
    }
  }
}

Creating an Event with Attendees and Reminders

You can create more complex events with attendees, reminders, and other additional options:

Node Configuration:

{
  "resource": "event",
  "operation": "create",
  "parameters": {
    "calendarId": {
      "mode": "id",
      "value": "primary"
    },
    "summary": "Security Review Meeting",
    "start": "2024-06-20T14:00:00Z",
    "end": "2024-06-20T15:30:00Z",
    "useDefaultReminders": false,
    "additionalFields": {
      "description": "Quarterly security review of all systems and applications",
      "location": "Virtual Meeting Room",
      "sendNotifications": true,
      "attendees": [
        "[email protected]",
        "[email protected]",
        "[email protected]"
      ],
      "reminders": {
        "overrides": [
          {
            "method": "email",
            "minutes": 60
          },
          {
            "method": "popup",
            "minutes": 15
          }
        ]
      },
      "conferenceData": {
        "conferenceDataProperties": {
          "createRequest": true
        }
      }
    }
  }
}

Creating a Recurring Event

Create an event that repeats on a regular schedule:

Node Configuration:

{
  "resource": "event",
  "operation": "create",
  "parameters": {
    "calendarId": {
      "mode": "id",
      "value": "primary"
    },
    "summary": "Weekly Team Standup",
    "start": "2024-06-17T09:00:00Z",
    "end": "2024-06-17T09:30:00Z",
    "additionalFields": {
      "description": "Weekly team status update meeting",
      "location": "Virtual Meeting Room",
      "recurrence": {
        "rrule": {
          "frequency": "weekly",
          "interval": 1,
          "count": 12
        }
      },
      "conferenceData": {
        "conferenceDataProperties": {
          "createRequest": true
        }
      }
    }
  }
}

Example: Retrieving Calendar Events

Get a Specific Event

Retrieve details about a specific calendar event:

Node Configuration:

{
  "resource": "event",
  "operation": "get",
  "parameters": {
    "calendarId": {
      "mode": "id",
      "value": "primary"
    },
    "eventId": "abc123def456ghi789"
  }
}

Get All Events in a Time Range

Retrieve all events within a specific time range:

Node Configuration:

{
  "resource": "event",
  "operation": "getAll",
  "parameters": {
    "calendarId": {
      "mode": "id",
      "value": "primary"
    },
    "returnAll": false,
    "limit": 50,
    "options": {
      "timeMin": "2024-06-01T00:00:00Z",
      "timeMax": "2024-06-30T23:59:59Z",
      "orderBy": "startTime",
      "singleEvents": true
    }
  }
}

Example: Updating Calendar Events

Update an Existing Event

Update the details of an existing calendar event:

Node Configuration:

{
  "resource": "event",
  "operation": "update",
  "parameters": {
    "calendarId": {
      "mode": "id",
      "value": "primary"
    },
    "eventId": "abc123def456ghi789",
    "updateFields": {
      "summary": "Updated: Project Status Meeting",
      "description": "Weekly project status review meeting with additional stakeholders",
      "location": "Conference Room B",
      "start": "2024-06-15T11:00:00Z",
      "end": "2024-06-15T12:30:00Z",
      "sendNotifications": true
    }
  }
}

Example: Checking Calendar Availability

Check Availability for a Time Period

Check if a calendar has any events during a specific time period:

Node Configuration:

{
  "resource": "calendar",
  "operation": "availability",
  "parameters": {
    "calendarId": {
      "mode": "id",
      "value": "primary"
    },
    "timeMin": "2024-06-15T09:00:00Z",
    "timeMax": "2024-06-15T17:00:00Z",
    "options": {
      "timeZone": "America/New_York"
    }
  }
}

Best Practices

For optimal use of the Google Calendar integration, follow these best practices:

1. Use Appropriate Time Formats: Always use ISO 8601 format for date and time values (YYYY-MM-DDTHH:MM:SSZ).

2. Handle Time Zones Carefully: Specify time zones when necessary to avoid scheduling errors across different regions.

3. Limit Event Retrieval: When using the "Get All" operation, use timeMin and timeMax parameters to limit the range of events retrieved.

4. Recurring Events: For recurring events, use the recurrence rules to define the pattern rather than creating individual events.

5. Attendee Notifications: Be mindful of when to send notifications to attendees, particularly when updating events.

6. Calendar Permissions: Ensure that your OAuth2 credentials have the appropriate permissions for the calendars you're trying to access.

7. Error Handling: Implement proper error handling in your workflows to manage cases where events cannot be created or updated.

Troubleshooting

Common issues and their solutions:

Authentication Errors

Issue: "Failed to authorize with Google Calendar API" Solution: Verify that your OAuth2 credentials are correct and that the Google Calendar API is enabled in your Google Cloud project.

Permission Errors

Issue: "Insufficient permission to access calendar" Solution: Ensure that the authenticated user has access to the calendar you're trying to work with.

Event Creation Failures

Issue: "Failed to create event" Solution: Check that all required parameters are provided and formatted correctly. Ensure that the calendar ID is valid.

Rate Limiting

Issue: "Rate limit exceeded" Solution: Implement backoff strategies in your workflows or reduce the frequency of API calls.

Additional Resources

• Google Calendar API Documentation
• Google OAuth2 Documentation
• Google Cloud Console