Bug 20253

Summary: Optionally use buyer's purchase order number from EDIFACT quote in basket name
Product: Koha Reporter: Colin Campbell <colin.campbell>
Component: AcquisitionsAssignee: Martin Renvoize (ashimema) <martin.renvoize>
Status: Needs Signoff --- QA Contact: Kyle M Hall (khall) <kyle>
Severity: enhancement    
Priority: P5 - low CC: aude.charillon, hdunne-howrie, jeremy.evans, martin.renvoize
Version: Main   
Hardware: All   
OS: All   
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: 40383    
Attachments: Bug 20253: Add tests for RFF+ON segment handling and basket naming
Bug 20253: Add basket_name_source field to vendor_edi_accounts table
Bug 20253: Optionally use buyer's purchase order number from EDIFACT quote in basket name
Bug 20253: (follow-up) Add RFF+ON segments to outgoing ORDER messages
Bug 20253: Add tests for RFF+ON segment handling and basket naming
Bug 20253: Add basket_name_source field to vendor_edi_accounts table
Bug 20253: Optionally use buyer's purchase order number from EDIFACT quote in basket name
Bug 20253: (follow-up) Add RFF+ON segments to outgoing ORDER messages
Bug 20253: (follow-up) Remove warnings from EDI when running tests
Bug 20253: DBIC Schema
Bug 20253: Remove warnings from EDI when running tests
Bug 20253: Add tests for RFF+ON segment handling and basket naming
Bug 20253: Add po_is_basketname field to vendor_edi_accounts table
Bug 20253: DBIC Schema
Bug 20253: Optionally use buyer's purchase order number from EDIFACT quote as basket name
Bug 20253: (follow-up) Add duplicate purchase order number validation
Bug 20253: (follow-up) Make basket name read-only when derived from EDI purchase order number
Bug 20253: (follow-up) Use purchase order number in BGM segment for outgoing ORDER messages
Bug 20253: Add tests for RFF+ON segment handling and basket naming
Bug 20253: Add po_is_basketname field to vendor_edi_accounts table
Bug 20253: DBIC Schema
Bug 20253: Optionally use buyer's purchase order number from EDIFACT quote as basket name
Bug 20253: (follow-up) Add duplicate purchase order number validation
Bug 20253: (follow-up) Make basket name read-only when derived from EDI purchase order number
Bug 20253: (follow-up) Use purchase order number in BGM segment for outgoing ORDER messages
Bug 20253: (follow-up) Block auto_orders and UI ordering for duplicate PO numbers

Description Colin Campbell 2018-02-20 14:10:13 UTC
Current default behaviour is to use the filename of the QUOTE in the basketname. 
This would instead use the buyer's purchase order number (segment RFF with a qualifier ON) instead so that this would be searchable.

This should be optional as even when supplied many (most) sites do not have meaningful or distinctive data in the field (e.g. 'Books for branch X'). Logical is to add it as a vendor option
Comment 1 Jeremy Evans 2021-09-27 08:13:17 UTC
We would support this. We have recently started using EDI and one of the issues is not being able to see the basket name from the vendor in Koha.
We enter a basket name on the vendor site based on site/date etc so we can tell from the basket name which site the order was placed for and the date. The quote in Koha only shows the file name. When we confirm the order, the actual order sent back to the vendor uses the Koha OrderID as the basket name. So we end up with 3 different references depending if it is a quote or order and whether you look in the vendor system or Koha so not easy to cross-check between the vendor and Koha.

Ideally we would want to retain the vendor basketID in the Quote seen in Koha (or at least be able to see/search sort by this).
It would also be useful to be able to use this as the basis for the orderID sent back to the vendor though it needs to be unique so would need koha to add some suffix to the order & quote don't have exactly the same refence on the vendor system
Comment 2 Hannah Dunne-Howrie 2025-05-20 13:20:57 UTC
We also support this and would like to see this happen to automate the process and allow file names to be used for different purposes. 

Although, ideally, we'd want to see the order reference added in as the basket ID as opposed to the basket name.
Comment 3 Martin Renvoize (ashimema) 2025-07-08 14:30:50 UTC Comment hidden (obsolete)
Comment 4 Martin Renvoize (ashimema) 2025-07-08 14:30:52 UTC Comment hidden (obsolete)
Comment 5 Martin Renvoize (ashimema) 2025-07-08 14:30:54 UTC Comment hidden (obsolete)
Comment 6 Martin Renvoize (ashimema) 2025-07-08 14:30:56 UTC Comment hidden (obsolete)
Comment 7 Martin Renvoize (ashimema) 2025-07-10 17:11:35 UTC Comment hidden (obsolete)
Comment 8 Martin Renvoize (ashimema) 2025-07-10 17:11:37 UTC Comment hidden (obsolete)
Comment 9 Martin Renvoize (ashimema) 2025-07-10 17:11:39 UTC Comment hidden (obsolete)
Comment 10 Martin Renvoize (ashimema) 2025-07-10 17:11:41 UTC Comment hidden (obsolete)
Comment 11 Martin Renvoize (ashimema) 2025-07-10 17:11:43 UTC Comment hidden (obsolete)
Comment 12 Martin Renvoize (ashimema) 2025-07-10 17:11:45 UTC Comment hidden (obsolete)
Comment 13 Martin Renvoize (ashimema) 2025-07-11 15:36:13 UTC Comment hidden (obsolete)
Comment 14 Martin Renvoize (ashimema) 2025-07-11 15:36:16 UTC
Created attachment 184001 [details] [review]
Bug 20253: Add tests for RFF+ON segment handling and basket naming

This patch adds tests for:
1. RFF+ON (Purchase Order Number) segment parsing in EDIFACT messages
2. Vendor configuration for basket naming preferences
3. Basket naming logic in QUOTE processing

Test coverage includes:
- Message-level RFF+ON segment extraction
- Validation that RFF+ON processing stops at LIN segments
- Multiple RFF segment handling
- Database field storage and constraints
- Basket naming configuration logic
- Fallback behavior when purchase order number unavailable
Comment 15 Martin Renvoize (ashimema) 2025-07-11 15:36:18 UTC
Created attachment 184002 [details] [review]
Bug 20253: Add po_is_basketname field to vendor_edi_accounts table

This patch adds a new boolean field 'po_is_basketname' to the vendor_edi_accounts
table to allow configuration of how basket names are used in EDIFACT.

Changes:
- Added atomicupdate for existing installations
- Updated kohastructure.sql for new installations
Comment 16 Martin Renvoize (ashimema) 2025-07-11 15:36:20 UTC Comment hidden (obsolete)
Comment 17 Martin Renvoize (ashimema) 2025-07-11 15:36:22 UTC
Created attachment 184004 [details] [review]
Bug 20253: Optionally use buyer's purchase order number from EDIFACT quote as basket name

This enhancement allows libraries to configure vendors to use the buyer's
purchase order number (from RFF+ON segments) as the basket name instead of
the EDIFACT filename, improving searchability and reference tracking.

Backend Changes:
- Added purchase_order_number() method to Koha::Edifact::Message to extract
  RFF+ON segments from message-level data (before first LIN segment)
- Modified process_quote() in Koha::EDI to use purchase order number for
  basket naming when configured, with fallback to filename

Frontend Changes:
- Updated admin/edi_accounts.pl to handle po_is_basketname parameter
- Added "Use purhase order numbers" option to EDI accounts template

Test Plan:
1. Apply patches and run database update
2. Go to Administration > Acquisitions > EDI accounts
3. Create or edit a vendor EDI account
4. Verify "Use purchase order numbers" option appears
5. Enable "Use purchase order numbers" and save
6. Process an EDIFACT quote file that contains RFF+ON segments
7. Verify the created basket name uses the purchase order number instead of filename
8. Process a quote file without RFF+ON segments
9. Verify the basket name falls back to the filename
10. Test with "Use purchase order numbers" disabled
11. Verify basket names use filenames regardless of RFF+ON presence
12. Run tests: prove t/Edifact.t t/db_dependent/Koha/EDI.t

The feature is optional and backward compatible - existing behavior is
unchanged unless explicitly configured.
Comment 18 Martin Renvoize (ashimema) 2025-07-11 15:36:24 UTC
Created attachment 184005 [details] [review]
Bug 20253: (follow-up) Add duplicate purchase order number validation

When processing EDI quotes with purchase order numbers, validate that the
purchase order number is unique for the vendor to prevent operational
confusion. The validation:

- Checks for existing baskets with the same purchase order number and vendor
- Includes both open and closed baskets in the uniqueness check
- Logs an error with the raw RFF+ON segment and details to the edifact_errors table
- Continues processing (non-blocking) to prevent data loss
- Provides system log warnings for monitoring

The error logging includes:
- Section: Raw RFF+ON segment (e.g., "RFF+ON:orders 23/1")
- Details: Clear description of the duplicate purchase order number issue

This ensures administrators can identify and resolve duplicate purchase order
numbers while maintaining system functionality and audit trails.
Comment 19 Martin Renvoize (ashimema) 2025-07-11 15:36:26 UTC
Created attachment 184006 [details] [review]
Bug 20253: (follow-up) Make basket name read-only when derived from EDI purchase order number

When a basket is created from an EDI quote with the vendor EDI account configured
to use purchase order numbers, the basket name should be protected from changes
to maintain the integrity of the purchase order number reference.

This patch:
- Makes the basket name field read-only in the UI when the basket was created
  from EDI with purchase order number setting
- Adds explanatory text when the field is protected
- Implements server-side protection to prevent basket name changes even if
  the UI is bypassed
- Preserves the original purchase order number derived name
Comment 20 Martin Renvoize (ashimema) 2025-07-11 15:36:28 UTC
Created attachment 184007 [details] [review]
Bug 20253: (follow-up) Use purchase order number in BGM segment for outgoing ORDER messages

When vendors are configured to use purchase order numbers for basket naming,
the purchase order number should be included in outgoing ORDER messages as
the document message number in the BGM segment for proper EDI workflow continuity.

According to EDIFACT specifications, the purchase order number from incoming
quote messages (RFF+ON segments) should be used as the document message number
in the BGM segment of outgoing ORDER messages, rather than as a separate RFF+ON
segment.

This follow-up ensures that:
1. Purchase order numbers from incoming QUOTE messages are preserved
2. The same purchase order numbers are sent back in ORDER messages via BGM segment
3. Vendors receive the reference numbers they expect for order processing in the
   correct format.

Implementation:
- Added get_purchase_order_number() method to extract PO number from basket name
  when vendor is configured with 'po_is_basketname'
- Modified beginning_of_message() to accept purchase order number parameter
- Uses purchase order number in BGM segment when available, falls back to basketno
- Added comprehensive tests for purchase order number handling in ORDER messages

Test Plan:
1. Apply patches
2. Configure a vendor EDI account with "Basket name source" = "Purchase order number"
3. Process a QUOTE message containing RFF+ON segment
4. Verify basket is created with purchase order number as name
5. Generate ORDER message from the basket
6. Verify ORDER message contains purchase order number in BGM segment
7. Run tests: prove t/db_dependent/Koha/Edifact/Order.t

This completes the round-trip EDI workflow for purchase order number handling
according to EDIFACT standards: Quote RFF+ON → Basket Name → Order BGM
Comment 21 Martin Renvoize (ashimema) 2025-08-07 15:27:13 UTC Comment hidden (obsolete)
Comment 22 Martin Renvoize (ashimema) 2025-08-07 15:27:16 UTC Comment hidden (obsolete)
Comment 23 Martin Renvoize (ashimema) 2025-08-07 15:27:18 UTC Comment hidden (obsolete)
Comment 24 Martin Renvoize (ashimema) 2025-08-07 15:27:21 UTC Comment hidden (obsolete)
Comment 25 Martin Renvoize (ashimema) 2025-08-07 15:27:23 UTC Comment hidden (obsolete)
Comment 26 Martin Renvoize (ashimema) 2025-08-07 15:27:26 UTC Comment hidden (obsolete)
Comment 27 Martin Renvoize (ashimema) 2025-08-07 15:27:28 UTC Comment hidden (obsolete)
Comment 28 Martin Renvoize (ashimema) 2025-08-07 15:27:31 UTC
Created attachment 185228 [details] [review]
Bug 20253: (follow-up) Block auto_orders and UI ordering for duplicate PO numbers

When po_is_basketname is enabled for a vendor, duplicate purchase order
numbers should prevent both automatic ordering (auto_orders) and manual
UI-triggered ordering to avoid conflicts with existing baskets.

This patch implements blocking functionality that:

1. Auto-orders blocking:
   - Tracks baskets with PO number conflicts during quote processing
   - Skips auto-ordering for baskets with duplicate PO numbers
   - Logs clear warnings about blocked baskets

2. UI basket ordering blocking:
   - Adds duplicate checking in create_edi_order function
   - Returns detailed error information when conflicts detected
   - Prevents EDI order creation for conflicting baskets

3. User-friendly error handling:
   - Updates basket.pl to handle duplicate PO number errors
   - Stays on basket page to display error messages
   - Provides clear messaging about conflicts and resolution steps

4. Template messaging:
   - Adds clear error message explaining duplicate PO conflicts
   - Shows which existing basket uses the same PO number
   - Guides users on next steps to resolve the issue

This ensures data integrity and prevents order processing conflicts
while providing clear feedback to users about duplicate PO number
issues.

Test plan:
1. Set up a vendor with EDI account and enable "po_is_basketname"
2. Create a basket with a specific name (e.g., "PO12345")
3. Process an EDIFACT quote that contains the same PO number:
   - If auto_orders is enabled: verify the new basket is created but NOT automatically ordered
   - Check the logs show "Auto-order blocked" message
4. For UI testing, create another basket manually with the same name
5. Try to generate EDI order via "Generate EDI order" button
6. Verify: Error message appears stating duplicate PO number conflict
7. Verify: Basket remains open (not closed)
8. Verify: Error message shows which existing basket uses the PO number
9. Test with po_is_basketname disabled: verify normal operation continues
10. Test with unique PO numbers: verify orders process normally