Doc · 12 External system protection

External system protection · maintained texts stay as they are

ERP systems, marketplace connectors or translation services often write to Shopware via the API and overwrite texts you maintained in the PIM. External system protection remembers the PIM state per product number and language and restores it as soon as it was changed from outside.

What the protection is for

Many shops connect external systems via Shopware integrations. If such a system sends its own product names or descriptions with every sync, maintained SEO texts and translations are gone after the next run. The protection detects such write operations and resets the affected fields. You find it in the config matrix, tab "External systems". It is off by default.

How the comparison works

Reference state: The PIM stores the protected fields per product number and language in its own table.
Detect: If an external system writes product translations via an integration, the PIM queues the affected products. Write operations by signed-in users, including the PIM itself, refresh the reference state immediately instead.
Restore: Fields that deviate from the reference state are reset to it. Afterwards the PIM records the state as reference again.

Inheritance is preserved: An empty field inherited from the parent language is stored as "inherited" and written back that way. The protection strictly distinguishes "inherited" from "empty text". Because the reference state is tied to the product number, it also works when internal IDs change during a re-import.

All settings in the "External systems" tab

Setting	Meaning	Default
Enable protection	While off, no reference state is recorded and nothing is restored	off
Protected languages	Only these languages are monitored. If a sales channel uses its own language, select exactly that one	none
Protected fields	Name, description, meta title, meta description, keywords	all five
Integrations treated as external	Selection from your Shopware integrations. Without a selection every integration counts as external	none
Trigger	Events and scheduled run, Events only, Scheduled run only (cron job), Manual only	Events and scheduled run
Wait time between runs	Seconds between two automatic runs, 0 to 3600	60

Without at least one protected language nothing happens. If you selected integrations, the PIM treats write operations of all other integrations like your own changes and refreshes the reference state.

Trigger in detail

Events detect write operations via integrations immediately and queue the products.
The scheduled run processes this queue. It requires active task processing in Shopware.
Manual only starts nothing automatically, the comparison runs solely via the buttons in the tab.

For automatic restoring, the default "Events and scheduled run" is the right choice. In all modes every edit in the PIM refreshes the reference state.

Reference state, check and restore

The section "Reference state and log" offers three buttons:

Set reference state: The current state of all products becomes the target state. A confirmation dialog shows the number of fields, languages and entries stored so far.
Check only: Reports how many entries deviate from the reference state without changing anything.
Restore now: Checks the entire catalogue and resets all deviations. This also covers changes that bypassed the interface, such as an import written directly to the database. The action cannot be undone.

Below you see the number of stored reference entries and the time of the last refresh and the last run.

Reference first, then protection: When setting up, set the reference state first and make sure the texts are correct at that moment. If a text has already been overwritten from outside, the external text becomes the reference and cannot be recovered afterwards.

Log and CSV export

The table shows the last ten runs with time, trigger (Reference set, Manual, Event, Scheduled run), checked, restored and recorded entries and the duration. The last 50 runs are kept. If a run restored texts, you download the list with product number, name and affected fields via CSV, ideal for clarifying things with the operator of the external system. The file uses a semicolon as separator and opens in Excel with correct umlauts. Up to 2000 products are recorded per run.

Scheduled task staw_pim_direct.translation_guard

The plugin registers the scheduled task staw_pim_direct.translation_guard with an interval of 300 seconds. It only runs if the protection is enabled and the trigger includes a scheduled run, and it respects the wait time. On purpose it only checks queued products and not the entire catalogue: this way it cannot mistake an intended edit for an external overwrite.

Call via HTTP without command line

Without command line access you start the comparison via an address that the tab shows for copying:

https://your-shop.com/api/_action/staw-pim-direct/guard/cron/<key>

Call via GET or POST, for example every five minutes via your host's cron service.
By default only queued products are processed. With ?full=1 appended, the call checks the entire catalogue, which is considerably more demanding.
The call only works with protection enabled and a trigger that includes a scheduled run. Without full=1 the wait time applies.

Treat the key like a password: The address works without sign-in and is protected only by a 32-character random key. "New key" creates a new one, the previous address becomes invalid immediately.

Console command staw:pim:guard:snapshot

For the first run on large catalogues the console is the better way: in the admin, setting the reference runs in a single request and can hit the web server's time limit with tens of thousands of rows.

bin/console staw:pim:guard:snapshot
bin/console staw:pim:guard:snapshot --check
bin/console staw:pim:guard:snapshot --restore

Call	Effect
without option	Sets the reference state for all products
`--check`	Reports deviating entries, writes nothing
`--restore`	Restores deviations across the entire catalogue and then refreshes the reference
`--force`	Runs the command even if the protection is switched off

If no protected language is selected, the command stops with a notice.

What's next

You create texts for many languages with AI text generation or via CSV import. The "External systems" tab and all other settings are in the config matrix, who may see them is defined in permissions & super admin.

Frequently asked questions

Will my own changes in the PIM be reset?

No. Write operations by signed-in users refresh the reference state immediately. Only changes via integrations that count as external are reset.

Which fields can I protect?

Name, description, meta title, meta description and keywords of the product translations, each for the selected languages.

Do I need a cron job?

For automatic restoring, Shopware's task processing must be running. Alternatively, call the displayed HTTP address regularly via a cron service.

What about imports directly into the database?

Such changes trigger no event. "Restore now", the console command with --restore or the HTTP address with ?full=1 check the entire catalogue and still find them.