docs/RELEASE_NOTES_NEXT/Administration/phonelist.txt

   1 Release Notes for the Phonelist.pm Module
   2 =========================================
   3
   4 PhoneList.pm is a mod_perl module for Apache that works with Evergreen
   5 to generate callings lists for patron holds. It outputs a csv file
   6 that can be fed into an auto-dialer script to call patrons with little
   7 or no staff intervention.  It is accessed and configured via a special
   8 URL and passing any parameters as a ``Query String'' on the URL.  The
   9 parameters are listed in the table below.
  10
  11 .Parameters for the phonelist program:
  12 |=====================================
  13 | user |  Your Evergreen login. Typically your library's circ account. If you leave this off, you will be prompted to login.
  14 | passwd | The password for your Evergreen login. If you leave this off you will be prompted to login.
  15 | ws_ou | The ID of the system or branch you want to generate the list for (optional). If your account does not have the appropriate permissions for the location whose ID number you have entered, you will get an error.
  16 | skipemail | If present, skip patrons with email notification (optional).
  17 | addcount | Add a count of items on hold (optional). Only makes sense for holds.
  18 | overdue | Makes a list of patrons with overdues instead of holds. If an additional, numeric parameter is supplied, it will be used as the number of days overdue. If no such extra parameter is supplied, then the default of 14 days is used.
  19 |=====================================
  20
  21 The URL is
  22
  23 `https://your.evergreen-server.tld/phonelist`
  24
  25 A couple of examples follow:
  26
  27 `https://your.evergreen-server.tld/phonelist?user=circuser&passwd=password&skipemail
  28
  29 The above example would sign in as user circuser with password of
  30 ``password'' and get a list of patrons with holds to call who do not
  31 have email notification turned on. It would run at whatever branch is
  32 normally associated with circuser, which would likely be MVC or
  33 central site. (Note: There is no actual circuser account, it is used
  34 here for illustration purposes only.)
  35
  36 `https://your.evergreen-server.tld/phonelist?skipemail`
  37
  38 The above example would do more or less the same, but you would be
  39 prompted by your browser for the user name and password.
  40
  41 If your browser or download script support it, you may also use
  42 conventional HTTP authentication parameters.
  43
  44 `https://user:password@your.evergreen-server.tld/phonelist?overdue&ws_ou=2`
  45
  46 The above logs in as ``user'' with ``password'' and runs overdues for location ID 2.
  47
  48 The following sections provide more information on getting what you want in your output.
  49
  50 Adding Parameters
  51 -----------------
  52
  53 If you are not familiar with HTTP/URL query strings, the format is
  54 quite simple.
  55
  56 You add parameters to the end of the URL, the first parameter is
  57 separated from the URL page with a question mark (``?'') character. If
  58 the parameter is to be given an extra value, then that value follows
  59 the parameter name after an equals sign (``=''). Subsequent parameters
  60 are separated from the previous parameter by an ampersand (``&'').
  61
  62 Here is an example with 1 parameter that has no value:
  63
  64 `https://your.evergreen-server.tld/phonelist?skipemail`
  65
  66 An example of 1 argument with a value:
  67
  68 `https://your.evergreen-server.tld/phonelist?overdue=21`
  69
  70 An example of 2 arguments, 1 with a value and 1 without:
  71
  72 `https://your.evergreen-server.tld/phonelist?overdue=21&skipemail`
  73
  74 Any misspelled or parameters not listed in the table above will be
  75 ignored by the program.
  76
  77 Output
  78 ------
  79
  80 On a successful run, the program will return a CSV file named
  81 phone.csv. Depending on your browser or settings you will alternately
  82 be prompted to open or save the file. Your browser may also
  83 automatically save the file in your Downloads or other designated
  84 folder. You should be able to open this CSV file in Excel, LibreOffice
  85 Base, any other spread sheet program, or a text editor.
  86
  87 If you have made a mistake and have mistyped your user name or
  88 password, or if you supply a ws_ou parameter with an ID where your
  89 user name does not have permission to look up holds or overdue
  90 information, then you will get an error returned in your browser.
  91
  92 Should your browser appear to do absolutely nothing at all. This is
  93 normal. When there is no information for you to download, the server
  94 will return a 200 NO CONTENT message to your browser. Most browsers
  95 respond to this message by doing nothing at all. It is possible for
  96 there to be no information for you to retrieve if you added the
  97 `skipemail` option and all of your notices for that day were sent via
  98 email, or if you ran this in the morning and then again in the
  99 afternoon and there was no new information to gather.
 100
 101 The program does indicate that it has already looked at a particular
 102 hold or overdue and will skip it on later runs. This prevents
 103 duplicates to the same patron in the same run. It will, however,
 104 create a ``duplicate'' for the same patron if a different copy is put
 105 on hold for that patron in between two runs.
 106
 107 The specific content of the CSV file will vary if you are looking at
 108 holds or overdues. The specific contents are described in the
 109 appropriate sections below.
 110
 111 Holds
 112 -----
 113
 114 The `phonelist` program will return a list of patrons with copies on
 115 hold by default, so long as you do not use the `overdue`
 116 parameter. You may optionally get a number of items that patron
 117 currently has on hold by adding the `addcount` parameter.
 118
 119 As always, you can add the skipemail parameter to skip patrons with
 120 email notifications of their overdues, [#0.5.Skipping patrons with
 121 email notification of holds|outline as described below].
 122
 123 .Columns in the holds CSV file:
 124 |=====================================
 125 | Name | Patron's name first and last.
 126 | Phone | Patron's phone number.
 127 | Barcode | Patron's barcode.
 128 | Count | Number of copies on hold, if `addcount` parameter is used, otherwise this column is not present in the file.
 129 |=====================================
 130
 131 Overdues
 132 --------
 133
 134 If you add the `overdue` parameter, you can get a list of patrons with
 135 overdue copies instead of a list of patrons with copies on the hold
 136 shelf. By default, this will give you a list of patrons with copies
 137 that are 14 days overdue. If you'd like to specify a different number
 138 of days you can add the number after the parameter with an equals
 139 sign:
 140
 141 `https://your.evergreen-server.tld/phonelist?overdue=21&ws_ou=2`
 142
 143 The above will retrieve a list of patrons who have items that are 21
 144 days overdue at the location with ID of 2.
 145
 146 The number of days is an exact lookup. This means that the program
 147 will look only at patrons who have items exactly 14 days or exactly
 148 the number of days specified overdue. It does not pull up any that are
 149 less than or greater than the number of days specified.
 150
 151 As always, you can add the skipemail parameter to skip patrons with
 152 email notifications of their overdues, [#0.5.Skipping patrons with
 153 email notification of holds|outline as described below].
 154
 155 .Columns in the overdues CSV file:
 156 |=================================
 157 | Name | Patron's name first and last.
 158 | Phone | Patron's phone number.
 159 | Barcode | Patron's barcode.
 160 | Titles | A colon-separated list of titles that the patron has overdue.
 161 |=================================
 162
 163 Skipping patrons with email notification of holds
 164 -------------------------------------------------
 165
 166 Skipping patrons who have email notification for their holds or
 167 overdues is very simple. You just need to add the `skipemail`
 168 parameter on the URL query string. Doing so will produce the list
 169 without the patrons who have email notification for overdues, or for
 170 all of their holds. Please note that if a patron has multiple holds
 171 available, and even one of these holds requests a phone-only
 172 notification, then that patron will still show on the list. For this
 173 option to exclude a patron from the holds list, the patron must
 174 request email notification on all of their current holds. In practice,
 175 we find that this is usually the case.
 176
 177 Using the ws_ou parameter
 178 -------------------------
 179
 180 Generally, you will not need to use the ws_ou parameter when using the
 181 phonelist program. The phonelist will look up the branch where your
 182 login account works and use that location when generating the list.
 183 However, if you are part of a multi-branch systems in a consortium,
 184 then the ws_ou parameter will be of interest to you.  You can use it
 185 to specify which branch, or the whole system, you wish to search when
 186 running the program.
 187
 188 Automating the download
 189 -----------------------
 190
 191 If you'd like to automate the download of these files, you should be
 192 able to do so using any HTTP programming toolkit. Your client must
 193 accept cookies and follow any redirects in order to function.