Docs: Hold Groups
authorFelicia Beaudry <>
Fri, 9 Apr 2021 14:24:37 +0000 (10:24 -0400)
committerGalen Charlton <>
Mon, 12 Apr 2021 15:22:55 +0000 (11:22 -0400)
Signed-off-by: Felicia Beaudry <>
Signed-off-by: Andrea Buntz Neiman <>
Signed-off-by: Galen Charlton <>
12 files changed:
docs/modules/admin/pages/hold_groups_admin.adoc [new file with mode: 0644]
docs/modules/circulation/assets/images/media/add_patrons.png [new file with mode: 0644]
docs/modules/circulation/assets/images/media/catalog_place_hold.png [new file with mode: 0644]
docs/modules/circulation/assets/images/media/delete_hold_group.png [new file with mode: 0644]
docs/modules/circulation/assets/images/media/new_hold_group.png [new file with mode: 0644]
docs/modules/circulation/assets/images/media/new_hold_group_event.png [new file with mode: 0644]
docs/modules/opac/assets/images/media/opac_hold_groups.png [new file with mode: 0644]
docs/modules/opac/assets/images/media/opac_remove_hg.png [new file with mode: 0644]

diff --git a/docs/modules/admin/pages/hold_groups_admin.adoc b/docs/modules/admin/pages/hold_groups_admin.adoc
new file mode 100644 (file)
index 0000000..fd05e03
--- /dev/null
@@ -0,0 +1,33 @@
+= Hold Groups Administration
+[indexterm:Hold Groups]
+There are several administrative elements described below which relate to the xref:circulation:basic_holds.adoc#hold_groups[Hold Groups] feature
+A new Library Setting allows for hold placement times to be randomized
+among list members for fair distribution. It can be found at *Administration -> Local
+Administration -> Library Settings Editor -> Randomize group hold
+New Action Triggers allow for Evergreen to generate email or SMS
+notifications to patrons when a new hold is placed through Hold Groups.
+New tables in the database store the batch place hold events occurring
+on a particular Hold Group (action.batch_hold_event) and the
+relationship between the batch hold request and successfully placed
+holds (action.batch_hold_event_map).
+A new staff permission for MANAGE_BATCH_HOLDS allows applicable users to
+place and cancel batch holds through Hold Groups.
+A new user bucket type was created for this feature, adding a row in the
+container.user_bucket_type with a unique code value to segregate new
+Hold Group user buckets.
+The Hold Group feature relies on the open-ils.circ.holds.create.batch
+API methods to facilitate the batch creation of holds. A new API method
+processes the Hold Group user bucket each time a staff user requests it,
+optionally randomize the hold request creation times, and create a hold
+request for a specified title for a Hold Group member that does not
+already have an active hold on that title.
\ No newline at end of file
diff --git a/docs/modules/circulation/assets/images/media/add_patrons.png b/docs/modules/circulation/assets/images/media/add_patrons.png
new file mode 100644 (file)
index 0000000..42c177e
Binary files /dev/null and b/docs/modules/circulation/assets/images/media/add_patrons.png differ
diff --git a/docs/modules/circulation/assets/images/media/catalog_place_hold.png b/docs/modules/circulation/assets/images/media/catalog_place_hold.png
new file mode 100644 (file)
index 0000000..0ef4f6d
Binary files /dev/null and b/docs/modules/circulation/assets/images/media/catalog_place_hold.png differ
diff --git a/docs/modules/circulation/assets/images/media/delete_hold_group.png b/docs/modules/circulation/assets/images/media/delete_hold_group.png
new file mode 100644 (file)
index 0000000..dbd701d
Binary files /dev/null and b/docs/modules/circulation/assets/images/media/delete_hold_group.png differ
diff --git a/docs/modules/circulation/assets/images/media/new_hold_group.png b/docs/modules/circulation/assets/images/media/new_hold_group.png
new file mode 100644 (file)
index 0000000..6c01fff
Binary files /dev/null and b/docs/modules/circulation/assets/images/media/new_hold_group.png differ
diff --git a/docs/modules/circulation/assets/images/media/new_hold_group_event.png b/docs/modules/circulation/assets/images/media/new_hold_group_event.png
new file mode 100644 (file)
index 0000000..389e183
Binary files /dev/null and b/docs/modules/circulation/assets/images/media/new_hold_group_event.png differ
index 058ac1f..4eae8da 100644 (file)
@@ -549,3 +549,242 @@ Click _Save_. The _Simplified Pull List Interface_ will now include the hold
 type each time that you log into the staff client.
+== Hold Groups
+[indexterm:Hold Groups,User Buckets,Hold Subscriptions]
+The Hold Groups feature allows library staff to create lists of
+patrons that can then be used to place multiple title-level holds on the
+same bibliographic record. This is useful for book clubs, new or
+on-order items, and/or high demand items.
+The Hold Groups interface is based on the xref:circulation:circulation_patron_records_web_client.adoc#_user_buckets[User Buckets]
+feature, where staff can create lists of patrons and perform batch
+actions for each user on the list.
+=== Notable Features of Hold Groups
+Patrons can be added to a Hold Group by patron barcode, by an integrated
+patron search in the Hold Group interface, and through the normal patron
+Hold placement can be randomized so that when a hold is placed it does
+not always follow the order in which patrons were added to the Hold
+Group, thereby ensuring a fairly distributed holds queue placement for
+members of the Hold Group.
+Hold Groups for an individual patron are visible on that patron’s record
+under *Other -> Hold Groups*.
+Hold Groups can be made visible to the patron through the public
+catalog. From *My Account*, patrons can view their current hold Hold
+Groups and remove themselves from a Hold Group if desired.
+Like User Buckets, hold Hold Groups are visible only to the staff member
+who created them but can be shared through Bucket ID.
+Please see xref:admin:hold_groups_admin.adoc[Hold Groups Administration] for information on some of the technical
+developments related to this feature.
+Please see xref:opac:my_account.adoc#hold_groups_opac[Hold Groups OPAC] for information on using Hold Groups from the OPAC My Account interface.
+=== Hold Groups Staff Interface 
+The new Hold Groups interface is found under *Circulation -> Hold
+The interface is divided into four tabs:
+* *Hold Groups* - The *Hold Groups* tab provides an overview of all Hold
+Groups created by the logged in user. New Hold Groups can be created
+from this tab.
+* *Current Users* - The *Current Users* tab is used to view the list of
+users on the open Hold Group. Hold Groups can also be created, edited,
+and deleted from this tab. Access to shared Hold Groups can be found on
+this tab as well.
+* *Add Users* - The *Add Users* tab is used to identify patrons to add to
+the open Hold Group.
+* *Hold Events* - The *Hold Events* tab displays a list of holds placed
+for users in the open Hold Group. Holds can be initiated and canceled
+from this tab as well.
+As with other interfaces in Evergreen, the tabs for Current Users, Add
+Users, and Holds Events include checkboxes for each line (users, holds,
+etc.), which are used to activate the Actions menu. The Actions menu is
+different on each tab and allows for actions appropriate to the purpose
+of the section.
+Double-clicking on a Hold Group will open the Hold Group in the *Current
+Users* tab.
+=== Staff Workflows
+The following workflows detail how to create new Hold Groups, add users
+to a Hold Group, edit and delete a Hold Group, and place holds for a
+Hold Group.
+==== Create a New Hold Group
+. Go to *Circulation -> Hold Groups*.
+. On the Hold Group tab, click *New Hold Group*.
+. Enter a name for the Hold Group.
+. Enter a description for the Hold Group (optional).
+. Choose the owning library from the drop-down (defaults to the
+workstation library).
+. If you want the Hold Group to be visible to the patrons on the list,
+check the *Visible to Patrons?* checkbox.
+. Click *Create Bucket*.
+The same workflow may be used on the *Current Users* and *Add Users*
+tabs to create a new Hold Group.
+image::media/new_hold_group.png[Create New Hold Group]
+==== Add Users to a Hold Group
+Patrons can be added to a Hold Group by barcode, by searching for a
+patron with an integrated patron search on the Add Users tab, or by a
+normal patron search. Staff must have PLACE_HOLD permissions to add
+patrons to a Hold Group at least at the same organizational unit depth
+(library) as the patron they are trying to add. For example, a staff
+member with branch level permissions for Branch A could only add patrons
+to Hold Groups owned by Branch A. If they needed to add patrons to
+Branch B or Branch C too, they would need system or consortial-level
+===== Add Users By Barcode
+. Go to *Circulation -> Hold Groups*.
+. Double-click the name of the Hold Group you wish to add patrons to.
+. Go to the *Add Users* tab.
+. Scan or enter the patron barcode into the *Scan Barcode* field.
+. Added patrons appear in a list under the *Add All To Hold Group* button.
+Users in this list are considered pending and have not yet been added to
+the Hold Group. Note that the parenthetical number for *Add Users*
+increases to display the number of pending users.
+. Continue adding barcodes as needed.
+. From the list, select one or more users with the checkboxes at the
+beginning of each row or select all users with the checkbox at the list.
+. Use the *Actions* button (or right click any user line) and choose *Add
+to Hold Group*. The users will now appear on the *Current Users* tab as
+part of the Hold Group.
+image::media/add_patrons.png[Add Users to Hold Group]
+===== Add Users With Integrated Patron Search 
+. Go to *Circulation -> Hold Groups*.
+. Double-click the name of the Hold Group you wish to add patrons to.
+. Go to the *Add Users* tab.
+. Click *Search for Patron*. A patron search pop-up opens. The search is
+scoped to the workstation of the logged in staff member, but can be
+expanded by using the additional search fields.
+. Enter search criteria into the appropriate fields. The pop-up defaults
+to the basic patron search. Additional search fields are available by
+clicking the down-arrow button to the right of the Search button. This
+option is sticky.
+. Click *Search* or hit the *Enter* key. Results appear in the bottom
+portion of the pop-up window.
+. Click anywhere on a row in the results list to select that patron.
+. Click *Select*. The patron is added to the list of pending users. Users
+on this list have not yet been added to the Hold Group. Note that the
+parenthetical number for Add Users increases to display the number of
+pending users.
+. Continue adding patrons as needed.
+. From the list, select one or more users with the checkboxes at the
+beginning of each row or select all users with the checkbox at the list.
+. Use the Actions button (or right click any user line) and choose *Add to
+Hold Group*. The users will now appear on the *Current Users* tab as
+part of the Hold Group.
+. You can add some or all of the users in the pending users list to
+different Hold Groups without entering barcodes or searching again.
+Simply go to the *Hold Groups* tab and double-click another Hold Group
+from the list. Return to the *Add Users* tab and select the users you
+wish to add to the new Hold Group, and use the Actions menu to add them
+to the Hold Group.
+===== Add Users From Patron Search
+. Go to *Search -> Search for Patrons*.
+. Enter your search criteria.
+. Use the checkboxes on each patron search result to select one or more
+. Click *Add to Bucket*.
+. A list of Hold Groups, as well as other patron buckets, are visible.
+(Only those Hold Groups created by the logged in user are visible.)
+Choose the Hold Group to which you want to add the patron(s) or create a
+new Hold Group.
+. A message displays on the bottom right corner of the screen to confirm
+whether the patrons were added successfully to the Hold Group.
+==== Edit An Existing Hold Group
+. Go to *Circulation -> Hold Groups*.
+. On the Hold Groups tab, double-click the Hold Group you wish to modify.
+This will open the Hold Group in the Current Users tab.
+. Click the Hold Groups button and choose Edit Hold Group.
+. The *Edit Bucket* pop-up will open. You can edit the name, description,
+owning library, or visibility.
+==== Place Holds For a Hold Group
+Holds can be placed from the Hold Groups interface or by searching the
+catalog. Staff must have MANAGE_BATCH_HOLDS permissions to place a batch
+hold or cancel holds with this interface.
+===== From the Hold Groups Interface
+. Go to *Circulation -> Hold Groups*.
+. From the *Hold Groups* tab, double-click a Hold Group. The Hold Group
+will open in the *Current Users* tab.
+. Go to the *Hold Events* tab.
+. Click on *New Hold Group Event*.
+. Enter the *Record ID* number for the bibliographic record on which you
+wish to place the hold.
+. Use the checkbox to override all hold-blocking conditions possible if
+. Click *Create Event*.
+image::media/new_hold_group_event.png[New Hold Group Event]
+===== From Searching the Catalog
+. Search the catalog to identify the record on which you wish to place a
+. Click “Place Hold” from the results or detailed record. The Hold
+Placement page appears.
+. Use the radio button to choose Place hold for patron Hold Group and use
+the drop-down to choose the Hold Group from the
+image::media/catalog_place_hold.png[Hold Group From Catalog]
+. Please note that most additional hold options (e.g., choosing the pickup
+library or notification preferences) are disabled for holds placed by
+Hold Group. Pickup location and notification preferences adhere to the
+defaults for the respective patrons. Patrons can edit their notification
+preferences and pickup locations from My Account on the public catalog
+after the hold is placed. Holds may be suspended and an activate date
+added if desired.
+. Click Submit.
+Holds can be cancelled from the Hold Events tab by selecting the hold
+and using the Actions menu and choosing *Cancel Hold Group Event.*
+==== Deleting a Hold Group
+Hold Groups can be deleted on the Current Users tab. Deleting a Hold
+Group does not cancel any holds placed through the Hold Group.
+. Go to *Circulation -> Hold Groups*.
+. From the Hold Group tab, double-click the Hold Group you wish to delete.
+This will open the Hold Group in the Current Users tab.
+. Click the *Hold Groups* dropdown and choose *Delete Hold Group*.
+image::media/delete_hold_group.png[Delete Hold Group]
\ No newline at end of file
index 30fcf92..ea0c7b5 100644 (file)
@@ -2,8 +2,9 @@
 ** xref:admin:librarysettings.adoc[Library Settings Editor]
 ** xref:admin:lsa-address_alert.adoc[Address Alert]
 ** xref:admin:lsa-barcode_completion.adoc[Barcode Completion]
-** xref:admin:hold_driven_recalls.adoc[Hold-driven recalls]
 ** xref:admin:emergency_closing_handler.adoc[Emergency Closing Handler]
+** xref:admin:hold_driven_recalls.adoc[Hold-driven recalls]
+** xref:admin:hold_groups_admin.adoc[Hold Groups Administration]
 ** xref:admin:actiontriggers.adoc[Notifications / Action Triggers]
 *** xref:admin:actiontriggers_process.adoc[Processing Action Triggers]
 ** xref:admin:staff_client-recent_searches.adoc[Recent Staff Searches]
diff --git a/docs/modules/opac/assets/images/media/opac_hold_groups.png b/docs/modules/opac/assets/images/media/opac_hold_groups.png
new file mode 100644 (file)
index 0000000..d4c0684
Binary files /dev/null and b/docs/modules/opac/assets/images/media/opac_hold_groups.png differ
diff --git a/docs/modules/opac/assets/images/media/opac_remove_hg.png b/docs/modules/opac/assets/images/media/opac_remove_hg.png
new file mode 100644 (file)
index 0000000..504644b
Binary files /dev/null and b/docs/modules/opac/assets/images/media/opac_remove_hg.png differ
index 33681a1..f7bc5a2 100644 (file)
@@ -1,6 +1,7 @@
 * xref:opac:introduction.adoc[Using the Public Access Catalog]
 ** xref:opac:using_the_public_access_catalog.adoc[Using the Public Access Catalog]
 ** xref:opac:my_lists.adoc[My Lists]
+** xref:opac:my_account.adoc[My Account]
 ** xref:opac:batch_actions_from_search.adoc[Batch Actions from Search]
 ** xref:opac:kids_opac.adoc[Kids OPAC]
 ** xref:opac:catalog_browse.adoc[Catalog Browse]
index 8bc1550..4052fcd 100644 (file)
@@ -180,6 +180,33 @@ To protect patron privacy, the Holds History will be completely blank unless the
+=== Hold Groups
+[indexterm: Hold Groups]
+Screenshots in this section are taken from the Bootstrap OPAC (BOOPAC),
+but similar functionality is available in the Template Toolkit OPAC
+A patron who is a member of a publicly visible xref:circulation:basic_holds.adoc#hold_groups[Hold Group] will see
+a new option on the Holds menu of My Account labelled *Hold Groups*.
+image::media/opac_hold_groups.png[My Account Hold Groups]
+If the *Hold Groups* menu item is selected, the patron will see a list
+of Hold Groups of which they are a member, as well as a link for
+removing themselves from the Hold Group.
+image::media/opac_remove_hg.png[Remove Me From Hold Group]
+Only those Hold Groups that were marked by staff as “publicly visible”
+are displayed. If the patron does not belong to any publicly visible
+Hold Groups, the Hold Group menu item is not displayed at all.
+Holds placed through a Hold Group can be modified by patrons in the same
+way as other holds (e.g., suspended, cancelled, etc.).
 == Account Preferences ==
 indexterm:[my account, account preferences]