Letters are communications generated to borrowers that are stored in the database and can be reviewed, adjusted or even discarded before transmission.
The Letters module creates borrower communications that can include:
- details about the borrower
- details of all issues currently out to the borrower
- details of all current overdues for the borrower
- details of outstanding fees for the borrower.
Library administrators can customise the existing templates (there are 9 templates included with Athenaeum) or create new templates.
The Letters module consists of
- Letters - the letters generated and printed or emailed to the borrower
- Templates - the structure of each letter
- Tokens - the bits of information that are evaluated in real time and substituted into the templates to build the Letters
You only need to know about tokens when you want to adjust or create templates.
HTML or plain text?
Letters have two parts:-
- a plain text component
- an HTML component
Plain text is always used in every letter.
The HTML component is only used when sending emails and is discarded for printed letters.
Depending upon the email client that borrowers are using, they are most likely to see the HTML version of your letter, but not always. So when sending email letters, always ensure that both versions of the letter are similar.
Creating Letters from Borrowers
Letters can be generated from a found set of borrowers or a found set of issue records.
The procedure to create Letters when looking at a selection of borrowers is to:
- click the “Letters” menu
- choose a letter template
- check and possibly edit the generated Letters
- output it to printer, pdf or e-mail
Find your Borrowers
Find the borrowers you wish to communicate in one of the standard ways - for example:
- ad hoc find or
- find a class/room or group or
- find a set of issues and then “list borrowers” for those issues
Choose a template
While viewing the borrower found set in list view, click the “Letters” button:
Click on the name of the template you wish to use. The names should be reasonably self explanatory.
Confirm that you wish to create letters for the number of borrowers.
The letters are generated immediately and a list of Letters is displayed. You can scroll through this list, reviewing the various letters.
If you make a mistake, then immediately go to the Command menu and choose “Delete X letters” to remove the Letters you just created.
Check and edit
Each individual Letter is presented in a tab showing plain text.
However, if the template used has an html version, such as the overdue letters created from circulation, then the html version of the letter is also stored. You can switch between the plain and html tabs to see each.
Do not apply any text formatting such as bold, italic of font styles, as this will be discarded.
Output your Letters
You can print individual letters by clicking the print button. ￼ E-mail individual letters by clicking e-mail buttons 1 or 2. ￼ If no e-mail address is associated with the borrower, the email buttons do not show. ￼ Clicking the gear widget below the print/email options shows a pop-over window with the date printed and/or emailed.
Of course, you may output bulk Letters in one step.
At the top of the list, you may use the send e-mails and print Letters buttons to send all found set of letters to e-mail addresses 1, 2 or print.
Creating Letters from Issues (circulation)
This is slightly different in that you don’t choose a template, but rather choose an action on the found set of issue records, either from the print or email menus.
One difference between generating letters from Circulation compared to doing so from Borrowers is that Letters from Circulation can be processed (e.g. printed or sent) immediately, whereas letters from Borrowers will be saved to the database and you must then choose to print or email as a separate action.
Another is that the Circulation letters have “html” options which can include book cover image information in emails.
Creating and Customising templates
Athenaeum Pro comes with 9 templates that cover common Letters scenarios. You may - and are encouraged to - edit existing templates to create Letters customised for your needs and you can duplicate and customise existing templates or create new templates from scratch.
Letters is generated from Templates, which combine plain text and “tokens”. ￼ Click the List Templates button at the right side of the Borrower Utility screen to see a scrollable list of the current templates.
Templates consist of the following components:
- Include flag
- The template content
- navigation list of templates - click one to jump to that template
- include in list flag (uncheck to hide from the letters list on borrower screen)
- context: defines which modules (borrower or circulation) that the template is visible to
- plain text and html tabs - only visible when a template has both components
- token list - sliding panels with clickable tokens. Click a token to insert it where your cursor currently is located in the letter. Tokens are substituted at the time the letter is generated.
- the content of the template. Enter text here as you would in a plain text editor. Do not apply formatting such as font faces, bold, italics, etc as formatting will be ignored.
The template contains the text and embedded tokens that are substituted at the time the letter is generated.
Tokens are the symbols that are replaced at the time the letter is generation. To use these, simply type your text into the template, and when you wish to insert a token, click, using the mouse, the token you want to insert and its symbol will be inserted.
For example, if you would like letters to William Smith read:
Dear William, Please ...etc...
You would type into a new template:
then you would click on the borrower first name token on the right.
Athenaeum inserts the token for Borrower first name (which happens to be
Then continue to type the rest of the template.
There are three types of tokens.
Simple tokens which substitute a single value into Letters (e.g. borrower last name which inserts the current borrower’s last name). These should be inserted into the middle of the text just like any other word.
Complex tokens, such as “outstanding fees” which will substitute one or more lines of text, such as a list of fees outstanding with a date, reason, etc. ￼
These are complex tokens (possibly multiple line) where you can specify elements to be included or not.
[[issued_items (barcode location author fee dateIssue dateDue)]]
￼ When inserting such a token, you may choose to delete individual words from between the parentheses, and the corresponding information will be omitted from the letters.
For example, this template:
Dear [[borrower_full_name]], The following items are overdue. Please come to the library and either return the item or explain the circumstances of the lateness. [[overdue_items (barcode location author fee dateIssue dateDue)]] Thank you for your co-operation. Claire Files Ararimu Library
￼ might produce this Letters:
Dear Darryl Krell, The following items are overdue. Please come to the library and either return the item or explain the circumstances of the lateness. Matting, mounting and framing art Max Hyder ; illustrated by Paul LaPlaca. - Hyder, Max.  replace fee: $54.95 issued: 10/02/2013 due: 31/03/2013 Ptolemy's gate Jonathan Stroud. - Stroud, Jonathan.  replace fee: $29.95 issued: 23/04/2013 due: 26/04/2013 Biker - Masters, Anthony  issued: 29/04/2013 due: 23/07/2014 Thank you for your co-operation. Claire Files Ararimu Library
￼ You can see that two entries were inserted into the letter and the replacement fee, issue & due dates, bar code, title are all included.
However, editing the template like so (removing the due date, author and location): ￼
Dear [[borrower_full_name]], The following items are overdue. Please come to the library and either return the item or explain the circumstances of the lateness. [[overdue_items (barcode fee dateIssue)]] Thank you for your co-operation. Claire Files Ararimu Library
Will result in a simplified output:
Dear Darryl Krell, The following items are overdue. Please come to the library and either return the item or explain the circumstances of the lateness. Matting, mounting and framing art Max Hyder ; illustrated by Paul LaPlaca.  replace fee: $54.95 issued: 10/02/2013 Ptolemy's gate Jonathan Stroud.  replace fee: $29.95 issued: 23/04/2013 Biker  issued: 29/04/2013 Thank you for your co-operation. Claire Files Ararimu Library
|insert button name||token||description|
|borrower address||borrower_contact_address||the multi-line contact address for the current borrower|
|borrower contact||borrower_contact_name||the name of the contact associated with the borrower consisting the title + contact first + contact last names|
|borrower email||borrower_email1||the first email address associated with the borrower|
|borrower email 2||borrower_email2||email address 2 for the borrower|
|borrower $$family name||$$borrower_family_name||Used specifically in Room Overdue list. When building this list, Athenaeum notes the family name of the borrower associated with the room (actually “group 2”) of the current issue.|
|borrower last name||borrower_family_name||last or family name of the current borrower|
|borrower $$full name||$$borrower_full_name||Used specifically in Room Overdue list. When building this list, Athenaeum notes the full name of the borrower associated with the room (actually “group 2”) of the current issue.|
|borrower name||borrower_full_name||full name of the borrower|
|borrower $$given name||$$borrower_given_name||Used specifically in Room Overdue list. When building this list, Athenaeum notes the given (first) name of the borrower associated with the room (actually “group 2”) of the current issue.|
|borrower first name||borrower_given_name||first or given name of the current borrower|
|borrower group 1 (e.g. year)||borrower_group1||group 1 of the current borrower–e.g. Room–this is a generic name and is customised for each installation|
|borrower group 2 (e.g room)||borrower_group2||group 2 of the current borrower–e.g. Year–this is a generic name and is customised for each installation|
|current date||currentDate||the date the report is generated|
|date reserved||date_reserve||the date that an item is reserved, used only by reserve_notifcation template.|
|outstanding fees||fees||list of fees for the current borrower|
|group 1 descriptor (e.g. “year”, etc.)||group1_descriptor||the label you have assigned for group 1 (e.g. year)|
|group 2 descriptor (e.g. “room”, “vertical form”, etc.)||group2_descriptor||the label you have assigned for group 2 (e.g. room or vertical form)|
|group 2 family name (e.g. room contact last name)||group2_family_name||the last name for the borrower assigned to the group2 for the current issue record (similar to $$borrower_family_name above, but is created in a different context, internal differences require this)|
|group 2 given name (e.g. room contact first name)||group2_given_name||the first name for the borrower assigned to the group1 for the current issue record (similar to $$borrower_given_name above, but is created in a different context, internal differences require this)|
|Issued items title - optional barcode, location, author fee, dateIssue, dateDue||issued_items (barcode location author callnumber dewey fee dateIssue dateDue)||details for the issue items - descriptors inside the parentheses are optional inclusions for each line|
|issues list in memory||issues_variable||used by letters to rooms|
|item bar code of current issue||item_bar_code||token replaced by the bar code of the current item|
|list of issues||list_of_issues||a token representing the list of issues for the current borrower as plain text|
|list of issues as html table||list_of_issues_html||a token representing the list of issues for the current borrower as html text|
|logon details||logon_details||sends the web logon and password for the current borrower|
|lookup borrower family name||lookup_borrower_family||maintained for compatibility|
|lookup borrower first name||lookup_borrower_first||maintained for compatibility|
|lookup borrower group2||lookup_borrower_group2||maintained for compatibility|
|overdue items title - optional barcode, location, author, dateIssue, dateDue||overdue_items (barcode location author callnumber dewey fee dateIssue dateDue)||details for the issued items as overdues - descriptors inside the parentheses are optional inclusions for each line|
|signature||signature||the signature stored in admin preferences|
|signature html||signature_html||the signature stored in admin preferences, but retrieved as html|
|title of current issue||title||title of current issue, as you might expect!|
|author of current issue||title_author||Used in Reserve notification and calculates to the Author field from the Title table (does not use field labelled “other authors/contributors”)|
Copyright © 2018 SumWare Consulting. All Rights Reserved.