Skip to content

Reference: Google Integration

This page captures the data model, integration flows, and automation behind the Google module. It is meant for admins and power users who need to know how synchronization actually works.

Architecture & Flows

flowchart LR
    U["User connects Google account<br/>OAuth 2.0"] --> EA["External Google Account"]
    EA --> CalJob["Job \"SynchronizeEventsWithGoogleCalendar\"<br/>*/10 minutes"]
    CalJob <--> CRMEvents[Meetings & Calls in CRM]
    CalJob <--> GCal[Google Calendar API]
    EA --> ContactsPush["Push to Google" action on Contacts/Leads]
    ContactsPush <--> PeopleAPI[Google People API]
    EA --> GmailOAuth[OAuth2 IMAP/SMTP for Gmail]

Data Objects

Object Purpose Linkage
External Google account (ExternalAccount) Stores OAuth tokens and per-user choices for calendar, contacts, and Gmail. Linked to User; Google integration.
GoogleCalendar (GoogleCalendar) Local catalog of Google calendars (ID, name). Used by Meetings/Calls (googleCalendar, googleCalendarEventId).
GoogleCalendarUser (GoogleCalendarUser) Assigns a calendar to a user; role/type (main vs monitored), sync token state. References User and GoogleCalendar.
GoogleCalendarEvent (GoogleCalendarEvent) Mapping of a specific meeting/call to a Google event ID. LinkParent to source entity + link to GoogleCalendar.
GoogleCalendarRecurrentEvent (GoogleCalendarRecurrentEvent) Holds recurrence info (tokens, last loaded time). Linked to GoogleCalendarUser.
GoogleContactsGroup (GoogleContactsGroup) Catalog of Google labels/groups for contacts. Used when selecting the synced group.
GoogleContactsUser (GoogleContactsUser) Contact group selection per user (main/monitored, active flag, last sync timestamps). References User and GoogleContactsGroup.
GoogleContactsPair (GoogleContactsPair) Connects a CRM Contact/Lead with a Google contact (resourceName, etag, account email). Has-children link from Contact/Lead.

Configuration Fields (User Profile → External Accounts → Google)

  • Calendar: calendarDirection (CRM → Google / Google → CRM / both), calendarStartDate (date from which changes are pulled), calendarEntityTypes (entities to sync – typically Meeting/Call), calendarDefaultEntity (default type for Google-originated events), removeGoogleCalendarEventIfRemovedInEspo, dontSyncEventAttendees (default = on), calendarMainCalendar (required), calendarMonitoredCalendars (optional extra calendars), calendarAssignDefaultTeam.
  • Contacts: contactsGroups – Google group selection; only one active group is allowed (validated on save).
  • Gmail: gmailEmailAddress – address used for OAuth IMAP/SMTP. Gmail panel is available only for Espo versions ≥ 5.6 (older versions are blocked).

Automation & Jobs

  • SynchronizeEventsWithGoogleCalendar (cron: */10 * * * *) – two-way sync of meetings and calls according to direction, calendars, and default entity settings.
  • GoogleJob (daily 02:15) → schedules JobRunner for internal license/health checks.
  • Push to Google action (record and mass action for Contact/Lead) calls GoogleContacts/action/push and respects the selected contacts group.

Panel Visibility & Conditions

  • Gmail panel on inbound email/accounts is shown only in detail mode and only when host or SMTP host contains gmail. (google:inbound-email-dynamic-handler).
  • Disconnecting the account wipes OAuth tokens (accessToken, refreshToken) and disables all enabled products.

Security & Constraints

  • Authentication uses OAuth 2.0 only; user passwords are never stored in CRM.
  • A user may enable multiple products (Calendar, Contacts, Gmail), but panels appear only after a successful connection.
  • Before the first sync, ensure the user profile has a timezone and permissions to Meetings, Calls, and Contacts.