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.