Technical Administration Guide

1. Product Overview

DonorAtlas for Raiser's Edge NXT matches your constituents against the DonorAtlas database and delivers prospect research two ways:

• The DonorAtlas tile, a Blackbaud SKY add-in on every Constituent record page, shows a synced constituent's full DonorAtlas profile.
• Synced fields are written into native RE records — ratings, contact information, relationships, education — where they work in lists, queries, exports, and reporting.

The two are independent. The tile always shows the complete profile; the field configuration (Section 5) controls only what is persisted into RE records. They also have different audiences: the tile renders only for users with a DonorAtlas account, while synced fields are ordinary RE records that every user of your database can see, query, and report on.

Nothing is installed inside your database. The tile is a DonorAtlas-hosted web app rendered by Blackbaud in an iframe, configuration and bulk operations live in the DonorAtlas web app, and the DonorAtlas backend talks to the Blackbaud SKY API to read constituent identity data and write enrichment records.

What the Integration Never Touches

• Gifts. The integration never reads or writes gift records, giving history, or financial transactions.
• Records it didn't create. Every record DonorAtlas writes is tracked individually, and unsync/resync only remove records DonorAtlas created.
• Constituent identity fields. DonorAtlas never edits a constituent's name or other core biographical fields.

2. Prerequisites & Roles

3. Installation & Connection

There is no package to install and nothing to upgrade later. Setup is three steps; the click-by-click version with screenshots is the Quick Start Guide.

Step 1: Connect the Application

An admin opens the DonorAtlas connection link and clicks Connect. This is done once per environment; it makes the DonorAtlas tile appear on Constituent record pages. Connecting by itself grants no data access — that comes from each user's authorization in Step 2.

Step 2: Log In (Each User, Once)

Each user clicks Log in on the tile, signs in to DonorAtlas, and clicks Authorize on Blackbaud's consent screen. The integration links their DonorAtlas team to the RE environment automatically; users who belong to more than one DonorAtlas team pick which one to link.

An RE environment links to exactly one DonorAtlas team, and a team to exactly one environment. The first user to authorize creates the link; everyone after that joins it. If you hit an “already linked” error you didn't expect, contact DonorAtlas support — moving a link is a support action.

Step 3: SKY API Key and Field Selection

After authorizing, you land on the configuration page: enter the team's SKY API subscription key and choose synced fields. Both are covered in Section 5. Once the configuration validates, the integration is live.

4. Authentication Architecture

Three credentials are involved:

OAuth Details

• Authorization uses Blackbaud's standard authorization-code flow with the openid email profile scopes.
• Access and refresh tokens are stored encrypted by DonorAtlas, per user and team, and refreshed automatically. Users are not re-prompted during normal use.
• If Blackbaud invalidates a refresh token (password change, revocation), that user's connection is flagged for re-authorization. The fix is to log in again from the tile.

How the Tile Authenticates

The tile never holds your Blackbaud password or tokens. Blackbaud's add-in framework passes it a short-lived, signed user-identity token proving which Blackbaud user and environment are viewing the page, and DonorAtlas validates that token on every request.

5. Configuration

Configuration lives in the DonorAtlas app: My Profile → Raiser's Edge NXT → Configure. It has two parts: the SKY API key and the synced-field selection.

SKY API Key

Blackbaud requires a subscription key on all SKY API traffic. Your team supplies its own, created with a free Blackbaud developer account; the configuration page links a step-by-step guide. DonorAtlas validates the key with a live SKY API call before saving it.

Synced Fields and Validation

Move fields between Synced Fields and Available Fields, then click Validate Configuration. Several RE record types require matching entries in your database's code tables; validation checks every entry each selected field needs, creates missing ones, reactivates inactive ones, and re-checks. Only fields that pass validation are written during syncs.

Changing the selection later is safe. Newly enabled fields are written on each constituent's next sync or resync, and records for disabled fields are removed on their next resync.

6. Data Model

DonorAtlas adds no custom objects, fields, or schema to Raiser's Edge. Everything is written to native RE record types, so the data works everywhere RE already exposes those records.

Provenance

Every record DonorAtlas writes is identifiable: ratings carry Source: DonorAtlas and DonorAtlas-prefixed category names, addresses carry the DonorAtlas information source, emails and phones use DonorAtlas-prefixed types, and relationships carry a DonorAtlas comment. You can filter, query, or audit exactly what the integration wrote.

Organization Constituents

Employment, board, foundation, and donation relationships need an organization on the other end. When a donor's employer or board isn't in your database, DonorAtlas creates an Organization constituent for it, first searching your existing constituents and reusing an organization whose name matches (ignoring case, punctuation, and spacing).

Sync Tracking

For every synced constituent, DonorAtlas stores (on the DonorAtlas side) the matched profile, the match confidence, who synced it and when, and the ID of every RE record it wrote. That ledger is what lets resync and unsync remove exactly the records DonorAtlas created and nothing else.

7. Data Dictionary

Every field below is individually selectable in the configuration. The names are exactly what you'll see in your database.

Constituent Ratings

Written to the Ratings tab as Currency ratings with Source: DonorAtlas and the sync date.

Contact Information

Relationships

Written to the Relationships tile, each linking to an Organization constituent (Section 6) and carrying a DonorAtlas comment.

Education

Written to the constituent's Education records: school (added to the Schools code table as needed), degree (normalized to a standard Degrees entry like BS, MBA, Ph.D.), and class year.

Length Limits

Blackbaud enforces maximum lengths on several of these records; DonorAtlas truncates to fit rather than fail the write. Rating and relationship comments cap at 255 characters, job titles at 50, school and organization names at 60, degree names at 30, and online presence URLs at 255.

8. Sync Operations

Single Sync (from the Tile)

1. DonorAtlas reads the constituent's identity data from RE: name, address, employer and job title, and school.
2. A matching job runs against the DonorAtlas database (Section 9). The tile shows Pending and checks for a result every 15 seconds; matching typically completes within a minute or two.
3. On a match, DonorAtlas writes every configured, validated field into RE and adds the donor to the team's “Donors Synced with Raiser's Edge NXT” list in DonorAtlas.

Bulk Sync (from the DonorAtlas App)

My Profile → Raiser's Edge NXT → Bulk Sync syncs a saved RE constituent list, or the entire environment via “All Constituents”. Already-synced constituents are skipped, and only Individual constituents are processed.

A bulk sync works through your entire saved list — there is no per-run cap on the number of constituents. Blackbaud limits how fast anyone can write to your database, so a first sync of a large list is paced across many batches and can take a while. Lists with relationship-style fields configured (Employment, Board Affiliations, Private Foundations, Donations, Education, Social Media and Bio Websites) make many more API writes per constituent, so they move more slowly than a ratings-and-contact sync.

Runs are bounded only by your remaining import credits — one credit per constituent. Already-synced constituents are skipped, so re-running a list picks up where the previous run left off.

Resync

Resync refreshes the five ratings, the mailing address, and verified email/phone: it deletes the DonorAtlas-written records for those fields and writes current values. It also removes records for any fields disabled since the last sync.

Unsync

Unsync deletes every RE record DonorAtlas created for the constituent, using the tracked record IDs, then clears the sync link. The constituent and any organization constituents are never deleted.

Send to RE (Constituent Creation)

From a DonorAtlas donor profile, Sync with Raiser's Edge NXT creates a new Individual constituent (first, middle, and last name only) and runs a full sync against it. DonorAtlas searches your database for possible duplicates by name first. Afterward, the profile shows a View button that opens the constituent in RE.

9. Matching

Matching runs on the DonorAtlas identity-resolution engine, the same system used across the platform. No field mapping is needed: RE's standard constituent schema determines where each input comes from. Exactly these fields are read from the constituent and sent to the matcher:

Nothing else is sent. Gift history, notes, actions, custom fields, and constituent codes are not read and are not used in matching.

A match is only accepted when the evidence clears the engine's confidence threshold; otherwise the tile shows No match found and nothing is written to the constituent. Filling in a fuller address or an employer and re-syncing gives the matcher more to work with.

10. Limits & Considerations

SKY API Rate Limits

Blackbaud enforces a strict per-second request limit (on the order of 10 requests per second) and a daily request quota on each subscription key, and the SKY API has no bulk-write endpoint, so every rating, relationship, and education entry is an individual call. DonorAtlas paces all calls made with your key and honors Blackbaud's retry guidance, so rate limiting shows up as slower syncs rather than failures.

Operational Limits

There are no Blackbaud webhooks in this integration. Nothing in RE triggers DonorAtlas automatically; all syncs are user-initiated, and the tile polls for results.

11. Credits

• Syncing a constituent costs 1 import credit, charged when the sync is queued. This applies per constituent in bulk syncs and to constituents created via Send to RE. Resync and unsync are free.
• If a bulk sync is larger than the remaining balance, only as many constituents as the balance covers are queued, and the run reports what was skipped.
• With no credits remaining, syncs are rejected with “Insufficient imports remaining!” Balances are on the DonorAtlas Usage page.

12. Security & Privacy

What DonorAtlas Reads from RE

• Constituent identity data used for matching: name, address, employer and school relationships.
• Saved constituent list names and membership, for Bulk Sync.
• Code tables, for validation (Section 5).

What DonorAtlas Stores

• Encrypted Blackbaud OAuth tokens per authorized user, and the team's SKY API subscription key.
• Sync-tracking rows: constituent ID, matched DonorAtlas profile, match confidence, who synced and when, and the IDs of the RE records DonorAtlas wrote.

Boundaries

• Gift and financial data is never read, transmitted, or stored.
• Every SKY API call runs under a real user's authorization and is bounded by that user's RE security rights.
• All traffic is encrypted in transit (TLS).
• The tile renders only for users with a DonorAtlas account. Data written into RE is not gated that way: it consists of ordinary RE records, visible to anyone whose RE security rights let them see ratings, contact information, relationships, and education.
• Uninstalling removes stored tokens, the subscription key, and the connection (Section 14).

For DonorAtlas's broader security posture and compliance program, see donoratlas.com/security.

13. Troubleshooting

For anything else, request support from inside DonorAtlas or email team@donoratlas.com.

14. Uninstallation

A DonorAtlas team admin can uninstall from the configuration page (Uninstall Integration). Uninstalling:

1. Unsyncs every synced constituent, removing all DonorAtlas-written records from RE.
2. Removes the DonorAtlas rating categories and the DonorAtlas source entry from your code tables.
3. Deletes the stored Blackbaud tokens, the SKY API key, the environment link, and the “Donors Synced with Raiser's Edge NXT” list in DonorAtlas.

To also disconnect the application from your Blackbaud environment, remove it under Marketplace → Manage after uninstalling in DonorAtlas.

15. Glossary