Slice 622414: [SOA] [Pioneer] Enhancing Sales Order Agent with Item Variant : availability and prices

[tomasevicst]

What & why

This PR adds end-to-end Item Variant support to the Sales Order Agent. The agent can now resolve a customer request to a specific item and variant, use that variant when checking availability and calculating prices, and carry the resolved Variant Code through to the sales quote or order.

Previously, item search operated primarily at the item level. Exact item matches could bypass the Item Selector, variant intent expressed in natural language could be lost, and availability checks could fall back to the unqualified item. This could produce quote lines with an empty or incorrect Variant Code.

The updated flow:

• Runs Item Selector consistently for exact, standard, and broader search results.
• Includes known item variants and relevant same-item message context during selection.
• Returns an optional variant_code together with an explicit variant_match classification.
• Validates returned items and item-variant combinations against the original candidate set.
• Allows concrete alternatives for interchangeable differences such as color, finish, or pattern.
• Prevents substitutions for suitability-changing differences such as size, fit, compatibility, capacity, or technical specification.
• Treats a valid empty selection as an authoritative result and does not fall back to the original candidates.
• Distinguishes valid empty decisions from selector or response-parsing failures.
• Checks availability for matching item-variant combinations before considering concrete alternatives.
• Uses the resolved variant for availability, pricing, shipment date, translations, and quote or order creation.
• Leaves Variant Code empty when no variant was requested.
• Emits non-sensitive telemetry for selector failures and rejected item or variant results.
• Adds ten active scenarios covering explicit, implicit, broad, missing, unavailable, prohibited-substitution, and multi-item variant requests.

The availability page remains item-based. When the requested variant is unavailable and the selector returns multiple safe, interchangeable alternatives, the initial implementation presents the first available concrete alternative for that item. It does not silently substitute the variant or create a quote until the customer confirms the alternative.

The mandatory-variant-without-request scenario remains deferred because Variant Mandatory if Exists is not currently included in the Item Selector candidate metadata.

Linked work

Fixes AB#622414

How I validated this

• I read the full diff and it contains only changes I intended.
• I built the affected app(s) locally with no new analyzer warnings.
• I ran the change in Business Central and confirmed it behaves as expected.
• I added or updated tests for the new behavior, or explained below why none are needed.

What I tested and the outcome

Validation executed

• Full multi-project AL build with CodeCop enabled: Passed with no errors or warnings.
• Item Selector tool schema parsed with ConvertFrom-Json: Passed.
  • selected_items is the sole required top-level result field.
  • unresolved_variant_requests is not present.
• Focused diagnostics for the changed AL and prompt files: No errors found.

Accuracy coverage prepared

The following ten active scenarios are defined in SOA-QUOTE_ITEMS_HANDLING_VARIANTS.yaml:

• QUOTE_5_ITEMS_VARIANTS_01: Explicit variant codes resolve to the expected quote-line Variant Codes.
• QUOTE_5_ITEMS_VARIANTS_02: Variants expressed within natural-language item descriptions resolve correctly.
• QUOTE_3_ITEMS_VARIANTS_03: Synonyms and broad wording, such as “any color,” resolve to suitable variants.
• QUOTE_3_ITEMS_VARIANTS_04: Items without a requested variant retain an empty Variant Code.
• QUOTE_1_ITEM_VARIANT_ALTERNATIVE_05: A missing interchangeable color offers one available same-item variant and does not create a quote before confirmation.
• QUOTE_1_ITEM_VARIANT_ALTERNATIVE_06: An existing but unavailable shoe size does not cause available sizes 42 or 46 to be offered.
• QUOTE_1_ITEM_VARIANT_ALTERNATIVE_07: A non-existent shoe size produces no unsafe size substitution and no quote.
• QUOTE_1_ITEM_VARIANT_ALTERNATIVE_08: An explicit prohibition against color substitution is honored and no quote is created.
• QUOTE_1_ITEM_VARIANT_ALTERNATIVE_10: An unavailable requested color can offer available same-item colors, but no quote is created before confirmation.
• QUOTE_2_ITEMS_VARIANT_CONTEXT_ISOLATION_11: Variant intent for one requested item does not leak to another item in the same request.

QUOTE_1_ITEM_VARIANT_ALTERNATIVE_09, covering an item where a variant is mandatory but none was requested, remains deferred. Variant Mandatory if Exists is not currently included in the Item Selector candidate metadata, so this behavior cannot yet be enforced reliably.

UI verification

The Variant Code field is now visible on the Sales Quote and Sales Order subforms used by the agent.

Risk & compatibility

Risk level: Medium. The change affects item search, variant selection, availability, pricing, and quote creation, but remains scoped to the Sales Order Agent workflow.

• Customers without Item Variant records retain the existing item-level behavior, including an empty Variant Code.
• No new setup option, data migration, or schema upgrade is required.
• Variant Mandatory if Exists is not currently included in the Item Selector candidate metadata. Mandatory-without-request enforcement and its accuracy scenario remain deferred until that metadata is supplied or deterministic downstream enforcement is added.
• Exact, standard, and broader searches now invoke the Item Selector consistently. This adds AOAI latency and token usage to paths that previously could bypass model selection.
• Matching item-variant combinations are availability-checked first. Concrete alternatives returned by the selector are considered only when no matching combination remains available.
• Items with several candidate variants can require additional availability calculations.
• Model output is treated as untrusted. Returned item numbers must belong to the original candidate set, returned variants must exist for the selected item, and invalid variant_match combinations are rejected.
• The application does not synthesize alternatives for unresolved variant requests. Alternatives must be returned as concrete selector entries and pass server-side validation.
• Suitability-changing variants, such as size, fit, compatibility, capacity, or technical specification, are not substituted unless the customer explicitly permits that difference.
• The availability page remains item-based and supports one displayed variant per item. When several safe alternatives are returned, only the first available concrete alternative is presented.
• An alternative is not silently substituted and is not used to create a quote until the customer confirms it.
• Resolved variant state is cleared whenever the search changes, including when the search is cleared, to prevent values from leaking between searches.
• A valid empty selector result is authoritative and does not fall back to the original candidates.
• Selector execution failures and malformed responses retain the existing best-effort fallback behavior.
• Versioned telemetry distinguishes valid empty decisions from selector and validation failures. It records only categories, booleans, and aggregate rejection counts, without customer content, item numbers, variant codes, or descriptions.
• The change targets version 29 and is not intended for backporting until the broader variant workflow has been validated.

[github-actions]

Copilot PR Review

Iteration 6 · Outcome: completed

Knowledge source: https://github.com/microsoft/BCQuality@809af9708e265f110ced6752fd8f2e40f1efc820

Findings by domain

Findings split into Knowledge-backed (cite a BCQuality article) and Agent (the agent's own judgement, no matching BCQuality rule).

Domain	Findings	Knowledge-backed	Agent	Inline	Fallback
Agent	1	0	1	1	0

Totals: 0 knowledge-backed · 1 agent findings.

Orchestrator pre-filter (2 file(s) excluded)

• layer-disabled (knowledge) : 2 file(s)

_{Findings produced by the Copilot CLI agent against BCQuality at 809af9708e265f110ced6752fd8f2e40f1efc820. Reply 👎 on any inline comment to flag false positives.}

[alexei-dobriansky]

Agentic PR Review - Round 1

Recommendation: Request Changes

What this PR does

Feature summary: this PR adds item variant support to Sales Order Agent item search, item availability, price calculation, and the sales line instructions. It lets the item selector return variant_code, shows a Variant Code column in the availability page, and passes the resolved variant into availability, capable-to-promise, translations, and temporary sales line price calculation.

The specific-variant path is mostly wired through correctly. The open issue is the no-specific-variant path. The Slice says that when the customer does not request a specific variant, the agent should suggest several available variants. The current flow is still keyed by Item.SystemId and the page source is still Item, so the page can only show one row per item and one resolved variant code per item. For an item-only request, the new fallback also does not add variants, so the agent can return a blank Variant Code instead of variant choices.

Suggestions

S1 - Show variant choices when none is specified
When the query names only an item, return available variant choices instead of a blank Variant Code. The current HasVariantSignalForItem / ResolvedItemVariants flow does not do that, and the Item page can only show one resolved variant per item.

S2 - Add tests for variant selection and pricing
Please add tests for the new variant behavior. Cover at least a specific variant request, an item-only request where variants must be suggested, and price or availability calculation with the selected Variant Code.

Risk assessment and necessity

Risk: this touches item selection, availability, capable-to-promise, and sales price calculation. A wrong variant can show the wrong inventory, wrong shipment date, or wrong customer price, and can also create a sales line that fails when variants are mandatory.

Necessity: the feature is useful and matches the Slice direction, especially for customers that sell items with mandatory variants. The scope is right, but the item-only variant path is not complete yet, and the behavior is testable through the Sales Order Agent test app internals.

---

[AI-PR-REVIEW] version=1 system=github pr=9364 round=1 by=alexei-dobriansky at=2026-07-14T17:07:47Z lastSha=328958f66529adf8688f69dd225ef7082d1cdc99 suggestions=S1,S2

[github-actions]

⚠️ Stale Status Check Deleted

The Pull Request Build workflow run for this PR was older than 72 hours and has been deleted.

📋 Why was it deleted?

Status checks that are too old may no longer reflect the current state of the target branch. To ensure this PR is validated against the latest code and passes up-to-date checks, a fresh build is required.

---

🔄 How to trigger a new status check:

1. 📤 Push a new commit to the PR branch, or
2. 🔁 Close and reopen the PR

This will automatically trigger a new Pull Request Build workflow run.

[github-actions]

$\textbf{🟠\ High\ Severity\ —\ Telemetry}$

LogTelemetryForFindItems (invoked unconditionally from FindRecordItemFromMultiItemsAvailability right after FindRecordItem returns) calls FeatureTelemetry.LogUsage('0000QB7', ..., 'SOA Multi Items Availability: Find Items v2', ...) regardless of the Found/MatchingItem outcome of the search. The only guard is AgentTaskID = 0, which filters by session context, not by search success. This inflates adoption telemetry for the new 'Find Items v2' event with unsuccessful/empty searches. Gate the LogUsage call on the search actually having found or matched an item, and use LogError/LogUptake for the attempt/failure paths.

Knowledge:

• microsoft/knowledge/telemetry/feature-usage-only-after-success.md

Line mapping was unavailable, so this was posted as an issue comment.

_{👍 useful · ❤️ especially valuable · 👎 wrong - reply with why · AL review agent v1.18.4}

[qasimikram]

Reviewed the prompts for now.