About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
development:plugins:ils_drivers

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
development:plugins:ils_drivers [2021/06/07 13:02] – [getMyHolds] emaijaladevelopment:plugins:ils_drivers [2023/11/28 19:33] (current) – [getHolding] demiankatz
Line 1: Line 1:
 ====== ILS Drivers ====== ====== ILS Drivers ======
  
-// This page refers to VuFind 2.x and later; use of earlier versions is no longer recommended. // +This page contains details on writing a custom driver for an integrated library system not already supported by VuFind®.  VuFind® supports many platforms, so check to see if it already has support before you try to write your own!
- +
-This page contains details on writing a custom driver for an integrated library system not already supported by VuFind.  VuFind supports many platforms, so check to see if it already has support before you try to write your own!+
  
  
Line 14: Line 12:
 **Service Locator Configuration Section in module.config.php:** ['vufind']['plugin_managers']['ils_driver'] **Service Locator Configuration Section in module.config.php:** ['vufind']['plugin_managers']['ils_driver']
  
-**Service Manager Name for Service Locator:** VuFind\ILSDriverPluginManager (VuFind 2.x-4.x), VuFind\ILS\Driver\PluginManager (VuFind 5.0+)+**Service Manager Name for Service Locator:** VuFind\ILSDriverPluginManager (VuFind® 2.x-4.x), VuFind\ILS\Driver\PluginManager (VuFind® 5.0+)
  
-See the [[development:plugins:general_information|General Plugin Information]] page for more details on VuFind plugins.+See the [[development:plugins:general_information|General Plugin Information]] page for more details on VuFind® plugins.
  
 ===== Basic Structure ===== ===== Basic Structure =====
Line 22: Line 20:
   * The PHP driver class must be registered in the service locator with the value used as the driver setting in the [Catalog] section of [[configuration:files:config.ini]].   * The PHP driver class must be registered in the service locator with the value used as the driver setting in the [Catalog] section of [[configuration:files:config.ini]].
   * The driver class must implement the VuFind\ILS\Driver\DriverInterface.  For convenience, most drivers will achieve this by extending VuFind\ILS\Driver\AbstractBase.   * The driver class must implement the VuFind\ILS\Driver\DriverInterface.  For convenience, most drivers will achieve this by extending VuFind\ILS\Driver\AbstractBase.
-  * You may wish to define a catalog-specific .ini file in VuFind's configuration directory -- the name of this file should correspond with the base class name of the driver (i.e. for VuFind\ILS\Driver\Voyager, use Voyager.ini).  This configuration will be automatically loaded and sent to the setConfig() method by the VuFind\ILS\Connection wrapper class; you do not need to write explicit config loading into your driver.+  * You may wish to define a catalog-specific .ini file in VuFind®'s configuration directory -- the name of this file should correspond with the base class name of the driver (i.e. for VuFind\ILS\Driver\Voyager, use Voyager.ini).  This configuration will be automatically loaded and sent to the setConfig() method by the VuFind\ILS\Connection wrapper class; you do not need to write explicit config loading into your driver.
   * All heavy-weight initialization logic (i.e. establishing database connections) and configuration validation should take place in the init() method, NOT the constructor.  Driver constructors should be as light-weight as possible.   * All heavy-weight initialization logic (i.e. establishing database connections) and configuration validation should take place in the init() method, NOT the constructor.  Driver constructors should be as light-weight as possible.
  
Line 30: Line 28:
  
 ==== cancelHolds ==== ==== cancelHolds ====
-This method cancels a list of holds for a specific patron. (optional)  // Not supported prior to VuFind 1.2 //+This method cancels a list of holds for a specific patron. (optional)  // Not supported prior to VuFind® 1.2 //
  
-  * Input: cancelDetails An associative array with two keys: patron (array returned by the driver's patronLogin method) and details (an array of strings returned by the driver's getCancelHoldDetails method)+  * Input: cancelDetails An associative array with two keys: patron (array returned by the driver's patronLogin method) and details (an array of strings -- either cancel_details values provided by the getMyHolds method, or values returned by the driver's getCancelHoldDetails method if cancel_details was unset)
   * Output: Associative array containing:   * Output: Associative array containing:
     * count – The number of items successfully cancelled     * count – The number of items successfully cancelled
     * items – Associative array where key matches one of the item_id values returned by getMyHolds and the value is an associative array with these keys:     * items – Associative array where key matches one of the item_id values returned by getMyHolds and the value is an associative array with these keys:
       * success – Boolean true or false       * success – Boolean true or false
-      * status – A status message from the language file (required -- VuFind-specific message, subject to translation)+      * status – A status message from the language file (required -- VuFind®-specific message, subject to translation)
       * sysMessage - A system supplied failure message (optional -- useful for passing additional details from the ILS)       * sysMessage - A system supplied failure message (optional -- useful for passing additional details from the ILS)
  
 ==== cancelILLRequests ==== ==== cancelILLRequests ====
-This method cancels a list of ILL requests for a specific patron. (optional)  // Not supported prior to VuFind 2.3 //+This method cancels a list of ILL requests for a specific patron. (optional)  // Not supported prior to VuFind® 2.3 //
  
   * Input: cancelDetails An associative array with two keys: patron (array returned by the driver's patronLogin method) and details (an array of strings returned by the driver's getCancelILLRequestDetails method)   * Input: cancelDetails An associative array with two keys: patron (array returned by the driver's patronLogin method) and details (an array of strings returned by the driver's getCancelILLRequestDetails method)
Line 48: Line 46:
     * items – Associative array where key matches one of the item_id values returned by getMyILLRequests and the value is an associative array with these keys:     * items – Associative array where key matches one of the item_id values returned by getMyILLRequests and the value is an associative array with these keys:
       * success – Boolean true or false       * success – Boolean true or false
-      * status – A status message from the language file (required -- VuFind-specific message, subject to translation)+      * status – A status message from the language file (required -- VuFind®-specific message, subject to translation)
       * sysMessage - A system supplied failure message (optional -- useful for passing additional details from the ILS)       * sysMessage - A system supplied failure message (optional -- useful for passing additional details from the ILS)
  
 ==== cancelStorageRetrievalRequests ==== ==== cancelStorageRetrievalRequests ====
-This method cancels a list of storage retrieval requests for a specific patron. (optional)  // Not supported prior to VuFind 2.3 //+This method cancels a list of storage retrieval requests for a specific patron. (optional)  // Not supported prior to VuFind® 2.3 //
  
   * Input: cancelDetails An associative array with two keys: patron (array returned by the driver's patronLogin method) and details (an array of strings returned by the driver's getCancelStorageRetrievalRequestDetails method)   * Input: cancelDetails An associative array with two keys: patron (array returned by the driver's patronLogin method) and details (an array of strings returned by the driver's getCancelStorageRetrievalRequestDetails method)
Line 59: Line 57:
     * items – Associative array where key matches one of the item_id values returned by getMyStorageRetrievalRequests and the value is an associative array with these keys:     * items – Associative array where key matches one of the item_id values returned by getMyStorageRetrievalRequests and the value is an associative array with these keys:
       * success – Boolean true or false       * success – Boolean true or false
-      * status – A status message from the language file (required -- VuFind-specific message, subject to translation)+      * status – A status message from the language file (required -- VuFind®-specific message, subject to translation)
       * sysMessage - A system supplied failure message (optional -- useful for passing additional details from the ILS)       * sysMessage - A system supplied failure message (optional -- useful for passing additional details from the ILS)
  
 ==== changePassword ==== ==== changePassword ====
-This method changes patron's password (PIN code). (optional) // Not supported prior to VuFind 2.4 //+This method changes patron's password (PIN code). (optional) // Not supported prior to VuFind® 2.4 //
  
   * Input: details An associative array with three keys:   * Input: details An associative array with three keys:
Line 71: Line 69:
   * Output: Associative array containing:   * Output: Associative array containing:
     * success – Boolean true or false     * success – Boolean true or false
-    * status – A status message from the language file (required -- VuFind-specific message, subject to translation)+    * status – A status message from the language file (required -- VuFind®-specific message, subject to translation)
  
 ==== checkILLRequestIsValid ==== ==== checkILLRequestIsValid ====
-// Not supported prior to VuFind 2.3 //+// Not supported prior to VuFind® 2.3 //
    
 This optional method can be used to check if a particular user is allowed to place an ILL request on a particular item.  If you omit this method, the driver will still operate correctly; however, implementing it allows minor enhancements to the user experience. This optional method can be used to check if a particular user is allowed to place an ILL request on a particular item.  If you omit this method, the driver will still operate correctly; however, implementing it allows minor enhancements to the user experience.
  
   * Input: Bibliographic ID, Item Data (similar to the details parameter passed to the placeILLRequest() method, but without the 'patron' key), Patron Data (from patronLogin() method)   * Input: Bibliographic ID, Item Data (similar to the details parameter passed to the placeILLRequest() method, but without the 'patron' key), Patron Data (from patronLogin() method)
-  * Output: True if item may be requested, false if not. Prior to VuFind 4.0, this might also return “block” if the patron is blocked from making requests; that functionality has been superseded by the getRequestBlocks method. Starting with VuFind 4.0, this may also return an array with two keys: valid (boolean) plus status (message string to display to user).+  * Output: True if item may be requested, false if not. Prior to VuFind® 4.0, this might also return “block” if the patron is blocked from making requests; that functionality has been superseded by the getRequestBlocks method. Starting with VuFind® 4.0, this may also return an array with two keys: valid (boolean) plus status (message string to display to user).
  
 ==== checkRequestIsValid ==== ==== checkRequestIsValid ====
  
-Introduced in VuFind 1.3, this optional method can be used to check if a particular user is allowed to place a hold/recall request on a particular item.  If you omit this method, the driver will still operate correctly; however, implementing it allows minor enhancements to the user experience.+Introduced in VuFind® 1.3, this optional method can be used to check if a particular user is allowed to place a hold/recall request on a particular item.  If you omit this method, the driver will still operate correctly; however, implementing it allows minor enhancements to the user experience.
  
   * Input: Bibliographic ID, Item Data (similar to the holdDetails parameter passed to the placeHold() method, but without the 'patron' key), Patron Data (from patronLogin() method)   * Input: Bibliographic ID, Item Data (similar to the holdDetails parameter passed to the placeHold() method, but without the 'patron' key), Patron Data (from patronLogin() method)
-  * Output: True if item may be requested, false if not. Starting with VuFind 4.0, this may also return an array with two keys: valid (boolean) plus status (message string to display to user).+  * Output: True if item may be requested, false if not. Starting with VuFind® 4.0, this may also return an array with two keys: valid (boolean) plus status (message string to display to user).
  
 ==== checkStorageRetrievalRequestIsValid ==== ==== checkStorageRetrievalRequestIsValid ====
-// Not supported prior to VuFind 2.3 //+// Not supported prior to VuFind® 2.3 //
    
 This optional method can be used to check if a particular user is allowed to place a storage retrieval request on a particular item.  If you omit this method, the driver will still operate correctly; however, implementing it allows minor enhancements to the user experience. This optional method can be used to check if a particular user is allowed to place a storage retrieval request on a particular item.  If you omit this method, the driver will still operate correctly; however, implementing it allows minor enhancements to the user experience.
  
   * Input: Bibliographic ID, Item Data (similar to the details parameter passed to the placeStorageRetrievalRequest() method, but without the 'patron' key), Patron Data (from patronLogin() method)   * Input: Bibliographic ID, Item Data (similar to the details parameter passed to the placeStorageRetrievalRequest() method, but without the 'patron' key), Patron Data (from patronLogin() method)
-  * Output: True if item may be requested, false if not. Prior to VuFind 4.0, this might also return "block" if the patron is blocked from making requests; that functionality has been superseded by the getRequestBlocks method. Starting with VuFind 4.0, this may also return an array with two keys: valid (boolean) plus status (message string to display to user).+  * Output: True if item may be requested, false if not. Prior to VuFind® 4.0, this might also return "block" if the patron is blocked from making requests; that functionality has been superseded by the getRequestBlocks method. Starting with VuFind® 4.0, this may also return an array with two keys: valid (boolean) plus status (message string to display to user).
  
 ==== findReserves ==== ==== findReserves ====
Line 113: Line 111:
 ==== getAccountBlocks ==== ==== getAccountBlocks ====
  
-This optional method returns an array of strings describing blocks on the user's account (for example, lost items, financial violations, etc.). If no blocks are in place, it returns false. // Not supported prior to VuFind 4.0 //+This optional method returns an array of strings describing blocks on the user's account (for example, lost items, financial violations, etc.). If no blocks are in place, it returns false. // Not supported prior to VuFind® 4.0 //
  
   * Input: patron (array returned by the driver's patronLogin method)   * Input: patron (array returned by the driver's patronLogin method)
Line 119: Line 117:
  
 ==== getCancelHoldDetails ==== ==== getCancelHoldDetails ====
-This method returns a string to use as the input form value for cancelling each hold item. (optional, but required if you implement cancelHolds). // Not supported prior to VuFind 1.2 //+This method returns a string to use as the input form value for cancelling each hold item. If determining this identifier does not require complex calculations, you can fill in the cancel_details key directly in the getMyHolds method instead of implementing this method. (optional, but required if you implement cancelHolds and do not provide cancel_details in getMyHolds). // Not supported prior to VuFind® 1.2 //
  
   * Input:   * Input:
     * holdDetails - One of the individual item arrays returned by the getMyHolds method     * holdDetails - One of the individual item arrays returned by the getMyHolds method
-    * patron (array returned by the driver's patronLogin method) // Added in VuFind 8.0 // +    * patron (array returned by the driver's patronLogin method) // Added in VuFind® 8.0 // 
-  * Output: A string to use as the input form value for cancelling each hold item; you can pass any data that is needed by your ILS to identify the hold -- the output of this method will be used as part of the input to the cancelHolds method. Starting with VuFind 3.0, you may indicate holds which are not allowed to be cancelled by returning an empty string.+  * Output: A string to use as the input form value for cancelling each hold item; you can pass any data that is needed by your ILS to identify the hold -- the output of this method will be used as part of the input to the cancelHolds method. Starting with VuFind® 3.0, you may indicate holds which are not allowed to be cancelled by returning an empty string.
  
  
 ==== getCancelHoldLink ==== ==== getCancelHoldLink ====
-This method returns a URL to use as a link to a native OPAC for cancelling each hold item. (optional -- only implement this if your ILS is unable to support implementation of the cancelHolds method). // Not supported prior to VuFind 1.2 //+This method returns a URL to use as a link to a native OPAC for cancelling each hold item. (optional -- only implement this if your ILS is unable to support implementation of the cancelHolds method). // Not supported prior to VuFind® 1.2 //
  
   * Input:   * Input:
     * holdDetails - One of the individual item arrays returned by getMyHolds method     * holdDetails - One of the individual item arrays returned by getMyHolds method
-    * patron (array returned by the driver's patronLogin method) // Added in VuFind 8.0 //+    * patron (array returned by the driver's patronLogin method) // Added in VuFind® 8.0 //
   * Output: A URL to a native OPAC for cancelling each hold item   * Output: A URL to a native OPAC for cancelling each hold item
  
 ==== getCancelILLRequestDetails ==== ==== getCancelILLRequestDetails ====
-This method returns a string to use as the input form value for cancelling each hold item. (optional, but required if you implement cancelILLRequests). // Not supported prior to VuFind 2.3 //+This method returns a string to use as the input form value for cancelling each hold item. (optional, but required if you implement cancelILLRequests). // Not supported prior to VuFind® 2.3 //
  
   * Input:   * Input:
Line 144: Line 142:
  
 ==== getCancelStorageRetrievalRequestDetails ==== ==== getCancelStorageRetrievalRequestDetails ====
-This method returns a string to use as the input form value for cancelling each hold item. (optional, but required if you implement cancelStorageRetrievalRequests). // Not supported prior to VuFind 2.3 //+This method returns a string to use as the input form value for cancelling each hold item. (optional, but required if you implement cancelStorageRetrievalRequests). // Not supported prior to VuFind® 2.3 //
  
   * Input:   * Input:
Line 152: Line 150:
  
 ==== getConfig ==== ==== getConfig ====
-This method returns driver configuration settings related to a particular function.  It is primarily used to get the configuration settings for placing holds. (optional, but necessary if you want to implement hold or other request functionality) // Not supported prior to VuFind 1.2 //+This method returns driver configuration settings related to a particular function.  It is primarily used to get the configuration settings for placing holds. (optional, but necessary if you want to implement hold or other request functionality) // Not supported prior to VuFind® 1.2 //
  
   * Input:   * Input:
Line 163: Line 161:
  
     * Array keys used for input of "Holdings"     * Array keys used for input of "Holdings"
-      * itemLimit (optional) - The page size used when retrieving holdings data in a paginated format (see [[#getHolding|getHolding()]]). :!: In VuFind 6.0.x, this was erroneously included in the "Holds" section instead, but it was moved to "Holdings" beginning with release 6.1.+      * itemLimit (optional) - The page size used when retrieving holdings data in a paginated format (see [[#getHolding|getHolding()]]). :!: In VuFind® 6.0.x, this was erroneously included in the "Holds" section instead, but it was moved to "Holdings" beginning with release 6.1.
  
     * Array keys used for input of "Holds"     * Array keys used for input of "Holds"
-      * HMACKeys - a colon-separated list of fields to verify with a hash key when submitting a hold form (at a minimum, "id" is recommended).  Note that this is used for verifying VuFind's own hold form; it is not directly tied to the ILS in any way.  MUST BE PROVIDED in order to place holds within VuFind; if omitted, VuFind will attempt to fail over from placeHold to placeHoldLink functionality.  This also serves another important purpose:  any keys in the return array from getHolding will be passed to placeHold if they match entries in this list.  This makes it possible to pass through all of the the necessary details about placing a hold. +      * HMACKeys - a colon-separated list of fields to verify with a hash key when submitting a hold form (at a minimum, "id" is recommended).  Note that this is used for verifying VuFind®'s own hold form; it is not directly tied to the ILS in any way.  MUST BE PROVIDED in order to place holds within VuFind®; if omitted, VuFind® will attempt to fail over from placeHold to placeHoldLink functionality.  This also serves another important purpose:  any keys in the return array from getHolding will be passed to placeHold if they match entries in this list.  This makes it possible to pass through all of the the necessary details about placing a hold. 
-      * extraHoldFields (optional) - a colon-separated list of form fields to include in the place hold form; may include "comments", "requiredByDate" and "pickUpLocation" Note that all parameters activated here must be processed by the placeHold method.+      * extraHoldFields (optional) - a colon-separated list of form fields to include in the place hold form; may include "comments", "requiredByDate""pickUpLocation" and (from VuFind® 8.0) "startDate" Note that all parameters activated here must be processed by the placeHold method.
       * defaultRequiredDate - A colon-separated list used to set the default "not required after" date for holds in the format days:months:years (e.g. 0:1:0 will set a "not required after" date of 1 month from the current date).       * defaultRequiredDate - A colon-separated list used to set the default "not required after" date for holds in the format days:months:years (e.g. 0:1:0 will set a "not required after" date of 1 month from the current date).
         * This only applies if extraHoldFields includes "requiredByDate."         * This only applies if extraHoldFields includes "requiredByDate."
-        * Starting with VuFind 2.3, you may prefix this string with "driver:" to attempt to load a default date from the ILS based on internal rules instead of calculating one in VuFind; if the ILS calls, the relative rules will still be used (e.g. "driver:0:1:0"); this feature requires that the driver implement the [[#getHoldDefaultRequiredDate|getHoldDefaultRequiredDate()]] method.+        * Starting with VuFind® 2.3, you may prefix this string with "driver:" to attempt to load a default date from the ILS based on internal rules instead of calculating one in VuFind®; if the ILS calls, the relative rules will still be used (e.g. "driver:0:1:0"); this feature requires that the driver implement the [[#getHoldDefaultRequiredDate|getHoldDefaultRequiredDate()]] method.
       * consortium (optional) - Boolean true or false (default): Does this driver provide consortial capabilities (e.g., XCNCIP2 driver)? If set to true, then the driver method getConsortialHoldings() will be called in order to to provide multiple Holding statuses in a consortial environment; this feature requires that the driver implement the [[#getConsortialHoldings|getConsortialHoldings()]] method.  If set to false (or omitted), the [[#getHolding|getHolding()]] method will be called.       * consortium (optional) - Boolean true or false (default): Does this driver provide consortial capabilities (e.g., XCNCIP2 driver)? If set to true, then the driver method getConsortialHoldings() will be called in order to to provide multiple Holding statuses in a consortial environment; this feature requires that the driver implement the [[#getConsortialHoldings|getConsortialHoldings()]] method.  If set to false (or omitted), the [[#getHolding|getHolding()]] method will be called.
-      * itemLimit (optional, deprecated) - This setting was used here in VuFind 6.0.x; it was moved to Holdings (see above) with release 6.1, but is still supported here for backward compatibility.+      * itemLimit (optional, deprecated) - This setting was used here in VuFind® 6.0.x; it was moved to Holdings (see above) with release 6.1, but is still supported here for backward compatibility
 +      * helpText - A generic help text displayed on the hold request form. Displayed as is; HTML tags can be used, but everything needs to be properly escaped. 
 +      * helpText[*] - (From VuFind® 8.0) A default help text displayed on the hold request form if not overridden. Displayed as is; HTML tags can be used, and everything needs to be properly escaped. 
 +      * helpText[lng] - A language-specific help text displayed on the hold request form. Displayed as is; HTML tags can be used, and everything needs to be properly escaped. 
 +      * updateHelpText[*] - (From VuFind® 8.0) A default help text displayed on the hold update form. Displayed as is; HTML tags can be used, and everything needs to be properly escaped. 
 +      * updateHelpText[lng] - (From VuFind® 8.0) A language-specific help text displayed on the hold update form. Displayed as is; HTML tags can be used, and everything needs to be properly escaped. 
 +      * updateFields (optional) - (From VuFind® 8.0) A colon-separated list of form fields to include in the update holds form; may include "frozen", "frozenThrough", "startDate", "requiredByDate" and "pickUpLocation" Note that all parameters activated here must be processed by the updateHolds method.
    
     * Array keys used for input of "Renewals"     * Array keys used for input of "Renewals"
Line 178: Line 182:
  
     * Array keys used for input of "StorageRetrievalRequests" (from v2.3)     * Array keys used for input of "StorageRetrievalRequests" (from v2.3)
-      * HMACKeys - a colon-separated list of fields to verify with a hash key when submitting a hold form (at a minimum, "id" is recommended).  Note that this is used for verifying VuFind's own request form; it is not directly tied to the ILS in any way.  MUST BE PROVIDED in order to place requests within VuFind.  This also serves another important purpose:  any keys in the return array from getHolding will be passed to placeStorageRetrievalRequest if they match entries in this list.  This makes it possible to pass through all of the the necessary details about placing a request.+      * HMACKeys - a colon-separated list of fields to verify with a hash key when submitting a hold form (at a minimum, "id" is recommended).  Note that this is used for verifying VuFind®'s own request form; it is not directly tied to the ILS in any way.  MUST BE PROVIDED in order to place requests within VuFind®.  This also serves another important purpose:  any keys in the return array from getHolding will be passed to placeStorageRetrievalRequest if they match entries in this list.  This makes it possible to pass through all of the the necessary details about placing a request.
       * extraFields (optional) - a colon-separated list of form fields to include in the request form; may include "comments", "requiredByDate", "pickUpLocation" and "item-issue" Note that all parameters activated here must be processed by the placeStorageRetrievalRequest method.       * extraFields (optional) - a colon-separated list of form fields to include in the request form; may include "comments", "requiredByDate", "pickUpLocation" and "item-issue" Note that all parameters activated here must be processed by the placeStorageRetrievalRequest method.
       * defaultRequiredDate - A colon-separated list used to set the default "not required after" date for requests in the format days:months:years (e.g. 0:1:0 will set a "not required after" date of 1 month from the current date).       * defaultRequiredDate - A colon-separated list used to set the default "not required after" date for requests in the format days:months:years (e.g. 0:1:0 will set a "not required after" date of 1 month from the current date).
         * This only applies if extraFields includes "requiredByDate."         * This only applies if extraFields includes "requiredByDate."
-      * helpText - A generic help text displayed on the request form. +      * helpText - A generic help text displayed on the request form. Displayed as is; HTML tags can be used, and everything needs to be properly escaped. 
-      * helpText[lng] - A language-specific help text displayed on the request form.+      * helpText[*] - (From VuFind® 8.0) A default help text displayed on the request form if not overridden. Displayed as is; HTML tags can be used, and everything needs to be properly escaped
 +      * helpText[lng] - A language-specific help text displayed on the request form. Displayed as is; HTML tags can be used, and everything needs to be properly escaped.
  
     * Array keys used for input of "ILLRequests" (from v2.3)     * Array keys used for input of "ILLRequests" (from v2.3)
-      * HMACKeys - a colon-separated list of fields to verify with a hash key when submitting a hold form (at a minimum, "id" is recommended).  Note that this is used for verifying VuFind's own request form; it is not directly tied to the ILS in any way.  MUST BE PROVIDED in order to place requests within VuFind.  This also serves another important purpose:  any keys in the return array from getHolding will be passed to placeILLRequest if they match entries in this list.  This makes it possible to pass through all of the the necessary details about placing a request.+      * HMACKeys - a colon-separated list of fields to verify with a hash key when submitting a hold form (at a minimum, "id" is recommended).  Note that this is used for verifying VuFind®'s own request form; it is not directly tied to the ILS in any way.  MUST BE PROVIDED in order to place requests within VuFind®.  This also serves another important purpose:  any keys in the return array from getHolding will be passed to placeILLRequest if they match entries in this list.  This makes it possible to pass through all of the the necessary details about placing a request.
       * extraFields (optional) - a colon-separated list of form fields to include in the request form; may include "comments", "requiredByDate", "pickUpLocation", "pickUpLibrary", "pickUpLibraryLocation" and "itemId". "pickUpLibraryLocation" is a special dynamic field that is populated based on "pickUpLibrary" using the [[#getILLPickupLocations|getILLPickupLocations()]] method, which must be implemented by the ILS driver. Note that all parameters activated here must be processed by the placeILLRequest method.       * extraFields (optional) - a colon-separated list of form fields to include in the request form; may include "comments", "requiredByDate", "pickUpLocation", "pickUpLibrary", "pickUpLibraryLocation" and "itemId". "pickUpLibraryLocation" is a special dynamic field that is populated based on "pickUpLibrary" using the [[#getILLPickupLocations|getILLPickupLocations()]] method, which must be implemented by the ILS driver. Note that all parameters activated here must be processed by the placeILLRequest method.
       * defaultRequiredDate - A colon-separated list used to set the default "not required after" date for requests in the format days:months:years (e.g. 0:1:0 will set a "not required after" date of 1 month from the current date).       * defaultRequiredDate - A colon-separated list used to set the default "not required after" date for requests in the format days:months:years (e.g. 0:1:0 will set a "not required after" date of 1 month from the current date).
         * This only applies if extraFields includes "requiredByDate."         * This only applies if extraFields includes "requiredByDate."
-      * helpText - A generic help text displayed on the request form. +      * helpText - A generic help text displayed on the request form. Displayed as is; HTML tags can be used, and everything needs to be properly escaped. 
-      * helpText[lng] - A language-specific help text displayed on the request form.+      * helpText[*] - (From VuFind® 8.0) A default help text displayed on the request form if not overridden. Displayed as is; HTML tags can be used, and everything needs to be properly escaped
 +      * helpText[lng] - A language-specific help text displayed on the request form. Displayed as is; HTML tags can be used, and everything needs to be properly escaped.
  
     * Array keys used for input of "changePassword" (from v2.4)     * Array keys used for input of "changePassword" (from v2.4)
Line 210: Line 216:
  
 ==== getDefaultPickUpLocation ==== ==== getDefaultPickUpLocation ====
-This method returns the default pick up location code or id for use when placing holds and other requests. (optional) // Not supported prior to VuFind 1.2 //+This method returns the default pick up location code or id for use when placing holds and other requests. (optional) // Not supported prior to VuFind® 1.2 //
  
-    * Input: Patron array returned by patronLogin method (optional), hold information array similar to placeHold's input (optional, provided only when user is in the process of placing a hold -- may be used to limit the available pickup options based on item ID, etc.; not supported prior to VuFind 1.3) +    * Input: Patron array returned by patronLogin method (optional), hold information array similar to placeHold's input (optional, provided only when user is in the process of placing a hold -- may be used to limit the available pickup options based on item ID, etc.; not supported prior to VuFind® 1.3) 
-    * Output: A pick up location id or code (string); starting with VuFind 2.3, this may also return false to force the user to choose a location.+    * Output: A pick up location id or code (string); starting with VuFind® 2.3, this may also return false to force the user to choose a location.
  
  
Line 228: Line 234:
   * Output: An associative array with key = fund ID, value = fund name.   * Output: An associative array with key = fund ID, value = fund name.
  
-//IMPORTANT: The return value for this method changed in r2184.  If you are using VuFind 1.0RC2 or earlier, this function returns a flat array of options (no ID-based keys), and empty return values may cause problems.  It is recommended that you update to newer code before implementing the new item feature in your driver.//+//IMPORTANT: The return value for this method changed in r2184.  If you are using VuFind® 1.0RC2 or earlier, this function returns a flat array of options (no ID-based keys), and empty return values may cause problems.  It is recommended that you update to newer code before implementing the new item feature in your driver.//
  
 ==== getHoldDefaultRequiredDate ==== ==== getHoldDefaultRequiredDate ====
-Get Default "Hold Required By" Date (optional). // Not supported until VuFind 2.3. //+Get Default "Hold Required By" Date (optional). // Not supported until VuFind® 2.3. //
  
-  * Input: Patron array returned by patronLogin method (optional), hold information array similar to placeHold's input (optional, provided only when user is in the process of placing a hold -- may be used to limit the available pickup options based on item ID, etc.; must never add new options to the return array -- may only be used as a limiter; not supported prior to VuFind 1.3)+:!: This method is only called if the defaultRequiredDate setting in the ILS driver's .ini file has a "driver:" prefix. An example: 
 +<code> 
 +[Holds] 
 +defaultRequiredDate = 'driver:0:2:0' 
 +</code> 
 + 
 +  * Input: Patron array returned by patronLogin method (optional), hold information array similar to placeHold's input (optional, provided only when user is in the process of placing a hold -- may be used to limit the available pickup options based on item ID, etc.; must never add new options to the return array -- may only be used as a limiter; not supported prior to VuFind® 1.3)
   * Output: Unix timestamp (or null if no date available)   * Output: Unix timestamp (or null if no date available)
  
Line 239: Line 251:
 This method queries the ILS for holding information. This method queries the ILS for holding information.
  
-:!: Starting with VuFind 6.0, this method supports pagination to prevent retrieval of impractically large result sets. To support pagination, the getConfig("Holds") call must return an itemLimit value.+:!: Starting with VuFind® 6.0, this method supports pagination to prevent retrieval of impractically large result sets. To support pagination, the getConfig("Holds") call must return an itemLimit value.
  
-:!: In VuFind 6.1, the reliance on the getConfig("Holds") call for retrieving itemLimit values was revised to use the more appropriate getConfig("Holdings") call instead.+:!: In VuFind® 6.1, the reliance on the getConfig("Holds") call for retrieving itemLimit values was revised to use the more appropriate getConfig("Holdings") call instead.
  
   * Input: RecordID, output of patronLogin (so that patron-specific data may be added to the return array), additional options (beginning in release 6.0; these may include 'page', 'itemLimit' and 'offset' parameters used for result pagination).   * Input: RecordID, output of patronLogin (so that patron-specific data may be added to the return array), additional options (beginning in release 6.0; these may include 'page', 'itemLimit' and 'offset' parameters used for result pagination).
   * Output: Prior to release 6.0, returns an array of associative arrays, one for each item attached to the specified bibliographic record. Beginning with release 6.0, may instead return an associative array with 'total' and 'holdings' keys, where 'total' is the total number of items available from the ILS, and 'holdings' is the requested page of results, represented as associative arrays). Beginning with release 6.1, an 'electronic_holdings' key may also be included, containing records for online items not found in the regular 'holdings' array; these are highlighted at the top of the holdings display, independently from pagination, to ease access to available full content. Regardless of top-level format or whether it's a 'holding' or 'electronic_holding', each associative array representing an item holding contains these keys:   * Output: Prior to release 6.0, returns an array of associative arrays, one for each item attached to the specified bibliographic record. Beginning with release 6.0, may instead return an associative array with 'total' and 'holdings' keys, where 'total' is the total number of items available from the ILS, and 'holdings' is the requested page of results, represented as associative arrays). Beginning with release 6.1, an 'electronic_holdings' key may also be included, containing records for online items not found in the regular 'holdings' array; these are highlighted at the top of the holdings display, independently from pagination, to ease access to available full content. Regardless of top-level format or whether it's a 'holding' or 'electronic_holding', each associative array representing an item holding contains these keys:
-    * id - the RecordID that was passed in 
-    * availability - boolean: is the item available (i.e. on the shelf and/or available for checkout)? 
-    * status - string describing the availability status of the item 
-    * location - string describing the physical location of the item. Note: prior to VuFind 1.3, some drivers HTML entity encoded this string; that is incorrect behavior in VuFind 1.3 or later -- this should be plain text, not HTML. 
-    * location_code - an internal code representing the location. (optional) 
-    * locationhref - a URL to link the location name to. (optional, introduced in VuFind 2.5) 
-    * reserve - string indicating "on reserve" status -- legal values: 'Y' or 'N' 
-    * callnumber - the call number of this item 
-    * duedate - string showing due date of checked out item (null if not checked out) 
-    * returnDate - A string showing return date of an item (false if not recently returned) 
-    * number - the copy number for this item (note: although called "number", this may actually be a string if individual items are named rather than numbered -- the value will be used in displays to distinguish between copies within a list) 
-    * enumchron - enumeration / chronology data about the current copy (i.e. volume number and/or year); introduced in VuFind 5.0 to separate this detailed information from the simple number field above. 
-    * requests_placed – The total number of holds and recalls placed on an item (optional) 
-    * barcode - the barcode number for this item (important: even if you do not have access to real barcode numbers, you may want to include dummy values, since a missing barcode will prevent some other item information from displaying in the VuFind interface). 
-    * notes - an array of notes associated with holdings (optional; deprecated in VuFind 3.0 in favor of holdings_notes) 
-    * holdings_notes - an array of notes associated with holdings record containing the current item (optional; introduced in VuFind 3.0) 
-    * item_notes - an array of notes associated with the current item (optional; introduced in VuFind 3.0) 
-    * summary - an array of summary information strings associated with holdings (optional) 
-    * supplements - an array of strings about supplements associated with holdings (optional, introduced in VuFind 2.3) 
-    * indexes - an array of strings about indexes associated with holdings (optional, introduced in VuFind 2.3) 
-    * is_holdable – whether or not ANY user can place a hold or recall on the item – allows system administrators to determine hold behaviour (optional; defaults to true if unset). Use this setting to indicate hold availability based on the item itself; use the addLink setting for hold availability based on the combination of the item and the current logged-in user. 
-    * holdtype – the type of hold to be placed – of use for systems with multiple hold types such as "hold" or "recall". Prior to VuFind 4.0, a value of "block" will inform the user that they cannot place a hold on the item due to account blocks (optional); starting in 4.0, the "block" value was replaced with the separate getRequestBlocks method. 
-    * addLink – whether not the CURRENT user can place a hold or recall on the item – for use with drivers which can determine hold logic based on patron data -- i.e. only used when holds_mode is set to "driver" in config.ini; normally a boolean, but until VuFind 4.0 may be set to the special value of "block" to indicate a user permission problem (optional; starting in 4.0, use the getRequestBlocks method instead).  Starting with VuFind 1.3, you can also use the special value of "check" which will trigger an AJAX call against the checkRequestIsValid() method to allow complex link rules to be evaluated without holding up the main page load. 
-    * item_id - the item (as opposed to bibliographic) identifier (optional) 
-    * holdOverride - Starting with VuFind 1.3, you can use this value to override the usual config.ini Catalog:holds_mode setting on an item-by-item basis; useful for local customizations but not recommended for generic shared driver code.  Also note that this feature only works when the Catalog:allow_holds_override setting is turned on in config.ini. 
-    * addStorageRetrievalRequestLink - Starting with VuFind 2.3, you can use this value to indicate availability of storage retrieval requests. See addLink above for valid values. If "check" is returned, the driver must implement the [[#checkstorageretrievalrequestisvalid|checkStorageRetrievalRequestIsValid()]] method. See also getConfig and other storage retrieval request methods. At least [[#placestorageretrievalrequest|placeStorageRetrievalRequest()]] must be implemented.  
-    * addILLRequestLink - Starting with VuFind 2.3, you can use this value to indicate availability of Inter-Library Loan (ILL) requests. See addLink above for valid values. If "check" is returned, the driver must implement the [[#checkillrequestisvalid|checkILLRequestIsValid()]] method. See also getConfig and other ILL request methods. At least [[#placeillrequest|placeILLRequest()]] must be implemented. 
-    * source - The search backend from which the record may be retrieved (optional - defaults to Solr, introduced in VuFind 2.4) 
-    * use_unknown_message - An optional boolean that, when set to true, will cause display of a message indicating that the status of the item is unknown. 
-    * services - Starting with VuFind 3.0, this value can be used to indicate availability services (loan, presence). For now, 'services' is only used by code calling getStatus(), not getHolding(), but setting it here as well will not hurt anything and may be useful for future enhancements. See the [[#getstatus|getStatus()]] documentation for more details. 
  
-==== getHoldings -- DEPRECATED ==== +^ Key              ^ Type               ^ Required         ^ Minimum Version  ^ Description ^ 
-This method queries the ILS for holding information on multiple records at once +| id               | string             | yes              |                  | the RecordID that was passed in | 
-  * Input: Array of RecordIDs +| availability     | boolean/int        | yes              | * / 9.1          | is the item available (i.e. on the shelf and/or available for checkout)? See below for further information. | 
-  * OutputReturns an array of associative arrayseach the return value of getHolding for one of the input RecordIDs.  The indexing of this array does not necessarily correspond with the input index values; to find specific record, you should loop through and check "id" values.+| status           | string             | yes              |                  | description of the availability status of the item | 
 +| location         | string             | yes              |                  | description of the physical location of the item. Noteprior to VuFind® 1.3, some drivers HTML entity encoded this string; that is incorrect behavior in VuFind® 1.3 or later -- this should be plain text, not HTML. | 
 +| location_code    | string             | no                                | an internal code representing the location. | 
 +| locationhref     | string             | no               | 2.5              | a URL to link the location name to. | 
 +| reserve          | string             | yes              |                  | "on reserve" status -- legal values: 'Y' or 'N'
 +| callnumber       | string             | yes              |                  | the call number of this item | 
 +| callnumber_prefix | string            | no               | 8.0              | a call number prefix (i.e. a value that sets the context of the call numbersuch as a material format designation, but is not part of the call number for sorting purposes, etc.) | 
 +| duedate          | string             | no                                | due date of checked out item in a human-readable form (null if not checked out) | 
 +| returnDate       | string or boolean  | no                                | A string showing return date of an item (false if not recently returned) | 
 +| number           | string             | yes              |                  | the copy number for this item (note: although called "number", this may actually be a string if individual items are named rather than numbered -- the value will be used in displays to distinguish between copies within a list) | 
 +| enumchron        | string             | no               | 5.0              | enumeration / chronology data about the current copy (i.e. volume number and/or year); introduced to separate this detailed information from the simple number field above. | 
 +| requests_placed  | int                | no                                | The total number of holds and recalls placed on an item | 
 +| barcode          | string             | yes              |                  | the barcode number for this item (important: even if you do not have access to real barcode numbers, you may want to include dummy values, since a missing barcode will prevent some other item information from displaying in the VuFind® interface). | 
 +| notes            | string[]           | no               | :!: deprecated in 3.0| an array of notes associated with holdings | 
 +| holdings_id      | string             | no                                | the ID of the holdings record containing the current item | 
 +| holdings_notes   | string[]           | no               | 3.0              | an array of notes associated with holdings record containing the current item | 
 +| item_notes       | string[]           | no               | 3.0              | an array of notes associated with the current item | 
 +| summary          | string[]           | no                                | an array of summary information strings associated with holdings | 
 +| supplements      | string[]           | no               | 2.3              | an array of strings about supplements associated with holdings | 
 +| indexes          | string[]           | no               | 2.3              | an array of strings about indexes associated with holdings | 
 +| is_holdable      | bool               | no                                | whether or not ANY user can place a hold or recall on the item – allows system administrators to determine hold behaviour (defaults to true if unset). Use this setting to indicate hold availability based on the item itself; use the addLink setting for hold availability based on the combination of the item and the current logged-in user. | 
 +| holdtype         | string             | no                                | the type of hold to be placed – of use for systems with multiple hold types such as "hold" or "recall". Prior to VuFind® 4.0, a value of "block" will inform the user that they cannot place a hold on the item due to account blocks (optional)starting in 4.0, the "block" value was replaced with the separate getRequestBlocks method. | 
 +| addLink          | string or bool     | no                                | whether not the CURRENT user can place a hold or recall on the item – for use with drivers which can determine hold logic based on patron data -- i.e. only used when holds_mode is set to "driver" in config.ini; normally boolean, but until VuFind® 4.0 may be set to the special value of "block" to indicate a user permission problem (optional; starting in 4.0, use the getRequestBlocks method instead).  Starting with VuFind® 1.3, you can also use the special value of "check" which will trigger an AJAX call against the checkRequestIsValid() method to allow complex link rules to be evaluated without holding up the main page load. | 
 +| item_id          | string             | no                                | the item (as opposed to bibliographic) identifier (optional) | 
 +| holdOverride     | string             | no               | 1.3              | you can use this value to override the usual config.ini Catalog:holds_mode setting on an item-by-item basis; useful for local customizations but not recommended for generic shared driver code.  Also note that this feature only works when the Catalog:allow_holds_override setting is turned on in config.ini. | 
 +| addStorageRetrievalRequestLink | string or bool | no     | 2.3              | you can use this value to indicate availability of storage retrieval requests. See addLink above for valid values. If "check" is returned, the driver must implement the [[#checkstorageretrievalrequestisvalid|checkStorageRetrievalRequestIsValid()]] method. See also getConfig and other storage retrieval request methods. At least [[#placestorageretrievalrequest|placeStorageRetrievalRequest()]] must be implemented. | 
 +| addILLRequestLink | string or bool    | no               | 2.3              | you can use this value to indicate availability of Inter-Library Loan (ILL) requests. See addLink above for valid values. If "check" is returned, the driver must implement the [[#checkillrequestisvalid|checkILLRequestIsValid()]] method. See also getConfig and other ILL request methods. At least [[#placeillrequest|placeILLRequest()]] must be implemented. | 
 +| source            | string            | no               | 2.4              | The search backend from which the record may be retrieved (defaults to Solr) | 
 +| use_unknown_message | bool            | no                                | when set to true, will cause display of a message indicating that the status of the item is unknown. | 
 +| services          | string[]          | no               | 3.0              | this value can be used to indicate availability services (loan, presence). For now, 'services' is only used by code calling getStatus(), not getHolding(), but setting it here as well will not hurt anything and may be useful for future enhancements. See the [[#getstatus|getStatus()]] documentation for more details. | 
 +| boundWithRecords  | array             | no               | 10.0             | an array of arrays, where each instance defines bibId and title keys describing a "bound-with" record associated with the current record | 
 +The ''availability'' field may contain a boolean value: 
 +  * true  - Item is available, and 'Available' is displayed as status 
 +  * false - Item is unavailable, and the ''status'' field is used for display 
 + 
 +Starting with VuFind 9.1, also the following constants from ''\VuFind\ILS\Logic\ItemStatus'' class can be used, and the ''status'' field is always used for display: 
 +  * STATUS_UNAVAILABLE - Item is unavailable 
 +  * STATUS_AVAILABLE   - Item is available 
 +  * STATUS_UNCERTAIN   - Item availability is uncertain (the item could be available e.g. only to a specific patron group)  
  
  
Line 285: Line 305:
 This method returns a URL that links into the ILS to allow the patron to place a hold.  Optional -- should only be defined when the placeHold method cannot be implemented due to ILS limitations. This method returns a URL that links into the ILS to allow the patron to place a hold.  Optional -- should only be defined when the placeHold method cannot be implemented due to ILS limitations.
  
-  * Input: Bibliographic Record ID, Item details array from getHolding (second parameter is optional and was introduced in VuFind 1.2; starting with VuFind 1.4, it is also possible that the second parameter will contain a 'level' key set to 'title' instead of item information for cases where a user has explicitly requested a title-level hold)+  * Input: Bibliographic Record ID, Item details array from getHolding (second parameter is optional and was introduced in VuFind® 1.2; starting with VuFind® 1.4, it is also possible that the second parameter will contain a 'level' key set to 'title' instead of item information for cases where a user has explicitly requested a title-level hold)
   * Output: Link to legacy OPAC for placing hold (or null if no hold link is available for this item).   * Output: Link to legacy OPAC for placing hold (or null if no hold link is available for this item).
  
 ==== getILLPickupLibraries ==== ==== getILLPickupLibraries ====
-// Not supported prior to VuFind 2.3 //+// Not supported prior to VuFind® 2.3 //
  
 This method must be implemented if "pickUpLibrary" is specified in extraFields of getConfig('ILLRequests'). This method must be implemented if "pickUpLibrary" is specified in extraFields of getConfig('ILLRequests').
Line 300: Line 320:
  
 ==== getILLPickupLocations ==== ==== getILLPickupLocations ====
-// Not supported prior to VuFind 2.3 //+// Not supported prior to VuFind® 2.3 //
  
 This method must be implemented if "pickUpLibraryLocation" is specified in extraFields of getConfig('ILLRequests'). This method must be implemented if "pickUpLibraryLocation" is specified in extraFields of getConfig('ILLRequests').
Line 317: Line 337:
 ==== getMyFines ==== ==== getMyFines ====
 This method queries the ILS for a patron's current fines This method queries the ILS for a patron's current fines
-  * Input: Patron array returned by patronLogin method + 
-  Output: Returns an array of associative arrays, one for each fine associated with the specified account. Each associative array contains these keys: +Input: Patron array returned by patronLogin method 
-    amount The total amount of the fine IN PENNIES.  Be sure to adjust decimal points appropriately (i.e. for a $1.00 fine, amount should be set to 100). + 
-    checkout A string representing the date when the item was checked out. +Output: Returns an array of associative arrays, one for each fine associated with the specified account. Each associative array contains these keys: 
-    fine A string describing the reason for the fine (i.e. "Overdue", "Long Overdue"). + 
-    balance The unpaid portion of the fine IN PENNIES. +^ Key              ^ Type               ^ Required         ^ Minimum Version  ^ Description ^ 
-    createdate – A string representing the date when the fine was accrued (optional) +amount           | int                | No                                | The total amount of the fine IN PENNIES.  Be sure to adjust decimal points appropriately (i.e. for a $1.00 fine, amount should be set to 100) | 
-    duedate A string representing the date when the item was due. +checkout         | string             | No                                | A string representing the date when the item was checked out | 
-    id The bibliographic ID of the record involved in the fine. +fine             | string             | No                                | A string describing the reason for the fine (i.e. "Overdue", "Long Overdue"
-    source The search backend from which the record may be retrieved (optional - defaults to Solr). // Introduced in VuFind 2.4. //+| description      | string             | No               | 10.0             | A string with textual description for the fine (e.g. manual fine reason) | 
 +balance          | int                | No                                | The unpaid portion of the fine IN PENNIES | 
 +createdate       | string             | No                                | A string representing the date when the fine was accrued (optional) | 
 +duedate          | string             | No                                | A string representing the date when the item was due | 
 +id               | string             | No                                | The bibliographic ID of the record involved in the fine | 
 +source           | string             | No               | 2.4              | The search backend from which the record may be retrieved (defaults to Solr) |
  
 ==== getMyHolds ==== ==== getMyHolds ====
Line 339: Line 364:
 | id               | string             | No                                | Bibliographic record ID associated with the hold | | id               | string             | No                                | Bibliographic record ID associated with the hold |
 | source           | string             | No               | 2.4              | Search backend from which the record may be retrieved (defaults to Solr) | | source           | string             | No               | 2.4              | Search backend from which the record may be retrieved (defaults to Solr) |
-| item_id          | string             | with cancelHolds |                  | Item id of the requested item (must be unique if cancelHolds is supported) | +| item_id          | string             | with cancelHolds |                  | Item id of the requested item (must be unique if cancelHolds is supported) | 
-| location         | string             | No               | 1.3              | In VuFind 1.3 and later, either a locationID value or a raw ready-to-display string. In VuFind 1.2, should correspond with a locationID value from getPickUpLocations. |+| location         | string             | No               | 1.3              | In VuFind® 1.3 and later, either a locationID value or a raw ready-to-display string. In VuFind® 1.2, should correspond with a locationID value from getPickUpLocations. |
 | reqnum           | string             | with updateHolds |                  | A control number for the request (must be unique if updateHolds is supported) | | reqnum           | string             | with updateHolds |                  | A control number for the request (must be unique if updateHolds is supported) |
 | expire           | locale date string | No                                | Expiration date of the hold | | expire           | locale date string | No                                | Expiration date of the hold |
Line 347: Line 372:
 | available        | boolean            | No                                | Whether or not the hold is available for pickup | | available        | boolean            | No                                | Whether or not the hold is available for pickup |
 | in_transit       | string/boolean     | No                                | If in transit, either boolean true or a string describing the destination location; false otherwise | | in_transit       | string/boolean     | No                                | If in transit, either boolean true or a string describing the destination location; false otherwise |
-| last_pickup_date | locale date string | No               | 5.1              | A string representing the deadline for picking up the item; ignored unless available (above) is set to true | +| last_pickup_date | locale date string | No               | 5.1              | A string representing the deadline for picking up the item; ignored unless available (above) is set to true | 
-| frozen           | boolean            | with frozenUntil | 8.0              | Whether the hold is temporarily suspended | +| frozen           | boolean            | with frozenThrough | 8.0              | Whether the hold is temporarily suspended | 
-frozenUntil      | locale date string | No               | 8.0              | Last suspension date if a hold is temporarily suspended |+frozenThrough    | locale date string | No               | 8.0              | Last suspension date if a hold is temporarily suspended |
 | cancel_details   | string             | No               | 3.1              | A cancel token, or a blank string to indicate that the hold cannot be canceled. If omitted, this will be dynamically generated using getCancelHoldDetails(). The value is passed to the cancelHolds method when a hold is canceled. You can fill this in if it is efficient to calculate the value up front; if it is an expensive calculation, you should omit the value entirely and let getCancelHoldDetails() do its job on demand (note, however, that getCancelHoldDetails is currently called for each hold unconditionally). | | cancel_details   | string             | No               | 3.1              | A cancel token, or a blank string to indicate that the hold cannot be canceled. If omitted, this will be dynamically generated using getCancelHoldDetails(). The value is passed to the cancelHolds method when a hold is canceled. You can fill this in if it is efficient to calculate the value up front; if it is an expensive calculation, you should omit the value entirely and let getCancelHoldDetails() do its job on demand (note, however, that getCancelHoldDetails is currently called for each hold unconditionally). |
 | updateDetails    | string             | No               | 8.0              | An update token, or a blank string to indicate that the hold cannot be updated. The value is passed to the updateHolds method when holds are updated. If both this and cancel_details are non-empty, the values must match. | | updateDetails    | string             | No               | 8.0              | An update token, or a blank string to indicate that the hold cannot be updated. The value is passed to the updateHolds method when holds are updated. If both this and cancel_details are non-empty, the values must match. |
-| title            | string             | No                                | Title of the item (only used if the record cannot be found in VuFind's index) |+| title            | string             | No                                | Title of the item (only used if the record cannot be found in VuFind®'s index) |
 | publication_year | string             | No                                | Publication year of the item | | publication_year | string             | No                                | Publication year of the item |
 | volume           | string             | No                                | Volume number of the item | | volume           | string             | No                                | Volume number of the item |
Line 359: Line 384:
 | oclc             | string             | No               | 2.3              | OCLC number for use in cover image loading | | oclc             | string             | No               | 2.3              | OCLC number for use in cover image loading |
 | upc              | string             | No               | 2.3              | UPC for use in cover image loading | | upc              | string             | No               | 2.3              | UPC for use in cover image loading |
 +| proxiedBy        | string             | No               | 9.0              | Display name of user that placed the request (if different from the current user) | 
 +| proxiedFor       | string             | No               | 9.0              | Display name of user for whom the request was placed (if different from the current user) |
 ==== getMyILLRequests ==== ==== getMyILLRequests ====
-This method queries the ILS for a patron's current ILL requests. (optional) // Not supported prior to VuFind 2.3 // +This method queries the ILS for a patron's current ILL requests. (optional) // Not supported prior to VuFind® 2.3 // 
  
   * Input: Patron array returned by patronLogin method   * Input: Patron array returned by patronLogin method
   * Output: Returns an array of associative arrays, one for each request associated with the specified account. Each associative array contains these keys:   * Output: Returns an array of associative arrays, one for each request associated with the specified account. Each associative array contains these keys:
     * id - The bibliographic record ID associated with the request (optional).     * id - The bibliographic record ID associated with the request (optional).
-    * source - The search backend from which the record may be retrieved (optional - defaults to Solr). // Introduced in VuFind 2.4. //+    * source - The search backend from which the record may be retrieved (optional - defaults to Solr). // Introduced in VuFind® 2.4. //
     * location - A string describing the pickup location for the requested item (optional).  It may be either a locationID value or a raw ready-to-display string.     * location - A string describing the pickup location for the requested item (optional).  It may be either a locationID value or a raw ready-to-display string.
     * reqnum - A control number for the request (optional).     * reqnum - A control number for the request (optional).
Line 377: Line 403:
     * issue - The issue of the item (optional).     * issue - The issue of the item (optional).
     * year – The publication year of the item (optional).     * year – The publication year of the item (optional).
-    * title - The title of the item (optional -- only used if the record cannot be found in VuFind's index).+    * title - The title of the item (optional -- only used if the record cannot be found in VuFind®'s index).
     * canceled - Boolean or date (string) indicating that the request has been canceled.     * canceled - Boolean or date (string) indicating that the request has been canceled.
     * processed - Boolean or date (string) indicating that the request has been processed.     * processed - Boolean or date (string) indicating that the request has been processed.
Line 394: Line 420:
     * address1     * address1
     * address2     * address2
-    * city (added in VuFind 2.3) +    * city (added in VuFind® 2.3) 
-    * country (added in VuFind 2.3)+    * country (added in VuFind® 2.3)
     * zip     * zip
     * phone     * phone
-    * mobile_phone (added in VuFind 5.0)+    * mobile_phone (added in VuFind® 5.0)
     * group -- i.e. Student, Staff, Faculty, etc.     * group -- i.e. Student, Staff, Faculty, etc.
-    * expiration_date -- account expiration date (added in VuFind 4.1)+    * expiration_date -- account expiration date (in display format, added in VuFind® 4.1
 +    * birthdate (Y-m-d or an empty string, added in VuFind® 9.0)
  
 ==== getMyStorageRetrievalRequests ==== ==== getMyStorageRetrievalRequests ====
-This method queries the ILS for a patron's current storage retrieval requests. (optional) // Not supported prior to VuFind 2.3 // +This method queries the ILS for a patron's current storage retrieval requests. (optional) // Not supported prior to VuFind® 2.3 // 
  
   * Input: Patron array returned by patronLogin method   * Input: Patron array returned by patronLogin method
   * Output: Returns an array of associative arrays, one for each request associated with the specified account. Each associative array contains these keys:   * Output: Returns an array of associative arrays, one for each request associated with the specified account. Each associative array contains these keys:
     * id - The bibliographic record ID associated with the request (optional).     * id - The bibliographic record ID associated with the request (optional).
-    * source - The search backend from which the record may be retrieved (optional - defaults to Solr). // Introduced in VuFind 2.4. //+    * source - The search backend from which the record may be retrieved (optional - defaults to Solr). // Introduced in VuFind® 2.4. //
     * location - A string describing the pickup location for the requested item (optional).  It may be either a locationID value or a raw ready-to-display string.     * location - A string describing the pickup location for the requested item (optional).  It may be either a locationID value or a raw ready-to-display string.
     * reqnum - A control number for the request (optional).     * reqnum - A control number for the request (optional).
Line 419: Line 446:
     * issue - The issue of the item (optional).     * issue - The issue of the item (optional).
     * year – The publication year of the item (optional).     * year – The publication year of the item (optional).
-    * title - The title of the item (optional -- only used if the record cannot be found in VuFind's index).+    * title - The title of the item (optional -- only used if the record cannot be found in VuFind®'s index).
     * canceled - Boolean or date (string) indicating that the request has been canceled.     * canceled - Boolean or date (string) indicating that the request has been canceled.
     * processed - Boolean or date (string) indicating that the request has been processed.     * processed - Boolean or date (string) indicating that the request has been processed.
Line 433: Line 460:
 :!: The getConfig method must return a non-false value for this feature to be enabled. For privacy reasons, the entire feature should be disabled by default unless explicitly turned on in the driver's .ini file. :!: The getConfig method must return a non-false value for this feature to be enabled. For privacy reasons, the entire feature should be disabled by default unless explicitly turned on in the driver's .ini file.
  
-// This feature was added in VuFind 5.0. //+// This feature was added in VuFind® 5.0. //
  
   * getConfig may return the following keys if the service supports paging on the ILS side:   * getConfig may return the following keys if the service supports paging on the ILS side:
Line 442: Line 469:
     * sort - An associative array where each key is a sort key and its value is a translation key     * sort - An associative array where each key is a sort key and its value is a translation key
     * default_sort - Default sort key      * default_sort - Default sort key 
 +  * getConfig may return also the following keys with boolean true as the value if the service supports purging of all or selected entries from the history:
 +    * purge_all - Supports purging of all entries
 +    * purge_selected - Supports purging of selected entries
   * Input: Patron array returned by patronLogin method and an array of optional parameters (keys = 'limit', 'page', 'sort').   * Input: Patron array returned by patronLogin method and an array of optional parameters (keys = 'limit', 'page', 'sort').
   * Output: Returns an array of associative arrays containing some or all of these keys:   * Output: Returns an array of associative arrays containing some or all of these keys:
Line 455: Line 485:
     * borrowingLocation - checkout location     * borrowingLocation - checkout location
     * message - message about the transaction     * message - message about the transaction
 +    * row_id - ID of the transaction history row (required if purgeTransactionHistory is enabled)
  
 ==== getMyTransactions ==== ==== getMyTransactions ====
 This method queries the ILS for a patron's current checked out items This method queries the ILS for a patron's current checked out items
-  * Starting with VuFind 5.1, getConfig may return the following keys if the service supports paging on the ILS side: +  * Starting with VuFind® 5.1, getConfig may return the following keys if the service supports paging on the ILS side: 
-    * max_results - Maximum number of results that can be requested at once. Overrides the config.ini Catalog section setting historic_loan_page_size.+    * max_results - Maximum number of results that can be requested at once. Overrides the config.ini Catalog section setting checked_out_page_size.
     * page_size - An array of allowed page sizes (number of records per page)     * page_size - An array of allowed page sizes (number of records per page)
     * default_page_size - Default number of records per page     * default_page_size - Default number of records per page
-  * Starting with VuFind 5.1, getConfig may return also the following keys if the service supports sorting:+  * Starting with VuFind® 5.1, getConfig may return also the following keys if the service supports sorting:
     * sort - An associative array where each key is a sort key and its value is a translation key     * sort - An associative array where each key is a sort key and its value is a translation key
     * default_sort - Default sort key      * default_sort - Default sort key 
-  * Input: Patron array returned by patronLogin method, and (starting with VuFind 5.1) an optional array of parameters (keys = 'limit', 'page', 'sort'+  * Input: Patron array returned by patronLogin method, and (starting with VuFind® 5.1) an optional array of parameters (keys = 'limit', 'page', 'sort'
-  * Output: Starting with VuFind 5.1, may return an array with 'count' and 'records' keys, where 'count' is the total number of transactions available, and 'records' is the currently-requested page of results (in the format described below). Prior to 5.1, always returned an array of associative arrays, one for each item checked out by the specified account; this response format is still supported for drivers that do not allow pagination. Each associative array contains these keys:+  * Output: Starting with VuFind® 5.1, may return an array with 'count' and 'records' keys, where 'count' is the total number of transactions available, and 'records' is the currently-requested page of results (in the format described below). Prior to 5.1, always returned an array of associative arrays, one for each item checked out by the specified account; this response format is still supported for drivers that do not allow pagination. Each associative array contains these keys:
     * duedate - The item's due date (a string).     * duedate - The item's due date (a string).
     * dueTime - The item's due time (a string, optional).     * dueTime - The item's due time (a string, optional).
-    * dueStatus - A special status -- may be 'due' (for items due very soon) or 'overdue' (for overdue items). If this is false, empty string, or unset, VuFind will assume that items have no special status. (optional).+    * dueStatus - A special status -- may be 'due' (for items due very soon) or 'overdue' (for overdue items). If this is false, empty string, or unset, VuFind® will assume that items have no special status. (optional).
     * id - The bibliographic ID of the checked out item.     * id - The bibliographic ID of the checked out item.
-    * source - The search backend from which the record may be retrieved (optional - defaults to Solr). // Introduced in VuFind 2.4. //+    * source - The search backend from which the record may be retrieved (optional - defaults to Solr). // Introduced in VuFind® 2.4. //
     * barcode - The barcode of the item (optional).     * barcode - The barcode of the item (optional).
     * renew - The number of times the item has been renewed (optional).     * renew - The number of times the item has been renewed (optional).
-    * renewLimit - The maximum number of renewals allowed (optional - introduced in VuFind 2.3).+    * renewLimit - The maximum number of renewals allowed (optional - introduced in VuFind® 2.3).
     * request - The number of pending requests for the item (optional).     * request - The number of pending requests for the item (optional).
     * volume – The volume number of the item (optional).     * volume – The volume number of the item (optional).
Line 480: Line 511:
     * renewable – Whether or not an item is renewable (required for renewals).     * renewable – Whether or not an item is renewable (required for renewals).
     * message – A message regarding the item (optional).     * message – A message regarding the item (optional).
-    * title - The title of the item (optional -- only used if the record cannot be found in VuFind's index).+    * title - The title of the item (optional -- only used if the record cannot be found in VuFind®'s index).
     * item_id - this is used to match up renew responses and must match the item_id in the renew response.     * item_id - this is used to match up renew responses and must match the item_id in the renew response.
     * institution_name - Display name of the institution that owns the item (optional). Used e.g. with received interlibrary loans (ILL) if they are displayed in the checked out items list (e.g. UB Requests between Voyager libraries).     * institution_name - Display name of the institution that owns the item (optional). Used e.g. with received interlibrary loans (ILL) if they are displayed in the checked out items list (e.g. UB Requests between Voyager libraries).
Line 499: Line 530:
   * Output: An associative array with two keys: 'count' (the number of items in the 'results' array) and 'results' (an array of associative arrays, each with a single key: 'id', a record ID).   * Output: An associative array with two keys: 'count' (the number of items in the 'results' array) and 'results' (an array of associative arrays, each with a single key: 'id', a record ID).
  
-//IMPORTANT: The fundID parameter changed behavior in r2184.  In VuFind 1.0RC2 and earlier versions, it receives one of the VALUES returned by getFunds(); in more recent code, it receives one of the KEYS from getFunds().  See getFunds for additional notes.//+//IMPORTANT: The fundID parameter changed behavior in r2184.  In VuFind® 1.0RC2 and earlier versions, it receives one of the VALUES returned by getFunds(); in more recent code, it receives one of the KEYS from getFunds().  See getFunds for additional notes.//
  
 ==== getOfflineMode ==== ==== getOfflineMode ====
-This optional method (introduced in VuFind 1.4) gets the online status of the ILS -- "ils-offline" for systems where the main ILS is offline, "ils-none" for systems which do not use an ILS, false for systems that are fully online.  If not implemented, the value defaults to false -- most drivers will not need to worry about this method, which is primarily used by the special NoILS driver.+This optional method (introduced in VuFind® 1.4) gets the online status of the ILS -- "ils-offline" for systems where the main ILS is offline, "ils-none" for systems which do not use an ILS, false for systems that are fully online.  If not implemented, the value defaults to false -- most drivers will not need to worry about this method, which is primarily used by the special NoILS driver.
  
   * Output: string or false, as described above   * Output: string or false, as described above
  
 ==== getPickUpLocations ==== ==== getPickUpLocations ====
-This method returns a list of locations where a user may collect a hold. (optional) // Not supported prior to VuFind 1.2 //+This method returns a list of locations where a user may collect a hold. (optional) // Not supported prior to VuFind® 1.2 //
  
-  * Input: Patron array returned by patronLogin method (optional), hold information array similar to placeHold's input (optionalprovided only when user is in the process of placing a hold -- may be used to limit the available pickup options based on item ID, etc.; must never add new options to the return array -- may only be used as a limiter; not supported prior to VuFind 1.3) +Input:  
-  Output: Array of associative arrays containing these keys+ 
-    locationID A pick up location id or code (string) +^ Parameter        ^ Type               ^ Always Provided  ^ Minimum Version  ^ Description ^ 
-    locationDisplay – The text to display for the location (string)+| patron           array              | No                                | Patron information from patronLogin 
 +| holdDetails      | array              | No               | 1.3              | When in the process of placing a hold, an array similar to placeHold's input. When editing a hold, the hold information returned by getMyHolds. May be used to limit the available pickup options based on item ID, etc.; must never add new options to the return array -- may only be used as a limiter. 
 + 
 +Output: An array of associative arrrays with the following fields
 + 
 +^ Key              ^ Type               ^ Required         ^ Minimum Version  ^ Description ^ 
 +locationID       | string             | Yes              |                  | A pick up location id or code | 
 +locationDisplay  | string             | Yes              |                  | The text to display for the location 
 + 
 +==== getProxiedUsers ==== 
 + 
 +This method returns a list of users for which the provided user can place proxy requests. // This method was added in VuFind® 9.0. // 
 + 
 +  * Input: Patron array returned by patronLogin method 
 +  * Output: Associative array of user ID => user display name
  
 ==== getPurchaseHistory ==== ==== getPurchaseHistory ====
Line 524: Line 569:
  
 ==== getRenewDetails ==== ==== getRenewDetails ====
-This method returns a string to use as the input form value for renewing each hold item. (optional, but required if you implement the renewMyItems method) // Not supported prior to VuFind 1.2 //+This method returns a string to use as the input form value for renewing each hold item. (optional, but required if you implement the renewMyItems method) // Not supported prior to VuFind® 1.2 //
  
   * Input: checkOutDetails - One of the individual item arrays returned by the getMyTransactions method   * Input: checkOutDetails - One of the individual item arrays returned by the getMyTransactions method
Line 531: Line 576:
 ==== getRequestBlocks ==== ==== getRequestBlocks ====
  
-This optional method returns an array of strings describing reasons for blocking the active user from placing requests (holds, recalls, etc.). If no blocks are in place, it returns false. // Not supported prior to VuFind 4.0 //+This optional method returns an array of strings describing reasons for blocking the active user from placing requests (holds, recalls, etc.). If no blocks are in place, it returns false. // Not supported prior to VuFind® 4.0 //
  
   * Input: patron (array returned by the driver's patronLogin method)   * Input: patron (array returned by the driver's patronLogin method)
Line 538: Line 583:
 ==== getRequestGroups ==== ==== getRequestGroups ====
  
-This optional method returns information used to group together collections of pickup locations. // Not supported prior to VuFind 2.3. //+This optional method returns information used to group together collections of pickup locations. // Not supported prior to VuFind® 2.3. //
  
-  * Input: bibID (of record being requested), Patron Data (from patronLogin() method), holdDetails (Optional array, only passed in when getting a list in the context of placing a hold; contains most of the same values passed to placeHold, minus the patron data.  May be used to limit the request group options or may be ignored; added in VuFind 4.0).+  * Input: bibID (of record being requested), Patron Data (from patronLogin() method), holdDetails (Optional array, only passed in when getting a list in the context of placing a hold; contains most of the same values passed to placeHold, minus the patron data.  May be used to limit the request group options or may be ignored; added in VuFind® 4.0).
   * Output: False if request groups not in use or an array of associative arrays with id and name keys   * Output: False if request groups not in use or an array of associative arrays with id and name keys
  
Line 548: Line 593:
   * Input: Bibliographic record ID   * Input: Bibliographic record ID
   * Output: Returns an array of associative arrays, one for each item attached to the specified bibliographic record. Each associative array contains these keys:   * Output: Returns an array of associative arrays, one for each item attached to the specified bibliographic record. Each associative array contains these keys:
-    * id The bibliographic record ID (same as input). + 
-    * status - String describing the status of the item. +^ Key              ^ Type               ^ Required         ^ Minimum Version  ^ Description ^ 
-    location - The location of the item (string). Note: prior to VuFind 1.3, some drivers HTML entity encoded this string; that is incorrect behavior in VuFind 1.3 or later -- this should be plain text, not HTML. +id               | string             | yes              |                  | The bibliographic record ID (same as input) | 
-    reserve Is the item on course reserve?  ("Y" for yes, "N" for no). +| availability     | boolean/int        | yes              | / 9.1          | Is the item available (i.e. on the shelf and/or available for checkout)? See the description in getHolding for further information. | 
-    callnumber - The item'call number+status           | string             | yes              |                  | description of the availability status of the item | 
-    * availability - Boolean: is the item available (i.e. on the shelf and/or available for checkout)? +location         | string             | yes              |                  | description of the physical location of the item. Note: prior to VuFind® 1.3, some drivers HTML entity encoded this string; that is incorrect behavior in VuFind® 1.3 or later -- this should be plain text, not HTML. | 
-    use_unknown_message - An optional boolean that, when set to true, will cause display of a message indicating that the status of the item is unknown. +reserve          | string             | yes              |                  | Is the item on course reserve?  ("Y" for yes, "N" for no) | 
-    services - Starting with VuFind 3.0, this optional value can be used to indicate availability services (loan, presence). When set, the value is expected to be an array of strings representing available services for the current item. These services will be displayed in the result list in order to provide more detailed availability information than simply showing binary available/unavailable status. Further display control can be achieved through CSS classes assigned to every service. For now, only the services "loan" (available to be borrowed) and "presentation" (available for use within the institution) are supported (including appropriate translation strings). See additional documentation on services [[development:architecture:real_time_availability_status#services|here]]. +callnumber       | string             | yes              |                  | the call number of this item 
-    error - Starting with VuFind 5.0, if you set this to an error string, all other fields except id will be ignored, and the error message will be displayed to the user along with an "Item Status Unavailable" status. This is particularly useful in the [[configuration:ils:multibackend_driver|MultiBackend driver]] for dealing with partial failures, but other applications may exist.+| callnumber_prefix | string            | no               | 8.0              | a call number prefix (i.e. a value that sets the context of the call number, such as a material format designation, but is not part of the call number for sorting purposes, etc.| 
 +use_unknown_message | bool            | no                                | when set to true, will cause display of a message indicating that the status of the item is unknown. | 
 +services         | string[]           | no               3.0              | This can be used to indicate availability services (loan, presence). When set, the value is expected to be an array of strings representing available services for the current item. These services will be displayed in the result list in order to provide more detailed availability information than simply showing binary available/unavailable status. Further display control can be achieved through CSS classes assigned to every service. For now, only the services "loan" (available to be borrowed) and "presentation" (available for use within the institution) are supported (including appropriate translation strings). See additional documentation on services [[development:architecture:real_time_availability_status#services|here]]. | 
 +error            | string             | no               5.0              | If you set this to an error string, all other fields except id will be ignored, and the error message will be displayed to the user along with an "Item Status Unavailable" status. This is particularly useful in the [[configuration:ils:multibackend_driver|MultiBackend driver]] for dealing with partial failures, but other applications may exist. |
  
 Note: Some driver implementations add additional values beyond those listed above.  However, these extra values are not used by core code and should generally be ignored. Note: Some driver implementations add additional values beyond those listed above.  However, these extra values are not used by core code and should generally be ignored.
Line 567: Line 615:
  
 ==== getSuppressedAuthorityRecords ==== ==== getSuppressedAuthorityRecords ====
-Return a list of suppressed authority records (used to remove non-visible items from VuFind's index). // Note: this method was introduced in VuFind 1.4. //+Return a list of suppressed authority records (used to remove non-visible items from VuFind®'s index). // Note: this method was introduced in VuFind® 1.4. //
  
   * Output: An array of authority record IDs.   * Output: An array of authority record IDs.
  
 ==== getSuppressedRecords ==== ==== getSuppressedRecords ====
-Return a list of suppressed bibliographic records (used to remove non-visible items from VuFind's index).+Return a list of suppressed bibliographic records (used to remove non-visible items from VuFind®'s index).
  
   * Output: An array of bibliographic record IDs.   * Output: An array of bibliographic record IDs.
 +
 +==== getUrlsForRecord ====
 +This optional method (introduced in VuFind® 9.1) returns one or more ILS-specific links associated with the provided bibliographic record ID.
 +
 +  * Input: Bibliographic record ID
 +  * Output: Link data (in the same format returned by the record driver's getURLs method)
  
 ==== hasHoldings ==== ==== hasHoldings ====
-This optional method (introduced in VuFind 1.4) can be used to hide the holdings tab for records where holdings do not apply.  Most drivers will not need to implement this -- it is primarily for use by the special NoILS driver.+This optional method (introduced in VuFind® 1.4) can be used to hide the holdings tab for records where holdings do not apply.  Most drivers will not need to implement this -- it is primarily for use by the special NoILS driver.
  
   * Input: Bibliographic ID   * Input: Bibliographic ID
Line 589: Line 643:
  
 ==== loginIsHidden ==== ==== loginIsHidden ====
-This optional method (introduced in VuFind 1.4) can be used to hide VuFind's login options.  Most drivers will not need to implement this -- it is primarily for use by the special NoILS driver.+This optional method (introduced in VuFind® 1.4) can be used to hide VuFind®'s login options.  Most drivers will not need to implement this -- it is primarily for use by the special NoILS driver.
  
   * Output: true if login should be hidden, false otherwise.   * Output: true if login should be hidden, false otherwise.
Line 596: Line 650:
 This method processes authentication against the ILS.  This method processes authentication against the ILS. 
  
-When ILS or MultiILS authentication is used as the login method, the username in VuFind's user table is, by default, taken from cat_username but it's configurable with the ILS_username_field in [Authentication] section of [[configuration:files:config.ini]].+When ILS or MultiILS authentication is used as the login method, the username in VuFind®'s user table is, by default, taken from cat_username but it's configurable with the ILS_username_field in [Authentication] section of [[configuration:files:config.ini]].
  
-Starting with version 4.0, VuFind uses the id field as the primary link between the ILS user and the VuFind user. The cat_username field or the field configured above is used if the user cannot be found with id. The idea is to have a more persistent link between the account (since cat_username is typically a library card, and a card may need to be changed, it's not really permanent) while allowing the existing accounts that don't yet have the id in them to be found.+Starting with version 4.0, VuFind® uses the id field as the primary link between the ILS user and the VuFind® user. The cat_username field or the field configured above is used if the user cannot be found with id. The idea is to have a more persistent link between the account (since cat_username is typically a library card, and a card may need to be changed, it's not really permanent) while allowing the existing accounts that don't yet have the id in them to be found.
  
 Depending on the driver and its configuration, the username may be a library card number, an email address or another patron identifier. For instance with Alma there are a couple of different login methods, and only the regular password authentication uses the password parameter. Depending on the driver and its configuration, the username may be a library card number, an email address or another patron identifier. For instance with Alma there are a couple of different login methods, and only the regular password authentication uses the password parameter.
Line 614: Line 668:
  
 ==== placeHold ==== ==== placeHold ====
-This method places a hold on a specific record for a specific patron. (Optional – if this feature is not supported by the ILS, you can define the getHoldLink method instead).  // This method was not consistently implemented until VuFind 1.2 -- earlier drivers may include a placeHold method, but none of those early versions are supported by standard core code. //+This method places a hold on a specific record for a specific patron. (Optional – if this feature is not supported by the ILS, you can define the getHoldLink method instead).  // This method was not consistently implemented until VuFind® 1.2 -- earlier drivers may include a placeHold method, but none of those early versions are supported by standard core code. //
  
   * Input: holdDetails - An associative array with several keys.  'patron' will always be defined to contain the array returned by patronLogin method; other fields may vary depending on the fields defined in the HMACKeys and extraHoldFields settings returned by the getConfig method.  Some commonly used values:   * Input: holdDetails - An associative array with several keys.  'patron' will always be defined to contain the array returned by patronLogin method; other fields may vary depending on the fields defined in the HMACKeys and extraHoldFields settings returned by the getConfig method.  Some commonly used values:
Line 622: Line 676:
     * comment - user comment     * comment - user comment
     * id - bibliographic ID     * id - bibliographic ID
-    * level - starting with VuFind 1.4, this key may be passed in set to 'title' when a user requests a title-level hold; in order for the title-level hold mechanism to work correctly, make sure that the HMACKeys setting returned by getConfig('Holds') includes 'level'.+    * level - starting with VuFind® 1.4, this key may be passed in set to 'title' when a user requests a title-level hold; in order for the title-level hold mechanism to work correctly, make sure that the HMACKeys setting returned by getConfig('Holds') includes 'level'.
   * Output: Associative array containing:   * Output: Associative array containing:
     * success – Boolean true or false     * success – Boolean true or false
Line 628: Line 682:
  
 ==== placeILLRequest ==== ==== placeILLRequest ====
-This method places an ILL request on a specific record for a specific patron. (optional) // Not supported prior to VuFind 2.3 // +This method places an ILL request on a specific record for a specific patron. (optional) // Not supported prior to VuFind® 2.3 // 
  
   * Input: details - An associative array with several keys.  'patron' will always be defined to contain the array returned by patronLogin method; other fields may vary depending on the fields defined in the HMACKeys and extraFields settings returned by the getConfig method.  Some commonly used values:   * Input: details - An associative array with several keys.  'patron' will always be defined to contain the array returned by patronLogin method; other fields may vary depending on the fields defined in the HMACKeys and extraFields settings returned by the getConfig method.  Some commonly used values:
Line 641: Line 695:
  
 ==== placeStorageRetrievalRequest ==== ==== placeStorageRetrievalRequest ====
-This method places a storage retrieval request on a specific record for a specific patron. (optional) // Not supported prior to VuFind 2.3 // +This method places a storage retrieval request on a specific record for a specific patron. (optional) // Not supported prior to VuFind® 2.3 // 
  
   * Input: details - An associative array with several keys.  'patron' will always be defined to contain the array returned by patronLogin method; other fields may vary depending on the fields defined in the HMACKeys and extraFields settings returned by the getConfig method.  Some commonly used values:   * Input: details - An associative array with several keys.  'patron' will always be defined to contain the array returned by patronLogin method; other fields may vary depending on the fields defined in the HMACKeys and extraFields settings returned by the getConfig method.  Some commonly used values:
Line 652: Line 706:
     * success – Boolean true or false     * success – Boolean true or false
     * sysMessage – A system supplied failure message (optional)     * sysMessage – A system supplied failure message (optional)
 +
 +==== purgeTransactionHistory ====
 +
 +// Not supported prior to VuFind® 9.1 //
 +
 +This method deletes selected entries or all entries from the transaction (checkout) history. 
 +
 +Availability of purge options in the UI is controlled by getConfig for getMyTransactionHistory returning ''purge_all = true'' and/or ''purge_selected = true''.
 +
 +Input: 
 +
 +^ Parameter        ^ Type               ^ Always Provided  ^ Minimum Version  ^ Description ^
 +| patron           | array              | Yes              |                  | Patron information from patronLogin |
 +| ids              | array or null      | No                                | Array of row_id's from getMyTransactionHistory or null to purge all entries from the transaction history  |
 +
 +Output: An associative array containing the following fields:
 +
 +^ Key              ^ Type               ^ Required         ^ Minimum Version  ^ Description ^
 +| success          | boolean            | Yes              |                  | Whether the purge request was successful |
 +| status           | string             | If success=false |                  | Status string containing information on why the purge request failed |
 +| sysMessage       | string             | No                                | System message that can be displayed to the user to further explain the reason for a failure |
  
 ==== renewMyItems ==== ==== renewMyItems ====
-This method renews a list of items for a specific patron. (optional -- you may wish to implement getRenewLink instead if your ILS does not support direct renewals) // Not supported prior to VuFind 1.2 //+This method renews a list of items for a specific patron. (optional -- you may wish to implement getRenewLink instead if your ILS does not support direct renewals) // Not supported prior to VuFind® 1.2 //
   * Input: renewDetails - An associative array with two keys:   * Input: renewDetails - An associative array with two keys:
     * patron - array returned by patronLogin method     * patron - array returned by patronLogin method
Line 668: Line 743:
  
 ==== renewMyItemsLink ==== ==== renewMyItemsLink ====
-This method returns a URL to use as a link to a native OPAC for renewing each item. (optional, and should not be implemented unless your ILS is unable to support implementation of the renewMyItems method). // Not supported prior to VuFind 1.2 //+This method returns a URL to use as a link to a native OPAC for renewing each item. (optional, and should not be implemented unless your ILS is unable to support implementation of the renewMyItems method). // Not supported prior to VuFind® 1.2 //
  
   * Input: checkOutDetails - One of the individual item arrays returned by the getMyTransactions method   * Input: checkOutDetails - One of the individual item arrays returned by the getMyTransactions method
Line 684: Line 759:
   * Input: method name, array of parameters   * Input: method name, array of parameters
   * Output: boolean true (method is supported) or false (method is not supported)   * Output: boolean true (method is supported) or false (method is not supported)
 +
 +==== updateHolds ====
 +This method updates a list of holds for a specific patron. (optional)  // Not supported prior to VuFind® 8.0 //
 +
 +Input: 
 +
 +^ Parameter        ^ Type               ^ Always Provided  ^ Minimum Version  ^ Description ^
 +| holdsDetails     | array              | Yes              |                  | Array of updateDetails strings to identify the holds to update |
 +| fields           | array              | Yes              |                  | Associative array of fields to update. The array contains only fields modified by the user. |
 +| patron           | array              | Yes              |                  | Patron information from patronLogin |
 +
 +Output: An associative array with reqnum as the key, containing arrays with the following fields:
 +
 +^ Key              ^ Type               ^ Required         ^ Minimum Version  ^ Description ^
 +| success          | boolean            | Yes              |                  | Whether the hold was successfully updated |
 +| status           | string             | If success=false |                  | Status string containing information on why the hold was not updated, subject to translation |
 +| sysMessage       | string             | No                                | System message that can be displayed to the user to further explain the reason for the update failure |
  
 ===== Further Reading ===== ===== Further Reading =====
  
-  * [[http://blog.library.villanova.edu/libtech/2011/06/02/expanded-ils-functionality-in-vufind/|Expanded ILS Functionality in VuFind]] -- Blog post providing an overview of how the driver's hold/recall/renewal functionality works.+  * [[http://blog.library.villanova.edu/libtech/2011/06/02/expanded-ils-functionality-in-vufind/|Expanded ILS Functionality in VuFind®]] -- Blog post providing an overview of how the driver's hold/recall/renewal functionality works.
   * [[configuration:ils:troubleshooting|ILS Driver Troubleshooting]]   * [[configuration:ils:troubleshooting|ILS Driver Troubleshooting]]
 +
 +===== Related Video =====
 +
 +See [[videos:ils_drivers_1|ILS Drivers, Part 1]] for further discussion of ILS drivers.
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : 
 ---- ----
  
development/plugins/ils_drivers.1623070963.txt.gz · Last modified: 2021/06/07 13:02 by emaijala