Upgrading DonorSearch in Salesforce.

Treat the upgrade as a parallel migration.

The safest approach is to install DonorSearch 360+ alongside the legacy package in a sandbox.

Do not begin by uninstalling the old package. A parallel installation gives administrators time to:

• Configure the new package.
• Migrate existing DonorSearch profiles.
• Rebuild field mappings.
• Validate user permissions.
• Update dependent automation.
• Test screening and result delivery.
• Identify metadata that still references the legacy namespace.

DonorSearch's current installation guide directs customers to install 360+ from Salesforce AppExchange or through a package link supplied by their representative. It also describes separate configuration steps for permission sets and Lightning components. See the DonorSearch 360+ Standard Guide.

For most organizations, installing for administrators first provides the most controlled starting point. Broader access can then be assigned after configuration and testing.

Inventory the legacy implementation before changing it.

Before running the migration wizard, document how the legacy package is used. At minimum, inspect:

• Installed package name, namespace, and version.
• Profiles and permission sets with access to package objects.
• Users receiving that access through profiles or permission sets.
• Apex classes, triggers, scheduled jobs, and flows.
• Reports and dashboards based on legacy package data.
• Page layouts, Lightning pages, list buttons, and quick actions.
• Integration users and connected applications.
• ETL, reporting, middleware, or data warehouse queries.
• Any downstream objects where DonorSearch results are copied or transformed.

This inventory is important because the migration wizard can move package-supported configuration and data, but it cannot understand every customization a Salesforce customer has built around the old package.

Expect a different data model.

One of the most important lessons is that DonorSearch 360+ is not simply the legacy package with a new namespace.

The new package stores screening results in its own profile-oriented model. Organizations that previously reported directly from legacy package records—or copied the data into another reporting model—must review how the new profile data should flow downstream.

DonorSearch describes 360+ as supporting Contact, Lead, and Person Account screening and exposing wealth and philanthropic insights in Salesforce. See the DonorSearch Salesforce integration overview.

Build a field crosswalk with three columns:

1. Legacy DonorSearch field.
2. DonorSearch 360+ equivalent.
3. Downstream destination or business use.

Classify each field as:

• Direct replacement.
• Replacement requiring transformation.
• No longer available.
• Newly available in 360+.
• Historical value that should be preserved.
• Field requiring business-owner review.

Do not automatically clear historical values when the new package has no corresponding field. Preserving the last known value is often safer until data owners decide how discontinued attributes should be handled.

Review every automation dependency.

Custom automation is often the greatest technical risk.

An organization may have a scheduled or batch process that reads legacy DonorSearch records and moves selected values into reporting, prospect-management, or analytics structures. After installing 360+, that automation may still compile and run—but continue reading the old data.

Updating it may require more than changing a namespace. The new model can have:

• Different object relationships.
• Renamed or consolidated fields.
• Different identifiers.
• Different status values.
• Fields that no longer have direct equivalents.
• Multiple profiles associated with the same household or organization.

Matching logic deserves particular attention. A robust synchronization process should normally prefer a unique DonorSearch profile identifier, then use an individual record relationship as a fallback. Matching only at the household or organization level can merge results belonging to different people.

Automated tests should cover updating an existing result, creating a result when no match exists, preventing duplicates, multiple people associated with one account, missing source values, and preservation of legacy-only historical values.

Rebuild and verify screening-input mappings.

The migration wizard may migrate profiles successfully while skipping field mappings.

This can happen when the new package has not yet created the necessary input-configuration records for Contacts, Leads, or Person Accounts. If that occurs:

1. Open DonorSearch Settings.
2. Configure the input mappings for each supported record type.
3. Save the mappings.
4. Rerun the field-mapping portion of the migration.
5. Verify the saved configuration directly.

Start conservatively. Name and postal address fields are usually the minimum useful screening inputs. Add email, phone, business information, giving history, or other attributes only when the organization has confirmed that they are appropriate and intentionally included.

Do not assume permissions migrate automatically.

Permission migration should be treated as its own workstream.

DonorSearch 360+ provides package permission sets, but organizations must still determine who should receive them. A good migration process compares legacy effective access with the new package access model.

Review both access inherited from profiles and access assigned through permission sets or permission-set groups. For each user population, decide whether it needs:

• Standard DonorSearch access.
• Administrative DonorSearch access.
• Read-only reporting access.
• Access only through an integration user.

Also verify field-level security for package fields on Contact, Lead, Person Account, and the new DonorSearch profile records.

Avoid granting administrative access simply because a user could previously read the legacy object. Apply least privilege and verify access using representative business and integration users.

Understand the supported screening experience.

A common request is an Account-level button that screens every eligible person associated with the account. Organizations should not assume that this workflow exists out of the box.

The standard package experience may instead submit selected Contacts or Leads from a list view, or submit records through a Salesforce report. DonorSearch advertises report-based screening and scheduled screening as supported capabilities in its integration overview.

If you need a custom Account-level action, first ask DonorSearch for a documented integration surface, such as:

• A global Apex method.
• An invocable action.
• A supported Flow input contract.
• A documented API endpoint.
• A supported batch-record creation pattern.

Managed-package classes and components can be visible in Salesforce metadata without being callable from subscriber code. Building against hidden implementation details creates an upgrade and support risk.

Expect screening to be asynchronous.

A successful submission does not necessarily mean the DonorSearch profile is immediately available. The package can:

1. Create a batch job.
2. Submit it to DonorSearch.
3. Poll for status asynchronously.
4. Receive the completed screening results.
5. Create or update the corresponding Salesforce profile.

During testing, monitor both the package batch job and the resulting profile record. A job that remains in Processing without a Salesforce exception may be waiting on vendor-side processing rather than failing in your organization's Apex.

If processing takes unusually long, capture the batch name and Salesforce record ID, creation time, source and object type, current status and phase, submitted and failed record counts, package error message, and relevant scheduled and asynchronous job results.

Send that evidence to DonorSearch Client Support rather than repeatedly submitting duplicate jobs.

Test the complete data path.

A migration is not complete when the wizard finishes. End-to-end testing should prove that:

• A supported Salesforce record can be submitted.
• The package creates a batch job.
• The batch reaches a terminal status.
• A new DonorSearch profile is created or updated.
• Users can see the profile from the relevant record.
• Downstream synchronization processes the new profile.
• Existing results update without duplication.
• Reports and integrations can query the new data.
• Integration users have the required access.
• No process still depends on the legacy namespace.

Add the new DonorSearch related lists or Lightning components to the relevant record pages so users can actually see the results. The standard guide notes that the rating widget must be added manually to the Lightning record pages an organization uses.

Make uninstalling the old package the final phase.

Salesforce will prevent the legacy package from being uninstalled while subscriber-owned metadata still references it.

Typical blockers include page layouts, Lightning record pages, list-view buttons, quick actions, flows, reports and report folders, custom code, related lists, object-specific actions, and deleted reports still present in the Recycle Bin.

Use Salesforce metadata dependency analysis to distinguish subscriber-owned blockers from components owned by the managed package. Package-owned components are normally removed with the package; subscriber-owned references must be updated or deleted first.

Keep a metadata backup before cleanup. Remove legacy references in the sandbox, deploy the cleanup, test again, and only then retry the uninstall.

Manage the dependencies, not just the package.

The upgrade to DonorSearch 360+ is manageable, but it should be treated as a controlled Salesforce migration rather than a package-version update.

The biggest risks are usually not the package installation itself. They are the dependencies around it: automation, permissions, mappings, reporting, integration users, page configuration, and old metadata that must be removed before uninstall.

Organizations that inventory those dependencies first, run both packages in parallel during testing, and validate the full screening-to-reporting lifecycle will have a far smoother cutover—and far fewer surprises when it is time to remove the legacy package.