We will need to base this on current recurring donation where present, most recent donation where there is no recurring and to check for changes to the email since the most recent donation (which might indicate the email has been changed in email prefs center or by DR) and not update emails which have been changed since then.
Description
Description
Details
Details
Related Changes in Gerrit:
Customize query in gerrit
Related Changes in GitLab:
| Title | Reference | Author | Source Branch | Dest Branch | |
|---|---|---|---|---|---|
| Add contact save activity diagram | repos/fundraising-tech/fr-tech-diagrams!7 | wfan219 | T416052-contact-save | main |
Event Timeline
Comment Actions
Change #1237534 had a related patch set uploaded (by Wfan; author: Wfan):
[wikimedia/fundraising/crm@master] Replacing email to phone for venmo check
Comment Actions
Change #1237617 had a related patch set uploaded (by Wfan; author: Wfan):
[wikimedia/fundraising/crm@master] Assign location type for 3rd party donaiton
Comment Actions
Change #1237625 had a related patch set uploaded (by Wfan; author: Wfan):
[wikimedia/fundraising/crm@master] add activity type if venmo user name update
Comment Actions
Change #1237534 merged by jenkins-bot:
[wikimedia/fundraising/crm@master] Replacing email to phone for venmo unique identifier check
Comment Actions
Start Processing New Donation
|
v
+----------------------+
| Existing contact ? |
+----------+-----------+
|
+-----+-----+
| |
v v
CREATE UPDATECREATE
|
v
+----------------------------------+
| Third-party payment method ? |
| (apple/google/venmo/paypal/ach) |
+-------------+--------------------+
|
+--------+--------+
| |
Yes| No |
v v
location_type = location_type =
payment_method default (Home)
| |
v v
+----------------------+
| is_primary = 1 |
| (ALWAYS primary) |
+----------------------+
|
v
Contact::create()
|
v
DoneUPDATE email
|
v
+-----------------------+
| Find matching email ? |
+-----------+-----------+
|
No |----------------------------------------------+
| |
| +-------+---------------------+
| | Trusted source? Not From |
| | ach/apple/venmo/paypal/venmo|
| +-------+---------------------+
| |
| +--------+-----------+
| | |
| Yes No
| | |
| v v
| +------------+------------+ +-----------+----------+
| |Set new email as PRIMARY | |Create new SECONDARY |
| |location_type = default | |location_type = source|
| |on_hold = 0 | |on_hold = 0 |
| +------------+------------+ +----------+----------+
Yes | |
| v v
+-----------------------------+ Done Done
| Matched record is PRIMARY ? |
+-----------+-----------------+
Yes | No
| \
v v
+------------------------+ +--------------------------+
| before not trusted | | is exist location type |
| now trusted source ? | | same as new one |
+-------------+----------+ +-----------+--------------+
Yes | No | Yes No
| \ | |
v v v v
+---------------------------+ +----------------+ +---------------------------+
| Update location_type | | Do nothing | | Create new SECONDARY |
| (stay PRIMARY) | | (stay same) | | location_type = new |
| | | | | on_hold = 0 |
+-----------+---------------+ +--------+-------+ +-------------+-------------+
| | |
v v v
Done Done DoneComment Actions
https://docs.google.com/document/d/1PM4TdDRIcDQNv6FlQ4ZQXlbbN9QvaozuYGYbhcIx8dQ/edit?tab=t.0 discussion here to treat ACH the same as we did for un trust source
Comment Actions
I had a chat with a certain friend of mine ... here are the scenarios based on the chart
- After all this I realised I had not thought at all about Email Preference Centre***
Email Handling Scenarios – Donation Imports
This document collates all identified (ahem - that is chatGPT oversell) real-world scenarios for how donor email records are created and updated during donation imports.
Definitions
Trusted sources
- Donor donates via form → creates an email with location type Home
- Staff edits or imports donor → creates an email with location type Other, Main etc
Non-trusted sources
- Payment processors such as PayPal, Venmo, Apple Pay, ACH, etc.
Scenario 1: First-time donor via form
Steps
- Donor donates via form with alice@example.org
Result
- Email created
- Location type: Home
- Set as PRIMARY
Status: OK
Scenario 2: Donor donates again via form with the same email
Steps
- Existing email: alice@example.org (Home, PRIMARY)
- Donor donates via form again with alice@example.org
Result
- Matching email found
- No changes made
Status: OK
Scenario 3: Donor donates via form with a different email
Steps
- Existing email: alice.old@example.org (Home, PRIMARY)
- Donor donates via form with alice.new@example.org
Result
- alice.new@example.org created
- Location type: Home
- Set as PRIMARY
- alice.old@example.org demoted to SECONDARY
Area of concern
- Donor now has two Home emails - CiviCRM does not like multiple of the same location type
- Both are trusted and donor-entered - have we always kept both - or overwritten when the type is the same??
Scenario 4: Donor has staff-created email, then donates via form
Pre-existing state
- Email exists: alice.staff@example.org
- Location type: Other (or Main, etc)
- Set earlier by staff edit or import
Steps
- Donor donates via form with alice@example.org
Result
- alice@example.org created
- Location type: Home
- Set as PRIMARY
- Staff-created email remains SECONDARY
area of concern:
duplicate emails with no meaningful difference (home vs Other === 'meh')
Scenario 5: Donor has staff-created email, donates via form with same email
Pre-existing state
- Email exists: alice@example.org
- Location type: Other (or Main)
- Set earlier by staff edit or import
Steps
- Donor donates via form with alice@example.org
Result
- Matching email found
- Location type may be updated to Home
Area of concern
- There is no good reason to alter location type in this scenario
Scenario 6: Donor has Home email, PayPal sends same email
Steps
- Existing email: alice@example.org (Home, PRIMARY)
- PayPal reports alice@example.org
Result
- Matching email found
- No changes made
Status: OK
Scenario 7: Donor has Home email, PayPal sends different email
Steps
- Existing email: alice@example.org (Home, PRIMARY)
- PayPal reports alice.paypal@example.org
Result
- alice.paypal@example.org created
- Location type: PayPal
- Set as SECONDARY
- Home email unchanged
Status: OK
Scenario 8: Donor has only PayPal email, then donates via form
Pre-existing state
- Email exists: alice.paypal@example.org (PayPal, PRIMARY)
Steps
- Donor donates via form with alice@example.org
Result
- alice@example.org created
- Location type: Home
- Set as PRIMARY
- PayPal email demoted to SECONDARY
Status: OK
Scenario 9: Donor has staff-created email, PayPal sends same email
Pre-existing state
- Email exists: alice@example.org
- Location type: Other / Main
- Created via staff edit or import
Steps
- PayPal reports alice@example.org
Result
- Matching email found
- Location type remains Other/Main
Status OK
Scenario 10: Donor donates via form with new email after staff-created email
Pre-existing state
- Email exists: alice.staff@example.org (Other/Main, PRIMARY)
Steps
- Donor donates via form with alice@example.org
Result
- alice@example.org created
- Location type: Home
- Set as PRIMARY
- Staff email demoted to SECONDARY
Status: OK
Scenario 11: Donor ends up with two different trusted emails of different location types
Steps
- Staff edit or import (earlier) → alice.staff@example.org (Other/Main)
- Donor donates via form → alice@example.org (Home)
Result
- Two trusted emails:
- Home (donor-entered, PRIMARY)
- Other/Main (staff-entered, SECONDARY)
Status: OK -?
Scenario 12: Same email touched by multiple trusted paths over time
Steps
- Staff import (earlier) → alice@example.org (Other/Main)
- Donor later donates via form → alice@example.org
Result
- Email exists twice with Home & Other type
Area of concern
- We have 2 emails but only need 1 - these types are not meaningfully different
Summary of Key Concerns
- Multiple Home emails can be created via repeated form donations ( CiviCRM does not like more than one email with the same location type)
- Can wind up with multiple emails that are the same except for location type, where the location type is not important - ie Main & other
Comment Actions
- Email NOT found (new address)
Trusted source (user typed it directly)
→ Create PRIMARY
location_type = default (Home/Other)
on_hold = 0
Payment/provider source
→ Create SECONDARY
location_type = provider (PayPal/Venmo/etc)
on_hold = 0
- Email FOUND (already exists)
If matched record is PRIMARY
Previously untrusted → now trusted
→ Update location_type_id
→ Stay PRIMARY
Otherwise
→ Do nothing
If matched record is SECONDARY
Same location type already exists
→ Do nothing
New location type
→ Create another SECONDARY
location_type = new provider
on_hold = 0
Comment Actions
wfan219 opened https://gitlab.wikimedia.org/repos/fundraising-tech/fr-tech-diagrams/-/merge_requests/7
Add contact save activity diagram
Comment Actions
wfan219 merged https://gitlab.wikimedia.org/repos/fundraising-tech/fr-tech-diagrams/-/merge_requests/7
Add contact save activity diagram
Comment Actions
Change #1244856 had a related patch set uploaded (by Wfan; author: Wfan):
[wikimedia/fundraising/crm@master] Update lowconfiedence logic to check current primary location
Comment Actions
Change #1237625 abandoned by Wfan:
[wikimedia/fundraising/crm@master] When venmo username update, add activity for old one
Reason:
No longer needed
Comment Actions
Change #1248961 had a related patch set uploaded (by Wfan; author: Wfan):
[wikimedia/fundraising/crm@master] Update lowconfiedence logic to check current primary location
Comment Actions
Change #1244856 abandoned by Wfan:
[wikimedia/fundraising/crm@master] Update lowconfiedence logic to check current primary location
Comment Actions
Change #1244856 restored by Wfan:
[wikimedia/fundraising/crm@master] Update lowconfiedence logic to check current primary location
Comment Actions
Change #1244856 merged by jenkins-bot:
[wikimedia/fundraising/crm@master] Update lowconfiedence logic to check current primary location