Wow. It’s been a year and a half since I’ve written any blog posts so I guess it’s about time.

General catchup: slightly new job at the US Senate Sergeant at Arms with slightly different responsibilities, and I’m still doing and loving Python, Django, and Postgres.

On the volunteer work front, I’ve been doing quite a lot with CiviCRM over the past year and I’m really enjoying it. The application itself is great and the community is friendly, helpful, and all-around fabulous. It’s everything an open source project should be.

In the spirit of giving back, I figured now that I have a decent handle on a thing or two I’d start sharing a bit of what I’m learning and doing with CiviCRM.

For this installment, I’ll cover how to do year-end contribution summary letters, which is relatively simple but there’s a couple of wrinkles I thought might help others, or if nothing else will help me next year when I have to do this again.

The Task

One organization I do CiviCRM work for is the wonderful Port Townsend, WA non-profit community radio station KPTZ. Since we’re a 501(c)(3) donations to the station are tax deductible, so for tax purposes we need to send out a letter to each donor with their total contributions for the previous calendar year.

For context, I’m using CiviCRM 5.9.0 on WordPress 5.0.3.

Step One: Enable Smarty in Mail Templates

It turns out there’s a variable you can access in mail templates to total up the contributions by donor, but it only works if you enable the ability to use the PHP template engine Smarty in CiviCRM’s mail templates, and this is disabled by default. (Thanks to Demerit on the CiviCRM StackExchange for pointing out my oversight on this!)

1. ssh into your server
2. Open the file [wordpress-root]/wp-content/uploads/civicrm/civicrm.settings.php in an editor
3. Locate the following line and change 0 to 1:
   define( ‘CIVICRM_MAIL_SMARTY’, 1 );
4. Save the file

Step Two: Create Your Mail Template

One of the many great features of CiviCRM is the fantastic, flexible mail templating system, and as we’ll see in a bit once you create a template it can email people with email addresses and use the same template to generate PDFs for contacts who don’t have email addresses.

1. Log into CiviCRM
2. Go to Administer -> Communications -> Message Templates
3. Click “Add Message Template”
4. Give your message a title and subject
5. In the HTML Format section you’ll enter your letter, which of course will contain the text you want. To output the total contributions for a donor for the year, you’ll use the template token {$contribution_aggregate}, so you can have something like this in your letter:
   Your total donations for 2018 were {$contribution_aggregate}
6. Another tip: with Smarty enabled, you can also add the current date to your letter much more easily than without Smarty:
   {$smarty.now|date_format}
7. Although most everyone can deal with HTML email just fine these days, it’s still best practice to include a plain text version of HTML emails, so be sure and copy your letter from the HTML Format box into the Plan-Text Format box
8. Click “Save and Done” to save your template

A really quick aside on the Smarty date_format filter — in the context of the WYSIWYG editor doing a custom date format (e.g. date_format:”%B %e, %Y”) will blow things up because the quotes get turned into HTML entities by the WYSIWYG editor. You can get away with this in source view, but if you ever change back to WYSIWYG mode it’ll break things again. For my case the default date format was just fine.

Step Three: Find Your Contributions

Next we’ll want to locate the contributions for which you want to send the summary letter, which in my case I did as follows (obviously update this as needed for your use case):

1. Contributions -> Find Contributions
2. Search Criteria:
1. Date Received; Previous calendar year
2. Financial Type: Donation
3. Contribution Status: Completed
3. Click “Search”

From the search results you can pick and choose the donations you want to include; in my case I want all the donations for the previous calendar year so I do the following:

1. Click the radio button to select all the records returned
2. Click the Actions drop-down and select “Thank-you letters – print or email”

Step Four: Email/Generate Thank-You Letters

Now for the easy part! At this point all we need to do is select a couple of options and use the template we created above.

Thank-you Letter Options

1. Set “Update thank-you dates” and “Update receipt dates” as you wish
2. Group contributions by: Contact
3. Separator: this is the separator you want to use for the contribution-related tokens if you’re going to output each individual contribution in your letter. This doesn’t matter for my use case since I’m not including the individual contributions, but set this as needed for your letter.
4. Print and email options: For testing purposes you’ll probably want to choose “Generate PDFs for printing (only)” so you don’t inadvertently send out any emails before you’re sure everything’s working, and then once everything looks good I tend to use the “Send emails where possible. Generate printable PDFs for contacts who cannot receive email.”
5. From Email Address: pick the appropriate from email for your letter

In the “Use template” drop-down, select the template you created in Step Two above. You’ll see the Document Body populate (and you can tweak your template for this specific mailing at this point) as well as the Activity Subject.

If everything looks good, click the “Make Thank-you Letters” button to generate the PDFs. Verify everything is correct, and then send out the actual emails and letters.

That’s it! Pretty simple, and after you’ve set this up once you’ll be all set for next year.

I hope some of you other CiviCRM newbies found this useful. I hope to write more about CiviCRM soon. Thanks for reading.