1 == Ebook API integration ==
3 Evergreen supports integration with third-party APIs provided by OverDrive and
6 When ebook API integration is enabled, the following features are supported:
8 * Bibliographic records from these vendors that appear in your
9 public catalog will include vendor holdings and availability information.
10 * Patrons can check out and place holds on OverDrive and OneClickdigital ebook
11 titles from within the public catalog.
12 * When a user is logged in, the public catalog dashboard and My Account
13 interface will include information about that user's checkouts and holds for
16 WARNING: The ability to check out and place holds on ebook titles is an experimental
17 feature in 3.0. It is not recommended for production use without careful
20 For API integration to work, you need to request API access from the
21 vendor and configure your Evergreen system according to the instructions
22 below. You also need to configure the new `open-ils.ebook_api` service.
24 This feature assumes that you are importing MARC records supplied by the
25 vendor into your Evergreen system, using Vandelay or some other MARC
26 import method. This feature does not search the vendor's online
27 collections or automatically import vendor records into your system; it
28 merely augments records that are already in Evergreen.
30 A future Evergreen release will add the ability for users to check out
31 titles, place holds, etc., directly via the public catalog.
33 === Ebook API service configuration ===
34 This feature uses the new `open-ils.ebook_api` OpenSRF service. This
35 service must be configured in your `opensrf.xml` and `opensrf_core.xml`
36 config files for ebook API integration to work. See
37 `opensrf.xml.example` and `opensrf_core.xml.example` for guidance.
39 === OverDrive API integration ===
40 Before enabling OverDrive API integration, you will need to request API
41 access from OverDrive. OverDrive will provide the values to be used for
42 the following new org unit settings:
44 * *OverDrive Basic Token*: The basic token used for API client
45 authentication. To generate your basic token, combine your client
46 key and client secret provided by OverDrive into a single string
47 ("key:secret"), and then base64-encode that string. On Linux, you
48 can use the following command: `echo -n "key:secret" | base64 -`
49 * *OverDrive Account ID*: The account ID (a.k.a. library ID) for your
50 OverDrive API account.
51 * *OverDrive Website ID*: The website ID for your OverDrive API
53 * *OverDrive Authorization Name*: The authorization name (a.k.a.
54 library name) designated by OverDrive for your library. If your
55 OverDrive subscription includes multiple Evergreen libraries, you
56 will need to add a separate value for this setting for each
57 participating library.
58 * *OverDrive Password Required*: If your library's OverDrive
59 subscription requires the patron's PIN (password) to be provided
60 during patron authentication, set this setting to "true." If you do
61 not require the patron's PIN for OverDrive authentication, set this
62 setting to "false." (If set to "true," the password entered by a
63 patron when logging into the public catalog will be cached in plain text in
65 * *OverDrive Discovery API Base URI* and *OverDrive Circulation API
66 Base URI*: By default, Evergreen uses OverDrive's production API, so
67 you should not need to set a value for these settings. If you want
68 to use OverDrive's integration environment, you will need to add the
69 appropriate base URIs for the discovery and circulation APIs. See
70 OverDrive's developer documentation for details.
71 * *OverDrive Granted Authorization Redirect URI*: Evergreen does not
72 currently support granted authorization with OverDrive, so this
73 setting is not currently in use.
75 For more information, consult the
76 https://developer.overdrive.com/docs/getting-started[OverDrive API
79 To enable OverDrive API integration, adjust the following public catalog settings
82 * `ebook_api.enabled`: set to "true".
83 * `ebook_api.overdrive.enabled`: set to "true".
84 * `ebook_api.overdrive.base_uris`: list of regular expressions
85 matching OverDrive URLs found in the 856$9 field of older OverDrive
86 MARC records. As of fall 2016, OverDrive's URL format has changed,
87 and the record identifier is now found in the 037$a field of their
88 MARC records, with "OverDrive" in 037$b. Evergreen will check the
89 037 field for OverDrive record identifiers; if your system includes
90 older-style OverDrive records with the record identifier embedded in
91 the 856 URL, you need to specify URL patterns with this setting.
93 === OneClickdigital API integration ===
94 Before enabling OneClickdigital API integration, you will need to
95 request API access from OneClickdigital. OneClickdigital will provide
96 the values to be used for the following new org unit settings:
98 * *OneClickdigital Library ID*: The identifier assigned to your
99 library by OneClickdigital.
100 * *OneClickdigital Basic Token*: Your client authentication token,
101 supplied by OneClickdigital when you request access to their API.
103 For more information, consult the
104 http://developer.oneclickdigital.us/[OneClickdigital API documentation].
106 To enable OneClickdigital API integration, adjust the following public catalog
107 settings in `config.tt2`:
109 * `ebook_api.enabled`: set to "true".
110 * `ebook_api.oneclickdigital.enabled`: set to "true".
111 * `ebook_api.oneclickdigital.base_uris`: list of regular expressions
112 matching OneClickdigital URLs found in the 859$9 field of your MARC
113 records. Evergreen uses the patterns specified here to extract
114 record identifiers for OneClickdigital titles.
116 === Additional configuration ===
117 Evergreen communicates with third-party vendor APIs using the new
118 `OpenILS::Utils::HTTPClient` module. This module is configured using
119 settings in `opensrf.xml`. The default settings should work for most
120 environments by default, but you may need to specify a custom location
121 for the CA certificates installed on your server. You can also disable
122 SSL certificate verification on HTTPClient requests altogether, but
123 doing so is emphatically discouraged.