Connectors
A connector keeps a person's Microsoft 365 or Google Workspace account and Hearth in step, as that person. There are five: calendar, contacts, mail, files, and chat notifications. Each works with both providers, each is off until an administrator turns it on, and each person chooses what to connect.
Setup, the app registration, and the permissions are on Microsoft 365 and Google Workspace. Open Settings, then Connectors to turn them on, and to see every person's status and last error.
Calendar
Keeps a person's Hearth calendar and their Google or Outlook calendar the same, in both directions.
A window of a week back to ninety days ahead syncs, with recurring events expanded to their instances. Each event keeps its title, notes, place, and time, and all-day events keep their days.
| Where it changed | What happens |
|---|---|
| A new event at Google or Microsoft | It appears in Hearth |
| A new event in Hearth, made by the person | It appears at Google or Microsoft |
| An event changed at Google or Microsoft | Hearth takes the change |
| An event changed in Hearth | Google or Microsoft takes the change |
| Changed in both since the last run | The provider's version wins, and the log says so |
| Deleted on one side, inside the window | Deleted on the other |
Work that has a due date, maintenance schedules, and logged hours are not copied. Hearth reads them where they live.
Meet and Teams links. An administrator can turn on a link for events Hearth creates: a Google Meet link for Google Workspace, a Teams meeting for Microsoft 365. It is added once, when the event is created in Hearth, and not to all-day events. A link already on an event made elsewhere is shown as its place when the event has none.
Shared calendars and departments. A person sees every calendar they can read and can add one to their own Hearth calendar. A manager of a department can instead send it to the department: its events become the department's, so everybody Hearth gives that department can see them, with no Google or Microsoft account of their own. Events added to the department in Hearth go back to that calendar. One calendar goes into one department.
Events are matched in UTC, and all-day events by their date in UTC, so run Hearth with its clock in UTC. A person who disconnects keeps the events that came across, which are now theirs in Hearth, and loses the link to the provider.
Contacts
Keeps a person's address book at Google Contacts or Outlook and the Hearth CRM the same, in both directions.
Each contact with a name or an address comes in as a CRM contact with its name, address, phone, and job title, and each contact a person makes in the CRM goes to their address book. If an address is already in the CRM, Hearth links the two and changes nothing at first, because the existing record is the better source. A company is attached when the contact's company matches one the person can already see, name for name. Hearth does not make companies from free text.
| Where it changed | What happens |
|---|---|
| A new contact at the provider | A new CRM contact |
| A new CRM contact, made by the person | A new contact at the provider |
| Changed at the provider only | Hearth takes the change |
| Changed in Hearth only | The provider takes the change |
| Changed on both sides since the last run | The provider's version wins, and the log says so |
| Deleted at the provider | Deleted in the CRM, as a soft delete the CRM can restore |
| Deleted in the CRM | Deleted at the provider |
Contacts that come in are imported as the person who connected, so they are that person's own in the CRM. The CRM's own sharing decides who else sees one. Connecting an address book does not hand it to the company.
Mail
A person's Gmail or Outlook mailbox inside Hearth, read and write, as that person.
Mailbox in Settings opens the inbox, sent mail, archive, or all mail, with search in the provider's own syntax. Any message the person can see opens with its whole body. From there they can:
- send a new message, with To, Cc, and Bcc
- reply, or reply to everybody, in the same thread
- forward a message to other people with a note above it
- archive it, label it (Gmail labels, Outlook categories), mark it read or unread, and delete it to the bin
Everything passes straight through to Google or Microsoft as the person, so a reply appears in their own Sent folder and nothing is kept in Hearth. A message with attachments lists their names and links back to the message to download them. A forward carries the text of the message, and attachments stay with the original.
Mail on a contact. Hearth also reads recent mail, the last fourteen days at first and then what is new, and links each message to the people in the CRM it names. The whole message is kept for those, and shows on the contact's page to the person whose mailbox it came from and to nobody else. A colleague who can see the same contact does not see mail from somebody else's mailbox. A stored message is dropped after ninety days, and disconnecting deletes them all.
Files
OneDrive, SharePoint, and Google Drive inside Hearth, read and write, as the person.
Cloud files in Settings lists a person's own drive and the places they can reach: the document libraries of SharePoint sites they follow, and Google shared drives. What they see is exactly what Microsoft or Google says they may see, listed live, with nothing cached in Hearth. From there they can upload a file into the folder being shown, replace a file's content, rename or move a file or folder, make new folders, and delete a file or folder, which sends it to the provider's bin where it can be restored.
| Choice | What happens |
|---|---|
| Link | Hearth records where the file lives. The document shows a link back to the original |
| Import a copy | Hearth downloads the file once and attaches the copy to the document, and keeps the link as well |
| Save to a drive | A file attached to a Hearth document is copied into the folder being shown |
Linking and importing need permission to edit the document, and saving an attachment out needs permission to see it, which Hearth checks. A Google Docs, Sheets, or Slides file is imported as Word, Excel, or PowerPoint. Imports and uploads are limited to 50 MB. Removing a link does not remove an imported copy.
Without the Sites.Read.All permission, OneDrive still works and SharePoint libraries do not appear.
Chat notifications
Copies a person's Hearth notifications into a Google Chat space or a Microsoft Teams chat they choose. Unlike the other connectors it asks the provider for no permissions, because it uses an incoming webhook.
A person makes a webhook in the place they want the notifications, and pastes its address under Settings, then Connectors.
- Google Chat: in a space, open Apps and integrations, then Webhooks, and make one.
- Microsoft Teams: in the Workflows app, make a workflow that posts to a chat or channel when a webhook request is received, and copy its address.
Hearth then posts the same line the person's inbox shows, with a link to open the item. Quiet hours hold it, as they hold email and push. A notification is never posted to somebody else's webhook.
The address is a credential, since whoever holds it can post. Hearth stores it encrypted, shows it to nobody, and only calls the vendors' own hosts: chat.googleapis.com for Google, and webhook.office.com, logic.azure.com, and powerplatform.com for Teams. An address anywhere else is refused, so a pasted address cannot point Hearth at a machine inside your network. If a post fails, the Connectors page shows the reason without the address. Stopping the copy deletes the address.
Permissions at a glance
| Connector | Google Workspace | Microsoft 365 (delegated) |
|---|---|---|
| Calendar | https://www.googleapis.com/auth/calendar | Calendars.ReadWrite |
| Contacts | https://www.googleapis.com/auth/contacts | Contacts.ReadWrite |
https://mail.google.com/ | Mail.ReadWrite, Mail.Send | |
| Files | https://www.googleapis.com/auth/drive | Files.ReadWrite.All, Sites.Read.All |
| Chat notifications | none | none |