Importing Google Contacts

openPRM can import the contacts of one or more Google accounts and keep them up to date. The import is one-way and read-only: openPRM never changes anything in Google.

It works through homefirst.cloud, which holds Home First’s Google app registration. Your openPRM keeps the account’s tokens (encrypted with OPENPRM_CREDENTIALS_KEY); the cloud never stores them, and neither side can read your contacts without the other.

Before you start

• openPRM is enrolled with homefirst.cloud and OPENPRM_CREDENTIALS_KEY is set (see Configuration).
• Optionally set OPENPRM_PUBLIC_URL so your browser comes back to openPRM after you approve access.

Settings → Connected accounts says why connecting isn’t possible when something is missing: the cloud isn’t set up or isn’t connected, the key isn’t set, or your homefirst.cloud doesn’t offer Google Contacts.

Connecting a Google account

1. Open Settings → Connected accounts and choose Connect Google account.
2. Open the link it shows in your browser (or copy it), sign in to the Google account you want and approve read-only access to your contacts. Google also shares the account’s email address, which openPRM uses as its name.
3. The page updates by itself when the account is connected, and the first import starts right away.

Any signed-in member of your household can connect their own accounts; the import runs as them. You see and manage your own accounts (an admin sees everyone’s).

More than one account

Choose Connect another Google account to add a second one (say, a personal and a work account). Each account is listed and synced on its own; connecting one never replaces another. Connecting an account that is already listed just renews it.

Reconnecting and disconnecting

If Google stops accepting an account’s access (you revoked it, changed your password, or it lapsed), the account shows Needs reconnecting and its sync pauses. Choose Reconnect from its menu and approve access again.

Disconnect deletes openPRM’s tokens for that account and stops importing from it. Other accounts are not affected, and the people already imported stay. To revoke access at Google as well, remove Home First in your Google account’s third-party access settings.

What is imported

Only what openPRM’s person record holds:

From Google	In openPRM
Name (prefix, first, middle, last, suffix)	The name fields
Nicknames	Nickname
Email addresses (home / work / other)	Email (personal / work / other)
Phone numbers (mobile, home, work, fax, …)	Phone (mobile / home / work / fax / other)
Job title (current organization)	Title
Birthday with a year	Important date (birthday)

Not imported: photos, addresses, websites, notes, relations, groups and other fields — openPRM doesn’t request them. A birthday without a year is skipped, because openPRM stores full dates.

Every imported value is a normal openPRM fact whose source is the Google account and contact it came from, so you can always see where it came from.

How contacts become people

• Each contact is linked to one person. Later syncs update that person instead of creating a new one.
• Matching an existing person happens only on an exact email address shared with exactly one person you can see. Names alone never merge people. If an address matches several people, the contact is imported as a new person and a review item lists the possible matches, so you can merge them yourself.
• The same person in two Google accounts (found by a shared email) is one openPRM person linked to both contacts. Values that both accounts have are stored once.
• Your edits win. The import only changes values it wrote itself. If you change a name in openPRM, retract an imported email, or add notes, later syncs leave those alone; if you delete the person, the import doesn’t bring them back.
• With OPENPRM_GOOGLE_CONTACTS_SCOPE=private, imported people are visible only to the person who connected the account, and only their private people are matched.

When contacts change at Google

openPRM syncs each account every few hours (OPENPRM_GOOGLE_CONTACTS_SYNC_INTERVAL, default 3 hours) and straight after it’s connected; Sync now in the account’s menu runs it immediately. Google has no push notifications for contacts, so changes appear at the next sync. A failing sync is retried with growing delays; the last error is shown on the account.

Each sync asks Google only for what changed since the last one. Changed values are updated (the old value stays in the person’s history). If Google has expired the change marker — after about a week without a sync — openPRM quietly re-reads the whole address book.

A contact deleted at Google is marked removed at source; the person, their facts, notes and history stay in openPRM. The account shows how many of its contacts were removed. Delete the person in openPRM if you no longer want them.

Privacy

• Access is read-only (contacts.readonly), plus your Google email address to name the account.
• Tokens are encrypted at rest and never logged or shown.
• openPRM’s logs record counts, never contact details.