--- /dev/null
+Release Notes for the Phonelist.pm Module
+=========================================
+
+PhoneList.pm is a mod_perl module for Apache that works with Evergreen
+to generate callings lists for patron holds. It outputs a csv file
+that can be fed into an auto-dialer script to call patrons with little
+or no staff intervention. It is accessed and configured via a special
+URL and passing any parameters as a ``Query String'' on the URL. The
+parameters are listed in the table below.
+
+.Parameters for the phonelist program:
+|=====================================
+| user | Your Evergreen login. Typically your library's circ account. If you leave this off, you will be prompted to login.
+| passwd | The password for your Evergreen login. If you leave this off you will be prompted to login.
+| 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.
+| skipemail | If present, skip patrons with email notification (optional).
+| addcount | Add a count of items on hold (optional). Only makes sense for holds.
+| 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.
+|=====================================
+
+The URL is
+
+`https://your.evergreen-server.tld/phonelist`
+
+A couple of examples follow:
+
+`https://your.evergreen-server.tld/phonelist?user=circuser&passwd=password&skipemail
+
+The above example would sign in as user circuser with password of
+``password'' and get a list of patrons with holds to call who do not
+have email notification turned on. It would run at whatever branch is
+normally associated with circuser, which would likely be MVC or
+central site. (Note: There is no actual circuser account, it is used
+here for illustration purposes only.)
+
+`https://your.evergreen-server.tld/phonelist?skipemail`
+
+The above example would do more or less the same, but you would be
+prompted by your browser for the user name and password.
+
+If your browser or download script support it, you may also use
+conventional HTTP authentication parameters.
+
+`https://user:password@your.evergreen-server.tld/phonelist?overdue&ws_ou=2`
+
+The above logs in as ``user'' with ``password'' and runs overdues for location ID 2.
+
+The following sections provide more information on getting what you want in your output.
+
+Adding Parameters
+-----------------
+
+If you are not familiar with HTTP/URL query strings, the format is
+quite simple.
+
+You add parameters to the end of the URL, the first parameter is
+separated from the URL page with a question mark (``?'') character. If
+the parameter is to be given an extra value, then that value follows
+the parameter name after an equals sign (``=''). Subsequent parameters
+are separated from the previous parameter by an ampersand (``&'').
+
+Here is an example with 1 parameter that has no value:
+
+`https://your.evergreen-server.tld/phonelist?skipemail`
+
+An example of 1 argument with a value:
+
+`https://your.evergreen-server.tld/phonelist?overdue=21`
+
+An example of 2 arguments, 1 with a value and 1 without:
+
+`https://your.evergreen-server.tld/phonelist?overdue=21&skipemail`
+
+Any misspelled or parameters not listed in the table above will be
+ignored by the program.
+
+Output
+------
+
+On a successful run, the program will return a CSV file named
+phone.csv. Depending on your browser or settings you will alternately
+be prompted to open or save the file. Your browser may also
+automatically save the file in your Downloads or other designated
+folder. You should be able to open this CSV file in Excel, LibreOffice
+Base, any other spread sheet program, or a text editor.
+
+If you have made a mistake and have mistyped your user name or
+password, or if you supply a ws_ou parameter with an ID where your
+user name does not have permission to look up holds or overdue
+information, then you will get an error returned in your browser.
+
+Should your browser appear to do absolutely nothing at all. This is
+normal. When there is no information for you to download, the server
+will return a 200 NO CONTENT message to your browser. Most browsers
+respond to this message by doing nothing at all. It is possible for
+there to be no information for you to retrieve if you added the
+`skipemail` option and all of your notices for that day were sent via
+email, or if you ran this in the morning and then again in the
+afternoon and there was no new information to gather.
+
+The program does indicate that it has already looked at a particular
+hold or overdue and will skip it on later runs. This prevents
+duplicates to the same patron in the same run. It will, however,
+create a ``duplicate'' for the same patron if a different copy is put
+on hold for that patron in between two runs.
+
+The specific content of the CSV file will vary if you are looking at
+holds or overdues. The specific contents are described in the
+appropriate sections below.
+
+Holds
+-----
+
+The `phonelist` program will return a list of patrons with copies on
+hold by default, so long as you do not use the `overdue`
+parameter. You may optionally get a number of items that patron
+currently has on hold by adding the `addcount` parameter.
+
+As always, you can add the skipemail parameter to skip patrons with
+email notifications of their overdues, [#0.5.Skipping patrons with
+email notification of holds|outline as described below].
+
+.Columns in the holds CSV file:
+|=====================================
+| Name | Patron's name first and last.
+| Phone | Patron's phone number.
+| Barcode | Patron's barcode.
+| Count | Number of copies on hold, if `addcount` parameter is used, otherwise this column is not present in the file.
+|=====================================
+
+Overdues
+--------
+
+If you add the `overdue` parameter, you can get a list of patrons with
+overdue copies instead of a list of patrons with copies on the hold
+shelf. By default, this will give you a list of patrons with copies
+that are 14 days overdue. If you'd like to specify a different number
+of days you can add the number after the parameter with an equals
+sign:
+
+`https://your.evergreen-server.tld/phonelist?overdue=21&ws_ou=2`
+
+The above will retrieve a list of patrons who have items that are 21
+days overdue at the location with ID of 2.
+
+The number of days is an exact lookup. This means that the program
+will look only at patrons who have items exactly 14 days or exactly
+the number of days specified overdue. It does not pull up any that are
+less than or greater than the number of days specified.
+
+As always, you can add the skipemail parameter to skip patrons with
+email notifications of their overdues, [#0.5.Skipping patrons with
+email notification of holds|outline as described below].
+
+.Columns in the overdues CSV file:
+|=================================
+| Name | Patron's name first and last.
+| Phone | Patron's phone number.
+| Barcode | Patron's barcode.
+| Titles | A colon-separated list of titles that the patron has overdue.
+|=================================
+
+Skipping patrons with email notification of holds
+-------------------------------------------------
+
+Skipping patrons who have email notification for their holds or
+overdues is very simple. You just need to add the `skipemail`
+parameter on the URL query string. Doing so will produce the list
+without the patrons who have email notification for overdues, or for
+all of their holds. Please note that if a patron has multiple holds
+available, and even one of these holds requests a phone-only
+notification, then that patron will still show on the list. For this
+option to exclude a patron from the holds list, the patron must
+request email notification on all of their current holds. In practice,
+we find that this is usually the case.
+
+Using the ws_ou parameter
+-------------------------
+
+Generally, you will not need to use the ws_ou parameter when using the
+phonelist program. The phonelist will look up the branch where your
+login account works and use that location when generating the list.
+However, if you are part of a multi-branch systems in a consortium,
+then the ws_ou parameter will be of interest to you. You can use it
+to specify which branch, or the whole system, you wish to search when
+running the program.
+
+Automating the download
+-----------------------
+
+If you'd like to automate the download of these files, you should be
+able to do so using any HTTP programming toolkit. Your client must
+accept cookies and follow any redirects in order to function.
--- /dev/null
+New Feature: "Purge Holds"
+==========================
+Similar to purging circulations one may wish to purge old (filled or canceled) hold information. This feature adds a database function and settings for doing so.
+
+Purged holds are moved to the action.aged_hold_request table with patron identifying information scrubbed, much like circulations are moved to action.aged_circulation.
+
+The settings allow for a default retention age as well as filled, canceled, and canceled by cancel cause ages. The most specific one wins unless a patron is retaining their hold history. In the latter case the patron's holds are retained either way.
+
+Note that the function still needs to be called, which could be set up as a cron job or done more manually, say after statistics collection. A new script, purge_holds.srfsh, is added that can be used to purge holds from cron.
--- /dev/null
+Z39.50 Batch Search and Queue
+=============================
+
+Staff Work Flow
+---------------
+
+ * Staff add records to bib record buckets
+ * Staff select the new "Locate Z39.50 Matches" action for a selected bucket.
+ * Staff choose which Z39.50 sources and indexes to search and the destination
+ queue.
+ * Submitting the search fires a series of parallel Z39.50 searches across
+ all selected Z39.50 sources.
+ * Matches are added to the selected (Vandelay) queue.
+ * Matched records may be manually or automatically overlaid to existing
+ catalog records using the existing Vandelay import/merge/overlay features.
+
+Vandelay Limit to Bucket
+------------------------
+
+As a side effect of this feature, Vandelay now has a new option in the
+interface which allows staff to limit which catalog records to which an
+inbound record matches to bib records within a record bucket. When a record
+bucket and match set are chosen, only the records in the bucket can act as
+merge/overlay targets for the inbound Vandelay records.
+
+Configuration
+-------------
+
+Z39.50 Index Field Maps
+~~~~~~~~~~~~~~~~~~~~~~~
+
+These map bib record indexes (Metabib Fields and Record Attributes) to Z39.50
+search attributes. The purpose of the mapping is to allow the server to
+determine which values to use for the automated Z39.50 searches. For example,
+if the Z39.50 "title" attribute is mapped to the "Uniform Title" Metabib Field,
+the extracted value for "Uniform Title" for each record in the bucket will be
+used as the "title" value in the Z39.50 search.
+
+Mappings can be applied to specific Z39.50 attributes, which define an attribute
+type and a Z39.50 source, or to generic attribute types (e.g. "title"). When
+a specific attribute is used, the mapping will only be applied to searches
+directed at the Z39.50 source linked to the attribute.
+
+The management interface can be found in the staff client under
+
+Admin => Server Administration => Z39.50 Index Field Maps
+
+Metabib Field Additions
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Stock config.metabib_field entries for author include additional author-
+related data, like dates. For example, a value for Personal Author might
+look like this:
+
+'girdlestone cuthbert morton 1895 1975 creator'
+
+In the context of searching Z39.50 servers, the extraneous data can be
+detrimental. Creating a separate field definition without the extra data
+is recommended.
+
+[source,sql]
+--------------------------------------------
+INSERT INTO config.metabib_field
+ (field_class, name, label, format, xpath, search_field)
+ VALUES (
+ 'author',
+ 'personal - trimmed',
+ 'Personal Author (trimmed)',
+ 'mods32',
+ '//mods32:mods/mods32:name[@type=''personal'' and mods32:role/mods32:roleTerm[text()=''creator'']]/mods32:namePart[not (@type)]',
+ FALSE
+ );
+
+-- FULL BIB (OR INDEX-TARGETED) RE-INGEST REQUIRED
+--------------------------------------------
+
+
+Org Unit Settings
+~~~~~~~~~~~~~~~~~
+
+ * cat.z3950.batch.max_parallel
+ ** Maximum Parallel Z39.50 Batch Searches
+ ** The maximum number of Z39.50 searches that can be in-flight at any given
+ time when performing batch Z39.50 searches
+ * cat.z3950.batch.max_results
+ ** Maximum Z39.50 Batch Search Results
+ ** The maximum number of search results to retrieve and queue for each
+ record + Z39 source during batch Z39.50 searches
+
--- /dev/null
+Authority-enhanced bibliographic browse
+---------------------------------------
+
+The Evergreen OPAC includes functionality for browsing by bibliographic terms,
+and where those terms are controlled by authority records, for linking directly
+to the records that use other authority controlled terms that are appropriately
+linked to the browse-exposed term. In this way, one can browse authors for
+"King, Stephen" and, when appropriate and correct cataloging has been performed,
+be presented with a browse link within the author browse list to that brings the
+user to a "Bachman, Richard" entry, assuming visible bibliographic records are
+indeed attached to both records. Likewise, when browsing for "Bachman,
+Richard", users will be presented with a browse link leading to the "King,
+Stephen" browse location.
+
+Additionally, any unused but inter-authority-linked terms will appear in the
+browse list if the linked heading is in use by bibliographic records. In this
+way, browsing for "Bachman, Richard" will lead the user the "King, Stephen" even
+if no bibliographic records make use of the "Bachman, Richard" heading.
+
+Linked authority records will not be exposed of neither is in use by visible
+bibliographic records. This means that the feature will not lead to dead-end
+searches, but also means that this is not a complete authority browsing tool
+acceptable for use as such by a cataloger. See the Manage Authorities interface
+exposed through the Staff Client for that functionality.
+
+++ /dev/null
-Release Notes for the Phonelist.pm Module
-=========================================
-
-PhoneList.pm is a mod_perl module for Apache that works with Evergreen
-to generate callings lists for patron holds. It outputs a csv file
-that can be fed into an auto-dialer script to call patrons with little
-or no staff intervention. It is accessed and configured via a special
-URL and passing any parameters as a ``Query String'' on the URL. The
-parameters are listed in the table below.
-
-.Parameters for the phonelist program:
-|=====================================
-| user | Your Evergreen login. Typically your library's circ account. If you leave this off, you will be prompted to login.
-| passwd | The password for your Evergreen login. If you leave this off you will be prompted to login.
-| 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.
-| skipemail | If present, skip patrons with email notification (optional).
-| addcount | Add a count of items on hold (optional). Only makes sense for holds.
-| 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.
-|=====================================
-
-The URL is
-
-`https://your.evergreen-server.tld/phonelist`
-
-A couple of examples follow:
-
-`https://your.evergreen-server.tld/phonelist?user=circuser&passwd=password&skipemail
-
-The above example would sign in as user circuser with password of
-``password'' and get a list of patrons with holds to call who do not
-have email notification turned on. It would run at whatever branch is
-normally associated with circuser, which would likely be MVC or
-central site. (Note: There is no actual circuser account, it is used
-here for illustration purposes only.)
-
-`https://your.evergreen-server.tld/phonelist?skipemail`
-
-The above example would do more or less the same, but you would be
-prompted by your browser for the user name and password.
-
-If your browser or download script support it, you may also use
-conventional HTTP authentication parameters.
-
-`https://user:password@your.evergreen-server.tld/phonelist?overdue&ws_ou=2`
-
-The above logs in as ``user'' with ``password'' and runs overdues for location ID 2.
-
-The following sections provide more information on getting what you want in your output.
-
-Adding Parameters
------------------
-
-If you are not familiar with HTTP/URL query strings, the format is
-quite simple.
-
-You add parameters to the end of the URL, the first parameter is
-separated from the URL page with a question mark (``?'') character. If
-the parameter is to be given an extra value, then that value follows
-the parameter name after an equals sign (``=''). Subsequent parameters
-are separated from the previous parameter by an ampersand (``&'').
-
-Here is an example with 1 parameter that has no value:
-
-`https://your.evergreen-server.tld/phonelist?skipemail`
-
-An example of 1 argument with a value:
-
-`https://your.evergreen-server.tld/phonelist?overdue=21`
-
-An example of 2 arguments, 1 with a value and 1 without:
-
-`https://your.evergreen-server.tld/phonelist?overdue=21&skipemail`
-
-Any misspelled or parameters not listed in the table above will be
-ignored by the program.
-
-Output
-------
-
-On a successful run, the program will return a CSV file named
-phone.csv. Depending on your browser or settings you will alternately
-be prompted to open or save the file. Your browser may also
-automatically save the file in your Downloads or other designated
-folder. You should be able to open this CSV file in Excel, LibreOffice
-Base, any other spread sheet program, or a text editor.
-
-If you have made a mistake and have mistyped your user name or
-password, or if you supply a ws_ou parameter with an ID where your
-user name does not have permission to look up holds or overdue
-information, then you will get an error returned in your browser.
-
-Should your browser appear to do absolutely nothing at all. This is
-normal. When there is no information for you to download, the server
-will return a 200 NO CONTENT message to your browser. Most browsers
-respond to this message by doing nothing at all. It is possible for
-there to be no information for you to retrieve if you added the
-`skipemail` option and all of your notices for that day were sent via
-email, or if you ran this in the morning and then again in the
-afternoon and there was no new information to gather.
-
-The program does indicate that it has already looked at a particular
-hold or overdue and will skip it on later runs. This prevents
-duplicates to the same patron in the same run. It will, however,
-create a ``duplicate'' for the same patron if a different copy is put
-on hold for that patron in between two runs.
-
-The specific content of the CSV file will vary if you are looking at
-holds or overdues. The specific contents are described in the
-appropriate sections below.
-
-Holds
------
-
-The `phonelist` program will return a list of patrons with copies on
-hold by default, so long as you do not use the `overdue`
-parameter. You may optionally get a number of items that patron
-currently has on hold by adding the `addcount` parameter.
-
-As always, you can add the skipemail parameter to skip patrons with
-email notifications of their overdues, [#0.5.Skipping patrons with
-email notification of holds|outline as described below].
-
-.Columns in the holds CSV file:
-|=====================================
-| Name | Patron's name first and last.
-| Phone | Patron's phone number.
-| Barcode | Patron's barcode.
-| Count | Number of copies on hold, if `addcount` parameter is used, otherwise this column is not present in the file.
-|=====================================
-
-Overdues
---------
-
-If you add the `overdue` parameter, you can get a list of patrons with
-overdue copies instead of a list of patrons with copies on the hold
-shelf. By default, this will give you a list of patrons with copies
-that are 14 days overdue. If you'd like to specify a different number
-of days you can add the number after the parameter with an equals
-sign:
-
-`https://your.evergreen-server.tld/phonelist?overdue=21&ws_ou=2`
-
-The above will retrieve a list of patrons who have items that are 21
-days overdue at the location with ID of 2.
-
-The number of days is an exact lookup. This means that the program
-will look only at patrons who have items exactly 14 days or exactly
-the number of days specified overdue. It does not pull up any that are
-less than or greater than the number of days specified.
-
-As always, you can add the skipemail parameter to skip patrons with
-email notifications of their overdues, [#0.5.Skipping patrons with
-email notification of holds|outline as described below].
-
-.Columns in the overdues CSV file:
-|=================================
-| Name | Patron's name first and last.
-| Phone | Patron's phone number.
-| Barcode | Patron's barcode.
-| Titles | A colon-separated list of titles that the patron has overdue.
-|=================================
-
-Skipping patrons with email notification of holds
--------------------------------------------------
-
-Skipping patrons who have email notification for their holds or
-overdues is very simple. You just need to add the `skipemail`
-parameter on the URL query string. Doing so will produce the list
-without the patrons who have email notification for overdues, or for
-all of their holds. Please note that if a patron has multiple holds
-available, and even one of these holds requests a phone-only
-notification, then that patron will still show on the list. For this
-option to exclude a patron from the holds list, the patron must
-request email notification on all of their current holds. In practice,
-we find that this is usually the case.
-
-Using the ws_ou parameter
--------------------------
-
-Generally, you will not need to use the ws_ou parameter when using the
-phonelist program. The phonelist will look up the branch where your
-login account works and use that location when generating the list.
-However, if you are part of a multi-branch systems in a consortium,
-then the ws_ou parameter will be of interest to you. You can use it
-to specify which branch, or the whole system, you wish to search when
-running the program.
-
-Automating the download
------------------------
-
-If you'd like to automate the download of these files, you should be
-able to do so using any HTTP programming toolkit. Your client must
-accept cookies and follow any redirects in order to function.
+++ /dev/null
-New Feature: "Purge Holds"
-==========================
-Similar to purging circulations one may wish to purge old (filled or canceled) hold information. This feature adds a database function and settings for doing so.
-
-Purged holds are moved to the action.aged_hold_request table with patron identifying information scrubbed, much like circulations are moved to action.aged_circulation.
-
-The settings allow for a default retention age as well as filled, canceled, and canceled by cancel cause ages. The most specific one wins unless a patron is retaining their hold history. In the latter case the patron's holds are retained either way.
-
-Note that the function still needs to be called, which could be set up as a cron job or done more manually, say after statistics collection. A new script, purge_holds.srfsh, is added that can be used to purge holds from cron.
+++ /dev/null
-Z39.50 Batch Search and Queue
-=============================
-
-Staff Work Flow
----------------
-
- * Staff add records to bib record buckets
- * Staff select the new "Locate Z39.50 Matches" action for a selected bucket.
- * Staff choose which Z39.50 sources and indexes to search and the destination
- queue.
- * Submitting the search fires a series of parallel Z39.50 searches across
- all selected Z39.50 sources.
- * Matches are added to the selected (Vandelay) queue.
- * Matched records may be manually or automatically overlaid to existing
- catalog records using the existing Vandelay import/merge/overlay features.
-
-Vandelay Limit to Bucket
-------------------------
-
-As a side effect of this feature, Vandelay now has a new option in the
-interface which allows staff to limit which catalog records to which an
-inbound record matches to bib records within a record bucket. When a record
-bucket and match set are chosen, only the records in the bucket can act as
-merge/overlay targets for the inbound Vandelay records.
-
-Configuration
--------------
-
-Z39.50 Index Field Maps
-~~~~~~~~~~~~~~~~~~~~~~~
-
-These map bib record indexes (Metabib Fields and Record Attributes) to Z39.50
-search attributes. The purpose of the mapping is to allow the server to
-determine which values to use for the automated Z39.50 searches. For example,
-if the Z39.50 "title" attribute is mapped to the "Uniform Title" Metabib Field,
-the extracted value for "Uniform Title" for each record in the bucket will be
-used as the "title" value in the Z39.50 search.
-
-Mappings can be applied to specific Z39.50 attributes, which define an attribute
-type and a Z39.50 source, or to generic attribute types (e.g. "title"). When
-a specific attribute is used, the mapping will only be applied to searches
-directed at the Z39.50 source linked to the attribute.
-
-The management interface can be found in the staff client under
-
-Admin => Server Administration => Z39.50 Index Field Maps
-
-Metabib Field Additions
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Stock config.metabib_field entries for author include additional author-
-related data, like dates. For example, a value for Personal Author might
-look like this:
-
-'girdlestone cuthbert morton 1895 1975 creator'
-
-In the context of searching Z39.50 servers, the extraneous data can be
-detrimental. Creating a separate field definition without the extra data
-is recommended.
-
-[source,sql]
---------------------------------------------
-INSERT INTO config.metabib_field
- (field_class, name, label, format, xpath, search_field)
- VALUES (
- 'author',
- 'personal - trimmed',
- 'Personal Author (trimmed)',
- 'mods32',
- '//mods32:mods/mods32:name[@type=''personal'' and mods32:role/mods32:roleTerm[text()=''creator'']]/mods32:namePart[not (@type)]',
- FALSE
- );
-
--- FULL BIB (OR INDEX-TARGETED) RE-INGEST REQUIRED
---------------------------------------------
-
-
-Org Unit Settings
-~~~~~~~~~~~~~~~~~
-
- * cat.z3950.batch.max_parallel
- ** Maximum Parallel Z39.50 Batch Searches
- ** The maximum number of Z39.50 searches that can be in-flight at any given
- time when performing batch Z39.50 searches
- * cat.z3950.batch.max_results
- ** Maximum Z39.50 Batch Search Results
- ** The maximum number of search results to retrieve and queue for each
- record + Z39 source during batch Z39.50 searches
-
+++ /dev/null
-Authority-enhanced bibliographic browse
----------------------------------------
-
-The Evergreen OPAC includes functionality for browsing by bibliographic terms,
-and where those terms are controlled by authority records, for linking directly
-to the records that use other authority controlled terms that are appropriately
-linked to the browse-exposed term. In this way, one can browse authors for
-"King, Stephen" and, when appropriate and correct cataloging has been performed,
-be presented with a browse link within the author browse list to that brings the
-user to a "Bachman, Richard" entry, assuming visible bibliographic records are
-indeed attached to both records. Likewise, when browsing for "Bachman,
-Richard", users will be presented with a browse link leading to the "King,
-Stephen" browse location.
-
-Additionally, any unused but inter-authority-linked terms will appear in the
-browse list if the linked heading is in use by bibliographic records. In this
-way, browsing for "Bachman, Richard" will lead the user the "King, Stephen" even
-if no bibliographic records make use of the "Bachman, Richard" heading.
-
-Linked authority records will not be exposed of neither is in use by visible
-bibliographic records. This means that the feature will not lead to dead-end
-searches, but also means that this is not a complete authority browsing tool
-acceptable for use as such by a cataloger. See the Manage Authorities interface
-exposed through the Staff Client for that functionality.
-
projects / evergreen / masslnc.git / commitdiff