Field Mapping and Custom Fields on Receipts

Field mapping controls which information is copied from a gift onto the receipt. Together with receipt templates, it decides what appears on the PDF. This page explains how mapping works and covers two common tasks:

• adding your own custom field to a receipt
• showing text only when a field has a value

It is written for Salesforce administrators. For the objects and fields involved, see the Data Model page.

How Field Mapping Works

A PDF receipt is built in two steps:

1. The Receipt record is created. Field mappings copy values from the gift (Gift Transaction) or the Gift Commitment onto fields on the new Receipt.
2. The PDF is generated. The receipt template is HTML containing merge fields such as {!dryad__Receipt__c.dryad__Donor_Name__c}, which are replaced with values from the Receipt record.

Templates can only read fields on the Receipt record. Anything from the gift that you want on the PDF must first be mapped onto the Receipt, or be calculated by a formula field on the Receipt.

Mappings Are a Snapshot

Values are copied once, when the receipt is created. Editing the gift afterwards does not change an existing receipt. This is deliberate: an issued official receipt should keep the details it was issued with. To show corrected information, issue a replacement receipt.

Source Objects and Targets

Mapping tab	Used for	Can map to
Gift Transaction	Receipts created from gift transactions: single receipts, and consolidated receipts that group a donor's gifts.	Receipt
Gift Commitment	Consolidated receipts created for a gift commitment, such as a recurring donation. Only these mappings are applied to them: the Gift Transaction mappings are not. The donor's name, email, address, delivery preference and the Receipting Account always come from the commitment.	Receipt

Consolidated Receipts

A consolidated receipt combines several gifts, but it has only one Receipt record.

• For consolidated receipts that group a donor's gifts, the Gift Transaction mappings are applied for each gift in turn, so each Receipt field ends up holding the value from the last gift processed. This works for values that are the same for every gift, such as donor name, address, receipting account or template.
• For consolidated receipts created for a gift commitment, the Gift Commitment mappings are applied once.
• Values that differ from gift to gift (a gift note, a campaign, a fund) can't be shown per gift: a receipt has no per-gift lines. The gifts a receipt covers are listed under its Receipt Assignments.
• Amount and date fields on consolidated receipts are calculated by the app, not copied: amounts are totals, the receipt carries the date range of the gifts, and the receipt year is the year of the earliest gift.

Managing Field Mappings

Go to the Dryad Receipting Settings page > Field Mappings, then pick the tab for the source object. You need the Receipt Admin permission set.

• Add a mapping, then choose the source field and the Receipt field. The field lists show API names with field types, for example Gift_Note__c (STRING).
• Deactivate a mapping by switching off its Active toggle. Inactive mappings are kept but ignored.
• Delete a mapping you no longer need.

Reset to Default deletes your custom mappings. The Reset to Default button deletes all field mappings, on both tabs, including ones you added, and recreates the package defaults. Note your custom mappings before you use it.

Rules for a Valid Mapping

• The target must be writable. Don't map to a formula, roll-up or auto-number field. Receipt fields that the app sets itself are left out of the list.
• The field types must be compatible: text to text, number or currency to number or currency, date to date, checkbox to checkbox, and a lookup to a lookup on the same object. To put a number or date into a text field, create a text formula on the source object first, then map that formula.
• The source field must be on the source object itself. You can't map a field from a related record, such as the Gift Transaction's Campaign or Donor. Create a formula field on the source object that reads the related value, for example Campaign.Name, then map that formula.
• Each target field should be mapped once per tab. If two mappings on the same tab write to the same target, only one of them is used.

A mapping that breaks these rules doesn't show an error when you save it. The error appears later, when receipts are created. After every change, create one test receipt before running a batch.

How To: Show a Custom Field on the PDF

Example: you have a custom field Gift Note (Gift_Note__c, Text 255) on Gift Transaction and want it printed on the receipt.

1. Create a matching field on Receipt. In Setup > Object Manager > Receipt, create a field of the same type, for example Gift Note (Gift_Note__c, Text 255). Make it a normal field, not a formula.

2. Give users access. The field must be readable by everyone who creates or previews receipts, and editable by everyone who creates them. The packaged permission sets can't include your own fields, so grant access through a profile or your own permission set.

3. Add the mapping. In Settings > Field Mappings > Gift Transaction, click Add:

   • Gift Transaction field: Gift_Note__c
   • Receipt field: Gift_Note__c
   • Active: on

   If you also create receipts for gift commitments, add the same mapping on the Gift Commitment tab, using a matching field on Gift Commitment.

4. Add the merge field to your template. Open the template, place the cursor where the value should go, and choose it from the Insert Receipt Field button. This inserts {!dryad__Receipt__c.Gift_Note__c}. Fields you create have no dryad__ prefix on the field name. The object name always keeps it: dryad__Receipt__c.

5. Test. Create a new receipt from a gift that has a Gift Note, then preview the template with that Receipt's ID. Receipts created before you added the mapping don't have the value.

When You Don't Need a Mapping

If the value can be worked out from fields already on the Receipt, skip the mapping and create a formula field on Receipt instead. The Receipt has lookups to the donor's Account (dryad__Donor__c) and to the Receipting Account (dryad__Receipting_Account__c), so a formula can also read donor details, for example dryad__Donor__r.Salutation for a person account.

	Mapping	Formula on Receipt
Value is taken	Once, when the receipt is created	Every time the receipt or PDF is generated
Best for	Gift details that must not change after issue	Wording, formatting and conditions based on Receipt fields; current donor details
Watch out	Old receipts don't get the value	A regenerated PDF can differ from the one originally sent if the related record changed

Dates and amounts. Merge fields print raw Salesforce values. For dates, use the packaged formatted date fields, such as dryad__Issue_Date_Formatted__c and dryad__Transaction_Date_Formatted__c. They apply your Date Format setting, which is why the raw date fields aren't offered in the Insert Receipt Field button. For your own dates or amounts, create a text formula that formats the value the way you want.

How To: Show Text Only When a Field Has a Value

Templates don't support IF logic directly. Instead, put the logic in a text formula field on Receipt that returns the wording when a condition is met and returns nothing otherwise. Then add that formula field to the template.

The package uses this pattern itself: Replacement Text (EN) prints "This cancels and replaces receipt …" only on replacement receipts, and Voided Text (EN) prints "VOID" only on voided ones.

Formulas in your org must use the dryad__ prefix for packaged fields, as in the examples below. A formula may return simple HTML such as <br/>, <strong> or <p>, which is rendered on the PDF.

Example 1: Line Only When a Field Is Filled In

Print the Gift Note from the previous section, with a label, only when there is one. Create a Receipt formula field Gift Note Line (Formula, return type Text):

IF(
  ISBLANK(Gift_Note__c),
  "",
  "<p><strong>Note:</strong> " & Gift_Note__c & "</p>"
)

In the template: {!dryad__Receipt__c.Gift_Note_Line__c}. When the note is blank, nothing is printed and no empty label is left behind.

Example 2: Appraiser Details

The appraiser's name and address are mapped to the Receipt by default, and CRA requires them on receipts for appraised gifts in kind. A Receipt formula Appraiser Line (Text):

IF(
  ISBLANK(dryad__Appraiser_Name__c),
  "",
  "Appraised by " & dryad__Appraiser_Name__c
    & ", " & dryad__Appraiser_Address__c & "<br/>"
)

Example 3: Fallback Value

Use BLANKVALUE to print a default when a field is empty. A Receipt formula Salutation (Text): BLANKVALUE(dryad__Donor_First_Name__c, "Friend")

In the template: Dear {!dryad__Receipt__c.Salutation__c},

Example 4: Show or Hide a Whole Block

For a longer, formatted section that you want to keep editable in the template, use a formula that returns a CSS value instead of the text itself. A Receipt formula Show Advantage (Text): IF(dryad__Advantage_Amount__c > 0, "block", "none")

Then wrap the section in the template, using the editor's the Code View button (</>):

<div style="display:{!dryad__Receipt__c.Show_Advantage__c}">
  <p>Value of advantage: {!dryad__Receipt__c.dryad__Advantage_Amount__c}<br/>
  {!dryad__Receipt__c.dryad__Advantage_Description_EN__c}</p>
</div>

Always check the result with the Preview button, using one receipt where the condition is true and one where it is false.

Formula on Receipt or on the gift? A formula on Receipt is recalculated whenever the PDF is generated, which suits conditions based on Receipt fields (status, replacement, mapped values). If the wording depends on gift fields that aren't mapped, create the text formula on the Gift Transaction or Gift Commitment, map it to a Text field on Receipt, and the wording is fixed at the time of issue.

Troubleshooting

Symptom	Check
The value is blank on the PDF	Was the receipt created after the mapping was added? Is the mapping Active, and on the right tab for how the receipt was created (Gift Transaction or Gift Commitment)? Does the gift have a value? Does the user have read access to the Receipt field? On a consolidated receipt, was the value on the last gift processed? See Consolidated Receipts.
Receipts fail to be created after adding a mapping	The target field is a formula or read-only, the field types don't match, or the user creating receipts can't edit the target field. Fix or deactivate the mapping.
A recurring donation receipt is missing a value that single receipts show	Receipts created for a gift commitment use only the Gift Commitment mappings. Add a mapping on the Gift Commitment tab.
The merge field prints as blank even though the Receipt has a value	Check the spelling: it must be {!dryad__Receipt__c.Your_Field__c}, with the dryad__ prefix on the object and on packaged field names, and no prefix on your own fields. Merge fields can't follow lookups (for example dryad__Donor__r.Phone); use a formula field instead.
My field isn't listed in the Insert Receipt Field button	The list shows custom Receipt fields that you can read. Check field-level security. A few packaged fields are hidden on purpose, such as raw dates; use their formatted versions.
HTML from a formula prints as text, or the layout breaks	Keep formula HTML simple (<br/>, <p>, <strong>) and make sure every tag is closed. Text formulas are limited to 3,900 characters.
Existing receipts need the new field	Issue replacement receipts, or update the existing Receipt records with a data tool and regenerate their PDFs.

Reference: Default Mappings

These mappings are created when the package is installed and recreated by Reset to Default. Source fields without a namespace prefix are standard Nonprofit Cloud fields. All others are Dryad Receipting fields (dryad__).

Gift Transaction

Gift Transaction field	Target	Target field
DonorId	Receipt	dryad__Donor__c
CurrentAmount	Receipt	dryad__Gift_Amount__c
dryad__Receiptable_Amount__c	Receipt	dryad__Receipt_Amount__c
dryad__Advantage_Amount__c	Receipt	dryad__Advantage_Amount__c
dryad__Advantage_Description_EN__c	Receipt	dryad__Advantage_Description_EN__c
dryad__Advantage_Description_FR__c	Receipt	dryad__Advantage_Description_FR__c
dryad__Appraiser_Name__c	Receipt	dryad__Appraiser_Name__c
dryad__Appraiser_Address__c	Receipt	dryad__Appraiser_Address__c
GiftType	Receipt	dryad__Gift_Type__c
dryad__Transaction_Year__c	Receipt	dryad__Receipt_Year__c
dryad__Donor_Name__c	Receipt	dryad__Donor_Name__c
dryad__Donor_Email__c	Receipt	dryad__Donor_Email__c
dryad__Donor_Address__c	Receipt	dryad__Donor_Address__c
dryad__Donor_Address_Multiline__c	Receipt	dryad__Donor_Address_Multiline__c
dryad__Donor_Receipt_Delivery__c	Receipt	dryad__Donor_Receipt_Delivery__c
dryad__Receipting_Account__c	Receipt	dryad__Receipting_Account__c
dryad__Receipt_Template_Id_Assigned__c	Receipt	dryad__Receipt_Template_Id__c
dryad__Email_Template_Id_Assigned__c	Receipt	dryad__Email_Template_Id__c
dryad__External_Receipt_Num__c	Receipt	dryad__Replacement_External_Receipt_Num__c

Gift Commitment

Gift Commitment field	Target	Target field
DonorId	Receipt	dryad__Donor__c
dryad__Donor_Name__c	Receipt	dryad__Donor_Name__c
dryad__Donor_Email__c	Receipt	dryad__Donor_Email__c
dryad__Donor_Address__c	Receipt	dryad__Donor_Address__c
dryad__Donor_Address_Multiline__c	Receipt	dryad__Donor_Address_Multiline__c
dryad__Donor_Receipt_Delivery__c	Receipt	dryad__Donor_Receipt_Delivery__c
dryad__Receipting_Account__c	Receipt	dryad__Receipting_Account__c
dryad__Receipt_Template_Id_Assigned__c	Receipt	dryad__Receipt_Template_Id__c
dryad__Email_Template_Id_Assigned__c	Receipt	dryad__Email_Template_Id__c

Don't remove the core mappings. Donor, amount, template and receipting account mappings drive how receipts are addressed, delivered and rendered. Change them only if you are replacing them with an equivalent field.