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 extend the DriverInterface base class (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 the following methods. It should be assumed that any method may return a PEAR_Error object in case of an unexpected problem.

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 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 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 status of the item
  • location - string describing the physical location of the item
  • 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)
  • 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)
  • barcode - the barcode number for this item

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

Note: The values listed above as optional are not provided by every driver implementation and are not used by the standard VuFind code base as of this writing. Any new code which references them should assume they may not be present.

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

Note: The values listed above as optional are not provided by every driver implementation and are not used by the standard VuFind code base as of this writing. Any new code which references them should assume they may not be present.

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 method returns a subset of the information from getHolding

• Input: Bibliographic record ID
• Output: Associative array with the following keys:
  • id - The bibliographic record ID (same as input).
  • status - String describing the status of the item.
  • location - The location of the item (string).
  • 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 records (used to remove non-visible items from VuFind's index).

• Output: An array of bibliographic record IDs.

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.

• Input: RecordID, PatronID, Comment
• Output: Boolean