Safety Rules
Non-negotiable rules
| Before any change, export a snapshot of the current configuration so you can manually roll back if needed. |
| Built-in rollback is not available yet. The current rollback procedure is to re-import a known-good snapshot (when supported by the module) or to coordinate recovery with your backend admins. |
Merge vs Replace
Many import dialogs let you choose between MERGE and REPLACE modes. This choice directly affects how existing configuration is treated during import.
MERGE (recommended default)
MERGE updates existing entries and creates new ones, while preserving everything that is not present in the uploaded file.
Use MERGE when you want to:
-
apply incremental changes,
-
add or update specific entries,
-
minimize the risk of accidental data loss.
Typical behavior:
-
Existing entries found in the file → updated
-
New entries in the file → created
-
Existing entries NOT in the file → unchanged
| MERGE is the safest option and should be your default choice unless you explicitly need cleanup behavior. |
REPLACE (use with caution)
REPLACE updates and creates entries from the uploaded file and may delete existing entries that are not present in the file.
Use REPLACE only when:
-
the uploaded file represents the full and authoritative configuration, and
-
you intentionally want to remove anything not listed in the file.
Typical behavior (module-specific):
-
Existing entries found in the file → updated
-
New entries in the file → created
-
Existing entries NOT in the file → deleted
| REPLACE can permanently remove configuration data. Always review the dry-run results carefully before confirming an import in REPLACE mode. |
Dry-run is mandatory
Regardless of the selected mode:
-
A dry-run is always executed first.
-
The import action remains disabled until dry-run completes successfully.
-
Changing the file or switching between MERGE and REPLACE automatically invalidates the previous dry-run.
Dry-run shows:
-
what will be created, updated, or deleted,
-
warnings that require attention,
-
blocking errors that must be fixed before import.
Import safety checklist
-
Confirm you are in the correct environment.
-
Confirm your selected context (for example, client type) matches the file.
-
Export a snapshot before changes.
-
Run Dry-run and review:
-
errors (must be resolved),
-
warnings (understand impact),
-
create/update/delete counts.
-
-
If using REPLACE, confirm you accept deletions shown in the dry-run plan.
-
Apply import and immediately verify by refreshing and re-opening the affected entries.