Skip to main content
ExLibris
  • Subscribe by RSS
  • Ex Libris Knowledge Center

    Sending SMS Messages

    Primo allows users to send Short Message Service (SMS) messages from the Primo Front End. These messages can be sent from the Keeping this item section of the Full Results page and the e-Shelf. This option displays only for users that are authorized to use the SMS feature.
    Using the standard Ex Libris SMS Proxy, Primo includes out-of-the-box support for the following SMS providers:
    • Clickatell (www.clickatell.com)
    • OpenMarket (www.openmarket.com), formerly known as Simplewire
    OpenMarket no longer offers a credit-based messaging platform, but their current service model supports mass messaging and provides two-way messaging for clients. This provider may be of interest if you plan to send over 10,000 SMS messages monthly.
    In addition to the out-of-the-box providers, customers can add their own providers by using the SMS Proxy Adapter. For more information, see the following documents:
    Since the SMS gateway limits the length of the message sent, Primo sends only selected fields from the record. Primo selects these fields on the assumption that one of the main uses of the SMS will be to locate the item in the library. Therefore, Primo sends the following fields from the display section of the requested PNX record:
    • title: at least 20 characters of the title are included. If there is no space for the complete title, then the title will end with an ellipsis (…).
    • ispartof (citation for articles): the entire field is included even if this means sending more than one SMS message.
    • availlibrary (availability): there can be several lines. Preference is given to the lines that match the institution of the user and that are "Available" ($$Savailable); second priority should be given to Check-Holdings ($$Scheck_holdings). The following subfields from availlibrary will be sent:
      • $$L library name
      • $$1 sublocation
      • $$2 call-number
    The cell phone number for the SMS field has been added to the User Preferences page of the Front End. Note that the cell phone number needs to be sent to the SMS gateway in international format. The prefix for the country is added automatically by the system via the Country Code for SMS parameter unless the user prefixes the number with a plus (+). Note that the country prefix will not display in the Front End.

    Configuring the SMS Proxy

    Primo uses the standard Ex Libris SMS Proxy, which currently interfaces with the Clickatell SMS Gateway at http://www.clickatell.com and the OpenMarket SMS gateway at http://www.openmarket.com/. To use this gateway, each site must open an account with Clickatell or OpenMarket and receive a user ID, password, and other account details. If necessary, sites can open an account for each Primo institution.

    Configuring SmsProxyConf.xml for Clickatell

    To configure the SMS Proxy to interface with the Clickatell SMS gateway, the SmsProxyConf.xml file (see the following figure) defines the SMS provider and the institutions that provide the SMS service. This file is located in the following directory (fe_conf), where <r> is your initial release of Primo and <x> is the Primo instance:
    /exlibris/primo/p<r>_<x>/ng/primo/home/system/search/conf
    <?xml version="1.0" encoding="UTF-8" ?>
    <SmsProxyRoot xmlns="http://com/exlibris/core/sms/proxy/conf">
    <Providers>
    <Provider name="clickatell" code="clickatell">
     <component>com.exlibris.core.sms.proxy.ClickatellProvider</component>
      </Provider>
      </Providers>
    <Institutions>
    <Institution name="Primo" code="Primo">
    <ProviderCode>clickatell</ProviderCode>
    <ProviderUser>smithj</ProviderUser>
    <ProviderPassword>Xabcd123:1234567</ProviderPassword>
    <ProviderMo>1</ProviderMo>
    <ProviderFrom></ProviderFrom>
      </Institution>
      </Institutions>
    <Senders>
    <Sender>111.111.111.111</Sender>
      </Senders>
      </SmsProxyRoot>
    Sample SmsProxyConf.xml File (Clickatell)
    The following elements should be defined per institution. Every institution should have a separate Institution section.
    • Institution name and Code – Enter the name and code of the institution assigned by Clickatell. Primo will send the user's institution to the SMS proxy when the user sends an SMS.
    • ProviderCode – Enter clickatell.
    • ProviderUser – Enter the username assigned to you by Clickatell.
    • ProviderPassword – Enter your Clickatell password, followed by a colon (:) and your Clickatell API_ID.
    • ProviderMo – Enter 1 (true) to enable two-way messaging for mobile originations.
    • ProviderFrom – Enter the mobile number assigned to the Clickatell account. This parameter is required to allow messages to be sent from your USA long code (which is required to send messages to the USA).
    • Senders – Enter a list of all IP addresses that are allowed to send SMS messages from the FE servers.
    You can define additional providers in the SmsProxyConf.xml file by adding a <provider> element for each provider, but you can assign only one provider to an institution code.
    After updating this file, it is necessary to restart the Front End server.

    Configuring SmsProxyConf.xml for OpenMarket

    To configure the SMS Proxy to interface with the Open Market SMS gateway, the SmsProxyConf.xml file (see the following figure) defines the SMS provider and the institutions that provide the SMS service. This file is located in the following directory (fe_conf), where <r> is your initial release of Primo and <x> is the Primo instance:
    /exlibris/primo/p<r>_<x>/ng/primo/home/system/search/conf
    <?xml version="1.0" encoding="UTF-8"?>
    <SmsProxyRoot xmlns="http://com/exlibris/core/sms/proxy/conf">
    <Providers>
    <Provider name="SimpleWire" code="simplewire">
     <component>com.exlibris.core.sms.proxy.SimpleWireProvider</component>
      </Provider>
      </Providers>
    <Institutions>
    <Institution name="PRIMO" code="PRIMO">
    <ProviderCode>simplewire</ProviderCode>
    <ProviderUser>415-562-401-59715</ProviderUser>
    <ProviderPassword>9DB13831</ProviderPassword>
      </Institution>
      </Institutions>
    <Senders>
    <Sender>127.0.0.1</Sender>
    <Sender>10.1.234.254</Sender>
      </Senders>
      </SmsProxyRoot> </Senders>
    </SmsProxyRoot>
    Sample SmsProxyConf.xml File (OpenMarket)
    The following elements should be defined per institution. Every institution should have a separate Institution section.
    • Institution name and Code: Enter the name and code of the institution assigned by Open Market. Primo will send the user's institution to the SMS Proxy when the user sends an SMS.
    • ProviderCode: Enter simplewire.
    • ProviderUser/ProviderPassword: Enter the user ID and password provided by Open Market.
    • Senders: Enter a list of all IP addresses that are allowed to send SMS messages from the FE servers.
    You can define additional providers in the SmsProxyConf.xml file by adding a <provider> element for each provider, but you can assign only one provider to an institution code.
    After updating this file, it is necessary to restart the Front End server.

    Specifying the JAR File Location

    If you decide to create your own SMS plug-in, you will need to perform the following on the Primo server:
    • Place the JAR file for your SMS plug-in on the Primo server.
    • Include the ExternalJarLocation element in the SMS file to let the system know where you have placed the JAR file for your SMS plug-in. For example:

    <?xml version="1.0" encoding="UTF-8"?>

    <SmsProxyRoot xmlns="http://com/exlibris/core/sms/proxy/conf">

        <Providers>
            <Provider name="SimpleWire" code="simplewire">
                 <component>com.exlibris.core.sms.proxy.SimpleWireProvider</component>
             </Provider>
        </Providers>
        
        <Institutions>
            <Institution name="PRIMO" code="PRIMO">
                <ProviderCode>simplewire</ProviderCode>
                <ProviderUser>415-984-632-59825</ProviderUser>
                <ProviderPassword>9AD19931</ProviderPassword>
            </Institution>    
        </Institutions>
        
        <Senders>
             <Sender>127.0.0.1</Sender>
             <Sender>10.1.234.254</Sender>
        </Senders>
        
        <ExternalJarLocation>/exlibris/primo/OneSMSProvider/target/lib</ExternalJarLocation>

    </SmsProxyRoot>

    ExternalJarLocation Element Example

    Configuring the Back Office

    The Back Office allows you to configure the SMS settings for the Front End views and to add institutions to the SmsProxyConf.xml file on the server.
    To activate the SMS feature, update the configuration settings in the Back Office:
    1. The Keeping this item tile has been added to the Full Results page of the Views wizard. In this tile, it is possible to assign the user groups that should be allowed to use the SMS option. User groups can be defined using the following parameters:
      • Function: the function to configure. Currently, only SMS is available.
      • Description: the description of the function.
      • Institution: all or specific institution.
      • On-Off campus: the user IP range (should be within or without the institution IP).
      • User Group: To enable SMS for signed-in users only, set this field to NOT Guest.
    2. On the E-mail and SMS Configuration page of the Advanced Configuration Wizard, enter the following parameters:
      • Country Code for SMS: the country code used for SMS messages. The default is +1.
      • Maximum SMS Per Message: The maximum number of SMS messages that are sent per message. The default is 2.