docs/RELEASE_NOTES_3_9.adoc

   1 = Evergreen 3.9 Release Notes =
   2 :toc:
   3 :numbered:
   4 :toclevels: 3
   5
   6 == Evergreen 3.9.0 ==
   7
   8 === Upgrade notes ===
   9
  10 ==== New Permissions ====
  11
  12 * UPLOAD_COVER_IMAGE
  13 * ADMIN_STAFF_PORTAL_PAGE
  14 * RUN_SIMPLE_REPORTS
  15
  16 ==== New Library Settings ====
  17
  18 * Custom jQuery for the OPAC
  19
  20 === New Features ===
  21
  22 ==== Administration ====
  23
  24 ===== Localized Templates Available for Action Triggers =====
  25
  26 This feature supplies the ability to create alternate templates for Action Triggers
  27 that will generate locale specific out for Action Triggers.  If you send notices in
  28 multiple languages, we recommend putting some words to that effect in your notice
  29 templates.  The template, message and message title can all be localized.  To use the
  30 feature the following new UI elements have been added:
  31
  32 - When you double-click on an Event Definition under Notifications / Action Triggers
  33   to edit it there will be a tab option for Edit Alternate Template if the reactor is
  34   ProcessTemplate, SendEmail or SendSMS.
  35 - In the Patron Registration and Patron Editor screens staff members may now select a
  36   locale for a patron and edit it in the Patron Preferred Language field.
  37 - Patrons may set their own locale in the My Account interface off the OPAC by going to
  38   Preferences -> Personal Information and setting the Preferred Language field.
  39
  40 The templates used on the Edit Definition tab are the defaults that are used if there are
  41 no alternate templates available that match the preferred language.  If alternate templates
  42 are available the system will use a locale that is an exact match and then if failing that
  43 use one where the language code matches and then fall back to the default one.
  44
  45 For example, if a patron has a locale of fr-CA and there are templates for both fr-CA and
  46 fr-FR it will use the fr-CA.  If the fr-CA template was deleted it would fall back on using
  47 the fr-FR for the patron since it at least shares the same base language.
  48
  49 Valid locales are the codes defined in the i18n_locale table in the config schema.
  50
  51 ===== Staged Search Tables and Functions Removed from Database =====
  52
  53 This release removes the asset.opac_visible_copies materialized view and
  54 search.query_parser_fts function from the Evergreen database.  They have been
  55 obsolete since staged search was eliminated in Evergreen 3.0.  Any custom code
  56 that relies on them should be updated accordingly.
  57
  58 ==== API ====
  59
  60 ===== array_accum Aggregate Removed =====
  61
  62 The custom `array_accum` aggregate function has been removed from the
  63 PostgreSQL database because it will need to be dropped and recreated
  64 with a different definition when upgrading to PostgreSQL version 14 or
  65 later.  Its functionality is also redundant with PostgreSQL's own
  66 `array_agg` function.
  67
  68 Sites that have custom code using Evergreen's `array_accum` function
  69 should alter their code to use `array_agg` instead.
  70
  71 ===== Removal of OpenILS::Utils::ISBN =====
  72
  73 Evergreen used to include a perl module called OpenILS::Utils::ISBN.
  74 This module provided a single subroutine, `isbn_upconvert`, which
  75 wrapped some behavior from the Business::ISBN module.  The module
  76 is no longer used in Evergreen code.  Any custom code that used it
  77 should be migrated to use Business::ISBN directly.
  78
  79 ==== Cataloging ====
  80
  81 ===== Custom Cover Image Uploader  =====
  82
  83 If configured for a given Evergreen instance, staff with the UPLOAD_COVER_IMAGE
  84 permission may upload a custom jacket/cover image for a given bibliographic
  85 record for display in the staff client and OPAC. This is done through the Other
  86 Actions -> Upload Cover Image command from the record details page in the staff
  87 interface.
  88
  89 ====== Note for system administrators ======
  90
  91 The following stanza needs to be added to eg_vhost.conf:
  92
  93 [source,conf]
  94 ----------------------------------------------------------------
  95 <Location /jacket-upload>
  96     SetHandler perl-script
  97     PerlHandler OpenILS::WWW::Vandelay::spool_jacket
  98     Options +ExecCGI
  99     Require all granted
 100 </Location>
 101 ----------------------------------------------------------------
 102
 103 and this to the open-ils.vandelay -> app_settings -> databases section of
 104 opensrf.xml:
 105
 106 [source,conf]
 107 ----------------------------------------------------------------
 108 <jackets>/openils/var/web/opac/extras/ac</jackets>
 109 ----------------------------------------------------------------
 110
 111 with the path appropriately adjusted for your installation. The Apache process
 112 will need write permissions for that directory.
 113
 114 Additionally, the following directories need to exist and be writable by the Apache process:
 115
 116 /openils/var/web/opac/extras/ac/jacket/large/r
 117 /openils/var/web/opac/extras/ac/jacket/medium/r
 118 /openils/var/web/opac/extras/ac/jacket/small/r
 119
 120 ==== Circulation ====
 121
 122 ===== Copy Inventory Date Improvements =====
 123
 124 This release fixes two bugs with copy inventory dates:
 125
 126  * https://bugs.launchpad.net/evergreen/+bug/1883171[duplicate entries for a copy in asset.latest_inventory table]
 127  * https://bugs.launchpad.net/evergreen/+bug/1940663[Staff users can update inventory dates on non-owned items]
 128
 129 In addition to fixing the above bugs, improvements are made to the implementation of the latest copy inventory feature so that it may be further expanded in the future.
 130
 131 ====== Technical Details for Developers and System Administrators ======
 132
 133 The following changes are made to the database, back end, and staff client user interface code:
 134
 135  * The data moves to a new table in the database, `asset.copy_inventory`.
 136  * The new data table is accessible via a new Fieldmapper object, `aci`.
 137  * The new data table has appropriate foreign keys and triggers to ensure data integrity and prevent duplicate entries.
 138  * The old data table, `asset.latest_inventory`, is now a view on the new table.
 139  * The Fieldmapper object `alci` is now read-only.
 140  * The `open-ils.circ.circulation.update_copy_inventory` method replaces the `open-ils.circ.circulation.update_latest_inventory` method.
 141  * The `open-ils.circ.circulation.update_copy_inventory` method inserts into the `asset.copy_inventory` table.
 142  * The `open-ils.circ.circulation.update_latest_inventory` method is removed.
 143  * The Item Status screen now uses `open-ils.circ.circulation.update_copy_inventory` to update a copy's inventory date.
 144  * The staff client Item Status screen now toasts success or failure as appropriate.  It previously only toasted success.
 145  * ngToast has also been added for a single record view in the Item Status screen.  This means that toasts can be added for other events.
 146  * The circulation back end code inserts into the `asset.copy_inventory` table when the do inventory modifier is used at check in.
 147  * An `asset.copy_inventory` entry is only added if the copy is at its "home," or owning, library or if the copy can float to the library where the inventory is being updated.
 148  * A Perl live test is added to verify back end functionality.
 149  * Pgtap tests are added to verify the schema and to verify database functionality.
 150
 151 The following items remain unchanged:
 152
 153  * The staff interface to add/update copy inventory dates remains the same:
 154    ** the Update Inventory option on the Checkin Modifiers menu
 155    ** the Update Inventory command on the Item Status Actions menu.
 156  * The staff client's Circulation and Item Status screens display data from the `alci` view object.
 157  * The `alci` object looks the same, so reports based on it should still work.
 158
 159 The motivation behind the changes beyond simply fixing the two bugs listed above is to allow for possible future expansion of the copy inventory feature.  The new table makes it easier to add new fields and to track inventory updates of a given copy over time.  While these changes do not constitute an inventory module, they should ease the implementation of such a module and assist in the preservation of the current data.
 160
 161 ==== Client ====
 162
 163 ===== Customizable Staff Portal =====
 164
 165 The staff portal / staff home page is now customizable. A new Local
 166 Administration interface, Staff Portal Page, allows staff users who
 167 have the new `ADMIN_STAFF_PORTAL_PAGE` permission to specify groups
 168 of Evergreen menu links, external links, catalog search widgets,
 169 and free text to display on the staff home page.
 170
 171 The portal customization is available only on the Angular version of
 172 the portal, so access to the AngularJS version is now redirected to
 173 the Angular one.
 174
 175 Different portal pages may be configured for different Organizational
 176 Units. The displayed portal page will depend on the staff user's
 177 workstation. The Organizational Unit tree will be walked up starting
 178 from the workstation until one or more `config.ui_staff_splash_page_entry`
 179 rows are found for the Organizational Unit. The set of entries for
 180 that Organizational Unit will constitute the entire splash page entries
 181 to display, i.e., it won't try to merge branch, system, and
 182 consortial-level entries.
 183
 184 The administration interface allows authorized to:
 185
 186 * create, modify, or delete portal page entries
 187 * clone a library's set of portal page entries to a different library
 188
 189 Portal page entries consist of the following fields:
 190
 191 * Entry Label: free text that displays on the portal page
 192 * Entry Type: Catalog Search, Header, Link, Menu Item, or Text and/or HTML
 193 * Entry Target URL: target of Link or Menu Item entries
 194 * Entry Text: Free text and limited HTML to display for Text/HTML entry types. HTML is sanitized to allow only basic formatting and link elements.
 195 * Entry Image URL: for specifying an icon to display with the portral entry.
 196 * Owner: the Organization Unit that owns the entry.
 197 * Page Column and Column Position: these control the positioning of the entry. The portal is styled so that three columns are displayed by default, as with the legacy hard-coded portal, but if the user chooses to define more than three columns, columns after the third will stack vertically as additional rows.
 198
 199 ====== Upgrade notes ======
 200
 201 This patch adds the following:
 202
 203   * New database table `config.ui_staff_splash_page_entry`. This stories the entries to display on the portal.
 204   * New database table `config.ui_staff_portal_page_entry_type`. This is a lookup table for entry types.
 205   * New permission `ADMIN_STAFF_PORTAL_PAGE`. This is implicitly available to stock Local and Global Administrator permission groups via the `EVERYTHING` permission.
 206   * New grid setting for the administration interface.
 207
 208
 209 ===== Org Selector Now Supports Entry Styling =====
 210
 211 The Org Selector now supports the ability to pass in an object composed of
 212 an array of Org Unit IDs and a function returning a CSS key value pair.
 213
 214 ==== OAI2 ====
 215
 216 ===== OAI-PMH Data Provider Support =====
 217
 218 Evergreen can now act as an OAI-PMH data provider, exposing the catalog to
 219 harvesting through the (https://www.openarchives.org/OAI/openarchivesprotocol.html[OAI2 protocol]).
 220
 221
 222 Entry points
 223 ++++++++++++
 224
 225 There are two: one for bibliographic records and one for authority records:
 226
 227     http://your-domain/opac/extras/oai/authority
 228     http://your-domain/opac/extras/oai/biblio
 229
 230 An example of a working URL on a system with an authority record with ID
 231 1:
 232
 233     http://your-domain/opac/extras/oai/authority?verb=GetRecord&identifier=oai:localhost:1&metadataPrefix=oai_dc
 234
 235 Setspec are not implemented
 236 +++++++++++++++++++++++++++
 237
 238 This is a work in progress and not enabled. The aim is to have the owning library determine the set hierarchy. The Concerto
 239 test database for example has a record with record ID #1. This record is so popular it has copies attached to library units
 240 "Example Branch 1", "Example Branch 2", "Example Branch 3", "Example Bookmobile 1" which is a child of Branch 3 and
 241 "Example Branch 4". This entire kinship is expressed as sets like so:
 242
 243 [source,xml]
 244 ----
 245 <header>
 246     ...
 247     <setSpec>CONS</setSpec>
 248     <setSpec>CONS:SYS1</setSpec>
 249     <setSpec>CONS:SYS2</setSpec>
 250     <setSpec>CONS:SYS1:BR1</setSpec>
 251     <setSpec>CONS:SYS1:BR2</setSpec>
 252     <setSpec>CONS:SYS2:BR3</setSpec>
 253     <setSpec>CONS:SYS2:BR4</setSpec>
 254     <setSpec>CONS:SYS2:BR3:BM1</setSpec>
 255 </header>
 256 ----
 257
 258 Likewise the setSpecs of authority records are derived from their browse axis ( Title, Author, Subject and Topic ).
 259
 260 Bibliographic mapping of assets to 852 subfields
 261 ++++++++++++++++++++++++++++++++++++++++++++++++
 262
 263 Certain attributes asset are placed into 852 subfields so:
 264
 265 |===
 266 | subfield code | asset resource
 267
 268 | a | location
 269 | b | owning_lib
 270 | c | callnumber
 271 | d | circlib
 272 | g | barcode
 273 | n | status
 274 |===
 275
 276 Thus the Concerto with record ID #1 will have it's 852 subfields expressed as:
 277
 278 [source,xml]
 279 ----
 280 <marc:datafield ind1="4" ind2=" " tag="852">
 281     <marc:subfield code="a">Stacks</marc:subfield>
 282     <marc:subfield code="b">BR4</marc:subfield>
 283     <marc:subfield code="c">ML 60 R100</marc:subfield>
 284     <marc:subfield code="d">BR4</marc:subfield>
 285     <marc:subfield code="g">CONC70000435</marc:subfield>
 286     <marc:subfield code="n">Checked out</marc:subfield>
 287 </marc:datafield>
 288 ----
 289
 290 This mapping can be customized and extended with static subfields:
 291
 292 [source,xml]
 293 ----
 294     <marc:subfield code="q">A constant value</marc:subfield>
 295 ----
 296
 297 Default configuration
 298 +++++++++++++++++++++
 299
 300 See comments in opensrf.xml (in the open-ils.supercat app_settings/oai element)
 301 for default configuration and customization instructions.
 302
 303 Upgrade Instructions
 304 ++++++++++++++++++++
 305 OAI support is not turned on by default. To enable it, edit the Apache
 306 configuration file `eg_vhost.conf` to uncomment the following
 307 section and restart Apache:
 308
 309 [source,conf]
 310 ----
 311 #<Location /opac/extras/oai>
 312 #    SetHandler perl-script
 313 #    PerlHandler OpenILS::WWW::SuperCat::OAI
 314 #    Options +ExecCGI
 315 #    PerlSendHeader On
 316 #    Require all granted
 317 #</Location>
 318 ----
 319
 320 ==== OPAC ====
 321
 322 ===== jQuery OPAC Library Setting  =====
 323
 324 A new setting entitled opac.patron.custom_jquery has been added to library settings. Using this does require that the ctx.want_jquery be uncommented and set to 1 (true) in the opac/parts/config.tt2 file.  Using this setting will allow OPACs to run jQuery without customizing server side templates.  For example adding the following:
 325
 326 $(document).ready(function(){ $("a:contains(Link 2)").text('Kafka'); });
 327
 328 Will change the text of 'Link 2' in the link bar to say 'Kafka'.  See the Evergreen WIKI (https://wiki.evergreen-ils.org/) for examples.
 329
 330 ==== Reports ====
 331
 332 ===== Simple Reports =====
 333
 334 This release includes a new Simple Reports reporting system focused on ease of
 335 use and simplicity that is available from the Administration menu of the
 336 staff client. Simple Reports can be restricted by staff permissions and
 337 access to the overall feature is granted through a new RUN_SIMPLE_REPORTS
 338 permission.
 339
 340 The Simple Reports interface is intended to provide an alternate access point
 341 for running reports in Evergreen and is not intended to replace the main
 342 Reports interface. In particular, users in need of complex reports should
 343 still make use of the main Reports interface.
 344
 345 To simplify report creation some fields are generated from multiple backend
 346 fields and other fields such as dates are repeated with multiple transforms
 347 pre-applied. Reports and schedules can be edited at any time as needed.
 348
 349 ==== SIP ====
 350
 351 ===== Adding Captured Hold Phone Notification Number to Checkin Response =====
 352
 353 Some third party systems can phone users when a SIP checkin captures
 354 an item they have on hold. Normally, to do this a patron information
 355 request is sent (message pair 63/64), but some systems will only look
 356 for it in the reply to the Checkin pair, 09/10. Because this is not
 357 a part of the SIP2 standard and exposes patron personal information
 358 when used indescriminately, it must be enabled by including the key
 359 `<phone_ext_on_msg10 enabled="true" />` in the "institution"
 360 section of `oils_sip.xml`.
 361
 362 ===== Upgrade Note =====
 363
 364 To use this feature, Evergreen administrators should upgrade to the
 365 latest version of `SIPServer`.
 366
 367 ==== Miscellaneous ====
 368
 369 * The patron record juvenile flag is now available to the checkout and
 370   items out print templates. (https://bugs.launchpad.net/evergreen/+bug/1830387[Bug 1830387])
 371 * The Notices / Action Triggers administration interface (under Local
 372   Administration) is ported to Angular. (https://bugs.launchpad.net/evergreen/+bug/1855780[Bug 1855780])
 373 * The Local Administration interface Shelving Location Order Editor is ported to Angular https://bugs.launchpad.net/evergreen/+bug/1846552[Bug 1846552])
 374 * Series Title is now a column option in the Holds Pull List (https://bugs.launchpad.net/evergreen/+bug/1863196[Bug 1863196])
 375 * Credit card payment approval code is now available to the Payment Receipt template (https://bugs.launchpad.net/evergreen/+bug/1865062[Bug 1865062])
 376 * There is a new widget to share a Carousel on an external site (https://bugs.launchpad.net/evergreen/+bug/1882982[Bug 1882982])
 377 * Item Status Circ History now includes original checkout workstation and staff (https://bugs.launchpad.net/evergreen/+bug/1919500[Bug 1919500])
 378 * The 520 Summary field is now more prominently displayed in the Bootstrap OPAC (https://bugs.launchpad.net/evergreen/+bug/1930614[Bug1930614])
 379 * It is now easier to customize the Boostrap OPAC topnav logo (https://bugs.launchpad.net/evergreen/+bug/1964963[Bug 1964963])
 380 * Improvements to Angular grid 'copy to clipboard' dialog (https://bugs.launchpad.net/evergreen/+bug/1958581[Bug 1958581])
 381 * Patron Notes now include Creation Date/Time and default to sorting by most recent created note (https://bugs.launchpad.net/evergreen/+bug/1956970[Bug 1956970])
 382 * 'Due date' field is now available under Show More Details in staff catalog search results (https://bugs.launchpad.net/evergreen/+bug/1955931[Bug 1955931])
 383 * Staff can add jQuery code in to a Library Setting to perform simple OPAC customizations (https://bugs.launchpad.net/evergreen/+bug/1849113[Bug 1849113])
 384 * Added API call to allow external carousel display (https://bugs.launchpad.net/evergreen/+bug/1951318[Bug 1951318])
 385
 386
 387
 388 Acknowledgments
 389 ---------------
 390 The Evergreen project would like to acknowledge the following
 391 organizations that commissioned developments in this release of
 392 Evergreen:
 393
 394 * CW MARS
 395 * Equinox Open Library Initiative
 396 * Evergreen Indiana
 397 * Linn-Benton Community College
 398 * Missouri Evergreen
 399 * NOBLE
 400 * Pioneer Library System
 401
 402 We would also like to thank the following individuals who contributed
 403 code, translations, documentations patches and tests to this release of
 404 Evergreen:
 405
 406 * MaryAnn Alexander
 407 * Jason Boyer
 408 * Dan Briem
 409 * Steven Callender
 410 * Galen Charlton
 411 * Garry Collum
 412 * Jeff Davis
 413 * Bill Erickson
 414 * Jason Etheridge
 415 * Lynn Floyd
 416 * Rogan Hamby
 417 * Blake Graham Henderson
 418 * Kyle Huckins
 419 * Angela Kilsdonk
 420 * Shula Link
 421 * Tiffany Little
 422 * Llewellyn Marshall
 423 * Terran McCanna
 424 * Gina Monti
 425 * Michele Morgan
 426 * Andrea Buntz Neiman
 427 * Jennifer Pringle
 428 * Jane Sandberg
 429 * Chris Sharp
 430 * Jason Stephenson
 431 * Josh Stompro
 432 * Mike Risher
 433 * Mike Rylander
 434 * Remington Steed
 435 * Lucien van Wouw
 436 * Jennifer Weston
 437
 438 We also thank the following organizations whose employees contributed
 439 patches:
 440
 441 * BC Libraries Coop
 442 * Bibliomation
 443 * Calvin College
 444 * Catalyte
 445 * CW MARS
 446 * Equinox Open Library Initiative
 447 * Georgia Public Library Service
 448 * Greater Clarks Hill Regional Library
 449 * Indiana State Library
 450 * International Institute of Social History
 451 * Kenton County Library
 452 * King County Library System
 453 * Lake Agassiz Regional Library
 454 * Linn Benton Communit College
 455 * MOBIUS
 456 * NOBLE
 457 * Sigio
 458 * Sitka
 459 * Westchester Library System
 460
 461 We regret any omissions.  If a contributor has been inadvertently
 462 missed, please open a bug at http://bugs.launchpad.net/evergreen/
 463 with a correction.
 464