---
sourceDocument: Brazil IT Operations Management
sourceDocumentLink: https://www.servicenow.com/docs/r/it-operations-management

 Release :

    - brazil

ft:locale :

    - en-US

ft:publication_title :

    - Brazil IT Operations Management

ft:clusterId :

    - itom

bundleId :

    - itom

workflow :

    - Technology


---

# Run a mass upgrade using a background script

# Run a mass Agent Client Collector upgrade using a background script {#ariaid-title1}

Release version: Brazil  
Updated September 10, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 1 minute to read  
Trigger an immediate upgrade of all eligible Agent Client Collector agents without waiting for the next scheduled job run.

## Before you begin

Configure the required upgrade properties before running the script. For details, see [Configure Agent Client Collector upgrade properties](https://www.servicenow.com/docs/7Vix3WEo~ELyPm8vMKsm~A "Set the system properties that control Agent Client Collector upgrade behavior, including the target version and rate limits for mass upgrades.").

Role required: agent_client_collector_admin

## About this task

The background script upgrades agents connected via MID Server and agents connected via Cloud Services (ICS) in a single run. Both function calls in the script are required --- omitting either skips the corresponding agent group.

The system queries all agents that are Up, not duplicated, have a valid MID Server or Pod connection, and have not exceeded the retry limit. Agents with no prior failures are upgraded before agents with prior failures.

## Procedure

1. Navigate to AllSystem DefinitionScripts - Background.
2. Change the application scope to `sn_agent` (Agent Client Collector).
3. Paste the following script into the editor.  

       var duration = 60; // Duration in minutes for rate limiting calculations

       var a = new AgentUpgradeUtil();
       a.upgradeAgentsLimitedByMid(duration);  // Upgrades agents connected via MID Servers
       a.upgradeAgentsMidless(duration);       // Upgrades agents connected via Cloud Services

   {#run-agent-mass-upgrade-script__codeblock_mass_upgrade_script}

   Set `duration` to the number of minutes used for rate limiting calculations. The default value of `60` applies the per-hour limits configured in the upgrade properties.
4. Select Run script.  
   The system begins upgrading eligible agents immediately, adhering to the rate limits set in the upgrade properties.

*[\>]: and then