---
sourceDocument: Yokohama IT Operations Management
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/yokohama/it-operations-management

 Release :

    - yokohama

ft:locale :

    - en-US

ft:publication_title :

    - Yokohama 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: Yokohama
* 
* Updated May 28, 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 [Agent Client Collector upgrade properties](https://servicenow-prod.fluidtopics.net/rEORgRNPifDAgjkiXg2KkA "System properties that control Agent Client Collector upgrade behavior, including the target version, rate limits, retry logic, and timeouts.").

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