Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Information needed to add a library's collections to SimplyE

Note
titleStatus: Draft

This document is currently undergoing revision. Feedback welcome.


Table of Contents

Table of Contents

Anchor
introduction
introduction
Introduction to SimplyE

A public library may get electronic content from a variety of sources: Overdrive, Bibliotheca, Axis 360, One Click Digital, the public domain, and so on. Currently, patron access to these different collections is gated by different mobile applications. Since patrons have a limited tolerance for installing and learning new mobile apps, a lot of valuable (and expensive) content gets ignored. This also makes it impractical for libraries to purchase content from too many sources, even when it might make sense for other reasons (price, selection, etc.).
SimplyE unifies access to many sources of electronic content in a single mobile interface. Patrons locate their local library, authenticate with their library credentials, search and browse a unified catalog of available content, borrow material, and consume it, all in a single app.
Your system libraries do not have to set up any servers or administer the SimplyE software themselves: 3rd party vendors like Deloitte Digital (aka Day1 Solutions), WebQEM or Datalogics can take care of that for you if you prefer to outsource these such operations and application hosting and management. However, getting a library onto SimplyE requires that the library volunteer a lot of information about itself. This document is a checklist for that information.
Note: "SimplyE" and "Library Simplified" are three different names for the same technology. It is currently undecided what name will be shown to your library patrons. For purposes of this document I'll use "SimplyE" to describe the mobile application as well as the overall system. However, when asking vendors for information it may be safer to refer to the system as "Library Simplified". I'll mention this whenever it's likely.

Anchor
audience
audience
Intended Audience

This document is intended for the person at a library or library consortium who is responsible for getting the library or consortium onto the SimplyE system. This person must be able to represent their library/consortium to outside vendors (such as Overdrive), and must be able to locate technical information about the library/consortium's systems, such as their ILS.

Anchor
whatweneed
whatweneed
What We Need from You


This document contains two forms at the end. If you represent a library or library consortium, make a copy of this document and fill out the forms as best you can. Send the completed document to the vendor setting up the services for you. The vendor will follow up if we need any more information or if we encounter a problem.
If you represent a library consortium, it may be more efficient to assemble the answers to this questionnaire into a spreadsheet, rather than creating twenty or thirty copies of the questionnaire.
If you are setting up the Library Simplified circulation manager yourself, you will be entering all of this information into the administrative interface yourself.

Anchor
journey
journey
A Patron's Journey

When a patron first starts up the SimplyE application, they will be asked to choose their local library. The patron will be shown a list of participating libraries near their current location (as determined by IP address geolocation). The patron will also be able to search for their ZIP code or city to find participating libraries that serve their area.
At this point the patron is interacting with the library registry, a server-side piece of software that knows a lot about the geography of your state and the libraries that participate in the SimplyE program.
Once the patron chooses a library, they are handed off to another piece of software, the circulation manager. The circulation manager is configured especially to serve the patrons of one specific library or library consortium. The circulation manager shows that library's patrons a unified catalog of all content available from that library.
When a patron tries to borrow a book, they're asked for their library credential. This credential is validated against the ILS system of that patron's library. If validation is successful, the circulation manager in SimplyE initiates a loan with the original provider of the content (Overdrive, OneClick, etc.), on behalf of the patron and that library. SimplyE then delivers the content to the patron's device.
Once the content is on the patron's device, they can open it in an integrated reader. When they're done reading, they can return the content via the same mobile application they used to read it.

Note: The library registry is in development. Currently patrons choose their library from a static list that does not take geography into account.

 

Anchor
registry
registry
What we need to know - Library registry


This is the information we need to help your patrons find their library among all the libraries in your state. This information is recapitulated in a form at the end of this document. That's the form we'd like you to fill out.
If you represent a library consortium, we need this information for each individual library.

...

  • A short description explaining who the library serves. This helps patrons distinguish between libraries that may have similar names or that aren't named after their service area. In most cases this can be something simple like: "Serving Newtown, CT."
  • Your library's logo, if you have one. This will be shown in search results. The logo must be in PNG format, 135 by 135 pixels square.
  • Highlight color. If your library uses a particular color scheme, SimplyE can be configured to use a similar color scheme when a patron is interacting with your library. If you do not choose a color, SimplyE will display your collection using a neutral grey color scheme.
  • Some libraries have online sign-up forms that allows patrons to get a library card automatically, without going into a branch library. If you have a sign-up form like this, provide the URL.

 

Anchor
circmanager
circmanager
What we need to know - Circulation manager

The circulation manager has a tougher job than the registry. The registry is like the phone book--it helps your patrons find you. The circulation manager is more like the library itself: it needs to be able to carry out actions on behalf of your patrons.
The library registry needs information that's pretty easy to look up, but the circulation manager needs information you might not even know. The circulation manager needs access to systems that may have been set up by someone who no longer works at your library.
The good news is that if your library has an Overdrive account, it's a guarantee the information is out there. Someone at your library had to go through a similar process to this when you set up your Overdrive account. The same is true if your library has a Bibliotheca or Axis 360 account. We can't get all this information directly from the vendors, but we can help you look for it at your library.
Again, if you represent a library consortium, we need this information for each library in the system. There's no guarantee that every library in a consortium uses a common ILS, for example. (If you do, then that's great--say so! But it might not be true.)
Like the library registry information, this information is recapitulated in a form at the end of this document. That's the form we'd like you to fill out.

  • A point of technical contact at the library (or consortium), so we can get your help while troubleshooting.

 

  • The patron authentication mechanism. If a patron says their barcode is "12345", how do you know whether that's a real barcode? If you do this with an ILS, we need to know the brand of ILS you use. We also we need to have credentials to an API that allow us to validate patrons against the ILS, and get basic information such as whether the patron's card has expired. (This is a very complicated issue that has its own section below.)

...

A patron may authenticate using any of these identifiers, and all four must
identify the same patron record.
If anything like this is going on in your ILS, we need to know about it, so we can
authenticate your patrons no matter which identifier they use to log in. We need to know
which fields in an ILS record might contain alternate identifiers for patrons.  

Anchor
ilses
ilses
ILS Systems

Detail: {+}https://github.com/NYPL-Simplified/Simplified/wiki/AuthenticationSetup+
Different libraries have different ways of authenticating patrons. For most libraries, the simplest thing to do is to find an answer to this question:
How does Overdrive communicate with my ILS?
Most libraries have an Overdrive account. Before loaning out a book, Overdrive has to communicate with your ILS to verify that a patron has provided the right credentials, and that their card is not expired or blocked (e.g. due to unpaid fines). Your library's SimplyE circulation manager needs to do exactly the same thing. If you got it set up with Overdrive, you can use the same strategy to set up a circulation manager.
If your library set up its Overdrive account a long time ago, you may not remember how it was set up, and the person who set it up might not work at the library anymore. If you're not sure, file a support request with Overdrive and ask them how Overdrive communicates with their ILS. It's easy for them to check.
Once you have this information, find your ILS on the list below and follow the directions to gather the information necessary to connect the Library Simplified circulation manager to your ILS. Your vendor will need this information. Remember, if you got it to work with Overdrive, you can get it to work with SimplyE.
If you don't have an Overdrive account, you probably won't have a precedent for what you need to do here. You'll need to decide how the Library Simplified circulation manager should connect to your ILS. Find your ILS on the list below to read about your options.

Anchor
triplei
triplei
Triple I (III)

Anchor
sierra
sierra
Sierra

The Sierra ILS offers two APIs that can be used to connect a circulation manager to a Sierra installation:

...


The names can get confusing. The Millenium Patron API is a "REST API" provided by Sierra, but it is not the product called the "Sierra REST API". The PatronIO SOAP API is an API for dealing with patrons, but it is not the product called the "Millenium Patron API". The Millenium Patron API is not "The III Patron Update Service" or "The My Millenium Service".
The first step in connecting a circulation manager to your Sierra ILS is to figure out which API to use. You're probably using one of them already--this is how Overdrive communicates with your ILS. When in doubt, file a support request with Overdrive and ask them how Overdrive communicates with your ILS to provide ebook service.
Because of a history of confusion on this topic, I'm using very precise terms in this section. But the Overdrive support representative may not use precise terms. If they say "SIP" or "SIP2" then you should do the integration with SIP2. If they say "the REST API" or "the patron API" or anything that doesn't sound like "SIP", you should do the integration with the Millenium Patron API.

Anchor
millenium
millenium
The Millennium Patron API

Detail: {+}https://github.com/NYPL-Simplified/Simplified/wiki/Millenium+
Millennium Patron API URLs tend to look like this:

...


We'll want to use the HTTPS URLs (which tend to include port 54620), since the circulation manager will probably be calling out to your ILS across the public Internet. If you don't have an HTTPS version of the Millennium Patron API, file a support request with III and ask for one.
Because you don't want random people to be able to check patron PINs and look at patron records, access to the Millennium Patron API is most likely restricted only to the specific IP addresses that need it. (This is a good thing to check, actually. If your library offers public wifi, get on the wifi and try to access the URL for the Millennium Patron API. You should not be able to connect!)
Since your SimplyE circulation manager will probably be hosted outside your library's internal network, the circulation manager will need to be whitelisted. Once you have an IP address for your circulation manager (Day1 will provide this), your network administrator will need to whitelist that IP address for access to the Millennium Patron API. Again, your library probably went through a similar process when setting up Overdrive, though the person who set it up may no longer work with you.

Anchor
evergreen
evergreen
Evergreen

Evergreen ILSes use a well-understood variant of SIP2 (see below).

Anchor
sirsi
sirsi
SyrsiDynix

Anchor
symphony
symphony
Symphony

Symphony has an API that we believe can be used to do a circulation manager integration. However, this has not been tested. As a fallback we should be able to do integrations through SIP2 (see below).

Anchor
horizon
horizon
Horizon

Integration with Horizon should be done through SIP2 (see below). However, this has not been tested, and nothing is known about the Horizon variant of SIP2.

Anchor
koha
koha
Koha

Integration with Koha ILSes should be done through SIP2 (see below). However, this has not been tested, and nothing is known about the Koha variant of SIP2.

Anchor
overdriveauth
overdriveauth
Direct Overdrive Integration

Some libraries don't use an ILS at all, and just send lists of valid barcodes to Overdrive so their patrons can get Overdrive books. We should be able to get this to work, but we do not yet have a working example to test with, so you might be the guinea pig.

Anchor
sip2
sip2
SIP2

SIP2 is the default choice. Almost all library ILSes support SIP2. However, not all libraries use SIP2 to conduct transactions, and different ILSes support different variants of SIP2. If you are the lucky first library to integrate with SimplyE using your brand of ILS, NYPL will need to run some experiments to learn about the variant of SIP2 your ILS uses.
For any SIP2 server (experimental or not) we will also need to know the following information:

...


Because you don't want random people to be able to check patron PINs and look at patron records, access to the SIP2 server is most likely restricted only to the specific IP addresses that need it. (This is a good thing to check, actually. If your library offers public wifi, get on the wifi and try to telnet into the SIP2 server. You should not be able to connect!)
Since your SimplyE circulation manager will probably be hosted outside your library's internal network, the circulation manager will need to be whitelisted. Once you have an IP address for your circulation manager (Day1 will provide this), your network administrator will need to whitelist that IP address for access to the SIP2 server. Again, your library probably went through a similar process when setting up Overdrive, though the person who set it up may no longer work with you.

Anchor
otherils
otherils
Other Systems

If your ILS is not on this list, or if it is on the list but we don't know how it works, then we need to work something out. Get in touch with Leonard Richardson (leonardrichardson@nypl.org) and let's talk about the ILS you use. In most cases the answer will be "use SIP2", but we'll need to run some experiments to see which flavor of SIP2 your ILS uses.
When working this out, it will be useful to have on hand:

  • Connection information for any SIP2 server you are running. (see the "SIP2" section for details)
  • Any API or Web Service documentation provided by your ILS vendor.
  • Information about how Overdrive, Bibliotheca or Axis 360 currently validate your patrons (assuming you currently have accounts with any of those vendors).

Anchor
distributors
distributors
Distributors

Anchor
overdrive
overdrive
Overdrive

You'll need to apply for API access on behalf of your library. You can do this when you apply for an Overdrive developer account. (https://developer.overdrive.com/application)
If you already have an Overdrive developer account, then go to the Overdrive Member Center ({+}https://developer.overdrive.com/member-center+), log in, and apply for API access through there.
When you apply, you'll be asked which API you want access to. Ask for access to all three. You will probably only need two of the three, but the approval process is slow, it doesn't cost anything extra to get all three, and you won't have to go back and re-apply if your situation changes.
Under "Planned API usage", mention the name of your library and that you are integrating your Overdrive collection into the SimplyE system.
It can take a week or more to get approved for API access, so don't put this off!

Anchor
bibliotheca
bibliotheca
Bibliotheca


Send an email to the Bibliotheca support address (cloudsupport@bibliotheca.com) from an email account associated with your library. Mention the full name of your library and the mailing address. Ask for your library ID, account ID, and account key. Be sure to mention that this is for "Library Simplified" (they don't know what SimplyE is).

Anchor
axis360
axis360
Axis 360/Baker & Taylor

Send an email to the Axis 360 support address (TBD) from an email account associated with your library. Mention the full name of your library. Ask for a username, password, and library ID that can be used with the production Axis 360 API. Be sure to mention that this is for SimplyE.

Anchor
rbdigital
rbdigital
RB Digital

Send an email to Leonard Richardson (leonardrichardson@nypl.org) and ask for a RB Digital partner token for your library. Leonard will get in touch with RB Digital and get back to you with a partner token which you can use to configure your RB Digital collection.

Anchor
classics
classics
Instant Classics

NYPL maintains a collection of about 5000 high-quality public domain titles. Access to these titles is free to your patrons and unlimited. If you want these books integrated into your collection, just mention this when you fill out the form and One Click will make sure they're included.
You can see the available titles by installing the SimplyE mobile app and choosing "The SimplyE Collection" as your library. This collection includes the 5000 Instant Classics titles, made available to anyone without a library card. The question here is whether you want these titles integrated into your collection so that your patrons can borrow them without having to switch over to "The SimplyE Collection".

Anchor
regform
regform
The Form: Library Registry


Name of library:
Alternate names:
Description:
Point of technical contact:
Library web page:
Coverage area:
(City names are preferred, but ZIP codes are also fine.)
Logo:
(Copy and paste)
Highlight color:
Online patron sign-up URL:

Anchor
circmanform
circmanform
The Form: Circulation Manager

Anchor
_qbmk35qho2uq
_qbmk35qho2uq
Administrative Interface

How do we make sure that only employees of your library can access the administrative interface?
[ ] Don't bother. I'll create accounts for the administrative interface as I need them.
[ ] Ask people to log in to their library Google account to prove they're library employees.
If you check this, enter the G Suite/Google Enterprise managed domain here:
[ ] Look up people in an LDAP server to prove they're library employees.
If you check this, enter the name of the LDAP server here:
[ ] This is theoretically possible, but none of the ways mentioned above will work.
If you check this, explain how this should work here:

Anchor
_h0thvtg8za6n
_h0thvtg8za6n
Sample patron credentials


Patron with borrowing privileges:
Patron with expired card:
Patron with excessive fines:
Patron blocked for some other reason:
Patrons that illustrate library-specific policies:

Anchor
_xl8jwi2qo1wt
_xl8jwi2qo1wt
ILS credentials


Name of ILS product:

Anchor
_h28f6sjzkaux
_h28f6sjzkaux
Sierra connection credentials

Millennium Patron API connection URL:
(This should look something like this: https://mylibrary.iii.com:54620/PATRONAPI/)
(Note: a string that looks like "f58u11mXiFXti2uMbxLiXSw-jMxT7WRw" is probably a credential for the Sierra REST API. This API cannot be used to integrate SimplyE with a library's Overdrive collection. You'll need to use either SIP2 or the Millennium Patron API.)

Anchor
_uq3imte555lh
_uq3imte555lh
SIP2 connection credentials


Hostname:
Port number:
Login user ID:
Login password:
Location code to use:
Patron ID field code:

Anchor
_9eecr3epspdj
_9eecr3epspdj
Collection credentials

 

Anchor
_tgkpb9wz5hur
_tgkpb9wz5hur
Overdrive credentials

Client key:
Client secret:
Website ID:
Library ID:
ILS name:
Patron identifier field (barcode, record number, etc):

Anchor
_g163nygcygch
_g163nygcygch
Bibliotheca credentials

Library ID:
Account ID:
Account key:

Anchor
_m27n6qq1o5kh
_m27n6qq1o5kh
Axis 360 credentials

Username:
Password:
Library ID:

Anchor
_57gdv8asehg1
_57gdv8asehg1

...

RB Digital credentials

URL:

Anchor
_857wg1o3e6x5
_857wg1o3e6x5
NoveList Select credentials

Profile:
Password:

Anchor
_6fyg59ah8fxw
_6fyg59ah8fxw
Other collections


Do you want the Instant Classics collection? (Yes/No):
Other electronic collections for this library:

Anchor
libpolicy
libpolicy
Library Policies


Library code:
(When multiple libraries share an ILS, what ties a patron to this library?)
Maximum fees before patron loses borrowing privileges:
How to tell if a patron is banned:
Any other library-specific rules about patrons losing borrowing privileges:
Any library-specific rules restricting which books patrons can borrow:
Any rules about patrons with different types of identifiers: