Extracting patron images from Koha DB

This is part of the series of blog posts on how to extract your data from a Koha system where you unable to access the DB directly, but where you have “superlibrarian” access. In this part, we talk about extracting the patron images stored inside the patronimage table in your Koha database.

Prequisites

  • You should be comfortable using the GNU/Linux command line
  • Familiarity with SQL syntax
  • The Koha DB schema reference for your version of Koha
  • A Linux system with cURL and LibreOffice installed
  • Superlibrarian userid and password of your Koha instance

Modus operandi

  1. Use the Koha Reports module to download the list of the borrowernumbers of patrons having their image in the db
  2. Remove the header line and save it as a text file, with one borrowernumber per line
  3. Use cURL to get the CGISESSID cookie using the authentication SVC API call
  4. Execute the BASH script, passing the authenticated session id and the file holding the list of borrowernumbers as command line parameters
  5. Use the Koha Reports module to generate the IDLINK.txt batch patron image uploader file

The background

Patron images in Koha are stored in the patronimage table of the database. The table has following schema:

Column Type Size Parents Comments
borrowernumber int 10 borrowers the borrowernumber of the patron this image is attached to (borrowers.borrowernumber)
mimetype varchar 15   the format of the image (png, jpg, etc)
imagefile mediumblob 16777215   the image

A blob is a “binary large object” which means it is not a text field. The contents won’t make any sense if we used the report module to SELECT imagefile FROM patronimage. This brings cURL into the picture.

The patron image is served on the OPAC / staff client using the patronimage.pl Perl script using an URL like this: http://<your_instance>/cgi-bin/koha/members/patronimage.pl?borrowernumber=<borrowernumber>.

But before we can run cURL on this URL, we must do one more thing. We need our BASH script to login using our superlibrarian userid and password using Koha authentication web service API call.

We need to do this for two reasons: (a) login into our Koha instance with superlibrarian access and (b) get hold of the CGISESSID cookie.

Putting it all together

  1. A simple SQL report as given below with fetch us the borrowernumber of patrons with their image stored in the DB.

    SELECT borrowernumber FROM patronimage

    We will download the result as Open Document spreadsheet.

    Next we copy and save the list of patron borrowernumbers into a text file (let’s call it list-of-pix.txt), with one borrowernumber per line.

  2. Lets put together our small BASH script. We shall call it get_pix.sh.
    #!/bin/bash
    
    mkdir patronimages
    
    while read LINE
        do  curl -b CGISESSID=$1  -o ./patronimages/$LINE.png http://<your_instance>/cgi-bin/koha/members/patronimage.pl?borrowernumber=$LINE
    done < $2

    NOTE: <your_instance> need to be changed with **your** actual server URL.
    Make the script executable by running chmod a+x get_pix.sh.

  3. From the command-line run the following command:
    $ curl -i http://<your_instance>/cgi-bin/koha/svc/authentication -d 'userid=<yourid>&password=<yourpass>'

    If we had put in the correct information, we shall see something like this:

    HTTP/1.1 200 OK
    Date: Thu, 20 Dec 2018 09:53:02 GMT
    Server: Apache/2.4.18 (Ubuntu)
    Set-Cookie: CGISESSID=4a732ae75d8991a994d7ad0df584f84c; path=/; HttpOnly
    Vary: Accept-Encoding
    Transfer-Encoding: chunked
    Content-Type: text/xml; charset=ISO-8859-1
    
    <?xml version='1.0' standalone='yes'?>
    <response>
      <status>ok</status>
    </response>

    This gives us the two things we need for the next step: (a) the CGISESSID and (b) the status as OK. OK signifies that we were successfully logged in.

  4. Now we run the get_pix.sh script
    ./get_pix.sh f03a894f1885e891e30f6d40e6e9838c ./list-of-pix.txt

    And we shall see the patron images getting downloaded.

  5. Once the patron images have all been downloaded to patronimages folder created by the get_pix.sh script, its time to generate the IDLINK.txt file, which we will place in the aforementioned patronimages folder. Again, we shall turn to Koha's Reports module with this small SQL script:
    SELECT CONCAT(borrowers.cardnumber,", ", patronimage.borrowernumber, ".png") AS 'IDLINK'
      FROM patronimage 
      LEFT JOIN borrowers ON patronimage.borrowernumber=borrowers.borrowernumber

    This will generate our listing for the IDLINK.txt. If you are not sure about what IDLINK.txt does, please read up from here.

  6. Download the report as Open Document Spreadsheet, remove the header line and copy the rest into a text file and save it as IDLINK.txt in the patronimages folder.
  7. Zip up the patronimages folder as mentioned here and we have the patron images ready for a batch upload.

AskALibrarian – Koha’s new feedback form plugin

A Koha plugin that adds user feedback functionality to Koha’s OPAC.

What is the ‘AskALibrarian’ Koha plugin?

It is a Koha plugin that adds a modal user feedback form to the Koha OPAC. It is written to utility the Koha Plugin System that was originally introduced into #kohails with version 3.12. This means that while the feature is an extension to a stock Koha installation, it is essentially a koha-native solution. Thus it is well-integrated within Koha as compared to any other third party solution. In terms of direct advantages it brings in (a) ease of maintainability across Koha upgrades, (b) ability to use the submitted data directly from Koha’s SQL reports, (c) data privacy – the data is stored directly inside your Koha database, as opposed to with any other 3rd party solution (something that assumes far greater significance in the GDPR era).

Why this plugin?

The Koha OPAC provides a lot of functionality to both the library staff as well as the library patrons. Below is a short list of things you can (there are more) and things you can not do.

Things you can 👍 Things you can’t 👎
  • Login with your user account
  • Reserve a book
  • Renew a book
  • Pay a fine or fee
  • Update your contact information
  • Do a self-registration
  • Submit a purchase suggestion
  • Add star ratings
  • And much more
  • Leave a feedback for the library staff

Since a lot of L2C2 Technologies’s client partners seem to be wanting the facility of user feedback forms, we finally decided “Why not… let’s do a plugin!” And so the AskALibrarian plugin was born.

How does it work?

The plugin adds a bootstrap modal feedback form as a menu option on the navbar at the top of the Koha OPAC. On submission of the form by the user / visitor, the information is submitted via an AJAX call to a Perl script – askalibrarian.pl, on the staff client side. The script invokes the required sub-routines from the plugin to do two things : (a) send the user an acknowledgement of the submitted input to the user’s email address, it provided is reachable and (b) store the submitted data in the koha_plugin_com_l2c2technologies_askalibrarian_feedback table in the Koha database. A callback sends up an alert popup on the OPAC, informing if it has successfully captured the data.

How to get the plugin?

The plugin is published under GNU GPL v3.0 license and is available here from L2C2 Technologies‘s GitHub repository. Pull requests for bugs or improvements are welcome 🙂

Please show me step by step!

Given how our readers from the Indian sub-continent are fond of “step-by-step” instructions, we have a small video for our readers (about 11 mins) that shows how to setup and use plugin.

Enjoy! May the source be with you!

Koha Patron Image Packer helper script

One-click utility to help build bulk patron image loader zip archive for users accessing Koha ILS from their Windows PCs.

Academic libraries like the ones in colleges, typically have a need to bulk upload patron images (of students) at the start of every school year. The photos are usually made available from their admissions office, named and numbered as per either unique enrollment id or student id of each student. The college libraries typically also utilize these same numbers as their library card numbers.

Of course, when several hundred patron images have to be imported, Koha’s bulk patron image upload option comes in very handy. It is available at More > Tools > Patrons and Circulation > Upload Patron Images. We can create a ZIP archive with all these uniquely named and numbered photos along with a manifest file named either DATALINK.txt or IDLINK.txt. The structure of the manifest file is simple – <cardnumber><separator><filename>. The <separator> can be a comma or a tab character.

The only kink in this work flow is that quite often we would see people creating that manifest by hand. This, as expected, quite often led to errors, and as a result they often had to make multiple runs at uploading the photos along with wasting precious time identifying the errors in the manifest.

So when our client-partner Basanti Devi College Library wanted to upload several hundred patron images at one go, we decided to put together a small PowerShell script that could automate this function so that it could get done quickly, without any error and at the click of the mouse.

The Koha Patron Image Packer is the outcome. It is small PowerShell script that allows users working on Windows based system to build their bulk patron image batch loader zip file along with it’s IDLINK.txt manifest with just a single click. It’s minimum requirements are PowerShell v 3.0 script with .NET Framework 4.0.

Get the code

The code is available from https://gitlab.com/indradg/koha-patron-image-packer

Installation

Installation is nothing more than copying the datalinker.ps1 file over to folder which is holding your patron images named as per their cardnumbers in Koha.

However, before your Windows system may allow you to run an PowerShell script, it may be require you to set your ExecutionPolicy to RemoteSigned for your CurrentUser. To do that, go to Run and type in PowerShell and hit enter to open up the Windows PowerShell interactive console and type in the following command:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

To check if this has been set currently you can run the command and check the output by typing in

Get-ExecutionPolicy -List

Demostration

A screencast of this feature at work is available on Youtube. It is a short video under 2 minutes. Watch it at 720p at full-screen if supported on your bandwidth.

License

It is released under GNU GPL v3 or later, the same license as Koha.

Acknowledgment

A.J. Tomson, Librarian, Devagiri College, Kozhikode who wrote an early version of analogous script in Python in Koha 3.12 days.

Vimal Kumar V. whose blog post “A useful script to compress patron images to upload” had originally put the spotlight on Mr. Tomson’s work.