Technical Administration Guide

1. Product Overview

DonorAtlas for Salesforce is a managed package that integrates the DonorAtlas platform with your Salesforce org. It allows organizations to enrich their Contact, Lead, and Account (Person Account) records with comprehensive donor research data (wealth information, giving history, board affiliations, education, work experience, private foundation connections, political affiliations, and more).

How It Works

1. An admin installs the package and configures field mappings that tell DonorAtlas which Salesforce fields to use for matching (name, address, employer, school)
2. Users sync individual Contact/Lead/Account records or bulk-sync from list views and campaigns
3. DonorAtlas matches the Salesforce record to its database and creates a child Donor record (and child records for donations, education, work experience, etc.) in Salesforce with enriched data.

2. Prerequisites and System Requirements

Salesforce Edition

• Required: Enterprise, Unlimited, or Developer Edition
• Not Supported: Essentials, Professional (unless API access is enabled). Please contact our team if you'd like to use the integration and are on these Salesforce editions!

Required Salesforce Features

• Salesforce API access must be enabled (this is enabled by default on Enterprise, Unlimited, and Developer Edition orgs).
• Lightning Experience must be enabled (the package uses Lightning Web Components)

Per-User Authentication

DonorAtlas uses OAuth to authenticate each individual Salesforce user. This means every user who wants to sync records must log in with their own DonorAtlas account through the integration. Users who are not logged in (or don't have a DonorAtlas account) will see a “Log In” button when they view the DonorAtlas component.

Because of this, we recommend that you only activate the DonorAtlas sync components to users who have DonorAtlas accounts. You can control this by assigning DonorAtlas permission sets only to users who should interact with the integration, and only activating the components for those users (see instructions for activating components for only some users in Adding the Sync Component to Record Pages section). Users without DonorAtlas accounts can still benefit from the data: they can view the underlying Donor records, child records, and run reports on DonorAtlas data, as long as they have the Viewer permission set or equivalent object access.

Browser Compatibility

Follows standard Salesforce browser support. Lightning Experience is required.

3. Installation

Installation Steps

1. Navigate to the installation URL provided by DonorAtlas. Installation page

   If your org has a sandbox, we recommend installing in your sandbox first to test the integration before rolling it out to production. If you don't have a sandbox, installing directly in production is perfectly fine. Each DonorAtlas team can be linked with exactly one Salesforce Sandbox/Scratch environment and one Production environment.

2. Choose Install for Admins Only (recommended) or Install for All Users.
3. Click Install and wait for the installation to complete. You will receive an email confirmation. Third-party access prompt
4. If you installed in a sandbox first, repeat the process for your production org once you've verified everything works.

Environment Limits

Each DonorAtlas team can be linked to one sandbox and one production Salesforce environment. You'll see both on your DonorAtlas profile page. If you try to link a second sandbox or production environment to a DonorAtlas team that already has one connected, you'll receive an error. Profile page

To switch to a different sandbox or production Salesforce environment, go to your DonorAtlas profile page, open the Configure page for that environment, and uninstall it. This frees up the slot so you can link a new sandbox or production org. If you need to link multiple production or sandbox environments, please contact our team!

What Happens During Installation

The package includes a post-install script (DonorAtlas_PostInstall) that automatically assigns the DonorAtlas_Integration_Admin permission set to the user who installs the package. Read more about permission sets in Section 6.

Upgrading

• The installer receives the Admin permission set if not already assigned
• If you have a sandbox, test the upgrade there before upgrading production

4. Post-Installation Configuration

Quick Setup Checklist

Adding the Sync Component to Record Pages

1. Navigate to a Contact record page
2. Click the gear icon > Edit Page to open Lightning App Builder. Edit Page button
3. Scroll down to the Custom Components section and look for donorAtlasSync.
4. Drag it onto the record page layout (recommended: above the activity section on the right, but outside the white box which contains the activity section). Component in App Builder
5. (Recommended) Set component visibility so the component only appears for users with a DonorAtlas permission set:
   1. Click on the component you just placed, then click Set Component Visibility in the properties panel on the right
   2. Add a filter with type Advanced
   3. Click Select under Field, then search for Permissions → Custom Permission → DonorAtlas_Can_View
   4. Click Done
6. Click Save and Activate the page
7. Repeat for Lead and Account (Person Account) record pages
8. For Campaign pages, add the donorAtlasCampaignSync component in a similar way (with the same visibility filter).

Adding the Bulk Sync Button to List Views

1. Go to Setup > Object Manager > Contact > List View Button Layout
2. Edit the layout and add “Sync with DonorAtlas” to the Custom Buttons section. Button layout setup
3. Save the layout
4. Repeat for the Lead and Account objects

Configuring Field Mappings

1. Navigate to the DonorAtlas Configuration tab (visible to users with the Admin permission set). Configuration tab
2. Log in to DonorAtlas by clicking the “Log In” button. If you do not have a DonorAtlas account, please contact our team. We are able to add Configuration-only DonorAtlas accounts which do not count towards your team's usage of DonorAtlas seats. You must have a DonorAtlas account and be a member of your organization's DonorAtlas team to continue.
3. A new browser tab opens and takes you to DonorAtlas. Sign in with your DonorAtlas credentials.
4. DonorAtlas will ask you to authorize access to your Salesforce org. Click Allow. OAuth authorization
5. Once complete, you'll see a confirmation. Return to Salesforce. Connection confirmed
6. Select the Contact, Lead, or Account Field Mapping tab Configuration tab
7. Configure which Salesforce fields DonorAtlas should use for matching:
   • Name Fields (required)
   • Addresses (highly recommended)
   • Employers, Occupations, and Schools
8. For each field, you can select fields from related objects (for example, you can select Account.Name for Employers if you store employers in Salesforce Account objects)
9. Click Save to persist the mapping, then Submit to push it to DonorAtlas. Submitted confirmation

5. Authentication Architecture

DonorAtlas uses a two-way OAuth authentication model that establishes trust in both directions: Salesforce needs credentials to call the DonorAtlas API, and DonorAtlas needs credentials to call back into Salesforce (for writing sync results and automatic data refreshes). Each user completes this setup individually.

Authentication Flow

The setup flow handles both directions in a single login experience:

After setup, communication flows in both directions:

• Salesforce > DonorAtlas: When a user syncs a record, Salesforce sends the request to the DonorAtlas API with the JWT token (Authorization: Bearer <jwt_token>).
• DonorAtlas > Salesforce: When DonorAtlas finishes processing a match or performs an automatic data refresh, it uses the Salesforce OAuth credentials to write Donor records and child records back into the user's Salesforce org. When a Salesforce user triggers a sync, resync, unsync, or any other DonorAtlas action from Salesforce, DonorAtlas uses that user's OAuth credentials for all calls to Salesforce. For automatic periodic data refreshes, DonorAtlas uses the same user who initially synced the relevant Salesforce records.

JWT Token Write & Credential Fallback

In Step 6 above, DonorAtlas writes a JWT token back to Salesforce as a DonorAtlas_Auth_Token__c Custom Setting record. Creating Custom Settings requires the Customize Application or Manage Custom Permissions permission in Salesforce. If the current user does not have this permission, the write will fail.

When this happens, DonorAtlas falls back and retries the write using the OAuth credentials of each other connected user, in order of when they were initially connected to DonorAtlas. If no connected user has the necessary permission, the authentication flow will fail entirely.

External Client Application

The package includes a registered External Client Application (DonorAtlas) that enables the Salesforce OAuth flow in Step 4 above. This is a standard Salesforce mechanism for allowing external systems to securely access your org's API.

• OAuth Scopes: Api (API access) and RefreshToken (long-lived access for automatic re-syncing)
• Distribution: Packaged with the managed package — no manual Connected App setup required

Token Storage

Tokens are stored in the DonorAtlas_Auth_Token__c Hierarchy Custom Setting. Because JWT tokens can be longer than 255 characters, the token is split across five text fields (Token_1__c through Token_5__c), supporting tokens up to 1,275 characters.

This is a per-user setting, meaning each Salesforce user has their own token and their own DonorAtlas session.

This splitting and re-combining is done automatically by the DonorAtlas API and the installed package.

Users (and admins) are unable to see these tokens, for security purposes. You can verify their existence by looking in Custom Settings in Salesforce Setup for DonorAtlas Auth Token.

API Communication

All API calls are made to the DonorAtlas API at https://api.donoratlas.com/v1/integrations/external/sf via HTTPS. The package includes a Remote Site Setting for api.donoratlas.com to enable secure callouts.

6. Permission Sets and Security

DonorAtlas includes three permission sets: DonorAtlas_Integration_Admin, DonorAtlas_Integration_User, and DonorAtlas_Integration_Viewer. These are managed package permission sets and cannot be modified by subscribers.

Permission Set Summary

DonorAtlas Integration Admin

API Name: DonorAtlas_Integration_Admin

Full access to all DonorAtlas features, data, and configuration. Automatically assigned to the user who installs the package.

Grants:

• The DonorAtlas_Can_Sync and DonorAtlas_Can_View custom permissions
• Visibility to the DonorAtlas Configuration tab

Assign to: Salesforce administrators and users who need to configure field mappings.

DonorAtlas Integration User

API Name: DonorAtlas_Integration_User

Full access to donor data and sync operations, but no access to configuration.

Grants:

• The DonorAtlas_Can_Sync and DonorAtlas_Can_View custom permissions

Assign to: Regular users who need to sync and work with donor data.

DonorAtlas Integration Viewer

API Name: DonorAtlas_Integration_Viewer

Read-only access to donor data. Cannot sync, resync, or unsync records.

Grants:

• The DonorAtlas_Can_View custom permission

Assign to: Users who only need to view donor intelligence data but should not trigger syncs, unsyncs, or resyncs.

Custom Permission: DonorAtlas Can Sync

API Name: DonorAtlas_Can_Sync

Controls whether a user can initiate sync, resync, and unsync operations. Included in Admin and User permission sets, but NOT in Viewer.

Custom Permission: DonorAtlas Can View

API Name: DonorAtlas_Can_View

Indicates that a user has access to DonorAtlas components. Included in all three permission sets (Admin, User, and Viewer). This permission is useful for controlling component visibility on record pages — see Section 4: Post-Installation Configuration for how to set up component visibility filters using this permission.

How to Assign Permission Sets

1. Go to Setup > Permission Sets
2. Click the desired permission set (e.g., DonorAtlas_Integration_User)
3. Click Manage Assignments > Add Assignment
4. Select the users and click Assign

Sharing Model

7. Security and Privacy

Data Handling

• Salesforce-to-DonorAtlas: When you sync a Contact, Lead, or Account (Person Account), only the record ID is sent to DonorAtlas. DonorAtlas then fetches the Contact, Lead, or Account record and uses the data you specify in the field mappings to match the record to a DonorAtlas donor profile. No other Salesforce data leaves your org. The information you send to DonorAtlas is used according to our Terms and Conditions: we will never disclose any of your data to third parties nor will we use your information on DonorAtlas profiles. See our full trust portal here.
• DonorAtlas-to-Salesforce: Enriched donor data is written to custom objects within your Salesforce org. This data is governed by your org's standard Salesforce security model, including sharing rules, permission sets, and field-level security.

8. Data Model

The diagram below shows the DonorAtlas data model. The Donor object is the central entity, with five child objects linked via Master-Detail relationships, and three lookup relationships to standard Contact, Lead, and Account (Person Account) objects. Donor record in Salesforce Related child records

Entity Relationship Diagram

Relationship Summary

Internal / Configuration Objects

9. Field-Level Data Dictionary

Donor__c (Donor)

The central object that stores enriched donor data from DonorAtlas. Linked to a Contact, Lead, or Account (Person Account) via lookup relationships.

Identification Fields

Name Fields

Demographic Fields

Address Fields

Financial / Net Worth Fields

Nonprofit Giving Fields

Political Giving Fields

Other Fields

Donation__c (Donation)

Education__c (Education)

Work_Experience__c (Work Experience)

Board_Affiliation__c (Board Affiliation)

Private_Foundation__c (Private Foundation)

10. Field Mappings

When you sync a Contact, Lead, or Account (Person Account) with DonorAtlas, the integration needs to know which fields on your Salesforce record to send for matching. For example, DonorAtlas needs a person's name and one other piece of information to match them to a DonorAtlas donor. Field mappings are the configuration that tells DonorAtlas where to find these values on your Contact, Lead, and Account records.

The more information you provide, the better the match quality. It is highly recommended to map at least First Name, Last Name, and an address. Adding Employers and Schools further improves accuracy, and you can configure as many of each as you have available.

Recommended Mappings

We recommend the following mappings for standard Salesforce fields. You can configure these from the DonorAtlas Configuration tab after installation.

Contact:

Lead:

Account (Person Account):

Mapping Categories

Related Object Mappings

You can map fields from related objects:

• Account.Name — The Contact's Account name (for employer matching)
• ReportsTo.Name — The Contact's “Reports To” contact name
• Any lookup relationship accessible from the Contact, Lead, or Account

Storage

Mappings are stored in DonorAtlas_Configuration_Setting__c using 50 Contact mapping fields, 50 Lead mapping fields, and 50 Account mapping fields. Each stores the format: category::subcategory::FieldApiName

11. Data Synchronization

Sync Architecture

DonorAtlas sync is a two-way data synchronization between Salesforce and the DonorAtlas platform:

1. When a Salesforce user syncs a Contact, Lead, or Account, Salesforce sends only the record ID to DonorAtlas via an API call.
2. DonorAtlas uses the user's Salesforce OAuth credentials to fetch the relevant fields from the Contact/Lead/Account record using the Salesforce API.
3. DonorAtlas uses this information to find a match or research the donor to produce a final DonorAtlas donor profile.
4. If a match is found, a Donor__c record is created in Salesforce with the enriched data. If no match is found, no Donor__c record is created, and a “No Match” message is displayed on the Salesforce record.
5. After a record has been synced, DonorAtlas automatically keeps the Donor record and its child records (Donations, Education, Work Experience, Board Affiliations, Private Foundations) up to date. By default, this happens every 7 days. Contact our team if you would like to change this interval.

Credit Usage

User-Initiated Sync Methods

Single Record Sync

1. Navigate to a Contact, Lead, or Account (Person Account) record page
2. In the DonorAtlas component, click Sync with DonorAtlas. Not Synced state
3. The component sends the record's ID to DonorAtlas via an API call
4. DonorAtlas processes the match asynchronously
5. The component polls for status updates (10s, then 30s, then 2m intervals, up to 30 minutes). Pending state
6. When complete, the Donor record and child records are created/updated in Salesforce (or a “No Match” message is displayed on the Salesforce record). Synced state

Bulk Sync from List Views

1. Navigate to a Contact, Lead, or Account list view
2. Select the records you want to sync (checkbox selection). List view selection
3. Click the “Sync with DonorAtlas” button. Sync button
4. Record IDs are sent in batches of up to 1,000 to the DonorAtlas API.

Campaign Sync

1. Navigate to a Campaign record page
2. In the DonorAtlas Campaign Sync component, view sync status for Contacts and Leads separately. Campaign sync component
3. Click Sync with DonorAtlas for Contacts, Leads, or both
4. All Campaign Members of the selected type are synced in bulk via an API call. This method supports an unlimited number of Contact and Lead records at once (the integration simply sends the Salesforce Campaign ID to DonorAtlas, which DonorAtlas uses to find all Contact or Lead IDs to sync).

Sync Statuses

Resync

Resync refreshes the data for a previously synced record. Use this when DonorAtlas has updated its database and you want the latest data.

Unsync

Unsync removes the underlying Donor record and its child records from Salesforce, and unsyncs the Contact/Lead/Account from DonorAtlas. Use this when the match is incorrect or you wish to remove the Donor record and its child records from Salesforce.

12. UI Components

DonorAtlas Sync Component (Contact/Lead/Account Pages)

Component: donorAtlasSync
Placement: Contact, Lead, and Account (Person Account) record pages
Description: Displays the sync status of a Contact, Lead, or Account record and provides controls to sync, resync, unsync, and navigate to the DonorAtlas profile.

DonorAtlas Campaign Sync Component (Campaign Pages)

Component: donorAtlasCampaignSync
Placement: Campaign record pages
Description: Shows sync status for all campaign members, separated by Contacts and Leads. Displays progress (e.g., “3/10 Contacts synced”) and provides bulk sync/resync for campaign members. Campaign component

DonorAtlas Configuration (App Page)

Component: donorAtlasConfiguration
Placement: Dedicated app page accessible via the DonorAtlas Configuration app (which you can find in the App Launcher)
Visibility: Only visible to users with the Admin permission set
Description: Field mapping configuration tool with three tabs (Contact, Lead, and Account). Provides drag-and-drop style mapping of Salesforce fields to DonorAtlas matching categories. The Account tab is used for Person Account field mappings. Configuration interface

Component Architecture

The sync components use a Visualforce iframe architecture. The host LWC embeds a Visualforce page via iframe, which in turn loads a Lightning Out application containing the actual sync component.

Communication between the iframe and host uses the postMessage API for resize events, toast notifications, and navigation.

This architecture ensures that the DonorAtlas component never interferes with the rest of your Contact/Lead/Account/Campaign pages and never makes them load slower. The DonorAtlas component is essentially loaded as a separate page entirely. Sometimes, this causes it to take an extra second to load the DonorAtlas component.

13. Reports and Report Types

In Salesforce, a report type defines which objects and relationships are available when building a report. DonorAtlas ships with four report types that cover common use cases, and you can create your own if you need different combinations of objects.

Included Report Types

The package includes four report types out of the box:

Running a Report Using an Included Report Type

1. Go to the Reports tab and click New Report
2. In the report type picker, search for “Donor” to find the DonorAtlas report types
3. Select the report type that fits your needs (e.g., “Contacts with Donors”)
4. Click Start Report
5. Add columns from the available sections — for “Contacts with Donors,” you'll see both Contact fields and Donor fields
6. Add filters as needed. Common Donor filters include:
   • Net Worth Min / Net Worth Max — filter by estimated net worth
   • Nonprofit Capacity — filter by estimated giving capacity
   • State / City — filter by location
   • Age — filter by age
7. Click Save & Run

Example Reports

The package installs three example reports in the DonorAtlas Example Reports folder to help you get started:

You can clone these reports and modify them to fit your needs, or use them as references when building your own. Example report

Creating a Custom Report Type

The four included report types cover some common scenarios, but you may need a custom report type if you want to report on other Donor child objects — for example, Donations, Work Experience, Board Affiliations, or Private Foundations. You might also want a report type that combines a child object with Contacts, Leads, or Accounts (e.g., “Contacts with Donors with Board Affiliations”).

Here are the Donor child objects available for custom report types:

To create a custom report type:

1. Go to Setup > search for Report Types > click New Custom Report Type
2. Set the Primary Object — choose the object you want as the starting point:
   • Use Contact, Lead, or Account if you want Contact/Lead/Account fields alongside Donor data
   • Use Donor (Donor__c) if you only need Donor data and its children
3. Give it a name, description, and choose a category (e.g., “Other”)
4. Set Deployment Status to Deployed
5. Click Next to define object relationships:
   • If your primary object is Contact, Lead, or Account, add Donor (Donor__r) as the next level
   • Then add the child object you need (e.g., Donations, Board Affiliations)
   • Salesforce supports up to 4 levels of object relationships in a report type
6. For each join, choose whether records without the related object should be included (outer join) or excluded (inner join)
7. Click Save, then use the Edit Layout button to choose which fields from each object are available to report builders

14. Troubleshooting and FAQ

Sync says “Pending” or “Processing” for a long time

Cause: DonorAtlas can take some time to process a sync request, especially if you're syncing a large number of records.

Resolution: If it's been more than 15 minutes when syncing a single record, contact DonorAtlas support, and include the ID of the Contact, Lead, or Account!

DonorAtlas component isn't showing up on the record page

Cause: The component hasn't been added to the page layout, it hasn't been activated for this user, or the user lacks the required permissions.

Resolution:

1. Verify the user has one of the three DonorAtlas permission sets assigned (DonorAtlas_Integration_Admin, DonorAtlas_Integration_User, or DonorAtlas_Integration_Viewer)
2. Edit the Contact/Lead/Account record page in Lightning App Builder:
   • Click the gear icon > Edit Page
   • Search for donorAtlasSync in the Components panel
   • Drag it onto the page layout
   • Click Save and Activate
3. For Campaign pages, add donorAtlasCampaignSync
4. Make sure the page activation applies to the correct app, record type, and/or profile. Click Activation in the Edit Page dialog to see where it's activated and for which users.

Sync returned “No Match”

Cause: DonorAtlas could not find a matching donor profile based on the information provided.

Resolution:

1. Verify the Contact/Lead/Account has sufficient data for matching (at minimum: first name, last name, and one other piece of information)
2. Check that the field mappings are correctly configured in the DonorAtlas Configuration app
3. Ensure the mapped fields actually contain data on the record being synced
4. Unsync and then Sync the Contact, Lead, or Account again to retry the match.
5. If the issue persists, contact DonorAtlas support, and include the ID of the Contact, Lead, or Account!

My component says “refused to connect”

myorg.vf.force.com refused to connect.

Cause: Your Salesforce environment has clickjack protection enabled, and your Salesforce domain is not configured as a trusted domain. Therefore, Salesforce is blocking the component from loading.

Resolution:

1. Navigate to Setup → Session Settings → Trusted Domains and click Add Domain.
2. Enter the domain in the browser URL bar where you are logged into Salesforce and using Lightning Experience (e.g. myorg.lightning.force.com).
3. Select Visualforce Pages for iFrame Type, and click Save.
4. Go back to the component and check again!

15. Limits and Considerations

Salesforce Governor Limits

• SOQL Query Limit: As a verified managed package, DonorAtlas runs under its own separate SOQL query limit
• Callout Limit: Each sync operation makes HTTP callouts. Salesforce allows 100 callouts per transaction. Bulk syncs batch records in groups of 1,000
• Storage: Plan for approximately 1 Donor record + 5-20 child records per synced Contact/Lead/Account

DonorAtlas API Limits

• Metered based on your subscription plan
• When credits are exhausted, the API returns an HTTP 402 error
• Contact DonorAtlas to upgrade your plan

16. Uninstallation

Before Uninstalling

Uninstallation Steps

1. Go to your DonorAtlas profile page and click on the Salesforce integration Configure button.
2. Click the Uninstall button and wait a few minutes. This will unsync all records from Salesforce and delete all DonorAtlas data from your Salesforce org.
3. Back on Salesforce, go to Setup > Installed Packages and find DonorAtlas and click Uninstall.
4. Review the components that will be removed and click Uninstall.

17. Glossary