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.
- General System Administrator
- Letter Administrator

- 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
Setting Letter Retention
Configuring Letter Labels
- 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.

- 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
- 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>@@description@@</th>-->.
<th>@@title@@</th>
<!--<th>@@description@@</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.
- Use the substring and string-length functions to output the last four digits of a code:
- Select Yes to save your customizations.
-
You can select Preview Letter to view the letter setup without data.
Example Letter Customization: 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:
- 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).
- Add a borrowing request for an inventory item (make yourself the Requester; see Adding a Resource Sharing Borrowing Task From a Search).
- 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.
- Save the XML letter to a file, such as letter.xml .
- Modify the labels:
- On the Letters Configuration page, locate the Query to Patron Letter and edit it.
- 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.
- Select Save.
- Modify the XSL:
- Select the Template tab.
- 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> - 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
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.

The template is attached to the email. You can see sample XML output of many letters on the Developer’s Network.
Configuring Outgoing Email
- 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..
- 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.
- 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:
-
Select Send directly from Ex Libris (selected by default).
-
Enter a valid email address for EnvelopeFrom.
-
-
To use your institution's mail relay server:
-
Select Send using institution mail relay. Several additional fields appear.
-
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.
-
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.
-
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.
-
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.
-
If the mail relay requires encryption, select Use encryption.
Encryption port is set to 587 for you.
-
- Select Save.
Letter List
Letter Name | Letter Description | Preconditions | Examples |
---|---|---|---|
Author Matching Report Letter | Email sent when the Author Matching job completes. It contains an attachment with the report. |
|
|
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. |
|
|
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 |
Additional References
- Configuring Allowed Emails
- Components/Templates to Reuse Across Letters (e.g., headers, footers, etc.)
- Ongoing Maintenance and Administration in Esploro
- Esploro Integration
- PPTX Presentation: Letter Configuration in Alma (visualizes the main concepts in Alma which are basically the same as for Esploro)