How to I activate, edit, test, and set retention periods for letters in Alma?
Answer
Alma uses Letters to send email notifications to users and print paperwork for library staff. Whenever a letter is generated, the following things happen:
- Alma generates an XML file containing information about the event that triggered the letter.
- Alma uses an XSL template to format the information in the XML file into a readable letter. Each letter has its own XSL template that must be configured separately. Alma also uses letter components to insert headers and footers into your letters. These components are shared by all letters, so changes to a component's XSL template will be reflected in all letters that use that component.
- Alma sends the letter to a user or a printer.
Alma provides two general functions for editing your letters. The Letter Configuration function allows you to activate/deactivate, edit, and test the XSL templates used to format your letters. The Components Configuration function allows you to edit headers and footers that are used by all letters. In order to edit letters and components, you will need one of the following roles:
- General System Administrator
- Letter Administrator
For a list of patron facing letters that should be reviewed, please see the following Google spreadsheet:
https://docs.google.com/spreadsheets/d/1zns56tSmI_4HHLKp1gVKd9O2OrmBSUBLMVOy71Ahf1Y/edit#gid=0
Note: If you edit a letter template and run into a problem, it's possible to use the Restore function to undo your changes. However, the Restore function will overwrite your current letter template with the default letter template, so any changes made since go live will be lost. Therefore, we recommend you copy your letter template to a text file and save it before you start making any changes. If you run into problems, you'll be able to copy and paste that saved template back into Alma.
Table of Contents
- General Layout of Letter Configuration and Components Configuration Functions
- Navigating to the Letter Configuration and Components Configuration Functions
- Activating and Deactivating Letters
- Setting Letter Retention Periods
- Editing Letter Templates
- Saving Letter Template Drafts
- Editing Letter Labels
- Editing Letter Components
- Previewing Letters
General Layout of Letter Configuration and Components Configuration Functions
The interfaces for the Letter Configuration and Components Configuration functions are divided into three sections:
- Upper Left: XSL Template
- Lower Left: XML file
- Right: Letter preview
When an edit is made to either the XSL template or the the sample XML, the letter preview will update in real time. If you would like to send a copy of the email you are configuring to a specific email address, you can enter that email address in the Send Example by Email field in the lower right corner and then click the Send button.
Labels: In order to make editing letter templates easier, Alma uses labels to insert text into the templates rather than including that text in the XSL template itself. These labels are referenced in the XSL template by surrounding the label name with two @ symbols on either side (ex. @@supplied_to@@). You can edit these labels by clicking on the Labels link in the upper right corner. Additional information on how to edit labels is below.
Letter Examples: Alma provides a default example XML file for each letter that can be used to preview that letter. These default example XML files do not contain very much data, and they are often unhelpful. You can replace the default example XML files with XML files that were actually generated at your library by clicking on the Letter Examples link in the upper right corner. Additional information on how to replace default XML files can be found here.
Navigating to the Letter Configuration and Components Configuration Functions
1. Go to Configuration | General | Letters | Letters Configuration or Components Configuration.
Activating and Deactivating Letters
1. Go to Configuration | General | Letters | Letters Configuration.
2. Scroll to the letter you wish to activate or deactivate, toggle the Enabled button to the left if you wish to disable the letter or to the right if you wish to enable the letter, and then click Save.
Setting Letter Retention Periods
1. Go to Configuration | General | Letters | Letters Configuration.
2. Scroll to the letter you wish to set a retention period for, enter the number of days you wish the letter to be retained, and then click Save. Letters without a retention period will be retained indefinitely. Letters with a retention period will be deleted by the Letters Purge With Retention job once their retention period has passed. Please note that the Letters Purge With Retention job runs only once per week. To turn on the Letters Purge With Retention job, please submit a Salesforce case to Ex Libris.
1. Go to Configuration | General | Letters | Letters Configuration.
2. Scroll to the letter you wish to edit, click the ellipsis next to that letter, and then click Edit.
3. Make needed changes to the XSL template in the XSL section of the letter template interface. As you edit the XSL template, the letter preview will be updated accordingly. Once your letter looks the way you need it to look, click the Save button.
If you are working on a letter template and you need to save your work so you can finish it later, you can use the Save Draft function. The changes you've made to the letter template will be saved, but those changes will not be applied to the letter until the saved draft is completed.
1. To save the changes you've made to a letter template as a draft, click the Save Draft link and then click the Cancel button to navigate away from the letter template. Do not click the Save button. Clicking the Save button will permanently save the changes you've made to the template.
2. Once a draft of a letter has been saved, "(XSL Draft)" will be added to the end of that letter's name in the Letters Configuration list. To resume editing the draft, click the ellipsis next to that letter and click Edit Draft. If you want to delete the draft, click Remove Draft.
3. Resume editing the letter as described above. Once you are finished editing the template, click the Save button. The changes you've made to the template will be implemented, and the draft designation will be removed from the letter's name. If you need to save your changes as a draft again, you can click the Save Draft link and then click the Cancel button. Your draft will be updated, and you can use the Edit Draft function as described above to resume editing it. If you wish to delete your draft, you can click the Remove Draft link.
In order to make editing letter templates easier, Alma uses labels to insert text into the templates rather than including that text in the XSL template itself. These labels are referenced in the XSL template by surrounding the label name with two @ symbols on either side (ex. @@supplied_to@@). Here is an example:
<tr>
<td>
<b>@@supplied_to@@: </b>
<xsl:value-of select="notification_data/partner_name"/>
</td>
</tr>
In this example, Alma will replace "@@supplied_to@@" with the text listed in the Description field of the supplied_to label. Details on how to edit a label's Description field are below.
1. Navigate to the template of the letter you wish to edit and then click the Labels link.
2. If the label you need to edit has never been edited before, you'll first need to click the ellipsis next to that label and then click the Customize link. Once you do this, the Description field will become editable. If the label has previously been edited, the Description field will already be editable. Change the value in the Description field as needed, and then click the Save button.
Alma uses Letter Components to simplify the process of editing headers and footers that appear in all letters. The image below details where specific Letter Components appear in your letters.
1. Go to Configuration | General | Letters | Components Configuration.
2. Click the ellipsis next to the component you wish to edit and then click Edit.
3. To edit a component's labels or template, follow the same procedures outlines in the Editing Letter Labels and Editing letter Templates sections above.
Alma will provide a real-time preview of the changes you've made to a letter's template on the right side of your screen. The preview you're seeing uses the XML showing in the lower right portion of your screen. That XML will be default XML included with Alma unless you actively replace it. The default XML included with Alma is extremely generic and is often missing important information, so it's best to use an actual XML file generated at your library. Instructions for replacing the default XML are below.
1. Navigate to the template of the letter you wish to edit and then click the Letters Example link.
2. Click the Add From Systems Letters link. A list of XML files for recently sent letters will appear. Please note that Alma retains only the 10 most recent XML files generated for a letter, and it does not retain any files older than 14 days.
3. Click on the XML file you wish to use to preview the letter. Once you click on an XML file, it will be added to the Letter Example list.
4. Click the Default Preview button for the XML file you just added to the Letter Example list and then click the Save button. Alma will replace the XML in the lower left corner of the page and generate a new letter preview using the XML you selected.
Note: You can add as many XML files to the Letter Examples list as you wish, and you can change the Default Preview setting to switch between them as necessary. To remove an XML file from the Letters Examples list, click the ellipsis next to that file and then click Delete. Unfortunately, you cannot rename the XML files you select from the Add From Systems Letters interface. Alma will always use the letter name and the date and time the letter was sent as the name for those files. If you'd to rename an XML file in the Letters Example list, you can set it as the Default Preview letter, click the Download link in the XML section of the main letter template interface, save the file with the file name you wish to use, click the Letters Example link, and then use the Upload Letters Example (XML) link to upload the XML file you downloaded and renamed.