ILS Driver

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!

• ILS Drivers are found in the web/Drivers folder of the VuFind installation.
• The PHP file containing the driver must be named for the value used as the driver setting in the [Catalog] section of web/conf/config.ini.
• The name of the class defined in the PHP file should match the filename, and the class must implement the DriverInterface (found in web/Drivers/Interface.php).
• You may wish to define a catalog-specific .ini file in the /web/conf/ directory for your ILS – you can look at other existing drivers to see how this can be loaded in the constructor.

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 return a PEAR_Error 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

• 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)
• Output: Associative array containing:
  • 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:
    • success – Boolean true or false
    • 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)

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)
• Output: True if item may be requested, false if not.

This method returns items that are on reserve for the specified course, instructor and/or department.

• Input: CourseID, InstructorID, DepartmentID (these values come from the corresponding getCourses, getInstructors and getDepartments methods; any of these three filters may be set to a blank string to skip)
• Output: An array of associative arrays representing reserve items (or a PEAR_Error object if there is a problem). Array keys:
  • BIB_ID - The record ID of the current reserve item.
  • DISPLAY_CALL_NO - The call number of the current reserve item (not currently used).
  • AUTHOR - The author of the current reserve item (not currently used).
  • TITLE - The title of the current reserve item (not currently used).
  • PUBLISHER - The publisher of the current reserve item (not currently used).
  • PUBLISHER_DATE - The publication date of the current reserve item (not currently used).

The “not currently used” values listed above only appear to be implemented in the Voyager driver and should probably be considered deprecated.

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

• Input: holdDetails - One of the individual item arrays returned by the getMyHolds method
• 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.

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: holdDetails - One of the individual item arrays returned by getMyHolds method
• Output: A URL to a native OPAC for cancelling each hold item

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 functionality) Not supported prior to VuFind 1.2

• Input: A string corresponding with the function to check (“cancelHolds”, “Holds”, “Renewals”)
• Output: An associative array of configuration settings
  • Array keys used for input of “cancelHolds”
    • No required keys at this time
  • 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.
    • 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.
    • 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.”
  • Array keys used for input of “Renewals”
    • No required keys at this time

This method queries the ILS for a list of courses to be used as input to the findReserves method (Optional)

• Output: An associative array with key = course ID, value = course name.

This method returns the default pick up location code or id for use when placing holds. (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)
• Output: A pick up location id or code (string)

This method queries the ILS for a list of departments to be used as input to the findReserves method (Optional)

• Output: An associative array with key = department ID, value = department name.

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.

• 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.

This method queries the ILS for holding information.

• Input: RecordID
• 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 RecordID that was passed in
  • availability - boolean: is this item 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.
  • 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)
  • 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)
  • summary - an array of summary information strings associated with holdings (optional)
  • is_holdable – whether or not ANY user can place a hold or recall on the item – allows system administrators to determine hold behaviour (optional)
  • holdtype – the type of hold to be placed – of use for systems with multiple hold types such as “hold” or “recall”. A value of “block” will inform the user that they cannot place a hold on the item due to account blocks (optional)
  • 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; normally a boolean, but may be set to the special value of “block” to indicate a user permission problem (optional). 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.

This method queries the ILS for holding information on multiple records at once

• 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.

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)
• Output: Link to legacy OPAC for placing hold

This method queries the ILS for a list of instructors to be used as input to the findReserves method (Optional)

• Output: An associative array with key = instructor ID, value = instructor name.

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:
  • 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.
  • fine - A string describing the reason for the fine (i.e. “Overdue”, “Long Overdue”).
  • balance - The unpaid portion of the fine IN PENNIES.
  • createdate – A string representing the date when the fine was accrued (optional)
  • duedate - A string representing the date when the item was due.
  • id - The bibliographic ID of the record involved in the fine.

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:
  • type - A string describing the type of hold (optional).
  • id - The bibliographic record ID associated with the hold (optional).
  • location - A string describing the pickup location for the held item (optional). In VuFind 1.2, this should correspond with a locationID value from getPickUpLocations. In VuFind 1.3 and later, it may be either a locationID value or a raw ready-to-display string.
  • reqnum - A control number for the request (optional).
  • expire - The expiration date of the hold (a string).
  • create - The creation date of the hold (a string).
  • position – The position of the user in the holds queue (optional)
  • available – Whether or not the hold is available (true) or not (false) (optional)
  • item_id – The item id the request item (optional).
  • volume – The volume number of the item (optional)
  • publication_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).

This method queries the ILS for a patron's current profile information

• Input: Patron array returned by patronLogin method
• Output: An associative array with the following keys (all containing strings):
  • firstname
  • lastname
  • address1
  • address2
  • zip
  • phone
  • group – i.e. Student, Staff, Faculty, etc.

This method queries the ILS for a patron's current checked out items

• Input: Patron array returned by patronLogin method
• Output: Returns an array of associative arrays, one for each item checked out by the specified account. Each associative array contains these keys:
  • duedate - The item's due date (a string).
  • id - The bibliographic ID of the checked out item.
  • barcode - The barcode of the item (optional).
  • renew - The number of times the item has been renewed (optional).
  • request - The number of pending requests for the item (optional).
  • volume – The volume number of the item (optional)
  • publication_year – The publication year of the item (optional)
  • renewable – Whether or not an item is renewable (required for renewals)
  • 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).
  • item_id - this is used to match up renew responses and must match the item_id in the renew response

This method queries the ILS for new items

• Input: getNewItems takes the following parameters:
  • page - page number of results to retrieve (counting starts at 1)
  • limit - the size of each page of results to retrieve
  • daysOld - the maximum age of records to retrieve in days (maximum 30)
  • fundID - optional fund ID to use for limiting results (use a value returned by getFunds, or exclude for no limit); 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 getFunds. The important thing is that this parameter supports an ID returned by getFunds, whatever that may mean.
• 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.

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

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)
• Output: Array of associative arrays containing these keys:
  • locationID - A pick up location id or code (string)
  • locationDisplay – The text to display for the location (string)

This method returns information on recently received issues of a serial.

• Input: Bibliogrpahic record ID
• Output: Array of associative arrays, each with a single key:
  • issue - String describing the issue

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

• Input: checkOutDetails - One of the individual item arrays returned by the getMyTransactions method
• Output: A string to use as the input form value for renewing each item; you can pass any data that is needed by your ILS to identify the transaction to renew – the output of this method will be used as part of the input to the renewMyItems method.

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
• Output: A URL to a native OPAC for renewing each item

This method returns a subset of the information from getHolding

• 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:
  • id - The bibliographic record ID (same as input).
  • status - String describing the status of the item.
  • 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.
  • reserve - Is the item on course reserve? (“Y” for yes, “N” for no).
  • callnumber - The item's call number.
  • availability - Boolean: is the item available for checkout?

Note: Some driver implementations add additional values beyond those listed above. However, these extra values are not used and should be ignored.

This method calls getStatus for an array of records

• Input: Array of bibliographic record IDs.
• Output: Array of return values from getStatus (note – the keys of this array have no special meaning; you will need to search it if you want to retrieve a specific record's values).

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.

Return a list of suppressed bibliographic records (used to remove non-visible items from VuFind's index).

• Output: An array of bibliographic record IDs.

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
• Output: true if holdings exist, false if they do not.

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.

This method processes authentication against the ILS

• Input: Username, Password
• Output: null on failed login, PEAR_Error object on error, associative array of patron information on success. Keys:
  • id - the patron's ID in the ILS
  • firstname - the patron's first name
  • lastname - the patron's last name
  • cat_username - the username used to log in
  • cat_password - the password used to log in
  • email - the patron's email address (null if unavailable)
  • major - the patron's major (null if unavailable)
  • college - the patron's college (null if unavailable)

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:
  • holdtype - type of hold (as provided by the getHolding method)
  • pickUpLocation - user-selected pickup location
  • item_id - item ID
  • comment - user comment
  • 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'.
• Output: Associative array containing:
  • success – Boolean true or false
  • sysMessage – A system supplied failure message (optional)

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:
  • patron - array returned by patronLogin method
  • details - array of values returned by the getRenewDetails method identifying which items to renew
• Output: An associative array with two keys:
  • blocks - An array of strings specifying why a user is blocked from renewing (false if no blocks)
  • details - Not set when blocks exist; otherwise, an array of associative arrays (keyed by item ID) with each subarray containing these keys:
    • success – Boolean true or false
    • new_date – string – A new due date
    • new_time – string – A new due time
    • item_id – The item id of the renewed item
    • sysMessage – A system supplied renewal message (optional)

• Expanded ILS Functionality in VuFind – Blog post providing an overview of how the driver's hold/recall/renewal functionality works.
• ILS Driver Troubleshooting