Rings AI
for Salesforce

01 Overview

What Rings AI Is

Rings brings relationship intelligence into Salesforce — analyzing your organization's real-world email and meeting activity to understand who knows whom, and how well.

The app does two things

Two properties worth internalizing

Read-only against your CRM. Rings data lands only in the app's own ringsai__ fields. Standard fields your team maintains are never touched.

Read-only against Rings. The app only fetches data (GET). Nothing from your org is written back to Rings.

02 Package Contents

What Gets Installed

The ringsai managed package adds the following — and its uninstall cleanly removes all of it.

On install, the post-install script assigns both permission sets to System Administrator users, creates the default settings record, and schedules the daily log-cleanup job — so an admin can open Rings AI Settings immediately.

03 Setup

Quick Start

The fastest path from installed package to working app. Each step is expanded in the sections that follow.

1. Set the API key

   Setup → Named Credentials → External Credentials tab → Rings_AI_API_Production → in Custom Headers, set the x-api-key value. (Sandbox orgs: Rings_AI_API_Sandbox.)

2. Assign permission sets

   Rings_AI_Admin + Rings_AI_Standard_Access to admins; Rings_AI_Standard_Access to everyone who should see Rings data.

3. Enable the app

   Open Rings AI Settings → turn on App Enabled → turn on sync for the objects you want → set Sync Frequency and Bulk Sync Hour → Save. Leave all "Use Mock" toggles off.

4. Map your users

   Rings AI Settings → User Mappings: link each Salesforce user to their Rings identity. Unmapped users don't get relationship paths or per-user data.

5. Add the panel to record pages

   In Lightning App Builder, add the recordPanel component to your Account, Contact, Lead, and Opportunity record pages.

6. Run the first sync

   Rings AI Settings → Run Now on the Data Sync card. For large orgs, set Max Records Per Sync Run to ~1,000 first and raise it after checking the results.

7. Schedule the incremental sync

   Rings AI Settings → Incremental Sync Schedule → accept the default hourly cron → Schedule. This keeps matched records fresh.

8. Verify

   Open a Contact you know is active — the panel should load with data, and the Rings fields should populate with Match Status Matched.

That's a working install. Everything below is detail and tuning.

04 Mechanics

How the App Works

Matching

Before any data lands on a record, the record must be matched to its Rings counterpart:

• Contacts / Leads match by email or LinkedIn URL in the scheduled bulk sync. Name-only records can still match — through the panel's search, or automatically on creation — but the nightly bulk matcher requires an email or LinkedIn URL.
• Accounts match by name, website domain, or LinkedIn URL.
• Opportunities match through their parent Account's identifiers.

The result is stamped on the record:

The Rings profile link is stored in ringsai__Rings_Record_Id__c ("Rings ID").

Three sync paths

The record panel (live data)

The panel fetches from the Rings API at view time — it does not read the synced fields.

Panel data is user-contextual where it matters: relationship paths and interaction context are computed relative to the logged-in user. Two users can see different paths on the same record — that's by design.

05 Configuration

Settings Reference

All settings live on the Rings AI Settings page, backed by the protected General_Settings__c custom setting.

Master switches

Data sync

The Data Sync card also shows the next scheduled run and offers Run Now (with confirmation) and Cancel Scheduled Sync. Run Now refuses while a previous run is still working — same for the scheduled fire, which skips itself rather than starting an overlapping run.

Incremental sync

Scheduled from its own card with a cron expression. Common values:

The first run after install looks back 30 days; each later run only pulls changes since the last successful run (watermarks visible on the card). Run Now works with or without an active schedule.

Panel features

Performance & logging

06 Identity

User Mappings

A user mapping links a Salesforce User to their Rings identity. It powers everything user-specific:

• Relationship Paths — computed from the viewing user; no mapping, no paths.
• Top user / strongest relationship fields — Strongest_Int_Rel_*_User__c, Top_Email_User_*, Top_Meeting_User_*, and the Best Ext "Top Int" fields only resolve to a Salesforce User when that person is mapped. Unmapped = blank, even when Rings has the data.
• Interaction context — per-user email/meeting detail in the panel.

Manage under Rings AI Settings → User Mappings: pick the Salesforce user, pick the matching Rings user from the dropdown (loaded live from Rings), save.

07 Data Model

Fields on Records

Every Rings field is namespaced ringsai__ and labeled "Rings …". By category:

Two Contact/Lead fields (Person_Title_Updated_At__c, Person_Company_Updated_At__c, and the Days Since Last Job Change formula over them) are installed but stay blank — the Rings API doesn't supply their source data yet. They'll populate automatically once it does.

PathPower, as a color

PathPower comes in a text form (WEAK → STRONGEST) and a numeric Score (1–5). The spectrum runs cool to warm as the relationship gets stronger:

Points an admin should know

• Rings Days Since Last Interaction is a formula over Rings Last Interaction — usable directly in "gone quiet" list views and report filters on all four objects.
• Opportunity engagement fields mirror Account (counts, PathPower, next meeting), so a report built for Accounts translates to Opportunities by swapping the object.
• Fields are read-only for users and overwritten by sync — treat them as a feed.

08 Routing

Choosing a "Best User" Field

Contacts and Leads carry three fields that each answer "which internal user should own this relationship?" — but they measure different things. Pick by use case.

Practical guidance

• Assignment rules / lead routing: use Strongest_Int_Rel_1_User__c. It's populated whenever any internal relationship exists, while the Top fields go blank when there's no recent activity.
• "Gone quiet" alerts: combine — Strongest_Int_Rel_1_User__c tells you who should re-engage; blank Top fields tell you nobody currently is.
• Tie-breaking / fallback order: Strongest_Int_Rel_1_User__c → Top_Meeting_User_Last_3_Months__c → Top_Email_User_Last_3_Months__c → Strongest_Int_Rel_2_User__c.
• All resolve to a Salesforce User only when that person has a Rings user mapping. If a field is unexpectedly empty, check the mapping first.
• Companion fields: each Strongest slot has a Score and Last At; the Top Meeting user has Top_Meeting_User_Meetings_Last_3_Months__c.

09 Design Rationale

Why Rings Fields Shadow Standard Fields

Many Rings fields intentionally duplicate a standard field: ringsai__Name__c vs Name, ringsai__Email__c vs Email, ringsai__Job_Title__c vs Title, and ringsai__Last_Interaction_At__c vs LastActivityDate, among others. This is deliberate — the Rings fields are a Rings-verified shadow copy.

• The sync never overwrites your CRM data. Standard fields stay hand-maintained; Rings writes only to its own namespaced fields. Installing the app cannot clobber an email or company name your team curated.
• Side-by-side comparison is the point. When Email and Rings Email disagree, that's signal — Rings has seen a newer address in live communication. Reports comparing the two surface stale CRM data.
• Rings fields are read-only by design. They're overwritten on every sync, so hand edits don't stick. Treat them as a feed, not a place to type.
• Standard-field meaning differs. Standard LastActivityDate reflects Salesforce tasks/events; Rings Last Interaction reflects real-world email/meeting interactions observed by Rings — often earlier and more complete.

If you want Rings data to flow into standard fields, do it deliberately with your own Flow on the fields you choose — the package will never do it for you.

10 Operations

Monitoring & Troubleshooting

Where to look

• Api_Log__c — the app's log object. Errors from syncs, callouts, and background jobs land here with source class, severity, endpoint, and status code. First stop for any "data didn't populate" question.
• Rings AI Settings page — sync cards show schedule state, next run, and last-sync watermarks.
• Setup → Apex Jobs — status of the batch (RingsMatchAndSyncBatch) and queueable (RingsIncrementalSyncQueueable, RingsRematchQueueable) runs.
• Enable Verbose Logging temporarily to capture full call detail while reproducing a problem; turn it off after.

Common issues

11 Governance

Security & Permissions

• Two permission sets. Rings_AI_Standard_Access ("Rings AI Viewer") grants read-only access to every Rings field plus the external-credential access needed for callouts — assign it to everyone, admins included. Rings_AI_Admin layers on settings, job, and user-mapping management; it is assigned alongside Standard Access, not instead of it.
• Users cannot edit Rings fields. All record fields are read-only in the permission sets; only the sync writes them.
• The API key lives in the External Credential (Setup → Named Credentials), never in code, settings records, or logs.
• Logs are sanitized. Api_Log__c entries have query strings stripped and PII scrubbed before they're written.
• Outbound only, read only. The app calls the Rings API to fetch data; it never sends your org's data to Rings, and it never writes to standard fields.

12 Lifecycle

Disabling & Uninstalling

Uninstall (Setup → Installed Packages) removes everything the package added: objects, fields, components, permission sets, Named Credentials. Be aware:

• Data in the app's custom objects — settings, user mappings, logs — is deleted with them.
• The Rings fields on Account/Contact/Lead/Opportunity and the data in them are removed.
• Standard fields and their data are untouched — the app never wrote there.