Managing Materials Requests (aka Purchase Suggestions) in Koha and Aspen Discovery

by Kalleen Marquise on Mar 1, 2023

If you are a Koha and Aspen library, we typically suggest you set up your Materials Request system in Koha and then Aspen can pull from that setup.

Because Aspen is ILS-agnostic, there is a separate Aspen Materials Request module that will work with any ILS and does not require any set up in Koha. There is more information about that module here. Libraries can also choose to simply display a link to an external materials request form in Aspen (Example: Google Form, Jot Form, page on library website, etc.) without setting up anything in Aspen or Koha. There is more information about that option here.

In this blog post, we are only going to focus on the Koha ILS Materials Request System and how it works with Aspen.

Allow Patrons to Make Purchase Suggestions in Koha

  1. Go to your Global System Preference in the Administration Module of Koha and search for the system preference suggestion. (Note: There are several system preferences that will display with this search term. This one is found in OPAC > Features > suggestion.)
  2. Turn to this preference to “enable"

Set Your Mandatory Fields in Koha

It is very important to pick which fields should be required when patrons fill out the purchase suggestion form.

This global system preference is called OPACSuggestionMandatoryFields. Click into the system preference and select your required fields.

If you are setting up Item Type as a mandatory field, it can be very helpful in determining what format of that item your patron really wants the library to order.

To have users select from a drop down of predetermined formats for item type, set them up in Koha Administration > Authorized Values under SUGGEST_FORMAT. If the authorized value SUGGEST_FORMAT is not set up you can create a new authorized value for this purpose.

Once you create this authorized value SUGGEST_FORMAT, you can add item types as they are shown in your Koha Administration > Basic Parameters > Item Types section. You can limit the item types that are available for purchase suggestions. For example, you may not want patrons to suggest Reference item types. Using the SUGGEST_FORMAT authorized values instead of your full list of item types gives you more control over the item type options available to your patrons.

When creating your Suggest Format codes, enter a Description and an OPAC description into this form. The Description (OPAC) is what will appear in Aspen.

Similarly, if you want to set up an Authorized Value for Reasons for Purchase (patronreason), you can do that in Koha Administration > Authorized Values under OPAC_SUG. What is set in the Description (OPAC) column is what will show in Aspen on the request form. The Description column will display to your staff in the Suggestions management section of the Acquisitions module in Koha.

Set Maximums on Patrons Submitting Requests in Koha

MaxOpenSuggestions: This is an open text box where you can assign a numeric value to the number of open suggestions a patron can make. Only Pending suggestions without a staff response will count towards this total. These items will show as Asked status on the patron's account in Aspen.

The default message in Aspen will be, "Reached the maximum pending suggestions limit". This message can be translated within the Aspen translation module.

MaxTotalSuggestions/NumberOfSuggestionDays: Total number of suggestions allowed in X number of days. All purchase suggestions, regardless of staff response, count towards this total.

The default message in Aspen will be, "Reached the suggestion limit". This message can be translated within the Aspen translation module.

Now that the initial setup is configured in Koha, let's move over to Aspen.

Turn on the Materials Request Form in Aspen

Users will need the the following permission to enable this functionality:

Library Materials Request Options
Configure Library fields related to how materials request is configured in Aspen

Full Aspen Admin users should have this by default.

Navigate to Aspen Administration > Primary Configuration > Library Systems > click into your library system > Materials Request > Materials Request System > select ILS Request System

Check Turn on Materials Request for Public when you are ready to see this form in Aspen.

Check Allow Deleting ILS Materials Requests if you want patrons to have the ability to delete suggestions from My Account > Materials Requests in Aspen.

Where Does the Materials Request Form Display in Aspen?

Patrons can find the Materials Request form in up to five places within Aspen:

  • Directly via this URL: {YourAspenURL}/MaterialsRequest/NewRequestIls
  • At the bottom of search results:
  • Within My Account > Materials Requests
  • Within the My Account > shortcut dropdown underneath the patron's name
  • By setting up a Menu Link of your choice, using the URL above, either along the top navigation bar along the top or in the side/hamburger menu of the Aspen catalog. Learn more about setting up Menu Links in Aspen here.




Hide and Adjust Unwanted Fields in Aspen

Hide Unwanted Fields

Aspen does not honor OPACSuggestionUnwantedFields in Koha and will show pre-set fields by default.

Non-mandatory fields can be hidden by going to Aspen Administration > Local Catalog Enrichment > JavaScript Snippets > Add New > name it something like Hide Fields on Materials Request form > add information from the snippet below

Use the Inspect tool in the browser to find the row/property ID that you want to hide.

Examples include:

<script>

$( "#propertyRowcopyrightdate" ).hide();

$( "#propertyRowisbn" ).hide();

$( "#propertyRowpublishercode" ).hide();

$( "#propertyRowcollectiontitle" ).hide();

$( "#propertyRowplace" ).hide();

$( "#propertyRowquantity" ).hide();

$( "#propertyRowitemtype" ).hide();

$( "#propertyRowbranchcode" ).hide();

$( "#propertyRownote" ).hide();

$( "#propertyRowpatronreason" ).hide();

</script>

So, if I wanted to hide the Standard number (ISBN,ISSN or other) field, the Publisher field, the Collection field, the Publication place field, and the Quantity field (common fields to hide), I would copy this code:

<script>

$( "#propertyRowisbn" ).hide();

$( "#propertyRowpublishercode" ).hide();

$( "#propertyRowcollectiontitle" ).hide();

$( "#propertyRowplace" ).hide();

$( "#propertyRowquantity" ).hide();

</script>

Changes will go into effect immediately.

Note: If the field is set to Mandatory in Koha in OPACSuggestionMandatoryFields and you hide it in Aspen with JavaScript, the form will not successfully submit. You must remove the field from OPACSuggestionMandatoryFields before you can hide the field in Aspen.


Adjust Unwanted Fields

The default field order on the Materials Request form is pre-set.

You can adjust the text labels on the field by entering Translation Mode in Aspen (more about language below) and adjusting the text. The fields will still correspond to the fields in Koha, so you wouldn't want to do this to completely swap fields, but this is great if you want to change "Copyright Date" to "Copyright Year" or "Item Type" to "Format" (for example).

Customize the Form Message in Aspen

The default message at the top of the Materials Request form in Aspen reads, "Please fill out this form to make a purchase suggestion. You will receive an email when the library processes your suggestion. Only certain fields are required, but the more information you enter the easier it will be for the librarians to find the title you're requesting. The Notes field can be used to provide any additional information."

To override the default messaging and add messaging of your own, go to Aspen Administration > Primary Configuration > Library Systems > click into your library system > Materials Request > New Request Summary

You might want to include information about your selection process, a hyperlink to your Collection Development policy, and other commonly asked questions related to the process.

Text entered in this New Request Summary box will override the default messaging and automatically appear at the top of the form.



The Patron View in Aspen

Patrons will see their submitted Materials Requests in My Account > Materials Requests.

Each request will display the following fields:

  • Summary: Title + Format + Author + Publication Year (if these fields were filled in by them)
  • Suggested On: Date of Submission
  • Note: Any notes the patron added in the Materials Request Notes field
  • Status: The status of their request. The default status will be Pending until action has been taken by a staff member to update the status. Note that Aspen will display the Authorized Value code from SUGGEST_STATUS (see below)



Users will be able to delete their current suggestions if this option is turned on in Aspen. They will also be able to submit a new request from this screen by clicking the "Submit a New Materials Request" button.


Staff Management of Suggestions in Koha

When a new Materials Request is submitted through the Materials Request form in Aspen, a "Suggestions pending approval" will show up toward the bottom of the main page of the Koha staff interface.

Staff members with the Suggestions Management - Manage purchase suggestions (suggestions_manage) permissions will be able to see and manage these submissions.

This module can also be accessed in the Koha Staff Interface in Acquisitions > Suggestions.

For libraries with multiple branches, the view will default to the logged-in library in Koha. To view suggestions from another or all branches, select from "Viewing suggestions for library" pulldown menu.

In the Suggestions Management view, you can see all Pending, Available, Checked, Ordered, and Rejected titles. Along the left side, if you click Suggestion Information, a number of different search filters will expand.

In the Pending view, you can see the form and click Edit to manage an individual suggestion or select multiple submissions by using the check boxes and batch updating the statuses with the Change Selected Suggestions tools along the bottom.

When you click into an individual submission, scroll to the Suggestion Management section to update the submission.

Set Default Statuses and Reasons for Suggestion Management in Koha

The values in the Choose a status dropdown are a combination of default values and any additional values set in Administration > Authorized Values > SUGGEST_STATUS

The default values are:

  • Pending
  • Accepted
  • Checked
  • Rejected
  • Ordered

Any additional values added in SUGGEST_STATUS will be added below these values in the dropdown in Koha.

In Aspen, the status to the patron will display as the Authorized Value code of any additional statuses that you add, NOT the Description or Description (OPAC).

The values in the with this reason dropdown are set in Administration > Authorized Values > SUGGEST.

In Aspen, under the Status column, the patron will see a combination of SUGGEST_STATUS + (SUGGEST) information.

Set Suggestion Notices in Koha

In Koha you can have various notices go out in relation to these different suggestion management statuses.

To find and edit notices, navigate to Tools > Notices and Slips > search for "suggest" to pull up related notices.

A suggestion's status change will trigger an email notice to be sent to the patron who made the suggestion.

The "Accepted" status will trigger the ACCEPTED notice.

The "Rejected" status will trigger the REJECTED notice.

The "Ordered" status will trigger the ORDERED notice. Note: the "Ordered" status will automatically be set when ordering from a suggestion and the corresponding notice will also be sent at that time. Change to this status manually only if you don't use the Acquisitions module to enter your orders.

To edit a notice, select Edit in the Actions column and then expand Email on the Default tab. Be sure to Save any changes you make before navigating away from this page.

If you don't want to send one of these notices, you can select Delete in the Actions column.

If you add custom statuses in the SUGGEST_STATUS authorized values, you can add corresponding notices with the same names, taking care to choose the "Suggestions" module when creating the new notices. Follow the detailed instructions in this blog post:

Koha Question of the Week: Can A New Status Be Added in Purchase Suggestions

The following notices relate to messages sent to internal accounts:

NEW_SUGGESTION - Disabled because the EmailPurchaseSuggestions/ EmailAddressForSuggestions system preference does not translate between Koha and Aspen.

  • TO_PROCESS - Requires the Email suggestions to process cron to be enabled, generating a notice to the fund owner that there are suggestions in need of processing.

NOTIFY_MANAGER - Notice sent to a staff member when they are assigned as a manager of a suggestion in the Acquisitions module. This notice generates, regardless of whether the purchase suggestion was created in the Koha OPAC or in Aspen.

Tying the Suggestions into Acquisitions in Koha

If you plan to use Koha's Acquisitions module to manage the suggestions, find more detailed information here:

Self Paced Learning in Koha: Purchase Suggestions

Choosing Between Calling this Process "Materials Request" or "Purchase Suggestion" to Patrons in Aspen

Language is important to clearly convey to patrons what is what in the library catalog. Aspen is an ILS-agnostic system so it is not always set up with Koha-specific language.

In Koha, the default wording for this process is called Purchase Suggestions. In Aspen, the default wording for this process is Materials Requests.

If you are already using this in Koha or a newly migrating Koha library, you may want to adjust the wording to match what patrons are used to.

In this case, you can translate anywhere it says "Materials Request" to "Purchase Suggestion" in Aspen (or to a completely different term your users are familiar with!)

To do this go to Aspen Administration > Languages & Translations > Translations > check Show All Translations > enter Materials Request in the Show Terms containing field > Update Filters > anywhere in the right hand column where you see Materials Request, change to Purchase Suggestion > Save.

These changes will be applied immediately.

Note: If you are in a consortium/manage multiple catalogs, this will change it on all Aspen interfaces.


Test - Test - Test

Now that you have this all set up, fill out the Materials Request form in Aspen and test the submission.

Then, go into Koha and make sure you can see the submission (could take a minute or so) and that you can update the status of the submission.

Test any notices that you may have set up along with this process.

Considerations for Consoritums

While the IndependentBranches system preference in Koha prevents staff (but not Superlibrarians) from modifying objects (holds, items, patrons, etc.) belonging to other libraries, this setting doesn’t affect purchase suggestions management. Staff with the suggestions_manage permissions can view and edit suggestions from any branch.

In Koha, you can set permissions per library location to manage purchase suggestions. The mandatory fields and authorized values would need to be the same on each of the forms within Koha.

In Aspen, the decision to accept and display the Materials Request form can be set per library system. To turn this on/off for a library system, go to go to Aspen Administration > Primary Configuration > Library Systems > click into your library system > Materials Request > and select None to turn off materials request or one of the other options to turn on. To turn this on for a large group or all libraries, use the Batch Update Selected or Batch Update All tool at the bottom of your Library Systems.

Additional Information

The following Koha System Preferences DO NOT interact with the Aspen opac:

  • OPACViewOthersSuggestions– Choose to allow or don’t allow to show purchase suggestions from other patrons on the OPAC.
    • Aspen catalog users cannot view other purchase suggestions
  • OPACSuggestionUnwantedFields- This system preference will allow libraries to hide fields they don't want/need for their patron to fill out.
    • Unwanted fields in Aspen can be hidden with Javascript (see above)
  • OPACSuggestionMandatoryFields > Branch Code
    • Aspen will populate this field but will not pull in the values from Basic Parameters > Libraries. We suggest you do not make this mandatory for this reason.
  • OpacSuggestionManagedBy- Show or don’t show the name of the staff member who managed a suggestion in the OPAC
    • Aspen will not show the name of the staff member who managed their suggestion
  • AnonSuggestions- Allow or don’t allow patrons that aren’t logged in to make purchase suggestions- this works with Anonymous Patron
    • Aspen will force users to log in to fill in the Materials Request form. There is no way to submit an anonymous Materials Request. Staff can assist patrons via Masquerade Mode in placing a Materials Request or by using a staff account to submit suggestions on behalf of a patron without a card.
  • EmailPurchaseSuggestions/ EmailAddressForSuggestions- For libraries that would like their purchase suggestions to go to a specific email, this can be set up to match a specific workflow regarding their purchase suggestions.
    • Materials Requests forms via Aspen will not trigger
  • OPACSuggestionAutoFill- Allow or don't allow OPAC suggestions form automatically filling with data from Google Books API.
    • Aspen will not autofill information into the Materials Request form from the Google Books API.


Aspen will not honor OPACUserJS Javascript, OPACUserCSS css or text set in Tools > News > OpacSuggestionsInstructions. All messaging on the Materials Request form is set within Aspen.

Aspen does not perform a duplicate check for the library when a patron submits a purchase suggestion.

Read more by Kalleen Marquise

Tags