Input variables

About input variables

One of the facets of the Datto RMM scripting engine is the ability to use input variables in your scripts. This lets you re-use a single component to carry out multiple tasks without having to modify the script itself, or create (and maintain) duplicate components.

Input variables allow you to define values in your script at runtime, rather than having them hard coded into the script.

EXAMPLE  For example, if you regularly had to restart a number of Windows services (netlogon service, DNS client service, DHCP client service), you could create a separate component for each service. They would be identical, except for the name of the service that was being restarted.
If you used a variable ("servicename") instead, you would need to create only one component (called "Restart Service"). The script would prompt you for the name of the service to be restarted.

NOTE   While you can create your own input variables, predefined internal Agent variables and User-defined field (UDF) variables are available for you to use when creating or editing components.

How do input variables work in Datto RMM?

Input variables in Datto RMM are a two-step process:

  1. First, the Administrator writing the script must refer to the input variable as if it were any other variable set within the script itself. One might, for example, check to see if the variable in question is "true" or "false" and then act upon it, without defining the variable itself at any point within the code. The name, default value, and type (string, Boolean, etc.) are defined as part of the component and saved as part of the metadata.
  2. When the component is run as part of a job, the user running the component is prompted to input the value they wish the input variable to reflect, which affects how the script runs. These variables are set as environment variables within the endpoint's script interpreter and are treated as if they had been defined as part of the script.

IMPORTANT  If a third party opens a script containing input variables, the input variable will be visible and not the value hidden behind it (these are defined at runtime). Input variables are a great way to obscure information if you suspect someone might inspect the script files on a local system.

How to...

Input variables are defined when you create or edit a component. Refer to Creating a component.

  1. Click Add Variable in the Variables section.
  1. Enter a Name for the variable. Enter it in the way the script will refer to it. Do not include the characters used to declare the variable, and do not use any space within the variable name.

EXAMPLE  Use exampleVar as opposed to %exampleVar% or $env:exampleVar.

  1. Select a Type for the variable. The options include Selection, String, Date, and Boolean.
    Although all input variables set in Datto RMM are passed through to the script interpreter as strings (even Booleans), Datto RMM offers four different types of input variables to make it easier for administrator users to provide the right variable mapping information when running jobs. For more information on each type, see the next sections.
    The Default field is also discussed within each type.

This variable type permits the Administrator creating the component to define specific options for their script to follow. These options work on the basis of multiple-choice mappings for a single variable, which significantly reduces the margin of error when running the script.

You can configure the following details specific to this variable type:

Field Description
Display Name and Value Display names are the names of the options the user will see when running the job. The device does not see these options.
The value is the value to be mapped to the variable (defined in Name).

Click Add Values and add a display name and a value of your choice. Click Add Value again to add another row. Click OK to save the entries.

NOTE  Display names must be unique.

NOTE  The Value field has a limit of 255 characters.
Default value From the drop-down list, select the default display name the user will see when running the job.

The most common input variable type. A simple text input field allows the user to map the input variable with any arbitrary data during the job scheduling process. Optionally, the Administrator can add a default value to the Default value field. Common usage scenarios are service or application names, device usernames, etc.
Variable value limit: 20,000 characters.

In cases where a standardized date format is required, using this input variable type permits the user to select an explicit date from a calendar during the job scheduling process. Optionally, the Administrator can add a default value to the Default value field by clicking the calendar icon and selecting a date.

This variable type is particularly useful in cases where a deployment operates across geographical boundaries where different date formats are used.

A basic True/False Boolean provides users with a simple decision, minimizing the chance of passing through invalid data. Optionally, the Administrator can choose a default value (True/False) in the Default value field.

NOTE  Care must be taken with this option when writing PowerShell scripts. Booleans in Datto RMM are set as strings and do not use the dedicated $true and $false environment variables. A valid PowerShell usage scenario for a Boolean input variable (called "exampleVariable"), which also takes into account PowerShell's requirement for explicit definition of environment variables, can be seen in the Examples section.

  1. Enter a description for the variable. Users can see this description next to the variable during the job scheduling process.
  2. Click Add to add the input variable to the list.
  1. When you run this component as a quick job, for example, you are able to specify the value that this should be set to when it runs. This example shows a variable type of Selection:

Call a variable in a script in the same manner as a variable that had been defined locally. In Batch, for example, calling the variable %test% when it is set as an input variable will return the data assigned to it within Datto RMM.

Refer to the individual script examples in the next section for more information.

Examples

This example Batch script uses a Boolean-type input variable called "exampleBoolean" and a value-type input variable called "exampleValue" set to the value "Datto".

@echo off
if %exampleBoolean% equ true (echo You are using a Component with %exampleValue%.)

This example PowerShell script uses a Boolean-type input variable called "exampleVariable". PowerShell scripts require input variables to be explicitly referred to as environment variables with the "$env:" prefix.

Note that the script checks the string value of the variable and not whether or not it was defined. Traditional methods (for example, "If example variable is not defined, do abc, else do xyz") will not work here as Booleans are defined as strings when set via Datto RMM input variables.

if ($env:exampleVariable -eq "true") {
	write-host "Example variable was set to true"
} else {
	write-host "Example variable was not set to true"
}

This example Shell script can be run on macOS or Linux endpoints. It uses a Boolean-type input variable called "exampleBoolean" and a value-type input variable called "exampleNumber" set to the number 4.

#!/bin/bash
if [ "$exampleBoolean" = "true" ]
	then
		printf "There are $exampleNumber lights"
	else
		printf "Not checking number of lights"
fi