<< Click to Display Table of Contents >> Navigation:  CREATING MAIL MERGE LETTERS > Mail Merge Fields

This page describes all of the fields that are available for use in the mail merge letters. They are inserted when you are editing a template in the mail merge editor.

 

This page includes the following subsections:

 

Common Donor and Organization Information (included in all types of letters)

Donor Information (added only to Donor Information letters)

Individual Donation Information

Total Donations Information

Pledge Information

Receipt Information (including Gift in Kind Receipts)

Specifying the DetailsTable (and related fields)

Controlling French and English use

Using If, Else and Endif to include optional text

Creating Reports instead of Letters (mail merge documents that include one or several lines per donor or donation etc., instead of separate pages for each)

 

Common Donor and Organization Information

 

First, the following fields are available no matter which of the radio buttons at the top of the Merge Letters or Merge One Letter window you select, because they are either about the donor, or are more general fields about your organization.

 

Please note that in all cases, if there is no information filled into a given field, and it is used in a mail merge, it will just be replaced with nothing. Also, in the Merge Letters or Merge One Letter window these field names are displayed as is, but when they are inserted as merge fields in letters, they are surrounded by the double angle bracket characters, as in «Name».

 

 

 

 

Currency and Date Formats

 

All currency fields display in mail merge letters in your currency format as set in Control Panel (the same way they display when you are entering them, and on other reports). All date fields display in a format like "December 31, 2016", subject to changes for French and English (see below).

 

Renameable Fields

 

You will note that if you change the labels for the donor Category 1 or 2 fields or the Other Info 1 through 6 fields in the Maintenance ⇒ Main Window Options window, the relevant mail merge field names do not change. Why? Suppose you had changed the label of Category 1 to "Membership Status", and the program then allowed you to use a merge field «MembershipStatus». What if you then decide to again change the label for Category 1, to just "Membership"? Any mail merge document using «MembershipStatus» would then be broken, because there was no longer a field with that name! So the mail merge fields for these donor details fields always have the standard names, Category1 or Category2, or OtherInfo1 through OtherInfo6, as listed above.

 

Middle Initial

 

The merge fields that include the Middle Initial are omitted from the list if you have not checked "Middle Initial" in the "Show Fields" area on the Maintenance ⇒ Main Window Options window.

 

Title

 

Similarly the Title merge field is omitted if you have not checked "Title" in the "Show Fields" area of the Maintenance ⇒ Main Window Options window. There are no separate merge fields for names with titles, because the Title is automatically included or excluded from all Name fields depending on the value of the "Include Title in Names in Letters and Receipts" checkbox on the Main Window Options window.

 

Donor Information

 

The following fields are added to the base Donor fields, when you select "Donor Information only":

 

 

Individual Donation Information

 

The following fields are added to the common Donor and Organization fields, when you select "Current Donation Information" in Merge One Letter, or "Individual Donation Information" in Merge Letters:

 

 

Note: The following three fields will only be filled in if the current donation has been included in a receipt.

 

 

Please note that although the inclusion of the last three fields above mean that the Current Donation Information or Individual Donation Information letters could in theory be used to replicate a receipt (or prepare a cover letter for a receipt), that would only be appropriate for receipts that only include one donation in them. And in addition, this provides no real advantage over using the Selected Receipt Information or Receipt Information Only options, which include even more fields that are helpful in relation to receipts.

 

Total Donations Information

 

The following fields are added to the common Donor and Organization fields, when you select "Total Donations Information" in either window. Please note that when you click Merge after selecting this option, you are prompted for a range of dates to report on (default the whole current year). The Amount fields, and the Details and Summary Tables, are restricted to that specified range of dates.

 

StartDate                The start of the date range selected for this merge

 

Pledge Information

 

The following fields are added to the common Donor and Organization Fields, when you select "Pledge Information" in either window. There is no prompt for a range of dates for Pledge Information letters - they always report on the entire pledge period.

 

Which pledge fields are added depends on which type of pledging you have selected on the Pledges tab of Maintenance ⇒ Main Window Options.

 

The interpretation of the fields below (except for the Multi-Year type) also depends on the value of the "Pledges are on a fiscal year basis" checkbox in that window - if it is checked, then all values and tables created by fields below are based on your fiscal year as specified in the Maintenance ⇒ Organization Info window.

 

Simple Annual Pledge type (this is the default type)

 

 

Annual with Start Date and Category type

 

 

Multi-Year type

 

 

Note: in most cases you would probably choose to include only one of the DetailsTable and DetailsTableAllYears fields in any one mail-merge letter, although the sample letter provided with the program includes both.

 

Receipt Information or Gift in Kind Receipt Information

 

The following fields are added to the common Donor and Organization Fields, when you select "Selected Receipt Information" in Merge One Letter, or "Receipt Information" in Merge Donors, or "Gift in Kind Receipt Information" in either one. (Note that this last option only appears if you have selected the option for different receipts for Gift in Kind donations in the Maintenance ⇒ Receipt Options window.)

 

YTDAdvantageAmount The total of all Advantage Amounts of all donations included in all receipts for this donor, not just the current receipt

 

 

The following field is only added for Receipt Information merges, and only when the Receipt Style / Location you selected in the Maintenance ⇒ Receipt Options window is set to "U.S.A.":

 

 

The following fields are only added for Receipt Information merges, and only when the Receipt Style / Location you selected allows for Fiscal Year Receipting:

 

 

The following four fields are only added for Receipt Information merges:

 

 

Note that the DetailsTable and SummaryTable fields are not available for Gift in Kind receipts, or for receipts with Advantage.

 

The following fields are only added for Gift in Kind Receipt Information:

 

 

The following field is only added for Canadian receipts, if you are generating receipts with Advantage, or you check the "With Advantage" checkbox in Letters ⇒ One Letter or Letters ⇒ Mass Mailing. See Donations and Receipts with Advantage for details.

 

 

Specifying the Details Table

 

When you select to insert the DetailsTable field for either Total Donations Information or Receipt Information, a Select Donation Fields window comes up on which you can specify which columns you want to appear in the table.

 

•The three normally included fields for receipts, Date, TotalAmount and Category, are already displayed in the Fields to Display list on the right.

•The Date and TotalAmount fields cannot be removed from the Fields to Display list.

•The other available fields for this table (EligibleAmount, AdvantageAmount, ChequeNo and Description) are in the Available Fields list on the left.

•Select additional fields to display, if desired, by clicking on them in the list on the left and clicking the Add button, or double-clicking on them in that list.

•Removed fields from the display, if desired, by clicking on them in the list on the right and clicking the Delete button, or double-clicking on them in that list.

•You can also change the order of the fields in the list on the right by clicking on a field and clicking the Move Up or Move Down buttons.

 

For Total Donations Information mail merges, one more field is available: Receiptable. This shows a Y or N, indicating whether the donation (and its donor) are receiptable, in accordance with the rules under Non-Receiptable Donors and Donations.

 

You can also, optionally, check the "Display 2 groups of columns of donations" checkbox, as long as you have only selected to display at most 3 fields in the table. If you do that, the headings of the table will be something like "Date Amount Category   Date Amount Category" (assuming those standard 3 fields were selected), i.e. two donations will be shown on each row. This will save space in the letter or receipt.

 

The available fields differ slightly for the DetailsTable for Pledge mail merge letters - see below for details.

 

Once you have made your selections, click OK in this window to insert the field into your document. It will display as something like this (if you included only the three default columns):

 

«DetailsTable:Date,TotalAmount,Category»

As you can see, what appears is the main merge field name ("DetailsTable"), followed by a colon, followed by a comma-separated list of the selected columns for that table. You can also hand-edit that merge field in the letter if you are careful. However, if you want to change the list of columns in the table, the easiest thing is to delete the entire merge field, then re-enter it from the list of insertable fields at the top of the window.

If you do check the "Display 2 groups of columns of donations" checkbox, the generated field will be:

«DetailsTable:Date,TotalAmount,Category;2column»

The ";2column" is a code indicating to show two groups of columns on each row. If you are careful, and think the table will still fit across the page, you can actually enter that code yourself, after the list of fields in a «DetailsTable» code, even if you are using more than the three standard fields. (The program won't let you select that option in the Select Donation Fields window if you have selected additional fields.)

Note: The Date column in the details table appears in a format like "Dec 31, 2016", to keep it relatively short so that more columns can fit into the table. However, that can be changed to use the Windows Short Date style set in Control Panel's Regional and Language Options tool if you check "Use Windows short dates for Details sections" in the Maintenance ⇒ Receipt Options window.

DetailsTables for Pledge Information merges

For the Pledge Information type mail merges, the DetailsTable and DetailsTableAllYears fields work almost exactly the same way as described above, with the popup window for selecting fields. However, because for Canadian users the Eligible Amount of a donation (when specified) is always considered to be the amount that fulfills a pledge, there is no reason to include the distinct TotalAmount, EligibleAmount and AdvantageAmount fields in the options for this table. Thus, only an Amount field is used. So the default three fields become Date, Amount and Category.

Those two tables only ever list donations that go towards fulfilling the pledge.

For the pledge type Annual with Start Date and Category, the DetailsTableAllCategories field is also available. It behaves exactly like the DetailsTable field for Total Donations Information letters, listing all donations for all categories, whether or not they go towards fulfilling the pledge. It always shows the donations for the entire year (calendar year, or fiscal year if you have selected to have pledges be for fiscal years), and always shows the total amount (never the Eligible Amount). For that same pledge type, the TotalAmountAllCategories field is also available, which will give the total of the donations shown in the DetailsTableAllCategories field's table.

Changing the Font Size for the Details and Summary Tables

All of the current versions of the mail-merge receipts and letters that include details or summary tables have code in them that sets the font size in those tables to 12pt. However, that code unfortunately tends to disappear if you ever edit the templates in Microsoft Word, so you might need to know how to restore it. Alternatively, you might need to find and edit it, if you want to change that point size. If you need to restore or edit it, use the Actions ⇒ View/Edit Source in Notepad menu option or corresponding toolbar button, from the mail-merge editor, to bring the code for that document up in the Windows text editor program Notepad.

Near the top of the file, you will see a section under a line containing "<style>". Look for two lines like:

table.DetailsTable td, table.DetailsTable th, table.SummaryTable td, table.SummaryTable th
 {font-size: 12pt;}

(You may alternatively see a variation on that, splitting it out into more lines.) If you see those lines, and want to change the font size, just change wherever it says "12pt". If those lines are absent, add them in, and again change the point size if you wish.

Save that change in Notepad (with the File ⇒ Save menu option) then exit Notepad. That will return you to the built-in editor, which will give you a message saying that the file has been changed, and prompting you to reload it. Answer Yes.

That will not change the apparent size of the mail-merge fields for the details or summary tables in the editor, but it will change the font on actual merged tables when you do your merge. (Changing the size of the merge fields for the tables directly in the built-in editor actually does nothing to change the merged results, although you might hope otherwise!)

Varying Languages in the Details and Summary Tables

Normally the column headings in these tables are in English or French (or both) depending on the selection you make in the Maintenance ⇒ Receipt Options window. If those are the languages you are using, please ignore the rest of this sub-section!

It is possible to override the normal wordings in English or French to support other languages, but only with these mail-merge fields - not for the built-in receipts that are not done by mail-merge.

To do that language overriding, you need to edit the DONATION.INI file which is in the program's Data Directory, with a text-editing program such as Notepad (do not use a Word Processor!). Find the section in that text file headed by:

[Database:extension]

where extension is replaced by the file extension on the database you are making these changes for. Normally that is DB if you only have one database (so you would be looking for "[Database:DB]"), but if you are Switching Databases, you will have multiple extensions and may need to make these changes for each of them (if they are all using the same language).

Under that heading, you need to add lines such as:

DateHeading=Date
CategoryHeading=Category
TotalAmountHeading=Total Amount
AmountHeading=Amount
EligibleAmountHeading=Eligible Amount
AdvantageAmountHeading=Value of Advantage
ChequeNoPaidByHeading=Cheque No. / Paid By
DescriptionHeading=Description

The values on the left of the equals signs must be exactly as shown above; the values on the right are whatever you want in your language to replace the sample English-language headings list above. The TotalAmountHeading, EligibleAmountHeading and AdvantageAmountHeading are only for if you are doing split receipting as in Canada, otherwise only AmountHeading is used.

The first list above is all the ones that can be used for the DetailsTable and DetailsTableAllYears. Only AmountHeading and CategoryHeading in that list above are used in the SummaryTable. (You don't need to repeat them twice!)

Using «French» and «English» to Force the Language for Dates

There are two special fields that you can insert anywhere near the top of a mail merge letter or receipt: «French» and «English». Inserting either one forces all dates printed in the merged letter or receipt to be in that language. This can serve as an override of the setting of the Use French Dates checkbox in the Maintenance ⇒ Receipt Options window.

Using «if:FIELDNAME» or «if:FIELDNAME=VALUE», «else» and «endif»

There are three special technical fields, «if:FIELDNAME», «else» and «endif», which can be used to eliminate irrelevant contents from a mail merge letter or receipt, if a given field's value is empty (or $0.00, for amounts), or optionally provide alternative content if it is empty. You must always replace FIELDNAME with the name of another field on the drop-down list of fields for this type of letter, as listed above. (You can't do this with the field names "DetailsTable" or "SummaryTable", though.)

You can also specify the "if" part as «if:FIELDNAME=VALUE», which will include the text following it, up to «else» or «endif», only if the value of the field is exactly the same as the value you enter after the equals sign. (For amount-type fields, that value has to be shown in your standard currency display format, such as $100.00.)

If you are wondering, "endif" is a common computer programming term for the end of a section that start with "if".

It's easiest to understand these new special fields via an example. For now we will use only «if:FIELDNAME» and «endif». You might have a section of a letter or receipt such as:

Envelope #: «MemberEnvNum»

The problem with this is that if you don't use Member/Envelope numbers, or you do use them but the current donor doesn't have one, the "Envelope #:" part will still show up in the merged letter. It would be better if it disappeared in those cases. To do that, surround it with the «if:FIELDNAME» and «endif» fields from the drop-down list, so that that section reads as follows:

«if:FIELDNAME»Envelope #:«endif» «MemberEnvNum»

Then, you need to change "FIELDNAME" to the field we are really testing for being empty, "MemberEnvNum". Change it to:

«if:MemberEnvNum»Envelope #:«endif» «MemberEnvNum»

Now, when you merge this letter, if the current donor has no Member/Envelope #, the "Envelope #:" part will be removed. If the donor does have a Member/Envelope #, it will be left in. Note that you don't need to surround the actual field «MemberEnvNum» with these special codes, because if the donor has no Member/Envelope # this will be replaced with nothing anyways. (Though no harm would be done by including it within the "if" section.)

There's a slight difference if you use this with amount fields, such as «DonationAmount». That field is never empty, though it might be $0.00. So its value will always be included in a letter that includes that field. If you want it to be removed if its value is $0.00, you can use the same technique, as in:

«if:DonationAmount»Amount: «DonationAmount»«endif»

If you use those codes, then when the donation amount is $0, nothing from the line above will be included in the letter.

For an example of using «if:FIELDNAME=VALUE», suppose you are using the Donor Category 1 field with values like "Member" and "Non-Member" to indicate the donor's status in your organization. And suppose you have a sentence in a mail-merge letter that you only want included for members. The following would be how you would do that:

«if:Category1=Member»Thank you for being a member of our organization. «endif»

Using «else»:

The «else» field can optionally be used between «if:FIELDNAME» and «endif» to provide alternative content. For instance, suppose you want to address a letter to people's first names (like "Dear Dan"), but for a few donors, there is a special nickname you wish to address them as, that should not be what you enter in the official First Name field. You could name one of the six renameable Other Info fields "Salutation" via the Main Window Options window, and fill it in only for those users with salutations different from their first names. Then the use the following in your letter:

Dear «if:Other1»«Other1»«else»«FirstName»«endif»,

That's assuming it was Other Info 1 that you renamed to Salutation, of course. That section of codes means that if the Other Info 1 (Salutation) field is filled in, it will be used. Otherwise, the First Name field will be used.

Tip for Techies Only: There is a minor complication using these codes when you are editing text that is in an HTML table, such as in our default layouts for mail-merged receipts. In that case, the prompt for a field (such as "Envelope #:") is generally in one cell of the table, while the field itself (such as "«MemberEnvNum»") is generally in an adjoining cell. If you wanted to make both the prompt and the field disappear if the Member/Envelope # field was empty for that donor, you would have to be careful. (Technically, you don't need to make «MemberEnvNum» disappear, because if it's empty nothing prints anyways, but this is just an example.)

In this case, if you put "«if:MemberEnvNum»" before the prompt, which is in one table cell, and "«endif»" after the MemberEnvNum field itself, which is in another table cell, then if the stuff between them is removed because there is no Member/Envelope #, you will also be removing the HTML codes that separates the two cells, and thus possibly ruining the layout of the table. To prevent this, if things appear to be in rows and columns (i.e. in a table), be sure to surround each individual section (table cell contents) with those codes, so each one is eliminated individually, without causing this type of problem.

Also, there is no "nesting" of one condition inside another, such as "«if:FIELD1»some field 1 text«if:FIELD2» some field 2 text«endif» some more field 1 text«endif»".

Creating Reports instead of Letters

By using «NoPageBreaks» at the very top of your document file, you can tell the mail merge routine to skip its normal insertion of page breaks between successive donor, donation or receipt records that it is merging. This allows you to create reports, or things like directories, instead of letters.

To make this work even better, there are two special «if:» fields you can use: «if:FIRST» and «if:LAST», each of which has to be paired with «endif» as usual. Whatever is enclosed in «if:FIRST» and «endif» will only be included in the output for the first record being merged. Whatever is enclosed in «if:LAST» and «endif» will only be included in the output for the very last record being merged. This, in essence, allows you to create a header section and footer section for the report that you are creating in this way.

Tip for Techies Only: If you want each record in the report to be one row of an HTML table, you may not be able to create what you want in just the built-in HTML editor. You may need to use Actions ⇒ View/Edit Source in Notepad in the built-in editor, to edit the HTML in Notepad, in order to get this right. What you want to end up with is something like this:

<HEAD>...</HEAD>
<BODY>
«NoPageBreaks»«if:FIRST»<p>Any Header Section you want.</p>
<table>
<tr><th>Column 1 Heading</th><th>Column 2 Heading</th><th>Column 3 Heading</th></tr>
<tr valign="top">«endif»
<td>«FirstField»</td>
<td>«SecondField»</td>
<td>«ThirdField»</td>
«if:LAST»</tr></table>
<p>Any Footer Section you want.</p>
«endif»</BODY>

This is a report with header and footer sections, and a table with three cells (columns) per row. There's a row of headers for the table at the top, and a data field in each of the cells of the table. (Of course, you replace "FirstField" by a real field name, etc.) Be sure to use the Actions ⇒ Show Table Borders on Screen menu option in the built-in editor to help you see where the table cells are and edit within them. (Those borders will not show when you print the merged report.)

Please note that if this report goes onto a 2nd or subsequent pages when you print it, the column headers (if you have any) will not be repeated. As the information above says, the «if:FIRST» and «if:LAST» section are done only once for the whole report, not once per page. We unfortunately cannot see any way to improve on this, with the technology we are using to do these mail merges.

Of course, this is not the only way to create custom reports - you would usually do that via the Reports ⇒ Custom Report menu option. But this way of creating custom reports via mail merge yields something that is further editable in your word processor, and in some ways gives you more control, for example over the headers, footers, and layout, than a Custom Report. (Mind you, you can also save any report to a file, including Custom Reports, and edit it in Excel or a word processor.)

---

This topic was last edited on Jan 14, 2023