Springshare and Koha - Library Setup

Springshare and Koha - Library Setup

How does it work?

Springshare can send email, SMS, and/or phone messages, connected by a plugin. Koha notice templates are updated with YAML, indicating that it should be transmitted to Springshare, rather than sending from Koha. 

Notice setup

What notices can Springshare send?

Currently, Springshare can send the following notice types, each listed with its Koha letter code and default message name in Springshare:
  1. HOLDDGST, Hold
  2. HOLD_REMINDER, Hold Reminder
  3. HOLD_CANCELLATION, Hold Cancel
  4. PREDUEDGST, Courtesy
  5. DUEDGST, Courtesy Reminder
  6. AUTO_RENEWALS_DGST, Autorenew
  7. ODUE, Overdue
or
  1. ODUE1,Overdue 1
  2. ODUE2, Overdue 2
  3. ODUE3, Overdue 3
System preferences

  1. If sending SMS messages, set SMSSendDriver to "Springshare".
  2. If sending Voice messages, set PhoneNotification to "Enable". 


How do I configure the notices?

To configure the notices, you'll clear out the text in the Koha notice and input the YAML blob. The YAML can be found on the github page which we've linked to previously in the article. 

Info
The YAML should be input when you're ready to start sending notices through the plugin. This cannot be done ahead of time. See "When should I input the YAML blob" below. 

How do I configure the Patron-facing notices?

The patron facing notices will be configured in Springshare's "LibConnectPro" interface, not in Koha. 

When should I input the YAML blob? 

The YAML should be input in the Koha notice when you're ready to start sending notices via the webhook plugin but not before. Springshare might ask you to test sending notices by sending notices to staff members, and this can be accomplished with some template toolkit in the notice. If you need help with this, submit a ticket. 

Plugin configuration

Install and configure the Springshare plugin on your site, adding library credentials (OAuth2 Token Endpoint URL, Client ID, Client Secret, Webhook Endpoint URL, and Customer ID).
This information should be given to you by Springshare. If they have not given it to you yet, reach out to them. 


Notice configuration

In Tools > Notices and slips, for all notices the library will be sending through Springshare:
  1. Copy/paste the YAML syntax from the Github documentation into the Email, SMS, and/or Phone tabs, as applicable. 
  2. Keep content in the Print tab for any notices that the library will want to print.

Alert
Note that Springshare requires that overdue notices use the letter codes ODUE1, ODUE2, and ODUE3.

Messaging settings and related preferences

Do staff need to capture patrons' mobile provider for Springshare SMS messages?

No, the mobile provider is not necessary for SMS messages sent through Springshare.

Do SMS numbers need hyphens?

No, SMS numbers do not need hyphens.

Do SMS numbers need the leading 1?

No, SMS numbers do not need the leading 1. Springshare will add it on their end. If your phone numbers have the leading 1, you do not need to remove them.

How does Springshare know what messages to send?

When a message to a patron is triggered by messaging preferences or overdue notice triggers, anything in a template where Koha finds "webhook: yes" will be compiled and transmitted to Springshare via the plugin. When the process_message_queue.pl cron runs, it passes those YAML bits to the plugin, the plugin pulls the related metadata for the indicated patron, checkout, item, etc. and this information is formatted into a JSON file and sent to Springshare.

How will libraries know what Springshare-controlled notices have been sent/delivered?

Patrons’ Notices tab will display the YAML data that was transmitted to Springshare via the plugin. The notice status in Koha will indicated whether or not the notice was successfully transmitted to Springshare, rather that whether or not it was delivered to the patron. Libraries should contact Springshare for the specific formatted notices sent to patrons and details of their delivery status.

Frequently Asked Questions

Can a message be resent?

Libraries can resend notices from the patron screen. The message status reverts to pending and the plugin will grab that message, and transmit it to Springshare again.

If a checked out item is returned to the library, will the patron still get a message?  

Yes. The plugin will check the issues table before compiling the JSON file to send to Springshare. If it doesn't find the checkout, it will look to the oldissues table and pull the data for the JSON blob to send to Springshare from there instead. For this reason, a checkout message can be sent to Springshare, even after an item has been returned.

Troubleshooting

If Springshare notices are not delivering as expected, there are three places to check, in order: 

  1. Check Github to be sure that latest version of the plugin is installed.
  2. Check your notice templates and confirm that the YAML blobs are entered correctly.
  3. Open a ticket with ByWater to have our Systems team confirm that the process_message_queue.pl scripts are correct.

    • Related Articles

    • Patron Point and Koha - Library Setup

      How does it work? Patron Point can send email, SMS, and/or phone messages. Similar to SIP users, an API patron/user allows third party integrations such as Patron Point to connect to Koha. The API patron will have permissions that allow it to ...

    • MessageBee and Koha - Library Setup

      Click here for Troubleshooting How does it work? MessageBee can send email, SMS, and/or phone messages, connected by a plugin. Koha notice templates are updated with YAML, indicating that it should be transmitted to MessageBee, rather than sending ...

    • CirriusImpact and Koha - Library Setup

      Click here for Troubleshooting How does it work? CirriusImpact can send email, SMS, and/or phone messages, connected by a plugin. Koha notice templates are updated with YAML, indicating that it should be transmitted to CirriusImpact, rather than ...

    • Third-Party Notice Integrations

      Koha has email and SMS messaging options built in. These templates are all configured in Tools > Notices and slips. Recently, some Partners have reported issues with cellular providers in their areas discontinuing email to SMS functionality (the way ...

    • Notices in Koha

      Notices are a powerful way to communicate with patrons about their checked-out materials, holds, renewals, etc. Koha has many options for customizing the notices and customizing how they are delivered, both through settings configuration and through ...