Background
The Message module provides several features for delivering emails:
- Message/Send will send an email without saving a Message row to the database
- Message/SaveEmail will save a Message row to the database, and if there are recipients specified, will also send an email
- The Message Template class supports the concept of 'canned' messages, where the body of the message is essentially 'mail merged' against data from the database
- The Message Recipient class supports tracking each recipient of an email, including read receipts.
Use Case: Email Users Their Work Lists
Freddie Mac wishes to email their users a list of work items each night. For most QBO systems, such work items include potentially Non-Public Information (NPI), so sending the raw data in the clear is a bad practice. Instead, an email containing the number of work items, with a hyperlink directly to the appropriate Smart Worklist view, is the preferred practice.
The items a user is eligible to work is determined by the Smart Worklist module, defined by the statement 'PersonEligible'. Sample output is:
| Person | AssignedCount | EligibleCount | Total |
| admin@quandis.com | 22 | 144 | 166 |
| joe@acme.com | 3 | 255 | 258 |
| ... | | | |
For this use case, we shall copy the basic PersonEligible statement to the Person/Config, and extend it to include an AsOfDate column.
Create a Message Template
A Message Template that applies to the Person table will be used to control the body of the email. For this use case, we shall name the template 'Nightly Worklist'. The BodyHtml should look something like:
As of {AsOfDate}, you are assigned {AssignedCount} items, and based on your team membership, you and your teammates are eligible to work a total of {EligibleCount} additional items.
<a href="Decision/SmartWorklist.ashx">View all your work</a>
You can manually test this as follows:
/Message/Message.ashx/Send?MessageTemplateID=X&ToAddress=admin@quandis.com&AsOfDate=1/1/2020&AssignedCount=22&EligibleCount=144
Create a Data Listener
A data listener take the output of a query, and for each row returned, invokes some operation. In this case, we shall create a data listener against the Person table called 'Nightly Worklist', with the following properties:
- Name: Nightly Worklist
- Statement: PersonEligible
- Class: Message
- Operation: Send?ToAddress={Person}&AssignedCount={AssignedCount}&EligibleCount={EligibleCount}&AsOfDate={AsOfDate}
- Async: True
When the data listener runs, each row returned by the new Person/PersonEligible statement will cause a Message/Send operation to be queued with the parameters above. Essentially, we invoke the manual test above for each row returned by the data listener query.
To invoke the data listener manually:
/Security/Person.ashx/Listen?Listeners=Nightly Worklist
Schedule the Data Listener