Information needed to add a library's collections to SimplyE

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.

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.

• Name of the library
• Any alternate names for the library (e.g. "NYPL" for the New York Public Library).
• The URL to your library's web page.
• The library's coverage area. There are four ways of providing this:
  • A list of cities and towns in your area that the library serves. This is by far the simplest solution.
  • A list of ZIP codes that the library serves.
  • If you happen to have an ESRI shapefile that marks out your coverage area, that will work great. But don't try to construct one if you don't already have one.
  • The latitude and longitude of each of the library's branch buildings. This is not as reliable as the other methods.

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.

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

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

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.

• If the library shares an ILS with other libraries, but does not share a collection with those libraries, there must be some way of identifying which library a patron belongs to when querying the ILS. Usually each library has something lke a 'location code' that distinguishes it from other libraries on the same ILS. We need to know this location code for each library. Without this location code, we cannot validate patrons against the ILS, because we can't tell the ILS which library they're a patron of.
• We need at least four sample patron credentials for testing:
  • A patron with borrowing privileges.
  • A patron whose borrowing privileges have expired.
  • A patron who has lost borrowing privileges because of excessive fines.
  • A patron who has lost borrowing privileges for some other reason.
• We need to know which electronic collections your library has access to. You may have access to a collection because your library paid for it directly, because you belong to a consortium that shares access to it, or because it's available to all libraries at the state level. You may have access to two distinct collections of the same type.

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.

• For each electronic collection that we support, we need a credential to an API which lets us borrow items from that collection. Overdrive, Bibliotheca, Axis 360 and One Click Digital all have APIs that meet our needs. But to get the credentials, you'll probably have to do some work in your capacity as the representative of your library. Your vendor can't necessarily do this work for you.

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

• Since we are borrowing books on behalf of your patrons, we need to know if your library's policy ever restricts your patrons' ability to borrow books. These two items of policy are pretty common:
  • How high do a patron's late fees have to go before you stop them from borrowing books? (For NYPL, this is $15.00.)
  • How can SimplyE tell, by looking at a patron's ILS record, whether the patron is barred from borrowing books for some other reason?

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.

• On top of basic things like blocking for excess fines, your library might have policies restricting the types of books a patron can borrow. For instance, NYPL has a rule that if your patron type (the "P TYPE[47]" field in Sierra) is 60, 62, or 152, you may only borrow children's books. If your library has similar rules, we need to hear about them. Again, we may not be able to enforce these policies immediately, but we need to hear about them so we can plan the work.
• Some library patrons may have multiple barcodes, due to library policy, or to agreements with governments or other libraries. For example, a single NYPL patron may have:
  • A NYPL barcode (the number on their library card)
  • An alphanumeric username (which they chose themselves when creating an account on nypl.org)
  • A second barcode corresponding to their Brooklyn Public Library card (by reciprocal agreement between NYPL and Brooklyn Public Library)
  • A third barcode corresponding to their NYC ID (by agreement between NYPL and the City of New York).

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:

• SIP2 (see below)
• The Millenium Patron API.

Unfortunately, Sierra also offers (at least) two APIs that cannot be used to connect a circulation manager to a Sierra installation:

• The[ |https://github.com/NYPL-Simplified/Simplified/wiki/Sierra-REST-API]"Sierra REST API" won't work because it does not allow a circulation manager to represent a patron to a third party (such as Overdrive).
• The "PatronIO" SOAP API is useful for creating patron records. It is not useful for validating patron credentials.

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:

• https://ils.mylibrary.org:54620/PATRONAPI/
• https://mylibrary.iii.com:54620/PATRONAPI/
• http://ils.mylibrary.org:4500/PATRONAPI/
• http://mylibrary.iii.com:4500/PATRONAPI/

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:

• The hostname of the SIP2 server.
• The port on that hostname where the SIP2 server is running.
• If sending SIP2 requests to the server requires authentication, SimplyE itself needs a login user ID and a password. (This is not a patron credential--it's permission to access the SIP2 server itself.) You may need to create a special account on the SIP server for SimplyE.
• Some SIP2 servers require that the location code be set to a specific value. If your server is like this, we need to know a value that will work.
• We need to know if you keep track of a unique patron ID–that is, an account number that stays the same even if the patron gets a new library card. If you don't have a unique patron ID, that's fine–we just won't use the features that require one.

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:

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

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: