Advertising sustains the DA. Ads are hidden for members. Join today

On this page

Drupal opac connector specification

Last updated on
30 April 2025

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

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.

Help improve this page

Page status: Not set

You can: