DataFirefly Catalog Merge: merging duplicate attributes and features

<h2>Installation</h2>
<p>Install the module from <strong>Modules > Module Manager > Upload a module</strong> using the ZIP file, or drop the <code>dfcatalogmerge</code> folder into the <code>/modules/</code> directory of your shop and click Install.</p>
<p>On install, the module creates its two tables (feature value positions and merge history), registers the <code>filterProductContent</code> hook and adds a <strong>Catalog Merge</strong> tab under the Catalog menu.</p>
<div class=”df-callout warn”><p>This module changes your catalog data permanently. Back up your database before your first cleanup campaign. Merges cannot be undone.</p></div>

<h2>Module settings</h2>
<p>The settings live on the module configuration page. Four options, all enabled by default.</p>
<h3>Force the order on product pages</h3>
<p>Applies the positions you set to the feature values shown on the product page. This option is required on PrestaShop 8, whose core does not sort feature values. On PrestaShop 9 the module also fills the native position column, and the option guarantees the same result whatever the shop <code>PS_FEATURE_VALUES_ORDER</code> setting is.</p>
<h3>Merge duplicate combinations</h3>
<p>When two combinations of the same product become identical after a merge, the module joins them automatically. Turn this off only if you want to handle those cases by hand, keeping in mind that PrestaShop handles two combinations carrying the exact same attributes poorly.</p>
<h3>Update third party tables</h3>
<p>The module looks through the database for every table holding an <code>id_attribute</code> or <code>id_feature_value</code> column outside the core tables, notably the faceted search index, and repoints or removes the affected rows. Without this option, ghost filters can survive a merge.</p>
<h3>Keep a merge history</h3>
<p>Records every applied merge: source value, target value, number of rows updated, employee and date. Available in the History tab.</p>

<h2>Merging attribute values</h2>
<p>Open <strong>Catalog > Catalog Merge</strong>, <strong>Attribute values</strong> tab. Pick the attribute group to clean up and the language you want to read the labels in.</p>
<p>The table lists the values of the group with, for each one, the number of products and combinations using it. Tick the duplicates to remove, pick the value to keep in the “Merge the selected values into” list, then click <strong>Simulate</strong>.</p>
<h3>Reading the simulation report</h3>
<p>The simulation writes nothing. The report shows the number of combination lines to convert, the number of products involved, the combinations already holding the target value and those that will become identical after the merge. If the report suits you, click <strong>Apply this merge</strong>.</p>
<h3>What happens to combinations</h3>
<p>Every combination using a deleted value moves to the value you keep. Three special cases are handled automatically:</p>
<ul>
<li>A combination already held the target value and its duplicate: the duplicate line is removed, the rest of the combination is left alone.</li>
<li>Two combinations of the same product become identical: they are joined. Quantities are added up shop by shop, images and specific prices are transferred, the default combination is kept, and the parent product stock is resynchronised.</li>
<li>Open carts referencing the removed combination are repointed to the one that stays.</li>
</ul>
<div class=”df-callout note”><p>The values to merge must belong to the same attribute group as the target value. The module refuses a merge across two groups, which would produce inconsistent combinations.</p></div>

<h2>Merging feature values</h2>
<p>The <strong>Feature values</strong> tab works the same way: pick a feature, tick the duplicates, pick the target value, simulate then apply.</p>
<p>Product assignments are converted to the value you keep. If a product already carried both values, the duplicate assignment is removed. On PrestaShop 9, feature values attached to combinations are handled at the same time.</p>
<h3>Custom values</h3>
<p>PrestaShop lets you type a feature value specific to a single product, flagged <em>custom</em> in the table. Those values are the first source of duplicates after an import. You can merge them into a shared value like any other. If the target value was itself custom and ends up used by several products after the merge, the module turns it into a shared value automatically.</p>

<h2>Finding duplicates automatically</h2>
<p>The <strong>Duplicate finder</strong> tab scans the whole catalog and groups values whose label is identical once case, accents, punctuation and repeated spaces are ignored. “Red”, “red” and “RED” therefore form a single group, as do “Organic cotton” and “organic-cotton”.</p>
<p>For each group, the most used value is suggested as the target, with a preference for shared values over custom ones. The <strong>Simulate this merge</strong> button sends the group to the simulation screen, where you keep control over the final choice.</p>
<p>The scan runs in the selected language. On a multilingual catalog, run it again in each language: a duplicate may exist in one translation only.</p>

<h2>Setting the display order</h2>
<p>In the first two tabs, each row has a handle on the left. Drag a row to change its position: the new order is saved right away, without reloading the page.</p>
<p>The <strong>Sort automatically</strong> button arranges the values with no manual work. Clothing sizes follow the XS, S, M, L, XL, XXL sequence rather than alphabetical order, and numeric values follow natural order: 2 before 10, 39 before 41.</p>
<h3>What the customer sees</h3>
<p>For attribute values, the position is the one used by the combination selector on the product page, on PrestaShop 8 as well as PrestaShop 9. No extra setting is needed.</p>
<p>For feature values, the order applies to the feature table of the product page as long as the “Force the order on product pages” option is on. On PrestaShop 9 the native position is filled in parallel, which brings the same order to the other back office screens.</p>
<div class=”df-callout tip”><p>If the order does not change on the front office after an edit, clear the shop cache. Product pages are cached by PrestaShop and by most performance modules.</p></div>

<h2>Merge history</h2>
<p>The <strong>History</strong> tab lists the applied merges, newest first: date, type, source value with its id, value kept and number of rows updated. The ids are kept so you can cross-check against a database backup if you ever need to roll something back by hand.</p>

<h2>Good practice</h2>
<ul>
<li>Back up the database before a cleanup campaign, especially on a catalog of several thousand products.</li>
<li>Always simulate. The report shows you the combinations that will disappear through merging before it happens.</li>
<li>Work group by group rather than in a single pass, to keep the reports readable.</li>
<li>After a large merge, rebuild the faceted search index if you use that module.</li>
<li>On a busy shop, apply merges during quiet hours: converting combinations briefly locks the tables involved.</li>
</ul>

<h2>Troubleshooting</h2>
<h3>The merge is refused with a message about the attribute group</h3>
<p>Every ticked value must belong to the same attribute group as the target value, or to the same feature for feature values. Check that you have not ticked a value from another group carrying the same name.</p>
<h3>Feature value order does not change on the product page</h3>
<p>Check that the “Force the order on product pages” option is on, then clear the cache. If your theme renders features through a third party module rather than through the native product page variables, the order may not be picked up: contact us with the theme name.</p>
<h3>A merge stopped halfway</h3>
<p>Writes run inside a transaction: on error the database returns to its initial state and no data is lost. The error message shown at the top of the screen holds the cause. Tables must be InnoDB for the rollback to work.</p>
<h3>Faceted filters still show the deleted value</h3>
<p>Make sure the “Update third party tables” option was on when the merge ran, then rebuild the index of the faceted navigation module from its configuration page.</p>

<h2>Compatibility</h2>
<ul>
<li>PrestaShop 8.0 to 9.x, the same ZIP covers both branches.</li>
<li>Multistore and multilingual.</li>
<li>ModuleAdminController architecture, no Composer dependency.</li>
<li>Interface available in English, French, Spanish, German, Italian, Dutch, Polish and Portuguese.</li>
</ul>