Beginning on 9/18 you will be able to change your enterprise password from within Jira!

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Current »


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

 

Status: Development

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 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: 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): a45fc87defbc11f3 (shwon as an example, but not used if following the demonstration)

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:

  • Creating individual user accounts 
  • Configuring single sign-on using Google accounts

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

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

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 testing deployment, no other site settings are necessary

Create the Elasticsearch Service Integration

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

Required Information

To create a Search integration, you must obtain the URL (IP address or hostname and any port number) required to connect to the search server. If you are following our guide to creating a demonstration Circulation Manager instance, the URL will typically be a local one: http://172.18.0.11:9200. For an AWS deployment, where you are using the AWS ES service, the URL will have the form: https://vpc-[domain-name]-[unique-id].[region].es.amazonaws.com .

Configure the Search Integration

Configure the Elasticsearch service integration for the Circulation Manager:

  1. Click the Search sidebar item
  2. Click the Create a new search service item
  3. Enter a descriptive name for the service; e.g., Elasticsearch indexing server
  4. Currently only the Elasticsearch server is supported, so the default Protocol item is appropriate
  5. Enter the URL to your Elasticsearch service as noted above
  6. Unless there is a local reason to change it, leave the default Elasticsearch index name as circulation-works
  7. Click the Submit button.

Create a Metadata Wrangler Integration

The New York Public Library offers a metadata enhancement service to libraries using SimplyE. Named a metadata wrangler, the service contacts known sources of book metadata and cover images in order to enhance the data that is supplied by publishers or content providers such as Overdrive, Axis 360, and Bibliotheca. The enhanced metadata facilitates end-user searching of collections and, in the case of covers, provides a more appealing visual interface to the SimplyE apps by supplying covers for many titles where the original provider does not. Follow these steps to make the service available to your Circulation Manager instance. Additionally, the service establishes a normalized categorization and description of the book for use if the provider does not supply one. THis is necessary so that the circulation manager can properly organize the collection for presentation and navigation by users.

Step-by-step guide

  1. Login to your Circulation Manager's administration site.
  2. Click the Configuration or the System Configuration link in the top menu bar.
  3. Click the Metadata sidebar item.
  4. Click the Create a new metadata service item.
  5. Enter a name for the shared Library Simplified Metadata Wrangler service; for example, NYPL Metadata Wrangler. the url is https://metadata.librarysimplified.org/
  6. In the Protocol list, select the Library Simplified Metadata Wrangler item.
  7. You can accept the supplied URL for the shared metadata wrangler service. (e.g. https://metadata.librarysimplified.org/ )
  8. Click the Submit button to save the integration.


Note: If you happen to receive an error message (Error: The library could not complete your request because a third-party service has failed), the Wrangler server may be experiencing high volume or be down for maintenance. Try waiting ten minutes or so and re-submit the form. If you continue to experience the error, post a message in the #devops channel in Slack.

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.

  1. Click the Libraries sidebar item.
  2. Click the Create a new library button.
  3. Enter the library Name to display in various screens of the Circulation Manager; e.g., ABC Public Library; this name will be displayed in the active library list in the SimplyE mobile apps
  4. Enter a unique Short name for the library; this value will be used as the first segment of the URL path in the library's Circulation Manager OPDS/catalog feed
    1. previously this was a value obtained from NYPL, of the form FLABCL
    2. the suggested form is a two-letter state abbreviation followed by a short tag identifying the library
    3. letter case is optional (all uppercase is not required), though consistent usage is preferred for all libraries configured in the Circulation Manager
  5. Enter an email address into the Patron support email address field, which the library has designated for their patrons to submit help requests
    1. This field is required.
    2. The email address must be valid.
  6. Enter a valid email address into the Default email address to use when notifying patrons of changes field;
    1. This email address is needed to handle email notifications that come directly from the remote content vendor (OverDrive and others); the SimplyE system does not currently send any emails
    2. The email address is required in order for the SimplyE Circulation Manager to submit the hold request to the content vendor; the content vendors normally use this email address to notify patron of hold request updates
    3. This email address should be set to discard or bounce all email sent to it (your email support staff can help with this) because it contains potentially sensitive information about patron activities
    4. An example of an email address you may have seen that performs this function is no-reply@example.com
    5. NOTE: There is currently no support in the SimplyE app for automated hold request notifications (see About Hold Notifications for information about current development); patrons must check hold status manually through the app
  7. Select a color for the library's mobile app theming; this field is optional but recommended
  8. You can upload a logo image (in PNG, JPG, or GIF format, 135x135px required); this field is optional but recommended
  9. The eng English language code is supplied by default; enter language codes for any other primary languages represented in the library's collection(s); e.g., spa for Spanish
  10. Click the Add button to the right of the primary language field if added.
  11. For production use, there are a number of other elements you should supply: help pages, loan periods, etc.; however, these are sufficient for testing.
    1. If you do not set the focus and service areas, they will default to "Everywhere"
  12. Click the Submit button to create the library in the Circulation Manager. 

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; 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 Add Library dropdown, select the name of the library you added earlier: ABC Public Library
    2. Click the Add Library button which appears below the dropdown; this links the collection to the library
    3. 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 Submit 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 library you created
  8. Click the Add Library button at the bottom of the form
  9. Click the Submit button to create the integration

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.

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 this demonstration example, it is a critical step in making the library's commercial collections usable in production. We are working on the forthcoming document Add a Library to the SimplyE Library Registry, which describes and demonstrates the registration process, as development on the SimplyE Library Registry continues.


  • No labels