Versions Compared

Old Version 1

changes.mady.by.user Unknown User (robertwilliams)

Saved on

compared with

New Version 2

changes.mady.by.user Unknown User (robertwilliams)

Saved on

Key

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

Anchor
_wrtnnkq6cz23
_wrtnnkq6cz23
Configuration: SimplyE Circulation Manager Configuration Quick Start

...

A guide to configuring the SimplyE Circulation Manager

Anchor
_1psak36my2mp
_1psak36my2mp
Purpose

This document provides the basic instructions necessary to create a "test run" of the Circulation Manager, configuring system settings for a first-time deployment. The instructions do not include settings to activate 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. Promote confidence that the organization is ready to deploy a more robust, production Circulation Manager.


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.

Anchor
_p67uznk20zxo
_p67uznk20zxo
Resources

Anchor
_pytr5lrji82r
_pytr5lrji82r
Requirements

You will need a Chrome or Firefox web browser to access the configuration panel. The admin panel does not display correctly if using Internet Explorer/Edge.
You also need the domain name for which you created a DNS entry in the previous document. The administrative panel site will have a URL of the following form: http://test.example.com/admin
The following steps are needed to get the SimplyE Circulation Manager server installed and ready for configuration.
Domain Name for Circulation Manager
You will need to secure a domain for your instance of SimplyE. The established convention is https://library_name.simplye-state-abbreviation.org (com or net) You will need SSL certificates as well to establish secure communications with the applciation services.
DRM Token for Adobe Vendor ID
To enable a library to borrow ebooks from its various provider collections (Overdrive, Axis360, etc.) in the SimplyE apps, you need to register your library deployment with NYPL's SimplyE Adobe ID service. This allows your Circulation Manager to authorize users with the NYPL Adobe ID license. You'll need to contact NYPL staff using their SimplyE Slack site as mentioned above.
Here is a basic outline of the process:

  • Send a direct message (DM) to Leonard Richardson (@leonardr), supplying the following information (the information is the same as you will gather and enter into the Library configuration page below):
  • Leonard will create a shortname for your library, six characters long. The first two characters will be a two-character postal abbreviation.
  • Leonard will create a shared secret for your Circulation Manager to use in creating a token for use in borrow actions using the NYPL Adobe ID license.
  • During the process of adding the new library to the Circulation Manager, you'll run a script on the (or one of) your webapp servers to register the library with NYPL's service. See section Register a Library with the NYPL Adobe ID Service for details.
  • Send a direct message to Greg O'Neill with the following information:
    • The URL of the circulation manager and library (the library's feed URL: see section X.y below [TBD])
    • The barcode/user_id and PIN/password for the library's "good" test user
    • Potentially, information referencing the library's logo and color choice [Feedback needed: what is required/optional; is this only set in the library's Circulation Manager configuration?]
  • When the Test Flight mobile applications are updated and tested, Greg will respond back with links to/copies of the test applications.



Configuring the Circulation Manager through the Admin Interface
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 initial server settings automatically created for your system
  3. Configure Elasticsearch AWS Getting Started Guide
  4. Register the circulation manager with the metadata wranglerI need to add this to the guide.. Guide Document
  5. Configure library / libraries. Guide DocumentThis needs a document

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

  1. Configure a patron authentication technique (SIP or ILS) and associate it with the libraryDocument needed?
  2. Configure an analytics mechanism and associate it with the library.Document needed?
  3. Configure collections and associate them with the library. Guide Document
  4. Register your library with NYPL's library registry.


Service Status Controller
One piece that is not currently well integrated into the admin interface, but which you may find useful, is the `service_status` controller
e.g. https://circulation.librarysimplified.org/NYNYPL/service_status for NYPL this will run a self-test of the patron authentication mechanism and the credentials of all collections associated with the library

Anchor
_kb91icjrldg7
_kb91icjrldg7
Test Run

Anchor
_v9jpdelwe38h
_v9jpdelwe38h
Perform Web-Based System Configuration

  1. Log into the new Circulation Manager's administrative configuration panel:
    • Go to the admin panel using your URL (e.g. https://<your-circ-manager-url>/admin )
    • Scroll to the bottom of the initial entry screen to the "Create a new individual administrator" form.
    • Enter the email address and password for your first administrative user. You can create additional admin accounts in the configuration utility.
    • Click the submit button to create the first admin account.
    • At the resulting login page, enter the admin credentials you created above and click the Sign In button.
    • Click the Configuration link in the upper right corner of the admin panel.
    • You should see the main configuration page with eleven configuration sections in a left sidebar. Those configurations sections are:
      1. Libraries
      2. Collections
      3. Admin Authentication
      4. Patron Authentications
      5. Site Wide Settings
      6. Metadata
      7. Analytics
      8. CDN
      9. Search
      10. Discovery
  2. Verify the initial server settings created automatically for your installation:
    • Click the Sitewide Settings item in the left sidebar.
    • 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).
    • For this base testing deployment, no other site settings are necessary.
  3. Configure the Elasticsearch service integration for the Circulation Manager:
    • Click the Search sidebar item.
    • Click the Create a new search service item.
    • Enter a descriptive name for the service, such as "Elasticsearch indexing server"
    • Currently only the Elasticsearch server is supported, so the default Protocol item is appropriate.
    • Enter the URL to your Elasticsearch service:
      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.
    • Unless there is a local reason to change it, leave the default Elasticsearch index name as "circulation-works".
    • Click the Submit button.
  4. Create a Metadata Wrangler integration:
    • Click the Metadata sidebar item.
    • Click the Create a new metadata service item.
    • Enter a name for the shared Library Simplified Metadata Wrangler service; e.g., "NYPL Metadata Wrangler".
    • In the Protocol list, select the "Library Simplified Metadata Wrangler" item.
    • You can accept the supplied URL for the shared wrangler
    • Click the Submit button. 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.
  5. Create the first library:
    • 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.
  6. Create a test collection and assign it to the demo library:
    • Click the Collections sidebar item.
    • Click the Create a new collection item.
    • Enter a descriptive name that uniquely identifies the collection and makes it easy to find in potentially a long list of collections.
    • 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.
    • 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): [{+}http://oacontent.librarysimplified.org/works/sources/Plympton+

    • 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:
      1. In the Add Library dropdown, select the name of the test 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 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.
  7. 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.
    • Click the Patron Authentication sidebar item.
    • Click the Create a new patron authentication service item.
    • Again, give the service a descriptive name that is easy to identify in a long list of services.
    • Accept the default "Simple Authentication Provider" in the dropdown list for this test.
    • Enter a test user identifier; for a simulated 14-digit barcode, you might enter the following: 29999087654321.
    • Enter a test password, which in this case should actually be a PIN, something like: 0550.
    • In the Libraries dropdown item, select the test library you created.
    • Click the Add Library button at the bottom of the form.
    • Click the Submit button.

Anchor
_lojyman12rw8
_lojyman12rw8
Register a Library with the NYPL Adobe ID Service

As mentioned above, new libraries added to the Circulation Manager must be registered with NYPL in order for patrons using the SimplyE app to borrow books from their collection(s). After obtaining the library's shared secret from NYPL staff above (see DRM Token for Adobe Vendor ID on page three), log into the Circulation Manager application server and create a Short Client Token and register the library with the service.
[Steps to be added.]
bin/configuration/short_client_token_library_configuration --website-url="<website_url>" --vendor-id="NYPL" --short-name="<lib_shortcode>" --secret="<secret_from_NYPL>"

Anchor
_qm9oe4mp9x6a
_qm9oe4mp9x6a
Run Commands to Import the Test Collection

While the configuration of the collection above creates the database information needed to access the collection, and to contact to the metadata wrangler server at NYPL to provide additional/enhanced metadata if available, it does not actually result in books being added to the collection. The OPDS feed import option does not have a corresponding import script that is scheduled to run on the server. You will need to access the Circulation Manager host and execute the script manually.

Anchor
_njfg3fmb7euf
_njfg3fmb7euf
Log in to the Circulation Manager

When deploying the Circulation Manager host resources locally in VirtualBox or online using Linode.com, the instructions provided allow you to connect remotely to the host with a Vagrant command:
vagrant ssh
This will be the simplest way to connect. However, it isn't the most secure way to connect. For production servers, you should disable remote access to the host by the root user and enforce private-key-based access (with passphrase) only.
For deployments to Amazon Web Services, since this repository uses Ansible alone for AWS deployments, one should create a standard SSH connection. Future additions to the documentation will include specific instructions as needed.

Anchor
_pyekhfr2ckte
_pyekhfr2ckte
Run Scripts to Import the Collection

There are two Docker containers that provide Circulation Manager services: circ-scripts and circ-deploy. The circ-deploy container actually hosts the application; the circ-scripts container hosts the management scripts. Management scripts that are required to keep the Circulation Manager operating appropriately are already scheduled to run periodically.
However, the script which controls OPDS feed imports is not run automatically. To access the proper Docker container and execute the script, first connect to a console session inside the container. Issue the command:
sudo docker exec -it circ-scripts /bin/bash
Once you receive a command prompt in the container, you can begin the import process by running the following command:
../core/bin/run opds_import_monitor >> /var/log/cron.log 2>&1
The test collection, at the time of this writing, has about 70+ titles. Give the server fifteen minutes or so to complete importing the works from the feed.
Once the import process is complete, if you wish to review the import logs, execute the following command:
cat /var/log/libsimple/opds_import_monitor.log
After the title data is imported from the feed, the views of the collection may need to be "refreshed" before those titles will be available in the OPDS feed to the SimplyE app. However, the script to refresh the views only runs every 6 hours. To run the script manually, execute the following command:
../core/bin/run refresh_materialized_views >> /var/log/cron.log 2>&1
Once the "refresh" script is complete, you can return to the host by running the command:
exit

Anchor
_68xg7hxjuowq
_68xg7hxjuowq
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 in its primary interface. Lanes are automatically generated from the metadata included in an ebook data feed. However, the lanes presented can be customized. Customize the lanes configuration for a library using the web-based admin panel (as of version 2.1).
This section now needs a step-by-step demo of customizing the swim lanes in the Admin panel.
For previous Circulation Manager versions, you must configure lanes in a JSON-formatted configuration file. Specific elements and examples of lanes are documented in the official Simplifed wiki under LaneConfiguration. An example lane configuration file is provided in the files directory of the repository. Instructions to provide a configuration file in your test deployment are provided in the main README file.

Anchor
_249aa3m0u6tp
_249aa3m0u6tp
Configuring an Alternate URL in the SimplyE Mobile App

Once the system is configured and the test feed is imported, you can set up the generic SimplyE mobile app to point to your test library's collection by using a tap sequence to open up a hidden prompt.

  1. Open the SimplyE app on your device.
  2. Tap the menu icon.
  3. Tap the Settings item.
  4. In rapid succession, tap the Version entry eight times.
  5. Tap the Alternate URIs entry which appears.
  6. In the Feed URI field, enter the URL to the test library's OPDS feed; the feed will be of the following form, ending with the shortname mentioned above when creating the library settings:

http://hostname.example.com/shortname

  1. Click the Set button at the bottom of the form.
  2. Click the back arrow icon to go back to Settings.
  3. Click the menu icon.
  4. Click the Catalog item to display books in the test library's collection.

This manual mechanism is available for informally testing library collections. In production scenarios, each library created in the admin panel must be registered using the Discovery sidebar item and the Simplified Library Registry. The process of registering a library's circulation feed will enable the development team to include the library in the selector of available library feeds in the generic SimplyE mobile app. Do not register test libraries.