Dynamics 365 Integration Documentation

Overview

The Dynamics integration (accessed via Settings → Dynamics Integration) allows organizations to connect their BetterUnite account to a Microsoft Dynamics 365 environment and synchronize contacts, donors, and donations using the Microsoft Nonprofit Accelerator (MSNFP) entities.

Integration Setup Steps

1. Prerequisites

(Optional) The Microsoft Nonprofit Accelerator installed for donation/transaction sync (if not installed, only contact sync is available)

Integration Options (Connected State)

Option A: Sync Contacts

Triggered from the Contacts page → Actions → Export Results
Matching logic: searches Dynamics by primary email address to find existing records

0 matches → creates new contact/account
1 match → updates the existing record (only populates blank fields)
Multiple matches → returns an error for that record

Option B: Sync Donations & Donors

Available only when MSNFP is detected

The UI shows all BetterUnite campaigns with a dropdown to map each to a Dynamics Campaign

Sync flow:

Map campaign – user selects a Dynamics Campaign from the dropdown for each BetterUnite fundraiser to map campaigns between platforms

Sync Donations – processes donations in batches (paginated), for each:

Resolves/creates the donor contact in Dynamics
Creates an msnfp_transaction record

Single donation sync – for individual retry with optional manual contact selection
Validate Contact – checks if a donor can be matched before syncing

Progress & Error Handling:

Progress bar updates per batch (totalProcessed / totalCount)

Errors displayed inline with option to select from multiple matching contacts

Donations can be marked with a sync status

Option C: Remove Connection

Removes the stored credentials and unlinks the organization

Attribute Mappings

Contact → Dynamics contact

BetterUnite Field	Dynamics Attribute	Notes
FirstName	firstname	Only set if target is blank
LastName	lastname	Only set if target is blank
EmailAddress	emailaddress1	Only set if target is blank; also used as match key
CellPhone	mobilephone	Only set if target is blank
BusinessPhone	telephone1	Only set if target is blank
HomePhone	telephone2	Only set if target is blank
AddressLine1	address1_line1	Only set if target is blank
AddressLine2	address1_line2	Only set if target is blank
City	address1_city	Only set if target is blank
StateOrProvince	address1_stateorprovince	Only set if target is blank
PostalCode	address1_postalcode	Only set if target is blank

Account (Contact:DonorType=Company) → Dynamics account

BetterUnite Field	Dynamics Attribute	Notes
Account.Name	name	Always set
EmailAddress	emailaddress1	Only set if target is blank
CellPhone	mobilephone	Only set if target is blank
BusinessPhone	telephone1	Only set if target is blank
AddressLine1	address1_line1	Only set if target is blank
AddressLine2	address1_line2	Only set if target is blank
City	address1_city	Only set if target is blank
StateOrProvince	address1_stateorprovince	Only set if target is blank
PostalCode	address1_postalcode	Only set if target is blank

Transaction → Dynamics msnfp_transaction (Nonprofit Accelerator)

BetterUnite Field	Dynamics Attribute	Type
Amount	msnfp_amount	Money
ReceivedDate	msnfp_receiveddate	DateTime
BookDate	msnfp_bookdate	DateTime
DataEntrySource	msnfp_dataentrysource	OptionSetValue
CalculatedName	msnfp_name	string
ReceiptOnContactId	msnfp_receiptoncontactid	EntityReference → contact
CampaignId	msnfp_originatingcampaignid	EntityReference → campaign
CampaignId	msnfp_effectivecampaignid	EntityReference → campaign
Anonymity	msnfp_anonymity	bool/int

Contact ID Persistence & Reuse

When a BetterUnite contact is synced to Dynamics (either via contact export or as part of a donation sync), the resulting Dynamics GUID is stored on the BU CONTACT record.

Note: Despite the column name, this field stores both Dynamics Contact and Account IDs. The DonorType on the CONTACT record determines which Dynamics entity type it references.

Donation-Level Tracking

Each DONATION record independently tracks its own Dynamics sync state:

Column	Type	Purpose
dynamics_id	Guid?	The msnfp_transaction GUID created in Dynamics
dynamics_syncstatus	SyncStatus?	Sync outcome (Success, Error, etc.)
dynamics_syncdetail	string	Error detail message if sync failed

Sync Lookup Sequence

On each donation sync, the following resolution order is used for the donor:

Step 1 — Check for existing link Does BetterUnite CONTACT have a Dynamics Id value?

Yes → Step 2

No → Step 4

Step 2 — Retrieve by stored ID using the stored GUID.

Found → Use existing Dynamics record. Proceed to transaction export.

Not found / error → Step 3

Step 3 — Stored ID is stale The previously linked record may have been deactivated or deleted in Dynamics. Fall back to → Step 4.

Step 4 — Search Dynamics by email Query Dynamics contact or account entities where emailaddress1 matches the donor's email.

0 matches → Step 5

1 match → Step 6

Multiple matches → Step 7

Step 5 — Create new record Create a new contact or account in Dynamics. Store the new GUID in the BetterUnite CONTACT. Proceed to transaction export.

Step 6 — Use matched record Use the single matching record. Store the GUID in BetterUnite CONTACT. Proceed to transaction export.

Step 7 — Ambiguous match (manual resolution required) Return an error to the UI with the list of matching records. The user sees a dropdown next to the donation row to select the correct Dynamics contact/account. Once selected, re-syncing sends the chosen GUID, which is stored in the BetterUnite CONTACT and used for the transaction export.