docs/RELEASE_NOTES_NEXT/Circulation/due_date_timezones.adoc

   1 Honor timezone of the acting library
   2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   3
   4 Summary
   5 +++++++
   6
   7 * Display day-granular due dates in the circulating library's timezone.
   8 * Only display the date portion of the due date for day-granular circulations.
   9 * Display the full timestamp, in the client's timezone rather than the circulation library's, for hourly circulations.
  10 * Provide infrastructure for more advanced formatting of timestamps.
  11 * Override the built-in AngularJS date filter with an implementation that uses moment.js, providing consistency and better standards compliance.
  12
  13 Upgrade note
  14 ++++++++++++
  15
  16 The following query will adjust all historical, unaged circulations so
  17 that if their due date field is pushed to the end of the day, it is done
  18 in the circulating library's time zone, and not the server time zone.
  19
  20 It is safe to run this after any change to library time zones.
  21
  22 Running this is not required, as no code before this change has
  23 depended on the time string of '23:59:59'.  It is also not necessary
  24 if all of your libraries are in the same time zone, and that time zone
  25 is the same as the database's configured time zone.
  26
  27 [source,sql]
  28 ----
  29 DO $$
  30 declare
  31     new_tz  text;
  32     ou_id   int;
  33 begin
  34     for ou_id in select id from actor.org_unit loop
  35         for new_tz in select oils_json_to_text(value) from actor.org_unit_ancestor_setting('lib.timezone',ou_id) loop
  36             if new_tz is not null then
  37                 update  action.circulation
  38                   set   due_date = (due_date::timestamp || ' ' || new_tz)::timestamptz
  39                   where circ_lib = ou_id
  40                         and substring((due_date at time zone new_tz)::time::text from 1 for 8) <> '23:59:59';
  41             end if;
  42         end loop;
  43     end loop;
  44 end;
  45 $$;
  46 ----
  47
  48 Details
  49 +++++++
  50
  51 This is a followup to the work done in bug 1485374, where we added the ability
  52 for the client to specify a timezone in which timestamps should be interpreted
  53 in business logic and the database.
  54
  55 Most specifically, this work focuses on circulation due dates and the closed
  56 date editor. Due dates, where displayed using stock templates (including
  57 receipt templates) and used for fine calculation, are now manipulated in the
  58 library's configured timezone. This is controlled by the new 'lib.timezone'
  59 YAOUS, loaded from the server when required. Additionally, closings are
  60 recorded in the library's timezone so that so that due date calculation is more
  61 accurate. The closed date editor is also taught how to display closings in the
  62 closed library's timezone. Closed date entries also explicitly record if they
  63 are a full day closing, or a multi-day closing. This significantly simplifies
  64 the editor, and may be useful in other contexts.
  65
  66 To accomplish this, we use the moment.js library and the moment-timezone addon.
  67 This is necessary because the stock AngularJS date filter does not understand
  68 locale-aware timezone values, which are required to support DST. A simple
  69 mapper translates the differences in format values from AngularJS date to
  70 moment.js.
  71
  72 Of special note are a set of new filters used for formatting timestamps under
  73 certain circumstances. The new egOrgDateInContext, egOrgDate, and egDueDate
  74 filters provide the functionality, and autogrid is enhanced to make use of
  75 these where applicable. egGrid and egGridField are also taught to accept
  76 default and field-specific options for applying date filters. These filters may
  77 be useful in other or related contexts.
  78
  79 The egDueDate filter, used for all existing displays of due date via Angular
  80 code, intentionally interprets timestamps in two different ways WRT timezone,
  81 based on the circulation duration. If the duration is day-granular (that is,
  82 the number of seconds in the duration is divisible by 86,400, or 24 hours worth
  83 of seconds) then the date is interpreted as being in the circulation library's
  84 timezone. If it is an hourly loan (any duration that does not meet the
  85 day-granular criterium) then it is instead displayed in the client's timezone,
  86 just as all other timestamps currently are, because of the work in 1485374.
  87
  88 The OPAC is adjusted to always display the due date in the circulating
  89 library's timezone. Because the OPAC displays only the date portion of the due
  90 date field, this difference is currently considered acceptable. If this proves
  91 to be a problem in the future, a minor adjustment can be made to match the
  92 egDueDate filter logic.
  93
  94 Now that due dates are globally stored in the configured timezone of the
  95 circulating library, the automatic adjustment to day-granular due dates needs
  96 to take those timezones into account.
  97
  98 An optional SQL command is provided by the upgrade script to retroactively
  99 adjust existing due dates after library configuration is complete.
 100
 101 This work, as with 1485374, was funded by SITKA, and we thank them for their
 102 partnership in making this happen!
 103