User Tools

Site Tools


dev:proposal:patron_statistical_categories

Patron Statistical Category Enhancements

This proposal covers the following enhancements to Patron Statistical Categories:

  • Allow administrators to set Patron Statistical Categories as required fields;
  • Allow administrators to set a flag that prevents users from entering free text in a Patron Statistical Category
  • Allow administrators to set a default entry from the list of fixed entries available in the Patron Statistical Category

Background Information

Evergreen has user-defined fields called statistical categories (aka stat cats) that can be configured with the following information:

  • A category name
  • The owning organization – can be system wide or specific for a particular library
  • Whether the category can be made visible in the OPAC
  • A list of valid values for the statistical category to populate a drop down

Statistical categories are intended to be used for reporting and are not used in any business logic in the application itself. Stat cats can be set up for patrons and copies (an individual item in a library).

Statistical categories for copies can be made required when they are set up in the Statistical Categories Editor. When a user enters a value for a statistical category, they must select from the list of valid values in the drop down list.

Statistical categories for patrons cannot be made required. In addition, the user is allowed to type in value for the statistical category instead of selecting from a drop down list.

Use Case

Certain patron statistical categories are used for important consortium-wide reporting that determines funding levels. For reports to be meaningful, the data used to generate the reports must be available and consistent. Towards this end, it is important that patron records are entered with valid values for these fields.

Requirements

Statistical Categories Editor

  • In the Statistical Categories editor, the System Administrator must be able to optionally specify a patron statistical category as required when then statistical category is created or edited. This is currently possible for copy statistical categories, but not for patron statistical categories.
  • In the Statistical Categories editor, the System Administrator must be able to optionally mark one and only one entry for the statistical category as the default entry for a given organizational unit.

Patron Registration Screen

  • When registering a new patron or updating the record for an existing one, if the statistical category is required, do not allow the user to save the record if no default entry has been set AND no entry has been selected or no free text has been entered.
  • When registering a new patron or updating the record for an existing one, do not allow the user to enter text if the statistical category is set up to not allow user-entered text.
  • When registering a new patron, display a default value in the statistical category form field if a default entry has been configured in the entry list for the org unit or an ancestor org unit. Allow the user to save the record if the no change is made to the field; the value of the statistical category will be the default entry. When updating existing patrons, no default value will be supplied: the value of the form field will either be the previously-saved value or empty.

Objects Affected

All modified files are available at https://github.com/sprater/Evergreen/tree/patstatcat.

Comparisons: https://github.com/sprater/Evergreen/compare/patstatcat

Database TABLE actor.stat_cat

  • Add a Boolean field called required. Default is FALSE. This will be the same as the required field already in copy.stat_cat.
  • Add a Boolean field called allow_freetext. Default is TRUE. If this value is FALSE, a user must select a value from the drop-down list.

NEW Database TABLE actor.stat_cat_entry_default

  • Create a new table actor.stat_cat_entry_default to store default entries for statistical categories. It will have the following structure:
      id              SERIAL  PRIMARY KEY,
      stat_cat_entry  INT     NOT NULL REFERENCES actor.stat_cat_entry(id) ON DELETE CASCADE DEFERRABLE INITIALLY DEFERRED,
      stat_cat        INT     NOT NULL REFERENCES actor.stat_cat(id) ON DELETE CASCADE DEFERRABLE INITIALLY DEFERRED,
      owner           INT     NOT NULL REFERENCES actor.org_unit(id) ON DELETE CASCADE DEFERRABLE INITIALLY DEFERRED,
      CONSTRAINT sced_once_per_owner UNIQUE (stat_cat,owner)

See 005.schema.actors.sql and 950.data.seed-values.sql.

Statistical category editor

  • Add code to manage the new fields in actor.stat_cat and the new table actor.stat_cat_entry_default.

See

Patron registration

  • Read values for actor.stat_cat.required, actor.stat_cat.allow_user_entered_values, and actor.stat_cat_entry_default.
  • Add validation for required statistical categories.
  • Disable user entered values in statistical category if not allowed.
  • If a default entry is specified for the org unit and statistical category, mark it as selected by default.

See Open-ILS/web/js/ui/default/actor/user/register.js

Tests

The purpose of the tests is to verify that the new functions work as expected, as well as to ascertain that previous functionality has not been changed or broken.

Test suite 1: Verify required patron statistical field with fixed values and an entry marked as default

  1. Create a new patron stat category and make it required and disallow user-entered values. Create one or more entries.
  2. Mark one of the fixed entries as the default entry in the new patron stat category.
  3. Make an existing patron statistical category required and disallow user-entered values. Mark one of the fixed entries as the default entry.
  4. Register a new patron.
  5. Don’t enter values for the required statistical categories. Confirm that the record will be saved with the specified default value.
  6. Confirm that the user cannot enter their own values.
  7. Edit an existing patron.
  8. Don’t enter values for the required statistical categories. Confirm that the record will be saved with the previously-saved default.
  9. Confirm that the user cannot enter their own values.

Test suite 2: Verify required patron statistical field with fixed values and no entry marked as default

  1. Create a new patron stat category and make it required and disallow user-entered values. Do not mark any entry as the default.
  2. Make an existing patron statistical category required and disallow user-entered values. Do not mark any entry as the default.
  3. Register a new patron.
  4. Don’t enter values for the required statistical categories. Confirm that the user must select a value from the drop-down before the record will be saved.
  5. Confirm that the user cannot enter their own values and must select from the drop-down.
  6. Edit an existing patron and repeat the tests in step 4 and 5.

Test suite 3: Verify required patron statistical field with user-entered values and no entry marked as default

  1. Create a new patron stat category, make it required and allow user-entered values.
  2. Edit an existing patron stat category, make it required and allow user-entered values.
  3. Register a new patron.
  4. Don’t enter values for the required statistical categories. Confirm that the record can not be saved until values are entered for the required statistical categories.
  5. Confirm that a user can enter their own values and save their record.
  6. Edit an existing patron and repeat steps 4 and 5.

Test suite 4: Verify optional patron statistical field with fixed values and an entry marked as default

  1. Create a new patron stat category, make it optional and disallow user-entered values.
  2. Edit an existing patron stat category, make it optional and disallow user-entered values.
  3. Register a new patron.
  4. Confirm that a user can save their record without entering any values in the optional category. Confirm that the value saved is the default value.
  5. Confirm that a user cannot enter their own values and must select from the drop-down if they choose to fill in the field.
  6. Edit an existing patron.
  7. Confirm that a user can save their record without entering any values in the optional category. Confirm that no value is saved.
  8. Confirm that a user cannot enter their own values and must select from the drop-down if they choose to fill in the field.
  9. Confirm that if no value was previously saved for the optional category, the patron edit screen displays an empty field for the category.

Test suite 5: Verify optional patron statistical field with fixed values and no entry marked as default

  1. Create a new patron stat category, make it optional and disallow user-entered values.
  2. Edit an existing patron stat category, make it optional and disallow user-entered values.
  3. Register a new patron.
  4. Confirm that a user can save their record without entering any values in the optional category. Confirm that no value is saved for the optional category.
  5. Confirm that a user cannot enter their own values and must select from the drop-down if they choose to fill in the field.
  6. Edit an existing patron and repeat steps 4 and 5.

Test suite 6: Verify optional patron statistical field with user-entered values and no entry marked as default (original behavior)

  1. Create a new patron stat category, make it optional and allow user-entered values.
  2. Edit an existing patron stat category, make it optional and allow user-entered values.
  3. Register a patron.
  4. Confirm that a user can save their record without entering any values in the optional category.
  5. Confirm that a user can enter their own values and save their record if they choose to fill in the field.
  6. Edit an existing patron and repeat steps 4 and 5.
dev/proposal/patron_statistical_categories.txt · Last modified: 2022/02/10 13:34 by 127.0.0.1

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.