Editing Letters
- Chris Lee
Librarians and Library Staff often are not programmers and vary wildly in their experience writing any sort of code. This works as a crash course in programing for Alma Letters. This is information I wish I knew before I started working on Letters. Provided information includes XSLT Basics and Specific codes to paste into Letters for desired effects.
Please note I am self taught and this is not comprehensive. If there is any information you want added or changed please let me know at cwlee@calstate.edu.
Recommended Habits
Alma Letters can be complicated and are often edited by different people over time. To keep things simple, and to avoid issues, there are several habits you should consider developing when working with Letters.
Copy the Letter and save it in a folder on your computer, drive, or department server before editing. Then if something goes wrong you can easily restore the previous version of the letter.
Click Preview after every change to see if the change breaks the code.
Keep a change log of some sort. This can be a note in the code using Note Tags (
<!--Note Text-->).Formatting and spacing in the code isn’t as strict as other forms of programming, but keeping things formatted will make it easier for you, and future code editors, to read and understand. I recommend pasting the code into a XML formatter to keep it formatted after editing. I use this one: https://www.freeformatter.com/xml-formatter.html
How to Edit Letters in Alma
Before you can edit letters it is useful to know where to edit them and the basic options. To edit the Letters go to Configuration → General → Letters → Letters Configuration. Search for the Letter you want to edit and click the Letter name to open it for editing. There are three tabs to use for different parts of editing.
Labels
The first tab is the Labels tab. This tab lets you change some basic words from the letter. Click the ellipses and Customize to change the Description, which is the word that will appear in the text when the corresponding code appears in the XLST.
Template
The Template tab is the main area to edit the Letter. This is where the XSLT code lives and can be edited. Most of the tips and tricks on this page concern editing the code in this section. If you want to download versions of this letter shared by other libraries you can do so by clicking Shared XSLs. You can also share your code by clicking Contribute. You can also click Preview Letter to see a quick preview of what your letter will look like. Unfortunately, this preview often lacks much of the information present in the full letter. To see in depth previews I suggest using the last tab in the letter.
Letter Examples
The final tab is the Letters Examples. By default, there is a single default letter that will show an example of the letter using barebones XML that may lack most of the information needed in the real version of the letter. To generate a more accurate example click + Add from system letters and select one of the recent real examples of the letter. After selecting the example, click the ellipses and select preview to see the example. You can also set the new example as the Default Preview to use it as the preview on the Template tab.
You can also use the + Add from system letters to see the XML from an example to the real letter. This is very useful to see what information is available for the letter and code directions to retrieving the information from the XML. To see the XML click the ellipses, preview, and click Download XML.
If there are no examples appearing after you click + Add from system letters, that means the letter has never been sent out and you will need to replicate the circumstances that generate the letter.
XSLT Basics
When writing XSLT you need to keep in mid that the code needs an opening and closing tag for each action. An opening tag is formatted as <X> and a closing tag is </X>. For every opening tag there must be a closing tag. Everything between the two tags has the effect of that tag, so it will be on the same row or cell, have the same font, or all be highlighted depending on the tag used.
Tags
Many tags and elements are used repeatedly to achieve desired formatting. This section will go over many common formatting codes in Rapido. Like many programming codes these tags need to be placed before text or element and the closing tag needs to be placed after the text or element.
Rows, Cells, and Tables
The most common code in Alma Letters are the <tr>, <td>, <th>, <br />, tags.
<tr>is a row. Use this when you want the nested information on its own line. Close a row with</tr><td>is a basic cell. This is a space to add standard text or images. Close a cell with</td><th>is a header cell. Text in this cell will be bold and centered. Close a header with</th><br />is used as a line break in the text. This can stand alone without opening and closing.<table>is used to create a table where the rows and cells will be contained. By default the table is invisible, but it can be coded with table formatting such as spacing, padding, and a border. Close the table with</table>A table with formatting can look something like this:
<table cellspacing="0" cellpadding="0" border="1">. This code would say there is no added spacing or padding, but there is a 1px border around each cell. Tables can be placed inside other tables to create a single cell with a border with inside cells with no borders.
Formatting
<font color="X">is used to change the following text’s basic color. For example<font color="red">will make the text red. Close with</font>when you want the text to return to the default color.<b>is used to make the text bold. Close with</b>.  ;is used to add a permanent space in text. The space between 0 and ; will need to be removed to work. This web page translates the example into a literal space if added without a space breaking the code.<center>is used to make the following text centered in the cell or document. Close with</center>
Pulling Information from XML
Another common code is the <xsl> tag. This tag is used to tell the rest of the code what to do. I think of it as the “logic” rules of the code.
<xsl:value-of select="X" />tells the XSLT code to input the information from a specific location in the XML generated in Alma. For example, the code<xsl:value-of select="notification_data/metadata/title" />will pull the book title from the XML listed at notification_data/metadata/title. Since the tag contains a / it opens and closes itself and does not need a closing tag.<xsl:if test="X='Y' ">For Example,<xsl:if test="notification_data/incoming_request/format='PHYSICAL' ">will only use the code between this opening and closing tag if the Alma generated XML lists PHYSICAL as the variable at notification_data/incoming_request/format. Close with</xsl:if>
Alma Specific Codes
Several codes are specific to Alma and pull information from behind the scenes in Alma. These include things such as Barcodes and Labels.
Barcodes
One of the most important codes for printed Letters are the barcode files. Technically you can use code to make anything a barcode with a barcode font, but those barcodes are often too big to scan with library scanners. Thankfully there are several codes for Alma specific barcode files generated in Alma. The following can be pasted into Letters to generate a barcode:
Item Barcode
The following code will add the barcode of the item received by the Borrowing Library. This is useful for Circulation Staff to check out the item.
<tr>
<td>
<img src="cid:item_id_barcode.png" alt="Item Barcode" />
</td>
</tr>The Resource Sharing Receive Slip Letter uses a different image file for generating the barcode. In that letter use the following code instead.
<tr>
<td>
<img src="cid:Barcode.png" alt="Barcode" />
</td>
</tr>External ID (Full)
The following code will add a barcode for the full External Identifier. This version of the External ID may contain the 01// or 02// prefixes, which may prevent the barcode from scanning properly at the Borrowing Library. This is why this barcode works for articles and book chapters but not shipping items.
<tr>
<td>
<img src="cid:externalId.png" alt="externalId" />
</td>
</tr>External ID (truncated)
The following code will generate the External ID without the 01// or 02// prefixes. The official name of this ID is the Group Qualifier. This code works both at the Lending and Borrowing library and should be used when possible. This barcode is not available in all letters at the moment. Ex Libris will add it to more Letters in a future update.
Internal ID
The following code will add a barcode for the Internal ID. This barcode is important for the article and book chapter paperwork because the scanned or downloaded files need to be saved as the Internal Identifier.