Self-Check Integration Setup and Testing

Libraries that have self-check and self-service equipment in place, or that are setting up self-check equipment for the first time, will find that setting up equipment for Alma requires some configuration work in Alma and some modifications to your local equipment. This process will involve staff from your library, preferably staff with the Alma Adminstrator certification and roles, as well as your institution's IT staff and staff from the equipment vendor. CARLI staff are able to advise as well, and you may want to involve staff that work the circulation desk in testing. 

Before beginning, you and your team should view the Ex Libris video presenting Integration with Self-Service Systems,[1] and to review this document and other related documentation. 

Importantly, to use self-service equipment with Alma, you will need to work with your equipment vendor and IT group to implement stunnel[2] on a server or self-service station as a way to secure communications with Alma.

You can learn more about the Alma Self-Check integration[3] in the Ex Libris Knowledge Center.

To start work on these integrations, contact CARLI at support@carli.illinois.edu.

Overview of the process

1. Contact your IT group and your self-check system vendor. Identify that as part of the migration to Alma, you will need to configure and test the system in advance. Your IT group and your vendor will need to advise you on where stunnel should be installed (the workstation or a separate server). They should be able to document the steps used to configure your system for Alma, so that the work may be replicated when your institution goes live on Alma. Coordinate a date or dates to do the configuration and testing; testing may require several hours. Share with them ALL documentation presented and linked on this document.
2. Create a self-check integration profile. This involves creating a profile for each self-check system in use at the library, and identifying which services are available from that machine (e.g., check-out, check-in, renew, accept payments).
3. Associate the self-check profile with a circulation desk definition. This could be an existing circulation desk definition or a unique circulation desk that limits activities and policies applied on the self-check system.
4. Make a back-up of your existing self-check machine settings. You may need to reapply these settings after testing the connection with Alma.
5. Install and configure stunnel software on the self-check machine or on a server between the machine and the Internet. Configuration of stunnel includes applying certificate details downloaded from the Alma self-check integration that you created above, and configuring the Alma domain and ports for communications. Your IT group may also need to ensure that the ports used for stunnel communication are allowed by your institution’s firewall. Note: Your self-check machine will connect to stunnel; stunnel will communicate with Alma.
6. Configure the self-check machine with the details needed to connect Alma via stunnel. You will likely need the assistance of the vendor and your IT group to modify this configuration.
7. Test circulation transactions on the self-check machine, using combinations of users and items that test the use the fulfillment rules for the given library.

If your library is already live on Alma, and the configuration is working, congratulations. Keep the equipment communicating to stunnel, and stunnel connecting to Alma.

If you are a library that is migrating to Alma, and you still need to support self-check for your existing system, restore the self-check machine’s configuration to what you need for for your existing ILS. Effectively, you will change your self-check machine to point back to your ILS instead of stunnel.

Setup Process for Alma

In Alma, you will create a self-check integration profile in Configuration. Then you will associate that integration profile with a circulation desk, so that transactions are governed according to the fulfillment configuration for the locations served by the desk.

Setup Process for the Equipment

Frequently, equipment vendors will perform most of the equipment setup on delivery. Consult with the vendor on the functionality that you want the equipment to provide, and use this information to guide your selections in the self-check integration profile above.

Communication settings for self-check equipment frequently expect a direct connection to the IP address of the library system, as well as settings that indicate which functions are available. However, SIP2 communication is not an inherently secure protocol, so the connection to Alma must be placed in a secure wrapper. This is done using the stunnel software package, which should be installed on the equipment or on a local server in the institution. 

Equipment communicates to stunnel. Stunnel communicates securely to Alma.

If the equipment vendor has worked with sites using Alma before, they should have experience with the best location for the stunnel implementation. Your IT staff may also have a preference depending on how many self-check stations you are implementing. The Developer Network's page on configuring stunnel includes a discussion of the pros and cons for different approaches.

Setup Process for stunnel

As documented on the Developer Network, setting up stunnel involves five steps.

1. Select whether stunnel will be installed on the self-check station or on a server.
2. Obtain a security certificate from Alma, and add the certificate to stunnel.
   The security certificate may be downloaded from the self-check integration that you created above.
   • Go to the self-check integration: Configuration menu > General > External Systems > Integration Profiles. Click the self-check integration profile name.
   • Click the Actions tab.
   • Scroll down and click Download Certificate. Alma will download to your browser's download folder.
   • Click Back or click to the main Alma menu.
3. Update the configuration file of stunnel to communicate with Alma.
   • Start stunnel on the system where it is located.
   • Copy the certificate file that you downloaded above into the directory where stunnel is installed
   • Click the Configuration menu > Edit stunnel.conf 
   • Replace the contents of the default stunnel.conf file with those found on the Configuring Stunnel page.
   • In the new contents, replace [Alma domain] with your institution's domain, e.g., i-share-xxx.alma.exlibrisgroup.com
   • Note: The port number for Alma self-check is 6443. Your IT group should plan to allow firewall traffic on this port.
   • Save and close the file.
   • Click the Configuration menu > Reload stunnel.conf then confirm that the service is running, per the the Configuring Stunnel page.
   • Test that stunnel is accepting connections.
4. Update the configuration of self-check equipment to communicate with stunnel.
   • Enter the IP address and ports for the stunnel instance to your self-check equipment.
     • If installed on the same workstation, address should be 127.0.0.1:5001
     • If installed on a server, use the address and port(s) configured by your IT group.
5. Begin testing.

Testing the Configuration

When you test the self-check configuration, you will see whether the self-check equipment properly handles transactions in the same way as Alma handles them at the circulation desk. This includes checking whether patrons are eligible for services, checking the status of items, and allowing or disallowing loans of items according to fulfillment policies and terms of use. A good testing strategy includes having a sample mixture of data.

• Two or more patrons (real or created as samples) with different patron groups. 
  • Consider including a sample patron with the "I-Share" user group to test whether the equipment and profile handles I-Share borrowing correctly.
  • Consider including patrons with different account conditions, for instance fines and fees over a block level, or an expiration date in the past.
  • Depending on the functionality of the equipment, consider including patrons with different amounts of activity--loans, requests, etc.
• A variety of items from the collections served by this service point.
  • Items should cover the different fulfillment rules and scenarios that get checked at circ transactions.
    • Items that may be loaned to any patron
    • Items that may be loaned to some patron groups but don't circulate to other groups
    • Items that don't circulate to any patrons
  • If your institution has multiple Alma libraries, consider including sample items from libraries not normally covered by this service point. The equipment should behave consistently with your configuration settings; e.g., Circ Desk A is allowed to perform loans for Library B; or Special Collections are only served by Circ Desk C but not Circ Desk A or Circ Desk B.
• Prepare for your tests in advance by using the Alma's Fulfillment Configuration Utility to predict the outcome for each test. This should help spot any cases that aren't as useful, for instance, items with incorrect location or item policy settings, or fulfillment rules that aren't working as expected.
• Plan to test several combinations of patron and item
  • You will need the most examples when there are differences in how items circulate to different user groups.
  • You will need only a few examples when items circulate to all groups or when items are non-circulating for all groups.

Keep track of the test results in an Excel table or a check list. and store that in a column of the sheet. Different results from those expected could indicate an incorrect configuration in the Alma self-check profile or in the equipment configuration. 

Additional Process Comments

• In step 4 of the instructions to create an integration profile,[3, midpage] you are prompted for the SC Identifier. This is generally what the self-check machine’s identification is, and should match the configuration of the self-check machine itself.
• In step 3 of the instructions to add a profile to a circulation desk,[3, bottom] there is a field for Terminal Password. You should not need to change this from whatever Alma supplies. Typically the security certificate that you download will identify the machine to Alma. Remember, the self-check machine will communicate to stunnel; stunnel will communicate to Alma.
• You may use a single integration for multiple self-check machines if the circulation points offer the same set of services.
• If you have multiple self-check machines and want to track use separately, using separate integration profiles may be desirable.
• If you use only one self-check integration profile, you may choose to assign that profile to your DEFAULT_CIRC_DESK or create a new circulation desk for that self-check profile. For instance, this would allow you to distinguish between transactions made at the desk and those made by the equipment.
• If you use multiple self-check profiles, you should plan to create separate circulation desk definitions for those self-check profiles.

Resources

[1] YouTube. Ex Libris Channel. https://www.youtube.com/watch?v=Z-q-mCc33Bo&hd=1

[2] Ex Libris Developer Network. Setting Up Stunnel. https://developers.exlibrisgroup.com/alma/integrations/selfcheck/stunnel/

[3] Ex Libris Knowledge Center. Self-Check Machines. https://knowledge.exlibrisgroup.com/Alma/Product_Documentation/010Alma_Online_Help_(English)/090Integrations_with_External_Systems/040Fulfillment/060Self-Check_Machines

Updated 30 August 2023