NAV

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.