Donation thank-you letter workflow

[Coleman Watts]

I'm trying to figure out the workflow for sending thank-you letters for donations. For my case (and most cases, I would think) the ideal workflow would be:
-search for donations that haven't gotten a thank-you yet
-print a letter using tokens for donor name, contribution amount, date, etc.
-thank you date will automatically be set upon printing the letters

I imagine this is how it's supposed to work, so I'm not sure why I'm stuck. The documentation says this:

Thank-you letters: when sending personalised letters to donors thanking them for their support, it is often convenient to include specific acknowledgement of the donor's contribution amount. For example, a letter could say, "Thank you Judy for your recent contribution of ." To accomplish this, create your list of recipients using CiviContribute because the results of a search using Find Contributions will include contribution amounts. These results also include contact information so can be easily used for mail merge purposes. You can also create a custom token to get the latest contribution then use the PDF letter action. For detailed information on custom tokens, see the Hooks chapter of the section Extending CiviCRM, and also the Mail Merge Tokens for Contact Data section in the CiviCRM wiki.

However, when I follow these instructions, I get stuck at the "pdf letter action" part, since this option does not exist in contribution search results. What's going on?

[Coleman Watts]

Dlobo just went over this with me on IRC. We found the "pdf receipt" option, but that gives no option to compose a letter.

So I'm left wondering: Are the above instructions just wishful thinking? Or has there been a regression somewhere along the line that has disabled the PDF letter on contribution search results?

[Donald Lobo]

This is definitely a useful feature and would be great to have. However i dont think we are there yet. Wanna build this during the code sprint? u could be remote out in sunny woolman ln

Where does this say in the docs. url please

lobo

[Coleman Watts]

Here is the url of the above quote: http://en.flossmanuals.net/civicrm/ch022_postal-mail/

Could you tell me a little more about how it currently works? What is the current method for composing thank-you letters? And how is the "thankyou_date" contribution field normally populated?

Yes, I think I might be able to contribute to this, but I need to know how it currently is implemented first. And at the moment, I've got a couple hundred donors to mail letters to and need to figure out how to do it...

[samuelsov]

After a quick review of the code, it's quite easy to add an action to print pdf letter for each contribution :
* Add a task in CRM_Contribute_Task (ex: CRM_Contribute_Form_Task_PDFLetter)
* Create the new class CRM_Contribute_Form_Task_PDFLetter which is nearly a copie of CRM_Contact_Form_Task_PDF

After that, you need to :
* add some specific logic to CRM_Contribute_Form_Task_PDFLetter (ex: one letter by contribution instead of one by contact)
* add contribution specific token (maybe add function contributeTokens in CRM/Core/SelectValues.php ?)

Do i forget something ?

[Coleman Watts]

I prefer to print one letter per donor, not per donation.
This is what I was planning to do for my org (as soon as 4.1 with the improved tokenValues hook spec is available):

* Use the hooks to add a new token, called something like "unthanked donations"
* Use advanced search (not contribution search) to find donors who haven't been thanked yet
* Print PDF thank-you letter for them, and insert the token.
* Use "batch edit via profile" to set the thank-you date, so they won't come up again next time I do a round of thank-yous.

The token will run a query to find unthanked donations for that contact, and print them in a table like:

Date

Amount

Payment Method

Donation Type

[samuelsov]

Right, but if you print the amount, you need to have one receipt by contribution or do a sum if there are several contribution for the same contact.

[Eileen]

Hi,

If you do a contribution search & choose to send a pdf receipt it defaults to using the workflow template for online donations. I think if you exposed a choice of templates at that point it would be really valuable.

I suspect it would be really cool if a couple more tokens were available

1) Total contributions by contact
2) details of all contributions found in the search.

(NB that's a generic - this would be great for many rather than a specific answer to Coleman)

[Coleman Watts]

Just want to clarify our terminology here:
Receipt = receipt_date in the DB, typically is sent automatically at the time of contribution, can be printed via "pdf receipt" as Eileen says
Thank You = thankyou_date in the DB. Currently this cannot be generated by CiviCRM. This is the issue I'm wanting to address.

When we print a thank-you letter for a donor, it will have a table at the bottom of the letter with one row for each recent contribution, which is what my custom token will generate.
Would love for this to be more generally applicable, but that's all I got so far.

[samuelsov]

Hi Eileen,

In my use case, i also need one token with the contribution total group by recurring contribution for the year (one receipt by year) but i suspect it may be too specific.

Let's say we start with the following tokens : amount, receive_date, receipt_date, source, campaign, status, contribution type, payment type and total by contact. Other tokens could be added by hooks like suggested by colemanw.

[Eileen]

I think that 'total by contact' is the only one of your list not currently available from the contribution receipt (the one from the contribution search). But not being able to select template is a bit of a drag.

[Eileen]

NB - if the option  to choose the template were exposed on the contribution search action then it would make sense to also expose the ability to set receipt_sent & thankyou_sent from there (or not).

I think the most commonly requested other tokens are
'total_contributions'
'total_contributions_this_year'
'last_x_number_of contributions' (per Coleman).

I did do tokens for these but they are apiv2 & have hard-coded custom fields so I don't think they'll help much. I did start trying to build a civitoken module with a 'plugins' folder where you could add others as you wanted, but it stalled.

[Coleman Watts]

'last_x_number_of contributions' (per Coleman).

Specifically it's all contributions for whom a thank-you date is not yet set. In the context of writing a thank-you letter, that makes sense. However it has to be specific to donations, since we won't be thanking people (at least not on our donor letters) for paying their event fees, etc.

So like you I'm also going to be going the hard-coded route for now...

[samuelsov]

NB - if the option  to choose the template were exposed on the contribution search action then it would make sense to also expose the ability to set receipt_sent & thankyou_sent from there (or not).

Yes, absolutely ! This was the next step

[Eileen]

NB - Coleman - how many will you be generating at once. We managed to get the pdf letter with tokens to scale to about 100 but when we have a larger requirement recently I used a CiviReport (I put the code on the developer forum somewhere - it was last 5 pledges they wanted but printing several thousand @ once)