Aeon Alma Primo Catalog Addon

NameAlma Primo Catalog Addon
AuthorAtlas Systems, Inc.
DescriptionA catalog addon designed for libraries that utilize the Alma ILS and Primo as the discovery layer.


This addon is available for developers to modify and extend. Developers are encouraged to submit changes to this addon by forking the git repository from and creating a pull request.



Addon settings are configured in the Manage Addons form.

Catalog URL


The base URL that the query strings are appended to. The Catalog URL structure is "{URL of the catalog}/primo-explore/".

Home URL

StringHome page of the catalog. The Home URL structure is "{URL of the catalog}/primo-explore/search?vid={4 Digit Primo Code}".
Remove Trailing Special Characters
BooleanDefines whether to remove trailing special characters on import or not. The included special characters are "\/+,.;:-=."
Search Priority List
Title, Author

The fields that should be searched on, in order of search priority. Each field in the string will be checked for a valid corresponding search value in the request,

and the first search type with a valid corresponding value will be used. Each search type must be separated by a comma.

Auto Retrieve Items
Defines whether or not the addon should automatically retrieve items related to a record being viewed.
Disabling this setting can save the site on Alma API calls because it will only make a Retrieve Holdings List call when the button is pressed.
StringThe URL to the Alma API
Alma API Key
StringAPI key used for interacting with the Alma API
Primo Site Code

The 4 digit code that identifies the site in Primo Deep Links. It is the code that follows the "vid=" in the Primo-Explorer URL.

Data Mappings

Below are the default configurations for the catalog addon. The mappings within DataMappings.lua are settings that typically do not have to be modified from site to site. However, these data mappings can be changed to customize the fields, search queries, and xPath queries to the data.


Be sure to backup the DataMappings.lua file before making modifications Incorrectly configured mappings may cause the addon to stop functioning correctly. 

Search Types

Default Configuration
Search TypeQuery String
DataMapping.SearchTypes["Call Number"]lsr01
DataMapping.SearchTypes["Catalog Number"]any


The Catalog Number search type performs an any search because Primo does not have a search type for MMS ID.

Source Fields

The field that the addon reads from to perform the search.


Default Configuration
FieldSource TableSource Field
DataMapping.SourceFields["Aeon"]["Call Number"]TransactionCallNumber
DataMapping.SourceFields["Aeon"]["Catalog Number"]TransactionReferenceNumber

Bibliographic Import

The information within this data mapping is used to perform the bibliographic api call. The Field is the product field that the data will be imported into, MaxSize is the maximum character size the data going into the product field can be, and Value is the xPath query to the information.


One may specify multiple xPath queries for a single field by separating them with a comma. The addon will try each xPath query and returns the first successful one.

Example: An author can be inside of 100$a and 100$b or 110$a and 110$b. To accomplish this, provide an xPath query for the 100 datafields and an xPath query for the 110 datafields separated by a comma.


Item Import

The information within this data mapping is used import the correct information from the items grid. The Field is the product field that the data will be imported into, MaxSize is the maximum character size the data going into the product field can be, and Value is the FieldName of the column within the item grid.

Product FieldValueAlma API XML NodeDescription
ReferenceNumberReferenceNumbermms_idThe catalog identifier for the record (MMS ID)
CallNumberCallNumbercall_numberThe item's call number
LocationLocationlocationThe location of the item
LibraryLibrarylibraryThe library where the item is held
ItemNumberBarcodebarcodeThe item's barcode


The Holding ID and Item Description can also be imported by adding another table with a value of HoldingId and Description.

Customized Mapping

The CustomizedMapping.lua file contains the mappings to variables that are more site specific.

Location Mapping

Maps an item's location code to a full name. If a location mapping isn't given, the addon will display the location code. The location code is taken from the location node returned by a Retrieve Items List API call.


CustomizedMapping.Locations["{Location Code }"] = "{Full Location Name}"


How to add or change what information is displayed in the item grid?

There's more item information gathered than what is displayed in the item grid. If you wish to display or hide additional columns on the item grid, find the comment -- Item Grid Column Settings within the BuildItemGrid()function in the Catalog.lua file and change the gridColumn.Visible variable of the column you wish to modify.

How to modify what bibliographic information is imported?

To import additional bibliographic fields, add another lua table to the DataMapping.ImportFields.Bibliographic[{Product Name}] mapping. To remove a record from the importing remove it from the lua table.

The table takes a Field which is the product's field name, a MaxSize which is the maximum characters to be imported into the product, and Value which is the xPath query to the data returned by the Retrieve Bibs Alma API call.

How to add a new Search Type?

There are search types baked into the addon that are not enabled by default. The available search types are listed below.

  • Title
  • Author
  • Call Number
  • Subject
  • ISBN
  • ISSN
  • Catalog Number

To add these additional search types to your addon, open the addon's settings and find the AvailableSearchTypes setting. Add the Search Type's name to the comma-separated list within the value column. Save, refresh the cache, and reopen any item pages that may be open.

The new search type can be added to the addon's default configuration by opening the Config.xml document and find the AvailableSearchTypes setting. Add the Search Type's name to the comma-separated list within the value attribute of the setting. Save the document and reset the product's cache.

How to add a custom Search Type?

Note: Backup the addon before performing this customization. A misconfiguration may break the addon.

First navigate to your primo catalog and go to the advanced search page. On the advanced search page, choose the search option that you wish to add. Search for anything using the chosen search option and look at the URL. Find the part that says "query={Search Type},". Copy the search type (Example: title, creator).

Now that you have the search type, open up the DataMapping.lua file and scroll to the SearchTypes mapping. Copy and paste an existing SearchType mapping. Replace the string on the right side of the equals with your Search Type. Give the search type a name by replacing the string inside the brackets with the name of the search type. (Example: DataMapping.SearchTypes["{Search Type Name}"] = "{searchType}";).

Open up Config.xml and find "AvailableSearchTypes". Add the name of the Search Type to the comma-separated list within the value attribute (be sure to add a comma between search types).

Finally, open Catalog.lua and find the commend that says "-- Search Functions". Copy one of the search functions and paste it at the end of the search functions. Change the function's name to follow this formula; "Search{SearchTypeName}" (Note: remove any spaces from the Search Type Name, but keep casing the same). Within the PerformSearch method call, change the second parameter to be the Search Type Name (unmodified).

Addon Files

Config.xmlThe addon configuration file.
DataMapping.luaThe data mapping file contains mappings for the items that do not typically change from site to site.
CustomizedMapping.luaThe a data mapping file that contains settings that are more site specific and likely to change (e.g. location codes).
Catalog.luaThe Catalog.lua is the main file for the addon. It contains the main business logic for importing the data from the Alma API into the Atlas Product.
AlmaApi.luaThe AlmaApi file is used to make API calls against the Alma API
Utility.luaThe Utility file is used for common lua functions
Regex.luaImports .NET's RegEx into lua
WebClient.luaUsed for making web client requests.