From 5e85cc276497e1976ab49427515af0b0ffe8e853 Mon Sep 17 00:00:00 2001 From: Jane Sandberg Date: Mon, 26 Oct 2020 09:24:10 -0700 Subject: [PATCH] Docs: adding information about 3.6 features from the release notes Signed-off-by: Jane Sandberg --- docs/antora.yml | 1 + docs/modules/admin/pages/actiontriggers.adoc | 69 +++++++++++++++++- docs/modules/admin_initial_setup/nav.adoc | 1 + .../pages/bootstrap_opac.adoc | 29 ++++++++ docs/modules/integrations/_attributes.adoc | 4 + docs/modules/integrations/nav.adoc | 5 ++ docs/modules/integrations/pages/ezproxy.adoc | 29 ++++++++ .../integrations/pages/introduction.adoc | 6 ++ .../integrations/pages/patron-api.adoc | 34 +++++++++ docs/modules/integrations/pages/rfid.adoc | 73 +++++++++++++++++++ docs/modules/opac/nav.adoc | 1 - 11 files changed, 250 insertions(+), 2 deletions(-) create mode 100644 docs/modules/admin_initial_setup/pages/bootstrap_opac.adoc create mode 100644 docs/modules/integrations/_attributes.adoc create mode 100644 docs/modules/integrations/nav.adoc create mode 100644 docs/modules/integrations/pages/ezproxy.adoc create mode 100644 docs/modules/integrations/pages/introduction.adoc create mode 100644 docs/modules/integrations/pages/patron-api.adoc create mode 100644 docs/modules/integrations/pages/rfid.adoc diff --git a/docs/antora.yml b/docs/antora.yml index d1febd680f..3c87987900 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -14,6 +14,7 @@ nav: - modules/circulation/nav.adoc - modules/reports/nav.adoc - modules/opac/nav.adoc +- modules/integrations/nav.adoc - modules/development/nav.adoc - modules/api/nav.adoc - modules/appendix/nav.adoc diff --git a/docs/modules/admin/pages/actiontriggers.adoc b/docs/modules/admin/pages/actiontriggers.adoc index 27b8ebaf19..a7ecb3eedb 100644 --- a/docs/modules/admin/pages/actiontriggers.adoc +++ b/docs/modules/admin/pages/actiontriggers.adoc @@ -195,6 +195,73 @@ Reactors link the trigger definition to the action to be carried out. You may also create, edit and delete Reactors. Just remember that there must be an associated subroutine or module in the Reactor Perl module. +==== CallHTTP Reactor ==== + +This Action/Trigger reactor module allows an Evergreen administrator to +create event defintions that use HTTP (or HTTPS) to contact external services +and let them know that something has happened in Evergreen. + +For instance, a discovery layer can be informed when a bib record is updated +or when a user's barcode changes. + +===== CallHTTP Reactor Template Syntax ===== + +The new reactor module uses a template to define its behavior. While the +template is processed by Template Toolkit, as with any A/T templates, its +output format is new to Evergreen. + +The template should output data that can be parsed by the Config::General Perl +module. See: https://metacpan.org/pod/Config::General + +Top level settings should include the HTTP *method* and the *url*. + +A block called *Headers* can be used to supply arbitrary HTTP headers. + +A block called *Parameters* can be used to append CGI parameters to the URL, +most useful for GET form submission. Repeated parameters are allowed. If +this block is used, the URL should /not/ contain any parameters, use one or +the other. + +A HEREDOC called *content* can be used with POST or PUT to send an arbitrary block +of content to the remote server. + +If the requested URL requires Basic or Digest authentication, the template can +include top level configuration parameters to supply a *user*, *password*, *realm*, +and hostname:port *location*. + +A default user agent string of "EvergreenReactor/1.0" is used when sending requests. +This can be overridden using the top level *agent* setting. + +Here is an example template that could be used by a definition attached to the +*bib.edit* hook: + +[source,conf] +---- +method post # Valid values are post, get, put, delete, head +url https://example.com/api/incoming-update +agent MySpecialAgent/0.1 + +user updater +password uPd4t3StufF +realm "Secret area" +location example.com:443 + + + Accept-Language en + + + + type bib + id [% target.id %] + + +content <` stanza in Evergreen's eg_vhost configuration +file. In particular, you will need to allow access to from your EZProxy server, +fill in the base uri of your EZProxy server, and add a secret to the +_OILSRemoteAuthEZProxySecret_ variable. +. Restart Apache. +. Edit the EZProxy user.txt file. You will likely want to add a stanza such +as the following: + +.Sample user.txt stanza +---- +::CGI=http://your-evergreen-catalog.com/api/ezproxy?url=^R +::Ticket +MD5 +Expired; Deny expiredticket.htm +/Ticket +---- + +When this feature is enabled, users will see an Evergreen-based login screen. +You may customize the look and feel of this login screen by editing the relevant +template toolkit files. + diff --git a/docs/modules/integrations/pages/introduction.adoc b/docs/modules/integrations/pages/introduction.adoc new file mode 100644 index 0000000000..04f25a2c47 --- /dev/null +++ b/docs/modules/integrations/pages/introduction.adoc @@ -0,0 +1,6 @@ += Introduction = +:toc: + +Evergreen integrates smoothly with a number of other software products. + + diff --git a/docs/modules/integrations/pages/patron-api.adoc b/docs/modules/integrations/pages/patron-api.adoc new file mode 100644 index 0000000000..4a4b13d50f --- /dev/null +++ b/docs/modules/integrations/pages/patron-api.adoc @@ -0,0 +1,34 @@ += "PatronAPI" authentication = + +Evergreen now supports the III "PatronAPI" scheme for authenticating +patrons and supplying some information about them. + +To enable this, you will need to: + +. Add a new User Activity Type to Evergreen for PatronAPI authentications. +. Add a new Remote Authentication Profile to Evergreen. You will probably want +to use `PatronAPI` as the name. +. Edit the `` stanza in Evergreen's eg_vhost configuration +file. In particular, you will need to allow access to it from the server(s) +wanting to make PatronAPI requests, determine whether to enable the PatronAPI +"dump" feature, and specify whether users can be identified by username +or barcode. +. Restart Apache. +. Update the PatronAPI client to use https://your.evergreen.server/api/patronapi + as its base URL. + +Example PatronAPI URLs look something like this: + +.PatronAPI URLs +---- +# test a patron's PIN: +https://evergreen.example.org/api/patronapi/USERNAME/PASSWORD/pintest + +# dump some information about the patron. Note that this +# does _not_ require the the patron's password be supplied. +https://evergreen.example.org/api/patronapi/USERNAME/dump +---- + +The responses for the `pintest` and `dump` actions are specified by +Template Toolkit templates under (e.g.) `/openils/var/templates/remoteauth`. + diff --git a/docs/modules/integrations/pages/rfid.adoc b/docs/modules/integrations/pages/rfid.adoc new file mode 100644 index 0000000000..8c1f48eabc --- /dev/null +++ b/docs/modules/integrations/pages/rfid.adoc @@ -0,0 +1,73 @@ += RFID Product Integration = + +== Evergreen Integration with PV Supa GoodStuff RFID Reader == + +=== Introduction === + +This feature enables the Evergreen staff client to "talk" to the PV Supa Goodstuff RFID reader so that libraries can utilize PV Supa Goodstuff's RFID technology when checking items in and out. + +=== Administration === + +To use PV Supa Goodstuff, you must add code to the Admin module that Evergreen can use to identify the reader. + + +. Click *Admin* -> *Workstation Admin* -> *Server Add-ons*. + +. Enter the code, pv_supa_goodstuff, to identify PV Supa Goodstuff in the *Active Server Add-Ons* field. + +. Click *Update Active Add-Ons*. + +. Look at the next field, *Add-on Preferences*. Enter information in the *GoodStuff* tab. + +. Check the *Enabled* check box to enable this add-on. + +. Enter the *IP/Hostname* of the hardware. + +. Enter the *port*. + +. Click *Update*. + + + +=== Using RFID at the Circulation Desk === + +RFID functionality is available in the Circulation module via the check-out interface, the check-out function in the patron account, and the check-in interface. + + +From the *Check-Out* interface (F1): + +. Check the RFID checkbox if your library cards have embedded RFID chips that Evergreen can use to retrieve the patron barcode. RFID check boxes appear only if appropriate code words have been added in the Server Add-Ons. + +. Place the patron's library card and/or item(s) on the PV Supa Goodstuff Reader. Evergreen will take you to the patron's account. If item(s) with RFID chips have also been placed on the reader, and the corresponding checkbox is checked, then Evergreen will scan the item(s) into the patron's account. + +NOTE: RFID check boxes are sticky, so if you have checked an RFID box once, then it will continue to be checked when you re-open the interface. + +NOTE: If you do not use RFID chips to retrieve patrons' accounts, then leave the RFID box unchecked. You can scan a patron barcode with a barcode scanner, and Evergreen will retrieve the patron data without using the RFID feature. From the patron's account, Evergreen can check out items using the RFID reader. See the next section for details. + +. Click *Done* to complete the transaction, or close the window. + + + + +From the Check-Out tab in a patron's record: + + +. Open a patron's record, and stack the item(s) to be checked out on the RFID reader. To retrieve item data using the RFID chips embedded in the item barcodes, click the *RFID* check box at the bottom of the patron account. When this box is checked, Evergreen will read the item(s) that are stacked on the RFID reader, check out the item(s), and disable the security bits. + + +. Click *Done* to complete the transaction, or close the window. + +NOTE: Evergreen pop-up messages, such as an Alert Message or Item Already Circulating may appear during transactions. Two new dialogs specific to PV Supa Goodstuff may also appear. One dialog, Incomplete Sets, allows you to continue checking out an incomplete set, such as a CD collection, or you can ask the hardware to rescan the RFID tags to look again for a full set. The second dialog allows you to manually attempt to set or unset the security bit on an item if the automatic attempt failed. + + + + +From the *Check In* interface: + +. Click the *RFID* check box. + +. Place the items on the PV Supa Goodstuff Reader. + +. Evergreen will tell the reader to check in the item(s) and enable the security bits. The item(s) appear in a list on the screen. + + diff --git a/docs/modules/opac/nav.adoc b/docs/modules/opac/nav.adoc index 6787fc0c8a..33681a1e46 100644 --- a/docs/modules/opac/nav.adoc +++ b/docs/modules/opac/nav.adoc @@ -9,4 +9,3 @@ ** xref:opac:linked_libraries.adoc[Library Information Pages] ** xref:opac:opensearch.adoc[Adding Evergreen Search to Web Browsers] ** xref:opac:search_form.adoc[Adding an Evergreen search form to a web page] - -- 2.43.2