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!
Default Namespace: \VuFind\ILS\Driver
Interface: \VuFind\ILS\Driver\DriverInterface
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+)
See the General Plugin Information page for more details on VuFind® plugins.
ILS Drivers must contain some or all of the following methods (optional methods are marked as such in their descriptions). It should be assumed that any method may throw a VuFind\Exception\ILS object in case of an unexpected problem.
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 ILL 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
This method changes patron's password (PIN code). (optional) Not supported prior to VuFind® 2.4
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.
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.
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 method returns items that are on reserve for the specified course, instructor and/or department.
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 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
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 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 cancelStorageRetrievalRequests). Not supported prior to VuFind® 2.3
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 optional method (see getConfig()) queries the ILS for consortial holding information.
This method queries the ILS for a list of courses to be used as input to the findReserves method (Optional)
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 queries the ILS for a list of departments to be used as input to the findReserves method (Optional)
Get a list of funds that can be used to limit the “new item” search. Note that “fund” may be a misnomer – if funds are not an appropriate way to limit your new item results, you can return a different set of values from this function. For example, you might just make this a wrapper for getDepartments(). The important thing is that whatever you return from this function, the IDs can be used as a limiter to the getNewItems() function, and the names are appropriate for display on the new item search screen. If you do not want or support such limits, just return an empty array here and the limit control on the new item search screen will disappear.
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.
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:
[Holds] defaultRequiredDate = 'driver:0:2:0'
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.
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.
Key | Type | Required | Minimum Version | Description |
---|---|---|---|---|
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. |
status | string | yes | description of the availability status of the item | |
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. | |
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 number, such 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 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 | 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() method. See also getConfig and other storage retrieval request methods. At least 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() method. See also getConfig and other ILL request methods. At least 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() 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:
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:
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.
Not supported prior to VuFind® 2.3
This method must be implemented if “pickUpLibrary” is specified in extraFields of getConfig('ILLRequests').
Not supported prior to VuFind® 2.3
This method must be implemented if “pickUpLibraryLocation” is specified in extraFields of getConfig('ILLRequests').
This method queries the ILS for a list of instructors to be used as input to the findReserves method (Optional)
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:
Key | Type | Required | Minimum Version | Description |
---|---|---|---|---|
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) | |
checkout | string | No | A string representing the date when the item was checked out | |
fine | string | No | A string describing the reason for the fine (i.e. “Overdue”, “Long Overdue”) | |
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) |
This method queries the ILS for a patron's current holds
Input: Patron array returned by patronLogin method
Output: Returns an array of associative arrays, one for each hold associated with the specified account. Each associative array contains these keys:
Key | Type | Required | Minimum Version | Description |
---|---|---|---|---|
type | string | No | Type of hold – i.e. hold vs. recall | |
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) |
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. |
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 | |
create | locale date string | No | Creation date of the hold | |
position | string | No | Position in the hold queue | |
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 | |
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 frozenThrough | 8.0 | Whether the 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). |
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) | |
publication_year | string | No | Publication year of the item | |
volume | string | No | Volume number of the item | |
isbn | string | No | 2.3 | ISBN for use in cover image loading |
issn | string | No | 2.3 | ISSN 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 |
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) |
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 profile information
This method queries the ILS for a patron's current storage retrieval requests. (optional) Not supported prior to VuFind® 2.3
This method retrieves a patron's historic transactions (previously checked out items).
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 method queries the ILS for a patron's current checked out items
This method queries the ILS for new items
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.
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 method returns a list of locations where a user may collect a hold. (optional) Not supported prior to VuFind® 1.2
Input:
Parameter | Type | Always Provided | Minimum Version | Description |
---|---|---|---|---|
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 |
This method returns a list of users for which the provided user can place proxy requests. This method was added in VuFind® 9.0.
This method returns information on recently received issues of a serial.
Currently, most drivers do not implement this method, instead always returning an empty array. It is only necessary to implement this in more detail if you want to populate the “Most Recent Received Issues” section of the record holdings tab.
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 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 information used to group together collections of pickup locations. Not supported prior to VuFind® 2.3.
This method returns a subset of the information from getHolding
Key | Type | Required | Minimum Version | Description |
---|---|---|---|---|
id | string | yes | The bibliographic record ID (same as input) | |
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. |
status | string | yes | description of the availability status of the item | |
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 | yes | Is the item on course reserve? (“Y” for yes, “N” for no) | |
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 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 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 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.
This method calls getStatus for an array of records
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 bibliographic records (used to remove non-visible items from VuFind®'s index).
This optional method (introduced in VuFind® 9.1) returns one or more ILS-specific links associated with the provided bibliographic record ID.
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 method is where your driver should initialize all expensive resource dependencies and verify its configuration array (found in $this→config when extending VuFind\ILS\Driver\AbstractBase). If a problem is encountered, this method should throw an Exception.
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 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 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.
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.
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 an ILL 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
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 |
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 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
Set the driver's configuration array. In most circumstances, this will be automatically called by the VuFind\ILS\Connection class and passed a configuration array parsed from an .ini file whose name corresponds with the driver class. This method is implemented by VuFind\ILS\Driver\AbstractBase, so you do not need to add it if you inherit from that class.
If your ILS driver implements __call() for dynamic method calls, you must also implement this method to indicate which methods may be legally called dynamically. Note that this is only really relevant for very unusual drivers like the MultiBackend driver; in general, __call() should almost always be avoided.
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 |
See ILS Drivers, Part 1 for further discussion of ILS drivers.