Alma: Editing Letter Content

Letters are modified by navigating to Alma Configuration -> General -> Letters Configuration.

This page covers how to:

  • Customizing Letter Labels
  • Customizing Letter Components
  • Customizing Letter XML
  • Frequently Requested XML Edits

Customizing Letter Labels

Each letter has a list of editable labels that can be modified and enabled or disabled for display.
These labels are found by selecting any letter listed in the Letters Configuration pages in Alma Configuration. 

To customize the information in one of the label fields for a letter:

  1. In Alma Configuration> General> Letters> Letters Configuration, select the name of the letter you wish to customize.
  2. Find the label you wish to change in the list of editable letter fields. 
  3. Select the ellipses button to the far right of the label's line and select Customize.
  4. This should make the section in the Description field for that row editable. Update this to your library's preferred setting.
    The screenshot below shows an edited "addressFrom" label as an example.
  5. Save your changes to the letter when complete.

Screenshot shows the "addressFrom" label from a sample Alma letter. The "Description" box, where staff can make their wording edits, is highlighted.

Your institution should consider editing the labels in the following table:

Label Description Suggested Edits
addressFrom The email address that the outgoing email will be sent from. By default this is set to Your.Department@organization.com.

Change to a functional email for your institution, or set to no-reply@yourinstitution.edu.

To have your institution's name display in emails instead of the address, format the field as the following:
Institution Name <email@institution.edu>
department Used for the letter closing. For example:
Sincerely, Circulation Department 		 Check to ensure the correct department is attributed. Alternatively, this closing can be removed altogether by disabling the label along with the "Sincerely" label. 
header Contains the opening greeting for the letter. Default is often Dear Sir/Madam. CARLI has changed this to "Hello," over "Dear Sir/Madam." Libraries may override this to anything they choose.

Customizing Letter Components

Some components are shared among all letters in Alma. For example, the Header is the same for every letter. This includes parts of the letter like your institution's logo, the name of the letter, and the date. This template is then pulled into each individual letter with code like the following: 

         <xsl:include href="header.xsl" />
                <xsl:call-template name="head" />

The code above creates a header in the letter like the one below:

logo
On Hold Shelf Letter 01/24/2020

This common item is managed in a different area under Alma Configuration called Letters Components. Editing these components will change the content for those pieces across all the letters in your system. 

The following can be managed under Letters Components:

Component Description
checksum_calc.xsl For internal use. Ignore this component.
footer.xsl Defines the text (such as Contact Us and My Account) used in the footer for all letter emails.
header.xsl Defines the text (such as your institution's logo, the letter name, and the date) used in the header for all letter emails.
mailReason.xsl Defines the greeting (such as Dear Sir/Madam) used in most letter emails.
recordTitle.xsl Defines the text used for bibliographic details in letter emails.
senderReceiver.xsl Defines the address information for all letter emails. This component uses <xsl:value-of select="notification_data/user_for_printing/name"/>, which is populated according to the configuration in User Name Display. However, user_for_printing also includes the name and preferred name values, so it can be configured differently. 
smsRecordTitle.xsl Defines the text used for bibliographic details in SMS letters.
style.xsl Defines the CSS used for all letter emails. Here you will find style elements for 

Related Resource: Ex Libris Documentation on Configuring Components

Customizing Letter XML

Before customizing a letter's XML, please double-check whether the letter is consortially managed.

In addition to the letter labels, each letter can be further customized using XML under the Templatetab. XML works similar to HTML, using opening and closing tags to change how text is displayed or to create formatting elements like tables and headings. In addition to this, the letter labels mentioned above are pulled into the letter by surrounding the "Code" for the label (found in column three on the Labels tab) with two @ symbols on either side.

For example, the XML below creates a table. In that table will be the text that was input for those labels on the Labels tab:

            <table>
                <tr><td>@@sincerely@@,</td></tr>
                <tr><td>@@department@@</td></tr>
            </table>

The code above will create an HTML table with two rows containing the following:

             Sincerely,
             Circulation Department

Frequently Requested XML Edits

Below are some commonly requested XML edits to Alma Letters. 

Adding Preferred First Name

<xsl:value-of select="notification_data/receivers/receiver/user/preferred_first_name" />

More Advanced: Checking for Preferred First name, otherwise use First Name.

<xsl:choose>
    <xsl:when test="(/notification_data/receivers/receiver/user/preferred_first_name!='')">
    <xsl:value-of select="notification_data/receivers/receiver/user/preferred_first_name" />
    </xsl:when>
    <xsl:otherwise>
    <xsl:value-of select="notification_data/receivers/receiver/user/first_name" />
    </xsl:otherwise>
</xsl:choose>

Combining Greeting, Preferred First Name, and Last Name

Dear 
<xsl:choose>
    <xsl:when test="(/notification_data/receivers/receiver/user/preferred_first_name!='')">
        <xsl:value-of select="notification_data/receivers/receiver/user/preferred_first_name" />&#160;<xsl:value-of select="notification_data/receivers/receiver/user/preferred_last_name" />,
    </xsl:when>
    <xsl:otherwise>
        <xsl:value-of select="notification_data/receivers/receiver/user/first_name" />&#160;<xsl:value-of select="notification_data/receivers/receiver/user/preferred_last_name" />
    </xsl:otherwise>
</xsl:choose>

Steps For Removing the Letter Name from Alma Letters

  • The CARLI Office has added the name of each letter to the footer component. As we're learning Alma, and learning under what conditions and workflows each letter is produced, it can be helpful to know exactly which letter we're seeing. After a library is comfortable with the letters being generated, they can edit the footer.xml component to remove the letter reference.
  • To remove the letter name, delete the following line of XML from the footer.xml component:
            <xsl:if test="notification_data/general_data/letter_name !=''">
                 <h4>Letter Name: <xsl:value-of select="notification_data/general_data/letter_name"/> -
                 <xsl:value-of select="notification_data/general_data/letter_type"/></h4>
            </xsl:if>