Letters Basics

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 XSL 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. 

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 This link will take you to an external website in a new tab. 

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. The Letter interface has multiple areas you should be familiar with:

• XSL: This is where the code generating the Letter lives. You can edit this code to make the letter do everything from list the request metadata to displaying library logos. This is the main section you will be working in to edit any Alma Letter.
• XML: The XML code is the information supplied by Alma that the XSL pulls from. When a Letter is triggered the unique information from the request or item will automatically be added to an XML file behind the scenes in Alma. This is useful to find what information can be added to the Alma Letter and how to tell the XSL where to find the information in the XML file.
• Example: A visual example of the Letter generated takes up nearly half of the Letters area. This is extremely helpful to know that your code works and does what you want it to do. As you make edits to the XSL code the example will update to reflect the change.
• Labels: In the default Letters you will often see codes beginning and ending with @@ (example: @@title@@). These are Labels and they display whatever you add as the corresponding Description in the Labels table. To access the Labels table click Labels. The templates shared across the CSU do not use most Labels because these customizations cannot be shared, but they can be useful to make local customizations.
• Letter Examples: The Letter Examples page lets you select the most recent XMLs generated for this Letter to use as real world examples. 

When writing XSL 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>. Most opening tags have a closing tag, and 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.

Example: 

• <text>Almost all tags have an opening and a closing tag</text>

A few tags open and close themselves. These tags all end with a / and do not need a specific closeing tag.

Example: 

• <xsl:value-of select="notification_data/metadata/title" />

Common Tags

While there are many, many tags that can be used in XSL, the following are the most commonly used tags in both the default XSL code and the CSU templates:

Rows, Cells, and Table 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 Tags

• <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>.
• <text> is used to add static text that does not change with the XML. Close with </text>.
• <strong> can be used to combine <b> and <text>. A word or sentence between <strong> tags will be bold and static. Close with </strong>.
• &#160 ; 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>

Note Tag

• <!-- is to place a note in the code or disable a section of code. Anything between the opening and closing of this tag will be ignored when the code is run and is essentially invisible outside of the editing view. This is very handy if you want to disable, but not delete, a section of code or leave a note about what a section of code does. Close with -->

Variable Tags

Some tags tell the system to pull information from the XML and place it in the Letter in a specific spot. The information pulled from the XML varies every time the Letter is triggered. The tag is usually a variation of <xsl:X> where X can change depending on if you are selecting information or activating a section of code if certain variables are present. 

• <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>

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.

External ID (Full) Barcode

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.

External ID (Truncated) Barcode

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.

                          <tr>
                             <td>
                                <img src="cid:group_qualifier.png" alt="group_qualifier" />
                             </td>
                          </tr>

Internal ID Barcode

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.