<<

NAME

Koha::ILL::Request - Koha ILL request Object class

(Re)Design

An ILL request consists of two parts; the Koha::ILL::Request Koha::Object, and a series of related Koha::ILL::Request::Attributes.

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

init_processors

    $request->init_processors()

Initialises an empty processors arrayref

push_processor

    $request->push_processors(sub { ...something... });

Pushes a passed processor function into our processors arrayref

ill_batch

    my $ill_batch = $request->ill_batch;

Returns the Koha::ILL::Batch associated with the request

statusalias

    my $statusalias = $request->statusalias;

Returns a request's status alias, as a Koha::AuthorisedValue instance or implicit undef. This is distinct from status_alias, which only returns the value in the status_alias column, this method returns the entire AuthorisedValue object

illrequestattributes

illcomments

comments

    my $ill_comments = $req->comments;

Returns a Koha::ILL::Comments resultset for the linked comments.

logs

patron

    my $patron = $request->patron;

For a given request, return the linked Koha::Patron object associated with it, or undef if none exists

library

    my $library = $request->library;

Returns the linked Koha::Library object.

extended_attributes

    my $extended_attributes = $request->extended_attributes;

Returns the linked Koha::ILL::Request::Attributes resultset object.

status_alias

    $request->status_alias(143);

Overloaded getter/setter for status_alias, that only returns authorised values from the correct category and records the fact that the status has changed

status

    $request->status('CANREQ');

Overloaded getter/setter for request status, also nullifies status_alias and records the fact that the status has changed and sends a notice if appropriate

get_backend_plugin

    my $backend_plugin = $self->get_backend_plugin($backend_name);

Returns the installed Koha::Plugin corresponding to the given backend_id or undef if no plugin is found

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.

_status_graph_union

    my $status_graph = $illrequest->_status_graph_union($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_illview

View and manage an ILL request

backend_migrate

Migrate a request from one backend to another.

backend_confirm

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

backend_update_status

backend_cancel

    my $ILLResponse = $request->backend_cancel;

The standard interface method allowing for request cancellation.

backend_renew

    my $renew_response = $request->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.

backend_get_update

    my $update = backend_get_update($request);

    Given a request, returns an update in a prescribed
    format that can then be passed to update parsers

expand_template

    my $params = $abstract->expand_template($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( {
        branch  => $branch_code
    } );

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

get_type

    my $type = $abstract->get_type();

Return a string representing the material type of this request or undef

get_type_disclaimer_value

    my $type = $abstract->get_type_disclaimer_value();

Return the value submitted in the type disclaimer workflow stage

get_type_disclaimer_date

    my $type = $abstract->type_disclaimer_date();

Return the time the disclaimer was submitted in the type disclaimer workflow stage

check_limits

    my $ok = $requests->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 = $request->requires_moderation;

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

biblio

    my $biblio = $request->biblio;

For a given request, return the biblio associated with it, or undef if none exists

check_out

    my $stage_summary = $request->check_out;

Handle the check_out method. The first stage involves gathering the required data from the user via a form, the second stage creates an item and tries to issue it to the patron. If successful, it notifies the patron, then it returns a summary of how things went

generic_confirm

    my $stage_summary = $request->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.

send_patron_notice

    my $result = $request->send_patron_notice($notice_code);

Send a specified notice regarding this request to a patron

send_staff_notice

    my $result = $request->send_staff_notice($notice_code);

Send a specified notice regarding this request to staff

get_notice

    my $notice = $request->get_notice($params);

Return a compiled notice hashref for the passed notice code and transport type

attach_processors

Receive a Koha::ILL::Request::SupplierUpdate and attach any processors we have for it

append_to_note

    append_to_note("Some text");

Append some text to the staff note

id_prefix

    my $prefix = $record->id_prefix;

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

_censor

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

Return $params, modified to reflect our censorship requirements.

store

    $request->store;

Overloaded store method that, in addition to performing the 'store', possibly records the fact that something happened

requested_partners

    my $partners_string = $request->requested_partners;

Return the string representing the email addresses of the partners to whom a request has been sent

TO_JSON

    $json = $request->TO_JSON

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

TODO: This method does nothing and is not called anywhere. However, bug 74325 touches it, so keeping this for now until both this and bug 74325 are merged, at which point we can sort it out and remove it completely

Internal methods

to_api_mapping

strings_map

    my $strings = $self->string_map({ [ public => 0|1 ] });

Returns a map of column name to string representations. Extra information is returned depending on the column characteristics as shown below.

Accepts a param hashref where the public key denotes whether we want the public or staff client strings.

Example:

    {
        status => {
            backend => 'backendName',
            str     => 'Status description',
            type    => 'ill_status',
        },
        status_alias => {
            category => 'ILL_STATUS_ALIAS,
            str      => $value, # the AV description, depending on $params->{public}
            type     => 'av',
        }
    }

can_patron_place_ill_in_opac

    my $can_patron_place_ill_in_opac = Koha::Illrequest->can_patron_place_ill_in_opac($patron);

Returns whether the given patron can place an ILL request in OPAC

patron

Patron object

get_op_param_deprecation

    my $op = $req->check_url_param_deprecation($params);

Issues a deprecation message for the given parameters, if needed. Returns the appropriate operation based on the interface type.

interface

The interface this is running on: 'opac' or 'intranet'

params

CGI parameters

get_staff_table_actions

    my $ill_table_actions = $self->get_staff_table_actions;

Returns the table actions available in the Staff ILL list table A total join of core static actions with custom actions provided by installed plugins that implement the ill_table_actions hook

_type

AUTHOR

Alex Sassmannshausen <alex.sassmannshausen@ptfs-europe.com> Andrew Isherwood <andrew.isherwood@ptfs-europe.com>

<<