Revisiting Kerala eSMS service for updated versions of Koha ILS

If you are a Koha user from Kerala using the eSMS send driver written by us and found out that your SMS alerts have stopped after upgrading to 17.05 or later, then you should definitely read this.

For the impatient: Koha users from Kerala using the SMS::Send::IN::eSMS send driver, often find that after upgrading from 16.11 or earlier versions, their SMS alerts from Koha had stopped working. Usually this affects users who had used this previous blog post as the installation guide. This post addresses that and shows how to get SMS working again for eSMS service on 18.11 or later versions.

For the *really* impatient: Jump directly to the section Handling SMS::Send::IN:eSMS on supported versions of Koha

Background

About 3 years back, in early February 2017, we had published the only open-source SMS::Send driver implementation for Kerala Government’s eSMS transactional bulk SMS service for use with Koha ILS. The development was sponsored courtesy the State Librarian, Kerala State Central Library, Thiruvananthapuram, Kerala.

That time the latest stable version of Koha was 16.11. Up until then Koha’s C4/SMS.pm which acts as a wrapper against SMS::Send posed a small problem for Indian users thanks to a the requirement of senderid by Telecom Regulatory Authority of India (TRAI). Koha provided only two fields – the login and password fields. We in India needed three. So, we had to hack C4/SMS.pm as documented here.

The big change

At the end of May 2017, Koha 17.05 was released and with it came Bug id #13029. In the Release Notes, bug 13029 was defined as “Allow to pass additional parameters to SMS::Send drivers”.

This was a game-changer. We no longer needed to hack C4/SMS.pm. Handling extra parameters like SenderIDs, API keys or for that matter any arbitrary parameter(s) specific to a particular bulk transactional message provider could now be handled using a simple YAML file. The path to this YAML file is defined in koha-conf.xml and therefore making it instance-specific and multi-tenant friendly. <sms_send_config>/etc/koha/sites/<your_instance_name>/sms_send/</sms_send_config>

Handling SMS::Send::IN:eSMS on supported versions of Koha

At the time of writing, the supported versions of Koha are 19.11, 19.05 and 18.11. If your version is lower than 18.11, you should really upgrade. There are just three things to keep in mind; (a) there is no change in the SMS::Send::IN::eSMS code, it works out of the box provided you took care of “c” below; (b) no more hand editing C4/SMS.pm to handle the senderid parameter; and (c) you now need to create a YAML file eSMS.yaml at /etc/koha/sites/<your_instance_name>/sms_send/IN/eSMS.yaml with just the following text:

senderid: <put_your_senderid_here>

Well, that’s it! It just works!

P.S. The lawyer says we must add this – L2C2 Technologies or everyone associated with it, disclaims any and all responsibilities in the event of someone facing loss, damages either financial, operational or any problem whatsoever, due to or in course of following this blog post or any other on this blog. The information presented here is on AS-IS basis for personal educational purpose alone. This post is licensed under CC 4.0 BY-SA.

Installing SMS::Send::IN::eSMS send driver for Koha ILS

An easy peasy HOWTO along with a few under-the-hood details explained.

[UPDATE : If you are reading this in 2020, please find updated instructions here]

Step #1 : Installing the SMS::Send::IN::eSMS module from CPAN

Login as a sudo user and start the CPAN shell using the command sudo perl -MCPAN -e shell. Install the driver by typing in install SMS::Send::IN::eSMS. If everything works OK, you should see output on screen similar to this:

cpan[1]> install SMS::Send:IN::eSMS
Reading '/root/.cpan/Metadata'
  Database was generated on Thu, 09 Feb 2017 09:41:03 GMT
Running install for module 'SMS::Send::IN::eSMS'
Checksum for /root/.cpan/sources/authors/id/I/IN/INDRADG/SMS-Send-IN-eSMS-0.01.tar.gz ok
Scanning cache /root/.cpan/build for sizes
............................................................................DONE
Configuring I/IN/INDRADG/SMS-Send-IN-eSMS-0.01.tar.gz with Makefile.PL
Checking if your kit is complete...
Looks good
Generating a Unix-style Makefile
Writing Makefile for SMS::Send::IN::eSMS
Writing MYMETA.yml and MYMETA.json
  INDRADG/SMS-Send-IN-eSMS-0.01.tar.gz
  /usr/bin/perl Makefile.PL INSTALLDIRS=site -- OK
Running make for I/IN/INDRADG/SMS-Send-IN-eSMS-0.01.tar.gz
cp lib/SMS/Send/IN/eSMS.pm blib/lib/SMS/Send/IN/eSMS.pm
Manifying blib/man3/SMS::Send::IN::eSMS.3pm
  INDRADG/SMS-Send-IN-eSMS-0.01.tar.gz
  /usr/bin/make -- OK
Running make test
PERL_DL_NONLAZY=1 PERL_USE_UNSAFE_INC=1 /usr/bin/perl "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/checkloginpass.t .. ok
t/checkmsgdest.t .... ok
t/compile.t ......... ok
t/liveaccttest.t .... skipped: No login information available, skipping all tests.
t/pod-coverage.t .... ok
t/pod.t ............. ok
All tests successful.
Files=6, Tests=16,  1 wallclock secs ( 0.09 usr  0.00 sys +  0.99 cusr  0.07 csys =  1.15 CPU)
Result: PASS
  INDRADG/SMS-Send-IN-eSMS-0.01.tar.gz
  /usr/bin/make test -- OK
Running make install
Installing /usr/local/share/perl/5.20.2/SMS/Send/IN/eSMS.pm
Installing /usr/local/man/man3/SMS::Send::IN::eSMS.3pm
Appending installation info to /usr/local/lib/x86_64-linux-gnu/perl/5.20.2/perllocal.pod
  INDRADG/SMS-Send-IN-eSMS-0.01.tar.gz
  /usr/bin/make install  -- OK

cpan[2]>

With the SMS::Send::IN::eSMS module installed, we’ll now set up the Koha side of things.

Step #2 : Making a one-line change to Koha’s SMS.pm

Assumption : That you are using a .deb package based installation. If you are using a git or a tarball installation you probably do not need this guide. 🙂

The code in file /usr/share/koha/lib/C4/SMS.pm is what Koha uses to communicate with the SMS provider (in this case eSMS Kerala from KSITM) via the send driver. This code is capable of accepting two parameters i.e. (a) username and (b) password of the user with the SMS service provider via whom the user wants to send out the messages. However due to Telecom Regulatory Authority of India (TRAI) rules, in India we need to use three parameters, the third one being a mandatory, 6-character, nationally unique senderid allotted to every bulk transactional SMS sender in India. As of version 16.11 Koha can not handle this AS-IS.

Therefore, to make SMS work with Koha in India, we need to make a one-line change to the code. Look for the following code around line no. 80 of the file /usr/share/koha/lib/C4/SMS.pm:

# Create a sender
$sender = SMS::Send->new( $driver,
                          _login    => C4::Context->preference('SMSSendUsername'),
                          _password => C4::Context->preference('SMSSendPassword'),
                    );

Add the following line : _senderid => C4::Context->preference('SMSSendSenderID'),, so that the code looks like this:

# Create a sender
$sender = SMS::Send->new( $driver,
                          _login    => C4::Context->preference('SMSSendUsername'),
                          _password => C4::Context->preference('SMSSendPassword'),
                          _senderid => C4::Context->preference('SMSSendSenderID'),
                    );

Save and close the file. Now login into the staff client and add the four necessary system preferences – (a) SMSSendDriver, (b) SMSSendUsername, (c) SMSSendPassword and (d) SMSSendSenderID. Now, if you are on Koha 3.22 or higher version (i.e. 16.05 or 16.11), you will find the first three under Patron preferences and you only need to create the last one i.e. SMSSendSenderID to complete the setup.

eSMS_02

eSMS_03

However, if you are still using Koha 3.18.x or 3.20.x series then you will need to create three Local use preferences i.e. SMSSendUsername, SMSSendPassword and SMSSendSenderID. Either way, set these four parameters to your actual settings and you are ready to go start using the installed driver.

N.B.This behaviour will change from Koha 17.05 onward (estimated release date May 2017) when the bug number 13029 – “Allow to pass additional parameters to SMS::Send drivers” becomes generally available as part of the stable releases.

Troubleshooting #1 – Missing ‘make’

‘Make’ is required to configure and install the driver. So, if you see an error that reads as

Running make for I/IN/INDRADG/SMS-Send-IN-eSMS-0.01.tar.gz
Can't exec "/usr/bin/make": No such file or directory at /usr/local/share/perl/5                                                                                                             .20.2/CPAN/Distribution.pm line 2197.
  INDRADG/SMS-Send-IN-eSMS-0.01.tar.gz
  /usr/bin/make -- NOT OK
  No such file or directory
Failed during this command:
 INDRADG/SMS-Send-IN-eSMS-0.01.tar.gz         : make NO

Exit from cpan by using the command exit and from the command line install make by entering the command sudo apt-get install make. Once make is installed, run sudo perl -MCPAN -e shell and then proceed with driver installation using the command install SMS::Send::IN::eSMS.

Troubleshooting #2 – CPAN index is out of date

After typing in the command ‘install SMS::Send::IN::eSMS‘ if you find yourself facing the error Warning: Cannot install SMS::Send::IN::eSMS, don’t know what it is., DO NOT panic! It happened to us on one of our test servers too 🙂

It simply means your CPAN index metadata is out-of-date, and you need to refresh the index by running the command ‘reload index‘. After the updated index is fetched, re-run the command install SMS::Send::IN::eSMS. It will work this time.