The Ex Libris library community has created a number of different ways to integrate LibKey and the Primo interface, including:

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

These community created code options have been summarized in four different integration options outlined in the below implementation guide.

Step-by-Step Implementation Guide

This guide is intended for Primo administrators who have a basic familiarity with the back office functions of Primo 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

Contact Third Iron at 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.

Step 2: Copy and paste customized scripts into your Customization Package

You will need a few code blobs to successfully install this integration into your Primo Customization Package / Primo VE Customization Package. You will want to be using a plain text editor to do this.

Copy and paste the text below into your Customization Package. Note the PLACEMENT of this code as it goes in the MIDDLE of the function present in this package.

Before saving however, in the pasted text, you will need to customize a few items!

Thus, if you have the default setup like this, please note where the Third Iron code goes below:

(function () {
"use strict";
'use strict';

var app = angular.module('viewCustom', ['angularLoad']);
/****************************************************************************************************/
/*In case of CENTRAL_PACKAGE - comment out the below line to replace the other module definition*/
/*var app = angular.module('centralCustom', ['angularLoad']);*/
/****************************************************************************************************/

/** THIRD IRON CODE GOES HERE **/

})();

You will insert the configuration code right where it says /** THIRD IRON CODE GOES HERE **/

There are a large number of combinations of options available within the configuration script. To simplify installation, we have created a matrix of features to consider as well as pre-configured code snippets to help simplify installation and customization. For ALL of these, you are required to update lines 4, 5 and 32 with your custom information.

Option 1

This is the standard configuration. For additional variations offering unique attributes, see the other options listed.

Configuration name	Best format link presented (PDF preferred) or all formats presented	Link to View Complete Issue for serendipitous discovery in BrowZine?	Minimize duplicate links?	Show link resolver if LibKey link available?	Display Unpaywall non-version of record option?

Configuration name	Best format link presented (PDF preferred) or all formats presented	Link to View Complete Issue for serendipitous discovery in BrowZine?	Minimize duplicate links?	Show link resolver if LibKey link available?	Display Unpaywall non-version of record option?
Option 1	Best format link presented	Yes	Yes	Yes	Yes

// Begin BrowZine - Primo Integration...
  window.browzine = {
  
    libraryId: "XXX",
    apiKey: "ENTER API KEY",
    
    journalCoverImagesEnabled: true,
    
    journalBrowZineWebLinkTextEnabled: true,
    journalBrowZineWebLinkText: "View Journal Contents",
    
    articleBrowZineWebLinkTextEnabled: true,
    articleBrowZineWebLinkText: "View Issue Contents",
    
    articlePDFDownloadLinkEnabled: true,
    articlePDFDownloadLinkText: "Download PDF",
    
    articleLinkEnabled: true,
    articleLinkText: "Read Article",
    
    printRecordsIntegrationEnabled: true,
    showFormatChoice: false,
    showLinkResolverLink: true,
    enableLinkOptimizer: true,
  
    articleRetractionWatchEnabled: true,
    articleRetractionWatchText: "Retracted Article",
    
    articleExpressionOfConcernEnabled: true,
    articleExpressionOfConcernText: "Expression of Concern",
    
    unpaywallEmailAddressKey: "enter-your-email@your-institution-domain.edu",
    articlePDFDownloadViaUnpaywallEnabled: true,
    articlePDFDownloadViaUnpaywallText: "Download PDF (via Unpaywall)",
    articleLinkViaUnpaywallEnabled: true,
    articleLinkViaUnpaywallText: "Read Article (via Unpaywall)",
    articleAcceptedManuscriptPDFViaUnpaywallEnabled: true,
    articleAcceptedManuscriptPDFViaUnpaywallText: "Download PDF (Accepted Manuscript via Unpaywall)",
    articleAcceptedManuscriptArticleLinkViaUnpaywallEnabled: true,
    articleAcceptedManuscriptArticleLinkViaUnpaywallText: "Read Article (Accepted Manuscript via Unpaywall)",
  };

  browzine.script = document.createElement("script");
  browzine.script.src = "https://s3.amazonaws.com/browzine-adapters/primo/browzine-primo-adapter.js";
  document.head.appendChild(browzine.script);

  app.controller('prmSearchResultAvailabilityLineAfterController', function($scope) {
    window.browzine.primo.searchResult($scope);
  });

  app.component('prmSearchResultAvailabilityLineAfter', {
    bindings: { parentCtrl: '<' },
    controller: 'prmSearchResultAvailabilityLineAfterController'
  });
// ... End BrowZine - Primo Integration

Option 2

This configuration is almost identical to Option 1 but should be a considered a more accessible option as it will always show an Article Link option in addition to PDF links as Article Links can commonly have the full text in HTML which is usually more friendly to screen readers than a PDF. Additionally, to reduce the appearance of multiple links this option hides the link resolver. The link resolver menu is still accessible on all records by clicking the article title.

Configuration name	Best format link presented (PDF preferred) or all formats presented	Link to View Complete Issue for serendipitous discovery in BrowZine?	Minimize duplicate links?	Show link resolver if LibKey link available?	Display Unpaywall non-version of record option?

Configuration name	Best format link presented (PDF preferred) or all formats presented	Link to View Complete Issue for serendipitous discovery in BrowZine?	Minimize duplicate links?	Show link resolver if LibKey link available?	Display Unpaywall non-version of record option?
Option 2	All Formats Presented	Yes	Yes	No	Yes

// Begin BrowZine - Primo Integration...
  window.browzine = {
  
    libraryId: "XXX",
    apiKey: "ENTER API KEY",
    
    journalCoverImagesEnabled: true,
    
    journalBrowZineWebLinkTextEnabled: true,
    journalBrowZineWebLinkText: "View Journal Contents",
    
    articleBrowZineWebLinkTextEnabled: true,
    articleBrowZineWebLinkText: "View Issue Contents",
    
    articlePDFDownloadLinkEnabled: true,
    articlePDFDownloadLinkText: "Download PDF",
    
    articleLinkEnabled: true,
    articleLinkText: "Read Article",
    
    printRecordsIntegrationEnabled: true,
    showFormatChoice: true,
    showLinkResolverLink: false,
    enableLinkOptimizer: true,
  
    articleRetractionWatchEnabled: true,
    articleRetractionWatchText: "Retracted Article",
    
    articleExpressionOfConcernEnabled: true,
    articleExpressionOfConcernText: "Expression of Concern",
    
    unpaywallEmailAddressKey: "enter-your-email@your-institution-domain.edu",
    articlePDFDownloadViaUnpaywallEnabled: true,
    articlePDFDownloadViaUnpaywallText: "Download PDF (via Unpaywall)",
    articleLinkViaUnpaywallEnabled: true,
    articleLinkViaUnpaywallText: "Read Article (via Unpaywall)",
    articleAcceptedManuscriptPDFViaUnpaywallEnabled: true,
    articleAcceptedManuscriptPDFViaUnpaywallText: "Download PDF (Accepted Manuscript via Unpaywall)",
    articleAcceptedManuscriptArticleLinkViaUnpaywallEnabled: true,
    articleAcceptedManuscriptArticleLinkViaUnpaywallText: "Read Article (Accepted Manuscript via Unpaywall)",
  };

  browzine.script = document.createElement("script");
  browzine.script.src = "https://s3.amazonaws.com/browzine-adapters/primo/browzine-primo-adapter.js";
  document.head.appendChild(browzine.script);

  app.controller('prmSearchResultAvailabilityLineAfterController', function($scope) {
    window.browzine.primo.searchResult($scope);
  });

  app.component('prmSearchResultAvailabilityLineAfter', {
    bindings: { parentCtrl: '<' },
    controller: 'prmSearchResultAvailabilityLineAfterController'
  });
// ... End BrowZine - Primo Integration

Option 3

This configuration removes display of links to non-version of record copies. Commonly used by corporate libraries and hospitals who often prefer displaying only the version of record.

Configuration name	Best format link presented (PDF preferred) or all formats presented	Link to View Complete Issue for serendipitous discovery in BrowZine?	Minimize duplicate links?	Show link resolver if LibKey link available?	Display Unpaywall non-version of record option?

Configuration name	Best format link presented (PDF preferred) or all formats presented	Link to View Complete Issue for serendipitous discovery in BrowZine?	Minimize duplicate links?	Show link resolver if LibKey link available?	Display Unpaywall non-version of record option?
Option 3	Best Format Link Presented	Yes	Yes	Yes	No

Option 4

This configuration will display all link options and will display duplicate links

Configuration name	Best format link presented (PDF preferred) or all formats presented	Link to View Complete Issue for serendipitous discovery in BrowZine?	Minimize duplicate links?	Show link resolver if LibKey link available?	Display Unpaywall non-version of record option?

Configuration name	Best format link presented (PDF preferred) or all formats presented	Link to View Complete Issue for serendipitous discovery in BrowZine?	Minimize duplicate links?	Show link resolver if LibKey link available?	Display Unpaywall non-version of record option?
Option 4	All Formats Presented	Yes	No	Yes	Yes

Option 5

This configuration option minimizes the number of links to full text that appear

Configuration name	Best format link presented (PDF preferred) or all formats presented	Link to View Complete Issue for serendipitous discovery in BrowZine?	Minimize duplicate links?	Show link resolver if LibKey link available?	Display Unpaywall non-version of record option?

Configuration name	Best format link presented (PDF preferred) or all formats presented	Link to View Complete Issue for serendipitous discovery in BrowZine?	Minimize duplicate links?	Show link resolver if LibKey link available?	Display Unpaywall non-version of record option?
Option 5	Best Format Link Presented	Yes	Yes	No	Yes

Save the

custom.js file with these modifications.

Step 3: Upload and Deploy the modified Customization Package to Primo

With all your changes made, upload the zipped configuration package folder back to the Primo Back Office as described in the Primo Customization Package Documentation / Primo VE Customization Package Documentation and then deploy / save (depending on your version of Primo) to activate your changes in the Primo UI.

Step 4: Testing and Troubleshooting

Your code change should take immediate effect after you have deployed them, but your browser may still be caching old code. To ensure you are seeing the latest changes you made, make sure to do a hard refresh with shift-command-r (Mac) or shift-control-r (PC) in your browser before looking at any further troubleshooting steps!

After trying the above tip, if your BrowZine code is not appearing as described in this document or BrowZine is appearing but has caused your other integrations to STOP working please contact us for assistance and include your custom.js file as an attachment in your email. Thank you!

Implementation Variations

Libraries are invited to consider multiple different approaches to utilizing this API as well as other interactions to get the best use out of the BrowZine Journal Engagement Service:

Link directly to your BrowZine Library if a user clicks on the "Journals A-Z" tab at the top of the Primo interface. Therefore, the primary user experience for journal browsing begins in BrowZine whereas various options to link into BrowZine are still covered by Primo. You can see examples of this in action at University of Birmingham (UK), Charles Sturt University (AUS) and more!
Utilize the External Search API to create a search box on your home page to link a user's journal query directly into BrowZine! If the user's query turns out to not be for scholarly journals but only trade journals or popular ones that BrowZine does not cover, the search is auto-routed back to Primo's A-Z! Live examples of this in action (be sure to select the Journals/eJournals search from the appropriate dropdowns/options) can be see at Rensselaer Polytechnic Institute (USA), College of William & Mary (USA) and more!

Third Iron Technical Documentation

Ex Libris Primo Integration