Purpose

This document is to help you connect your library's Overdrive collection to your Library Simplified Circulation Manager service. Overdrive provides a glossary that explains most of the terminology.

Types of Overdrive Collections

Some libraries only have access to one Overdrive collection, the one they've acquired using local resources. For purposes of this configuration document we will refer to this as a simple Overdrive collection. However, some libraries also participate in a consortium that gives them access to a larger collection, with their individual library collection being an Overdrive Advantage collection of separate titles. We'll refer to this set of collections as a tiered Overdrive collection, with a parent collection and a child collection. In this case, your library's Advantage Collection is a child of the consortium collection (the parent). In order to configure tiered Overdrive collections, you (or your SimplyE hosting provider) will need account credentials for both the consortium's Overdrive collection and your library's Overdrive Advantage collection. You may need to contact the consortium's support staff to obtain their credentials.

If your library has only a simple Overdrive collection, you need to complete only the steps for "Configuring the Parent Overdrive Collection," using the Overdrive access credentials you obtain for your library as shown below.

For a tiered collection, you should complete the Parent section for the primary Overdrive account, the consortium account, with the credentials supplied by consortium staff. Afterwards, you should complete the "Configuring the Child Overdrive Collection," your Advantage collection, using your library's access credentials. 

Obtaining Access Credentials

The following steps will help you complete the application to obtain Overdrive API credentials for your library collection. As a precaution, you may wish to whitelist the email addresses associated with the application process so the response emails don't get caught by your spam protection software. At the least, you should whitelist the following two specific addresses:

apisupport@overdrive.com
support@overdrive.com


  1. To start connecting your library's Overdrive account to your Library Simplified circulation manager, go to the Member Center and apply for API access. You will need to create an Overdrive developer account to obtain credentials required in connecting the Circulation Manager to your Overdrive account.

    Apply for Access Early!

    It can take a week or more to get approved for API access, so don't put this off!

  2. Click the Apply link to start the application.

  3. Complete the Developer Application form as shown below

     

    a. For the "Are you requesting a new API client" dropdown, select the Existing Client option.

     

    b. Enter your name and your email address into the Contact Name and Contact Email Address fields.

    c. If you know your library's Overdrive identifier, you can enter it in the API Client Key field. If you don't, you can enter your library's city and state. The API Client Key should be provided to you in your response from Overdrive for developer access.

    d. Be sure to select both the Discovery and the Circulation options in the API Access Requested field.

    Overdrive API Types

    Overdrive distinguishes between Discovery and Circulation APIs. Library Simplified needs access to both, to keep track of the items in your collection as well as to conduct circulation transactions on behalf of your patrons.

    From the glossary:

    Discovery APIs: Discovery APIs are designed to allow your users to browse and explore OverDrive digital collections. You can search for titles, check availability, and get details on specific titles.

    Circulation APIs: These APIs are designed to allow you to circulate content from an OverDrive digital collection. You can borrow and place holds on titles, see what a specific user has borrowed or placed on hold, and get download links for content that a user has borrowed.

    e. Copy the following block of information in the Planned API Usage field. It is important to request all three authentication types (see the NOTES section below). Be sure to edit your library's name; the remainder of the items should remain as is:

    Library: Your Library Name
    Project: Integration with SimplyE, in partnership with NYPL
    Environment: Production (not testing)
    Authentication Types Required:
      - Client authentication
      - Patron authentication
      - Granted authentication

     

    f. Click the Confirm Conditions checkbox.

    g. Click the "I am not a robot" checkbox.

    h. Once you've reviewed the form, click the Submit button to complete the registration

  4. Wait for Overdrive to send you an email with production IDs needed to configure your Circulation Manager Overdrive Collection. You will receive an email response (to the address you provided above) almost immediately upon submitting your application, which is just a confirmation Overdrive received your request. In about 24 hours so (perhaps longer depending on circumstances) you should receive an email with your library's API credentials. The credentials will include the following data points:
    Library ID
    Website ID
    Client Secret
    Library ILS name
    OverDrive digital collection URL
    If you did not know your exact API Client Key to enter into the application form above, and you don't see it in the response, reply to the support address and request the API Client Key as well.

    Sandbox vs Production IDs

    When Overdrive sends your API credentials email, you may accidentally receive a website ID of 100300 and a library ID of 4425. Those are the IDs for the Overdrive test library. If this happens to you, reply to the email and tell them that you need the production IDs to integrate your library into the SimplyE system.

Configuring the Parent/Main Overdrive Collection

Once you have obtained either the API credentials for your library's Overdrive collection (a single Overdrive collection), or the consortium's API credentials for the main consortium collection (in a tiered Overdrive configuration), you can proceed to configure the Overdrive collection in the SimplyE Circulation Manager.

  1. Open a web browser and enter the URL to your Circulation Manager's Admin interface: for example, https://simplye.libraryname-state.org/admin 
  2. In the top menu bar, click System Configuration to enter into the Configuration Manager portion of the Admin interface.
  3. Click the Collections item from the left menu.
  4. Click Create a new collection
  5. Select the Overdrive item from the Protocol drop down field.
  6. Fill in the configuration form:
    1. Under Name, enter a descriptive phrase for the collection: for example, XYZ Consortium Overdrive
    2. Skip the Parent field if it is displayed
      Note: If this is the first Overdrive collection you have created in the Circulation Manager, the Parent field is not present.
    3. Under Library ID, enter the corresponding ID from your credentials email provided by Overdrive
      Note: If Overdrive's library ID starts with a zero, you'll probably have better results if you omit the zero.
    4. Under Website ID, enter the corresponding ID from your credentials email provided by Overdrive
    5. Under Client Key, enter the key provided by Overdrive
    6. Under Client Secret, enter string provided by Overdrive

    7. Select the appropriate library record from the Add Library drop down list
    8. In the library sub-form which displays, in the ILS Name field, enter the Library ILS name string provided by Overdrive
    9. Also in the library sub-form, in the Default Loan Period field, enter the length of the library's ebook loans
    10. When you have finished the library sub-form, click the Add Library button to enable titles from this collection to be displayed in the library's SimplyE browse feeds
    11. When you have reviewed the form and are ready, click the Submit button to create the Overdrive collection. If the Circulation Manager management scripts are all running, an ingest process for existing title metadata from Overdrive will begin within the hour.

If your Overdrive collection is a single, standalone collection, this completes your Overdrive configuration. If you were configuring the consortium collection which serves as a base for a library's subsidiary Overdrive Advantage collection, begin configuring that Advantage collection in the next section.

Configuring a Child/Advantage Overdrive Collection

When your library is part of a consortium that has a primary, overarching collection, but your library has a separate Overdrive Advantage collection, you need to configure the Advantage collection and associate it with the primary collection.

The script bin/informational/overdrive-advantage-list will query Overdrive to learn about all Overdrive Advantage collections associated with a primary Overdrive collection. In particular, it will list the names and library IDs of all libraries with an Overdrive Advantage collection associated with a primary collection. This is a useful script to run when setting up Overdrive Advantage accounts, because it can save some back-and-forth emailing with Overdrive.

To configure the Advantage collection:

  1. Login to the Circulation Manager Admin interface
  2. Click the System Configuration top menu item
  3. Click the Collections item on the left sidebar
  4. Click the Create a new collection item
  5. Select Overdrive from the Protocol dropdown list
  6. In this case, we need to link the new collection to a parent collection; select the appropriate parent collection from the Parent dropdown list

    Notice that selecting the parent collection removes several of the configuration options. This child collection will use the corresponding values from the parent collection.
  7. Under Library ID, enter the corresponding ID from your credentials email provided by Overdrive (or obtained through the bin/informational/overdrive-advantage-list script)
  8. Select the desired library record from the Add Library drop down list
  9. In the library sub-form which displays, in the ILS Name field, enter the Library ILS name string provided by Overdrive
  10. Also in the library sub-form, in the Default Loan Period field, enter the length of the library's ebook loans
  11. When you have finished the library sub-form, click the Add Library button to enable titles from this collection to be displayed in the library's SimplyE browse feeds
  12. When you have reviewed the form and are ready, click the Submit button to create the Overdrive collection. If the Circulation Manager management scripts are all running, an ingest process for existing title metadata from Overdrive will begin within the hour.

NOTES

The Three Types of Overdrive Authentication

When the Library Simplified Circulation Manager makes a call to the Overdrive API, Overdrive needs to verify that the Circulation Manager is authorized to act on behalf of your library. If the Circulation Manager is acting on behalf of a specific patron (e.g. creating a loan), Overdrive also needs to know that the Circulation Manager is authorized to act on behalf of that patron.

Overdrive offers three types of authentication:

  1. Client authentication verifies that the Circulation Manager is authorized to act on behalf of the library. It's used by scripts that run in the background to maintain an accurate picture of your library's Overdrive collection.
  2. Patron authentication and 
  3. Granted authentication

Each authentication type provides the Circulation Manager with an access token. In all cases, the token is only good for an hour, after which a new token will be requested.


Client Authentication
Client authentication is pretty simple. Overdrive issues you a set of credentials: a client key and a client secret. At any time, you can show those credentials to Overdrive to get an access token. Although this is the simplest way to get an an access token, the token is not authorized to act on behalf of a specific patron. You can look at the collection but you can't borrow books.
Patron Authentication
Patron authentication is the simplest way of getting an access token to act on behalf of a patron. It can only be used when your library does authentication by username and password (or equivalent pieces of information, such as barcode and PIN).

To get an access token with patron authentication, you provide your client key and client secret (as with client authentication), but you also provide the patron's username and password.

Overdrive checks the patron's username and password with your ILS. If the ILS says the username and password are valid, you get an access token.

This access token can act on behalf of the patron whose username it was associated with. You can borrow books, place holds, etc.

Granted Authentication

Granted authentication is a more complex way of getting an access token to act on behalf of a patron.

When you set up granted authentication with Overdrive, you'll be asked to set up a "redirect URI". (You can change your redirect URI here.) Your redirect URI should point to the oauth_calback controller of your circulation manager, e.g.:

https://my-circulation-manager.com/oauth_callback?provider=Overdrive

When a patron tries to check out a book through Overdrive, Library Simplified circulation manager will tell them to visit a URL based on this template:

https://oauth.overdrive.com/auth?client_id={ID}&redirect_uri={URLredirectedTo}&scope=accountId:{ID}&response_type=code&state={optionalStateParameter}

Overdrive will redirect the patron to... some URL somewhere. I's unclear yet if it's a URL on your ILS or one managed by Overdrive. Either way, the patron will be asked to log in. Once they log in they will be asked to authorize Library Simplified to act on their behalf. Once they allow this, Overdrive will send them to your redirect URI:

https://my-circulation-manager.com/oauth_callback?provider=Overdrive&state={optionalStateParameter}&code={authorizationCode}

The circulation manager can then use the {authorizationCode} to get an access token to act on behalf of the patron.

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.