• Primo Integration Overview
  • View Journal Contents to enhance the Journal Search Results in Primo 
  • View Issue Contents to enhance the Article Search Results in Primo
  • Download Now to provide LibKey Direct PDF linking within Primo
  • Read Article to provide LibKey Article Linking within Primo
  • Download PDF / Read Now (via Unpaywall) linking within Primo
• Primo VE Instances
• Step-by-Step Implementation Guide
  • 1) Contact Third Iron Support
  • 2) Copy and Paste the modified scripts into the Customization Package
  • 3) Upload and Deploy the modified Customization Package to Primo
  • 4) Testing and Troubleshooting
• Implementation Variations

Primo Integration Overview

The main purpose of the Primo integration is to enhance the user experience for Primo users by providing context-driven links within the Primo interface as illustrated below and to promote journal engagement.  Below are the two main interactions that are enhanced in Primo using the BrowZine API as well as some implementation variation options.

The Ex Libris Primo Integration code was originally developed in cooperation with Sarah Johnston at St. Olaf College.

"View Journal Contents" to enhance the Journal Search Results in Primo  

This interaction is made possible via our Journal Availability API.  Both the journals covers and the dynamic links are created by the BrowZine API.  You can read more details about what it does here.

(See the interaction described by clicking here)

In contrast to the normal route of "Online Access" which, depending on the source and configuration can take you to a choice between multiple sources, an authentication point and then ultimately one of hundreds of different publisher interfaces, the BrowZine interaction of "View Journal Contents" opens the current issue of that journal in the normalized, publisher-neutral view of BrowZine with an easy to understand and quickly-loading table of contents displayed.

Users can then quickly read the table of contents, link through to specific articles to the best available source automatically or be invited to add the title to "My Bookshelf" which allows for tracking of that title, being alerted about new issues and more.  The user may also explore the "App" link at the top noting that BrowZine is available on multiple devices and fully synchronized across all platforms.  Finally, in the lower right hand corner they are invited to discover more journals like this one by choosing one of the subjects that this title is classified within.

The code itself causes the link into BrowZine to appear dynamically, so only items active and available within BrowZine are shown so there are no dead links!

"View Issue Contents" to enhance the Article Search Results in Primo

This interaction is made possible via our Journal Availability API.  Both the journal covers and the links to BrowZine are made possible by the BrowZine API!  You can read more details about what it does here.

(See the interaction described by clicking here) 

These links are triggered by articles rather than journal results and serve to provide a unique form of serendipitous discovery.  While the user has found a specific article, in one click, the user can be taken to the exact issue and place IN the issue where the article was originally published.

This not only provides a nice pedagogical discussion point about how articles are grouped into issues and journals but also a great serendipitous discovery path to perhaps find other articles in that same issue which may be of interest to the researcher as well as all the advantages of BrowZine outlined above (allowing them to find other journals in their research area, tracking the journal for new articles to be published, a consistent browsing experience, etc.)

Note: When using the general Primo search, both the "View Journal Contents" and the "View Issue Contents" links will appear based on the resulting material (journals or articles).  When using the "Journals A-Z" tab in Primo, only journals are returned so only the "View Journal Contents" interaction occurs.

"Download Now" to provide one-click PDF download to articles in Primo

This feature utilizes LibKey technology to provide one-click access to PDF content held by the library on supported publisher platforms and is part of the BrowZine API.  The main purpose of this function is to provide as fast as possible route for the user to the full text of the article that they discovered within Primo.

This link appears BEFORE the customary "Available Online" link which routes a user to the publisher's site and which may involve looking for the PDF on the article page as well as choosing the appropriate source if a library holds this title in multiple locations.

This link is only displayed if a direct path to PDF is available.

The wording to this integration, like the other features can be modified with the integration code below for localization purposes.  Additionally, this feature is optional and can also be disabled in the integration code.

"Read Article" to provide one-click article linking to articles in Primo

This feature utilizes LibKey technology to provide one-click access to the article-level link on the platform subscribed by the library whenever a PDF version is not available to LibKey.  The main purpose of this function is to provide as fast as possible route for the user to the full text of the article that they discovered within Primo.

This link is only displayed if this integration (articleLinkEnabled) is set to "true".  If your configuration is missing this parameter, the default is set to FALSE for backwards compatibility with older integration configuration scripts.

The wording to this integration, like the other features can be modified with the integration code below for localization purposes.  Additionally, this feature is optional and can also be disabled in the integration code.

"Download PDF/Read Article (via Unpaywall)" to provide one-click Open Access article linking to articles in Primo via Unpaywall

If an article is not available via the open access or subscribed content access knowledge of LibKey, the Primo integration of LibKey Discovery also checks Unpaywall for additional open access discovery.

To turn this feature on, be sure you are using the latest version of the integration code posted below and have put in a custom email address in the configuration script as this is requested by the developers on Unpaywall.

There is separate wording for whether the article is available from the publisher site versus being an "accepted manuscript" copy that is held (usually) in a repository.

The wording to this integration, like the other features can be modified with the integration code below for localization purposes.  Additionally, this feature is optional and can also be disabled in the integration code.

Primo VE Instances

For this particular integration, the configuration instructions are the same for Primo VE instances as they are for standard Primo instances. While there are some UI differences in the interface, the Third Iron integration code is identical for both Primo and Primo VE instances. The step-by-step implementation guide below contains links to the respective Primo/Primo VE documentation where applicable, for reference.

Step-by-Step Implementation Guide

This guide is intended for Primo administrators with a basic familiarity with the back office functions of Primo but with little programming/scripting experience or knowledge or for those simply wanting to implement this integration quickly.  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 and simply let us know that you are a Primo library and would like to use this integration.  In response, we'll contact you with your BrowZine Library ID and BrowZine API Key.  You'll need this 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.

1) 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.

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

Thus, if you have the default setup like this....

(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']);*/
/****************************************************************************************************/

})();

You will insert the default code that looks like the below right after the commented out area.

// Begin BrowZine - Primo Integration...
  window.browzine = {
    api: "https://public-api.thirdiron.com/public/v1/libraries/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,

    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

And then Customize with your Library ID (where "XXXX" is) and your API Key where it says "ENTER API KEY".

Additionally, please insert a unique email address for use of the Unpaywall API as this is requested by the developers of Unpaywall.

Thus, for library "222" and your API key is d690efde-2f6f-124b-z87b-8df112f4f42f your final code will look like this:

(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']);*/
/****************************************************************************************************/

// Begin BrowZine - Primo Integration...
  window.browzine = {
    api: "https://public-api.thirdiron.com/public/v1/libraries/222",
    apiKey: "d690efde-2f6f-124b-z87b-8df112f4f42f",

    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,

    unpaywallEmailAddressKey: "melvil.dewey@greatuniversity.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

})();

3) 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

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:

1. 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!
2. 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!