DCB-1661 Polaris virtual patron analysis

This page documents the current state of the DCB Service's patron search functionality within Polaris library systems. The goal is to improve the reliability of finding virtual patrons and explore the viability of deleting them.

Scope: This document focuses solely on Polaris LMS.

Current Polaris Patron Methods

Finding Virtual Patrons:

The DCB Service utilizes the PAPI Service API method "Patron Search" to locate virtual patrons. This method relies on the "PATNF" field (Name - First, Middle, Last) and the "real" patron's barcode. Documentation for this API can be found here: https://documentation.iii.com/polaris/PAPI/current/PAPIService/PAPIServicePatronSearch.htm#papiservicepatronsearch_3172958390_1270206

Creating Unique Virtual Patrons:

The DCB Service creates virtual patrons using the "PatronRegistrationCreate Version 1" method within the PAPI Service API. Details and request body example can be found here: https://documentation.iii.com/polaris/PAPI/current/PAPIService/PAPIServicePatronRegistrationCreate_v1.htm

Patron Field Usage in DCB Polaris Patron Creation

_{PatronBranchID:}

• _{Usage: Specifies the item location ID.}

• _{Source: Derived from the items assigned branch ID.}

_NameFirst:

• _{Usage: Stores the original patron's barcode.}

• _{Source: Extracted from the original patron's information.}

_NameLast:

• _{Usage: Stores the UniqueID[0] value, a combination of the local patron ID and agency code.}

• _{Source: DCB constructed.}

_PatronCode:

• _{Usage: Specifies the local patron type.}

• _{Source: Mapped from the original patron type.}

_Barcode:

• _{Usage: Generates a unique barcode for the virtual patron.}

• _{Formula: Prefix (from configuration) + Original Patron Barcode}

_{Birthday (Required):}

• _{Usage: A mandatory field in Polaris.}

• _{Value: A fixed date "1999-11-01".}

Potential Issues with Patron Search

• Missed Patrons: In some cases, the search might miss existing virtual patrons, leading to the error “Unable to create virtual patron at polaris - error code: -3529” when the DCB Service attempts to create a new one. Examples of such requests can be found here:

  • https://libraries-dcb-hub-admin-scaffold-uat-git-production-knowint.vercel.app/en-US/patronRequests/aecb1de3-e3c4-4b64-bec4-e856c12849ac

  • https://libraries-dcb-hub-admin-scaffold-uat-git-production-knowint.vercel.app/en-US/patronRequests/35c8afe9-3b3c-4c78-8954-8730a7e420d2

  • https://libraries-dcb-hub-admin-scaffold-uat-git-production-knowint.vercel.app/en-US/patronRequests/07bd3105-4410-4bf1-ab01-b85cdeb7796e

• Ambiguous Matches: Due to relying on the "PATNF" field, situations can arise where the real patron's barcode is also a name. This leads to finding multiple virtual patrons, stopping the DCB Service from processing the request. Examples can be found here:

  • https://libraries-dcb-hub-admin-scaffold-uat-git-production-knowint.vercel.app/en-US/patronRequests/0ba8821f-349c-4689-80f8-5d7313926766

  • https://libraries-dcb-hub-admin-scaffold-uat-git-production-knowint.vercel.app/en-US/patronRequests/490f931b-2830-42aa-ae28-d4346fa52a44

  • https://libraries-dcb-hub-admin-scaffold-uat-git-production-knowint.vercel.app/en-US/patronRequests/37625062-f907-4745-8c2b-aa092a2988b2

• False Positives: There's a possibility of finding the wrong virtual patron due to limitations in barcode-based searching. If the initial search returns a single (incorrect) match, the DCB Service might proceed with that patron, potentially leading to issues with supplier-side requests.

Improving Patron Search Reliability

Addressing Ambiguity:

• Leverage Unique Identifiers that DCB currently holds such as; Existing Local patron ID (Patron Identity), DCB’s Patron UniqueId and DCB Patron UUID.

• Expand the search criteria to include checks when multiple patrons are found to improve accuracy and reduce ambiguity.

• Implement a strategy to validate exact matches by cross-checking multiple criteria, helping to minimise false positives.

Improving Diagnostics

• Enhance patron search logging to capture specific details about search failures, including search criteria, results, and potential reasons for mismatches.

• Monitor the performance of patron search queries to identify success rate/failure rate.

• Develop more rigorous testing strategies for testing current known issues.

Identifying DCB Virtual Patrons

• Consider using the PATNL field to search by DCB’s Patron Unique Id.

• Consider using the existing Patron identity local ID if it already exists in DCB.

• A script querying the patron barcode prefix can potentially identify all virtual DCB patrons that exist in a local Polaris system. 

Assessing the Viability of Virtual Patron Deletion

Prerequisites:

• A reliable patron search mechanism is essential to accurately identify and target virtual patrons for deletion.

• Conduct a thorough impact assessment to understand the potential consequences of deleting virtual patrons, including data loss and system disruptions.

Key Considerations:

• In-Flight Requests: Identify and address any in-flight requests associated with the virtual patron before deletion.

• Data Retention Policy: Establish a clear data retention policy to determine how long virtual patron records should be retained before deletion.

• Backup and Recovery Strategy: Develop a robust backup and recovery strategy to minimise data loss risks associated with deletion.

• Testing and Pilot: Implement a phased approach with rigorous testing and a pilot program to evaluate the feasibility and impact of virtual patron deletion.