A guide to configuring the SimplyE Circulation Manager, for hosting/implementation providers or technical library staff

 

This guide is currently under development. We're converting from a previous set of documents, so a few of the instructions and links are no longer valid. As soon as the conversion and initial edit is complete, we'll update the status to draft. Nevertheless, comments and feedback are welcome.

 

Purpose

This document provides the basic instructions necessary to configure a demonstration implementation of the Circulation Manager. They provide access to a single library with a small, open access collection. This configuration does not yet demonstrate configuring a DRM-protected library service stream from a commercial service, such as Overdrive, Bibliotheca, or Axis 360. Instead, the aim here is to:

  1. Ensure that the Circulation Manager is deployed successfully,
  2. Review how the Circulation Manager works,
  3. Provide an opportunity to experience actively configuring a Circulation Manager before deploying a production service, and
  4. Promote confidence that the organization is ready to deploy a more robust, production Circulation Manager.

Though this Quickstart does not demonstrate configuring a library's commercial collection of DRM-protected materials, there are other documents which provide step-by-step guidance. After you have configured this demonstration Circulation Manager, you may wish to see the "Configure" articles in the How-to articles section for integrating a specific commercial provider collection.

NOTE: I need to do something with the following block. After reviewing and editing the doc, 
This document will provide the following:

  1. Getting your initial Circulation Manager installed and configured to a state in which a Sysadmin can access and use the configuration UI
  2. Getting a testable version of the App through test flight so they may evaluate and troubleshoot configurations and operations prior to pilot.

Assumptions/Requirements

Deployment. Your Circulation Manager should be completely deployed and available on the Internet to fully test the configuration elements presented here. Refer to the Deploying a SimplyE Service document for more information on deployment scenarios and instructions on deploying to virtual servers and Amazon Web Services.

System and Library Information. This document refers 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.

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:

SimplyE Provider Domain: http://simplye.provider-name.org/

Library Name: ABC Public Library
Library Website URL: https://www.abclibrary.org/
Library Shortname (supplied by NYPL): TXABCL
Library Shared Secret (supplied by NYPL): a45fc87dffff

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.

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:

For the first access to the Circulation Manager, we recommend setting up a single user account acting as the primary administrator of the system. Subsequent access can then be configured as needed.

Access the Web-Based Configuration Interface

  
  1. Open a web browser and go to the /admin path in the Circulation Manager domain,
    as specified above; e.g., http://simplye.provider-name.org/admin 
  2. Scroll the bottom of the initial page to the section Create a new individual admin 
  3. Enter the appropriate administrative user's email address in the Email field
  4. Enter a secure password (12-16 characters recommended) into the Password field
  5. Click the Submit button below the form

 

When the administrator account is created, your browser will be redirected to the Admin login page.

Login as the Administrator

  

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

  1. Log into the new Circulation Manager's administrative configuration panel:
  2. Verify the initial server settings created automatically for your installation:
  3. Configure the Elasticsearch service integration for the Circulation Manager:
  4. Create a Metadata Wrangler integration:

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.

Create a Test Collection for the Library

  1. Create a test collection and assign it to the demo library:

Create the Library's Patron Authentication Integration


  1. Create a test patron authentication configuration To run a full test of the Circulation Manager, you will need to be able to authenticate the patron to the library. The web admin utility features a single-user test authentication mechanism. You can use this for testing, but you will need to use connectivity to an authentication resource, typically an ILS, for production systems.

Register the Library with the NYPL Adobe ID Service

When you create a library with commercial, DRM-protected collections, you must register the library with NYPL so the library will have access to NYPL's shared Adobe ID license. Though you can skip this step for the demonstration library in this example, it is a critical step in making the library's collections usable in production.

Configuring Custom Lanes for the SimplyE Mobile App

The SimplyE mobile app presents subsets of a library's collection, usually specific genres and/or sub-genres of a collection, as a set of carousels termed lanes (swim lanes) in its primary interface. Lanes are automatically generated from the metadata included in an ebook data feed. However, the lanes presented can be customized. The document Customizing Lane Categories, providing a demonstration with step-by-step configuration instructions, is planned for development soon. If you wish to look at the editor interface before that document is ready:

  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

More information will follow in the detailed document.

Accessing the Demonstration Collection in the Generic SimplyE Mobile App

Once the system is configured, you have created a library, and imported the demonstration collection, you can set up the generic production SimplyE mobile app to point to your test library's collection for review. Because this library is not registered with NYPL, its name will not appear in the list of available libraries using SimplyE. Instead, you can review your demonstration collection by using a tap sequence to open up a hidden prompt.

  1. Download/install the SimplyE app from the app store for your device (Apple Store or Google Play Store)
  2. Open the SimplyE app on your device
  3. Tap the menu icon
  4. Tap the Settings item
  5. In rapid succession, tap the Version entry eight times
  6. Tap the Alternate URIs entry which appears
  7. In the Feed URI field, enter the URL to the demonstration library's OPDS feed; e.g., http://simplye.org-name.com/TXABCL
  8. Click the Set button at the bottom of the form
  9. Click the back arrow icon to go back to Settings
  10. Click the menu icon
  11. Click the Catalog item to display books in the demonstration library's collection

This manual mechanism is available for informally testing the display of library collections. This will work with DRM-protected collections as well as the open collection used in this demo. However, this mechanism will not work correctly when you are ready to test download and reading of DRM-protected commercial collections. For that level of testing, you will need to contact NYPL to include the library in the beta distributions of the iOS and Android mobile apps. For instructions, see Request a Library's Inclusion in Beta/Production App (Draft).

Once you have successfully accessed the library's OPDS feed in the generic app, you have completed the configuration of your first SimplyE deployment.