Information needed to add a library's collections to SimplyE

This document is currently undergoing revision. Feedback welcome.


Table of Contents

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.

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.

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.

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.

 

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.

The coverage area determines which libraries show up in a search for "Newington"
or "06010". It is not used to restrict access. Access is controlled by the patron's
credentials.

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.


If you don't authenticate patrons using an ILS, we need to know how you do it. Some libraries send a set of barcodes to Overdrive and have Overdrive do the authentication themselves. This should also work with SimplyE, but we need to know what you use.

Currently, SimplyE can integrate collections from Overdrive, Bibliotheca, Axis 360 and One Click Digital. It's useful to know about all of your electronic collections, even the ones we currently don't support. When we implement our next integration, we'd prefer to do one that a lot of libraries are waiting for.

Each distributor has a section below that explains how to get a credential.

For example, Sierra has a 'block' field called MBLOCK[56]. NYPL sets the value to a letter code for patrons who are blocked and sets the value to '-' for patrons who are not blocked. This seems to be common among libraries that use Sierra, but we don't know if it's universal.
If your library has any other policies like this, we need to know about them. For example, maybe you mark cards as expired by prefacing the barcode with "EXP". We may not be able to enforce these policies for you immediately, but we'll never be able to get it to work if we don't hear about them.

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.  

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.

Triple I (III)

Sierra

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


Unfortunately, Sierra also offers (at least) two APIs that cannot 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.

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.

Evergreen

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

SyrsiDynix

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

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.

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.

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.

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.

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:

Distributors

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!

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

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.

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.

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".

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:

The Form: Circulation Manager

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:

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:

ILS credentials


Name of ILS product:

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

SIP2 connection credentials


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

Collection credentials

 

Overdrive credentials

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

Bibliotheca credentials

Library ID:
Account ID:
Account key:

Axis 360 credentials

Username:
Password:
Library ID:

RB Digital credentials

URL:

NoveList Select credentials

Profile:
Password:

Other collections


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

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: