Alma Letters: Editing Greetings and Preferred Names

This guide provides information on modifying greetings and names within Alma Letters, including working with preferred names.
Supplemental information can be found in Ex Libris Documentation: Configuring Alma Letters. 

One of the following Alma User Roles is required to perform the tasks outlined on this page:

• General System Administrator
• Letter Administrator

Table of Contents

• Background on Greetings and Preferred Names in Alma Letters
• Alma Letter Components/Templates
• Where Names and Greetings Show Up in Alma Letters
• How to Change Greetings and Names in All Alma Letters
  • Editing the senderReceiver.xsl Component/Template
    • Section 1 - user_for_printing
    • Section 2 - receivers/receiver/user
  • Editing the mailReason.xsl Component/Template
  • Editing Individual Letters Not Utilizing Alma Components/Templates
• Additional XSL Examples for Preferred Name
  • "Requested for" in Ful Hold Shelf Request Slip Letter with Preferred Names and Middle Initial
  • Preferred Name Implementation with Fallback to Default

Background on Greetings and Preferred Names in Alma Letters

• Alma uses Letters to communicate with patrons, librarians, and vendors via print and email.
• Patrons can designate preferred first names and last names in their user profile.
• Letters and Letter Components do not display preferred names by default.
• Users find Alma’s inconsistencies utilizing preferred name confusing.
• Additionally, many letters use a default greeting of “Dear Sir/Madam {last_name}” that libraries prefer to change.
• Letters in Alma do not use Alma’s Letter Templates consistently or follow the same formatting patterns, making it difficult to reliably change greetings and configure all letters to use preferred names.

Alma Letter Components/Templates

It is useful to understand where Letter Components/Templates are used in Alma Letters. 

There are 4 Letter Components/Templates used to construct the body of Alma Letters. They are listed below and displayed in the sample letter image to the right. 

1. header.xsl - library logo, letter name, and date
2. senderReceiver.xsl - patron name and address if available, library name and address if available
3. mailReason.xsl - The toWhomIsConcerned template within this component is used for the letter greeting. Default is "Dear Sir/Madam {last_name}." The example to the right has been changed to "Hello,". 
4. footer.xsl - library name, Contact Us link (removed in this example), My Account link (removed in this example)

Where Names and Greetings Show Up in Alma Letters

Alma Letters utilize names and greetings in 3 potential places. 

1. In Letter Components / Letter Templates
   • senderReceiver.xsl - Name and address at the top of the letter
   • mailReason.xsl - Greeting (Default: Dear Sir/Madam {last_name})
      
2. In individual Letter XSL 
   • Some letters have their own @@dear@@ or @@header@@ greeting field in the letter's EXL instead of utilizing Alma's templates. These letters must be edited individually in order to change the Dear Sir/Madam greeting.
     • These letters can be found in the table on our Alma Letters Using Templates for Greetings and Names page.
   • Note that the following letters have this field in the labels section for that letter, but the field is never called:
     • Ful Lost Loan Letter
     • Ful Lost Loan Notification Letter
     • Ful Overdue And Lost Loan Letter
     • Ful Overdue And Lost Loan Notification Letter
     • Ful Fines\Fees Notification Letter
     • General Assign To Letter
        
3. The following 3 letters use names within the body of the letter, beyond the header or greeting
   • Ful Resource Request Slip Letter - “Requested By {name}”
   • Ful Transit Slip Letter - “Requested By {name}”
   • Ful Hold Shelf Request Slip Letter - "Requested For {name}"

How to Change Greetings and Names in All Alma Letters

Not all Alma Letters utilize templates in the same way. As of 12/12/2024, this is the current state of greetings and names in Alma Letters:

• 61 letters use the senderReceiver.xsl template for name and address at the top of letters
  • Edit this in Configuration -> General -> Letters -> Components Configuration -> senderReceiver.xsl
  • Walkthrough: Editing the senderReceiver.xsl Component/Template
• 58 letters use the mailReason.xsl template for the "Dear Sir/Madam {lastName}" greeting at the start of the letter message
  • Edit this in Configuration -> General -> Letters -> Components Configuration -> mailReason.xsl
  • Walkthrough: Editing the mailReason.xsl Component/Template
• 23 letters have their own @@header@@ or @@dear@@ greeting in their XSL. This is similar to the code in the mailReason.xsl template, but is not using the template.
  • Edit this by visiting each of those letters and changing the text for the "Header" or "Dear" code under Labels
  • Walkthrough: Editing Letters Not Utilizing Alma Components/Templates
• 3 letters use names somewhere other than the header and greeting
  • Edit this within the XSL code for Ful Resource Request Slip Letter, Ful Transit Slip Letter, and Ful Hold Shelf Request Slip Letter
  • Example: "Requested for" in Ful Hold Shelf Request Slip Letter with Preferred Names and Middle Initial
• 26 letters do not use names anywhere in the header, greeting, or body of the letter.

For a full table that shows which letters are using templates, which are not, and which have their own unique greeting fields visit our Alma Letters Using Templates for Greetings and Names page.

Editing the senderReceiver.xsl Component/Template

The senderReceiver.xsl Component is found under Configuration -> General -> Letters -> Components Configuration -> senderReceiver.xsl
The component calls a user's name in two potential locations, depending whether the notification_data/user_for_printing field is being used or the notification_data/receivers/receiver/user field. 

Note that the code for user_for_printing is calling a single XML element that contains the user's last name and first name separated by a comma, while the code for /receivers/receiver/user is calling two XML elements, the last name element and first name element, which are separated by a space written in HTML code ( ).

To reiterate, there are two places where this template is generating LastName+FirstName depending on the situation, the method for creating LastName+FirstName is different in each place, and the output looks slightly different in each place. And, again, neither of these take Preferred Names into account.

    "notification_data/user_for_printing/name" = "LastName, FirstName"
    "/receivers/receiver/user/last_name" "/receivers/receiver/user/first_name" = "LastName FirstName"

 

Editing Section 1 - user_for_printing

For the user_for_printing section, CARLI is utilizing the following code to check for preferred names and fall back on default names when no preferred name is found. This code allows for preferred first and/or last names in any combination. 

Note 1: This code utilizes two XML elements, preferred_last_name and preferred_first_name, because a single field with "PreferredLastName, PreferredFirstName" does not exist. 

Note 2: CARLI decided to reverse the name order, changing from "LastName, FirstName" to "FirstName LastName" in this section. 

Replace the following line of code (line 18 in the above screenshot): 

<tr><td><b><xsl:value-of select="notification_data/user_for_printing/name"/></b></td></tr>

With the following: 

<tr><td><b>
    <xsl:choose>
        <xsl:when test="(notification_data/user_for_printing/preferred_first_name!='')">
            <xsl:value-of select="notification_data/user_for_printing/preferred_first_name" />
        </xsl:when>
        <xsl:otherwise>
            <xsl:value-of select="notification_data/user_for_printing/first_name" />
        </xsl:otherwise>
    </xsl:choose>&#160;
    <xsl:choose>
        <xsl:when test="(notification_data/user_for_printing/preferred_last_name!='')">
            <xsl:value-of select="notification_data/user_for_printing/preferred_last_name" />
        </xsl:when>
        <xsl:otherwise>
            <xsl:value-of select="notification_data/user_for_printing/last_name" />
        </xsl:otherwise>
    </xsl:choose>
</b></td></tr>

The code above can be written as a single line if you prefer: 

<tr><td><b><xsl:choose><xsl:when test="(notification_data/user_for_printing/preferred_first_name!='')"><xsl:value-of select="notification_data/user_for_printing/preferred_first_name" /></xsl:when><xsl:otherwise><xsl:value-of select="notification_data/user_for_printing/first_name" /></xsl:otherwise></xsl:choose>&#160;<xsl:choose><xsl:when test="(notification_data/user_for_printing/preferred_last_name!='')"><xsl:value-of select="notification_data/user_for_printing/preferred_last_name" /></xsl:when><xsl:otherwise><xsl:value-of select="notification_data/user_for_printing/last_name" /></xsl:otherwise></xsl:choose></b></td></tr>

RESULT

Given the following user metadata: 

<first_name>Jonathan</first_name>
<last_name>Doe</last_name>
<preferred_first_name>Jon</preferred_first_name>
<preferred_last_name>Doe-Smith</preferred_last_name>

The above code will produce the following:

Jon Doe-Smith

Editing Section 2 - receivers/receiver/user

For the receivers/receiver/user section of the template, a similar block of code is used to check for preferred names and fall back on default names when no preferred name is found.
This code calls the XML fields slightly differently from above because the line <xsl:for-each select="notification_data/receivers/receiver/user"> places us in the notification_data/receivers/receiver/user section of the XML already. 
Note: CARLI decided to reverse the name order, changing from "LastName FirstName" to "FirstName LastName" in this section.

Replace the following line of code (line 39 in the above screenshot): 

<tr><td><b><xsl:value-of select="last_name"/>&#160;<xsl:value-of select="first_name"/></b></td></tr>

With the following:

<tr><td><b>
    <xsl:choose>
        <xsl:when test="(preferred_first_name!='')">
            <xsl:value-of select="preferred_first_name" />
        </xsl:when>
        <xsl:otherwise>
            <xsl:value-of select="first_name" />
        </xsl:otherwise></xsl:choose>&#160;
    <xsl:choose>
        <xsl:when test="(preferred_last_name!='')">
            <xsl:value-of select="preferred_last_name" />
        </xsl:when>
        <xsl:otherwise>
            <xsl:value-of select="last_name" />
        </xsl:otherwise>
    </xsl:choose>
</b></td></tr>

The code above can be written as a single line if you prefer:

<tr><td><b><xsl:choose><xsl:when test="(preferred_first_name!='')"><xsl:value-of select="preferred_first_name" /></xsl:when><xsl:otherwise><xsl:value-of select="first_name" /></xsl:otherwise></xsl:choose>&#160;<xsl:choose><xsl:when test="(preferred_last_name!='')"><xsl:value-of select="preferred_last_name" /></xsl:when><xsl:otherwise><xsl:value-of select="last_name" /></xsl:otherwise></xsl:choose></b></td></tr>

RESULT

Given the following user metadata: 

<first_name>Jonathan</first_name>
<last_name>Doe</last_name>
<preferred_first_name>Jon</preferred_first_name>
<preferred_last_name>Doe-Smith</preferred_last_name>

The above code will produce the following:

Jon Doe-Smith

Editing the mailReason.xsl Component/Template

The mailReason.xsl Component is found under Configuration -> General -> Letters -> Components Configuration -> mailReason.xsl
By default, the mailReason.xsl Component/Template displays the greeting "Dear Sir/Madam {lastName}" in any letter using that template. This can be found in the screenshots below. 

At CARLI, we have replaced the Dear Sir/Madam Label with "Hello," and removed the XSL code for last name altogether. This results in a simplified greeting that does not utilize any names.
The XSL code for this template now looks like the following:

<?xml version="1.0" encoding="utf-8"?>

<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:template name="toWhomIsConcerned">
<table cellspacing="0" cellpadding="5" border="0">
    <tr>
        <td>
            <xsl:for-each select="notification_data">
                <h3>@@dear@@</h3>
            </xsl:for-each>
        </td>
    </tr>
</table>

</xsl:template>

</xsl:stylesheet>

Editing Individual Letters Not Utilizing Alma Components/Templates

23 letters have their own @@header@@ or @@dear@@ greeting in their XSL. Editing the mailReason.xsl template will not change the greetings in these letters.
These letters must be edited individually by changing the text in the label for the greeting. 

Letters using their own @@header@@ or @@dear@@ field for greeting instead of mailReason.xsl
Borrower Claim Email Letter	Lender Checked-in Email Letter
Borrower Receive Email Letter	Lender Reject Email Letter
Borrower Return Email Letter	Lender Renew Response Email Letter
Change Rapido Request Terms Letter	Lender Ship Email Letter
Externally Obtained Email Letter	Lender Will Supply Email Letter
Ful Cancel Email Letter	Lending Recall Email Letter
Ful Damaged Email Letter	Query To Patron Letter
Ful Lost Email Letter	Rapido member letter
Ful Outgoing Email Letter	Resend Notification Letter
Ful Renew Email Letter	Resource Sharing Request Confirmation Letter
Ful Requests Report Letter	User Notifications Letter
General Message Email Letter

Alma Letters with defunct labels

6 Alma Letters have a field in Labels for the greeting, but that field is not utilized. Changing this field in the labels area for these letters will do nothing. 
5 of these letters do not call the mailReason.xsl template for greeting either, meaning they have no greeting at all. 
1 letter, General Assign To Letter, does use the mailReason.xsl template.

• Ful Lost Loan Letter - Has its own @@dear@@ field in labels, but this is not used anywhere in the XML. Does not call mailReason.xsl template. Has no greeting. 
• Ful Lost Loan Notification Letter - Has its own @@dear@@ field in labels, but this is not used anywhere in the XML. Does not call mailReason.xsl template. Has no greeting. 
• Ful Overdue And Lost Loan Letter - Has its own @@dear@@ field in labels, but this is not used anywhere in the XML. Does not call mailReason.xsl template. Has no greeting. 
• Ful Overdue And Lost Loan Notification Letter - Has its own @@dear@@ field in labels, but this is not used anywhere in the XML. Does not call mailReason.xsl template. Has no greeting. 
• Ful Fines\Fees Notification Letter - Has its own @@dear@@ field in labels, but this is not used anywhere in the XML. Does not call mailReason.xsl template. Has no greeting. 
• General Assign To Letter - Has a @@mr_mrs@@ field in labels that is not used. DOES call mailReason.xsl template.

Additional XSL Examples for Preferred Name

Example: "Requested for" in Ful Hold Shelf Request Slip Letter with Preferred Names and Middle Initial

The Ful Hold Shelf Request Slip Letter utilizes patron names in the Requested For portion of that letter. Below is the code we are using to incorporate Preferred Names in that section. 
Note: CARLI has added middle initial to this section at the request of our libraries. If a user does not wish to have their middle initial appear, they can set their Preferred Middle Name to a space, which will result in the space being displayed instead of their default middle initial. 

<b>@@requested_for@@</b>:
<xsl:choose>
    <xsl:when test="(/notification_data/user_for_printing/preferred_last_name!='')">
        <xsl:value-of select="/notification_data/user_for_printing/preferred_last_name" />
    </xsl:when>
    <xsl:otherwise>
        <xsl:value-of select="/notification_data/user_for_printing/last_name" />
    </xsl:otherwise>
</xsl:choose>, 
<xsl:choose>
    <xsl:when test="(/notification_data/user_for_printing/preferred_first_name!='')">
        <xsl:value-of select="/notification_data/user_for_printing/preferred_first_name" />&#160;
    </xsl:when>
    <xsl:otherwise>
        <xsl:value-of select="/notification_data/user_for_printing/first_name" />&#160;
    </xsl:otherwise>
</xsl:choose> <xsl:choose>
    <xsl:when test="(/notification_data/user_for_printing/preferred_middle_name!='')">
        <xsl:value-of select="substring (/notification_data/user_for_printing/preferred_middle_name, 1,1)" />
    </xsl:when>
    <xsl:when test="(/notification_data/user_for_printing/middle_name!='')">
        <xsl:value-of select="substring (/notification_data/user_for_printing/middle_name, 1,1)" />
    </xsl:when>
</xsl:choose> 

RESULT

Given the following user metadata: 

<first_name>Jonathan</first_name>
<last_name>Doe</last_name>
<middle_name>Jacob</middle_name>
<preferred_first_name>Jon</preferred_first_name>
<preferred_last_name>Doe-Smith</preferred_last_name>
<preferred_middle_name>Samuel</preferred_middle_name>

The above code will produce the following:

Doe-Smith, Jon S

Example: Preferred Name Implementation with Fallback

For scenarios where it is necessary to utilize a patron's name, such as the senderReceiver.xsl Component/Template, it is ideal to use code that checks for preferred name, but can fall back to the default name if a preferred name is not found.

Below is one example of XSL code that checks for preferred first name, prints that name if found, and prints the default name if no preferred name is found. The code then repeats the process for preferred last name. This is the code we are currently using in our senderReceiver.xsl Component/Template.

<xsl:choose>
    <xsl:when test="(notification_data/user_for_printing/preferred_first_name!='')">
        <xsl:value-of select="notification_data/user_for_printing/preferred_first_name" />
    </xsl:when>
    <xsl:otherwise>
        <xsl:value-of select="notification_data/user_for_printing/first_name" />
    </xsl:otherwise>
</xsl:choose>&#160;
<xsl:choose>
    <xsl:when test="(notification_data/user_for_printing/preferred_last_name!='')">
        <xsl:value-of select="notification_data/user_for_printing/preferred_last_name" />
    </xsl:when>
    <xsl:otherwise>
        <xsl:value-of select="notification_data/user_for_printing/last_name" />
    </xsl:otherwise>
</xsl:choose>

RESULT

Given the following user metadata: 

<first_name>Jonathan</first_name>
<last_name>Doe</last_name>
<preferred_first_name>Jon</preferred_first_name>
<preferred_last_name>Doe-Smith</preferred_last_name>

The above code will produce the following:

Jon Doe-Smith