Bug 40219

Summary: Welcome Email Sent on Failed Patron Registration via API
Product: Koha Reporter: Leo Stoyanov <leo.stoyanov>
Component: REST APIAssignee: Leo Stoyanov <leo.stoyanov>
Status: Failed QA --- QA Contact: Pedro Amorim <pedro.amorim>
Severity: minor    
Priority: P5 - low CC: andrew, george, pedro.amorim, tomascohen
Version: Main   
Hardware: All   
OS: All   
See Also: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=35635
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=40420
GIT URL: Change sponsored?: ---
Patch complexity: --- Documentation contact:
Documentation submission: Text to go in the release notes:
Version(s) released in:
Circulation function:
Bug Depends on:    
Bug Blocks: 40220    
Attachments: Bug 40219: Moved Extended Attributes Validation Before Enqueuing Welcome Email
Bug 40219: Moved Extended Attributes Validation Before Enqueuing Welcome Email

Description Leo Stoyanov 2025-06-23 14:19:09 UTC
When registering a new patron via the /api/v1/patrons API endpoint, a welcome email notice is sent even if the endpoint returns a 400 error due to validation failures. This occurs because the welcome email logic executes before extended attribute validation is complete, within the database transaction.
Comment 1 Leo Stoyanov 2025-06-23 15:40:38 UTC
Created attachment 183421 [details] [review]
Bug 40219: Moved Extended Attributes Validation Before Enqueuing Welcome Email

Test Plan:
1. Configure Koha with: AutoEmailNewUser = "Send" and create a mandatory extended attribute that will cause validation to fail; for example, set for the attribute to display in the OPAC, to be editable in the OPAC, and to be mandatory. That means this bug must be tested before Bug 40220, where the validation failure is resolved.
2. Setup your Postman, or any other mock API software, to obtain an OAuth token (/api/v1/oauth/token) and to register a patron (/api/v1/patrons).
3. With the OAuth token, send a POST request to /api/v1/patrons with valid patron data and invalid or missing mandatory extended attribute data.
4. Observe the API response with the 400 error and notice that the welcome email was delviered despite the fact that no patron account was created.
5. Apply the patch and repeat step 3. Notice that the API response still contains the 400 error, but no welcome email was sent.
Comment 2 Andrew Fuerste-Henry 2025-07-16 17:26:59 UTC
Some testing complications to note here:

The Add Patron API call has a header option to tell it not to generate a welcome notice at all. If you've imported the Koha API into Postman and its generated default content for the body of your calls, it may have set this header by default. Learn from my mistakes :)

bug 35635 splits patron attribute mandatory-ness for staff/opac into two values. the API follows the staff mandatory values, so set your attribute to mandatory for the staff interface when testing this.

Because the message_queue has a foreign key constraint to borrowers, if your registration fails the notice will not save in the message_queue. That makes it hard to confirm that it's generated if you're on a test system that doesn't actually send email.

How to get KTD to send email:
https://gitlab.com/-/snippets/1893788#enabling-email-for-testing

If you don't set your system up to send email, you can still see that the message_queue.message_id increments up for the WELCOME notice for the failed patron.

Revised test plan:
1: set AutoEmailNewUser = "Send", confirm you have a WELCOME notice defined
2: create a patron attribute, check "Staff interface mandatory"
3: (optional but recommended) set up your test system up to send email via SMTP following directions linked above
4: use Postman or similar to add a patron successfully -- send all required borrower fields, an email address, and your required attribute
5: confirm you get a success message in Postman and your patron exists in koha
6: run report "select * from message_queue" and see your patron's WELCOME email
7: if you set up outgoing mail, confirm you received the WELCOME email
8: use Postman or similar to fail to add a patron -- send all required borrower fields, an email address, and NOT your required attribute
9: confirm you get a failure message about a missing attribute in Postman and your patron does not exist in Koha
10: run report "select * from message_queue" and see no change
11: if you set up outgoing mail, confirm you have just received a welcome email for your patron who did NOT successfully register
12: repeat steps 4-6 -- successfully make a patron via API and re-run your report. note that there are now 2 WELCOME emails in the message_queue and their message_ids are non-sequential. They skip a number for the notice generated for your failed patron
Comment 3 Andrew Fuerste-Henry 2025-07-16 17:53:55 UTC
I left out the part where you actually confirm the fix!

Revised revised test plan:
1: set AutoEmailNewUser = "Send", confirm you have a WELCOME notice defined
2: create a patron attribute, check "Staff interface mandatory"
3: (optional but recommended) set up your test system up to send email via SMTP following directions linked above
4: use Postman or similar to add a patron successfully -- send all required borrower fields, an email address, and your required attribute
5: confirm you get a success message in Postman and your patron exists in koha
6: run report "select * from message_queue" and see your patron's WELCOME email
7: if you set up outgoing mail, confirm you received the WELCOME email
8: use Postman or similar to fail to add a patron -- send all required borrower fields, an email address, and NOT your required attribute
9: confirm you get a failure message about a missing attribute in Postman and your patron does not exist in Koha
10: run report "select * from message_queue" and see no change
11: if you set up outgoing mail, confirm you have just received a welcome email for your patron who did NOT successfully register
12: repeat steps 4-6 -- successfully make a patron via API and re-run your report. note that there are now 2 WELCOME emails in the message_queue and their message_ids are non-sequential. They skip a number for the notice generated for your failed patron

13: apply patch, restart services

14: use Postman or similar to fail to add a patron -- send all required borrower fields, an email address, and NOT your required attribute
15: confirm you get a failure from postman about your missing attribute
16: confirm you didn't get an email and nothign new is in the message_queue
17: use Postman or similar to add a patron successfully -- send all required borrower fields, an email address, and your required attribute
18: confirm you get a welcome email, you see that welcome email in the message_queue, and the message_id is sequential from your last successful patron add
Comment 4 Andrew Fuerste-Henry 2025-07-16 19:58:58 UTC
Created attachment 184171 [details] [review]
Bug 40219: Moved Extended Attributes Validation Before Enqueuing Welcome Email

Test Plan:
1. Configure Koha with: AutoEmailNewUser = "Send" and create a mandatory extended attribute that will cause validation to fail; for example, set for the attribute to display in the OPAC, to be editable in the OPAC, and to be mandatory. That means this bug must be tested before Bug 40220, where the validation failure is resolved.
2. Setup your Postman, or any other mock API software, to obtain an OAuth token (/api/v1/oauth/token) and to register a patron (/api/v1/patrons).
3. With the OAuth token, send a POST request to /api/v1/patrons with valid patron data and invalid or missing mandatory extended attribute data.
4. Observe the API response with the 400 error and notice that the welcome email was delviered despite the fact that no patron account was created.
5. Apply the patch and repeat step 3. Notice that the API response still contains the 400 error, but no welcome email was sent.

Signed-off-by: Christopher Brannon <cbrannon@cdalibrary.org>
Comment 5 Pedro Amorim 2025-08-05 14:23:31 UTC
We need tests here, guys.