Ninjaone Script Variables

Related Skills

• ninjaone-environment-variables - Agent-provided context variables like NINJA_ORGANIZATION_NAME
• ninjaone-custom-fields - Persistent device data that complements script variables
• ninjaone-tags - Use script variables to configure tag names for flexible automation

Script Variables Overview

NinjaOne converts script variables defined in the platform into environment variables when the script executes.

Key Characteristics

• Always Strings: All script variables are sent as strings, regardless of intended type
• Empty Values: Empty (non-mandatory) variables are sent as empty strings ("")
• Type Conversion Required: Scripts must cast variables to appropriate types
• No Strong Typing: Platform does not enforce type constraints
• Maximum Variables: A script can have up to 20 variables maximum
• Unicode Support: Unicode characters (non-Latin scripts, symbols, Kanji, emojis) are supported
• Special Characters: The following characters cannot be used: Å Ä Ö & | ; $ > < \ !`
• Activity Logging: Variable changes generate activity log entries in System and Device dashboards
• Environment Conflicts: Scripts fail if system already has an environment variable with the same name

Variable Configuration

When creating script variables in the NinjaOne script editor:

Script Variable Types and Formats

Referencing Variables by Script Type

Different scripting languages use different syntax to reference environment variables:

Inserting Variables in Script Editor

Keyboard Shortcut: Press CTRL + Space in the script editor to open the variable selector contextual menu.

• Hover over variables to see descriptions
• Custom fields also appear in the variable selector
• Variables are automatically formatted for the selected script language
• Variables can be reordered by dragging them up or down in the Script Variables pane

Variable Handling Example

# Script variables from NinjaOne (received as environment variables)
$serverName = $env:ServerName
if ([string]::IsNullOrWhiteSpace($serverName)) {
    Write-Error "ServerName is required but was not provided"
    exit 1
}

# Convert and validate Port (Integer type)
$port = 443
if (-not [string]::IsNullOrWhiteSpace($env:Port)) {
    try {
        $port = [int]$env:Port
        if ($port -lt 1 -or $port -gt 65535) {
            Write-Warning "Port value '$port' is outside valid range. Using default: 443"
            $port = 443
        }
    } catch {
        Write-Warning "Failed to convert Port. Using default: 443"
        $port = 443
    }
}

# Convert checkbox/boolean
$enableLogging = $false
if (-not [string]::IsNullOrWhiteSpace($env:EnableLogging)) {
    $enableLogging = $env:EnableLogging -eq 'true'
}

# Convert Date/Time (ISO 8601 format)
$maintenanceWindow = $null
if (-not [string]::IsNullOrWhiteSpace($env:MaintenanceWindow)) {
    try {
        $maintenanceWindow = [DateTime]::Parse($env:MaintenanceWindow, $null, [System.Globalization.DateTimeStyles]::RoundtripKind)
    } catch {
        Write-Warning "Failed to parse MaintenanceWindow. Ignoring."
    }
}

# Validate IP Address
$ipAddress = $null
if (-not [string]::IsNullOrWhiteSpace($env:IPAddress)) {
    try {
        $ipAddress = [System.Net.IPAddress]::Parse($env:IPAddress)
    } catch {
        Write-Warning "Invalid IP Address format. Ignoring."
    }
}

VBScript Example

' VBScript requires explicit environment variable expansion
Set wshShell = CreateObject("WScript.Shell")
serverName = wshShell.ExpandEnvironmentStrings("%ServerName%")
port = wshShell.ExpandEnvironmentStrings("%Port%")

If serverName = "" Then
    WScript.Echo "ServerName is required"
    WScript.Quit 1
End If

' Convert port to integer
If port <> "" Then
    portNumber = CInt(port)
Else
    portNumber = 443
End If

Batch Script Example

@echo off
REM Batch script variables
SET SERVER_NAME=%ServerName%
SET PORT=%Port%

IF "%SERVER_NAME%"=="" (
    echo ServerName is required
    exit /b 1
)

IF "%PORT%"=="" (
    SET PORT=443
)

echo Connecting to %SERVER_NAME% on port %PORT%

Type Conversion Helper

function ConvertTo-TypedValue {
    <#
    .SYNOPSIS
        Converts NinjaOne script variable (string) to specified type with validation.

    .EXAMPLE
        $port = ConvertTo-TypedValue -Value $env:Port -Type 'Int32' -DefaultValue 443 -Min 1 -Max 65535

    .EXAMPLE
        $enabled = ConvertTo-TypedValue -Value $env:EnableFeature -Type 'Boolean' -DefaultValue $false
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [AllowEmptyString()]
        [string]$Value,

        [Parameter(Mandatory)]
        [ValidateSet('Int32', 'Int64', 'Boolean', 'DateTime', 'Double', 'Decimal', 'IPAddress')]
        [string]$Type,

        [Parameter()]
        $DefaultValue,

        [Parameter()]
        [object]$Min,

        [Parameter()]
        [object]$Max
    )

    process {
        if ([string]::IsNullOrWhiteSpace($Value)) {
            if ($PSBoundParameters.ContainsKey('DefaultValue')) {
                return $DefaultValue
            }
            return $null
        }

        try {
            $convertedValue = switch ($Type) {
                'Int32' { [int]$Value }
                'Int64' { [long]$Value }
                'Boolean' { $Value -eq 'true' }
                'DateTime' { [DateTime]::Parse($Value, $null, [System.Globalization.DateTimeStyles]::RoundtripKind) }
                'Double' { [double]$Value }
                'Decimal' { [decimal]$Value }
                'IPAddress' { [System.Net.IPAddress]::Parse($Value) }
            }

            # Range validation for numeric types
            if ($Type -in @('Int32', 'Int64', 'Double', 'Decimal')) {
                if ($PSBoundParameters.ContainsKey('Min') -and $convertedValue -lt $Min) {
                    Write-Warning "Value $convertedValue is below minimum $Min. Using default."
                    return $DefaultValue
                }
                if ($PSBoundParameters.ContainsKey('Max') -and $convertedValue -gt $Max) {
                    Write-Warning "Value $convertedValue is above maximum $Max. Using default."
                    return $DefaultValue
                }
            }

            return $convertedValue

        } catch {
            Write-Warning "Failed to convert '$Value' to $Type. Using default."
            if ($PSBoundParameters.ContainsKey('DefaultValue')) {
                return $DefaultValue
            }
            return $null
        }
    }
}

Variable Visualization in UI

When running a script with variables, NinjaOne renders an interactive form:

• Mandatory fields are marked with an asterisk (*)
• Empty mandatory fields turn red when attempting to run the script
• Description tooltips appear as info icons next to variable names
• Default values are pre-populated in form fields
• Dropdown options appear as selectable lists

Preset Parameters

NinjaOne supports passing parameters directly to scripts at runtime using preset parameter strings.

Key Characteristics

• Runtime Input: Parameters passed when script executes
• Positional Parameters: Consumed in order
• Space-Delimited: Multiple parameters separated by spaces
• Quote Support: Values with spaces must be quoted

PowerShell Example

<#
.NOTES
    NinjaOne Preset Parameters:
    - Parameter 1: Username (supports spaces when quoted)
    - Parameter 2: Password

    Example preset parameter strings:
    - "John Doe" SecurePass123
    - Alice P@ssw0rd!
#>

param(
    [Parameter(Position = 0, Mandatory = $true)]
    [string]$Username,

    [Parameter(Position = 1, Mandatory = $true)]
    [string]$Password
)

# Validation
if ([string]::IsNullOrWhiteSpace($Username)) {
    Write-Error "Username is required"
    exit 1
}

# Main logic
net user "$Username" "$Password" /add

When to Use Each Approach

Common Mistakes

1. Not handling empty strings for non-mandatory variables - Non-mandatory variables arrive as empty strings "" when not filled in, not as $null. Direct type casts like [int]$env:Port throw an exception on an empty string. Always guard with [string]::IsNullOrWhiteSpace($env:Port) before converting.
2. Checkbox comparison against the wrong value - Checkbox variables send "true" or "false" as strings, not PowerShell booleans. if ($env:EnableFeature) is always $true for a non-empty string. Use $env:EnableFeature -eq 'true' for correct boolean evaluation.
3. Special characters in variable names - Characters like &, |, ;, $, and backtick cannot be used in variable names or values. Scripts with these characters fail at runtime without a clear error.
4. Naming conflicts with system environment variables - If a script variable shares a name with an existing system environment variable (e.g., PATH, TEMP), the script will fail or use the wrong value. Prefix custom variable names (e.g., NR_Port) to avoid collisions.
5. Assuming DateTime locale - Date/Time variables use ISO 8601 with timezone (YYYY-MM-ddTHH:MM:SS.SSSZ). Parsing with [DateTime]::Parse($value) without DateTimeStyles.RoundtripKind loses timezone info and can shift the time. Use [DateTime]::Parse($value, $null, [System.Globalization.DateTimeStyles]::RoundtripKind).

Best Practices

1. Always Validate Input - Check for empty strings and validate data types
2. Use Descriptive Names - Clear variable names improve maintainability
3. Set Defaults - Provide sensible defaults for non-mandatory variables
4. Add Descriptions - Use tooltips to guide technicians using the script
5. Handle Conversion Errors - Always wrap type conversions in try-catch blocks
6. Log Activities - Remember that variable changes are logged to activity feeds
7. Check Environment Conflicts - Be aware of existing system environment variables
8. Limit Variables - Stay under the 20-variable maximum per script
9. Avoid Special Characters - Don't use: Å Ä Ö & | ; $ > < \ !`
10. Use Unicode Carefully - While supported, test Unicode characters thoroughly
11. Order Logically - Arrange variables in a logical order for the technician UI
12. Leverage Custom Fields - Custom fields are also available in the variable selector