Overview#

Class name: ContactPointWriteComponent Friendly name: Write Contact Points Category: MoveData: NPC Purpose: Writes a person's email, phone and address as ContactPointEmail, ContactPointPhone and ContactPointAddress records on their account, reusing any record that already holds the value

Class description#

Nonprofit Cloud keeps a person's contactable values in three related objects rather than on the person record, and those objects are what its reporting, list building and Marketing Cloud sync read. This component maintains them.

It runs once per person the notification resolves, from the contact post-upsert flow, after the person record has been saved and their account id is known. The person record is left alone: their Email, Phone and address fields keep behaving exactly as they always have, one value each, overwritten by the next donation that carries a different one. Contact points accumulate instead, so a supporter who gives a second email address ends up with two records rather than one replaced one.

A value that already has a contact point is reused, and a value that does not gets one. What decides "already has" is the match key: person, contact point type, and the normalised value. That key is the record's identity, which is why the component normalises rather than comparing verbatim. Platforms send the same address in different casing and the same phone number spaced and bracketed differently, and a duplicate contact point is not cosmetic: consent records attach to contact points, so a second copy of a value would split a supporter's permissions across two rows.

The whole component is off until an organisation turns Write Contact Points on. Nothing here throws, either. A contact point is an enrichment of a donation rather than the donation itself, so a rejected write is reported through Error and the donation stands.

Input parameters#

Person and parent#

Email#

Phone#

Address#

Shared#

Output parameters#

Where the values come from#

The Write Contact Points element in the contact post-upsert flow supplies every input, so a value that looks wrong in a notification's log can be traced to either a setting or the payload:

AddressUsageType is the one input the package's own flow does not wire, because no platform sends an address type today. Address contact points therefore take the organisation's default.

Behaviour#

Matching and reuse#

Each type is matched on its own normalised value, within that one person's records:

So (07700) 900 123 and 07700900123 are one phone record, and 021 123 456 and +64 21 123 456 are two. The second pair is one New Zealand mobile to a reader, and that is a known and accepted cost: deciding that a country code and a trunk zero describe the same subscriber is a question every notifier and every extension has, so it is answered centrally rather than inside this component. Until it is, an organisation whose platforms send both forms holds two phone contact points for the one number.

City and state sitting outside the address key is what lets a correction land. A platform that sends the same street and postcode with a corrected city updates the address record the organisation already holds instead of adding a second one, and those two fields are the only source values a matched record is ever updated with.

What is written once and never again#

IsPrimary, ActiveFromDate, the address Name, and the AddressType, PhoneType, UsageType and IsSmsCapable values are set when a record is created and left alone afterwards. A later donation has nothing new to say about them, and re-applying a default would overwrite a choice the organisation's team or another system made.

A matched phone number is not rewritten into the format this platform happens to send, for the same reason. For an organisation running two platforms that would flip the stored value back and forth on every donation, which is the overwrite behaviour contact points exist to avoid.

IsPrimary is true only on the first record of its type for that person. A second email address therefore arrives non-primary, and the first record is untouched.

The address quality gate#

An address scoring below the organisation's threshold is not written. The condition is the person record's own, condition for condition: the skip needs a threshold set, a score present, and the score below the threshold. A missing threshold passes and a missing score passes, which is almost all traffic.

The gate sits above the match, so a below-threshold address cannot update an address the organisation already holds any more than it can add a new one. That follows from reusing the person record's gate rather than from a separate choice, and it is the behaviour the person record has had all along.

When nothing is written#

Each of these is a log line naming the reason, not an error:

One invocation, many people#

Existing contact points are read once per invocation, one query per object, and matched in memory. Records created earlier in the same invocation are matched against too, so two requests for the same person in one notification cannot each create the same contact point.

What ends up on the notification#

Every created, matched, updated and skipped contact point is a log entry on the notification, naming the record and the value it matched on. The ids of the records touched go back as RecordList, matched and updated records as well as created ones, so a consultant can see which record a donation attached to and open it from the notification's Records section.

Error handling#

Configured type values#

All four type settings are checked against the field's active picklist values in that organisation, and a value the field does not carry is dropped, reported in Error, and the contact point written without it.

That check matters most where it is least obvious. AddressType and UsageType are unrestricted picklists, so Salesforce would accept a typo, store it, and then quietly leave the record out of every filtered report. PhoneType is restricted, so a typo there would reject every phone contact point outright. Both failure modes are someone's setting to fix, which is why they are reported rather than silently ignored.

A type the platform sent that the organisation's picklist does not carry falls back to the default without an error, because only a setting is someone's mistake.

Failed writes#

Records are inserted and updated with partial success allowed, so one rejected contact point neither rolls the donation back nor is reported against the other people on the same notification. A rejection sets Success to false, appends the reason to Error and writes a log line. Missing field-level access on the three objects is the common cause; see permission sets.

The flow element also carries a fault connector, so an unexpected failure is caught and recorded rather than failing the stage.

Dependencies#

Required objects#

• ContactPointEmail, ContactPointPhone, ContactPointAddress: the Nonprofit Cloud contact point objects
• Account: the parent of every contact point written

Required classes#

• movedata.MoveDataLogEntry: the pipeline's log entry type
• movedata__NamePatternParserComponent: resolves the address name pattern before this component runs

Related articles#

• Contact post-upsert flow
• Settings
• Permission sets
• Nonprofit Cloud overview