Toolbox Scripting API Guide
The scripts that you include in your toolbox can take advantage of SimpleHelp collected data and functionality to offer a wider range of scripting ability. This guide details how you can embed SimpleHelp Scripting API calls into your scripts to take advantage of this.
The SimpleHelp Scripting API isn't a new language, but rather a set of instructions that you can embed directly into your existing scripts. When your scripts are executed in SimpleHelp the server and remote machine will process your script and determine what metrics to insert into the script or actions to take.
Function Call Types
Scripting API calls can be grouped into two categories:
- Data Input Functions - these calls bring values into your script for use. SimpleHelp will substitute in values before the script is executed. These functions are tagged with PRE.
- Data Output Functions - these calls report values to SimpleHelp. SimpleHelp will identify these method calls in the output that your script produces. These functions are tagged with POST.
Data Input Functions
Some Scripting API functions fetch data that can be used in your script. For example, the scripting call ServerUtilsGetCpuUsage
fetches the CPU usage of the specified Remote Access machine and allows you to use it within your script.
In any case like this, the Scripting API function will run before the script itself runs, and will resolve to a literal value, as if you had typed it directly into the script.
For example, a windows batch script such as the following:
echo ServerUtilsGetCpuUsage(...)
would be equivalent simply to:
echo 95
and the script, when run, would output 95
.
Data Output Functions
Some Scripting API functions allow your script to push data back into the server, or to remote machines. In these cases, SimpleHelp will substitute in the appropriate scripting language calls to action the Script API call that you want to make.
For example, a script containing the following line:
ServerUtilsSendEmail(...)
will have a number of scripting language-specific calls placed into it so that when your script reaches this point, the request will be made to the SimpleHelp Scripting API and the email will be sent.
Security and Permissions
A Toolbox script that takes advantage of the Scripting API can perform more powerful and complicated actions within SimpleHelp. To prevent malicious use of the Scripting API a number of important security features exist to restrict access to the API so that they can be called only by the intended technicians. These steps are all fully automated and don't require any technician or administrator input, but they do influence how the API is used.
The security approach taken is that no machine has any access to any of the Scripting API at all, unless it has been specifically granted by a technician running a Tool against that machine. When a technician runs a Tool, the script is scanned to determine whether the Tool uses the Scripting API. A permission is granted within the server based on these required calls.
The permission is stored within the SimpleHelp Server and when the Tool is run. As it makes calls into the Scripting API, the individual calls are checked by the SimpleHelp Server to verify that they are allowed, and that they are using the data or parameters expected for that call. When the tool has finished, the permission is deleted from the SimpleHelp Server and no access is allowed unless another tool is run by a Technician.
This ensures that Scripting API is used only in accordance with what Technicians specify.
Using Script Variables in API Calls
Tool scripts that use scripting variables may use those variables within some Scripting API calls. It is not possible to use script variables within Data Input API calls as these calls are resolved before the script runs and their result is substituted directly into the script.
Data Output API calls may use variables within the call parameters, but should use inline variables rather than string concatenation. For example, the following calls will substitute in variable
and log the result to the server log:
Batch script:
ServerUtilsLog("The variable value is %variable%")
Powershell script:
ServerUtilsLog("The variable value is $variable")
Bash script:
ServerUtilsLog("The variable value is $variable")
Entities
Certain Scripting API calls receive one or more values when they are called. Often these values include a label indicating what they are. These values are called Entities
and begin with a @
symbol, such as:
@Emails(contact@example.com)
An entity wraps a value and fixes it within the script so that it cannot change. This allows SimpleHelp to ensure that the permissions for this API call are set correctly and that the script cannot abuse the API call in any way.
For example, the @Emails(...)
entity shown above specifies that the email address contact@example.com
should be used. Since this is specified within an entity, it will be part of the Permission Set for this API call and the SimpleHelp server will refuse to send an email (requested by the script) to any other address.
Entities are primarily a security feature and you don't generally need to worry about using them correctly. Instead you can simply follow the examples for the API calls you wish to use.
Scripting API Functions
The following is a comprehensive list of SimpleHelp Scripting API functions that you can use within any Tool script. Each function is marked as (Input)
or (Post)
to show whether it is run before or after your script. Typically, API calls which request data to be embedded in your script will run before, and API calls which are actions taken by your script will run after.
Pre / Input API Functions
Download File
ServerUtilsDownloadFile( _ , _ )
PRE
Download an instructional PDF from a website and save it into C: drive
ServerUtilsDownloadFile("C:\important.pdf", "https://example.com/downloads/instructions.pdf")
The ServerUtilsDownloadFile function requests that SimpleHelp download a file from a web address before your script runs. Although some scripting languages support this already, this makes the capability available in all scripting languages.
Param 1: Filename to download the file to
Param 2: URL or web address to download the file from
Get Machine Name
ServerUtilsGetMachineName()
PRE
Fetch the Remote Access Service name without it's group
ServerUtilsGetMachineName()
Fetch the Remote Access Service name of the machine the script is running on. Available as of 5.2.11.
Resolves to: the machine name as unquoted text in your script
Get Machine Group
ServerUtilsGetMachineGroup()
PRE
Fetch the Remote Access Service group, separated with forward slashes (e.g. USA/California)
ServerUtilsGetMachineGroup()
Fetch the Remote Access Service group of the machine the script is running on, separated by slashes. Available as of 5.2.11.
Resolves to: the machine group as unquoted text with group names separated by slashes in your script (e.g. World/USA/DC)
Get Machine Full Name
ServerUtilsGetMachineFullName()
PRE
Fetch the Remote Access Service full name (e.g. USA/California/MyServer)
ServerUtilsGetMachineFullName()
Fetch the Remote Access Service name and group, separated by slashes, of the machine the script is running on. Available as of 5.2.11.
Resolves to: the machine full name as unquoted text with group names separated by slashes in your script (e.g. World/USA/DC/Machine)
Get Machine Property
ServerUtilsGetMachineProperty( _ , _ )
PRE
Fetch the property "Customer" for the Remote Access machine that the script is running on.
ServerUtilsGetMachineProperty(@ThisMachine(), Customer)
Fetch the property "Emergency Phone" for the Remote Access machine with the name "Backend DB"
ServerUtilsGetMachineProperty(@Machine(Backend DB), Emergency Phone)
Fetch a property for a remote access machine (from the machine-specific properties list within the Technician App Access tab).
Param 1: @Machine(...) or @ThisMachine()
Param 2: Property name
Resolves to: the property value as unquoted literal text within your script
Get Machine Group Property
ServerUtilsGetMachineGroupProperty( _ , _ )
PRE
Fetch the property "Customer" for the Remote Access machine group "USA"
ServerUtilsGetMachineGroupProperty(@MachineGroup(USA), Customer)
Fetch a property for a remote access machine group (from the properties list within the Technician App Access tab). Available as of 5.2.12.
Param 1: @MachineGroup
Param 2: Property name
Resolves to: the property value as unquoted literal text within your script
Pull a File
ServerUtilsPrePullFile( _ , _ , _ )
PRE
Fetch a utility folder from a remote machine called "TechUtilities"
ServerUtilsPrePullFile(@Machine(TechUtilities), @Path("C:\Tools"), @Folder("C:\Tools"))
Fetch a document from a remote machine and place it into the same folder as the script
ServerUtilsPrePullFile(@Machine(TechUtilities), @Path("C:\Tools\Scanner.exe"), @Folder(.))
Pull a file from a Remote Access machine to a local folder and wait for the transfer to complete before the script runs.
Param 1: @Machine or @ThisMachine
Param 2: @Path remote file path to pull (may be a file or folder)
Param 3: @Folder Local folder path to place the file into (may be a file or folder and relative paths beginning .
may also be used)
Push a File
ServerUtilsPrePushFile( _ , _ , _ )
PRE
Push a document folder onto a remote machine called "Local Backups"
ServerUtilsPrePushFile(@Machine(Local Backups), @Folder("E:\All Backups"), @Path("C:\Users\abc\Documents"))
Push a document to a remote machine from the same folder as the script
ServerUtilsPrePushFile(@Machine(Gathered Data), @Folder("E:\Log Files"), @Path("CopiedLogFile.log"))
Push a file to a folder on a Remote Access machine and wait for the transfer to complete before the script runs.
Param 1: @Machine or @ThisMachine
Param 2: @Folder remote folder path to place the file into
Param 3: @Path local file path to push (may be a file or folder and relative paths beginning .
may also be used)
Compare Files or Directories
ServerUtilsCompareFiles( _ , _ , _ )
PRE
Compare source and destination data on two machines being kept in sync
ServerUtilsCompareFiles(@Machines(Web Server, /opt/criticaldata, Backup Server, /opt/criticaldata))
Compare two files or directories on Remote Access Services to determine if they are equivalent in terms of data, ignoring file metadata like last modification times and permissions. Available as of 5.2 beta 4.
Param 1: @Machine or @ThisMachine
Param 2: file or folder path for the machine specified in Param 1
Param 3: @Machine or @ThisMachine
Param 4: file or folder path for the machine specified in Param 3
Resolves to: 0 if the files or folders are the same, or 1 if they are not
Get CPU Usage
ServerUtilsGetCpuUsage( _ )
PRE
Get the CPU usage for the local machine
ServerUtilsGetCpuUsage(@ThisMachine())
Fetches the current CPU usage in percent rounded to the nearest integer and substitutes it into your script as a simple literal value.
Param 1: @Machine or @ThisMachine
Get Memory Usage
ServerUtilsGetMemoryUsage( _ )
PRE
Get the Memory usage for a remote machine
ServerUtilsGetMemoryUsage(@Machine(Web Server))
Fetches the current Memory usage (physical RAM) in percent rounded to the nearest integer and substitutes it into your script as a simple literal value.
Param 1: @Machine or @ThisMachine
Get WAN IP Address
ServerUtilsGetWanIp( _ )
PRE
Get the WAN IP of a remote machine
ServerUtilsGetWanIp(@Machine(Customer Computer))
Fetches the current WAN IP (external IP address, as seen by the SimpleHelp server) for a remote access machine and substitutes it into your script as a simple literal value.
Param 1: @Machine or @ThisMachine
Get WiFi Signal
ServerUtilsGetWifiMbit( _ )
PRE
Get the WiFi speed of the local machine
ServerUtilsGetWifiMbit(@ThisMachine())
Fetches the current WiFi signal, measured in Mbit/s bandwidth for a remote access machine and substitutes it into your script as a simple literal value.
Param 1: @Machine or @ThisMachine
Get WiFi Signal (%)
ServerUtilsGetWifiPercent( _ )
PRE
Get the WiFi speed of a remote machine
ServerUtilsGetWifiPercent(@Machine(Customer Computer))
Fetches the current WiFi signal, measured in percent, for a remote access machine and substitutes it into your script as a simple literal value.
Param 1: @Machine or @ThisMachine
Get RDP Sessions
ServerUtilsGetRdpSessions( _ )
PRE
Get the number of RDP sessions open on a remote machine
ServerUtilsGetRdpSessions(@Machine(Terminal Server))
Fetches the number of RDP sessions open on the specified remote access machine and substitutes it into your script as a simple literal value.
Param 1: @Machine or @ThisMachine
Wake On Lan
ServerUtilsWakeOnLan( _ )
PRE
Send a Wake On Lan Request to multiple Machines
ServerUtilsWakeOnLan(@Machines(Server1, Server2, Server3))
Requests that the SimpleHelp server issue a Wake-on-LAN message from one or more appropriately placed online Remote Access Services to wake one or more offline Remote Access Services. Use the API call WaitUntilOnline (see below) to also wait until one or more machines have actually come online. Available as of 5.2 beta 4.
Param 1: @Machine
, @Machines
or @ThisMachine
Wait for Online Service
ServerUtilsWaitUntilOnline( _ )
PRE
Wait up to five minutes for machines to come online
ServerUtilsWaitUntilOnline(@Machines(Test Server, Test Client 1, Test Client 2))
Wait up to five minutes until the specified Remote Access Services come online. Substitutes a literal 1 into the script if all machines are now online or 0 if one or more failed to come online. Available as of 5.2 beta 4.
Param 1: @Machine, @Machines or @ThisMachine
Ask User or Ask Technician
ServerUtilsAskUser / AskTech( _ , _ )
PRE
Prompts either the user on the machine currently running the script, or the Technician prior to running the script to gather input from them. In the case of scripts running within Alerts, since no Technician is available, any AskTech calls are ignored.
AskUser/AskTech placed in your script are collated and built into a single input form. This input form is then presented to the user or Technician. When the user or Technician has submitted the form, their choices for individual input items are substituted into the calls in your script, regardless of where you placed them.
The following parameters are standard for all form types:
Param 1: The label to show the user or Technician when asking for this item of input
Param 2: The type of input field to add to the form, this can be any one of the following input types:
Form Types
SimpleHelp supports a number of different data fields that you can place in your forms. These are listed below, along with any additional parameters that they required.
Set the Form Title - title
ServerUtilsAskUser(Customer Input Form, title)
The title of the input form. No additional parameters.
Change the Submit Text - submit
ServerUtilsAskUser(Accept, submit)
The text shown for the submit button on the input form. No additional parameters.
Single Line Text Field - text
ServerUtilsAskUser(Name, text)
ServerUtilsAskUser(Login, text, username)
ServerUtilsAskUser(Login, text, username, required)
A general single-line textual input field.
Optional Param 3: The default value for the field
Optional Param 4: required
if this field is required to allow the form to be submitted
Integer Number Field - int
ServerUtilsAskUser(Age, int)
ServerUtilsAskUser(Age, int, 21)
ServerUtilsAskUser(Age, int, 21, required)
An integer number input field.
Optional Param 3: The default value for the field
Optional Param 4: required
if this field is required to allow the form to be submitted
Decimal Number Field - decimal
ServerUtilsAskUser(Cost, decimal)
ServerUtilsAskUser(Cost, decimal, 10.99)
ServerUtilsAskUser(Cost, decimal, 10.99, required)
A decimal number input field.
Optional Param 3: The default value for the field
Optional Param 4: required
if this field is required to allow the form to be submitted
Phone Number Field - phone
ServerUtilsAskUser(Phone Number, phone)
ServerUtilsAskUser(Phone Number, phone, 01234 567890)
ServerUtilsAskUser(Phone Number, phone, 01234 567890, required)
A phone number input field.
Optional Param 3: The default value for the field
Optional Param 4: required
if this field is required to allow the form to be submitted
Email Field - email
ServerUtilsAskUser(Email Address, email)
ServerUtilsAskUser(Email Address, email, contact@example.com)
ServerUtilsAskUser(Email Address, email, contact@example.com, required)
An email input field.
Optional Param 3: The default value for the field
Optional Param 4: required
if this field is required to allow the form to be submitted
Label - label
ServerUtilsAskUser(Please note this tool may take some time to run, label)
A label to show between input fields (e.g. as a sub-heading). No additional parameters.
Password Input Field - password
ServerUtilsAskUser(Domain Password, password)
A password input field where individual characters are hidden as they are typed. No additional parameters.
Checkbox - checkbox
ServerUtilsAskUser(Check for updates, checkbox)
ServerUtilsAskUser(Do you accept these optional terms?, checkbox, http://example.com/terms)
A checkbox.
Optional Param 3: A URL web address to have the text of the checkbox label link to
Checkbox (Required) - mustcheckbox
ServerUtilsAskUser(Check for updates, mustcheckbox)
ServerUtilsAskUser(Do you accept these required terms?, mustcheckbox, http://example.com/terms)
A checkbox that must be checked by the user or Technician prior to submitting the form.
Optional Param 3: A URL web address to have the text of the checkbox label link to
File Path Field - file
ServerUtilsAskUser(File to upload, file)
ServerUtilsAskUser(File to upload, file, "C:\file.pdf")
A file path field with a button to select a file.
Optional Param 3: A default file path
Folder Path Field - folder
ServerUtilsAskUser(Folder to save to, folder)
ServerUtilsAskUser(Folder to save to, folder, "C:\")
A folder path field with a button to select a folder.
Optional Param 3: A default folder path
Multiple Choice - choice
A choice field where the default value is 1
ServerUtilsAskUser(Minutes to run checks for, choice, 1, 1, 5, 10, 20)
A choice field where the default value is 5
ServerUtilsAskUser(Minutes to run checks for, choice, 5, 1, 5, 10, 20)
A choice field where the default value is UK
ServerUtilsAskUser(Country, choice, UK, USA, UK, Germany)
A choice field where the default value is Germany
ServerUtilsAskUser(Country, choice, Germany, USA, UK, Germany, -, Unknown)
A dropdown with multiple options.
Required Param 3: The initially selected option
Required Param 4+: The options the user or Technician can choose from, or -
to indicate a separator between options
Single Choice - radio
ServerUtilsAskUser(Minutes to run checks for, radio, 1, 1, 5, 10, 20)
ServerUtilsAskUser(Minutes to run checks for, radio, 5, 1, 5, 10, 20)
ServerUtilsAskUser(Country, radio, UK, USA, UK, Germany)
ServerUtilsAskUser(Country, radio, Germany, USA, UK, Germany, -, Unknown)
Multiple options in a list where the selected item is highlighted.
Required Param 3: The initially selected option
Required Param 4+: The options the user or Technician can choose from, or -
to indicate a separator between options
Post / Output API Functions
Pull a File
ServerUtilsPullFile( _ , _ , _ )
POST
Fetch a utility folder from a remote machine with the name "TechUtilities"
ServerUtilsPullFile(@Machine(TechUtilities), @Path("C:\Tools"), @Folder("C:\Tools"))
Fetch a document from a remote machine and place it into the same folder as the script
ServerUtilsPullFile(@Machine(DocumentServer), @Path("E:\Documents\important.pdf"), @Folder(.))
Pull a file from a Remote Access machine into a local folder.
Param 1: @Machine or @ThisMachine
Param 2: @Path remote file path to pull (may be a file or folder)
Param 3: @Folder local folder path to place the file into (may be a file or folder and relative paths beginning .
may also be used)
Push a File
ServerUtilsPushFile( _ , _ , _ )
POST
Push a document folder onto a remote machine called "Local Backups"
ServerUtilsPushFile(@Machine(Local Backups), @Folder("E:\All Backups"), @Path("C:\Users\abc\Documents"))
Push a log file in the same folder as the script to a remote folder
ServerUtilsPushFile(@Machine(Gathered Data), @Folder("E:\Log Files"), @Path("CopiedLogFile.log"))
Push a file to a folder on a Remote Access machine
Param 1: @Machine or @ThisMachine
Param 2: @Folder remote folder path to place the file into
Param 3: @Path local file path to push (may be a file or folder and relative paths beginning .
may also be used)
Set Machine Property
ServerUtilsSetMachineProperty( _ , _ , _ )
POST
Set the property "Database Size" for the Remote Access machine that the script is running on.
ServerUtilsSetMachineProperty(@ThisMachine(), Database Size, 999999)
Set the property 'Last Backed Up' for multiple Remote Access machines.
ServerUtilsSetMachineProperty(@Machines(UK Server, US Server, EU Server), Last Backed Up, 28th October 2019)
Set a property for one or more remote access machines (from the machine-specific properties list within the Technician App Access tab).
Param 1: @Machines(...), @Machine(...) or @ThisMachine()
Param 2: Property name
Param 3: Property value
Set Machine Group Property
ServerUtilsSetMachineGroupProperty( _ , _ , _ )
POST
Set the property "Coordinates" for the Remote Access machine group "USA".
ServerUtilsSetMachineGroupProperty(@MachineGroup(USA), Coordinates, -1.1234/5.678)
Set a property for one or more remote access machine groups (from the properties list within the Technician App Access tab). Available as of 5.2.12.
Param 1: @MachineGroup(...)
Param 2: Property name
Param 3: Property value
Log to Server
ServerUtilsLog( _ )
POST
Log a successful completion.
ServerUtilsLog(This script has completed successfully)
Log to the SimpleHelp Server log file.
Param 1: Text to log
Log to File
ServerUtilsLogFile( _ , _ , _ )
POST
Log to a temporary file on the SimpleHelp server
ServerUtilsLogFile(@Server(), /tmp/myscript.log, This script has completed successfully)
Log to a file on a Remote Access machine
ServerUtilsLogFile(@Machine(Technician PC), "C:\Users\abc\Documents\script.log", "This script has found an issue")
Log to a log file on the SimpleHelp server or Remote Access machine.
Param 1: @Server, @Machine(...) or @ThisMachine()
Param 2: File path to log into
Param 3: Text to append to the log file
Send an Email
ServerUtilsSendEmail( _ , _ , _ , ... )
POST
Send an email to two email addresses
ServerUtilsSendEmail(@Emails(alice@example.com, bob@example.com), Important, Detected unauthorised access!)
Send an email to two Technicians, looked up by their name
ServerUtilsSendEmail(@TechsByName(Alice Smith, Bob Jones), Important, Detected unauthorised access!)
Send an email to one Technician, looked up by their username login
ServerUtilsSendEmail(@TechsByLogin(alicesmith), Important, Detected unauthorised access!)
Send an email to a support address and include a log file attachment
ServerUtilsSendEmail(@Emails(support@example.com), "Customer Logs", "Logs from incident 1234", "C:\Users\customer\Desktop\output.log")
Send an email to the specified addresses or Technicians.
Param 1: @Emails, @TechsByName or @TechsByLogin
Param 2: Email subject
Param 3: Email body
Optional Param 4+: File paths to attachments to send within the email (max 55MB per file)
Note: Attachments are supported in 5.2.15 and later.
Notify All Technicians
ServerUtilsNotifyAllTechs( _ , _ )
POST
ServerUtilsNotifyAllTechs(Important, Detected unauthorised access!)
Notify all Technicians via the Tech App.
Param 1: Subject
Param 2: Body
Notify Technicians
ServerUtilsNotifyTechs( _ , _ , _ )
POST
Send a notification to two Technicians, looked up by their name
ServerUtilsNotifyTechs(@TechsByName(Alice Smith, Bob Jones), Important, Detected unauthorised access!)
Send a notification to one Technician, looked up by their username login
ServerUtilsNotifyTechs(@TechsByLogin(alicesmith), Important, Detected unauthorised access!)
Notify one or more Technicians via the Tech App.
Param 1: @TechsByName or @TechsByLogin
Param 2: Subject
Param 3 Body
Notify Machines
ServerUtilsNotifyMachines( _ , _ , _ )
POST
Send a notification to all machines in the USA and UK groups
ServerUtilsNotifyMachines(@Machines(USA, UK), Important, Please note the company internal systems will be unavailable for the next ten minutes)
Notify one or more Machines with a popup message the same as the machine "Message" function in the Access tab. Available as of version 5.2.9.
Param 1: @ThisMachine, @Machine or @Machines
Param 2: Subject
Param 3: Body
Run a Tool
ServerUtilsRunTool( _ , _ , _ )
POST
Run a tool with the name 'Fix Printer' from a Technician toolbox on the current machine
ServerUtilsRunTool(@ThisMachine(), @TechsByLogin(alicesmith), @Tool(Fix Printer))
Run a tool with the name 'Fix Printer' on multiple Remote Access machines
ServerUtilsRunTool(@Machines(Customer Desktop, Customer Laptop), @TechsByName(Alice), @Tool(Fix Printer))
Run the tool with matching or partially matching the specified name from the Toolbox of the specified Technician, on one or more specified Remote Access machines.
Param 1: @Machine, @Machines or @ThisMachine(...)
Param 2: @TechByName or @TechByLogin
Param 3: @Tool
Relocate Script
ServerUtilsRelocate( _ )
POST
Run the rest of this script on a backup server
ServerUtilsRelocate(@Machine(Backup Server))
Relocate and run the remainder of this script on another machine.
Param 1: @Machine or @Machines
Open Browser
ServerUtilsOpenBrowser( _ )
POST
ServerUtilsOpenBrowser(http://example.com)
Open a URL (web address) on the machine running the script using the default browser.
Param 1: The URL (web address) to open
AlertTrigger / AlertReset
ServerUtilsAlertTrigger / AlertReset( _ )
POST
Force the Scheduled Alert to reset
ServerUtilsAlertReset()
Force the Scheduled Alert to trigger, even if ServerUtilsAlertReset has been called within this script
ServerUtilsAlertTrigger()
Force a scheduled alert run using this tool to trigger or reset the associated alert. Any call to AlertTrigger overrides a previous call within the current script run to AlertReset.