Skip to content

Overview#

Class name: ConsentWriteComponent Friendly name: Write Consent Category: MoveData: NPC Purpose: Writes the supporter's channel permissions as ContactPointConsent records, and their email permission as a CommSubscriptionConsent, against the contact points the contact point writer settled

Class description#

A donation form asks the supporter how they are happy to be contacted. Nonprofit Cloud records those answers as consent records hanging off the supporter's contact points, and those records are what its reporting, list building and Marketing Cloud sync read. MoveData discarded the answers until this component: the values arrived on every notification and nothing in the package wrote them anywhere.

It runs once per person the notification resolves, from the contact post-upsert flow, immediately after Write Contact Points. That order is not a preference. Every consent record references a contact point, so the component takes the three per-channel ids from the contact point writer's own response rather than querying for records the same transaction has just written. It also means consent is written only for an organisation that writes contact points: switch those off and nothing here runs.

Who consent is written for is the flow's decision, not the component's. The flow does not call it without a person account, or for the organisation's shared anonymous one, where pooling unrelated donors' permissions onto one record would make every one of them wrong.

Two objects are written, for two different purposes:

Object What it is for
ContactPointConsent One record per channel the supporter opted in to: email, phone, SMS or post. The audit trail of what they agreed to, and what channel-aware reporting reads.
CommSubscriptionConsent The supporter's subscription to a named communication subscription. Marketing Cloud will only send to a supporter who holds one of these.

There is no master switch. The four channels and the subscription are five independent settings, every one of them off until a consultant turns it on, so an organisation that has configured nothing is unchanged. A switch is on only when it is true: one a flow leaves unset, or a setting stored with no value, is off, the same as false. Nothing here throws: consent is an enrichment of a donation rather than the donation itself, so a rejected write is reported through Error and the donation stands.

Three things, and a record is matched on all three:

Part Field Always set?
where ContactPointId Yes
how EngagementChannelTypeId Only when the channel's Engagement Channel Type is named in the settings
why DataUsePurposeId Only when the channel's Data Use Purpose is named in the settings

Both names are optional and both default to blank, because a stock Nonprofit Cloud org has no EngagementChannelType records and a defaulted name would resolve to nothing. Blank matches blank: an existing record carrying no engagement channel is not the record a configured channel matches, so a new one is written beside it rather than the old one being relabelled.

A name that is filled in and resolves to no record is a misconfiguration, not a blank. That channel's consent is skipped and logged with the name it looked for, because a record written without the value the consultant configured would be filed under an identity nobody asked for — and the next correctly configured donation would not match it.

Phone and SMS#

They are the only two channels sharing a contact point: a supporter has one ContactPointPhone, and both their phone permission and their SMS permission attach to it. The engagement channel, the purpose, or both are what keep the two records apart.

With both channels on and an identical engagement channel and purpose — including both blank — neither record is written. The two would be indistinguishable, and merging them or picking one would record something the supporter may not have meant. The log carries the reason, the other channels and the contact points are untouched, and the donation succeeds. There is no merge option: an organisation that does not distinguish calls from texts turns Phone on and SMS off.

Input parameters#

Person and parent#

Parameter API name Type Description
Parent Account ID ParentId Id The supporter's person account. Written as the subscription consent's consent giver. No id, nothing written. The calling flow does not call the component for the anonymous person account.
List of Log Entries LogList List The flow's log collection. Every consent record written, matched or skipped is appended to it and handed back.
Parameter API name Type Description
Email Contact Point ID EmailContactPointId String From Write Contact Points. Null when no email contact point was settled, in which case email consent is skipped. A value that is not a record id is skipped the same way, and named in the log.
Phone Contact Point ID PhoneContactPointId String From Write Contact Points. Carries both the phone and the SMS consent records.
Address Contact Point ID AddressContactPointId String From Write Contact Points. Carries the postal consent record.

What the platform sent#

Parameter API name Type Description
Consent: Email ConsentEmail Boolean The payload's communication.email. Only true writes anything.
Consent: Phone ConsentPhone Boolean The payload's communication.phone.
Consent: SMS ConsentSms Boolean The payload's communication.sms.
Consent: Post ConsentPost Boolean The payload's communication.mail.
Consent: Any Channel ConsentAny Boolean The payload's communication.any. Writes nothing, and is logged when it is the only permission sent.
Consent Statement ConsentStatement String The wording the supporter agreed to, where the platform sends it.
Platform Label PlatformLabel String The source platform's display name, recorded as the capture source.

When the supporter was asked#

Parameter API name Type Description
Capture Date Time CaptureDateTime String When the supporter was asked, as ISO 8601 text. The packaged flow hands over the payload's communication.consent.capturedAt.
Activity Date Time ActivityDateTime Datetime The donation date. Used as the capture date when the platform sent no timestamp that reads as a date.

The organisation's settings#

Parameter API name Type Description
Write Email Channel WriteChannelEmail Boolean Whether an email ContactPointConsent is written. Does not govern the subscription consent.
Write Phone Channel WriteChannelPhone Boolean
Write SMS Channel WriteChannelSms Boolean
Write Post Channel WriteChannelPost Boolean
Purpose Name: Email PurposeNameEmail String The Data Use Purpose email consent is recorded under. Optional; blank leaves the field empty. A name that resolves to nothing skips the channel.
Purpose Name: Phone PurposeNamePhone String
Purpose Name: SMS PurposeNameSms String Identical to the phone channel and purpose writes neither record.
Purpose Name: Post PurposeNamePost String
Engagement Channel: Email EngagementChannelNameEmail String The Engagement Channel Type email consent is recorded against. Optional, same rules as the purpose.
Engagement Channel: Phone EngagementChannelNamePhone String
Engagement Channel: SMS EngagementChannelNameSms String Identical to the phone channel and purpose writes neither record.
Engagement Channel: Post EngagementChannelNamePost String
Subscription Engagement Channel Name SubscriptionChannelName String The Engagement Channel Type the subscription's channel record is found on. The subscription path's own setting, separate from the email row's above, and required when the subscription switch is on.
Write Communication Subscription Consent WriteSubscription Boolean The subscription section's own switch. Off writes no CommSubscriptionConsent, whatever the email channel switch says.
Subscription Name SubscriptionName String The communication subscription email consent is recorded against. Blank writes no CommSubscriptionConsent, and says so in the log.
Consent Statement Field StatementField String The organisation's own field for the consent wording, the same name on both objects. Blank writes the wording nowhere.

Output parameters#

Parameter API name Type Description
Success Success Boolean (required) False when a write failed. The donation still succeeds.
Error Error String Null unless a write failed. The flow appends it to the pipeline's error collection.
List of Log Entries LogList List (required) One entry per consent record created, updated, matched, left unchanged or skipped.
Json Output of Log Entries LogJson String JSON-encoded version of the same log entries.
Record IDs RecordList List of String The consent records this donation created or updated. The flow adds them to the contact point ids already in the notification's Records section.

Where the values come from#

The Write Consent element in the contact post-upsert flow supplies every input:

Input Supplied from
ParentId Record.Id, the person account the stage has just upserted
The three contact point ids Write_Contact_Points' own response
ConsentEmail, ConsentPhone, ConsentSms, ConsentPost, ConsentAny The payload's CommunicationEmail, CommunicationPhone, CommunicationSms, CommunicationMail and CommunicationAnyComms
CaptureDateTime CommunicationConsentCapturedAt, the payload's communication.consent.capturedAt
ActivityDateTime The donation date, or the person's created date when the donation carries none
ConsentStatement CommunicationConsentStatement, the payload's communication.consent.statement, which JustGiving sends
Email, Phone, Street, PostalCode The payload's own values, used only to compose a readable record name
Everything else The matching consent settings

Behaviour#

What writes a record, and what does not#

The platform sent What happens
true for a channel An opt-in is written or updated for that channel
false Nothing, and a log line saying so
Nothing at all Nothing, and no log line: most forms ask about some channels and not others
A general permission only Nothing, and a log line explaining why. It names no channel, and every consent record must name one

Only an opt-in is ever written. Neither platform captures a withdrawal on a donation form, so OptOut and OptInPending are never written by this component — though a newer opt-in does supersede a record carrying either.

Newer wins#

An existing consent record is updated only when the incoming capture timestamp is later than the record's last modified date. That is the rule that protects a withdrawal: a supporter who unsubscribes in a preference centre today, and whose donation from last month is then replayed, keeps their opt-out. The same notification processed twice changes nothing the second time, and the log says why.

A donation that carries no date at all, neither a capture timestamp nor a donation date, cannot be shown to be newer than anything. It creates a consent record where there is none, stamped with the time it was processed, and never updates one that is already there.

EffectiveFromDate on a subscription consent is set when the record is created and never restamped. It records when the supporter's subscription began, and a later opt-in on the same subscription does not begin it again.

The capture date#

The platform's own timestamp when it reads as a date, otherwise the donation date. It comes from the payload's communication.consent.capturedAt, which every platform that sends a capture time fills, so the flow reads one variable whichever platform the donation came from. That variable is supplied by MoveData 1.361 and later. On an earlier version it is blank and the donation date is used.

The platform value arrives as the raw text the payload carried rather than as a typed date, deliberately. A custom value is whatever the platform put in it, and a flow variable that cannot convert what it is handed fails the whole donation before the flow starts. A value that cannot be read as a date therefore falls back to the donation date and writes a log line, and the donation is unaffected.

The email channel and the subscription are independent#

The Email channel switch governs the email ContactPointConsent only, and Write Communication Subscription Consent governs the CommSubscriptionConsent. An organisation that manages email preferences in a preference centre turns the channel off and the subscription on, and keeps the record Marketing Cloud needs without a second place to manage email consent. Both read the same communication.email permission.

Written to the organisation's own field, found by describe before anything is written. It is a custom field on a standard object, so MoveData can neither ship it nor grant permission on it: a field name that does not exist, a field that is not a text or text area field, or one the integration user cannot edit becomes a log line naming which, and the consent records are written without the wording.

When nothing is written#

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

Nothing written Reason
Anything at all No ParentId. The flow does not reach the component at all for a missing person account or the anonymous one, so neither has a log line
A channel The organisation switched that channel off, or never switched it on
A channel No contact point was written for it, or the id handed over is not a record id, so there is nothing to hang consent on
A channel A configured Engagement Channel Type or Data Use Purpose name matches no record in the org
Phone and SMS Both channels are on with an identical engagement channel and purpose, including both blank, so the two records could not be told apart
The subscription consent The organisation switched the subscription section off, or never switched it on
The subscription consent No subscription named, the name matches no record, or the subscription has no channel on the configured email engagement channel

A configured name that no longer resolves — an administrator renamed the record — skips that one channel and logs the name it looked for. Every other channel still writes, and the donation succeeds.

One invocation, many people#

Configuration is resolved by name in up to four queries, and kept for the rest of the transaction. The flow runs once per person on a notification, so the first person pays for those queries and the next pays for none. Nothing is kept beyond the transaction: a renamed or deleted record is seen by the next notification.

Only the names something is about to be written under are looked up, and the existing consent records are loaded, in up to two more queries, only for the contact points a record is about to be written against. A donation that can write nothing, such as one carrying only a general permission, runs no queries at all. An organisation with the subscription section off runs neither of the two queries that path needs.

Record names are not unique. Where two records share a configured name the oldest is used, every time. Where an organisation already holds two consent records with the same contact point, engagement channel and purpose, the most recently changed is the one matched.

A record settled earlier in the same invocation is matched against rather than inserted again, so the same supporter appearing twice on a notification cannot produce a duplicate. A contact point id in its 15 character form matches the same record as its 18 character form.

Writes are grouped by object and allow partial success, so one rejected consent record neither rolls the donation back nor is reported against the other people on the same notification.

What ends up on the notification#

Every created, updated, matched, unchanged and skipped channel is a log entry naming the record and the reason. The ids of the records created and updated go back as RecordList and are added to the contact point ids already there, so the notification's Records section shows the contact points and the consent records hanging off them.

Error handling#

A rejected write sets Success to false, appends the reason to Error and writes a log line. Missing object or field-level access on the two consent objects is the common cause; see permission sets. The flow element also carries a fault connector. An unexpected failure is recorded against the notification and ends the contact post-upsert flow there: nothing after it runs for that person, the account relationship and the platform key included. That is different from a rejected write, which the component reports itself and the flow carries on from.

Dependencies#

Required objects#

  • ContactPointConsent, CommSubscriptionConsent: the records written
  • ContactPointEmail, ContactPointPhone, ContactPointAddress: what the consent records reference
  • DataUsePurpose: what tells one channel's consent from another's
  • EngagementChannelType, CommSubscription, CommSubscriptionChannelType: the subscription path

All seven are Nonprofit Cloud objects. The organisation creates the DataUsePurpose, EngagementChannelType, CommSubscription and CommSubscriptionChannelType records itself; MoveData reads them by name and never creates them.

Required classes#

  • movedata.MoveDataLogEntry: the pipeline's log entry type
  • ContactPointWriteComponent: supplies the contact point ids, and must run first
Ask MoveData AI
Ask about setup, configuration, or troubleshooting
How can I help you with MoveData today?