Refactor

Refactor turns indexed source evidence into a safer bulk replacement workflow. It starts from a fresh full scan, can narrow the batch by block content before preview, keeps the preview read-only until you apply, and preserves batch details so follow-up and rollback stay inspectable.

Prerequisites #

Refactor is safest when the current index baseline is fresh and the operator has the permissions needed for content writes.

• Run a fresh full scan before previewing or applying a batch.
• Confirm the current license and user permissions allow write-enabled workflows.
• Set a backup expectation that matches the scope of the content you are about to change.
• Use inventory filters, block-content filters, and source drill-down first so the change boundary is clear before batch setup begins.

Refactor modes #

• block_instance: replace matching block instances inside indexed source content when the exact block variant is the thing that should change.
• entity_reference: replace matching references to a shared pattern, template part, or navigation without editing the shared definition itself everywhere.
• entity_definition: update the shared entity definition itself when that one source of truth should change across every place that references it.

Configure -> Preview -> Apply -> Rollback #

1. Configure the target, mode, scope, and any relevant block-content filters from a fresh baseline.
2. Generate a read-only preview and inspect the rows that would change.
3. Apply only after the preview matches the intended replacement boundary.
4. Review batch details, then roll back if validation shows the batch should be reversed.

Use block content to narrow the batch #

When a block name is too broad, use block-content filters to narrow the batch to the exact wording variant you intend to replace.

• Target outdated CTA copy, disclaimers, placeholder text, or one campaign-specific variant inside a repeated block type.
• Confirm the same content-filtered rows in preview before you apply any write-enabled change.
• Rerun preview if the underlying content changed after the last trusted scan baseline.

Configure flow and key views #

JSON mode #

JSON mode is the portable version of the same Refactor workflow. Use it when the batch definition needs to be copied, reviewed, or stored outside the immediate admin session.

• Keep JSON aligned with the same fresh scan baseline you trust in the UI.
• Review target, mode, scope, and any block-content filters carefully before generating the preview.
• Treat JSON as batch configuration, not as a substitute for preview validation.

Batch details and operation history #

Batch details are the operation trail for Refactor. Review them after preview, after apply, and again before rollback if the batch needs follow-up.

• Preview snapshots show which rows are expected to change before content is written.
• Apply and rollback timestamps show when an operation actually ran.
• Per-row outcomes help you separate changed rows from skipped or failed rows.
• Operation history keeps the workflow inspectable for QA, handoff, or incident review.

What skipped, failed, and rolled back mean #

• Skipped usually means the row no longer matched the preview assumptions by the time apply or rollback ran.
• Failed means the operation attempted the row but could not complete it safely, so follow-up review is required.
• Rolled back means the previously applied change was reversed for that row.
• Skipped or failed rows are signals to inspect batch details, check freshness, and rerun preview if content changed.

Where to go next #