DevXMachina
Menu
EN RO
EN RO

How to Bulk Replace Gutenberg Blocks

Bulk replacement becomes safer when indexed source evidence defines the boundary before anything is written. This workflow uses a fresh scan, exact source review, block-content filters when needed, and a read-only preview before apply.

Before you start #

Bulk replacement should begin only after the indexed evidence is current enough to trust.

  • Run a fresh full scan.
  • Use block inventory, source drill-down, and block-content filters to confirm the exact replacement scope.
  • Make sure write-enabled access and your backup expectations match the size of the batch.

The safest replacement path is the one that keeps every step explainable to another teammate.

  1. Review the target block or entity in inventory and open exact sources.
  2. Choose the correct Refactor mode for the change boundary you actually want.
  3. Configure the target, scope, and any relevant attribute or block-content filters.
  4. Generate a read-only preview and inspect the rows that would change.
  5. Apply the batch only after the preview matches the intended replacement work.
  6. Review batch details after apply and keep rollback available for follow-up.

Why preview matters #

Preview is the point where replacement work stops being a guess and becomes something the team can inspect together.

  • Preview keeps content unchanged while the batch is still being challenged.
  • Preview reveals if the mode or scope is wider than expected.
  • Preview gives QA and reviewers a shared checkpoint before apply.

Visual walkthrough #

These views show how the configure flow moves from target selection to a reviewable batch, plus the portable JSON representation of the same work.

Target and mode selection Lock the target and Refactor mode first so the rest of the workflow stays anchored to the right change boundary.
DXM Block Toolkit Refactor Target step showing target setup and Refactor mode selection.
Scope configuration Use Scope to trim the batch to the exact indexed sources you want to touch.
DXM Block Toolkit Refactor Scope step showing source scope controls and filters.
Replacement definition Define the replacement only after the target and scope already reflect the batch you trust.
DXM Block Toolkit Refactor Replacement step showing replacement settings.
Review before apply Review is where the configured batch becomes easy to challenge before any content write is allowed.
DXM Block Toolkit Refactor Review step showing the configured batch summary before apply.
JSON mode JSON mode exposes the same batch definition when the workflow needs to move outside the current visual configure flow.
DXM Block Toolkit Refactor JSON mode showing the same batch definition outside the visual configure flow.

Scope discipline and JSON mode #

Refactor configuration can stay in the UI or move through JSON mode, but the same scope discipline still applies when the batch is narrowed by source filters or block content.

  • Keep the target, mode, filters, and block-content scope aligned with the same baseline you just reviewed.
  • Treat JSON as a way to carry the batch definition, not as a shortcut around preview review.
  • If scope feels ambiguous, stop and narrow the evidence before generating the preview.

For the full product-side reference, continue with Refactor .

Where to go next #

Refactor

See the full product-side Refactor reference, including JSON mode and batch details.

Read docs

How to Choose the Right Refactor Mode

Choose between block_instance, entity_reference, and entity_definition before batch setup.

Read guide

How to Validate and Roll Back a Refactor Batch

Validate outcomes after apply and decide when rollback is the right follow-up.

Read guide