A better onboarding tool for Koha
In November 2016 Mika Smith and I started as Koha interns at Catalyst. We were given an exciting opportunity to help library administrators all around the world by redesigning the installation process of the Koha library management system.
Koha users have found the existing web installer confusing and difficult to use. There were three key issues that needed attention:
- Not all steps had default selected options – new users need this guidance
- Users could deselect mandatory data values, resulting in a cut down Koha instance, but no warning was displayed to users
- There was no interface for users to create a library administrator account, forcing them to log into Koha for the first time using the database admin account. This triggers a warning message.
Our job was to make this installation process fast, easy to follow, and warning message-free. The solution was to improve the web installer, and develop a new feature – an onboarding tool to set up Koha properly so when the user logs in they are not faced with multiple warning messages. We collaborated on this project together until Mika left Catalyst to go to summer school in late December, and I have continued working on it since then.
The development of the onboarding tool was challenging and rewarding. Our tool should make the process of installing Koha much less confusing for users all around the world, but learning Perl for the first time while trying to understand and write appropriate code into our onboarding script was certainly a steep learning curve.
The end result was a massive patch (including 4341 lines of code added and 2469 lines of code removed from the Koha master version) which is currently going through the QA process. Other patches which depend on it are already being developed.
I have received a lot of feedback from the Koha community about the patch as it goes through the QA process which has been useful, and has taught me a lot – for example, which Perl pragmas best suit my scripts.
Our project produced the following deliverables:
Updated web installer
The updated web installer provides the user with the choice of basic or advanced setup mode. The basic setup, which is recommended for new users, selects all data values necessary for a fully functioning Koha instance by default. The advanced setup mode, recommended for experienced Koha users, provides the user with complete control over the data installed in their Koha database – it is the current web installer.
After the user has completed web installation, they are redirected to the second part of the patch: the onboarding tool.
Onboarding tool
The onboarding tool has several functions.
- It checks whether the user has installed sample libraries, patron/borrower categories, and item types when going through the updated web installer, and if they didn’t then a simplified form is displayed for the user to create these before they can proceed. By ensuring the Koha database contains at least one library and patron/borrower category the onboarding tool sets up the prerequisites to create an account.
- The tool provides a library administrator account creation form, thereby solving issue 3 (above). The user setting up Koha can use the account they create both to login to the Koha staff interface for the first time after finishing the onboarding tool, and subsequently to login on a daily basis when using Koha for work. This library administrator account is assigned super librarian privileges by default so the user can perform all necessary day-to-day tasks using it.
Having enjoyed the rewarding process of developing the onboarding tool so much I am currently working on additional enhancements, one of which is adding two further interfaces allowing the user to learn more about the different services they can use with Koha (SIP, and LDAP) and the other allows the user to further configure their Koha instance.
Our patch helps the user set up Koha in a fast and hassle free way; it even educates new users on where to create libraries, patron/borrower categories, patrons/borrowers, item types, and circulation rules in the Koha staff interface. Importantly it stops the situation of the user logging into Koha for the first time only to be faced with multiple warnings. Instead, everything is set up for the user because they used the onboarding tool, so they can log in using their unique user account and get straight to work.
Special thanks to the Catalyst Koha team for their support and guidance.
To find out more about this project, please visit https://koha-community.org/manual/installation/html/
