<<

NAME

Koha::Illrequest - Koha Illrequest Object class

(Re)Design

An ILLRequest consists of two parts; the Illrequest Koha::Object, and a series of related Illrequestattributes.

The former encapsulates the basic necessary information that any ILL requires to be usable in Koha. The latter is a set of additional properties used by one of the backends.

The former subsumes the legacy "Status" object. The latter remains encapsulated in the "Record" object.

TODO:

- Anything invoking the ->status method; annotated with: + # Old use of ->status !

API

Backend API Response Principles

All methods should return a hashref in the following format:

Interface Status Messages

Class methods

illrequestattributes

patron

load_backend

Require "Base.pm" from the relevant ILL backend.

_backend

    my $backend = $abstract->_backend($new_backend);
    my $backend = $abstract->_backend;

Getter/Setter for our API object.

_backend_capability

    my $backend_capability_result = $self->_backend_capability($name, $args);

This is a helper method to invoke optional capabilities in the backend. If the capability named by $name is not supported, return 0, else invoke it, passing $args along with the invocation, and return its return value.

NOTE: this module suffers from a confusion in termninology:

in _backend_capability, the notion of capability refers to an optional feature that is implemented in core, but might not be supported by a given backend.

in capabilities & custom_capability, capability refers to entries in the status_graph (after union between backend and core).

The easiest way to fix this would be to fix the terminology in capabilities & custom_capability and their callers.

_config

    my $config = $abstract->_config($config);
    my $config = $abstract->_config;

Getter/Setter for our config object.

metadata

_core_status_graph

    my $core_status_graph = $illrequest->_core_status_graph;

Returns ILL module's default status graph. A status graph defines the list of available actions at any stage in the ILL workflow. This is for instance used by the perl script & template to generate the correct buttons to display to the end user at any given point.

_core_status_graph

    my $status_graph = $illrequest->_core_status_graph($origin, $new_graph);

Return a new status_graph, the result of merging $origin & new_graph. This is operation is a union over the sets defied by the two graphs.

Each entry in $new_graph is added to $origin. We do not provide a syntax for 'subtraction' of entries from $origin.

Whilst it is not intended that this works, you can override entries in $origin with entries with the same key in $new_graph. This can lead to problematic behaviour when $new_graph adds an entry, which modifies a dependent entry in $origin, only for the entry in $origin to be replaced later with a new entry from $new_graph.

NOTE: this procedure does not "re-link" entries in $origin or $new_graph, i.e. each of the graphs need to be correct at the outset of the operation.

capabilities

    my $capabilities = $illrequest->capabilities;

Return a hashref mapping methods to operation names supported by the queried backend.

Example return value:

    { create => "Create Request", confirm => "Progress Request" }

NOTE: this module suffers from a confusion in termninology:

in _backend_capability, the notion of capability refers to an optional feature that is implemented in core, but might not be supported by a given backend.

in capabilities & custom_capability, capability refers to entries in the status_graph (after union between backend and core).

The easiest way to fix this would be to fix the terminology in capabilities & custom_capability and their callers.

custom_capability

Return the result of invoking $CANDIDATE on this request's backend with $PARAMS, or 0 if $CANDIDATE is an unknown method on backend.

NOTE: this module suffers from a confusion in termninology:

in _backend_capability, the notion of capability refers to an optional feature that is implemented in core, but might not be supported by a given backend.

in capabilities & custom_capability, capability refers to entries in the status_graph (after union between backend and core).

The easiest way to fix this would be to fix the terminology in capabilities & custom_capability and their callers.

available_backends

Return a list of available backends.

available_actions

Return a list of available actions.

mark_completed

Mark a request as completed (status = COMP).

backend_confirm

Confirm a request. The backend handles setting of mandatory fields in the commit stage:

backend_update_status

backend_cancel

    my $ILLResponse = $illRequest->backend_cancel;

The standard interface method allowing for request cancellation.

backend_renew

    my $renew_response = $illRequest->backend_renew;

The standard interface method allowing for request renewal queries.

backend_create

    my $create_response = $abstractILL->backend_create($params);

Return an array of Record objects created by querying our backend with a Search query.

In the context of the other ILL methods, this is a special method: we only pass it $params, as it does not yet have any other data associated with it.

expandTemplate

    my $params = $abstract->expandTemplate($params);

Return a version of $PARAMS augmented with our required template path.

getLimits

    my $limit_rules = $abstract->getLimits( {
        type  => 'brw_cat' | 'branch',
        value => $value
    } );

Return the ILL limit rules for the supplied combination of type / value.

As the config may have no rules for this particular type / value combination, or for the default, we must define fall-back values here.

getPrefix

    my $prefix = $abstract->getPrefix( {
        brw_cat => $brw_cat,
        branch  => $branch_code,
    } );

Return the ILL prefix as defined by our $params: either per borrower category, per branch or the default.

check_limits

    my $ok = $illRequests->check_limits( {
        borrower   => $borrower,
        branchcode => 'branchcode' | undef,
    } );

Given $PARAMS, a hashref containing a $borrower object and a $branchcode, see whether we are still able to place ILLs.

LimitRules are derived from koha-conf.xml: + default limit counts, and counting method + branch specific limit counts & counting method + borrower category specific limit counts & counting method + err on the side of caution: a counting fail will cause fail, even if the other counts passes.

requires_moderation

    my $status = $illRequest->requires_moderation;

Return the name of the status if moderation by staff is required; or 0 otherwise.

generic_confirm

    my $stage_summary = $illRequest->generic_confirm;

Handle the generic_confirm extended method. The first stage involves creating a template email for the end user to edit in the browser. The second stage attempts to submit the email.

id_prefix

    my $prefix = $record->id_prefix;

Return the prefix appropriate for the current Illrequest as derived from the borrower and branch associated with this request's Status, and the config file.

_censor

    my $params = $illRequest->_censor($params);

Return $params, modified to reflect our censorship requirements.

TO_JSON

    $json = $illrequest->TO_JSON

Overloaded TO_JSON method that takes care of inserting calculated values into the unblessed representation of the object.

Internal methods

_type

AUTHOR

Alex Sassmannshausen <alex.sassmannshausen@ptfs-europe.com>

<<