Hello Kohites!
Andrew and I have just finished a second major revision of our proposed
interlibrary loans module for Koha. The code and bug can be found at
[https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=7317].
We believe the code has now reached the maturity it requires for wider
engagement, and, more importantly, it's now reached the maturity that it
should be easy to get it up and running relatively easily in your
development environments.
Unfortunately we cannot deploy the module using sandboxes because
backends are implemented as separate code projects.
And we would *love* your comments thoughts and concerns about the module
if you are interested in ILL!
The final comment on the bug contains basic documentation for the Module
as a whole, and also some installation instructions. But for reference,
I've attached the same document to this email too.
Below you will find some further high-level background and a roadmap of
what we would like to achieve.
For now, if you're interested in this module:
• have a look at the bug, and get involved in the discussion!
• try to set up the module in your dev environment. It should work
easily on dev boxes and dev installs that track master.
• let us know if you face any issues!
• start a conversation with us if you might be interested in creating a
backend for your country's / organization's ILL workflows.
Finally, if you don't have access to a development environment, but you
would be interested in becoming involved in this project, get in touch
and we might be able to provide you with access to a testing
environment!
Best regards,
Alex Sassmannshausen
PTFS Europe
1 High-level background
═══════════════════════
The ILLModule aims to provide a core framework against which different
ILL workflows can be implemented within Koha. It achieves this by
using 2 new tables as data store, and by using an extensible backend
system to create 'connectors' to ILL providers.
The data store consists of the illrequests and the
illrequestattributes tables. The former is a traditional table that
stores essential values associated with an ILL request. The later is
a key/value store, linked to a row in the former. This store can be
used to store arbitrary data provided by a backend.
The backends implement highly customizable workflows for several core
steps in the ILL management process.
At the same time, each backend can extend the core steps (called
defined as the `core_status_graph` in Koha/Illrequest.pm) with their
own additional steps (defined as the `status_graph` in a backend's
Base.pm).
Each of these steps, both core and extensions, in turn can define any
number of 'stages' required to complete each individual step.
Each step has access to a template include file, which can dispatch on
'stage'. This is mirrored by each step having a sub in a backend's
Base.pm, which once again can dispatch on 'stage'. The subs in
Base.pm have access to the full data store provided by the ILLModule;
similarly the template includes have full access to Koha template
features, including access to custom JS blocks through which, for
instance, external APIs can be called.
The main aim of this Koha module was to provide a core that is
comprehensive enough to store core data to only have to implement ILL
once in Koha, whilst being extensible enough so that virtually any ILL
workflow can be implemented against this core.
We believe we have achieved this. I'd be very interested to hear from
you if you believe you have a workflow that cannot be captured by this
(obviously, third party tools that do not provide API access will be
virtually impossible to seamlessly integrate into Koha).
2 Roadmap
═════════
The roadmap starts from the current release of code on the bugzilla
issue.
• Publication of mature beta level code (21 February 2017)
⁃ public testing
⁃ public discussion
⁃ dogfooding
• Augment core functionality (~ June 2017)
⁃ add advanced configuration options for the core module
⁃ add a standard system for configuring backends
⁃ allow for an 'unmediated workflow'
⁃ finalise 'generic requests' workflow
• Meet Koha QA standards (~ July 2017)
• Add unit tests to core ILLModule
• Ensure UI respects Koha standards
• Ensure Core code passes qa scripts
• Addition of Documentation
⁃ contributing a chapter to the Koha manual
⁃ ensure all pod information is correct and complete
⁃ ('writing your own backend' tutorial?)
• Provide consistent error handling
⁃ standard means through which a backend can 'throw' an error.
⁃ replace uses of die with this standard route
• Integration into Koha core in Koha 17.11
Table of Contents
─────────────────
1 Change Log (since last set of patches pushed to bugzilla)
.. 1.1 Core module
.. 1.2 Backends
..... 1.2.1 New backend: FreeForm
..... 1.2.2 New backend: BLDSS (British Library)
..... 1.2.3 Dummy
2 Module Features
.. 2.1 What is handled by the module?
.. 2.2 What is not yet handled
3 Installation
4 Optional
5 Missing before inclusion in community
6 Test plan
.. 6.1 Core Module (+ Dummy backend)
..... 6.1.1 Creating requests (Staff)
..... 6.1.2 Creating requests (Patrons)
..... 6.1.3 Editing requests (Staff)
..... 6.1.4 Editing requests (Patrons)
..... 6.1.5 Requesting Cancellation (Patrons)
..... 6.1.6 Confirming requests (Staff)
..... 6.1.7 Reverting requests (Staff)
..... 6.1.8 Deleting requests (Staff)
..... 6.1.9 Place request with partners (Staff)
.. 6.2 BLDSS backend
.. 6.3 FreeForm backend
1 Change Log (since last set of patches pushed to bugzilla)
═══════════════════════════════════════════════════════════
1.1 Core module
───────────────
• Many improvements to general documentation in UI and configuration.
• Many improvements to the user interface.
• OPAC interface to viewing and commenting on their requests.
• OPAC interface for creating new requests with backends of choice.
• Add 'metadata' abstraction allowing backends to translate raw data
from their source to user friendly content.
• Add 'custom_capability's, means by which backends can extend the
workflow of the ILL module in a seamless manner.
• Add support for custom JS blocks in ILL backend template includes.
• Add generic 'backend request -> email to partners' functionality.
• Remove loads of legacy code.
1.2 Backends
────────────
1.2.1 New backend: FreeForm
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
• Allows creation of ILL requests using a manual form, which can be
extended at creation time.
1.2.2 New backend: BLDSS (British Library)
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
• Allows searching stock held by the british library, and placing
requests against it.
• By default uses test account, which means it is useful for learning.
1.2.3 Dummy
╌╌╌╌╌╌╌╌╌╌╌
• Upgrade to support latest features.
2 Module Features
═════════════════
• Extensible core for handling interlibrary loan requests in Koha
• As many backends can be added as desirable
• OPAC request form as well as Intranet request form
• Intranet request management
• Ability to create items against a backend (e.g. British Library),
using its advanced search features, and to then request the item
from peer libraries.
2.1 What is handled by the module?
──────────────────────────────────
• Create new requests
• Allow staff and customer notes
• Process those requests using custom workflows for backends
• Retain associations between requests and biblioitems that may be
created locally
• Peer lending libraries contact management (using Koha's
Organizational borrower types)
• Storage of core request information (borrower links, branch links,
request status, staff and customer notes, unique identifiers)
• Storage of arbitrary data returned by backend, and display of that
data.
2.2 What is not yet handled
───────────────────────────
• Automatic processing of received ILLs (biblio + biblioitem creation)
• Integration into specialized ILL loan & reminder policies
3 Installation
══════════════
• Apply patches (they should apply cleanly and without trouble on
master)
• Run databaseupdate to generate the ILL tables.
• Copy the 'interlibrary_loans' element from
'$kohaclone_root/etc/koha-conf.xml' to your active koha_conf.xml
• Update the path in 'interlibrary_loans > backend_dir' in
koha_conf.xml to point to '$kohaclone_root/Koha/Illbackends'
• git clone backends into the backend directory:
┌────
│ cd $kohaclone_root/Koha/ && mkdir Illbackends && cd Illbackends
│ git clone https://github.com/a-sassmannshausen/{Dummy,FreeForm,BLDSS}
└────
• Enable ILLModule in syspreferences
4 Optional
══════════
• Ensure latest Koha-Conf configuration values for interlibrary_loans
are set (see $kohaclone_root/etc/koha-conf.xml)
• Create peer lending libraries (by default they are expected to be
part of the 'ILLLIBS' borrower category, which also needs to be
created).
5 Missing before inclusion in community
═══════════════════════════════════════
• Unit tests
• Documentation (code + manual)
• Unmediated ILL Request placement workflow
• Advanced configuration
• Complete Generic Requests workflow (allow setting requests to
completed in this way, allow requests to resume backend specific
workflows after generic email is sent)
• Friendlier error handling.
6 Test plan
═══════════
6.1 Core Module (+ Dummy backend)
─────────────────────────────────
• Ensure the Dummy backend is installed (see [Installation])
• Enable the ILLModule (located under Administration sysprefs)
• Create a test patron, grant them at least ILL and usual staff
permissions.
• Browse to 'Home > ILL requests' (button should be visible)
[Installation] See section 3
6.1.1 Creating requests (Staff)
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
• Click on the 'New ILL request' button.
⁃ If you have multiple backends installed, select 'Dummy'
• Complete the form
⁃ Borrowernumber must be a borrowernumber, not a cardnumber.
⁃ You will always be shown the same 2 results
• Request one of the items
• You have now 'created' the request
6.1.2 Creating requests (Patrons)
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
• Log in to the OPAC
• Click on 'Your interlibrary loan requests'
• Click on 'Create a new request'
⁃ If you have multiple backends installed, select 'Dummy'
• Complete the form
⁃ As above, you will always be shown the same 2 results
• Request one of the items
• You have now 'created' the request.
6.1.3 Editing requests (Staff)
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
• From the ill-requests list, click on 'Manage request'
• Click on 'Edit request'
• Add some staff notes (or change other values)
• Click 'Submit'.
6.1.4 Editing requests (Patrons)
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
• From the patron screen, click on 'Your interlibrary loan requests'
• click on 'View'
• Enter some notes.
• Click on 'Submit modifications'
6.1.5 Requesting Cancellation (Patrons)
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
• From the patron screen, click on 'Your interlibrary loan requests'
• Click on 'View'
• Click on 'Request Cancellation'
• The request status should have changed
• The request can now be cancelled by staff if they consider the
cancellation is still possible
6.1.6 Confirming requests (Staff)
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Once a request is created, it exists in the ILLModule. But the
request has not yet been ordered from the source. To do the latter, a
request must be confirmed by staff:
• From the ill-requests list, click on 'Manage request'
• Click on 'Confirm request'.
⁃ The following process will be different for each backend.
⁃ In the case of Dummy, a simple click on the button is sufficient.
⁃ Other backends may take you through several screens.
6.1.7 Reverting requests (Staff)
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Once a request is confirmed it may still be possible to undo this
operation. This depends on the backend used, and the policies at the
source.
• From the ill-requests list, click on 'Manage request'
• Click on 'Revert request'.
⁃ The following process will be different for each backend
⁃ In the case of Dummy, a simple click on the button is sufficient.
6.1.8 Deleting requests (Staff)
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
• From the ill-requests list, click on 'Manage request'
• Click on 'Delete request'
⁃ This button will only be visible when the request has not yet been
confirmed.
6.1.9 Place request with partners (Staff)
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Rather than use the sources workflows to source a title for a specific
interlibrary loan, it may be desirable to ask a friendly library
whether they are able to satisfy the request.
The ILLModule supports this through "Generic requests". To use this
you will need to create 'Organizational patrons' to represent the
partner libraries. They must be of the 'ILLLIBS' patron category
(this can be changed by editing the koha-conf.xml file), which must
first be created.
Ensure that these patrons have email addresses!
Once a few patrons have been set up:
• From the ill-requests list, click on 'Manage request'
• Click on 'Place request with partners'
⁃ This button will only be visible if the request has not yet been
confirmed.
• Complete the form
⁃ You may select multiple partners in the select list
⁃ You may edit the email as desired.
• Click on Send email
• If your server is correctly configured to send emails, all should
have worked fine and an email should have been sent.
6.2 BLDSS backend
─────────────────
A backend to place and manage requests with the British library.
• Repeat tests as above.
• The workflows will be different for:
⁃ 'create'
⁃ 'confirm'
• There is an additional workflow:
⁃ 'status': retrieve the current status of the request at the
British library.
6.3 FreeForm backend
────────────────────
A backend to allow arbitrary manual creation of requests using an
unrestricted form of fields & values.
This backend has no 'source'. As such, requests that are created need
to then be 'confirmed' outside of ILLModule (or using the generic
requests functionality).
• Repeat tests as above.
• The workflows will be different for:
⁃ 'create'
⁃ 'confirm'
⁃ 'revert request'
_______________________________________________
Koha-devel mailing list
Koha-devel@lists.koha-community.org
http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
website : http://www.koha-community.org/
git : http://git.koha-community.org/
bugs : http://bugs.koha-community.org/
