Run an Updater Script

Overview

This page explains how to run a Groovy Updater Script to apply bulk changes to repository content in Bloomreach Content.

Updater scripts allow you to automate modifications across large sets of content. You can create, manage, and execute these scripts from the CMS UI using the Updater Editor. For guidance on writing scripts, see Write an Updater Script. This page focuses on execution options and operational details.

Important: Updater scripts can modify significant portions of your repository. Only trusted developers and administrators should have access to this functionality.

Security Considerations

Updater scripts run in a custom Groovy ClassLoader, which blocks some unsafe operations (such as System.exit()). However, this is not a fully secure sandbox. Scripts can potentially execute external programs and affect the server environment. Restrict access to the Updater Editor to trusted users only.

Updater Editor Structure

The Updater Editor UI is divided into three main sections:

  • Registry
    Displays all available updater scripts. Select a script here to prepare it for execution.
  • Queue
    Lists scripts scheduled for execution. Scripts run in the order added, and only one script runs at a time—even in clustered environments. You can stop the currently running script or remove scripts from the queue. When you stop a script, it completes the current NodeUpdaterVisitor#doUpdate call before halting. Script output appears in the lower section of the UI and updates automatically.
  • History
    Shows all scripts that have been executed, either fully or partially. If a script supports undo (by implementing undoUpdate), you can revert its changes from this section.

Execution Options

Node Selection

The updater engine uses the visitor pattern to process nodes. You can specify which nodes to visit using one of the following methods in the Select node using option:

  • Repository path
    Enter an absolute repository path (e.g., /content/documents or /hst:hst/hst:configurations). The engine visits the specified node and all its descendants.

  • XPath query
    Provide an XPath query to select nodes. Example queries:

    QueryDescription
    //element(*, hippo:document)Selects all nodes of type hippo:document
    /jcr:root/hst:hst/hst:configurations//element(*, hst:sitemapitem)Selects all hst:sitemapitem nodes under /hst:hst/hst:configurations
    //*[@example:title='foo']Selects all nodes with the property example:title set to foo

    Hint: You can test XPath queries in the repository servlet at http://localhost:8080/cms/repository.

  • Updater
    The script itself determines which nodes to visit. Implement or override the firstNode and nextNode methods in your script using the BaseNodeUpdateVisitor base class. See Write an Updater Script for details.

Performance Settings

You can control script performance using batch and throttle settings:

  • Batch size
    Defines how many updated nodes are processed before changes are saved to the repository. The engine counts only nodes where doUpdate(Node) returns true. Keep the batch size moderate (e.g., 50–100) to avoid large, memory-intensive transactions. See the Reporting of Execution section for more information.
  • Throttle
    Specifies the wait time (in milliseconds) after each batch. Throttling prevents the repository from becoming unresponsive during large updates.

Logging

  • Log Level
    Choose from TRACE, DEBUG, or INFO. The default is DEBUG. Only messages at or above the selected level are output.

  • Log Target (available in versions 14.7.7 and 15.0.1+)
    Select where log messages are written: LOG FILES or REPOSITORY.

    • LOG FILES: Messages are written to standard log files using the org.onehippo.repository.update.UpdaterExecutionReport logger. These logs are not shown in the UI.
    • REPOSITORY: Messages are stored in JCR nodes and displayed in the UI during script execution.

    Note: The Log Target option is available only in local development mode (using the cargo.run profile) or when the system property groovy.persist.logs.supported is set to true. In other environments, log messages are always written to log files.

    Caution: Avoid using REPOSITORY as the log target for scripts that generate large log outputs, as this can fill the datastore and degrade performance.

    Version-specific behavior:

    • 14.7.6 and 15.0.0:
      • In local development (cargo.run), logs are written to the repository and shown in the UI.
      • In other environments, logs are written to files only.
    • 14.7.5 and earlier:
      • Logs are always written to the repository and displayed in the UI.

Parameters

You can pass parameters to scripts as a JSON string representing a map of parameter names and values. Example:

{ "basePath": "/content/documents/myproject/news", "tag": "gogreen" }

Execution Mode

You can run scripts in two modes:

  • Execute
    Processes all selected nodes and saves changes to the repository after each batch. The UUIDs of modified nodes are logged for potential undo operations.
  • Dry run
    Processes all selected nodes but does not persist any changes. The engine calls Session.refresh(false) after each batch to discard modifications.

Use dry run mode to validate scripts before applying changes.

Automatically Execute Updater Scripts on Startup

You can configure scripts to run automatically at startup by adding them as content definitions to /hippo:configuration/hippo:update/hippo:queue using the repository-data-application module. When the application starts, it executes any scripts found in the queue.

By default (since version 13), the updater execution module runs scripts only on full CMS nodes.

To execute scripts automatically in a delivery-tier-only environment, ensure:

  • The property hipposys:cmsonly at /hippo:configuration/hippo:modules/updater-execution is set to false.
  • The script depends only on libraries available in that environment (typically, CMS libraries are not present).

Undo Updates

If a script implements the undoUpdate method, you can revert its changes. In the History section, click the Undo button for the relevant script. The updater engine revisits only the nodes modified by the original doUpdate call and applies undoUpdate to each.

You cannot undo actions for scripts that were run in dry run mode or that are themselves the result of an undo operation.

Bootstrapping Updater Scripts

Starting with version 14.1.0, updater scripts added through the CMS UI are stored as configuration, not as content. Each new script is saved in a separate YAML file. This approach allows you to bootstrap updater scripts as part of configuration management, without requiring content actions. For more information, see Manage Content.

Strict Mode

Info: Strict Mode is available in brXM 15.4.0 and later.

Strict Mode restricts the creation and modification of updater scripts in the CMS UI. When enabled, only existing scripts can be executed by CMS admin users; editing and creating scripts is disabled. This supports deployment workflows where developers manage scripts, and CMS admins can only run them.

When Strict Mode is active, the Updater Editor is read-only except for the Parameters, log level, and log target fields.

Enable Strict Mode by setting the system property:

groovy.strict.mode=true
Share Feedback
Page: /build/content-updates/run-an-updater-script
Section: Build
Category *