Last updated May 16, 2013. Created by Claire Hernandez on September 11, 2012.
Edited by Julian Maurice, LeeHunter, veggiematts, Alex Arnaud. Log in to edit this page.
This is an overview of what an OPAC connector should implement and how it should be built.
Here is an example of an OPAC connector: Koha connector
Overall
Before starting your connector, you should review the Drupal Coding Standards and especially the Object-Oriented Code conventions.
An OPAC connector is a PHP class and must implement the OpacConnector:
<?php
class MyConnector implements OpacConnector {
...
?>Declaration of a connector
Making a PHP class is not enough. You must declare your connector to make it visible to the OPAC module.
The recommended way to do that is to create a module which does the following:
- Includes the connector classes in the .info file (so your class is automatically loaded by Drupal).
- Implements hook_opac_connectors() so that the OPAC module knows more about your connector.
Example:
In the .info file:
name = Your connector
core = 7.x
dependencies[] = opac
files[] = your_connctor.incIn the .module file:
<?php
function your_connector_opac_connectors() {
return array(
'Your_connector' => array(
'id' => 'Your_connector',
'name' => 'My own connector for Awesome ILS',
),
);
}
?>List of required methods
- has()
- identity()
- patronFields()
- patronCheckoutsFields()
- patronHoldsFields()
- patronIssuesHistoryFields()
- itemFields()
- biblioFields()
- changePassword($user_name, $new_password)
- getInfos()
- authenticateUser($login, $pass)
- lookupUser($login, $type)
- marc($id)
- getBiblios($ids, $wanted_fields)
- itemsStatus($id, $wanted_fields)
- patronInfo($patron_id, $wanted_fields)
- patronCheckouts($patron_id)
- patronHolds($patron_id)
- patronIssuesHistory($patron_id)
- renewItem($patron_id, $itemid)
- cancelHold($patron_id, $itemid)
- placeHoldForm($patron_id, $record, $itemid = NULL)
- placeHold($values)
- biblioIsHoldable($record_id, $patron_id)
- patronRegistrationForm($user) (essai)
Methods description:
has()
Description: Tells if connector implements a feature or not.
Parameters:
- string $feature
- Name of feature.
Can be one of: 'issues_history'
Returns: TRUE if connector implements this feature. FALSE otherwise.
identity()
Description: Returns the connector identity which must be known by drupal-opac
Return: An array like the following:
<?php
array( 'id' => '<id_du_connecteur>', 'name' => '<nom_du_connecteur>');
?>patronFields()
Description: Drupal-opac calls this method to know which patron fields are available to map.
Return: An array with fields information (label, description)
<?php
array(
'id_champ' => array(
'label' => 'Label du champ',
'description' => 'description du champ',
),
'id_champ2' => array(
'label' => 'Label du champ 2',
'description' => 'description du champ 2',
),
);
?>patronCheckoutsFields()
Description: OPAC calls this method to know which checkouts fields
are available for display.
Return: An associative array where each value is an associative array
with the following keys:
- label (mandatory): Translated label of the field.
- type (optional): Type of field (at the moment, only 'date' type is
supported).
Example:
<?php
array(
'date_due' => array(
'label' => t('Date due'),
'type' => 'date',
),
'title' => array(
'label' => t('Title'),
),
)
?>Note that patronCheckouts MUST return the fields described here.
patronHoldsFields()
Description: OPAC calls this method to know which holds fields
are available for display.
Return: An associative array where each value is an associative array
with the following keys:
- label (mandatory): Translated label of the field.
- type (optional): Type of field (at the moment, only the 'date' type is
supported.
Example:
<?php
array(
'reservedate' => array(
'label' => t('Reserve date'),
'type' => 'date',
),
'title' => array(
'label' => t('Title'),
),
)
?>Note that patronHolds MUST return the fields described here.
patronIssuesHistoryFields()
Description: OPAC calls this method to know which fields are available for display.
Return: An associative array where each value is an associative array
with the following keys:
- label (mandatory): Translated label of the field.
- type (optional): Type of field (at the moment, only the 'date' type is
supported.
Example:
<?php
array(
'date_due' => array(
'label' => t('Date due'),
'type' => 'date',
),
'title' => array(
'label' => t('Title'),
),
)
?>Mandatory keys are 'recordid', 'title' and 'returndate'.
itemFields()
Description: Same as patronFields() but for item fields
Return: An array with fields information (label, description)
biblioFields()
Description: Same as patronFields and itemFields but for biblio fields
Return: An array with fields information (label, description)
changePassword($user_name, $new_password)
Description: Set $user_name password to $new_password.
Return: 1 on success or 0 on fail
getInfos()
Description: Returns information about the web services used by the connector.
Return:Information about the web services used by the connector, as follows:
<?php
array (
0 =>
array (
// Webservice name, mandatory
'name' => 'RESTWebService',
// Webservice url, mandatory
'url' => 'http://example.com/rest/informations',
// HTTP Response code, mandatory
'code' => '200',
// Additional information about the web service, as key/values,
// optional.
'infos' =>
array (
'key1' => 'value1',
'key2' => 'value2',
...
)
// Raw response from the web service, optional
'raw' => 'rawresponse'
),
1 =>
array (
// Web service name...
?>authenticateUser($login, $pass)
Description: Performs authentification with ILS.
Return: Either ILS identifier of the borrower if authentification succeeds or FALSE
lookupUser($login, $type)
Description: Looks up a patron in the ILS by an identifier, and returns the ILS identifier for that patron, aka the patron identifier.
Parameters:
- id (Required): an identifier used to look up the patron in the ILS.
- type (Optional): the type of the identifier.
Return: Either the ILS identifier of the borrower if authentication succeeds or FALSE
marc($id)
Description: Sends back marc data about a given biblio record ($id).
Return: An array representing marc data. See parseMarcSubfields() function in ILSDI connector.
An ILS that does not support marc should return "unsupported"
getBiblios($ids, $wanted_fields)
Description: Harvest biblio records ($ids) from an ILS
Return: An array containing records. One key is required: title. Other keys depend on the $wanted_fields array which is a list of the fields we want.
<?php
array(
'id_notice1' => array(
'title' => 'Titre notice 1',
'wanted_field_1' => array(
0 => 'foo',
1 => 'bar',
),
'wanted_field_2' => array(
0 => 'bar',
),
),
'id_notice2' => array(
'title' => 'Titre notice 2',
'wanted_field_2' => array(
0 => 'bar',
),
),
);
?>itemsStatus($id, $wanted_fields)
Description: Retrieves information about item(s) for a given biblio record ($id)
Return: An array containing item(s) with some required keys and $wanted_fields
<?php
array(
'avail' => '<nombre exemplaires disponibles>',
'total' => '<nombre total exemplaire>',
'items' => array(
'id_item1' => array(
'canhold' => 1 //Is it reserved?
'avail' => 1 //Is it available?
'wanted_field1' => 'foo',
'wanted_field2' => 'bar',
),
'id_item2' => array(
'canhold' => 1 //Is it reserved?
'avail' => 0 //Is it available?
'wanted_field1' => 'foo',
'wanted_field2' => 'bar',
),
),
);
?>patronInfo($patron_id, $wanted_fields)
Description: Retrieves patron information for a given patron ($patron_id)
Return: An array with $wanted_fields.
<?php
array(
'wanted_field1' => 'foo',
'wanted_field2' => 'bar',
);
?>patronCheckouts($patron_id)
Description: Get checkouts for a given patron ($patron_id)
Return:
<?php
array(
0 => array(
'recordid' => <identifiant_sigb_notice>,
'title' => '<titre_document>',
'duedate' => <TIMESTAMP>, // Date de retour
'date' => <TIMESTAMP>, // Date d'emprunt
'itemid' => <identifiant_sigb_exemplaire>,
'renewable' => '<is the issue renewable? >',
'reasons_not_renewable' => <string describing reasons why the issue is not renewable>, // only present if 'renewable' is FALSE
),
1 => array(
//...
),
//...
);
?>Additionally, for each checkout it must return the fields described in patronCheckoutsFields()
patronHolds($patron_id)
Description: Get holds for a given patron ($patron_id).
Return:
<?php
array(
0 => array(
'date' => <TIMESTAMP>, // Date d'emprunt
'title' => '<titre_document>',
'recordid' => <identifiant_sigb_notice>,
'barcode' => '<code_barre_exemplaire>',
'pickuploc' => '<pickup_location>',
'canceldate' => '<cancel_date>', // Pas de timestamp pour le moment (amélioration?)
'cancelid' => <cancel_id>, // Identifiant à transmettre au SIGB pour l'annulation
'status' => 'Waiting to be pulled', // exemple
),
1 => array(
//...
),
//...
);
?>Additionally, it must return for each hold the fields described in patronHoldsFields()
patronIssuesHistory($patron_id)
Description: Get checkouts for a given patron ($patron_id)
Return:
<?php
array(
array(
'recordid' => <ils_record_identifier>,
'title' => '<document_title>',
'duedate' => <TIMESTAMP>, // Due date
'date' => <TIMESTAMP>, // Issue date
),
array(
//...
),
//...
);
?>Additionally, for each issue it must return the fields described in patronIssuesHistoryFields()
renewItem($patron_id, $itemid)
Description: Performs a hold renewal for a given patron ($patron_id) and item ($itemid).
Return:
<?php
array(
'success' => <bool>, // Yes or no
'message' => 'what you want', // Message associated with yes or no
);
?>cancelHold($patron_id, $itemid)
Description: Cancel hold for a given patron ($patron_id) and item ($itemid).
Return: TRUE or FALSE
placeHoldForm($patron_id, $record, $itemid = NULL)
Description: Provide a web form adapted to what the ILS expects for holding a document.
Return: A Drupal form. See Form API
placeHold($values)
Description: Place a hold for an item or record. $values comes from the submitted form of placeHoldForm. So values
contain form element values + :
- itemid: If holding an item,
- recordid: If holding a record,
- opacuserid: ILS identifier of the borrower.
Return:
<?php
array(
'success' => <bool>, // yes or no
'message' => 'what you want', // Message associated with success or not
) ;
?>biblioIsHoldable($record_id, $patron_id)
Description:
Check if an item can be held by a patron.
Parameters:
- $record_id: ILS identifier of record
- $patron_id: ILS identifier of patron
Returns:
TRUE if the item can be held, FALSE otherwise.
patronRegistrationForm($user) (essai)
Description: Provide a web form for processing a registration to ILS.
Return: A Drupal form adapted to what the ILS expects.