Tray Customization Worklets
This document provides guidance for using Automox Worklets™ to customize aspects of the Automox Tray experience on user devices. These worklets allow administrators to configure functionality beyond what is available in policy settings, such as defining a persistent message or enabling or disabling the tray interface. Additional customization worklets will be introduced in future agent releases.
Prerequisites:
- Your Automox plan must include worklets to access the worklet catalog.
- If your plan does not include access to the worklet catalog, you can manually create a worklet using the corresponding script provided for each item in this document.
- You must have the required permissions to create or manage worklets in your organization.
Customize Trusted Message
This section describes two worklets that allow you to customize the message displayed at the bottom of the Automox Tray notification window. This static message helps users recognize that the notification is provided by an authorized IT administrator or service provider and is safe to act on. These worklets are available for both Windows and macOS.
The message supports up to two lines of text (approximately 75 characters total). Text beyond this limit will be cut off. This configuration is not controlled through policy settings and must be applied using a worklet.
- Windows
- macOS
Windows – Tray Notification – Customize Trusted Message
This worklet sets a trusted message at the bottom of the Automox tray for Windows devices. The message is visible to the user whenever a tray notification appears and is intended to help establish the source as trusted IT communication.
Evaluation Code
Copy
<#
.SYNOPSIS
This Worklet evaluates if the Automox Tray is installed and determines if branding text configuration can be applied.
.DESCRIPTION
USAGE
< Script block section >
.\evaluation.ps1
< This evaluation script checks for the presence of the Automox Tray executable and determines if remediation should proceed. >
Example 1: Script checks for amagent-ui.exe in Program Files (x86)\Automox\ directory.
Example 2: If not found in x86 directory, checks Program Files\Automox\ directory.
.PARAMETER None
This evaluation script does not require any parameters.
.EXAMPLE
Simply run the evaluation script:
.\evaluation.ps1
.NOTES
This evaluation script checks for the Automox Tray executable (amagent-ui.exe) in standard installation directories.
If the tray is found, remediation will proceed to set the custom branding text.
If not found, remediation will be skipped.
********************************************************************
* ATTENTION *
********************************************************************
* THIS POLICY CAN ONLY BE RUN FROM: *
* - THE DEVICE PAGE *
* - THE "RUN POLICY" OPTION *
* - RUNNOW *
********************************************************************
PREREQUISITES
Powershell: 5.1 or later
OS: Windows 10, Windows 11, Windows Server 2016+
Automox Agent: Must be installed for branding to take effect
.HISTORY
Author : Maor Gornic
Date : 06/27/2025
Version : 1.0.0
Revisions : Initial release.
Author : Maor Gornic
Date : 06/30/2025
Version : 1.0.3
Revisions : Fixed issue where only first word of branding text was applied.
Author : Maor Gornic
Date : 07/31/2025
Version : 1.0.4
Revisions : Move to "Tray Management" category.
#>
#########################################
# PREDEFINED PARAMETERS
# Defining the Automox Tray directory
$automoxTrayDir = "${env:ProgramFiles(x86)}\Automox\amagent-ui.exe"
if (-not (Test-Path $automoxTrayDir)) {
$automoxTrayDir = "$env:ProgramFiles\Automox\amagent-ui.exe"
}
# Check for the existence of the Automox Tray executable
$fileExists = Test-Path -Path $automoxTrayDir
#########################################
# --! Evaluate Compliance !--
# Check if the Automox Tray is installed
if ( -not $fileExists) {
[ System.Console ]::Out.WriteLine( "Automox Tray is not installed. `nSkipping remediation.")
exit 0
}
else {
[ System.Console ]::Out.WriteLine( "Automox Tray is installed. `nProceeding with remediation.")
exit 1
}
Remediation code
Copy
<#
.SYNOPSIS
Sets custom branding text for the Automox agent notifications.
.DESCRIPTION
This worklet sets custom branding text for the Automox Agent UI using the
'amagent notifications set_branding_message --message' command.
The branding text is defined directly in the worklet and can be modified
as needed to customize the footer text.
.PARAMETER BrandingText
[ System.String ] : Required
The custom branding text to set for the Automox agent notifications.
This is defined directly in the worklet and can be modified as needed.
Note that the character limit for this text is 75 characters. Providing
text longer than this limit will result in an error.
.NOTES
HISTORY
Author : Maor Gornic
Date : 06/27/2025
Version : 1.0.0
Revisions : Initial release.
Author : Maor Gornic
Date : 06/30/2025
Version : 1.0.3
Revisions : Fixed issue where only first word of branding text was applied.
Author : Maor Gornic
Date : 07/31/2025
Version : 1.0.4
Revisions : Move to "Tray Management" category.
#>
#########################################
# PARAMETERS
# Define the custom branding text for agent notifications here
$BrandingText = "Managed by your IT Administrators"
#########################################
# FUNCTIONS
function Set-AmagentBrandingText
{
<#
.SYNOPSIS
Sets custom branding text for Automox agent notifications
.PARAMETER BrandingText
[ System.String ] : Mandatory
The custom branding text to display in agent notifications
.OUTPUTS
[ System.Boolean ]: Returns $true if successful, $false otherwise
.EXAMPLE
PS> Set-AmagentBrandingText -BrandingText "Managed by Contoso IT"
.NOTES
Author : Maor Gornic
Date : 06/27/2025
#>
[ OutputType( [ System.Boolean ] ) ]
param(
[ Parameter( Mandatory, Position = 0 ) ]
[ System.String ]
$BrandingText
)
try
{
# Define the amagent executable path
$amagentPath = "${env:ProgramFiles(x86)}\Automox\amagent.exe"
if (-not (Test-Path $amagentPath)) {
$amagentPath = "$env:ProgramFiles\Automox\amagent.exe"
}
# Verify amagent exists
if ( ![ System.IO.File ]::Exists( $amagentPath ) )
{
[ System.Console ]::Error.WriteLine( "Amagent executable not found at: $amagentPath" )
return $false
}
# Execute the amagent command
$result = & $amagentPath 'notifications' 'set_branding_message' '--message' $BrandingText 2>&1
$exitCode = $LASTEXITCODE
# Check the exit code
if ( $exitCode -eq 0 )
{
[ System.Console ]::Out.WriteLine( "Successfully set branding text: $BrandingText" )
return $true
}
else
{
[ System.Console ]::Error.WriteLine( "Failed to set branding text. Exit code: $exitCode" )
if ($result) {
[ System.Console ]::Error.WriteLine( "Error output: $result" )
}
return $false
}
}
catch
{
[ System.Console ]::Error.WriteLine( "Error setting branding text: $( $_.Exception.Message )" )
return $false
}
}
#########################################
# EXECUTION
# --! Set Agent Branding Text !--
[ System.Console ]::Out.WriteLine( "Setting Automox agent branding text..." )
$brandingResult = Set-AmagentBrandingText -BrandingText $BrandingText
if ( $brandingResult )
{
[ System.Console ]::Out.WriteLine( "Successfully configured agent branding text: '$BrandingText'" )
[ System.Console ]::Out.WriteLine( "Branding text has been applied to agent notifications." )
exit 0
}
else
{
[ System.Console ]::Error.WriteLine( "Failed to configure agent branding text." )
exit 1
}
macOS – Tray Notification – Customize Trusted Message
This worklet sets a trusted message at the bottom of the Automox tray for macOS devices. The message is visible to the user whenever a tray notification appears and is intended to help establish the source as trusted IT communication.
Evaluation Code
Copy
#!/bin/bash
#================================================================
# HEADER
#================================================================
# SYNOPSIS
# Evaluates if Automox Tray is installed and branding text needs to be set
#
# DESCRIPTION
# This script checks for the presence of the Automox agent tray application
# on macOS and determines if remediation should proceed to configure custom
# branding text for agent notifications.
#
# USAGE
# ./evaluation.sh
#
#================================================================
# IMPLEMENTATION
# version AXAGENT-3156_change_branding_text (www.automox.com) 1.0
# author Maor Gornic
#
#================================================================
# HISTORY
# 06/27/2025 : MGornic : Initial script creation
# 07/31/2025 : MGornic : Move to "Tray Management" category.
# 07/31/2025 : MGornic : Rename worklet name
#
#================================================================
# END_OF_HEADER
#================================================================
#########################################
# PREDEFINED PARAMETERS
# Define the Automox Tray application path on macOS
automox_tray_path="/Library/Application Support/Automox/agent-ui"
#########################################
# EVALUATE COMPLIANCE
# Check if the Automox Tray is installed
if [[ -d "$automox_tray_path" ]]; then
echo "Automox Tray is installed."
echo "Proceeding with remediation."
exit 1
else
echo "Automox Tray is not installed."
echo "Skipping remediation."
exit 0
fi
Remediation Code
Copy
#!/bin/bash
#================================================================
# HEADER
#================================================================
# SYNOPSIS
# Sets custom branding text for the Automox agent notifications on macOS.
#
# DESCRIPTION
# This worklet sets custom branding text for the Automox Agent UI using the
# 'amagent notifications set_branding_message --message' command.
# The branding text is defined directly in the worklet and can be modified
# as needed to customize the footer text. Providing text longer than this
# limit will result in an error.
#
# USAGE
# ./remediation.sh
#
# PARAMETER BrandingText
# The custom branding text to set for the Automox agent notifications.
# This is defined directly in the worklet and can be modified as needed.
# Note that the character limit for this text is 75 characters.
#
#================================================================
# IMPLEMENTATION
# version AXAGENT-3156_change_branding_text (www.automox.com) 1.0
# author Maor Gornic
#
#================================================================
# HISTORY
# 06/27/2025 : MGornic : Initial worklet creation
# 07/31/2025 : MGornic : Move to "Tray Management" category.
# 07/31/2025 : MGornic : Rename worklet name
#
#================================================================
# END_OF_HEADER
#================================================================
#########################################
# PARAMETERS
# Define the custom branding text for agent notifications here
BRANDING_TEXT="Managed by your IT Administrators"
#########################################
# FUNCTIONS
set_amagent_branding_text() {
local branding_text="$1"
# Define the amagent executable path on macOS
local amagent_path="/usr/local/bin/amagent"
# Verify amagent exists
if [[ ! -f "$amagent_path" ]]; then
echo "Error: Amagent executable not found at: $amagent_path" >&2
return 1
fi
# Execute the amagent command
if "$amagent_path" notifications set_branding_message --message "$branding_text"; then
echo "Successfully set branding text: $branding_text"
return 0
else
echo "Error: Failed to set branding text. Exit code: $?" >&2
return 1
fi
}
#########################################
# EXECUTION
echo "Setting Automox agent branding text..."
# Attempt to set the branding text
if set_amagent_branding_text "$BRANDING_TEXT"; then
echo "Successfully configured agent branding text: '$BRANDING_TEXT'"
echo "Branding text has been applied to agent notifications."
exit 0
else
echo "Failed to configure agent branding text." >&2
exit 1
fi
Remove Custom Trusted Message
To remove an applied custom message, update the text in the worklet or apply a new worklet with empty text to reset to the default messaging.
Enable or Disable the Automox Tray
This section includes two worklets that let administrators enable or disable the Automox tray on supported Windows devices. Disabling the tray prevents it from displaying to users, while enabling it restores its visibility. These settings are applied locally through the presence or absence of a control file and are not managed through policy.
- Disable Tray
- Enable Tray
Disable Agent Tray
This worklet disables the Automox tray on supported Windows devices by creating a local control file. When the tray is disabled, it no longer appears to the user.
Evaluation code
Copy
<#
.SYNOPSIS
Evaluates if the Automox Agent Tray is installed and currently enabled.
.DESCRIPTION
This evaluation script checks for the presence of the Automox Agent Tray executable
and the absence of the 'amagent-ui-disable' file to determine if the tray can be disabled.
.NOTES
HISTORY
Author : Maor Gornic
Date : 07/10/2025
Version : 1.0.0
Revisions : Initial release.
PREREQUISITES
Powershell: 5.1 or higher
OS: Windows 10, Windows 11, Windows Server 2016+
Automox Agent Tray: Must be installed for tray configuration
EXIT CODES
0 : Agent Tray not found or already disabled, skip remediation
1 : Agent Tray found and enabled, proceed with remediation
#>
#########################################
# EVALUATION
# Check for Automox Agent Tray in common installation paths
$amagentTrayPaths = @(
"${env:ProgramFiles(x86)}\Automox\amagent-ui.exe",
"${env:ProgramFiles}\Automox\amagent-ui.exe"
)
$automoxDir = $null
$agentTrayFound = $false
foreach ($path in $amagentTrayPaths) {
if (Test-Path $path) {
$agentTrayFound = $true
$automoxDir = Split-Path $path -Parent
[ System.Console ]::Out.WriteLine("Automox Agent Tray found at: $path")
break
}
}
if (-not $agentTrayFound) {
[ System.Console ]::Out.WriteLine("Automox Agent Tray not found. Skipping remediation.")
exit 0
}
# Check if the disable file exists
$disableFilePath = Join-Path $automoxDir "amagent-ui-disable"
if (Test-Path $disableFilePath) {
[ System.Console ]::Out.WriteLine("Agent Tray is already disabled. No action needed.")
exit 0
} else {
[ System.Console ]::Out.WriteLine("Agent Tray is currently enabled. Remediation will disable it.")
exit 1
}
Remediation code
Copy
<#
.SYNOPSIS
Disables the Automox Agent Tray on Windows systems.
.DESCRIPTION
This worklet disables the Automox agent tray by creating the
'amagent-ui-disable' file in the Automox directory.
.NOTES
HISTORY
Author : Maor Gornic
Date : 07/10/2025
Version : 1.0.0
Revisions : Initial release.
PREREQUISITES
Powershell: 5.1 or higher
OS: Windows 10, Windows 11, Windows Server 2016+
Automox Agent Tray: Must be installed for tray configuration
#>
#########################################
# FUNCTIONS
function Disable-AmagentTray
{
<#
.SYNOPSIS
Disables Automox agent tray by creating the disable file
.OUTPUTS
[ System.Boolean ]: Returns $true if successful, $false otherwise
.EXAMPLE
PS> Disable-AmagentTray
.NOTES
Author : Maor Gornic
Date : 07/10/2025
#>
[ OutputType( [ System.Boolean ] ) ]
param()
try
{
# Define the Automox directory path
$automoxDir = "${env:ProgramFiles(x86)}\Automox"
if (-not (Test-Path $automoxDir)) {
$automoxDir = "${env:ProgramFiles}\Automox"
}
# Verify Automox directory exists
if ( ![ System.IO.Directory ]::Exists( $automoxDir ) )
{
[ System.Console ]::Error.WriteLine( "Automox directory not found at expected locations." )
return $false
}
# Define the disable file path
$disableFilePath = Join-Path $automoxDir "amagent-ui-disable"
# Create the disable file to disable the tray
if ( -not ( Test-Path $disableFilePath ) )
{
New-Item -Path $disableFilePath -ItemType File -Force | Out-Null
[ System.Console ]::Out.WriteLine( "Created disable file: $disableFilePath" )
[ System.Console ]::Out.WriteLine( "Agent Tray has been disabled." )
}
else
{
[ System.Console ]::Out.WriteLine( "Disable file already exists, tray already disabled." )
}
return $true
}
catch
{
[ System.Console ]::Error.WriteLine( "Error disabling agent tray: $( $_.Exception.Message )" )
return $false
}
}
#########################################
# EXECUTION
# --! Disable Agent Tray !--
[ System.Console ]::Out.WriteLine( "Disabling Automox agent tray..." )
$disableResult = Disable-AmagentTray
if ( $disableResult )
{
[ System.Console ]::Out.WriteLine( "Agent tray disable operation completed successfully." )
exit 0
}
else
{
[ System.Console ]::Error.WriteLine( "Failed to disable agent tray." )
exit 1
}
Enable Agent Tray
This worklet enables the Automox tray on supported Windows devices by removing the local control file. When enabled, the tray will reappear for users and resume standard functionality.
Evaluation code
Copy
<#
.SYNOPSIS
Evaluates if the Automox Agent Tray is installed and currently disabled.
.DESCRIPTION
This evaluation script checks for the presence of the Automox Agent Tray executable
and the 'amagent-ui-disable' file to determine if the tray can be enabled.
.NOTES
HISTORY
Author : Maor Gornic
Date : 07/10/2025
Version : 1.0.0
Revisions : Initial release.
PREREQUISITES
Powershell: 5.1 or higher
OS: Windows 10, Windows 11, Windows Server 2016+
Automox Agent Tray: Must be installed for tray configuration
EXIT CODES
0 : Agent Tray not found or already enabled, skip remediation
1 : Agent Tray found and disabled, proceed with remediation
#>
#########################################
# EVALUATION
# Check for Automox Agent Tray in common installation paths
$amagentTrayPaths = @(
"${env:ProgramFiles(x86)}\Automox\amagent-ui.exe",
"${env:ProgramFiles}\Automox\amagent-ui.exe"
)
$automoxDir = $null
$agentTrayFound = $false
foreach ($path in $amagentTrayPaths) {
if (Test-Path $path) {
$agentTrayFound = $true
$automoxDir = Split-Path $path -Parent
[ System.Console ]::Out.WriteLine("Automox Agent Tray found at: $path")
break
}
}
if (-not $agentTrayFound) {
[ System.Console ]::Out.WriteLine("Automox Agent Tray not found. Skipping remediation.")
exit 0
}
# Check if the disable file exists
$disableFilePath = Join-Path $automoxDir "amagent-ui-disable"
if (Test-Path $disableFilePath) {
[ System.Console ]::Out.WriteLine("Agent Tray is currently disabled. Remediation will enable it.")
exit 1
} else {
[ System.Console ]::Out.WriteLine("Agent Tray is already enabled. No action needed.")
exit 0
}
Remediation code
Copy
<#
.SYNOPSIS
Enables the Automox Agent Tray on Windows systems.
.DESCRIPTION
This worklet enables the Automox agent tray by removing the
'amagent-ui-disable' file from the Automox directory if it exists.
.NOTES
HISTORY
Author : Maor Gornic
Date : 07/10/2025
Version : 1.0.0
Revisions : Initial release.
PREREQUISITES
Powershell: 5.1 or higher
OS: Windows 10, Windows 11, Windows Server 2016+
Automox Agent Tray: Must be installed for tray configuration
#>
#########################################
# FUNCTIONS
function Enable-AmagentTray
{
<#
.SYNOPSIS
Enables Automox agent tray by removing the disable file
.OUTPUTS
[ System.Boolean ]: Returns $true if successful, $false otherwise
.EXAMPLE
PS> Enable-AmagentTray
.NOTES
Author : Maor Gornic
Date : 07/10/2025
#>
[ OutputType( [ System.Boolean ] ) ]
param()
try
{
# Define the Automox directory path
$automoxDir = "${env:ProgramFiles(x86)}\Automox"
if (-not (Test-Path $automoxDir)) {
$automoxDir = "${env:ProgramFiles}\Automox"
}
# Verify Automox directory exists
if ( ![ System.IO.Directory ]::Exists( $automoxDir ) )
{
[ System.Console ]::Error.WriteLine( "Automox directory not found at expected locations." )
return $false
}
# Define the disable file path
$disableFilePath = Join-Path $automoxDir "amagent-ui-disable"
# Remove the disable file to enable the tray
if ( Test-Path $disableFilePath )
{
Remove-Item -Path $disableFilePath -Force
[ System.Console ]::Out.WriteLine( "Removed disable file: $disableFilePath" )
[ System.Console ]::Out.WriteLine( "Agent Tray has been enabled." )
}
else
{
[ System.Console ]::Out.WriteLine( "Disable file does not exist, tray already enabled." )
}
return $true
}
catch
{
[ System.Console ]::Error.WriteLine( "Error enabling agent tray: $( $_.Exception.Message )" )
return $false
}
}
#########################################
# EXECUTION
# --! Enable Agent Tray !--
[ System.Console ]::Out.WriteLine( "Enabling Automox agent tray..." )
$enableResult = Enable-AmagentTray
if ( $enableResult )
{
[ System.Console ]::Out.WriteLine( "Agent tray enable operation completed successfully." )
exit 0
}
else
{
[ System.Console ]::Error.WriteLine( "Failed to enable agent tray." )
exit 1
}
