Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
development:plugins:ils_drivers [2023/09/19 16:06] – [getHolding] demiankatz | development:plugins:ils_drivers [2024/06/25 13:31] – [getHolding] demiankatz |
---|
====== 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! |
^ Key ^ Type ^ Required ^ Minimum Version ^ Description ^ | ^ Key ^ Type ^ Required ^ Minimum Version ^ Description ^ |
| id | string | yes | | the RecordID that was passed in | | | id | string | yes | | the RecordID that was passed in | |
| 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. | | | availability | boolean/int/AvailabilityStatusInterface | yes | * / 9.1 / 10.0 | is the item available (i.e. on the shelf and/or available for checkout)? See below for further information. | |
| status | string | yes | | description of the availability status of the item | | | status | string | depends on availability | | description of the availability status of the item. Is handled by ''availability'' if using AvailabilityStatusInterface. See below for further information. | |
| 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. | | | 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. | |
| location_code | string | no | | an internal code representing the location. | | | location_code | string | no | | an internal code representing the location. | |
| 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). | | | 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 | | | notes | string[] | no | :!: deprecated in 3.0| an array of notes associated with holdings | |
| holding_id | string | no | | the ID of the holdings record containing the current item | | | 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 | | | 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 | | | item_notes | string[] | no | 3.0 | an array of notes associated with the current item | |
| 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. | | | 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) | | | 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. | | | use_unknown_message | bool | no | | when set to true, will cause display of a message indicating that the status of the item is unknown. Is handled by ''availability'' if using AvailabilityStatusInterface. See below for further information.| |
| 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. | | | 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; title keys may be null if title information is unavailable | |
The ''availability'' field may contain a boolean value: | The ''availability'' field may contain a boolean value: |
* true - Item is available, and 'Available' is displayed as status | * true - Item is available, and 'Available' is displayed as status |
* false - Item is unavailable, and the ''status'' field is used for display | * 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: | Starting with VuFind 9.1, also the following constants from ''\VuFind\ILS\Logic\ItemStatus'' (VuFind 9.1) or ''\VuFind\ILS\Logic\AvailabilityStatusInterface'' (VuFind 10.0 and higher) class can be used, and the ''status'' field is always used for display: |
* STATUS_UNAVAILABLE - Item is unavailable | * STATUS_UNAVAILABLE - Item is unavailable |
* STATUS_AVAILABLE - Item is available | * STATUS_AVAILABLE - Item is available |
* STATUS_UNCERTAIN - Item availability is uncertain (the item could be available e.g. only to a specific patron group) | * STATUS_UNCERTAIN - Item availability is uncertain (the item could be available e.g. only to a specific patron group) |
| * STATUS_UNKNOWN - No information about the availability is known (VuFind 10.0) |
==== getHoldings -- DEPRECATED ==== | |
This method queries the ILS for holding information on multiple records at once | In VuFind 10.0 the ''AvailabilityStatusInterface'' was introduced that combines the fields ''availability'', ''status'' and ''use_unknown_message''. The latter two are neither required nor used if this is used for ''availability''. You can use the standard implementation ''\VuFind\ILS\Logic\AvailabilityStatus'' or create your own. The constructor of the standard implementation accepts the availability as boolean or int and the status as string. Using the constant STATUS_UNKNOWN as availability is equivalent to setting ''use_unknown_message'' to true. Note that if you don't return an instance of ''AvailabilityStatusInterface'' in your ils driver the fields ''availability'', ''status'' and ''use_unknown_message'' will be used to create an instance of the standard implementation that will be used throughout the rest of the code anyway. |
* Input: Array of RecordIDs | |
* Output: Returns an array of associative arrays, each 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 a specific record, you should loop through and check "id" values. | |
| |
==== getHoldLink ==== | ==== getHoldLink ==== |
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. |
==== 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 ==== |
* 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 (in display format, added in VuFind® 4.1) | * expiration_date -- account expiration date (in display format, added in VuFind® 4.1; omit or set to null to exclude) |
* birthdate (Y-m-d or an empty string, added in VuFind® 9.0) | * birthdate (Y-m-d or an empty string, added in VuFind® 9.0) |
| |