LP#1596595 Hold targeter release notes
[Evergreen.git] / docs / RELEASE_NOTES_NEXT / Administration / hold-targeter.adoc
1 Batch Hold Targeter Speed-up and New Features
2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3
4 Adds a new open-ils.hold-targeter service, supporting new targeting options
5 and runtime optimizations to speed up targeting.  The service is launched
6 from a new targeting script, hold_targeter_v2.pl (default location:
7 /openils/bin/hold_targeter_v2.pl).
8
9 This code has no effect on the existing hold targeter, which is still
10 available as of this release and functions as before.
11
12 New Features/Options
13 ++++++++++++++++++++
14
15 * Adds a global configuration flag 'circ.holds.retarget_interval' for 
16   setting the hold retarget interval.
17
18 * --target-all option forces the targeter to process all active
19   holds, regardless of when they were last targeted.
20
21 * --retarget-interval option make is possible to override the new
22   'circ.holds.retarget_interval' setting via the command line 
23   when calling the hold targeter.
24
25 * --skip-viable option causes the hold targeter to avoid modifying 
26   the currently targeted copy (i.e. the copy on the pull list) for holds 
27   that target a viable (capturable) copy.  
28   
29   For skipped holds, no entry is added to the unfulfilled_hold_list.
30   The set of potential copies (hold copy maps) are refreshed for all
31   processed holds, regardless of target viability.
32
33   This option is useful for 1.) finding targets for holds that require 
34   new targets and 2.) adding new/modified copies to the potential copy 
35   lists (for op capture) more frequently than you may want to do full
36   retargeting of all holds.
37
38 * --newest-first option processes holds in reverse order of request_time,
39   so that newer holds are (re)targeted first.  This is primarily useful
40   when a large backlog of old, un-targetable holds exist.  With 
41   --newest-first, the older holds will be processed last.
42
43 * --parallel option overrides the parallel settings found in opensrf.xml
44   for simpler modification and testing.
45
46 * --lockfile option allows the caller to specifiy a lock file instead
47   of using the default /tmp/hold_targeter-LOCK
48
49 * --verbose option prints progress info to STDOUT, showing the number of
50   holds processed per parallel targeter instance.
51
52 * When configured, hold target loops cycle through all org units (with 
53   targetable copies) instead of repeatedly targeting copies at the pickup
54   library when multiple targetable copies exist at the pickup library.
55
56 * When configured, hold target loops prioritize (targetable) org units
57   first by the number of previous target attempts, then by their 
58   weight/proximity.  This effectivy back-fills org units that had no
59   targetable copies during earlier target loops so that they are 
60   targeted as many times as other org units (to the extent possible, 
61   anyway).
62
63 Examples
64 ++++++++
65
66 * Traditional daily hold targeter with a value set for 
67   'circ.holds.retarget_interval'.
68
69 [code,sh]
70 --------------------------------------------------------------------------
71 /openils/bin/hold_targeter_v2.pl
72 --------------------------------------------------------------------------
73
74 * (Re)target non-viable holds twice a day, only processing holds that 
75   have never been targeter or those that have not been re-targeted in
76   the last 12 hours.
77
78 [code,sh]
79 --------------------------------------------------------------------------
80 /openils/bin/hold_targeter_v2.pl --skp-viable --retarget-interval "12h"
81 --------------------------------------------------------------------------
82
83 * (Re)target non-viable holds twice a day, processing all holds regardles
84   of when or if they were targeted before, running 3 targeters in
85   parallel.
86
87 [code,sh]
88 --------------------------------------------------------------------------
89 /openils/bin/hold_targeter_v2.pl --skip-viable --target-all --parallel 3
90 --------------------------------------------------------------------------
91