Automatic Product Metafield Synchronization

Automatic Product Metafield Synchronization

The automatic synchronization system is designed to fully automatically manage product eligibility for Carta del Docente vouchers. When you configure category mappings, the app automatically updates the metafields of all products in the associated Shopify collections.

How the Automatic System Works

1. Mapping Configuration: In the app’s Options section, you associate a Carta del Docente category (e.g., “Books and texts”) with one or more Shopify collections (e.g., “Books”).
2. Saving Settings: When you save the mappings, the app immediately triggers a background synchronization process.
3. Metafield Update: For each mapped collection, the app:
   • Retrieves all products present in the collection
   • Adds a metafield with namespace carta_docente and key categoria to each product
   • Sets the metafield value to the Carta del Docente category code (e.g., “libri-testi”)
4. Usage in the Discount Function: The Carta del Docente discount function reads this metafield to determine if a product in the cart is eligible for the specific voucher entered by the customer.

Activating a Manual Synchronization

In some situations, it may be necessary to force a manual resynchronization of metafields, for example, if you have added new products to an already mapped collection or if you have manually modified collections in Shopify.

To activate a manual synchronization:

1. Access your Shopify app’s admin interface
2. Use the dedicated API endpoint: /api/admin/sync-product-metafields
3. The app will respond with an operation summary, indicating how many products have been updated

Note: Manual synchronization uses exactly the same code as the automatic synchronization that occurs when settings are saved, ensuring consistency in behavior.

What Happens During Synchronization

The synchronization process performs these operations in sequence:

1. Metafield Definition Check: It checks if the carta_docente.categoria metafield definition already exists for products. If it doesn’t exist, it automatically creates it, configuring it for public access in the Storefront API.
2. Product Retrieval: For each mapped collection, it retrieves up to 250 products (with pagination support if necessary).
3. Metafield Update: It applies the metafield with the correct category value to each product found.
4. Results Report: Upon completion, it provides a detailed report of the number of products updated for each category and collection.

Note: The system is designed to be idempotent. If you run the synchronization multiple times on the same set of products, the final result remains the same, without creating duplicates or conflicts.

Troubleshooting

If you notice that some products are not correctly receiving the Carta del Docente discount despite being in mapped collections:

1. Check Mappings: In the Options section, verify that the Carta del Docente categories are correctly associated with the desired Shopify collections.
2. Check Product Metafields: In the Shopify admin interface, go to the affected product and check the Metafield section to see if a metafield with namespace carta_docente and key categoria exists.
3. Force a Manual Synchronization: Use the manual synchronization API endpoint to update all metafields.
4. Verify Metafield Definition: Ensure that the metafield definition exists and is configured for Storefront API access (necessary for the Discount Function to work).

The system is fully automatic and requires no manual action from you after the initial configuration of the mappings. When you add new products to already mapped collections, they will automatically receive the correct metafield during the next synchronization.