Harnessing Koha’s ExtendedPatronAttributes (aka patron custom fields)

Custom fields that make it possible to fit KohaILS to any type of library user category.

During from my frequent interactions with Indian Koha users over the last several years, one thing stands out rather starkly. There is surprisingly little understanding or use of the capabilities offered via Extended Patron Attributes. Since Koha ILS was written originally for public libraries (in fact public library consortia), its default patron data structures too are somewhat aligned with public libraries’ patron information capture.

When put to use in academic libraries e.g. K12 schools or colleges, the default patron information schema does not address the obvious need to capture data points like – programme enrolled, registration / roll numbers / class / sections details and in case of K12 schools – parent / guardian name and contact information etc. Many Koha users from the Indian sub-continent either (a) work their way around these issues without fully addressing their needs OR (b) often resort to direct editing of the koha.borrowers table schema, adding new custom fields and modifying the template files (.tmpl or .tt files) along with the Perl scripts that drive these templates.

The second approach is particularly problematic, as it means the modifications are usually hardcoded into scripts and templates. This is problematic is because doing so prevents the user from the benefit of seamless upgrades to their Koha. It means they have to do the whole “rinse-and-repeat” cycle everytime they upgrade their Koha, if they want their changes to persist. This makes Koha upgrades a costly, laborious, time-consuming process and error prone process.

Enter ExtendedPatronAttributes

According to the Koha manual –

“Patron attributes can be used to define custom fields to associate with your patron records. In order to enable the use of custom fields you need to set the ExtendedPatronAttributes system preference.”

About 10 years back, as Koha was finally moving out of version 2.x and moving into Koha 3.x, several new and exciting features were coming on to their own in Koha. One of this was the ability to easily handle custom fields for our patron records aka patron attributes. Around May 2008, my friend Galen Charlton, then with LibLime, wrote a (rather) large chunk of the code that brought in the support for custom fields to patron records. The ExtendedPatronAttributes system preference was the outcome and custom fields were here to stay.

Flash forward to present day

Recently we have been working with the Senior section library of Don Bosco School in Calcutta. Being a school library they needed to additionally support the following fields in their patron record (a) Class (b) Section (c) Roll No. (d) Parent / Guardian information i.e. name, contact info, relationship with student. Of course, we used defined these custom fields as patron attributes that were applicable only for their student patron category. In this blogpost, I will try to share just how easy and painless this is.

Step #1 : Enable ExtendedPatronAttributes syspref

This *is* the very first step and unless you enable this syspref, no matter what you do to define your custom fields (aka patron attributes), nothing would be visible.

Step #2 : Defining the Patron Attributes

In our case, we had two sets of information to be handled i.e. the student’s (a) academic details and (b) parent / guardian information. So we defined ST_CLASS, ST_SECTION and ST_ROLLNO patron attributes for the first part and ST_PNAME, ST_PRELATN and ST_PCONT as attributes for the second part.

2017-05-16_03-44-10

To make things easier for the library personnel (and reduce human error in the process), we pre-defined the values available to ST_CLASS, ST_SECTION and ST_PRELATN as authorised values.

2017-05-15_19-34-06

We also defined the PA_CLASS authorised value with the following two values : (a) ADETAILS (for academic details) and (b) GDETAILS (for guardian information).

2017-05-16_03-50-36

Step #3 : PA_CLASS – the secret sauce!

The Koha manual barely touches on this little nugget otherwise known as the PA_CLASS authorised value category. Before we proceed, just remember that in Koha Authorised value and Authority value mean two completely different things. Here we are talking about the former. If you have ever done any programming or done anything online, you must have used a drop-down / picklist to select a value. Well in Koha, authorised values are simply another name for picklists. These are defined as a category with the options added it. To the end-user, authorised values are presented as select drop-down HTML form element.

Now coming to PA_CLASS (or Patron Attribute Class), the first thing to remember is that by default Koha does not even define the PA_CLASS authorised value category. Rather it is left to the user to define it. There is a reason why it is not defined by default, not every library is going to used ExtendedPatronAttribute and unless you use it, PA_CLASS has no use. In our case, we have defined it and allotted it two values – ADETAILS and GDETAILS for now.

By allotting our custom fields (patron attributes) to either of these two PA_CLASS values allows us to logically group our two sets of information. By default, once done it looks like this:

2017-05-16_01-49-10

Order! Order! Order!

While chaos defines us, in life it is order that we look for, especially when we are attempting to present or capture information. So while the “Additional attributes and identifiers” grouping at the end of the page is adequate it is not ordered in the most logic flow with respect to the overall patron information form. Lucky for us, Koha has supported JQuery for donkey’s years. And JQuery provides us with a very nifty method .detach(). As the documentation says:

The .detach() method is the same as .remove(), except that .detach() keeps all jQuery data associated with the removed elements. This method is useful when removed elements are to be reinserted into the DOM at a later time.

blog-epa

By detaching the PA_CLASS grouped fieldsets from the DOM and by storing these into variables one at a time, we are now ready to insert them exactly where we want these fieldsets to be placed in the overall form. And that is exactly what we did.

epa-full

Conclusion

This way we did not touch the templates or the underlying business logic of KohaILS. All our definitions are stored in the database. As a result, we can now perform IN-SITU upgrades of Koha without worrying if we will break our forms if we upgraded.