Letters

Letters are communications generated to borrowers that are stored in the database and can be reviewed, adjusted or even discarded before transmission.

Introduction

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.

Components

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

Individually

output individual Letters
output individual 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.

In Bulk

Of course, you may output bulk Letters in one step.

output bulk Letters
output bulk Letters

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.

circulation email menu generates letters for you and offers to send them immediately
circulation email menu generates letters for you and offers to send them immediately

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.

list templates
list templates

Template Parts

Templates consist of the following components:

  • Context,
  • Name,
  • Include flag
  • The template content
template list showing a single template with components
template list showing a single template with components
1
navigation list of templates - click one to jump to that template
2
include in list flag (uncheck to hide from the letters list on borrower screen)
3
context: defines which modules (borrower or circulation) that the template is visible to
4
plain text and html tabs - only visible when a template has both components
5
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.
6
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.

Tokens

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:

Dear 

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

[[borrower_given_name]] 

Then continue to type the rest of the template.

There are three types of tokens.

Simple 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

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. 

Customisable Tokens

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.  [07573] 
	replace fee: $54.95 issued: 10/02/2013 due: 31/03/2013 

Ptolemy's gate Jonathan Stroud.  - Stroud, Jonathan.  [55409] 
	replace fee: $29.95 issued: 23/04/2013 due: 26/04/2013 

Biker  - Masters, Anthony  [60136] 
	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.  [07573] 
	replace fee: $54.95 issued: 10/02/2013 

Ptolemy's gate Jonathan Stroud.  [55409] 
	replace fee: $29.95 issued: 23/04/2013 

Biker  [60136] 
	issued: 29/04/2013 



Thank you for your co-operation.

Claire Files 
Ararimu Library

Token descriptions

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”)