These instructions are for the NDE version of Primo. If you are not currently using NDE but are still using the “New interface” of Primo/Primo VE please see the appropriate instructions for setup in that interface here. When you are ready to move to NDE, you can use the same API Key previously issued to your library in NDE and can use it in NDE and your current version of Primo at the same time. This will not cause any conflicts in operation for either interface.

Unsure where your API Key and Library ID are? You can find them in your CURRENT Primo integration configuration code which will be listed within the script in this manner:
….
libraryId: "XXXXX",

apiKey: "XXXXXXXXX",

….

Key aspects of the community-informed integration of LibKey into Primo include:

One-click to PDF and/or HTML articles from hundreds of publishers and aggregators
Extending BrowZine cover images to display in the citation record
Link from the citation record to the full journal issue in BrowZine
Link to the journal current issue in BrowZine
Indicating retracted article status
Indicating expression of concern status
Providing “Request PDF” links for document delivery with Article Galaxy Scholar
Links that resolve to indicate a second order retraction status

These different elements are optionally available so that libraries can customize their installation to work best for their community. There are five different recommended setup options to help guide libraries to a combination of features that is appropriate for them, but feel free to mix and match as you see fit!

Why Beta?

This is a brand new integration in a new environment and as such is being rolled out slowly to organizations interested in testing this in NDE.

There are a handful of known issues/bugs/shortcomings to be aware of:

Presently there is no support for multi-campus organizations (The NDE approach to add-ons does not allow the same add-on to be loaded multiple times with different configuration scripts attached to them which would be required for LibKey). (Ex Libris has been notified and we are awaiting for a solution/work around for this)
The link to BrowZine is presently first instead of second for Journal records. The BrowZine button should come AFTER the Alma button just like it does in Primo VE. (This is being corrected by Third Iron).
Some libraries have reported issues with incorrect links being built for “Available Online/Other Online Options” buttons that link back to the Alma full record. (This is being investigated by Third Iron as it seems library-dependent when this occurs so there could be a unique local Alma setting causing this).

Additionally, there are presently not recommended ways to customize or localize the labels that appear beyond the default English but if would like to try out the current (though not necessarily final approach to doing this customization of the labels please follow the instructions over in the github documentation here.)

Step-by-Step Implementation Guide

This guide is intended for Primo/Alma administrators who have a basic familiarity with Alma but with little programming/scripting experience or knowledge, or for those simply wanting a quick way to complete an integration. For advanced users, you are welcome to skip right to the this github repository with all necessary files and quick instructions.

Step 1: Contact Third Iron Support

Please contact support@thirdiron.com to let us know you are a Primo library and would like to integrate LibKey. In response, we will send your your library’s BrowZine Library ID and BrowZine API Key needed for Step 2.

If you already have an API Key for an old version of Primo and are upgrading, you can continue to use that one.

Step 2: Prepare your Content Security Policy (CSP) in Alma

You will need to include: *.thirdiron.com in the “allowed list additions” are of the CSP Header Configuration (to object-src, worker-src and script-scrc areas). More information from Alma documentation about this area of Alma.

Step 3: Customizing the JSON configuration file

The first thing to decide is which VIEW OPTION makes the most sense for your library and its users. This is a new option available in Primo NDE which was not available in the Primo VE integration. We did this in recognition of the new design language that Ex Libris introduced with NDE (what we call below “The Stack” - meaning the drop down of content access links that appears within the interface).

We provide three basic view options that effect the LibKey button arrangement:

"Stack + BrowZine Link"
This version fully embraces the new “Stack” concept of link minimization in NDE by putting the “one click” link front and center with additional linking options available in the drop down arrow. LibKey Links would take precedent over Alma QuickLinks whenever they may both exist. The BrowZine View Issue Contents link appears separate since it serves a different purpose then immediate content access.
Set in the config JSON file with: "viewOption": "stack-plus-browzine",

"Single Stack"
This version puts all LibKey and Alma generated links under a single stack. Effectively the only difference between this and the above option is that the BrowZine View Issue Contents appears with the links to content.
Set in the config JSON file with: "viewOption": "single-stack",

"No Stack"
With this arrangement we recommend turning off the link resolver when LibKey can create links as leaving it on can result in duplicate linking since Alma will generate a “stack” of links via a drop down menu off to the right which could be confusing.
Set in the config JSON file with: "viewOption": "no-stack",

As you’ll see in step 3 there is a small JSON file that needs to be created in a text editor. Here are some default values to get started during this BETA period for the add-on with recommended settings.

We will be revisiting this area after the beta period to showcase a number of suggested options for configuring the add on, but with the value names alone and consulting the documentation for the old version here you can probably quickly piece together what each setting means. The below configuration though is a great default to get started and to tweak from there as desired.

Fill in your LibKey Library ID and API Key, along with your Unpaywall Email Address. Save this file as:

libkey_nde_config.json

Update the other boolean configuration values as needed:

  {
    "apiKey": "your-libkey-api-key",
    "libraryId": "your-libkey-library-id",
    "viewOption": "stack-plus-browzine",
    "unpaywallEmailAddressKey": "your-unpaywall-email-address",
    "journalCoverImagesEnabled": "true",
    "journalBrowZineWebLinkTextEnabled": "true",
    "articleBrowZineWebLinkTextEnabled": "true",
    "articlePDFDownloadLinkEnabled": "true",
    "articleLinkEnabled": "true",
    "printRecordsIntegrationEnabled": "true",
    "showFormatChoice": "false",
    "showLinkResolverLink": "true",
    "enableLinkOptimizer": "true",
    "articleRetractionWatchEnabled": "true",
    "articleExpressionOfConcernEnabled": "true",
    "problematicJournalEnabled": "true",
    "articlePDFDownloadViaUnpaywallEnabled": "true",
    "articleLinkViaUnpaywallEnabled": "true",
    "articleAcceptedManuscriptPDFViaUnpaywallEnabled": "true",
    "articleAcceptedManuscriptArticleLinkViaUnpaywallEnabled": "true"
  }

Step 4: Creating and Configuring the Add-on

New for NDE, Ex Libris has added an official “Add-on” area to simplify the installation and maintenance of integrations designed for Primo NDE. To find this area, follow these breadcrumbs after logging into your Alma administrator area:

Configurations → Discovery → (Other) Add-on Configuration:

Then, click Add Row:

The resulting Edit Add-on Configuration screen prompts you to input a few key details to enable the add on.

1 = Defaulted to checked, this will allow the add-on to turn on immediately after you complete the needed fields and click the save button in the upper right hand corner. Come back to edit your add on and uncheck if you want to temporarily disable it.

2 = Select which view(s) in Primo you want to apply the integration into. The default is “All”.

3 = Provide the Add-on Name: LibKey

You must use the name “LibKey” to ensure proper function of the add on! This name is CASE-SENSITIVE (i.e. “libkey” will not work)

4 = This is the URL where the integration’s code is living. The URL for the LibKey Add on is located here: https://thirdiron-adapters.s3.amazonaws.com/primo-nde/production/

Advanced: If you have forked github repo and created your own variant of course you’ll want to use that deployed URL here instead.

5 = Click the folder icon to search your filesystem for the JSON format Add-on Configuration file you created in the previous step. Once selected, click “Upload” to upload it.

If all went well you’ll get a positive blue message indicated that you uploaded successfully. To complete the setup make sure you hit SAVE.

Step 5: Test!

Visit Primo in a view that you enabled the add-on for and observe that there are LibKey generated links present on article records. If your initial search does not yield good results, make sure to limit to “articles” or try a more “scholarly” topic as LibKey is focussed on DOI bearing materials.

If you run into any trouble, please reach out to our support team at support@thirdiron.com for assistance!