ILLiad Alma Primo Definitive Catalog Addon (WebView2 & Chromium)

Owned by Andrew Morgan
Last updated: Jul 29, 2024Version comment
5 min read

This addon will use the WebView2 browser in ILLiad. v9.2.5+, and the Chromium browser otherwise.

Name

Alma Primo Definitive Catalog Addon

Version

1.2.2

Author

Atlas Systems, Inc.

Description

Catalog Search and Import Addon that uses Alma as the catalog and Primo or Primo VE as the discovery layer.

Custom Fields Support

No

Download

The addon is developed to support Alma Catalogs that use Primo or Primo VE as its discovery layer in Aeon, Ares, and ILLiad.

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 GitHub and creating a pull request.

Release Notes

Release notes are available for Alma Primo Definitive Catalog Addon v1.0.2 and later. Note that v1.1.0 is the initial release of the addon for use with ILLiad.

v1.2.1:

  • Added support for XPath expressions containing commas when configuring bibliographic import fields in DataMapping.lua. In support of this change, the default XPath expression used in DataMapping.lua to perform the bibliographic import for the Author fields was updated from multiple expressions using commas to a single “or” expression.

v1.2.0:

  • Added support for use with Ares. The DataMapping.lua addon file has been modified to specify which data mapping settings are used with Ares installations. See the Data Mapping section below for more information on this file.

v1.1.0:

  • Added support for use with ILLiad. The DataMapping.lua addon file has been modified to specify which data mapping settings are used with Aeon installations vs. ILLiad installations. See the Data Mapping section below for more information on this file.

v1.0.2:

  • Replaced the addon's page watcher and page handler with a functionally equivalent .NET timer that runs the page handler function on a three-second interval to mitigate potential issues with the prior functionality.

Configuration

Addon settings are configured in the Manage Addons form.

Setting

Default

Type

Description

Setting

Default

Type

Description

CatalogURL

 

String

The base URL that the query strings are appended to. The Catalog URL structure is {URL of the catalog}/primo-explore/ for Primo or {URL of the catalog}/discovery for Primo VE.

HomeURL

 

 

The Home URL structure is {URL of the catalog}/primo-explore/search?vid={4 Digit Primo Code} for Primo or {URL of the catalog}/discovery/search?vid={4 Digit Primo Code} for Primo VE.

AutoSearch

True

Boolean

Defines whether the search should be automatically performed when the form opens.

RemoveTrailingSpecialCharacters

True

Boolean

Defines whether to remove trailing special characters on import or not. The included special characters are " \/+,.;:-=.".

Examples: Baton Rouge, La., becomes Baton Rouge, La.

AvailableSearchTypes

Title, Author

String

The types of searches your catalog supports. The types in this list must each have a corresponding entry configured in DataMapping.SearchTypes.

SearchPriorityList

Title, Author

String

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. Each search type must have a corresponding value in the AvailableSearchTypes setting and configured in DataMapping.SearchTypes.

AutoRetrieveItems

True

Boolean

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.

AlmaAPIURL

https://api-na.hosted.exlibrisgroup.com/almaws/v1/

String

The URL to the Alma API. The API URL is generally the same between sites. (ex. <https://api-na.hosted.exlibrisgroup.com/almaws/v1/)> More information can be found on Ex Libris' Site.

AlmaAPIKey

 

String

API key used for interacting with the Alma API.

PrimoSiteCode

 

String

The code that identifies the site in Primo Deep Links.

Ex: vid={PrimoSiteCode}.

IdSuffix

 

String

The last four digits of MMS IDs and IE IDs for your institution. This setting is required and should not be left blank.

Buttons

Back

Navigate back one page.

Forward

Navigate forward one page.

Stop

Stop loading the page.

Refresh

Refresh the page.

New Search

Goes to the home page of the catalog.

Search Buttons

Performs the specified search on the catalog using the contents of the specified field.

Retrieve Items

Retrieves the holding records for that item.

Note: This button will not appear when AutoRetrieveItems is enabled.

Import

Imports the selected record in the items grid.

Data Mapping

The mappings within DataMapping.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. Instructions for modifying each section of the DataMapping.lua file can be found in comments above the section in the file itself.

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

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}"

Developers

The addon is developed to support Alma Catalogs that use PrimoVE as its discovery layer in Aeon, Ares, and ILLiad.

Atlas welcomes developers to extend the addon with additional support. All pull requests will be merged and posted to the addon directories.

Addon Files

  • Config.xml - The addon configuration file.

  • DataMapping.lua - The data mapping file contains mappings for the items that do not typically change from site to site.

  • CustomizedMapping.lua - The a data mapping file that contains settings that are more site specific and likely to change (e.g. location codes).

  • Catalog.lua - The 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.lua - The AlmaApi file is used to make the API calls against the Alma API.

  • Utility.lua - The Utility file is used for common lua functions.

  • WebClient.lua - Used for making web client requests.

  • CatalogLayout_Browse_Chromium.xml - Used to load the browse layout (when the item grid is not visible) in the Chromium browser.

  • CatalogLayout_Browse_WebView2.xml - Used to load the browse layout (when the item grid is not visible) in the WebView2 browser.

  • CatalogLayout_Import_Chromium.xml - Used to load the import layout (when the item grid is visible) in the Chromium browser.

  • CatalogLayout_Import_WebView2.xml - Used to load the import layout (when the item grid is visible) in the WebView2 browser.

  • OnFormClosing.elf - Used to ensure the page watcher timer is stopped upon closing the request form. This file is encrypted and not available to modify.