Primo

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

Overview

The Primo product integration provides students with access to their library account and to search functionality. Currently Alma and Voyager are being implemented as the ILS.

User Experience

The following section describes information relating to the user experience for the Primo product integration.

User Activities

Students can check and manage various activities associated with their library account, such as loans (including renewing), requests (including canceling), saved items (favorites), fines and fees (including linking to payment options, if configured), and personal information.

The user has access to the discovery system search page, making it possible to search the library catalog by either using the embedded search from the App or by linking out to the Primo search page.

The user can save items to a list of favorites from the search pages.

In addition, information about library open hours as well as a page with useful links are available, as configured by the administrator.

Authentication

The Primo product integration requires the user's identifier from the vendor's system. This is obtained with token-based authentication attributes.

The connection to Alma is handled as part of the generic API Configuration under the Alma section. The first part of the API Configuration details the URL to which to connect and any parameters that are required. The second part relates to the API Authentication for the URL.

Authentication against Alma and Primo is made by the API key, which is to be provided when configuring the integration instance.

Authentication against Voyager is based on the VXWS and the XML over HTTP Web Service protocol. The connection is handled via the API Configuration under the Voyager section, where the User Input Identifier parameters are entered.

Offline Support

Library Card data is cached on the user’s device.

Screenshots

The following are examples of screenshots of the Primo product integration user interface for a reference when configuring it:

Home Page - Search	Library Card	Open Hours

Useful Links	Record Details	Search Results

Primo Legacy Live Tile	Primo Live Tile Example of 3 x 2 Dimensions

Live Tile

For the live tile legacy UI, we recommend using the following dimensions for an optimized experience:

1 width x 2 height

The new Primo live tile UI is designed to work with the following sizes. The tile will attempt to display as many elements as possible regardless of the dimensions set, but we cannot guarantee the intended experience if you do not adhere to the following dimensions. The tile dimensions are set in the App Builder, while the widgets per row (and other details) are set in the Configuration page for this product integration.

1 wide x 1 high
- This is a special case. The tile only displays one widget (the highest prioritized, enabled widget).
2 wide x 1 high
- We recommend using 1 - 2 widget rows and using 1 - 3 widgets per row.
2 wide x 2 high
- We recommend using 2 - 3 widget rows and using 1 - 3 widgets per row.
3 wide x 1 high
- We recommend using 1 - 2 widget rows and using 2 - 4 widgets per row.
3 wide x 2 high
- We recommend using 2 - 3 widget rows and using 2 - 4 widgets per row.

We also recommend keeping the header text and widget labels for the live tile short.

Technical Overview

The following section describes technical information for the Primo product integration.

Prerequisites

The following prerequisites are required for the Primo product integration:

The IDP should return the Alma/Voyager ID attribute. The Alma/Voyager ID attribute is a unique ID controlled by the customer that is defined per student and staff member in Alma/Voyager. If you are using CMAuth, this attribute can have any name in the IDP attributes response (from SAML/OAUth/LDAP), but needs to be mapped in the Additional Mapping section of the CMAuth integration profile. If you are not using CMAuth, the Alma/Voyager ID attribute must be returned in the LDAP attributes response. The attribute is configured in the User Input Identifier field in the Alma or Voyager Configuration section of the App Manager configuration.
The new mapping of the authentication token requires users to log out and log in to the app.

For examples of API requests and responses, see the Developer's Network.

For more information concerning Voyager APIs, see the Voyager API section of the Developer's Network.
The Primo and Alma API key requires read-write access.

Configuration

To configure the Primo product integration, select Add Product Integration from the Product Integrations main menu option.

Select Primo.

The following table describes the configuration options available on this page.

Configuration Option

Description

Mandatory

Data Type

Default

Example

Manage Integration

Enable Product Integration

Select to enable the product integration on the user's campusM app.

Checkbox

Unselected

Product Integration Description

A description of the product integration for internal use

Yes

String

Screen Title

The title that appears in the top header of the service

String

Library

My Primo

Vendor – This section defines the structure of the APIs used in this product integration.

Discovery System

Select Discovery System

Yes

String

Primo

Primo API Configuration

URL to retrieve the information

The URL to Primo API Gateway

Yes

String

North America	https://api-na.hosted.exlibrisgroup.com/primo/v1/
Europe	https://api-eu.hosted.exlibrisgroup.com/primo/v1/
Asia Pacific	https://api-ap.hosted.exlibrisgroup.com/primo/v1/

View ID

The View ID of your Primo

Yes

String

API Key

API key to connect with your Primo instance

Yes

String

Tab Name

Required for search functionality

Yes

String

default_tab

Scope Name

Required for search functionality

Yes

String

default_scope

Language Code

The language code of your Primo instance

Yes

String

Select ILS

Select an ILS (Alma or Voyager)

Yes

String

Alma

Alma API Configuration

Base URL to retrieve the information

The URL to Alma Gateway

Yes

String

North America	https://api-na.hosted.exlibrisgroup.com/almaws/v1/
Europe	https://api-eu.hosted.exlibrisgroup.com/almaws/v1/
Asia Pacific	https://api-ap.hosted.exlibrisgroup.com/almaws/v1/

User Input Identifier

Parameter Input Option

Select a parameter input option
(Available options: User Name, Token Property, Constant)

Yes

String

Token Property

Enter the property name to be retrieved from the token ({ USERNAME, MAIL, GIVEN_NAME, SURNAME, FULL_NAME } or as named in the integration profile)

Yes

String

API Key

API key to connect with your Alma instance

String

Voyager API Configuration

URL to retrieve the information

The base URL of your Voyager instance
http://server:port/vxws

Yes

String

User Input Identifier - AuthFactor

AuthFactor Type

Select AuthFactor type: Barcode, Institution Id or Social Security Number

Yes

String

Barcode

Parameter Input Option

Available Options: Token Property or Constant value

Yes

String

Token Property

Token Property Name

Enter the property name to be retrieved from the token ({ USERNAME, MAIL, GIVEN_NAME, SURNAME, FULL_NAME } or as named in the integration profile)

Yes

String

User Input Identifier - Last Name

Parameter Input Option

Select a parameter input option that matches your needs. Available Options: Token Property, Username, Constant Value

If Username is selected, it is not possible to use the Test API Configuration function.

Yes

String

Token Property

Token Property Name

Enter the property name to be retrieved from the token ({ USERNAME, MAIL, GIVEN_NAME, SURNAME, FULL_NAME } or as named in the integration profile)

Yes

String

Display Pin Option

Additional optional identification parameter, carrying the patron’s pin value

Checkbox

False

User Input Identifier - Pin

Parameter Input Option

Select a parameter input option that matches your needs. Available Options: Token Property, Username, Constant Value

Yes (if ‘Display Pin Option’ is set to ‘True’)

String

General

General Parameters

Date Format

The format to display any dates in, throughout the integration

Date/Time

DD MMM YYYY

Currency Display

Prefixed to any currency values displayed in this product instance, unless explicitly shown otherwise

String

Dollar

Blocked User Message

Appears on the Live Tile and the Library Card Screen

String

Account is blocked.

General Error Message

General error message if the page fails to load

String

Please, try again later

Empty Results List Message

Empty Results List message is displayed when the request retrieves no results for Loans, Requests, Fines and Fees, Favorites or Search

String

No Results

'Sort by' Dropdown List Label

Label that appears above the drop-down list on the Loans, Requests, Fines and Fees, Favorites and, Search results pages

String

Sort by

'Sort by' Dropdown List Placeholder

The value displayed before the sorting option is selected on the Loans, Requests, Fines and Fees, Favorites, and Search results pages.

String

Select Sort Option

Primo URL

URL for the Primo search page. It should contain only the Base URL.

String

https://XYZ-primo.hosted.exlibrisgroup.com/

Pages

Home Page

Page Title

Appears at the top of the page

String

My Primo

Display User Library Card Information Bar

Select to display the User Library Card information summary on the Home page screen

Yes

Checkbox

Yes

Place User Library Card Information Bar

Select an option to place the bar on the top or bottom of the page. This option appears if “Display User Library Card Information Bar” is set to "Yes".

Yes

Drop-down Menu

Top

Display User Loans Tab

Appears if “Display User Library Card Information Bar” is set to ‘Yes’

Yes

Checkbox

Yes

User Library Card Information Bar Loans Label

Appears if the “Display User Loans Tab” is set to ‘Yes’

String

My Loans

User Library Card Information Bar Loans Icon

Enter the icon URL to retrieve the icon for ‘Loans’ to change the default value

String

Book Icon

Display User Requests Tab

Appears if “Display User Library Card Information Bar” is set to ‘Yes’

Yes

Checkbox

Yes

User Library Card Information Bar Requests Label

Appears if “Display User Requests Tab” is set to ‘Yes’

String

My Requests

User Library Card Information Bar Requests Icon

Enter the icon URL to retrieve the icon for ‘Requests’ in order to change the default value

String

Bookmark Icon

Display User Fines and Fees Tab

Appears if “Display User Library Card Information Bar” is set to ‘Yes’

Yes

Checkbox

Yes

User Library Card Information Bar Fines and Fees Label

Appears if “Display User Fines and Fees Tab” is set to ‘Yes’

String

My Fines/Fees

User Library Card Information Bar Fines and Fees Icon

Enter the icon URL to retrieve the icon for ‘Fines and Fees’ in order to change the default value

String

Dollar Icon

Display User Favorites Tab

Appears if “Display User Library Card Information Bar” is set to ‘Yes’

Yes

Checkbox

Yes

User Library Card Information Bar Favorites Label

Appears if “Display User Favorites Tab” is set to ‘Yes’

String

My Favorites

User Library Card Information Bar Favorites Icon

Enter the icon URL to retrieve the icon for ‘Favorites’ in order to change the default value

String

Star Icon

Select Library Search Option

Select either ‘Embedded Search’ (search from the App) or ‘Link out’ (link to the Primo page)

Yes

String

Link out

Primo Search Page Link Button Text

Text that appears on the Link Button to the Primo Search Page; appears if “Select Library Search Option” is set to ‘Link out’

String

Go to Primo Search

Search Box Text

Text that appears inside the search box; appears if “Select Library Search Option” is set to ‘Embedded Search’

String

Search…

Display Static Content

Select to display the static content on the Home Page screen

Yes

Checkbox

Yes

Static Content Title

Appears if “Display Static Content” is set to ‘Yes’

String

Static Content Type

Appears if “Display Static Content” is set to ‘Yes’

String

Text

Image URL

Appears if “Static Content Type” is set to ‘Image’, ‘Image (above) and Text’, ‘Text (above) and Image’

String

Text

Appears if “Static Content Type” is set to ‘Text’, ‘Image (above) and Text’, ‘Text (above) and Image’

String

Main Menu Bar

Main Menu Bar Home Page Label

Label for the Home Page tab on the Main Menu Bar

String

Home

Main Menu Bar Library Card Label

Label for the Library Card tab on the Main Menu Bar

String

Library Card

Display Useful Links Tab

Select to display the Useful Links tab on the Main Menu Bar

Yes

Checkbox

Yes

Main Menu Bar Useful Links Label

Label for the Useful Links tab on the Main Menu Bar

String

Useful Links

Display Open Hours Tab

Select to display the library Open Hours tab on the Main Menu Bar

Yes

Checkbox

Yes

Main Menu Bar Open Hours Label

Label for the Open Hours tab on the Main Menu Bar

String

Open hours

Useful Links (Appears if “Display Useful Links Tab” is set to ‘Yes’)

Page Title

Appears at the top of the page

String

Useful Links

Links Group Title

Enter the title for the Links Group

String

Link Title

Enter the Link title

String

Link URL

Enter the Link URL

Yes

String

Open Hours (Appears if “Display Open Hours Tab” is set to ‘Yes’)

Page Title

Appears at the top of the page

String

Open Hours

Link URL

For Voyager only: Open Hours page URL is required

String

http://MyOpenHours.com

Message to be displayed if no information is found

Message to be displayed when no information about open hours for a specific day is found

String

No info

Library Card

Page Title

Appears at the top of the page

String

Library Card

Display User Loans

Select to display user’s loans

Yes

Checkbox

Yes

User Loans Label

Appears if “Display User Loans” is set to ‘yes’

String

My Loans

Display User Requests

Select to display user’s requests

Yes

Checkbox

Yes

User Requests Label

Appears if “Display User Requests” is set to ‘yes’

String

My Requests

Display User Fines and Fees

Select to display user’s fines and fees

Yes

Checkbox

Yes

User Fines and Fees Label

Appears if “Display User Fines and Fees” is set to ‘yes’

String

My Fines/Fees

Display User Favorites

Select to display user’s favorites (Primo saved items)

Yes

Checkbox

Yes

User Favorites Label

Appears if “Display User Favorites” is set to ‘yes’

String

My Favorites

Display User Personal Info

Select to display user’s personal info

Yes

Checkbox

Yes

User Personal Info Label

Appears if “Display User Personal Info” is set to ‘yes’

String

My Personal Info

User Loans

Page Title

Appears at the top of the page

String

My Loans

Items Per Page

Value from 1 to 10

Yes

Number

Display Sort Options

Select to display the sorting options drop-down menu for the user

Yes

Checkbox

Yes

‘Sort’ Button Text

Enter the text for the ‘Sort’ button

String

Sort by

Sort Loans List

Available options: by Date, Title – ASC, Title - DESC

Checkbox options

All checked

Sort Option 'Date' Text

Drop-down menu text to display for the ‘Date’ option

String

Date

Sort Option 'Title-ASC' Text

Drop-down menu text to display for the ‘Title - ASC’ option

String

Title - ASC

Sort Option 'Title-DESC' Text

Drop-down menu text to display for the ‘Title - DESC’ option

String

Title - DESC

'Renew' Button Text

Enter the text for the ‘Renew’ button

String

Renew

'Renew All' Button Text

Enter the text for the ‘Renew All’ button

String

Renew All

Renew Success Message

Message to be displayed when items are successfully renewed

String

Items are renewed

Renew Failed Message

Message to be displayed when one or more items were not renewed; the message is followed by the list of failed loans

String

Renewing failed for the loans:

User Loan Details

Page Title

Appears at the top of the page

String

My Loan

User Requests

Page Title

Appears at the top of the page

String

My Requests

Items Per Page

Value from 1 to 10

Yes

Number

Display Sort Options

Select to display the sorting options drop-down menu for the user

Yes

Checkbox

Yes

‘Sort’ Button Text

Enter the text for the ‘Sort’ button

String

Sort by

Sort Loans List

Available options: by Date, Title – ASC, Title - DESC

Checkbox options

All checked

Sort Option 'Date' Text

Drop-down menu text to display for the ‘Date’ option

String

Date

Sort Option 'Title-ASC' Text

Drop-down menu text to display for the ‘Title - ASC’ option

String

Title - ASC

Sort Option 'Title-DESC' Text

Drop-down menu text to display for the ‘Title - DESC’ option

String

Title - DESC

'Cancel' Button Text

Enter the text for the ‘Cancel’ button

String

Cancel

'Cancel All' Button Text

Enter the text for the ‘Cancel All’ button

String

Cancel All

Cancel Success Message

Message to be displayed when requests are successfully canceled

String

Requests are canceled

Cancel Failed Message

Message to be displayed when one or more requests were not canceled; the message is followed by the list of failed requests

String

Canceling failed for the requests:

User Request Details

Page Title

Appears at the top of the page

String

My Request

User Fines and Fees

Page Title

Appears at the top of the page

String

My Fines and Fees

Items Per Page

Value from 1 to 10

Yes

Number

Display Sort Options

Select to display the sorting options drop-down menu for the user

Yes

Checkbox

Yes

‘Sort’ Button Text

Enter the text for the ‘Sort’ button

String

Sort by

Sort Fines and Fees List

Available options: by Date Added, Type, Amount

Checkbox options

All checked

Display ‘Pay’ Button

Select if you want to configure paying fines option (link out). When selected, the button appears on both ‘User Fines and Fees’ and ‘Fine/Fee Details’ pages.

Checkbox

Sort Option 'Date' Text

Drop-down menu text to display for the ‘Date’ option

String

Date

Sort Option 'Type’ Text

Drop-down menu text to display for the ‘Type’ option

String

Type

Sort Option ‘Amount’ Text

Drop-down menu text to display for the ‘Amount’ option

String

Amount

'Pay' Button Text

Appears if “Display ‘Pay’ Button” is set to ‘Yes’

String

Pay

'Pay' Button URL

Appears if “Display ‘Pay’ Button” is set to ‘Yes’

String

User Fine/Fee Details

Page Title

Appears at the top of the page

String

My Fine/Fee

User Personal Info

Page Title

Appears at the top of the page

String

My Personal Info

Display Name (Last, First, Middle)

Appears at the top of the page

Checkbox

Yes

Display Status

Select to display user’s name

Checkbox

Yes

Display Expiration Date

Select to display user’s status

Checkbox

Yes

Display Contact Details

Select to display user’s expiration date

Checkbox

Yes

User Favorites

Page Title

Appears at the top of the page

String

My Favorites

Items Per Page

Value from 1 to 10

Yes

Number

Display Sort Options

Select to display the sorting options drop-down menu for the user

Yes

Checkbox

Yes

‘Sort’ Button Text

Enter the text for the ‘Sort’ button

String

Sort by

Sort Favorites List

Available options: by Date Added, Title, Author

Checkbox options

All checked

Sort Option 'Date Added' Text

Drop-down menu text to display for the ‘Date Added’ option

String

Date

Sort Option 'Title' Text

Drop-down menu text to display for the ‘Title’ option

String

Title

Sort Option 'Author' Text

Drop-down menu text to display for the ‘Author’ option

String

Author

Remove Item from the List Button Text

Text that appears on the button to remove item from the Favorites list

String

Remove

Search Results

Page Title

Appears at the top of the page

String

Search Results

Initial Load

Number of the initially loaded records; the value should be between 2 and 10

String

Load More Results

Number of the records, loaded on clicking the ‘Load More Results’ Button; the value should be between 2 and 5

String

‘Load More Results’ Button Text

Text for the ‘Load More Results’ Button

String

‘Scope Not Defined’ Error Message

Error Message the end-user gets if the Tab/Scope are not defined or defined incorrectly (see ‘Vendor > Primo > Primo API Configuration section)

String

Search Scope is not defined

Display Availability

Select to display the availability of the records

Checkbox

Yes

Display Availability for Electronic Items Text

Availability statement that will appear for the electronic records

String

Available Online

Link Availability Statement to Primo Home Page (link out) for Physical Items

Select to enable the click on the availability statement for physical items is clickable; NB: clicking the availability statement will result in the Primo home page, as defined in the ‘General > General Parameters’ section

Checkbox

Yes

Display Sort Options

Select to display the sorting options drop-down menu for the user

Checkbox

Yes

Sort Option 'Rank' Text

Drop-down menu text to display for the ‘Rank’ option

String

Rank

Sort Option 'Author' Text

Drop-down menu text to display for the ‘Author’ option

String

Author

Sort Option 'Title' Text

Drop-down menu text to display for the ‘Title’ option

String

Title

Sort Option 'Date-Newest' Text

Drop-down menu text to display for the ‘Date – Newest’ option

String

Date - Newest

Sort Option 'Date-Oldest' Text

Drop-down menu text to display for the ‘Date – Oldest’ option

String

Date - Oldest

Item in Search

Page Title

Appears at the top of the page

String

Record Details

Display Record Material Type

Select to display the material type of the record

Yes

Checkbox

Yes

Display Record Material Type

Material Type Label

Label for the record material type

String

Type

Display Record Title

Select to display the title of the record

Yes

Checkbox

Yes

Title Label

Label for the record title

String

Title

Display Record Author

Select to display the author of the record

Yes

Checkbox

Yes

Author Label

Label for the record author

String

Author

Display Record Publisher

Select to display the publisher of the record

Yes

Checkbox

Yes

Publisher Label

Label for the record publisher

String

Published by

Display Record Publication Date

Select to display the publication date of the record

Yes

Checkbox

Yes

Publication Date Label

Label for the record publication date

String

Publication Date

Display Record Language

Select to display the language of the record

Yes

Checkbox

Yes

Language Label

Label for the record language

String

Language

Display Record System Number

Select to display the system number of the record

Yes

Checkbox

Yes

System Number Label

Label for the record system number

String

System no.

Display Record Format

Select to display the format of the record

Yes

Checkbox

Yes

Format Label

Label for the record format

String

Format

Display Record Contributors

Select to display the contributors of the record

Yes

Checkbox

Yes

Contributors Label

Label for the record contributors

String

Contributors

Display Record Subjects

Select to display the subjects of the record

Yes

Checkbox

Yes

Subjects Label

Label for the record subjects

String

Subjects

Display Record Description and Table of Content

Select to display the description and table of content of the record

Yes

Checkbox

Yes

Description and Table of Content Label

Label for the record description and table of content

String

Description

Display Record ISBN/ISSN

Select to display the ISBN/ISSN of the record

Yes

Checkbox

Yes

ISBN/ISSN Label

Label for the record ISBN/ISSN

String

ISBN/ISSN

Display Record Availability

Select to display the availability statement of the record

Yes

Checkbox

Yes

Availability Statement Label

Label for the record availability statement

String

Availability

Live Tile

Enabled

Select to enable Live Tile

Checkbox

Yes

Design

Select the UI design (new or legacy)

Dropdown

Enable Latest Live Tile Design

General

Refresh Rate

The live tile refresh rate in minutes; must be between 60 and 360

Number

Loading Label Text

The text which is displayed while loading the Live Tile

String

Loading…

Please Login Text

The text that is displayed when the user is not logged in

String

You are not logged into Primo

Live Tile Look and Feel

Badge Color

Select a color for the badge

Yes

Color Code

#cd5c5c

Displayed Items

The Live Tile labels are limited to 20 characters. In some cases, however, such as in Web app with a relatively large number of tiles, when the library tile size is 1x1 or 1X2 (recommended size), a long label text can overlap a badge with numbers; therefore, we recommend that the labels do not exceed 8-12 characters for a label.

Header

Header Text Enabled

Select to display the header on the live tile. If cleared, the text does not appear in the header. If both the header text and the header logo are disabled, the header does not appear.

Boolean

True

Header Text

Set the header text

String

Primo

Header Icon Enabled

Select to display the logo on the live tile. If disabled, the logo does not appear in the header. If both the logo and the header text are disabled, the header does not appear.

Boolean

False

URL for Header Icon

The URL of the image to be used as the logo in the header.

String

Customise Live Tile Header Padding

If enabled, allows you to customise the blank space around the header block. All values have a minimum of 0.

Checkbox

The First Widget(s) Should Display on the Same Row As the Header

If disabled, the first widget row will start below the header.

Checkbox

Yes

Widgets Per Row

This sets the number of widgets to display per row. There is a minimum of 1 and a maximum of 5.

Integer

Charges

Enable

Select to display charges

Checkbox

Yes

Label Text

Label for charges

String

Charges

On Hold Shelf

Enable

Select to display the on hold shelf items

Checkbox

Yes

Label Text

Label for the on hold shelf items

String

On Hold Shelf

Overdue Loans

Enable

Select to display the overdue loans

Checkbox

Yes

Label Text

Label for the overdue loans

String

Overdue

Items Due Back Soon

Enable

Select to display the due back soon items

Checkbox

Yes

Label Text

Label for the due back soon items

String

Due soon

Days before Due Date

The maximum number of days before the due date to be considered an Item Due Back Soon

Number

Always Display Widget Count

If enabled, all widgets display the count even if the count is 0.

Checkbox

Yes

Prioritize Live Tile Items

Priority

This ordered list prioritizes the items that appear on the live tile. The item at the top of the list appears first, while the last item appears last.

Ordered List

Charges
On Hold Shelf
Overdue Loans
Items Due Back Soon

Icons

Use Custom Icons

Select to use custom icons instead of the default live tile icons

Boolean

False

URL

Enter the URLs of custom images for the icons of the various widgets

String

Look and Feel

Primary Theme Color

Select a color for the main elements on the page

Yes

Color Code

#444444

Secondary Theme Color

Select a color for the secondary elements on the page

Yes

Color Code

#6f8ea4