Product Mapping Attempt

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

ProductMappingAttempt is the queued review record that proposes how an unmapped staged vendor catalog item should map to a canonical product. It stores exact-match or LLM-assisted analysis, review state, and final acceptance or rejection.

Parent hierarchy:

• Inventory & Vendor Supply
• Vendor-To-Product Mapping And Review
• Product Mapping Attempt

Primary implementation paths:

• packages/framework/src/Models/ProductMappingAttempt.php
• packages/framework/src/Actions/ProductMappingAttempt
• packages/admin/src/Livewire/Admin/Vendor/Mappings/Attempts

What Users Can Do With It

Direct capabilities

Admin operators can:

• review pending, accepted, or rejected mapping attempts
• filter attempts by confidence, match result, match type, and verification status
• accept a successful pending attempt
• reject a successful pending attempt
• retry mapping analysis
• batch-process accepted, rejected, or retry actions from the attempts page

Indirect capabilities

The system also creates attempts automatically:

• from explicit retry actions
• from staged catalog-item actions
• from listener-based automation when vendor assignment rules allow auto mapping attempts

Things users cannot do directly

Operators do not directly type or edit:

• match_result
• match_type
• confidence_level
• ai_analysis
• matching_products

Those fields are generated by the attempt-processing workflow.

Where It Is Managed

Channel	Role	Notes
Vendor > Mappings > Attempts	Direct	Main review and batch-action page
Vendor catalog-item actions	Parent-owned	Catalog-item flows can open retry or product-attempt actions
Queue and analysis jobs	Indirect upstream input	Exact-match and optional LLM analysis populate the record
Storefront	Indirect	No direct shopper visibility

Sources:

• packages/admin/routes/web.php
• packages/admin/src/Livewire/Admin/Vendor/Mappings/Attempts/DataTable.php
• packages/admin/src/Livewire/Admin/Vendor/Mappings/Attempts/DataTable/ActionsField.php
• packages/framework/src/Actions/ProductMappingAttempt/CreateMappingAttempt.php
• packages/framework/src/Actions/ProductMappingAttempt/ProcessMappingAttempt.php

Creation Model

ProductMappingAttempt is system-generated.

The main write paths are:

1. CreateMappingAttempt validates that the staged vendor catalog item is valid and still unmapped
2. it creates or reuses a pending attempt record
3. it dispatches ProcessMappingAttempt on the mappings queue
4. the process job tries exact matching first
5. if exact matching is not enough and exact_match_only is false, it can run LLM analysis
6. the attempt is marked completed with success or failure metadata
7. exact high-confidence successful attempts can auto-accept

There is also a listener path that automatically creates mapping attempts when the manufacturer-vendor rule enables auto_mapping_attempts.

Sources:

• packages/framework/src/Actions/ProductMappingAttempt/CreateMappingAttempt.php
• packages/framework/src/Actions/ProductMappingAttempt/ProcessMappingAttempt.php
• packages/framework/src/Actions/ProductMappingAttempt/ProcessMappingAttempt/FindMatchingProducts.php
• packages/framework/src/Actions/ProductMappingAttempt/ProcessMappingAttempt/GenerateMappingsAnalysis.php

Configuration And Data Model

Important fields:

Field	Purpose
product_vendor_catalog_item_id	staged item being reviewed
product_id	proposed canonical product
product_vendor_mapping_id	accepted mapping, when one exists
match_result	success or failed
match_type	exact match or AI analysis
confidence_level	low, medium, high
justification	short explanation for the proposal
confidence_reasons	structured supporting reasons
ai_analysis	structured analysis payload
matching_products	candidate products considered
accepted_at / rejected_at	review state
status	pending or completed

Key scopes:

• toReview()
• accepted()
• rejected()
• pending()
• completed()
• successful()
• failed()

Source:

• packages/framework/src/Models/ProductMappingAttempt.php

Relationships

ProductMappingAttempt directly relates to:

• productVendorCatalogItem()
• product()
• productVendorMapping()
• rejectedByUser()
• acceptedByUser()

Supporting records:

• alternate codes participate in the matching pipeline but are not owned by the attempt itself

Sources:

• packages/framework/src/Models/ProductMappingAttempt.php
• packages/framework/src/Models/AlternateCode.php
• packages/framework/src/Models/Traits/HasAlternateCodes.php

Rules And Downstream Effects

Accept and reject rules

An attempt can only be accepted or rejected when:

• it is pending review
• it was successful
• the proposed product still exists
• a mapping does not already exist

Accepting an attempt:

• creates or updates a ProductVendorMapping
• sets default multipliers of 1
• records acceptance metadata

Rejecting an attempt:

• records rejection metadata
• leaves the staged item unmapped

Sources:

• packages/framework/src/Actions/ProductMappingAttempt/AcceptMappingAttempt.php
• packages/framework/src/Actions/ProductMappingAttempt/RejectMappingAttempt.php

Auto-accept behavior

The processing job can auto-accept a mapping attempt only when the result is:

• completed
• successful
• exact match
• high confidence

Source:

• packages/framework/src/Actions/ProductMappingAttempt/ProcessMappingAttempt.php

Integrations And Automation

Queue and analysis

Mapping attempts are queue-backed and can include LLM analysis.

Sources:

• packages/framework/src/Actions/ProductMappingAttempt/CreateMappingAttempt.php
• packages/framework/src/Actions/ProductMappingAttempt/ProcessMappingAttempt.php
• packages/framework/src/Actions/ProductMappingAttempt/ProcessMappingAttempt/GenerateMappingsAnalysis.php

Admin batch processing

The attempts page supports batch actions for accept, reject, and retry.

Source:

• packages/admin/src/Livewire/Admin/Vendor/Mappings/Attempts/DataTable.php

Where It Appears To End Users

ProductMappingAttempt is an internal review workflow only.

Customers never directly see it. They only experience the downstream result after an accepted mapping makes canonical inventory and related sellable supply possible.

Current Documentation Takeaways

1. ProductMappingAttempt is a review workflow, not the final mapping record.
2. Exact matching and optional LLM analysis both feed the same acceptance pipeline.
3. Accepting an attempt creates a real mapping, which can then unlock canonical inventory sync.

Open Questions

• The exact LLM prompt and provider behavior for mapping analysis live partly outside the inspected top-level workflow classes and need a later deep dive if we want full AI-governance documentation.
• The packaged review UI was inspected at the Livewire level, but not every rendered table cell blade was opened in this pass.