Skip to main content
Matrix42 Self-Service Help Center

Execute Bulk Actions via API Calls

  1. Last updated
  2. Save as PDF

Overview

The following article describes the possibility to perform certain actions on a larger number of devices. A possible application scenario is, for example, that a larger number of devices are replaced in the course of the usual device life cycle. Instead of performing as an example the Factory Wipe or Delete Business Data action for each device individually or selecting the devices in the Silverback Management Console and using the multiple actions option, a device list in *.csv format with certain identifiers can be created in advance, which is used as a base to trigger the API and execute a defined action. To automatically execute the API action per device based on the created device list in the next step, a PowerShell script is used to connect to the API, identify the device and execute the action and provide an output. The PowerShell script with two example *.csv files will be downloaded, modified and executed within this article. 

Create your API Token

Download and Extract Archive

  • Download the following *.zip archive: Execute Bulk Actions via API Calls.zip
  • Extract the archive to your desired target folder e.g. C:\API
  • Navigate to your target folder and review the structure :
    • The root folder contains with silverback_api.ps1 the main PowerShell script
    • The data folder contains two *.csv files containing device information
    • The scripts folder contains 8 ps.1 files that represents device actions 

Review file descriptions

  • To get an overall overview, please refer to the description below for each file:
File Description
  • silverback_api.ps1
 Represents the template of the PowerShell script with the connection details to execute the defined API action based on the provided devices.csv list.
  • devices.csv
 Defines the list of target devices by their specified identifier. By default, it contains two demo devices with the used identifier deviceSerialNumber. Supported identifiers are deviceSerialNumber, udid, imei, deviceIdentifier. They can be used in combinations as the devices_all_filters_example.csv demonstrates. In case you want to use as an example udid as the only identifier, replace the first line from deviceSerialNumber to udid and add devices by their UDID. To get specific identifiers, you can export a Hardware Summary with the Management Console or you can review them from the Device Information. In case you use IMEI, ensure to remove spaces and use only the first entry in the device information if the device reports multiple IMEI numbers.
  • devices_all_filters_example.csv
 Provides a full example for the devices.csv in case you want or need to use different or multiple device identifiers. This is helpful when devices may have not reported one of the used identifiers. The example shows that the first device will be identified only by the Serial Number, the second by the UDID, the third by the IMEI and the fourth one by the deviceIdentifier, which represents the Silverback API ID for a specific device. This information is not available in the Management Console and can be retrieved via regular API calls or within the Identification tab of a specific device in the Unified User Experience.
  • block.ps1
  • deletecompanydata.ps1
  • fulldevicewipe.ps1
  • lock.ps1
  • refresh.ps1
  • restart.ps1
  • unblock.ps1
  • unlock.ps1 
 Contains the location of the silverback_api.ps1 script, the path to the devices.csv file, the server and token information, and the appropriate action to perform. For convenience, we have prepared a script for each available action. You can open each one in a text editor such as Notepad++ and check the contents. Fulldevicewipe and Restart have additional params like Require Network Tether and Notify User, while the others are mostly identical.

Modify Connection String and execute action

  • For testing purposes, we recommend starting with refresh, lock, or restart as a command
  • Perform a right-click on e.g. restart.ps1 and open it with Notepad, Notepad++ or any text editor
  • Review the first section that contains File Path, URL, Token, Action, and Params
  • Keep the default Path or modify it e.g., to C:\temp\devices.csv
    • When you modify the path, ensure that the devices.csv is located in this folder
    • By default, it takes for the devices.csv from the Data folder
  • Change the URL to your Silverback URL, e.g. silverback.imagoverum.com
  • Replace the example token with your previously created API Token
  • Ensure that you modifying currently the right action and press save
Set-Location $PSScriptRoot
../silverback_api.ps1 `
    -FilePath '../Data/devices.csv' `
    -Server 'silverback.imagoverum.com' `
    -Token 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IiIsInNjb3BlcyI6IntcIlNjb3Blc1wiOlsx' `
    -Action 'restart' `
    -Params @{requiresNetworkTether = $true; notifyUser = $true;}

Depending on the device type, further parameters are available for the Factory Wipe action. If these body parameters are not specified, the standard variant is used as if the parameters were not available. If more parameters are specified than the operating system supports, the parameters are ignored. Please note additionally, that a PIN is mandatory for resetting a macOS device via the API and that until Silverback 23.0, the requiresNetworkTether attribute is also mandatory for all device types, except Windows 10/11. You can review an example in the Additional Notes section.

Create Device List

  • Perform a right-click on devices.csv and open it with Notepad, Notepad++ or any other text editor
  • Now replace the existing devices with Serial Numbers of your target devices
  • Add for every additional device the Serial Numbers below and use one line per device
  • Press File and Save

Execute Calls

  • Open Windows PowerShell or Terminal
  • Navigate to your target folder e.g, C:\API\Scripts
cd C:\API\Scripts
  • Now run the newly updated restart.ps1 with the following command
.\restart.ps1
  • Now review the execution process

 In case your execution policies prevents running the modified script, try to adjust your execution policy or try to copy, paste, and execute the content via PowerShell ISE. It may also be required to unblock the silverback_api.ps1 with using the unblock-file ".\silverback_api.ps1" command. 

Review Execution

  • The script will first inspect the devices.csv file and then processing the API Calls step by step for each device
PS C:\Temp> .\restart.ps1
File path: ../Data/devices.csv
Silverback url: silverback.imagoverum.com
Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IiIsInNjb3BlcyI6IntcIlNjb3Blc1wiOlsx
Action: restart

Total 2 devices found in file

Processing row 1
deviceSerialNumber: HCVDWM1TN735
Getting device data from https://silverback.imagoverum.com/api/v1/devices?details=true&$filter=deviceSerialNumber eq 'HCVDWM1TN735'
Found 1 devices satisfying fields
Executing 'restart' for device with Api ID 'FAC6F6C9-6AAC-4A40-9E28-ED7C45779BC8'. Url: https://silverback009.m42cloud.com/api/v1/devices/FAC6F6C9-6AAC-4A40-9E28-ED7C45779BC8/actions/restart?notifyUser=True&requiresNetworkTether=True
Action 'restart' executed successfully for row 1

Processing row 2
deviceSerialNumber: J0Y7WYXGWR
Getting device data from https://silverback.imagoverum.com/api/v1/devices?details=true&$filter=deviceSerialNumber eq 'J0Y7WYXGWR'
Found 1 devices satisfying fields
Executing 'restart' for device with Api ID 'DBB7C258-3EAE-4B31-BFC3-0F138E1F8C84'. Url: https://silverback009.m42cloud.com/api/v1/devices/DBB7C258-3EAE-4B31-BFC3-0F138E1F8C84/actions/restart?notifyUser=True&requiresNetworkTether=True
Action 'restart' executed successfully for row 2
PS C:\API\Scripts>

Additional Notes

  • You can review executed actions either on the device itself (e.g., with lock) or with the Pending Commands in the device overview for a specific device
  • In case you entered an incorrect connection string, the output will show only that Device(s) not found for each row
  • In case you entered a not existing URL, the output will show that the remote name could not be resolved
  • We recommend to start with your test devices and with an simple action like refresh or lock
  • Devices added to the Device Enrollment Program must be separately released in the Apple Business or School Manager
  • Review and evaluate the options to automate the execution of the device actions with the Task Scheduler on your Silverback Server
    • e.g., by Start the Program C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe with the argument -ExecutionPolicy Bypass -File C:\API\Scripts\restart.ps1
  • If you want to provide additional body parameters, like for fulldevicewipe, review the API help and add the parameters according to the example below:
Set-Location $PSScriptRoot
../silverback_api.ps1 `
    -FilePath '../Data/devices.csv' `
    -Server 'silverback.imagoverum.com' `
    -Token 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IiIsInNjb3BlcyI6IntcIlNjb3Blc1wiOlsx' `
    -Action 'fulldevicewipe' `
    -Params @{ `
        'pin'= '666666'; `
        'RemoteWipeType' = 'WipePersistUserData'; `
        'ObliterationBehavior'  = 'Default'; `
        'requiresNetworkTether' = $false; `
        'disableProximitySetup' = $true; `
        'PreserveDataPlan' = $true; `
    }