Docs: ebook api integrations from release notes

Signed-off-by: Jane Sandberg <sandbej@linnbenton.edu>

diff --git a/docs/admin/ebook_api.adoc b/docs/admin/ebook_api.adoc
new file mode 100644 (file)
index 0000000..9767f8c
--- /dev/null
+++ b/docs/admin/ebook_api.adoc
@@ -0,0 +1,119 @@
+Ebook API integration
+---------------------
+
+Evergreen 2.12 supports partial integration with third-party APIs
+provided by OverDrive and OneClickdigital.  When ebook API integration
+is enabled, bibliographic records from these vendors that appear in your
+public catalog will include vendor holdings and availability information.  Also,
+when a user is logged in, the public catalog dashboard and My Account interface
+will include information about that user's checkouts and holds for
+supported vendors.
+
+For API integration to work, you need to request API access from the
+vendor and configure your Evergreen system according to the instructions
+below.  You also need to configure the new `open-ils.ebook_api` service.
+
+This feature assumes that you are importing MARC records supplied by the
+vendor into your Evergreen system, using Vandelay or some other MARC
+import method.  This feature does not search the vendor's online
+collections or automatically import vendor records into your system; it
+merely augments records that are already in Evergreen.
+
+A future Evergreen release will add the ability for users to check out
+titles, place holds, etc., directly via the public catalog.
+
+Ebook API service configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This feature uses the new `open-ils.ebook_api` OpenSRF service.  This
+service must be configured in your `opensrf.xml` and `opensrf_core.xml`
+config files for ebook API integration to work.  See
+`opensrf.xml.example` and `opensrf_core.xml.example` for guidance.
+
+OverDrive API integration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Before enabling OverDrive API integration, you will need to request API
+access from OverDrive.  OverDrive will provide the values to be used for
+the following new org unit settings:
+
+  * *OverDrive Basic Token*: The basic token used for API client
+    authentication.  To generate your basic token, combine your client
+    key and client secret provided by OverDrive into a single string
+    ("key:secret"), and then base64-encode that string.  On Linux, you
+    can use the following command: `echo -n "key:secret" | base64 -`
+  * *OverDrive Account ID*: The account ID (a.k.a. library ID) for your
+    OverDrive API account.
+  * *OverDrive Website ID*: The website ID for your OverDrive API
+    account.
+  * *OverDrive Authorization Name*: The authorization name (a.k.a.
+    library name) designated by OverDrive for your library.  If your
+    OverDrive subscription includes multiple Evergreen libraries, you
+    will need to add a separate value for this setting for each
+    participating library.
+  * *OverDrive Password Required*: If your library's OverDrive
+    subscription requires the patron's PIN (password) to be provided
+    during patron authentication, set this setting to "true."  If you do
+    not require the patron's PIN for OverDrive authentication, set this
+    setting to "false."  (If set to "true," the password entered by a
+    patron when logging into the public catalog will be cached in plain text in
+    memcached.)
+  * *OverDrive Discovery API Base URI* and *OverDrive Circulation API
+    Base URI*: By default, Evergreen uses OverDrive's production API, so
+    you should not need to set a value for these settings.  If you want
+    to use OverDrive's integration environment, you will need to add the
+    appropriate base URIs for the discovery and circulation APIs.  See
+    OverDrive's developer documentation for details.
+  * *OverDrive Granted Authorization Redirect URI*: Evergreen does not
+    currently support granted authorization with OverDrive, so this
+    setting is not currently in use.
+
+For more information, consult the
+https://developer.overdrive.com/docs/getting-started[OverDrive API
+documentation].
+
+To enable OverDrive API integration, adjust the following public catalog settings
+in `config.tt2`:
+
+  * `ebook_api.enabled`: set to "true".
+  * `ebook_api.overdrive.enabled`: set to "true".
+  * `ebook_api.overdrive.base_uris`: list of regular expressions
+    matching OverDrive URLs found in the 856$9 field of older OverDrive
+    MARC records.  As of fall 2016, OverDrive's URL format has changed,
+    and the record identifier is now found in the 037$a field of their
+    MARC records, with "OverDrive" in 037$b.  Evergreen will check the
+    037 field for OverDrive record identifiers; if your system includes
+    older-style OverDrive records with the record identifier embedded in
+    the 856 URL, you need to specify URL patterns with this setting.
+
+OneClickdigital API integration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Before enabling OneClickdigital API integration, you will need to
+request API access from OneClickdigital.  OneClickdigital will provide
+the values to be used for the following new org unit settings:
+
+  * *OneClickdigital Library ID*: The identifier assigned to your
+    library by OneClickdigital.
+  * *OneClickdigital Basic Token*: Your client authentication token,
+    supplied by OneClickdigital when you request access to their API.
+
+For more information, consult the
+http://developer.oneclickdigital.us/[OneClickdigital API documentation].
+
+To enable OneClickdigital API integration, adjust the following public catalog
+settings in `config.tt2`:
+
+  * `ebook_api.enabled`: set to "true".
+  * `ebook_api.oneclickdigital.enabled`: set to "true".
+  * `ebook_api.oneclickdigital.base_uris`: list of regular expressions
+    matching OneClickdigital URLs found in the 859$9 field of your MARC
+    records.  Evergreen uses the patterns specified here to extract
+    record identifiers for OneClickdigital titles.
+
+Additional configuration
+~~~~~~~~~~~~~~~~~~~~~~~~
+Evergreen communicates with third-party vendor APIs using the new
+`OpenILS::Utils::HTTPClient` module.  This module is configured using
+settings in `opensrf.xml`.  The default settings should work for most
+environments by default, but you may need to specify a custom location
+for the CA certificates installed on your server.  You can also disable
+SSL certificate verification on HTTPClient requests altogether, but
+doing so is emphatically discouraged.

diff --git a/docs/opac/ebook_transactions.adoc b/docs/opac/ebook_transactions.adoc
index 020e60a..8d16d6f 100644 (file)
--- a/docs/opac/ebook_transactions.adoc
+++ b/docs/opac/ebook_transactions.adoc
@@ -1,12 +1,12 @@
-Ebook transactions
-------------------
+Electronic resources in the catalog
+-----------------------------------
 
-This release adds support for checking out and placing holds on
-OverDrive and OneClickdigital ebook titles from within the public
-catalog.  (This extends the partial integration with third-party APIs
-that was included in Evergreen 2.12.)
+Checking out and placing holds
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This is an experimental feature.  It is not recommended for production
+Evergreen supports checking out and placing holds on
+OverDrive and OneClickdigital ebook titles from within the public
+catalog.  This is an experimental feature.  It is not recommended for production
 use without careful testing.
 
 When ebook integration is enabled, a "Check Out E-Item" link will be
@@ -25,9 +25,9 @@ holds, download already-checked-out titles, and cancel holds.
 For API integration to work, you need to request API access from the
 vendor, and the vendor must have a way of authenticating your patrons.
 Your Evergreen system also needs to be configured for ebook API
-integration, following the instructions in the
-https://evergreen-ils.org/documentation/release/RELEASE_NOTES_2_12.html#_public_catalog[Evergreen
-2.12 release notes].
+integration, following the instructions in the command line system
+administration manual
+
 
 This feature assumes that you are importing MARC records supplied by the
 vendor into your Evergreen system, using Vandelay or some other MARC

diff --git a/docs/root_command_line_admin.adoc b/docs/root_command_line_admin.adoc
index 28e6c48..5b0de34 100644 (file)
--- a/docs/root_command_line_admin.adoc
+++ b/docs/root_command_line_admin.adoc
@@ -114,6 +114,8 @@ include::admin_initial_setup/troubleshooting_tpac.adoc[]
 
 :leveloffset: 0
 
+include::admin/ebook_api.adoc[]
+
 include::admin/audio_alerts.adoc[]
 
 include::opac/new_skin_customizations.adoc[]

diff --git a/docs/root_opac.adoc b/docs/root_opac.adoc
index 863688f..09185bc 100644 (file)
--- a/docs/root_opac.adoc
+++ b/docs/root_opac.adoc
@@ -41,6 +41,8 @@ include::opac/linked_libraries.adoc[]
 
 :leveloffset: -1
 
+include::opac/ebook_transactions.adoc[]
+
 include::opac/kids_opac.adoc[]
 
 include::opac/opensearch.adoc[]
@@ -49,6 +51,7 @@ include::opac/visibility_on_the_web.adoc[]
 
 :leveloffset: 0
 
+
 include::opac/sitemap.adoc[]
 
 See the Command Line System Administration Manual for details about