Configuring Esploro Letters

Overview

This page provides an overview of configuring letters in Esploro. For details on configuring letter components to customize templates and other components shared between letters, see here.

To configure letters, you must have one of the following roles:

General System Administrator
Letter Administrator

Esploro provides a letter system to send highly customizable messages to users, librarians, and vendors. Messages include warnings, confirmations, notifications, summary information, and so forth. Messages can be sent to a printer or an external system or sent by email, SMS, ISO protocol, or other means. And every letter that can be sent to a printer/email can be printed out using Quick Printing.

Esploro includes a list of letters (actually, letter types; a single letter type can be used to send multiple letters that use the same structure). Esploro constructs a letter by combining dynamic XML fields generated by Esploro (data), labels (static text), and a template (formatting). The static labels and template (XSL style sheets) are included with Esploro but may be configured by the user. Label sets are provided in multiple languages for institutions whose users prefer languages other than English.

Most letters are sent automatically by Esploro at the appropriate stage in a workflow. Some letters can be sent by a user at any time, such as a query to a vendor or a patron.

In addition, see the following page with sample XML data for letters on the Developer Network: https://developers.exlibrisgroup.com/blog/Esploro-letters-XML-samples-for-working-on-XSL-customization

Esploro does not use the letter subsystem for certain types of protocol-specific communication with supporting entities, such as ERP’s or other ILS’s. For example, Esploro can use electronic data interchange (EDI) in place of email to communicate with supporting vendors.

All Esploro letters appear on the Letters Configuration page (Configuration Menu > General > Letters Configuration). Available actions include enabling/disabling letters, setting retention periods, and editing letters to configure templates and labels (static content), and view/save letter examples. The Description text is hard coded and cannot be configured.

Description Field

For more information about mapping tables, see Mapping Tables.

To configure and customize Esploro letters:

Add the Letter Administrator role to users who will customize or maintain the email letters. For more information on assigning roles, see Adding Roles to Users.
If you are working in a sandbox environment or a pre-”Go Live” production environment, add the letter administrators’ email addresses to the allowed email list (see Configuring Allowed Emails).
Confirm that the appropriate letters are enabled (see Enabling/Disabling Letters).
Determine which XML data fields are used for a specific type of letter (see Testing Letter Output and Viewing the Source XML).
Customize the text elements (labels) of the letter (see Configuring Letter Labels).
Customize the look-and-feel (XSL) and content of the letter (see Customizing Letter Templates).
Test the output of the XML file and confirm that the letter appears correctly (see Testing Letter Output and Viewing the Source XML).

Enabling/Disabling Letters

Esploro does not send disabled letters. Attempting to send a disabled letter may result in an error notification when the letter is triggered.

Some letters can be activated for different types of notifications, for example SMS and email; the notification type of a letter is listed in the Channel column. If the email version of a letter type is disabled, for example, then email communication is disabled for the relevant scenario, even if email is enabled for this scenario.

Some notifications may be disabled for specific users or for bulk sets of users. For more information see the information for Patron Letters in Managing Users.

Setting Letter Retention

By default, letters sent by Esploro are retained indefinitely and available on the Attachments tab of the User Details (see Managing User Attachments). You can add a retention period, in number of days, in the Retention Period field of email letters so that the configured letters are deleted after a certain number of days.

A weekly job, Letters Purge with Retention, deletes all enabled letters, if they were created more than the configured number of days ago.

Configuring Letter Labels

You can configure the labels associated with letters. Select Edit on the row action list of the letter. The Labels tab is displayed by default.

The following options are available on the row actions menu:

Edit - Opens the label line to edit the Enabled switch and the Description field.
Language change - If another language is configured, the Translation field opens for editing.
Restore - If the line was modified, the Enabled and Description fields are restored to their default.
Restore Translation - If another language is configured and the Translation label was modified, the field is restored to the default.

Two kinds of data are substituted into, and configured by, the letter XSL before the letter is sent (to the patron, or the printer, or wherever): labels and XML data. Esploro generates dynamic XML data. Labels are strings of text that you create and translate.

Letter Labels

Edit each row as required:

Select Customize in the row actions list to change the label or its translation. Select Customize All to edit all rows.
- To edit translations, first select a language in the filter.
Select Restore in the row actions list to restore the label to its default text.
Select Restore Translation in the row actions list to restore the translation to its default text. Select Restore Default Translations to restore all translations.

When done, select Save.

The addressFrom label is the From: field in the email's header, which is separate from the SMTP envelope EnvelopeFrom address. Replies to emails go to the email header From: field. The EnvelopeFrom address is configured separately; see Configuring Outgoing Email. You can also specify an alias for the addressFrom parameter in the following format alias <actual_email_ID@university.edu>.
The Bcc label, used to send a blind copy of the letter to the relevant library's email address, is only available for patron-facing letters.
You can customize the email addresses (or URL) to which the Contact Us and My Account links are directed by configuring the email_my_account and email_contact_us parameters; see Configuring Other Settings.

Customizing Letter Templates

You can view and edit the template (XSL style sheet) that is used to format the letter and determine which fields and text appear in the letter. Configure the template to customize what and how labels and data appear in the letters. In addition, you can use XSL conditional statements to make decisions about what appears in a letter, and even whether the letter is sent. For an example, see How to use the if condition to configure a letter to not be sent under certain circumstances.docx.

Ex Libris support is available to assist with issues related to customized XSL stylesheets. However, their troubleshooting effort is within practical limits. If a style sheet is heavily customized, it may require time-consuming analysis to identify a specific error. Such validation cannot be provided by Support for all customized style sheets. The best practice in these situations is for you to eliminate one condition/test/section at a time to determine what causes the problem.

To customize a letter's template (XSL style sheets):

To open the template, find the desired letter on the Letters Configuration page, select Edit on the row action list of the letter, then select the Template tab.
The XSL and header information appear in a configuration pane.

XSL Template Page
Customize the XSL of the letter as required. The available fields on this page are in the labels associated with the letter and the XML fields that are generated by Esploro.
The following examples show what you can do with XSL to customize the output of your letters:
- Use the substring and string-length functions to output the last four digits of a code:
  <b>@@requested_for@@ :*****
  <xsl:value-of select="substring (notification_data/user_for_printing/identifiers/code_value/value,string-length(notification_data/user_for_printing/identifiers/code_value/value) - 3)"/></b>
- If the following snippet follows the address line in the SenderReceiver.xsl file, you can ensure that the user’s phone number is included in all the letters that use this template.
  <tr>
  <td><xsl:value-of select="notification_data/user_for_printing/phone"/></td>
  </tr>
- Have the name of the template appear as hidden text in the output by adding the following after the <html> tag:
  <html> <xsl:attribute name="data-filename"> <xsl:value-of select="/notification_data/general_data/letter_type"/> </xsl:attribute>
  
  The output will include something like:
  
  <html data-filename=”FulLoanReceiptLetter”> ...
- To remove an element from a letter, find the element to be removed. Add comment indicators on either side of the line, such as, .
  <th>@@title@@</th>
  
  <th>@@author@@</th>
  <th>@@due_date@@</th>
  <th>@@fine@@</th>
  <th>@@library@@</th>
  
  The output table displays without the description column.
- Suppress a letter being sent to users in a specific user group. Add a terminate clause condition after the initial include lines at the top of the letter, as follows:
  
  <table cellspacing="0" cellpadding="5" border="0">
  
  <tr><td><xsl:for-each select="notification_data">
  
  <xsl:if test="user_for_printing/user_group='STUDENT_GRADUATE'">
  
  <xsl:message terminate="yes">user group is STUDENT_GRADUATE </xsl:message></xsl:if></xsl:for-each></td></tr>
  </table>
  
  In the above example, the letter is not generated for users in the Graduate Student user group. For a more detailed explanation, see How to use the if condition to configure a letter to not be sent under certain circumstances.docx.
Select Yes to save your customizations.
You can select Preview Letter to view the letter setup without data.

If you use a tag to refer to an outside location such as a template or URL (for example, <xsl:include href="http://{$PathToWeb}/html/xsl/head.xsl">) and the outside source changes, refresh the XSL (by re-saving it) for the new information to be included in the letter.

Example Letter Customization: Query to Patron Letter

You can configure types of letters to be sent to patrons using the enhanced XSL Query to Patron letter. You can define up to 30 types of letters, for example a welcome letter, a response to a request, and so forth (see Configuring Patron Query Types).

After configuring the query types, a user with the Letter Administrator role can modify the labels and the style sheet of the Query to Patron letter.

To modify the Query to Patron letter:

Confirm that the Query to Patron letter is enabled (see Enabling/Disabling Letters).
Download a copy of the Query to Patron XML fields:
1. Configure Esploro to send you a copy of the XML fields when a Query to Patron letter is sent (see Viewing a Letter’s Source XML).
2. Add a borrowing request for an inventory item (make yourself the Requester; see Adding a Resource Sharing Borrowing Task From a Search).
3. On the Resource Sharing Borrowing Requests page, select Send Query to Patron beneath the new request (see Managing Resource Sharing Borrowing Requests). If you have configured multiple query types, select the letter to send. Otherwise, a message is sent automatically.
  You receive two emails: one is the selected letter and the other is the XML fields that were used to create the letter.
4. Save the XML letter to a file, such as letter.xml .
Modify the labels:
1. On the Letters Configuration page, locate the Query to Patron Letter and edit it.
2. For each label corresponding to the relevant codes that appear in the XSL, select Customize on the row actions menu and enter the new value in the Description column.
  The entries in the Code column (Type_1, Type_2, Type_3, and so forth) correspond to the query types you select in the Patron Query Types Code Table page (see Configuring Patron Query Types). For example, if you defined Type_1_query_name as enabled, you can configure the Type_1_xxxx entries in this table to configure the text lines to be part of this type of query.
3. Select Save.
Modify the XSL:
1. Select the Template tab.
2. In the Xsl field, modify the relevant XSL to change the format of your letter. The same XSL file is used to format all of the query types. You can add fields from the XML or labels, use the values of these fields to make conditions, and so forth.
  For example, a conditional clause looks something like:
  
  <xsl:when test="notification_data/query_type = 'Type_1_query_name'">
  ... special configurations for type 1 queries ....
  </when>
3. Select Save.
To test your changes, upload the XML (letter.xml) as described in Testing Letter Output and Viewing the Source XML.

Testing Letter Output and Viewing the Source XML

A template (XSL style sheet) does not look much like the letter it is used to create, but it contains variable elements in a particular order. The template contains text and XML, as well as XSL commands and variables. Language-dependent text is kept out of the template.

The letter data comes from internally generated XML fields and from the labels. Label values and XML fields are substituted into the variables in the templates. For example, if the page POLineClaimLetter contains the label greeting, the value you enter into this label is substituted into <xsl:variable name=greeting> in the POLineClaimLetter template.

If you store the XML output in a file that has an .xml suffix, you can use it to test changes to the letter.

On the Letter Examples tab, you can edit or download the letter XML, as well as upload new XML samples and delete the uploaded files. The row marked as the Default Preview letter is the one that will be used when selecting the Preview row action. You can browse the latest server side examples and download/add to your examples list. These examples are subject to the retention policy of the institution. The XML files saved in the system will be retained for 7 days and will be removed by the weekly cleanup job. The XML examples added to the XML list from the system are persistent and will not be cleaned by the weekly job. Any identifying information should be removed from these examples.

Available row actions are:

Edit - view and edit the letter XML. You can also select the Download XML option to download the file. Select Save when done.
Preview - open an HTML presentation of the letter. Type an email address in Send Example by Email to send a sample of the letter with the template attached. Select a language from the language drop-down list to preview the letter in one of the languages configured for your system.
Delete - delete a previously uploaded letter example from the table.

When done, select Save.

Letter Example Page

The template is attached to the email. You can see sample XML output of many letters on the Developer’s Network.

Configuring Outgoing Email

Esploro sends emails to patrons, library staff, and vendors.

Every email has two "from" addresses:

From: - Appears in the user's mail reader and determines the reply to address (if no other reply to address is specified).
EnvelopeFrom - Used internally by mail relay servers to determine the origin of the message. This field appears as From (without the colon :) at the very top of the email packet when you look at the packet source, but does not normally appear in the user's mail reader..

You can configure each outgoing email's From: address by configuring the letter's addressFrom label. (The exception to this is the General Message that you can send to any user when managing the user (see Editing Users). The default From: address for this message is set using the from_address parameter (see Configuring Other Settings).) If not configured, Ex Libris uses the default email address Your.Department@organization.com. For some letters, such as several resource sharing letters, the From: address contains the library's email address, if this address is configured. If the address is not configured, the letters use ILL@exlibrisgroup.com as the From address.

You can configure the outgoing email EnvelopeFrom using the mail handling integration profile. For more information about integration profiles, see Configuring Integration Profiles. By default, the EnvelopeFrom is also Esploro@exlibrisgroup.com.

Note that if a recipient's email server (for patrons and staff, this is generally a server run by your institution) has set up a spam filter, the filter checks whether received emails are actually sent by the domain of the address in EnvelopeFrom. When there is a mismatch, emails may be filtered as spam. To prevent this from happening, EnvelopeFrom should remain <something>@exlibrisgroup.com (unless your institution's anti-spam filters and SPF records are configured properly so that this is not an issue). If you are not worried about emails being filtered as spam, you may want to configure EnvelopeFrom in order to catch bounced emails. Emails caught in an email server's spam filter do not generally result in bounced emails.

Replies to emails go to the email header From: field, unless the email has a Reply-To: field.
Purchase order and claim notifications ignore the configured addressFrom field in the letter when an email address is defined in the institution for order response or claim response, respectively. See Configuring Institution/Library Contact Information and Communicating with Vendors.

Instead of configuring EnvelopeFrom, you can instead use the mail handling integration profile to have Esploro send all email through the institution's mail relay server. In this case, the mail relay server sets EnvelopeFrom on the outgoing email.

To configure the mail handling integration profile:

On the Integration Profile List page (Configuration Menu > Integration Profiles), select Add Integration Profile. Esploro allows you to define only one mail handling integration profile. If there is already a mail handling integration profile, select Edit in the row actions list to edit the profile.

Mail Handling Integration Profile Page 1
Enter a unique code and name for the profile.
In the Integration Type field, select Mail Handling.
Select Next. The second page of the wizard appears.

Mail Handling Integration Profile Page 2
To continue to use Esploro's mail server:
1. Select Send directly from Ex Libris (selected by default).
2. Enter a valid email address for EnvelopeFrom.
To use your institution's mail relay server:
1. Select Send using institution mail relay. Several additional fields appear.
2. Enter the institution domain name. After you do this, the domain name appears after the SMTP EnvelopeFrom address field as @<domain name>. The domain name can contain up to 63 lower case alphanumeric characters, dashes -, and periods followed by a period and a two to six character lower case alphabetic top-level domain.
3. Enter the institution SMTP mail relay host name. The host name can contain lower case alphanumeric characters as well as any of the characters - ! # $ % & ' * + / = ? ^ _ ` { | } or ~ and a period.
4. Custom SMTP EnvelopeFrom address is selected by default. Enter a username of the address in the unlabeled field below this option. This sets EnvelopeFrom to <username>@<domain name>. The username can contain the same characters as the SMTP mail relay host name.
  
  If you want, instead, that the EnvelopeFrom of each email outgoing from the institution mail relay be the same as the From: address of that email message, select Use the 'From address' header.
5. If the mail relay requires a username and password to accept email from Ex Libris, enter the username and password. These can be any ASCII characters.
6. If the mail relay requires encryption, select Use encryption.
  
  Encryption port is set to 587 for you.
Select Save.

Letter List

The following table lists the letters available in Esploro.

Letters will only be sent if they are activated in the Letters Configuration page (Configuration > General > Letters Configuration).

All letters are translatable by selecting Edit for the specific letter and then updating the Label/s.

Esploro Letters
Letter Name	Letter Description	Preconditions
Author Matching Report Letter	Email sent when the Author Matching job completes. It contains an attachment with the report.	Activated
New Research Outputs Added to Profile Letter	It is sent to the researcher to update him/her of new research outputs that were added to his/her researcher profile.	Configured per researcher (Manage Researchers > Edit > Researcher Notifications)
Research Asset Citations Send Email Letter	Email sent when choosing to “Export Citations” from a search results page.
Research Assign To Letter	Letter sent to an admin once an asset is assigned to them by someone else.
Research Deposit Action Letter	It is sent to the researcher to update him/her of a status change to their deposit. For example when they submit a deposit to the repository or when a repository manager has approved their deposit. Letter is automatically printed when a researcher submits a deposit, when a repository manager returns a deposit to researcher or when a deposit is approved.
Researcher APC Request Send Email Letter	The letter is only used when the APC request is turned on (see APC Integration). The recipient of the email is the email address that is configured in the Able APC mapping table in the Email for error messages Integration field. The content of the email is the API submission to Oable and the API response that is received from Oable. The email is generated each time an APC request is submitted.
Researcher Asset Page Send Email Letter	Letter which is sent manually from the asset form in the Research Hub. For configuring the address and subject see From Address and Subject for Email on the Configuring the Research Portal page.
Researcher Assets Usage Statistics Letter	It is sent to affiliated researchers with outputs that have been either viewed or downloaded in the past month. For more information, see Viewing Scheduled Jobs. Authors who have opted out will not receive email notifications.
Researcher ETD Usage Statistics Letter	It is sent to ETD authors with an output that has been either viewed or downloaded in the past month. For more information, see Viewing Scheduled Jobs. Authors who have opted out will not receive email notifications.
Researcher Url Identifier Notify Letter	This letter is sent to affiliated researchers with active profiles to notify them that their URL_identifier has been updated and their webpage URL has changed.
Research ORCID Letter	Notify researchers that their assets synched with ORCID
Student Deposit Approval Letter	Notify student depositor that their deposit was approved
title.Reply_To_Researcher_Letter	Reply to Researcher Letter