Warning: This page has not been updated in over over a year and may be outdated or deprecated.
legacy:vufind_1.x_developer_manual:building_an_ils_driver
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
building_an_ils_driver [2014/06/13 13:14] – external edit 127.0.0.1 | legacy:vufind_1.x_developer_manual:building_an_ils_driver [2018/12/19 14:15] (current) – demiankatz | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== ILS Driver | + | ====== ILS Drivers |
- | // This page refers | + | // This outdated |
- | + | ||
- | This page contains details on writing a custom driver | + | |
- | + | ||
- | + | ||
- | ===== Basic Structure ===== | + | |
- | + | ||
- | * 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 [[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/ | + | |
- | * 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. | + | |
- | + | ||
- | + | ||
- | ===== Key Methods ===== | + | |
- | + | ||
- | ILS Drivers must contain some or all of the following methods (optional methods are marked as such in their descriptions). | + | |
- | + | ||
- | ==== cancelHolds ==== | + | |
- | This method cancels a list of holds for a specific patron. (optional) | + | |
- | + | ||
- | * Input: cancelDetails An associative array with two keys: patron (array returned by the driver' | + | |
- | * 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) | + | |
- | + | ||
- | ==== checkRequestIsValid ==== | + | |
- | + | ||
- | 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 ' | + | |
- | * Output: True if item may be requested, false if not. | + | |
- | + | ||
- | ==== findReserves ==== | + | |
- | This method returns items that are on reserve for the specified course, instructor and/or department. | + | |
- | + | ||
- | * Input: CourseID, InstructorID, | + | |
- | * Output: An array of associative arrays representing reserve items (or a PEAR_Error object if there is a problem). | + | |
- | * 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" | + | |
- | + | ||
- | ==== 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 // | + | |
- | + | ||
- | * 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. | + | |
- | + | ||
- | ==== getCancelHoldLink ==== | + | |
- | 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 | + | |
- | + | ||
- | + | ||
- | + | ||
- | ==== getConfig ==== | + | |
- | This method returns driver configuration settings related to a particular function. | + | |
- | + | ||
- | * Input: A string corresponding with the function to check (" | + | |
- | * Output: An associative array of configuration settings | + | |
- | * Array keys used for input of " | + | |
- | * No required keys at this time | + | |
- | * Array keys used for input of " | + | |
- | * HMACKeys - a colon-separated | + | |
- | * extraHoldFields (optional) - a colon-separated list of form fields to include in the place hold form; may include " | + | |
- | * defaultRequiredDate - A colon-separated list used to set the default "not required after" date for holds in the format days: | + | |
- | * Array keys used for input of " | + | |
- | * No required keys at this time | + | |
- | + | ||
- | ==== getCourses ==== | + | |
- | 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. | + | |
- | + | ||
- | ==== getDefaultPickUpLocation ==== | + | |
- | This method returns the default pick up location code or id for use when placing holds. (optional) | + | |
- | + | ||
- | * Input: Patron array returned by patronLogin method (optional), hold information array similar to placeHold' | + | |
- | * Output: A pick up location id or code (string) | + | |
- | + | ||
- | + | ||
- | ==== getDepartments ==== | + | |
- | 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. | + | |
- | + | ||
- | + | ||
- | + | ||
- | ==== getFunds ==== | + | |
- | Get a list of funds that can be used to limit the "new item" search. | + | |
- | + | ||
- | * Output: An associative array with key = fund ID, value = fund name. | + | |
- | + | ||
- | // | + | |
- | + | ||
- | + | ||
- | + | ||
- | ==== getHolding ==== | + | |
- | 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. | + | |
- | * 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" | + | |
- | * 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 " | + | |
- | * 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 " | + | |
- | * 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 " | + | |
- | * 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: | + | |
- | + | ||
- | ==== getHoldings -- DEPRECATED ==== | + | |
- | 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. | + | |
- | + | ||
- | + | ||
- | ==== 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. | + | |
- | + | ||
- | * 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 ' | + | |
- | * Output: Link to legacy OPAC for placing hold | + | |
- | + | ||
- | + | ||
- | ==== getInstructors ==== | + | |
- | 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. | + | |
- | + | ||
- | + | ||
- | ==== getMyFines ==== | + | |
- | This method queries the ILS for a patron' | + | |
- | * 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. | + | |
- | * checkout - A string representing the date when the item was checked out. | + | |
- | * fine - A string describing the reason for the fine (i.e. " | + | |
- | * 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. | + | |
- | + | ||
- | + | ||
- | + | ||
- | ==== getMyHolds ==== | + | |
- | This method queries the ILS for a patron' | + | |
- | + | ||
- | * 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 -- i.e. hold vs. recall (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). | + | |
- | * 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' | + | |
- | + | ||
- | ==== getMyProfile ==== | + | |
- | This method queries the ILS for a patron' | + | |
- | * 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. | + | |
- | + | ||
- | + | ||
- | + | ||
- | ==== getMyTransactions ==== | + | |
- | This method queries the ILS for a patron' | + | |
- | * 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' | + | |
- | * item_id - this is used to match up renew responses and must match the item_id in the renew response | + | |
- | + | ||
- | ==== getNewItems ==== | + | |
- | 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 " | + | |
- | * Output: An associative array with two keys: ' | + | |
- | + | ||
- | // | + | |
- | + | ||
- | ==== getOfflineMode ==== | + | |
- | This optional method (introduced in VuFind 1.4) gets the online status of the ILS -- " | + | |
- | + | ||
- | * Output: string or false, as described above | + | |
- | + | ||
- | ==== getPickUpLocations ==== | + | |
- | 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' | + | |
- | * 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) | + | |
- | + | ||
- | ==== getPurchaseHistory ==== | + | |
- | 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. | + | |
- | + | ||
- | ==== getRenewDetails ==== | + | |
- | 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. | + | |
- | + | ||
- | ==== getStatus ==== | + | |
- | 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? | + | |
- | * 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. | + | |
- | + | ||
- | ==== getStatuses ==== | + | |
- | 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' | + | |
- | + | ||
- | ==== getSuppressedAuthorityRecords ==== | + | |
- | Return a list of suppressed authority records (used to remove non-visible items from VuFind' | + | |
- | + | ||
- | * Output: An array of authority record IDs. | + | |
- | + | ||
- | ==== getSuppressedRecords ==== | + | |
- | Return a list of suppressed bibliographic records (used to remove non-visible items from VuFind' | + | |
- | + | ||
- | * Output: An array of bibliographic record IDs. | + | |
- | + | ||
- | ==== hasHoldings ==== | + | |
- | This optional method (introduced in VuFind 1.4) can be used to hide the holdings tab for records where holdings do not apply. | + | |
- | + | ||
- | * Input: Bibliographic ID | + | |
- | * Output: true if holdings exist, false if they do not. | + | |
- | + | ||
- | ==== loginIsHidden ==== | + | |
- | This optional method (introduced in VuFind 1.4) can be used to hide VuFind' | + | |
- | + | ||
- | * Output: true if login should be hidden, false otherwise. | + | |
- | + | ||
- | ==== patronLogin ==== | + | |
- | 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. | + | |
- | * id - the patron' | + | |
- | * firstname - the patron' | + | |
- | * lastname - the patron' | + | |
- | * cat_username - the username used to log in | + | |
- | * cat_password - the password used to log in | + | |
- | * email - the patron' | + | |
- | * major - the patron' | + | |
- | * college - the patron' | + | |
- | + | ||
- | ==== placeHold ==== | + | |
- | 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: holdDetails - An associative array with several keys. ' | + | |
- | * 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 ' | + | |
- | * Output: Associative array containing: | + | |
- | * success – Boolean true or false | + | |
- | * sysMessage – A system supplied failure message (optional) | + | |
- | + | ||
- | ==== renewMyItems ==== | + | |
- | 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) | + | |
- | + | ||
- | ==== renewMyItemsLink ==== | + | |
- | 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 | + | |
- | + | ||
- | ===== Further Reading ===== | + | |
- | + | ||
- | * [[http:// | + | |
- | * [[ILS Driver Troubleshooting]] | + | |
---- struct data ---- | ---- struct data ---- | ||
+ | properties.Page Owner : | ||
---- | ---- | ||
legacy/vufind_1.x_developer_manual/building_an_ils_driver.1402665252.txt.gz · Last modified: 2015/08/05 12:32 (external edit)