Bug 41383 - SIP2 server does not search patrons by unique patron attributes (alternate IDs unusable in SIP2)
Summary: SIP2 server does not search patrons by unique patron attributes (alternate ID...
Status: Passed QA
Alias: None
Product: Koha
Classification: Unclassified
Component: SIP2 (show other bugs)
Version: Main
Hardware: All All
: P1 - high enhancement
Assignee: Saiful Amin
QA Contact: Martin Renvoize (ashimema)
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2025-12-05 06:28 UTC by Saiful Amin
Modified: 2026-03-07 06:18 UTC (History)
2 users (show)

See Also:
GIT URL:
Initiative type: ---
Sponsorship status: Unsponsored
Comma delimited list of Sponsors:
Crowdfunding goal: 0
Patch complexity: Small patch
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:
Circulation function:


Attachments
Bug 41383: Allow patron identification by custom unique attributes in find_by_identifier (4.62 KB, patch)
2025-12-08 19:20 UTC, Saiful Amin
Details | Diff | Splinter Review
Bug 41383 - SIP2 server does not search patrons by unique patron attributes (alternate IDs unusable in SIP2) (6.11 KB, patch)
2026-03-04 10:51 UTC, Saiful Amin
Details | Diff | Splinter Review
Bug 41383 - SIP2 server does not search patrons by unique patron attributes (alternate IDs unusable in SIP2) (6.15 KB, patch)
2026-03-05 11:51 UTC, Faheemuddin Syed
Details | Diff | Splinter Review
Bug 41383: SIP2 server does not search patrons by unique patron attributes (alternate IDs unusable in SIP2) (6.23 KB, patch)
2026-03-07 06:18 UTC, Martin Renvoize (ashimema)
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Saiful Amin 2025-12-05 06:28:50 UTC
Even when a patron attribute is marked as "Unique identifier," the SIP2 server cannot find patrons using that attribute value. SIP2 lookup is hard-coded to cardnumber/userid and does not consider extended attributes, even when it is unique.

Actual Result:
SIP2 returns "|AFInvalid cardnumber" when the SIP client sends a value stored in a unique patron attribute.

Expected Result:
SIP2 should be able to search by any patron attribute marked as a unique identifier.

Impact:
- Self-check machines using HID/NFC values fail
- Access control systems relying on alternate IDs cannot authenticate patrons

I plan to submit a patch that will allow unique extended patron attributes to be used in SIP2 requests.
Comment 1 Saiful Amin 2025-12-08 19:20:36 UTC
Created attachment 190311 [details] [review]
Bug 41383: Allow patron identification by custom unique attributes in find_by_identifier

Currently, Koha::Patrons->find_by_identifier only searches for patrons by userid and cardnumber.

This patch extends this method to also search by unique borrower attributes (where unique_id=1).
This enhancement allows modules like SIP2 to identify patrons using alternative unique identifiers
defined in the system.

Test Plan:
1. Apply the patch.
2. Run the tests:
   prove t/db_dependent/Koha/Patrons.t
   - Verify that all tests pass, including the new cases for unique attribute lookup.
3. Functional Verification:
   - Define a new patron attribute type with 'unique_id' set to 1.
   - Assign a value to a patron for this attribute.
   - Use a tool (like the SIP2 emulator) that utilizes Koha::Patrons->find_by_identifier
     to search for the patron using this attribute value. e.g.,
     perl misc/sip_cli_emulator.pl -su term1 -sp term1 -l CPL --host localhost --patron altid123 -m patron_information
   - Verify the patron is found.
   - Try with a non-unique attribute (unique_id=0) and verify the patron is NOT found.
Comment 2 Saiful Amin 2026-03-04 10:51:24 UTC
Created attachment 194439 [details] [review]
Bug 41383 - SIP2 server does not search patrons by unique patron attributes (alternate IDs unusable in SIP2)

Currently, Koha::Patrons->find_by_identifier only searches for patrons by userid and cardnumber.

This patch extends this method to also search by unique borrower attributes (where unique_id=1).
This enhancement allows modules like SIP2 to identify patrons using alternative unique identifiers
defined in the system.

Test Plan:
1. Test current behaviour:
   - Go to Administration -> Patron attribute types
   - Create a new Patron attribute with:
      - Patron attribute type code = "AltID"
      - Description = "Alternate ID"
      - Unique identifier checkbox selected
      - Save
   - Edit any patron record and go to Additional attributes and identifiers
      - Add a value "altid123" to "Alternate ID"
      - Save
   - Use any SIP2 client to search for the patron using this attribute value. e.g.,
     `perl misc/sip_cli_emulator.pl -su term1 -sp term1 -l CPL --host localhost --patron altid123 -m patron_information`
   - Verify that the patron is NOT found with this message:
     'AFInvalid cardnumber'
     e.g.:
     READ: 64YYYY          00120260304    104611000000000000000000000000AOCPL|AAaltid123|AE|BLN|AFInvalid cardnumber|

2. Apply the patch.

3. Run the tests:
   prove t/db_dependent/Koha/Patrons.t
   - Verify that all tests pass, including the new cases for unique attribute lookup.

4. Test with patch applied:
   - Use any SIP2 client to search for the patron using this attribute value. e.g.,
     `perl misc/sip_cli_emulator.pl -su term1 -sp term1 -l CPL --host localhost --patron altid123 -m patron_information`
   - Verify that the patron is found with this message:
     'AFGreetings from Koha.'
     e.g.:
     READ: 64              00120260304    104328000000000000000000000000AOCPL|AA23529001000463|AEEdna Acosta|BLY|BHUSD|BV0|CC5|BD7896 Library Rd. Portland, OR 44240|BF(212) 555-1212|PB19800424|PCPT|PIY|AFGreetings from Koha. |

5. Test non-unique attribute:
   - Go to Administration -> Patron attribute types
   - Edit "Alternate ID" attribute type
      - Unique identifier checkbox NOT selected
      - Save
   - Use any SIP2 client to search for the patron using this attribute value. e.g.,
     `perl misc/sip_cli_emulator.pl -su term1 -sp term1 -l CPL --host localhost --patron altid123 -m patron_information`
   - Verify that the patron is NOT found with this message:
     'AFInvalid cardnumber'
     e.g.:
     READ: 64YYYY          00120260304    104611000000000000000000000000AOCPL|AAaltid123|AE|BLN|AFInvalid cardnumber|

6. Sign-off
Comment 3 Faheemuddin Syed 2026-03-05 11:51:48 UTC
Created attachment 194497 [details] [review]
Bug 41383 - SIP2 server does not search patrons by unique patron attributes (alternate IDs unusable in SIP2)

Currently, Koha::Patrons->find_by_identifier only searches for patrons by userid and cardnumber.

This patch extends this method to also search by unique borrower attributes (where unique_id=1).
This enhancement allows modules like SIP2 to identify patrons using alternative unique identifiers
defined in the system.

Test Plan:
1. Test current behaviour:
   - Go to Administration -> Patron attribute types
   - Create a new Patron attribute with:
      - Patron attribute type code = "AltID"
      - Description = "Alternate ID"
      - Unique identifier checkbox selected
      - Save
   - Edit any patron record and go to Additional attributes and identifiers
      - Add a value "altid123" to "Alternate ID"
      - Save
   - Use any SIP2 client to search for the patron using this attribute value. e.g.,
     `perl misc/sip_cli_emulator.pl -su term1 -sp term1 -l CPL --host localhost --patron altid123 -m patron_information`
   - Verify that the patron is NOT found with this message:
     'AFInvalid cardnumber'
     e.g.:
     READ: 64YYYY          00120260304    104611000000000000000000000000AOCPL|AAaltid123|AE|BLN|AFInvalid cardnumber|

2. Apply the patch.

3. Run the tests:
   prove t/db_dependent/Koha/Patrons.t
   - Verify that all tests pass, including the new cases for unique attribute lookup.

4. Test with patch applied:
   - Use any SIP2 client to search for the patron using this attribute value. e.g.,
     `perl misc/sip_cli_emulator.pl -su term1 -sp term1 -l CPL --host localhost --patron altid123 -m patron_information`
   - Verify that the patron is found with this message:
     'AFGreetings from Koha.'
     e.g.:
     READ: 64              00120260304    104328000000000000000000000000AOCPL|AA23529001000463|AEEdna Acosta|BLY|BHUSD|BV0|CC5|BD7896 Library Rd. Portland, OR 44240|BF(212) 555-1212|PB19800424|PCPT|PIY|AFGreetings from Koha. |

5. Test non-unique attribute:
   - Go to Administration -> Patron attribute types
   - Edit "Alternate ID" attribute type
      - Unique identifier checkbox NOT selected
      - Save
   - Use any SIP2 client to search for the patron using this attribute value. e.g.,
     `perl misc/sip_cli_emulator.pl -su term1 -sp term1 -l CPL --host localhost --patron altid123 -m patron_information`
   - Verify that the patron is NOT found with this message:
     'AFInvalid cardnumber'
     e.g.:
     READ: 64YYYY          00120260304    104611000000000000000000000000AOCPL|AAaltid123|AE|BLN|AFInvalid cardnumber|

6. Sign-off

Signed-off-by: Syed Faheemuddin <faheem@nexuslib.com>
Comment 4 Faheemuddin Syed 2026-03-05 11:53:27 UTC
> 
> 2. Apply the patch.
>

Just a note here: The SIP2 services need to be restarted for the patch to take effect.
Comment 5 Martin Renvoize (ashimema) 2026-03-07 06:18:15 UTC
Created attachment 194930 [details] [review]
Bug 41383: SIP2 server does not search patrons by unique patron attributes (alternate IDs unusable in SIP2)

Currently, Koha::Patrons->find_by_identifier only searches for patrons by userid and cardnumber.

This patch extends this method to also search by unique borrower attributes (where unique_id=1).
This enhancement allows modules like SIP2 to identify patrons using alternative unique identifiers
defined in the system.

Test Plan:
1. Test current behaviour:
   - Go to Administration -> Patron attribute types
   - Create a new Patron attribute with:
      - Patron attribute type code = "AltID"
      - Description = "Alternate ID"
      - Unique identifier checkbox selected
      - Save
   - Edit any patron record and go to Additional attributes and identifiers
      - Add a value "altid123" to "Alternate ID"
      - Save
   - Use any SIP2 client to search for the patron using this attribute value. e.g.,
     `perl misc/sip_cli_emulator.pl -su term1 -sp term1 -l CPL --host localhost --patron altid123 -m patron_information`
   - Verify that the patron is NOT found with this message:
     'AFInvalid cardnumber'
     e.g.:
     READ: 64YYYY          00120260304    104611000000000000000000000000AOCPL|AAaltid123|AE|BLN|AFInvalid cardnumber|

2. Apply the patch.

3. Run the tests:
   prove t/db_dependent/Koha/Patrons.t
   - Verify that all tests pass, including the new cases for unique attribute lookup.

4. Test with patch applied:
   - Use any SIP2 client to search for the patron using this attribute value. e.g.,
     `perl misc/sip_cli_emulator.pl -su term1 -sp term1 -l CPL --host localhost --patron altid123 -m patron_information`
   - Verify that the patron is found with this message:
     'AFGreetings from Koha.'
     e.g.:
     READ: 64              00120260304    104328000000000000000000000000AOCPL|AA23529001000463|AEEdna Acosta|BLY|BHUSD|BV0|CC5|BD7896 Library Rd. Portland, OR 44240|BF(212) 555-1212|PB19800424|PCPT|PIY|AFGreetings from Koha. |

5. Test non-unique attribute:
   - Go to Administration -> Patron attribute types
   - Edit "Alternate ID" attribute type
      - Unique identifier checkbox NOT selected
      - Save
   - Use any SIP2 client to search for the patron using this attribute value. e.g.,
     `perl misc/sip_cli_emulator.pl -su term1 -sp term1 -l CPL --host localhost --patron altid123 -m patron_information`
   - Verify that the patron is NOT found with this message:
     'AFInvalid cardnumber'
     e.g.:
     READ: 64YYYY          00120260304    104611000000000000000000000000AOCPL|AAaltid123|AE|BLN|AFInvalid cardnumber|

6. Sign-off

Signed-off-by: Syed Faheemuddin <faheem@nexuslib.com>
Signed-off-by: Martin Renvoize <martin.renvoize@openfifth.co.uk>