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

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

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.

Good news for Koha users in Kerala : SMS Send driver for eSMS Kerala service released as Free Software (FOSS)

ANNOUNCEMENT: L2C2 Technologies has released the SMS::Send::IN::eSMS driver required by Koha ILS users using the eSMS Kerala service provided by the Kerala State IT Mission under a Free Software license. The development of the driver was made possible by the funding support of the State Librarian, State Central Library, Thiruvananthapurm (Trivandrum), Kerala, with KELTRON (Kerala State Electronics Development Corporation Ltd) acting as the facilitator. Any Koha library in the state of Kerala who are eligible to use the eSMS Kerala SMS service (provided by KSITM) can now freely implement SMS support using this driver.

With this release, it becomes the second open source regional SMS::Send driver now available to Indian Koha users that can be freely downloaded from the Comprehensive Perl Archive Network or CPAN.

Sending SMSes from Koha

For a long time now Koha has supported sending of SMS (short message service) text messages to library patrons and users about account creation, issue, return, fines, holds, overdues, purchase suggestions etc. To send out SMSes from Koha, we have to use the SMS service of a bulk transactional SMS service provider who provides that service.

What are SMS::Send drivers and why does Koha need them?

In order to communicate with the service provider’s messaging sending interface (also called messaging API), Koha uses a type of software called “SMS::Send driver”. The “catch” being that each service provider requires a different SMS Send driver. Sort of like the SIM card in our cellphones e.g. if we wish to use a Vodafone number we must have a Vodafone SIM card. However, unlike a SIM card the SMS::Send driver which is a software module written in the PERL language is not provided by the SMS service provider. Either one has to use a Free & Open Source send driver that already exists OR one has to write one by referring to (usually) the HTTP API of the SMS provider.

About eSMS Kerala

eSMS is an exclusive SMS Gateway established by the Kerala State IT Mission for use by various government departments for providing departmental services over mobile phones.

Downloading the driver

The SMS::Send::IN:eSMS driver can directly downloaded from CPAN by visiting http://search.cpan.org/~indradg/SMS-Send-IN-eSMS-0.01/lib/SMS/Send/IN/eSMS.pm or from L2C2 Technologies’s public repository on Github at https://github.com/l2c2technologies/sms-send-in-esms.

See also

1. “Koha and key lessons of using transactional SMS in India” – https://www.facebook.com/notes/l2c2-technologies/koha-and-key-lessons-of-using-transactional-sms-in-india/805775296178372