CirriusImpact and Koha - Library Setup

CirriusImpact and Koha - Library Setup

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 sending from Koha. 

Notice setup

What notices can CirriusImpact send?

Currently, CirriusImpact can send:
  1. HOLDDGST
  2. HOLDPLACED
  3. HOLD_CHANGED
  4. HOLD
  5. HOLD_REMINDER
  6. PREDUEDGST
  7. PREDUE
  8. Overdue notices

System preferences

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

Plugin configuration

Install and configure the CirriusImpact plugin on your site. The plugin requires values for Host, Username, and Password, all of which should be supplied by CirriusImpact. Under Features:
  1. Check the boxes to enable Phone, SMS, and/or Email based on which types of notices will be delivered via CirriusImpact.
  2. Check the box for "Skip calling ODUE if patron has SMS or Email" if desired. 
  3. Check the box for "Include messageText column in CSV output.
  4. Checking "Enable WhatsApp" will have no effect at this time.

Notice configuration

In Tools > Notices and slips, every notice template needs to be updated for each format to be delivered via CirriusImpact. The documentation on the plugin contains examples of the required YAML syntax for each notice. The plugin includes a script to update all templates to the CirriusImpact default values; ByWater can run this script on the library's site if desired. This YAML content includes the message that will be delivered to the patron. As an example, the following is the default HOLD message for SMS. The portion labeled "text" defines the message to be delivered.
  1.  ---
  2. CirriusImpact: yes
  3. patron: [% borrowernumber %]
  4. hold: [% hold.reserve_id %]
  5. sms:
  6.   text: "[% branch.branchcode %]: [% IF holds.size > 1 %][% holds.size %] holds ready: [% FOREACH h IN holds %][% h.biblio.title %][% UNLESS loop.last %]; [% END %][% END %][% ELSE %]Hold ready: [% biblio.title %][% END %]. Pickup by [% holds.0.expirationdate || hold.expirationdate | $KohaDates %]"
  7. ---
Keep content in the Print tab for any notices that the library will want to print.

Alert
Note that CirriusImpact requires that overdue notices use the letter codes ODUE, ODUE2, and ODUE3.

Messaging settings and related preferences

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

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

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. If your phone numbers have the leading 1, you do not need to remove them. CirriusImpact will successfully process either format.

How does CirriusImpact 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 "CirriusImpact: yes" will be compiled and transmitted to CirriusImpact 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 CSV file and sent to CirriusImpact.

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

Patrons’ Notices tab will display the YAML data that was transmitted to CirriusImpact via the plugin. The notice status in Koha will indicate whether or not the notice was successfully transmitted to CirriusImpact, rather that whether or not it was delivered to the patron. Libraries should contact CirriusImpact details of message 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 CirriusImpact again.

Troubleshooting

If CirriusImpact 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 ...

    • Springshare and Koha - Library Setup

      Click here for Troubleshooting 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 ...

    • 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 ...

    • 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 ...

    • 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 ...