Versions Compared

Key

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

...

System and Library Information. This document refers instructions below refer to data you will need to complete the configuration of several areas of the Circulation Manager. For example, in a production environment as the hosting provider/implementor, you should have already received information from a library to be added to the Circulation Manager. The required library data is described in detail in the document SimplyE Library Implementation Guide. We've included example data below which you will use if following the demonstration library configuration.

In addition to the library information, we make reference here to system-related information. For example, when you deployed your Circulation Manager infrastructure you should have implemented a domain name for the SimplyE Circulation Manager service and added it to your DNS zone. For a single library implementation within a statewide SimplyE implementation (the original design thinking for the service), the domain name would have the form https://library_name.simplye-state-abbreviation.org. With a change in software implementation to host multiple libraries on one Circulation Manager instance, and with providers offering services not constrained by geography, the Circulation Manager domain might take the form https://circulation.org-name.com/ or https://simplye.org-name.com/. For the sample configuration in this document, we will use the fictitious information below:

Info
iconfalse

SimplyE Provider Domain: http://simplye.provider-name.org/ (substitute here and below with the proper domain for your demonstration instance)
Elasticsearch Service URL: http://172.18.0.11:9200 (assuming you follow the demonstration deployment instructions; substitute the proper URL if not)

Library Name: ABC Public Library
Library Website URL: https://www.abclibrary.org/
Library Shortname (supplied by NYPL): TXABCL (shown as an example, but not used if following the demonstration)
Library Shared Secret (supplied by NYPL): a45fc87dffff a45fc87defbc11f3 (shwon as an example, but not used if following the demonstration)

Note
TECHNICAL NOTE: The provider domain above uses a simple HTTP service, not an encrypted site. The simple test deployment instructions referenced in Deploying a SimplyE Service do not install the OpenSSL library/module needed to provide HTTPS service. This is by design: the circ-webapp container does not include an SSL service. In a production environment, we assume the Circulation Manager application service will actually be deployed as a multi-server cluster behind a load balancer for reliability and scalability. In that case, the HTTPS service will terminate at the load balancer. Communication between the load balancer and the back-end application server instances will be via simple HTTP. This is standard practice as it decreases load on the application servers. If you will deploy a single application server host for your production Circulation Manager service, you will need to implement SSL on the circ-webapp container or potentially build a custom container. In production, then, we expect the provider domain to be available only via HTTPS.

Web Browser. Last, you must use Google Chrome or Mozilla Firefox to work in the Admin configuration interface. The Admin interface currently does not render correctly in Microsoft's Internet Explorer or Edge browsers.

Overview

Once you have deployed/installed the Circulation Manager software, you're ready to begin configuring the system to connect to the various external systems that make SimplyE work: commercial ebook provider systems and other sources of ebooks, libraries' integrated library systems, indexing/search servers, metadata servers, and analytics systems. The Circulation Manager acts as a nexus of these systems and provides lists of these resources in the form of OPDS feeds, based on the Atom Syndication Format, to remote clients. Currently SimplyE clients are available for both iOS and Android mobile operating systems. Plans are in place for a web-based client as well.

Configuration of the Circulation Manager can be divided into three areas:

  1. Creating administrator users
  2. Configuring system-wide settings:
    1. Verify the Circulation Manager's server-wide settings
    2. Configure Elasticsearch service
    3. Register the Circulation Manager with the NYPL Metadata Wrangler
  3. Configuring one or more libraries:
    1. Create the library record
    2. Configure one or more collections for the library and associate them with the library
    3. Configure a patron authentication technique (SIP or ILS) and associate it with the library
    4. Configure an analytics mechanism and associate it with the library
    5. In a more thorough test or in production, register the library's catalog with NYPL for inclusion in the mobile apps

The following sections show how to configure a demonstration Circulation Manager. This configuration continues the testing implementation begun in the Ansible deployment repositories.

Create a Circulation Manager Administrator User

The first action to take in configuring your Circulation Manager instance is to create an administrative user. Currently, it is possible to use two mechanisms to enable access to the Circulation Manager's admin interface:

...

  

On the Circulation Manager's login page:

  1. Enter the email address of the administrator you created above into the Email field
  2. Enter the password you created for the administrator into the Password field
  3. Click the Sign In button

 

Once you have installed the circulation manager software, go to https://<your-circ-manager-url>/admin, and:

  1. Configure admin authentication you must do this before you can proceed
  2. Verify the Circulation Manager's server-wide settings
  3. Configure Elasticsearch AWS Getting Started Guide
  4. Register the circulation manager with the metadata wrangler
  5. Configure one or more libraries
    1. Create the library record
    2. Configure one or more collections for the library and associate them with the library record
    3. Configure a patron authentication technique (SIP or ILS) and associate it with the library
    4. Configure an analytics mechanism and associate it with the library
  6. Register the library's catalog with NYPL for inclusion in the mobile apps

Configure the Circulation Manager System

Perform Web-Based System Configuration

...

Configure the Circulation Manager System

Login to the Circulation Manager Admin Interface

  1. Go to the admin website: e.g.,http://simplye.provider-name.org/admin
  2. There is a top menubar which contains the following options:
    1. a library section with a drop-down library selector, plus links for the library's
      1. Catalog
      2. Complaints (from users)
      3. Hidden Books
      4. Lists
      5. Lanes (Lanes Manager)
    2. a Dashboard link, providing general collection statistics
    3. a System Configuration link (just Configuration in older versions)
    4. a user drop-down selector with Sign Out option
  3. Click the System Configuration link in the menubar

You will see the main configuration page with thirteen configuration sections in a left sidebar:

    • Libraries
    • Admins
    • Collections
    • Admin Authentication
    • Patron Authentication
    • Sitewide Settings
    • Logging
    • Metadata
    • Analytics
    • CDN
    • Search
    • Storage
    • Discovery
  1. Verify the initial server settings created automatically for your installation

A few of these sections apply only to special cases, but most of them will be touched in production instances. In this demonstration configuration, we will only visit six; but these are the most commonly used and will give you a good experience in creating a useful SimplyE service.

Verify Initial Circulation Manager Settings

There are a number of settings created automatically when the Circulation Manager is installed or accessed the first time. In this case, we want to verify that the Base URL stored for the system matches the URL we entered in the web browser:

  1. Click the Sitewide Settings item in the left sidebar.
  2. Click the Base url of the application setting and make sure it is set to the host and domain name you desired (no trailing '/admin' path).
  3. For this base testing deployment, no other site settings are necessary.Configure the Elasticsearch service integration for the Circulation Manager:
  4. Click the Search sidebar item.
  5. Click the

Create

...

the

...

  1. for testing Virtualbox and Linode (single-server) implementations, enter the internal container IP-based URL, "{+}http://172.17.0.2:9200+".
  2. for testing AWS implementations using the AWS ES service, enter the URL to the Elasticsearch server as shown in your ES service console.

...

Elasticsearch Service Integration

The Elasticsearch service is responsible for supplying search results to the SimplyE mobile clients.

Excerpt Include
Create the Elasticsearch Integration
Create the Elasticsearch Integration
nopaneltrue

Create a Metadata Wrangler Integration

Excerpt Include
Create a Metadata Wrangler Integration
Create a Metadata Wrangler Integration
nopaneltrue

Configure a Library

Create the Library Record and Configure Usage

Note: When configuring the library, you MUST provide a default email address to use when notifying patrons of changes.

    • Click the Libraries sidebar item.
    • Click the Create a new library item.
    • Enter a descriptive name that uniquely identifies the library and makes it easy to find in a long list of library names hosted on the Circulation Manager; e.g., "Testing - Demo Library 1".
    • Enter the unique shortname for the library (e.g., "XXABCL", created by NYPL as described in DRM Token for Adobe Vendor ID on page three); this value is used in the OPDS feed path (see the last section of this document) for accessing the library's books from the mobile app.
    • Enter a required primary language code for the library's collection(s); e.g., 'eng' for English and/or 'spa' for Spanish. Again, at least one language must be specified.
    • Select a color for your library theming
    • You can upload a logo PNG - (135x135 required)
    • Click the Add button to the right of the primary language field.
    • You can specify other information about the library if desired (help pages, loan periods, etc.), but the above three are required for testing.
    • Click the Submit button to create the library.

Create a Test Collection for the Library

...

Excerpt Include
Create a New Library
Create a New Library
nopaneltrue

Create a Test Collection for the Library

Each library in SimplyE can be configured to have one or more collections associated with it. Generally, this means adding library-specific credentials to a commercial ebook provider's lending system. It can also mean adding links to open collections that are available for any library's use. Except for the specific data elements required to access a vendor's system, the process is very similar from vendor to vendor. For our demonstration library we create a simple collection which is a subset of NYPL's larger Library Simplified Open Access collection. This minimizes the ingest time required and enables us to review the system sooner to make sure everything is working properly. Follow these steps to create the collection and associate it with our demonstration library.

  1. Click the Collections sidebar item.
  2. Click the Create a new collection item.
  3. Enter a descriptive name into the Name field that uniquely identifies the collection and makes it easy to find in potentially a long list of collections; e.g., ABC Library - Plympton
  4. For a collection available as a simple public OPDS feed, which we'll use here (note: composed of 'open-access' or 'borrow' acquisition links; 'buy' links are not supported and such books do not appear in the collection's feed in the SimplyE app), accept the "OPDS Import" protocol.
  5. Enter the URL of a publicly accessible feed;

    for initial testing we will use a small subset of the Library Simplified Open Access collection (a small set of books minimizes import/indexing time and makes the full collection viewable in a short period):

    e.g., http://oacontent.librarysimplified.org/works/sources/Plympton

  6. Give the collection a unique data source name; e.g., oacontent-plympton

  7. Assign the collection to the test library:

    1. In
    the
    1. the Add Library
    dropdown
    1.  dropdown, select the name of the library you added earlier: ABC Public Library
    2. Click
    the
    1. the Add Library
    button
    1.  button which appears below the dropdown; this links the collection to the library
    2. You will see the library name in a group list and can delete it if necessary by clicking the 'x' to the right of its name

  8. Click

    the

    the Submit

    button

     button to create the collection

    .


Create the Library's Patron Authentication Integration

...

To enable library users to borrow and return items from the collection, a patron authentication integration must be created for the library. In all cases, this enables the Circulation Manager to check the user's credentials to ensure the user is a authorized user of the library. The patron authentication mechanisms available are generally either API-based, or SIP2-based. However, there is also a simple authentication mechanism available which is only good for initial testing. It provides a means of recording a single user barcode and PIN to test against when attempting to access the library's SimplyE catalog. We'll use the simple authentication for this demonstration library. For detailed information on configuring a patron authentication integration for a specific integrated library system in a production Circulation Manager, see the document Authenticating Library Patrons when it written.

To create a test authentication mechanism:

  1. Click the Patron Authentication sidebar item
  2. Click the Create a new patron authentication service item
  3. Again, give the service a descriptive name that is easy to identify in a long list of services; e.g., ABC Public Library -- Simple Auth
  4. Accept the default "Simple Authentication Provider" in the dropdown list for this test
  5. Enter a test user identifier; for a simulated 14-digit barcode, you might enter the following: 29999087654321
  6. Enter a test password, which in this case should actually be a PIN, something like: 0550
  7. In the Libraries dropdown item, select the test library you created
  8. Click the Add Library button at the bottom of the form
  9. Click the Submit button to create the integration

Register the Library with the NYPL Adobe ID Service

...

  1. Login to the Circulation Manager admin interface as normal
  2. On the left side of the top menubar, click the drop-down list of libraries
  3. Select the library name for which you would like to customize lanes
  4. In the top menubar, click the Lanes link
  5. Review the Lane Manager sidebar for customization options

...