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:\temp
  • Navigate to your target folder and review the three files:
    • devices.csv
    • devices_all_filters_example.csv
    • silverback_api.ps1

Review file descriptions

  • To get an overall overview, please refer to the description below for each file:
File Description
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.
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.

Modify Connection String and Action

  • Perform a right-click on silverback_api.ps1 and open it with Notepad, Notepad++ or any text editor
  • Review the first section that contains File Path, URL, Token and Action
  • 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 in the same folder as the ps1 is located
  • Change the URL to your Silverback URL, e.g. silverback.imagoverum.com
  • Replace the example token with your previously created API Token
  • Enter the action that you want to execute. If you want to execute lock, replace refresh with lock according to the example below

For testing purposes, we recommend starting with refresh or lock as a command

param(
    [string]$FilePath = '.\devices.csv',
    [string]$Url = 'silverback.imagoverum.com',
    [string]$Token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IiIsInNjb3BlcyI6IntcIlNjb3Blc1wiOlsx',
    [string]$Action = 'lock' # block, unblock, lock, unlock, refresh, fulldevicewipe, deletecompanydata
  •  Press File and Save as a new file, e.g silverback_api_custom.ps1

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:\Temp
cd C:\Temp
  • Now run the newly created silverback_api_custom.ps1 with the following command
.\silverback_api_custom.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.

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> .\silverback_api_custom.ps1
File path: .\devices.csv
Silverback url: silverback.imagoverum.com
Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IiIsInNjb3BlcyI6IntcIlNjb3Blc1wiOlsx
Action: lock

Total 2 devices found in file

Processing row 1
deviceSerialNumber: J0Y7WYXGWR
Getting device data from https://silverback.imagoverum.com/api/v1/devices?details=true&$filter=deviceSerialNumber eq 'F4GX82XVJC68'
Found 1 devices satisfying fields
Executing 'lock' for device with Api ID 'C7AB83C0-6897-4066-B64A-58FEE647F0BF'. Url: https://silverback.imagoverum.com/api/v1/devices/C7AB83C0-6897-4066-B64A-58FEE647F0BF/actions/lock
Action 'lock' executed successfully for row 1

Processing row 2
deviceSerialNumber: F4GX82XVJC67
Getting device data from https://silverback.imagoverum.com/api/v1/devices?details=true&$filter=deviceSerialNumber eq 'J0Y7WYXGWR02'
Found 1 devices satisfying fields
Executing 'lock' for device with Api ID 'F49BC344-E471-498C-AA60-E80216F4490F'. Url: https://silverback.imagoverum.com/api/v1/devices/F49BC344-E471-498C-AA60-E80216F4490F/actions/lock
Action 'lock' executed successfully for row 2
PS C:\Silverback>

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
  • If you want to provide additional body parameters, like for fulldevicewipe, review the API help and add the parameters according to the example below:
$BodyByAction = @{
    'FullDeviceWipe' = @{
        'pin' = '666666';
        'RemoteWipeType' = 'WipePersistUserData';
        'ObliterationBehavior' = 'Default';
        'requiresNetworkTether' = $false;
        'disableProximitySetup' = $true;
        'PreserveDataPlan' = $true;
    };
}