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.

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.

How to...

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

  1. Click the plus icon to the right of the Input Variables section to open the Add Input Variable dialog box.
  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, Variable Value, 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 Administrators to provide the right variable mapping information when running jobs. For more information on each type, see below.
    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
Selection Variables The following information is displayed:
• Display Name: Display names are the names of the options the user will see when running the job. The device does not see these options. By default, one row is displayed and it's set to "Example Name" (and "Example Value"). Delete "Example Name" and add a display name of your choice. Click Add an Option to add a new display name.
• Value: The value to be mapped to the variable (defined in Name). By default, it's set to "Example Value". Delete this and add a value of your choice.

NOTE  The Value field has a limit of 255 characters.
Default 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 field. Common usage scenarios are service or application names, device usernames, etc.
Maximum variable value: 65534 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 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 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 below.

  1. Add a Description of the variable. Users can hover over an information icon next to the variable during the job scheduling process and see this description.
  2. Click Add. The input variable is added 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:

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 (e.g., "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