LP#1673857: stamp schema update
[working/Evergreen.git] / docs / RELEASE_NOTES_2_3.adoc
1 Release notes
2 =============
3 :toc:
4 :numbered:
5
6 Upgrade notes
7 -------------
8
9 Log Protect (redaction)
10 ~~~~~~~~~~~~~~~~~~~~~~~
11 To prevent sensitive information such as passwords from being logged
12 in general activity logs, add the following XML chunk to the bottom of
13 `opensrf_core.xml`, just inside the `<config>` section:
14
15 [source, xml]
16 ----------------------------------------------------------------
17   ...
18   </routers>
19   <shared> <!-- new block starts here -->
20     <log_protect>
21       <match_string>open-ils.auth.authenticate.verify</match_string>
22       <match_string>open-ils.auth.authenticate.complete</match_string>
23       <match_string>open-ils.auth_proxy.login</match_string>
24       <match_string>open-ils.actor.patron.password_reset.commit</match_string>
25       <match_string>open-ils.actor.user.password</match_string>
26       <match_string>open-ils.actor.user.username</match_string>
27       <match_string>open-ils.actor.user.email</match_string>
28       <match_string>open-ils.actor.patron.update</match_string>
29       <match_string>open-ils.cstore.direct.actor.user.create</match_string>
30       <match_string>open-ils.cstore.direct.actor.user.update</match_string>
31       <match_string>open-ils.cstore.direct.actor.user.delete</match_string>
32     </log_protect>
33   </shared> <!-- new block ends here -->
34 </config>
35 ----------------------------------------------------------------
36
37 EDI Order Template Updates
38 ~~~~~~~~~~~~~~~~~~~~~~~~~~
39 An updated EDI order template is now part of the stock data.  To avoid 
40 clobbering potentially functional EDI templates, no upgrade script was 
41 included to automatically upgrade existing templates.  To upgrade to the
42 newest template:
43
44 [source, sql]
45 ----------------------------------------------------------------
46 UPDATE action_trigger.event_definition SET template = 
47 $$
48 ...
49 $$ WHERE id = 23;
50
51 /* 
52 Use the template value for event definition 23 (line 7995) in 
53 950.data.seed-values.sql as the contents (...) of the above command.
54 */
55 ----------------------------------------------------------------
56
57 New features
58 ------------
59
60 Acquisitions
61 ~~~~~~~~~~~~
62
63 ACQ Invoice Inline Lineitem Search and Add
64 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
65
66 The Invoice UI is now composed of two tabs, the main invoice tab and a new
67 Search tab.  The search tab consists of a subset of the Acquisitions unified
68 search interface.  The goal is to allow users to search for lineitems to
69 invoice.  Search results may be added directly to the growing invoice.  A number of small usability features are included.
70
71 Features
72 ++++++++
73
74     * Option (default) to limit searches to invoiceable items.  
75         ** These are lineitems that are not cancelled, have at least one invoiceable copy, linked to a PO whose provider matches that of the current invoice, and are not already linked to the current invoice.
76     * Search defaults to last-run search (on workstation).
77     * New Lineitem Detail filter options
78     * Sort searches by lineitem number (default) and title.
79     * There is a new Expected Cost field which includes both the total invoiced cost plus the anticipated cost of lineitems as they are added.
80     * New Price per Copy field
81     * Lineitem count field
82     * Show / Hide Invoice details button.  Details are displayed by default, but hidden when the user enters the search tab.  From there it remains hidden until manually shown (or a new invoice is opened).
83     * A new "Save & Clear" button which saves the current invoice then clears the invoice display to create a new invoice.
84     * Provider, shipper, and receiver fields are auto-populated from the first-added invoice data (when not already set).
85     * Totals are now read-only, since they are derived from existing data (and are informational only).
86
87
88 EDI Invoices
89 ^^^^^^^^^^^^
90
91 The same setup that is required today for retrieving and reacting to EDI Order
92 Response messages (ORDRSP) will also react to Invoices (INVOIC).
93
94 This essentially means you must have a Provider (acq.provider) configured with
95 an EDI Account (acq.edi_account) containing login credentials for a vendor, you must have the edi_webrick service running (EDI translator), and you must have
96 the edi_pusher script run periodically by cron.
97
98 An open Evergreen invoice will be created for a each EDI Invoice message.
99 Evergreen invoice entries will be created for each lineitem detected in the
100 EDI message if that lineitem can be linked to a known Evergreen lineitem in
101 your system.  An Evergreen invoice item will be created for a whole-invoice
102 tax.
103
104 Enriched EDI
105 ^^^^^^^^^^^^
106
107 Support for Enriched EDI with copy-level data via EDI in ORDER messages.
108
109 Encumbrance-only Rollover
110 ^^^^^^^^^^^^^^^^^^^^^^^^^
111
112 A new Library Setting allows the year-end close-out operation to roll over
113 encumbrances while dumping any unspent money.
114
115 Fund Report
116 ^^^^^^^^^^^
117
118 A new IDL reporter view that provides summary information for funds for
119 reporting. The resulting table looks like a fund with four additional fields:
120 allocated_total, spent_total, encumbrance_total, and combined_balance.
121
122 EDI Fetching and Parsing Enhancements / Repairs
123 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
124 This release includes various improvements to how Evergreen processes
125 vendor EDI responses, including order responses and invoices.  Changes
126 include architectural improvements as well as new features.
127
128 Bug Fixes
129 +++++++++
130
131 * Improved order response handling for cancelled items.
132 * Deleting fund debits (encumbrances) for cancelled items.
133 * Extracting invoice date
134 * Invoices include quantity and amount paid (in addition to billed) to reduce
135   manual staff data entry
136 * Proper handling of previously-cancelled (e.g. back-ordered) invoiced items.
137
138 Architectural improvements
139 ++++++++++++++++++++++++++
140
141 For EDI parsing, the Ruby libraries, Ruby HTTP gateway, and Business::EDI Perl
142 modules are no longer needed.  They have been replaced with a single Perl
143 module which handles EDI parsing.
144
145 This reduces the complexity of the fetching and parsing layer.  Though the Ruby
146 libraries and Ruby HTTP gateway are still needed for outbound EDI (for now), 
147 the Perl Business::EDI modules are no longer needed at all, so they are no 
148 longer installed.
149
150 EDI order template improvements (no SQL upgrade script!)
151 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
152
153 Improved template for EDI purchase orders.  This theoretically just
154 works better where the old template worked.  Corrections made for
155 interactions with ULS, Midwest Tape, Baker & Taylor, and Recorded Books
156 especially.  GIR segments in the right place.
157
158 And also the template is just more maintainable now.
159
160 **THERE IS NO UPGRADE SCRIPT INCLUDED**.  Sites using EDI may not
161 necessarily want to mess with what they already have working.
162
163 If you want the changes, and maybe you do, especially if you're doing
164 enriched ordering and/or ordering from the vendors listed above, you can
165 extract the template changes easily enough yourself from the
166 950.data.seed-values.sql file.  See Upgrade Notes above.
167
168 OPAC
169 ~~~~
170
171 TPAC: Simplified CSS Color Customization
172 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
173 CSS colors are now defined as a pair of Template::Toolkit files,
174 `Open-ILS/src/templates/opac/css/styles.css.tt2` and
175 `Open-ILS/src/templates/opac/parts/css/colors.tt2`. Evergreen administrators
176 can customize the color scheme for a given skin by copying `colors.tt2` into a
177 template override directory and adjusting the colors as desired.
178
179 Change required to eg_vhost.conf
180 ++++++++++++++++++++++++++++++++
181 To enable Apache to pass the CSS file to the Template::Toolkit handler, you
182 must remove `.css` from the list of file extensions that should not be passed
183 to a handler in `eg_vhost.conf` as follows:
184
185 .From
186 ------------------------------------------------------------------------------
187 <LocationMatch ^/eg/.*(\.js|\.css|\.html|\.xhtml|\.xml|\.jpg|\.png|\.gif)$>
188     SetHandler None
189 </LocationMatch>
190 ------------------------------------------------------------------------------
191
192 .To
193 ------------------------------------------------------------------------------
194 <LocationMatch ^/eg/.*(\.js|\.html|\.xhtml|\.xml|\.jpg|\.png|\.gif)$>
195     SetHandler None
196 </LocationMatch>
197 ------------------------------------------------------------------------------
198
199 After making this change, restart Apache to make the change take effect.
200
201
202 Add to Permanent Bookbag
203 ^^^^^^^^^^^^^^^^^^^^^^^^
204
205 TPAC was modified to allow a logged-in user to add records from search
206 results and record summary screens to their permanent bookbags rather
207 than to a temporary bookbag that goes away when logged out.
208
209 Bookbag Selection Menu
210 ++++++++++++++++++++++
211
212 The search results and record summary screens were modified so that
213 the "Add to my list" will show a menu when moused over by a logged-in
214 user.  This menu will display the option to add to a temporary
215 bookbag, the user's default list (if any), up to ten of the user's
216 other bookbags, a "See all" option to allow the user to choose one of
217 the bags not on the menu, and to create a new list and add the record
218 to it.
219
220 Choosing the temporary list from the menu will add the record to the
221 temporary my list as TPAC does before the addition of this feature.
222
223 Choosing a named list will add the record to the chosen list.
224
225 Choosing "See all" or "Add to new list" will take the user to their My
226 Lists page.  (The only difference being that "See all" will actually
227 list all of the user's bookbags if they have more than the current
228 limit.)  The My Lists page will have a new button "Add to this list"
229 next to each of their existing lists.  In addition, if the user
230 creates a new list on this screen, the selected record will
231 automatically be added to this new list.
232
233 You can tell all of the above is working if you are redirected to your
234 search results or record summary after adding to a list.  If there was
235 a problem, you will get either an error page or will see your My Lists
236 page.
237
238 Designating a Default Bookbag/list
239 ++++++++++++++++++++++++++++++++++
240
241 The user's My List screen has had a 'Make Default List' button added
242 for each list.  Clicking the button will cause that list to be
243 registered as the user's default list.  This is the list that will be
244 added to when a user chooses the Default List option on the Add to my
245 list menu in search or record summary.
246
247 The current default list has a 'Remove Default List' button next to
248 it.  Clicking this button will unset the default status of the list
249 and return to a state of having no default list.
250
251 One handy way that users may want to use this feature is to create a
252 new list, and then designate it as the default.  This list could then
253 be used to add records from searches based on a current topic of
254 interest.  Changing the default list is so easy that users may want to
255 do so when changing search topics in order to keep their results
256 better organized.
257
258 A Note on CSS Styles
259 ++++++++++++++++++++
260
261 If a user has a bookbag with an overly long name, the end of it will
262 jut out past the right margin of the menu in Firefox and several other
263 browsers.  To change this behavior, you may want to edit the `.popmenu
264 li:hover li a` css entry in `web/css/skin/default/opac/style.css` by
265 adding an `overflow` property.  If you desire to have the longer names
266 clipped to the size of the menu then add `overflow: hidden`.  If you
267 prefer to have a scroll bar for oversized entries, then add `overflow:
268 auto`.
269
270
271 Warn When Adding to a Temporary Bookbag
272 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
273
274 TPAC has been modified so that a user will see a warning before adding
275 a record to a temporary bookbag.  This message serves to inform the
276 user that they are adding to a temporary list that will disappear when
277 their session ends.
278
279 A new org. unit setting has been added,
280 opac.patron.temporary_list_warn, that will enable this warning when
281 set.  Sites may choose not to display this warning.
282
283 The user may also set a preference in their search preferences to
284 disable this warning.  The setting only works when a user is logged
285 in, of course.
286
287 Kid's OPAC
288 ^^^^^^^^^^
289
290 The Kids OPAC (KPAC) is a public catalog search that was designed for children
291 and teens.  Colorful menu items,large buttons, and simple navigation make this
292 an appealing search interface for kids.  Librarians will appreciate the flexible
293 configuration of the KPAC.  Librarians can create links to canned search results
294 for kids and can apply these links by branch.  The KPAC uses the same infrastructure
295 as the Template Toolkit OPAC (TPAC), the adult catalog search, so you can easily
296 extend the KPAC using the code that already exists in the TPAC.  Finally, third
297 party content, such as reader reviews, can be integrated into the KPAC.
298
299
300 Locale picker
301 ^^^^^^^^^^^^^
302
303 In situations in which more than a single locale is configured, the TPAC header
304 will display a locale picker based on the registered locales. 
305
306 Hidden Place Hold Links
307 ^^^^^^^^^^^^^^^^^^^^^^^^^
308
309 The title-level 'Place Hold' link in TPAC will be hidden on the search result
310 and record summary screens when there are no holdable copies on the bib. This
311 is based on the copy, status and location holdable flags.
312
313 When enabled in config.tt2, the 'Place Holds' link in TPAC will also be hidden
314 if copies are available in the search location. 
315
316 Library Selectors in Advanced Searches
317 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
318
319 The library selector is now available on the numeric and expert search pages.
320
321 Journal Title Search
322 ^^^^^^^^^^^^^^^^^^^^
323
324 A journal title search is now available as a stock TPAC filter.
325
326 Public Patron Notes
327 ^^^^^^^^^^^^^^^^^^^
328
329 Public patron notes are now visible in the 'Account Summary' box of 'My
330 Account'.
331
332 Auto-Override Permissible Patron Hold Fail Events
333 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
334
335 A new Library Setting is available that tells TPAC to automatically override
336 hold placement failure events in cases where the patron has the permission to
337 do so. The goal is to skip the confirmation step previously required by patrons
338 when overriding a TPAC hold.
339
340 Cataloging
341 ~~~~~~~~~~
342
343 Z39.50 Source Attributes Management Interface
344 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
345
346 There is a new interface for managing Z39.50 attributes on a Z39.50
347 source.  The interface is linked from each source name in the Z39.50
348 Source administrative interface.
349
350 Cloning
351 +++++++
352
353 In addition to attribute creation, deletion, and editing, it's also 
354 possible to clone a set of attributes from one source into another.
355 When cloning, any attributes present in the cloned source that are
356 not present in the destination source are copied into the destination 
357 source.
358
359 Vandelay (MARC Import/Export) Copy Overlay
360 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
361
362 Vandelay Item Attributes (Cataloging -> MARC Import / 
363 Export -> Import Item Attribute Definitions) contains 
364 a new field called "Overlay Match ID".  The presence of data 
365 in this field extracted from an import-item copy indicates 
366 to the Vandelay import process that a copy overlay is requested 
367 instead of new copy creation.  The value for the field is the 
368 copy id for bib record queues and the ACQ lineitem_detail ID for 
369 Acquisitions Queues.  For either type of queue, however, overlay 
370 occurs against a real copy (asset.copy).  In the ACQ queue case, 
371 we use the lineitem_detail ID because this is the data ACQ 
372 providers and sub-systems will have access to.
373
374 When a match point ID value is a set and a matching copy is found, 
375 the values extracted from the inbound copy data are used to replace 
376 values on the existing found copy, including the call-number label.  
377 Any fields on the inbound copy that are empty are ignored.
378
379 One use case for this feature are shelf-ready items produced by a 
380 3rd-party (e.g. ACQ provider) and delivered to the library via MARC
381 file for upload.  The file might contain improved MARC bibliographic
382 data as well as real barcodes (i.e. not temporary ACQ generated 
383 barcodes) for the copies already purchased through the vendor.
384
385 Permission
386 ++++++++++
387
388 This adds a new permission called IMPORT_OVERLAY_COPY which is 
389 required to perform the copy overlay step.
390
391 Regardless of permission, it is not possible to overlay values on
392 a copy unless the imported bib record links (creates/overlays/merges)
393 to/with the owning bib record for the copy to be overlaid.  This is 
394 both for security and removal of a potent foot-gun.
395
396 Circulation
397 ~~~~~~~~~~~
398
399 Simplified Hold Pull List
400 ^^^^^^^^^^^^^^^^^^^^^^^^^
401
402 There is a new hold pull list interface based on the Flattener service that's
403 designed to perform faster than existing pull list interfaces, both in staff
404 client display and printing.
405
406 Sorting
407 +++++++
408
409 You can sort on any one column by clicking on it.  Click again to reverse
410 direction.  This is typical of similar interfaces.
411
412 Now you can also sort by multiple columns.  Right click the column headers of
413 the grid in the pull list interface to get a dialog that allows you to sort
414 by multiple columns, in any order.
415
416 Column Picking
417 ++++++++++++++
418
419 The same dialog that allows you to choose multiple sort columns (accessed by
420 right clicking any column header) also allows you to toggle the display of any
421 column available to the pull list on or off.
422
423 Persistence
424 +++++++++++
425
426 Once saved, your changes in this dialog persist for your user account.  Column
427 display, display order, and `sorting choices affect printing as well as
428 displayed output.
429
430 Administration
431 ~~~~~~~~~~~~~~
432
433 Search Filter Groups
434 ^^^^^^^^^^^^^^^^^^^^
435
436 Search filter groups support the collection of free-form search queries into
437 named groups of named filters which can be applied to searches.  The purpose 
438 is to allow systems to fine tune filters in the catalog.
439
440 Editing the groups and their entries is done in the staff client at
441 Admin -> Local Administration -> Search Filter Groups.
442
443 Example
444 +++++++
445
446 Consider a new filter called "reading_level".  It uses a combination of 
447 MARC audience and shelving location to differentiate items.  It might have
448 entries that look like this:
449
450 Children's Materials => audience(a,b,c) locations(1,2,3,4,5,6,7)
451
452 Young Adult => audience(j,d) locations(5,6,7,8,9,10)
453
454 Adult => audience(e,f,g, ) -locations(1,2,3,4,5,6,7,8,9)
455
456 Using the filter in a template
457 ++++++++++++++++++++++++++++++
458
459 [source, html]
460 ---------------------------------------------------
461 <span>[% ctx.filter_groups.reading_level.label %]</span>
462 <span>
463 [%
464     INCLUDE 'opac/parts/filter_group_selector.tt2'
465     filter_group='reading_level'
466     none_ok=1
467     none_label=l('All')
468 %]
469 </span>
470 ---------------------------------------------------
471
472 Standing Penalty CAPTURE and FULFILL Blocks
473 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
474
475 This feature adds two additional types of standing penalty blocks to manage
476 holds. 
477
478 When a user has a standing penalty containing 'CAPTURE' in the block list, the
479 user can place holds (pending no 'HOLD' block), but no holds for the user will
480 be captured. This is effectively a policy-based freeze of the hold.
481
482 Users that have penalties with 'FULFILL' in the block list will be able to
483 place holds and have their holds captured (i.e. delivered) but will not be able
484 to check out the captured holds. This is basically a way to get patrons in to
485 pay outstanding balances.
486
487 Copy Location Additions to Circulation Policies
488 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
489
490 Similar to circulation modifiers, circ policies can now be based on copy
491 location. This also adds copy location to the circ matrix weights and to circ
492 limit sets.
493
494 Staff Client
495 ~~~~~~~~~~~~
496
497 XULRunner / Firefox
498 ^^^^^^^^^^^^^^^^^^^
499 Support for later versions of XULRunner is included, which means that later
500 improvements to XULRunner can be taken advantage of. This also means that the
501 Firefox extension mode works in Firefox 3.6+, though some frequent tweaking
502 will be needed due to the rapid Firefox major release schedule.
503
504 The majority of the actual changes are backend changes, but there are some
505 significant things to note for local customizations.
506
507 Remote XUL
508 ++++++++++
509 Remote XUL no longer works in XULRunner/Firefox 4+, but to work around it a
510 custom extension now creates an oils:// wrapper. Within the staff client that
511 wrapper contains a "remote" host, from which server-side XUL can be loaded.
512
513 Custom XUL pages stored on the server will need to reference the new wrapper
514 to function.
515
516 As a note: The new wrapper is used for all OPAC access and only talks SSL.
517
518 enablePrivilege
519 +++++++++++++++
520 The enablePrivilege command that would allow code to access various protected
521 functionality is no longer available. Any code that depended upon it will need
522 to be adjusted to use the oils:// wrapper created for Remote XUL.
523
524 Cookies
525 +++++++
526 Unfortunately, the oils:// wrapper has one less than useful effect. Any
527 JavaScript loaded via it loses access to cookies. This is most notable when you
528 are dealing with authtoken cookies. This only applies to JavaScript, however,
529 and the server can still see the cookies when it gets requests.
530
531 As a workaround you can load the data stash and fetch authtokens via it instead.
532 This should always work when using the oils:// wrapper due to the elevated
533 permission set it gets (nearly, if not equal to, local XUL).
534
535 url_prefix
536 ++++++++++
537 Finally, as a useful feature, the url_prefix function is now slightly easier to
538 use. Instead of needing to reference urls.SOMETHING you can instead just put the
539 SOMETHING at the start of the url to prefix:
540
541 url_prefix('SOMETHING/stuff.html')
542
543 In this case SOMETHING can be terminated by the end of the string or up to the
544 first instance of a slash (/), question mark (?), or pipe (|). The pipe is a
545 special case and is removed during the replacement.
546
547 For example, if urls.REPLACE were set to 'oils://remote/replace':
548
549 url_prefix('REPLACE/stuff') becomes 'oils://remote/replace/stuff'
550 url_prefix('REPLACE?query') becomes 'oils://remote/replace?query'
551 url_prefix('REPLACE|ment') becomes 'oils://remote/replacement'
552
553 The pipe is intended for cases where the urls entry may or may not already
554 contain a query string, say for differences between OPACs where one requires
555 that something be passed into the query string, but the other uses a path
556 component instead.
557
558 New Operator Change Features
559 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
560
561 The operator change dialog has a new dropdown allowing the selection of a
562 Temporary, Staff, or Permanent authtoken. The first option provides a temporary
563 operator change as has typically been done through this menu item. 'Staff' uses
564 a normal staff login authtoken for a multi-hour timeout. 'Permanent' is a staff
565 change that disregards the previous login instead of allowing it to be
566 recovered by using the menu item again.
567
568 Additional Work Log Entries
569 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
570
571 Entries for bill payment and hold placement are now available in the 'Work Log'.
572
573 SIP
574 ~~~
575
576 Support for credit card payment type and fine items details
577 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
578
579 Support is now available to create a credit card payment type in the SIP Fee
580 Paid message. There is also now support for SIP clients to retrieve and
581 display a detailed/itemized list of billings to the patron.
582
583 Staff Client Initial Hostname
584 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
585
586 For fresh installs of the staff client a common issue is people remembering
587 what hostname to specify. If you are building your own staff clients you can
588 now fill this in automatically.
589
590 You can specify this when configuring Evergreen with a new configure option:
591
592 --with-initialhost=example.org
593
594 It is also possible to specify when building the staff client itself using the
595 INITIAL_HOST variable:
596
597 make INITIAL_HOST=example.org build