Add-ons

A patron-import add-on is simply a Koha plugin that implements one or more hooks called by the main plugin (patron-import).

A add-on is used to handle specific cases that are not feasible by configuring the plugin like complex mappings or unusual data transformation.

Create an add-on

First, create the plugin’s directory. It should respect this structure: my-plugin-name/Koha/Plugin/Com/Biblibre/MyPluginName.pm.

A good practice is to name the plugin base directory like “koha-plugin-myplugin-patron-import”.

koha-plugin-myplugin-patron-import/Koha/Plugin/Com/Biblibre/MyPlugin.pm

Create this directory on a place where Koha can access / read.

Your plugin must contain at least this code to be installed by the Koha plugin system: Here is a starter for a plugin named “Example”:

package Koha::Plugin::Com::Biblibre::Example;

use base qw(Koha::Plugins::Base);

our $VERSION = '1.0';

our $metadata = {
    name            => 'Example Add-on for Patron Import plugin',
    author          => 'Joe Bar <joe.bar@foo.com>',
    description     => 'Example Add-on for Patron Import plugin',
    date_authored   => '2022-10-30',
    date_updated    => '2020-10-30',
    minimum_version => '21.11',
    maximum_version => undef,
    version         => $VERSION,
};

sub new {
    my ( $class, $args ) = @_;

    $args->{'metadata'} = $metadata;
    $args->{'metadata'}->{'class'} = $class;

    my $self = $class->SUPER::new($args);

    return $self;
}

1;

Hooks

A hook is called multiple times during the import process. Each hook corresponds to a specific point in the import. See “Available hooks” section below to learn when they are called and how to implement them.

To implement a hook add it where you want in the add-on package:

sub patron_import_mapping_preprocess {
    my ($self, $data, $borrower) = @_;

    # your specific code here.
}

Available hooks:

Tip

For authorized users, you can check the Example add-on.

Here is a list of available hooks and how they should be written.

  • patron_import_mapping_postprocess

This hook is called just after the field and value mappings are processed.
$borrower is the futur Koha patron.
sub patron_import_mapping_postprocess {
    my ($self, $borrower) = @_;
}

  • patron_import_patron_update

Called before the patron is updated in Koha.
$patron is the incoming patron
$extended_attributes contains the incoming patron extended attributes
$stored_patron is the current Koha patron
$stored_extended_attributes contains the current patron extended attributes
sub patron_import_patron_update {
    my ($self, $patron, $extended_attributes, $stored_patron, $stored_extended_attributes) = @_;
}

  • patron_import_patron_updated

Called after the patron is updated in Koha.
$borrowernumber is the updated borrowernumber.
sub patron_import_patron_updated {
    my ($self, $borrowernumber) = @_;
}

  • patron_import_patron_create

Called before the patron is created in Koha.
$patron is the incoming patron
$extended_attributes contains the incoming patron extended attributes
sub patron_import_patron_create {
    my ($self, $patron, $extended_attributes) = @_;
}

  • patron_import_patron_created

Called after the patron is created in Koha.
$borrowernumber is the updated borrowernumber.
sub patron_import_patron_created {
    my ($self, $borrowernumber) = @_;
}

  • patron_import_to_skip

Called to define if the patron should be ignored by the import process.
$patron id the mapped incoming patron.
sub patron_import_to_skip {
    my ($self, $patron) = @_;
}

  • patron_import_patron_exists

Called to define an additionnal condition after matchingpoint result.
$patron is the mapped incoming patron. $borrowernumber is the borrowernumber found (or not) by matchingpoint
sub patron_import_patron_exists {
    my ($self, $patron, $borrowernumber) = @_;
}

Now you created your add-on, you will have to install it.

Installation

Installing steps:

  1. Clone or upload your add-on on the server

  2. Add it in the Koha configuration file

  3. Launch the plugin installer

  4. Enable the add-on

  5. Link the add-on to a configured import

Clone or upload your add-on on the server

Place your add-ons directory somewhere Koha can access it

koha@koha:~$ cd /home/koha/lib/
koha@koha:~$ git clone https://git.biblibre.com/Add-on-patron-import/koha-plugin-example-patron-import.git

Add it in the Koha configuration file

Edit your koha-conf.xml and add a <pluginsdir> tag inside the <config> one.

<config>
  <pluginsdir>/home/koha/lib/koha-plugin-example-patron-import</pluginsdir>

At this point you might need to restart some Koha services and clear cache.

Launch the plugin installer

Go the Koha source code and run this command:

koha@koha:~$ /home/koha/src/
koha@koha:~$ perl misc/devel/install_plugins.pl

You should see this when your plugin is successfully installed:

Installed Example Add-on for Patron Import plugin version 1.0
All plugins successfully re-initialised

Enable the add-on

Before being used by Koha or other plugins the add-on must be enabled.
Go to the Koha plugins home page (cgi-bin/koha/plugins/plugins-home.pl), find your add-on, click on Actions and the Enable button.