| Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
| development:plugins:ils_drivers [2021/06/07 13:23] – [getConfig] emaijala | development:plugins:ils_drivers [2021/08/26 11:56] – Add and update help text settings, fix available fields in updateFields emaijala |
|---|
| 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 |
| |
| ==== 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: |
| * 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. |
| * updateFields (optional) - (From VuFind 8.0) A colon-separated list of form fields to include in the update holds form; may include "frozen", "frozenUntil" and "pickUpLocation". Note that all parameters activated here must be processed by the updateHolds method. | * 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[lng] - A language-specific help text displayed on the hold request form. Displayed as is; HTML tags can be used, but everything needs to be properly escaped. |
| | * updateHelpText - (From VuFind 8.0) A generic help text displayed on the hold update form. Displayed as is; HTML tags can be used, but 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, but 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" |
| * 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, but everything needs to be properly escaped. |
| * helpText[lng] - A language-specific help text displayed on the request form. | * helpText[lng] - A language-specific help text displayed on the request form. Displayed as is; HTML tags can be used, but 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) |
| * 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, but everything needs to be properly escaped. |
| * helpText[lng] - A language-specific help text displayed on the request form. | * helpText[lng] - A language-specific help text displayed on the request form. Displayed as is; HTML tags can be used, but 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) |
| ==== 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. // |
| | |
| | :!: 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) | * 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) |
| * 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)? | ^ Key ^ Type ^ Required ^ Minimum Version ^ Description ^ |
| * status - string describing the availability status of the item | | id | string | yes | | the RecordID that was passed in | |
| * 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. | | availability | boolean | yes | | is the item available (i.e. on the shelf and/or available for checkout)? | |
| * location_code - an internal code representing the location. (optional) | | status | string | yes | | description of the availability status of the item | |
| * locationhref - a URL to link the location name to. (optional, introduced in VuFind 2.5) | | 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. | |
| * reserve - string indicating "on reserve" status -- legal values: 'Y' or 'N' | | location_code | string | no | | an internal code representing the location. | |
| * callnumber - the call number of this item | | locationhref | string | no | 2.5 | a URL to link the location name to. | |
| * duedate - string showing due date of checked out item (null if not checked out) | | reserve | string | yes | | "on reserve" status -- legal values: 'Y' or 'N' | |
| * returnDate - A string showing return date of an item (false if not recently returned) | | callnumber | string | yes | | the call number of this item | |
| * 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) | | 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.) | |
| * 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. | | duedate | string | no | | due date of checked out item in a human-readable form (null if not checked out) | |
| * requests_placed – The total number of holds and recalls placed on an item (optional) | | returnDate | string or boolean | no | | A string showing return date of an item (false if not recently returned) | |
| * 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). | | 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) | |
| * notes - an array of notes associated with holdings (optional; deprecated in VuFind 3.0 in favor of holdings_notes) | | 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. | |
| * holdings_notes - an array of notes associated with holdings record containing the current item (optional; introduced in VuFind 3.0) | | requests_placed | int | no | | The total number of holds and recalls placed on an item | |
| * item_notes - an array of notes associated with the current item (optional; introduced in VuFind 3.0) | | 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). | |
| * summary - an array of summary information strings associated with holdings (optional) | | notes | string[] | no | :!: deprecated in 3.0| an array of notes associated with holdings | |
| * supplements - an array of strings about supplements associated with holdings (optional, introduced in VuFind 2.3) | | holdings_notes | string[] | no | 3.0 | an array of notes associated with holdings record containing the current item | |
| * indexes - an array of strings about indexes associated with holdings (optional, introduced in VuFind 2.3) | | item_notes | string[] | no | 3.0 | an array of notes associated with the current item | |
| * 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. | | summary | string[] | no | | an array of summary information strings associated with holdings | |
| * 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. | | supplements | string[] | no | 2.3 | an array of strings about supplements associated with holdings | |
| * 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. | | indexes | string[] | no | 2.3 | an array of strings about indexes associated with holdings | |
| * item_id - the item (as opposed to bibliographic) identifier (optional) | | 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. | |
| * 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. | | 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. | |
| * 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. | | 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 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. | |
| * 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. | | item_id | string | no | | the item (as opposed to bibliographic) identifier (optional) | |
| * source - The search backend from which the record may be retrieved (optional - defaults to Solr, introduced in VuFind 2.4) | | 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. | |
| * 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. | | 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. | |
| * 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. | | 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. | |
| |
| ==== getHoldings -- DEPRECATED ==== | ==== getHoldings -- DEPRECATED ==== |
| 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 (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) | 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 | |
| |
| ==== getPurchaseHistory ==== | ==== getPurchaseHistory ==== |
| * 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 | yes | | is the item available (i.e. on the shelf and/or available for checkout)? | |
| * callnumber - The item's 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. |
