Drupal opac connector specification

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:

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:

1. Includes the connector classes in the .info file (so your class is automatically loaded by Drupal).
2. 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.inc

In the .module file:

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)
• modifyUser($user_name, $data)
• 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:

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)

  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:

  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:

  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:

  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:

     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.

  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

  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.

  array(
    'wanted_field1' => 'foo',
    'wanted_field2' => 'bar',
  );

patronCheckouts($patron_id)

Description: Get checkouts for a given patron ($patron_id)

Return:

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:

  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:

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

modifyUser($user_name, $data) (3.x)

Description: Modify ILS user data.

Parameters:

$user_name

User name.

$data

An associative array where keys are names of fields to modify and values are new values for those fields.

Should returns: An associative array with the following keys:

success

A boolean that indicates if modification succeeded or not.

modified_fields

An associative array where keys are names of modified fields and values are new values for those fields.

renewItem($patron_id, $itemid)

Description: Performs a hold renewal for a given patron ($patron_id) and item ($itemid).

Return:

  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:

 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.