Best Practices voor KatanaPIM in Magento 2

Command line tools voor de KatanaPIM Connect extensie. Deze commando's zijn handig voor handmatige synchronisatie, automatiseringsscripts en probleemoplossing.

Beschikbare Commando's

katana:import:full

Voert een volledige synchronisatie uit van alle entiteiten uit KatanaPIM.

# Sync alles (attributen, categorieën, producten, assets)
bin/magento katana:import:full

# Sync alleen attributen
bin/magento katana:import:full --attributes

# Sync alleen categorieën
bin/magento katana:import:full --categories

# Sync alleen producten
bin/magento katana:import:full --products

# Sync alleen assets
bin/magento katana:import:full --assets

Opties:

Wanneer geen opties worden opgegeven, worden alle entity types gesynchroniseerd in de correcte volgorde.

Geforceerde Update: (beschikbaar vanaf v3.7.0)

Gebruik de --force vlag wanneer je producten opnieuw wilt synchroniseren, ongeacht of de data is gewijzigd:

# Forceer re-sync van alle producten (negeer hash vergelijking)
bin/magento katana:import:full --products --force

# Korte versie
bin/magento katana:import:full --products -f

Dit is handig wanneer:

• Magento data is gewijzigd buiten het sync proces om
• Hash vergelijking wijzigingen niet correct detecteert
• Je lokale wijzigingen wilt overschrijven met PIM data

Sync van Eén Product: (beschikbaar vanaf v3.11.0)

Gebruik --katana-pim-id om precies één product te synchroniseren in plaats van alles dat openstaat:

# Synchroniseer één product volledig
bin/magento katana:import:full --katana-pim-id=1234

# Combineer met --force om de hash vergelijking te negeren
bin/magento katana:import:full --katana-pim-id=1234 --force

# Sla de API over en verwerk alleen wat lokaal al is opgeslagen
bin/magento katana:import:full --katana-pim-id=1234 --skip-api

De scope geldt voor de hele run:

• De API fetch vraagt dat ene product op (en de bijbehorende assets) in plaats van door alles heen te pagineren
• De Magento product- en asset-sync worden beperkt tot dat product
• Alleen de entiteiten products en assets draaien. Geef --attributes of --categories expliciet mee als het product een vernieuwde attribuut- of categorie-mapping nodig heeft
• Reindexen blijft beperkt tot de Magento entiteit van dat product in plaats van een volledige reindexAll()

Er wordt tijdens een gescopete run nooit iets als verwijderd gemarkeerd. Een normale volledige sync markeert alles dat de API niet teruggaf als verwijderd, wat alleen veilig is als de run de complete catalogus heeft gezien. Een gescopete run ziet één product, dus die stap wordt overgeslagen en de output meldt Skipped marking deleted (scoped run).

Gebruik dit wanneer:

• Je uitzoekt waarom één specifiek product niet synchroniseert
• Een supportvraag over een enkele SKU
• Je een fix wilt verifiëren zonder een volledige run af te wachten

Hoe sync werkt:

De synchronisatie werkt in twee fases:

1. Data Ophalen — Haalt huidige data op uit de KatanaPIM API
2. Magento Updates — Maakt of updatet entiteiten gebaseerd op je configuratie

Of nieuwe entiteiten automatisch worden aangemaakt hangt af van je instellingen bij Stores → Configuration → KatanaPIM → Automation:

• Auto create new categories
• Auto create new products

Output: Toont voortgang en resultaten voor elk entity type.

Gebruik dit wanneer:

• Initiële setup en eerste import
• Na grote PIM wijzigingen
• Wekelijks/dagelijks onderhoud
• Troubleshooting van sync problemen

katana:import:incremental

Voert een delta-synchronisatie uit, importeert alleen items die zijn gewijzigd sinds de laatste sync.

bin/magento katana:import:incremental

Output: Toont voortgang en aantal bijgewerkte items.

Gebruik dit wanneer:

• Regelmatige geplande updates
• Magento gesynchroniseerd houden gedurende de dag
• Na individuele productwijzigingen in PIM

katana:assets:cleanup

Verwijdert soft-deleted assets (gemarkeerd als is_deleted=1) uit de Magento media galerij. Assets worden soft-deleted wanneer ze verwijderd zijn in KatanaPIM maar de daadwerkelijke mediabestanden nog in Magento staan. Dit commando ruimt die verweesde galerij-items op.

(Beschikbaar vanaf v3.8.0)

# Toon wat verwijderd zou worden zonder wijzigingen
bin/magento katana:assets:cleanup --dry-run

# Verwijder soft-deleted assets uit media galerij
bin/magento katana:assets:cleanup

Opties:

Gebruik dit wanneer:

• Na het verwijderen van afbeeldingen bij producten in KatanaPIM
• Om verweesde media galerij-items op te ruimen
• Als onderdeel van periodiek onderhoud

katana:migrate:attributes

Migreert attribuut-koppelingen van de oude Itonomy_Katanapim module naar KatanaPim_Connect. Dit commando is alleen nodig bij het upgraden van de legacy Itonomy module.

(Beschikbaar vanaf v3.10.0)

# Preview wat gemigreerd zou worden
bin/magento katana:migrate:attributes --dry-run

# Voer de migratie uit
bin/magento katana:migrate:attributes

Opties:

Hoe het werkt:

1. Leest attribuut-koppelingen uit de oude katanapim_attribute_mapping tabel
2. Vindt overeenkomende attributen in de nieuwe katanapim_attribute tabel op katana_attribute_code
3. Kopieert de magento_attribute_code en is_configurable instellingen naar de nieuwe tabel

Vereisten:

• De oude katanapim_attribute_mapping tabel moet bestaan (van een eerdere Itonomy_Katanapim installatie)
• Voer eerst een volledige API attribuut-import uit zodat de nieuwe tabel items heeft om tegen te matchen

Gebruik dit wanneer:

• Je migreert van de Itonomy_Katanapim module naar KatanaPim_Connect
• Je bestaande attribuut-koppelingen wilt behouden in plaats van handmatig opnieuw te configureren

Voorbeelden

Initiële Setup

# Eerste keer setup - importeer alles
bin/magento katana:import:full

Dagelijks Onderhoud

# Volledige sync tijdens onderhoudsvenster
bin/magento cache:flush
bin/magento katana:import:full
bin/magento indexer:reindex

Incrementele Updates

# Snelle sync van recente wijzigingen
bin/magento katana:import:incremental

Stapsgewijze Import

# Stap 1: Importeer en map eerst attributen
bin/magento katana:import:full --attributes

# Stap 2: Configureer attribuut mapping in admin
# (handmatige stap - gebruik Attributen grid)

# Stap 3: Importeer categorieën
bin/magento katana:import:full --categories

# Stap 4: Importeer producten
bin/magento katana:import:full --products

# Stap 5: Importeer afbeeldingen en video's
bin/magento katana:import:full --assets

Troubleshooting

# Draai met uitgebreide output
bin/magento katana:import:full -v

# Controleer wat gesynchroniseerd zou worden zonder wijzigingen
bin/magento katana:import:full --attributes

Indexer Aanbevelingen

Voor grote catalogi, zet je indexers op "Update on Schedule" mode voordat je imports uitvoert:

# Controleer huidige indexer modes
bin/magento indexer:show-mode

# Zet alle indexers op schedule mode
bin/magento indexer:set-mode schedule

Waarom "Update on Schedule"?

Met "Update on Save" mode triggert Magento reindexering na elke individuele entity import — extreem traag voor grote datasets. Schedule mode queued index updates en verwerkt ze in batches, wat de import prestaties aanzienlijk verbetert.

Meer Hulp Nodig?

Documentatie:

• Alle Help Artikelen - Compleet documentatie overzicht

Support:

• Contact Opnemen - Hulp van ons team