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:

The Receipt record is created. Field mappings copy values from the gift (Opportunity, Payment or Recurring Donation) onto fields on the new Receipt and, optionally, its Receipt Items.
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 and Receipt Item records. 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
Opportunity	Receipts created from Opportunities (single and consolidated).	Receipt and Receipt Item
Payment	Receipts created from Payments. The tab only appears when Enable Receipt by Payment is "Yes".	Receipt and Receipt Item
Recurring Donation	Consolidated receipts created from Recurring Donations. These values are applied after the Opportunity mappings, so they win if both map to the same Receipt field.	Receipt only

Consolidated and Summary Receipts

A consolidated receipt combines several gifts, but it has only one Receipt record. Receipt-level 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 values that differ from gift to gift (a gift note, a campaign, a fund), map them to the Receipt Item instead and show them as rows. See Per-Gift Rows on Consolidated Receipts.
Amount and date fields on consolidated receipts are calculated by the app, not copied: amounts are totals, and the receipt carries the date range of the gifts.

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, the target object (Receipt or Receipt Item) and the target field. The field lists show API names with field types, for example Gift_Note__c (STRING).
Deactivate a mapping by unchecking Active. Inactive mappings are kept but ignored.
Delete a mapping you no longer need.

Reset deletes your custom mappings. The Reset button deletes all field mappings, 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.
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 Opportunity's Account or Campaign. 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 Opportunity and want it printed on the receipt.

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.
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.
Add the mapping. In Settings > Field Mappings > Opportunity, click Add:
- Source field: Gift_Note__c
- Target object: Receipt
- Target field: Gift_Note__c
- Active: checkedIf you also receipt Payments or Recurring Donations, add the same mapping on those tabs, using a matching field on that object.
Add the merge field to your template. Open the template in Settings > Templates, 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.
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 Contact and Account (dryad__Contact__c, dryad__Account__c), so a formula can also read donor details, for example dryad__Contact__r.Preferred_Salutation__c.

	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 Calculated … Date fields, such as dryad__Calculated_Issue_Date__c and dryad__Calculated_Payment_Date__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 "Replaces receipt …" only on replacement receipts, and Voided Text EN prints "VOIDED" 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: Tribute Wording

The Opportunity's tribute fields are mapped to the Receipt by default. A Receipt formula Tribute Line (Text):

IF(
  ISBLANK(dryad__Honoree_Name__c),
  "",
  IF(ISPICKVAL(dryad__Tribute_Type__c, "Memorial"), "In memory of ", "In honour of ")
    & dryad__Honoree_Name__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 Opportunity or Payment, map it to a Text field on Receipt, and the wording is fixed at the time of issue.

Per-Gift Rows on Consolidated Receipts

To list each gift on a consolidated or summary receipt:

Map the values you need to Receipt Item (target object Receipt Item). Amount, date and receipt amount are mapped by default. Create custom fields on Receipt Item for anything else, following the same rules as above.

In the template, build a table and put the rows between the {{Receipt_Items_Start}} and {{Receipt_Items_End}} markers. Use the Insert Receipt Item Field button to add item merge fields:

{{Receipt_Items_Start}}
<table>
  <tr><th>Date</th><th>Amount</th><th>Note</th></tr>
  <tr>
    <td>{!dryad__Receipt_Item__c.dryad__Donation_Date__c}</td>
    <td>{!dryad__Receipt_Item__c.dryad__Donation_Amount__c}</td>
    <td>{!dryad__Receipt_Item__c.Gift_Note__c}</td>
  </tr>
</table>
{{Receipt_Items_End}}

Every table row (<tr>) between the markers that contains a Receipt Item merge field is repeated once per gift, in the order the items were created. Rows without one, such as the header row, print once.
Item dates use your Date Format setting, currency fields print as $1,234.00, and blank values print as nothing.
For conditional text inside a row, use a formula field on Receipt Item, as in the examples above.

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 (Opportunity, Payment or Recurring Donation)? 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 and Summary 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.
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__Contact__r.Email`); 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 Calculated 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.
Item rows aren't repeated	The row must be a `<tr>` between `{{Receipt_Items_Start}}` and `{{Receipt_Items_End}}` and must contain at least one `{!dryad__Receipt_Item__c.…}` merge field.
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 the Reset button. Source and target fields without a namespace prefix are standard or NPSP fields. All others are Dryad Receipting fields (dryad__).

Opportunity

Opportunity field	Target	Target field
`AccountId`	Receipt	`dryad__Account__c`
`npsp__Primary_Contact__c`	Receipt	`dryad__Contact__c`
`Amount`	Receipt	`dryad__Donation_Amount__c`
`CloseDate`	Receipt	`dryad__Donation_Date__c`
`Type`	Receipt	`dryad__Donation_Type__c`
`dryad__Receipt_Amount__c`	Receipt	`dryad__Receipted_Amount__c`
`dryad__Eligible_Amount__c`	Receipt	`dryad__Eligible_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`
`dryad__Close_Year__c`	Receipt	`dryad__Receipted_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__c`
`dryad__Email_Template_Id_Assigned__c`	Receipt	`dryad__Email_Template__c`
`dryad__External_Receipt_Num__c`	Receipt	`dryad__Replacement_External_Receipt__c`
`dryad__GAUs__c`	Receipt	`dryad__GAUs__c`
`dryad__GAUs_with_Amounts__c`	Receipt	`dryad__GAUs_with_Amounts__c`
`dryad__RecordType_Name__c`	Receipt	`dryad__Opportunity_RecordType_Name__c`
`npsp__Tribute_Type__c`	Receipt	`dryad__Tribute_Type__c`
`npsp__Honoree_Name__c`	Receipt	`dryad__Honoree_Name__c`
`npsp__Honoree_Contact__c`	Receipt	`dryad__Honoree_Contact__c`
`npsp__Honoree_Information__c`	Receipt	`dryad__Honoree_Information__c`
`Amount`	Receipt Item	`dryad__Donation_Amount__c`
`CloseDate`	Receipt Item	`dryad__Donation_Date__c`
`dryad__Receipt_Amount__c`	Receipt Item	`dryad__Receipt_Amount__c`

Payment

Payment field	Target	Target field
`dryad__Account_Id__c`	Receipt	`dryad__Account__c`
`dryad__Contact_Id__c`	Receipt	`dryad__Contact__c`
`npe01__Payment_Amount__c`	Receipt	`dryad__Donation_Amount__c`
`npe01__Payment_Date__c`	Receipt	`dryad__Donation_Date__c`
`dryad__Receipt_Amount__c`	Receipt	`dryad__Receipted_Amount__c`
`dryad__Eligible_Amount__c`	Receipt	`dryad__Eligible_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`
`dryad__Payment_Year__c`	Receipt	`dryad__Receipted_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__c`
`dryad__Email_Template_Id_Assigned__c`	Receipt	`dryad__Email_Template__c`
`dryad__External_Receipt_Num__c`	Receipt	`dryad__Replacement_External_Receipt__c`
`npe01__Payment_Amount__c`	Receipt Item	`dryad__Donation_Amount__c`
`npe01__Payment_Date__c`	Receipt Item	`dryad__Donation_Date__c`
`dryad__Receipt_Amount__c`	Receipt Item	`dryad__Receipt_Amount__c`

Recurring Donation

Recurring Donation field	Target	Target field
`npe03__Contact__c`	Receipt	`dryad__Contact__c`
`npe03__Organization__c`	Receipt	`dryad__Account__c`
`npe03__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__c`
`dryad__Email_Template_Id_Assigned__c`	Receipt	`dryad__Email_Template__c`
`dryad__GAUs__c`	Receipt	`dryad__GAUs__c`
`dryad__GAUs_with_Amounts__c`	Receipt	`dryad__GAUs_with_Amounts__c`

Don't remove the core mappings. Donor, contact, account, 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.

How Field Mapping Works​

Mappings Are a Snapshot​

Source Objects and Targets​

Consolidated and Summary Receipts​

Managing Field Mappings​

Rules for a Valid Mapping​

How To: Show a Custom Field on the PDF​

When You Don't Need a Mapping​

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

Example 1: Line Only When a Field Is Filled In​

Example 2: Tribute Wording​

Example 3: Fallback Value​

Example 4: Show or Hide a Whole Block​

Per-Gift Rows on Consolidated Receipts​

Troubleshooting​

Reference: Default Mappings​