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. |
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 meet four goals:
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 one or more specific commercial provider collections.
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 or Amazon Web Services.
System and Library Information. The 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:
SimplyE Provider Domain: |
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, we recommend you use Google Chrome or Mozilla Firefox to work in the Admin configuration interface. The Admin interface did not render correctly in Microsoft's Internet Explorer or Edge browsers in early 2.x versions of the Circulation Manager and occasionally may still exhibit problems in Explorer/Edge.
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:
The following sections show how to configure a demonstration Circulation Manager. This configuration continues the testing implementation begun in the Ansible deployment repositories.
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.
| ![]() |
When the administrator account is created, your browser will be redirected to the Admin login page.
On the Circulation Manager's login page:
| ![]() |
http://simplye.provider-name.org/admin
You will see the main configuration page with thirteen configuration sections in a left sidebar:
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.
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:
/admin
path)The Elasticsearch service is responsible for supplying search results to the SimplyE mobile clients.
Note: When configuring the library, you MUST provide a default email address to use when notifying patrons of changes.
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.
ABC Library - Plympton
Enter the URL of a publicly accessible feed; e.g., http://oacontent.librarysimplified.org/works/sources/Plympton
Give the collection a unique data source name; e.g., oacontent-plympton
Assign the collection to the test library:
ABC Public Library
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
Click the Submit button to create the collection
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:
ABC Public Library -- Simple Auth
29999087654321
0550
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:
More information will follow in the detailed document.
Once the system is configured with the library you created and the demonstration collection you imported, you will be able to view the collection in the Circulation Manager Admin interface.
To access the demonstration collection for the library, log in to the Admin interface as you've done in the sections above. Assuming the demo library is the single library tenant in the Circulation Manager, the library's catalog will be displayed in a series of topic carousels. If you have multiple library tenants in the Circulation Manager, select the desired library name in the library drop-down at the left side of the top Admin interface's top menu. The chosen library's catalog will be displayed.
Viewing a collection in either the beta or production SimplyE mobile apps requires registering the library with NYPL's Library Simplified Library Registry. App use currently is intended only for actual libraries. (Future development tasks have been discussed to enable registering a demonstration library but the feature is not yet available.) Skip this step for the demonstration example.
If you have configured an actual library and wish to include the library in the SimplyE Beta program so staff can fully review their collections in the SimplyE apps, you must register the library. Registration adds the library to the apps' list of libraries participating in SimplyE so users can log in and use materials. It also creates a secret key for the library so the apps can use NYPL's Adobe Vendor ID on behalf of the library in making loan requests of any commercial titles (OverDrive, Bibliotheca, Axis 360, etc.) in the library's collections.
Configuration steps coming soon.