In this article
Item Variants Functions codeunit events
OnBeforeConvertSalesLineToCollectionHeader
OnBeforeConvertPurchLineToCollectionHeader
The Variant Framework publishes a number of integration events so that a partner extension can hook into the purchase and sales order flow described in Working with Variants in Order Documents, instead of modifying the Variant Framework code directly. This article describes the events that are available for extending that flow.
From version 28.2
Item Variants Functions codeunit events
The following events are published by the codeunit LSC Item Variants Functions, which implements the Variant Framework's Dimension Matrix logic for purchase and sales order lines.
OnBeforeInsertPurchLine
Fires immediately before the Variant Framework inserts a new purchase line for a variant, while it is building the document lines that represent the quantities you entered for each variant in the Dimension Matrix.
[EventSubscriber(ObjectType::Codeunit, Codeunit::"LSC Item Variants Functions", 'OnBeforeInsertPurchLine', '', false, false)]
local procedure OnBeforeInsertPurchLine(var PurchaseLine: Record "Purchase Line"; pBaseRec: Record "Purchase Line")
begin
end;Parameters:
- PurchaseLine (var) – the new variant line that the Variant Framework is about to insert. All of its fields, including Quantity, are already populated. Change field values here if your extension needs the line to be inserted differently.
- pBaseRec – the collection header line that the new variant line belongs to. It is provided for context only and is not modifiable through this event.
IsHandled: Not available on this event. A subscriber can change field values on PurchaseLine before it is inserted, but cannot prevent the insert itself.
OnBeforeConvertSalesLineToCollectionHeader
Fires when a user first works with an item's variants through the Dimension Matrix on a sales document, immediately before the Variant Framework converts the ordinary sales line you started from into a collection header line.
[EventSubscriber(ObjectType::Codeunit, Codeunit::"LSC Item Variants Functions", 'OnBeforeConvertSalesLineToCollectionHeader', '', false, false)]
local procedure OnBeforeConvertSalesLineToCollectionHeader(var BaseRec: Record "Sales Line"; var IsHandled: Boolean)
begin
end;Parameters:
- BaseRec (var) – the sales line that is about to be converted into a collection header line.
- IsHandled (var) – set to true to take over the conversion yourself. See the warning below.
IsHandled: Setting it to true skips the Variant Framework's own conversion step entirely, so your subscriber becomes fully responsible for converting the line.
Warning: The Variant Framework's own conversion clears the line's Quantity, clears its Type, copies the original item number into the line's collection-item reference (the internal field that links the base line to its variant lines), clears the line's No. field, and saves the line.
If your subscriber sets IsHandled to true without reproducing all of this, the collection-item reference is never set. The next time the Variant Framework looks for existing variant lines under this base line it finds none, so it inserts new variant lines alongside a base line that still behaves like an ordinary item line – duplicating quantity on the document. If you handle this event, reproduce the full conversion, or call the equivalent logic yourself, before returning.
OnBeforeConvertPurchLineToCollectionHeader
The purchase order equivalent of OnBeforeConvertSalesLineToCollectionHeader. Fires when a user first works with an item's variants through the Dimension Matrix on a purchase document, immediately before the Variant Framework converts the ordinary purchase line you started from into a collection header line.
[EventSubscriber(ObjectType::Codeunit, Codeunit::"LSC Item Variants Functions", 'OnBeforeConvertPurchLineToCollectionHeader', '', false, false)]
local procedure OnBeforeConvertPurchLineToCollectionHeader(var BaseRec: Record "Purchase Line"; var IsHandled: Boolean)
begin
end;Parameters:
- BaseRec (var) – the purchase line that is about to be converted into a collection header line.
- IsHandled (var) – set to true to take over the conversion yourself. See the warning below.
IsHandled: Setting it to true skips the Variant Framework's own conversion step entirely, so your subscriber becomes fully responsible for converting the line.
Warning: The Variant Framework's own conversion clears the line's Quantity, clears its Type, copies the original item number into the line's collection-item reference (the internal field that links the base line to its variant lines), clears the line's No. field, and saves the line. If your subscriber sets IsHandled to true without reproducing all of this, the collection-item reference is never set.
- The next time the Variant Framework looks for existing variant lines under this base line it finds none, so it inserts new variant lines alongside a base line that still behaves like an ordinary item line – duplicating quantity on the document.
- If you handle this event, reproduce the full conversion, or call the equivalent logic yourself, before returning.
Retail PO Subpage page events
The following event is published by the Retail PO Subpage, which is the purchase order lines page used together with the Variant Framework.
OnBeforeValidateQty
Fires in the OnValidate trigger of the quantity field on the Retail PO Subpage, whenever a user enters a quantity on an ordinary purchase order item line. It does not fire for a collection header line.
[EventSubscriber(ObjectType::Page, Page::"LSC Retail PO Subpage", 'OnBeforeValidateQty', '', false, false)]
local procedure OnBeforeValidateQty(var Rec: Record "Purchase Line"; Xquantity: Decimal; var IsHandled: Boolean)
begin
end;Parameters:
- Rec (var) – the purchase line being edited.
- Xquantity – the quantity value that was entered on the page. It is not passed by reference, so a subscriber cannot change what value the standard trigger logic sees.
- IsHandled (var) – set to true to skip the standard quantity validation. See below.
IsHandled: Setting it to true skips only the call that validates Quantity against Xquantity using standard Business Central validation. The rest of the trigger still runs afterward. Use this when your extension needs to assign the quantity without triggering standard validation, for example by setting Rec.Quantity := Xquantity; directly, and then applying its own logic.
See also
Working with Variants in Order Documents