Hold It! is an application written for the Caltech Library's Circulation team to easily generate a printable "on hold" book list from the Caltech TIND server.
Authors: Michael Hucka
Repository: https://github.com/caltechlibrary/holdit
License: BSD/MIT derivative – see the LICENSE file for more information
- Introduction
- Installation instructions
- Basic operation
- Configuration
- Getting help and support
- Do you like it?
- Acknowledgments
- Copyright and license
The Caltech Library's Circulation Desk handles, among other things, requests by patrons to put books or other materials on hold. However, the catalog management software does not have a simple way to produce a printable list of items to hold. The staff who go to the stacks to find materials have to look up the information from the information management system used by Caltech (TIND), write the information on paper, and update a Google spreadsheet used to track requests.
Hold It! is aimed at automating more of this procedure to reduce frustration and possible errors. It uses Shibboleth to log in to the Caltech Library system, scrapes TIND to get the necessary information, produces a printable document (based on a user-customizable template), and updates the Google spreadsheet used to track holds.
The developers provide an installer program for Caltech Library users. Please contact the developers to get a copy of the installer program for Windows 7, Windows 10, or macOS 10.12+. Note also that installation of Hold It! on Windows requires administrator priviledges.
You can also build Hold It! from sources. Information about building the application can be found in the project Wiki.
The Important: The Tind account of the user running Hold It! must have access to Tind's Global Lists feature. This requires a Tind administrator to set the permissions on the user's Tind account. To find out if your Tind account has access to Global Lists, log in to Tind and look in the Administration menu for the Global Lists item. If it's missing, contact your Tind administrator.
Hold It! has both a GUI interface and a command-line interface. The GUI interface is simple: a user starts the program in a typical way (e.g., by double-clicking the program icon) and Hold It! creates a main window, then immediately begins its work by connecting to Caltech.tind.io and asking the user for login credentials. The image at right depicts the first dialog. After the user types in a login name and password, and clicks the OK button, the program does the following behind the scenes:
- Searches Caltech.tind.io for the most recent hold requests
- Scrapes the HTML page returned by the TIND search
- Downloads the Google spreadsheet used by the Circulation staff
- Compares the two data sources to determine if the TIND search returned new holds
- Adds any new hold requests to the Google spreadsheet
- Creates a Word document listing the latest hold requests (if any)
- Opens the Word document so that the user can print it
"New holds" are determined in the following way: Hold It! searches the circulation holds list in caltech.tind.io for items with status code 24 (which is the item status "on shelf") and status code 7 (which is the item status "lost"), compares their bar codes and request dates against all entries found in the Google spreadsheet, and writes out the records that are in caltech.tind.io but not in the spreadsheet. The assumption is that when a circulation desk staff processes a hold, they will change that item's status in caltech.tind.io, and thus the search will no longer retrieve it.
Unless an error occurs, Hold It! presents only one other dialog: to ask the user whether the Google spreadsheet should be opened in a browser window. If the user clicks the Yes button, it's opened. Either way, Hold It! exits after the user answers the dialog.
The Word document is created from a template Word file named template.docx, which Hold It! looks for in the same folder where the Hold It! program itself is found. (E.g., on Windows this might be C:\Program Files\Hold It or wherever the user installed the application.)
Users can modify the look and content of the template as they wish in order to customize the format of the printed hold sheets. Variables used in the template are indicated by surrounding special terms with {{ and }}; these then get substituted by Hold It! when it generates the printable document. The following table lists the recognized variables:
| Variable | Meaning |
|---|---|
{{item_title}} |
The title of the book or other item to be held |
{{item_details_url}} |
The URL to the "item details" page in Caltech.tind.io |
{{item_record_url}} |
The URL to the record editing/update page in Caltech.tind.io |
{{item_call_number}} |
The item's call number |
{{item_barcode}} |
A barcode assigned to every item |
{{item_location_name}} |
The campus library building where the item is located |
{{item_location_code}} |
A code name for the campus library building location |
{{item_loan_status}} |
The current status of the item, whether on loan, etc. |
{{item_loan_url}} |
The status page for the item's loan status |
{{date_requested}} |
The date the hold request was made |
{{date_due}} |
The date a held item is due back |
{{date_last_notice_sent}} |
The date of the most recent reminder notice sent to the patron |
{{overdue_notices_count}} |
How many notices have been sent |
{{holds_count}} |
How many holds exist on the item |
{{requester_name}} |
The name of the patron who requested the hold |
{{requester_type}} |
The type of patron (student, faculty, etc.) |
{{requester_url}} |
The URL of an information page about the patron |
{{caltech_status}} |
The item's status indication in the Google spreadsheet |
{{caltech_staff_initials}} |
Who handled the hold request |
{{current_date}} |
Today's date; i.e., the date when Hold It! generates the hold list |
{{current_time}} |
Now; i.e., the the time when when Hold It! generates the hold list |
For security reasons, the files checked into the repository do not include all the data necessary to run Hold It! Two things need to be done before Hold It! can be run from a command line or a working binary can be created.
- The value of
spreadsheet_idin the file holdit/holdit.ini must be set to the correct Google spreadsheet identifier. (Namely, the identifier of the spreadsheet used by the Caltech Library circulation group to track holds.) - A
credentials.jsonfile must be placed in the directory where Hold It! is installed or executed from. Thiscredentials.jsonfile needs to contain the OAuth credentials from Google to access the spreadsheet via the Google API.
More general information about building the Hold It! application can be found in the project Wiki on GitHub.
If you find an issue, please submit it in the GitHub issue tracker for this repository.
If you like this software, don't forget to give this repo a star on GitHub to show your support!
The vector artwork used as part of the logo for Hold It! was created by Yo! Baba and obtained from the Noun Project. It is licensed under the Creative Commons CC-BY 3.0 license.
Hold It! makes use of numerous open-source packages, without which it would have been effectively impossible to develop Hold It! with the resources we had. We want to acknowledge this debt. In alphabetical order, the packages are:
- appdirs – abstraction layer to determine application data/config directories on any OS
- Beautiful Soup – an HTML parsing library
- colorama – makes ANSI escape character sequences work under MS Windows terminals
- cryptography – cryptographic functions for Python
- docx – a library for creating and updating Microsoft Word (
.docx) files - docxcompose – a library for concatenating/appending Microsoft Word (
.docx) files - google-api-core, google-api-python-client, google-auth, google-auth-httplib2, google-cloud, google-cloud-vision, googleapis-common-protos, google_api_python_client – Google API libraries
- halo – busy-spinners for Python command-line programs
- httplib2 – a comprehensive HTTP client library
- ipdb – the IPython debugger
- keyring – a library to access the system keyring service from Python
- lxml – an XML parsing library for Python
- oauth2client – Google OAuth 2.0 library
- plac – a command line argument parser
- PyInstaller – a packaging program that creates standalone applications from Python programs for Windows, macOS, Linux and other platforms
- pypubsub – a publish-and-subscribe message-passing library for Python
- requests – an HTTP library for Python
- setuptools – library for
setup.py - termcolor – ANSI color formatting for output in terminal
- wxPython – a cross-platform GUI toolkit for the Python language
Copyright (C) 2018-2020, Caltech. This software is freely distributed under a BSD/MIT type license. Please see the LICENSE file for more information.
