Toolbox Guide
A detailed guide on how to create, manage and run toolbox items in SimpleHelp.
What is a Toolbox?
Toolboxes are groups of configurable tools (similar to scripts) that can be executed on a remote machine during a session, or through the Access tab in the Technician Console. Each tool specifies:
- The command to run on the remote machine.
- Any files and folders that need to be copied to the remote machine prior to launching the command.
- Additional information that helps SimpleHelp know when it can run a command, and what to do with the output.
Creating a Toolbox
Toolboxes are created and managed in the Technician Console. Log into SimpleHelp as a technician and switch to the Toolbox tab. Initially you will have no toolboxes setup.
There are two ways to get started with toolboxes:
- Create a New Toolbox - create and configure a new toolbox.
- Import a Toolbox - import a toolbox that has been shared by another technician. Details on how toolboxes are shared is detailed in the Sharing Toolboxes section below.
Creating a Tool
A toolbox can contain any number of tools. Press the Add a Tool button to create a new tool for your toolbox:
When you create a tool you can provide the following configuration properties.
Name |
The name of this tool. The name will be shown under its toolbox when a tool is to be executed. |
Target Operating System |
Select the target operating system. SimpleHelp uses this information to only present tools that can be run on a particular machine. |
Resources |
A set of individual files or folders that are synchronised with the remote machine before the tool is executed. To add a folder to the Resources section drag the required folder in from the operating system's file browser. |
Action To Take |
Choose whether SimpleHelp should run a single command line, or should instead execute a specified script. |
Command To Run |
The command to run on the remote machine when the tool is executed. The specified command will not be run within a command line interpreter, and will be launched directly. See the section titled Shells, Interpreters and Return Codes below for additional information. |
Working Directory |
The directory in which the resources will be copied, and from where the command will be launched. This is optional, and if omitted a temporary directory will be used. |
Wait For Tool To Complete |
Choose whether SimpleHelp should wait for the launched tool to complete before returning. |
Success Return Code |
Optionally specify the return code which designates that the command has succeeded. SimpleHelp uses this information to indicate success or failure when the tool is run. |
Your new tool will be listed in your toolbox as below:
Shells, Interpreters and Return Codes
When a tool is executed on the remote machine SimpleHelp will not launch it from within any shell or interpreter, unless a particular script is used. Consider the following command executed via a tool on a Windows machine:
dir *.exe
The expression *.exe is usually interpreted by the command prompt, and so passing *.exe to the application dir will not have the desired effect. Instead, this command must be interpreted by a command prompt:
cmd.exe /c dir *.exe
Similarly, commands and interpreters are responsible for determining the return code. In particular, PowerShell scripts do not automatically terminate and return once complete. Instead it is up to the user to specify the return code to use by using:
[Environment]::Exit(1)
This command returns 1 to SimpleHelp, and can subsequently be interpreted by your tool to determine success or failure.
Sharing Toolboxes
There are two different ways to share the toolboxes you create with other SimpleHelp users:
You can access the Share options by using the following Share button beside each Toolbox:
- By using the built-in Sharing mechanism, you can easily publicise your tools to other technicians that have access to your SimpleHelp server.
- By exporting your tools you can share the configurations and resources with other users.
You can access the Share options by using the following Share button beside each Toolbox:
Sharing with SimpleHelp Technicians
It is up to the creator of a toolbox to decide whether or not they wish to share the toolbox with other technicians. To share a toolbox press the Share button. The technician can now configure how the toolbox is to be shared:
Toolboxes can be shared with technicians in the same group as the creator, or with all technicians. If the toolbox is to be shared then a description can be provided that will be shown to other technicians when the toolbox is imported.
To import a shared toolbox a technician can press the Import button. SimpleHelp will then return a list of shared toolboxes that are visible to this technician. Check the toolboxes that you are interested in importing and they will subsequently be shown in your list of toolboxes.
To import a shared toolbox a technician can press the Import button. SimpleHelp will then return a list of shared toolboxes that are visible to this technician. Check the toolboxes that you are interested in importing and they will subsequently be shown in your list of toolboxes.
Exporting and Importing Toolboxes
|
Toolboxes can be exported to file so that they can be shared and distributed. An exported toolbox will include all tools from within the toolbox, and will also include all tool resources.
|
|
Toolboxes can then be imported. An imported toolbox can then be changed or reconfigured if desired.
|
Running Tools
SimpleHelp allows you to execute tools on a remote machine from within a remote support or remote access session. When a technician starts a new remote support or remote access session the list of toolboxes is presented in the chat panel to the right of the remote desktop view:
You can run any tool within a toolbox by clicking on the tool. Once the tool is complete the technician will be able to see the return code, as well as any output that the tool produced.
Batch and Scheduled Tool Runs
SimpleHelp also allows you to batch execute tools across multiple machines concurrently via the Access tab, or run them on a schedule using a Custom Alert.
Since batch execution of toolboxes and custom alerts are Remote Management features, they require a Business license. If you are interested in this functionality please see our Remote Management Guide.
Since batch execution of toolboxes and custom alerts are Remote Management features, they require a Business license. If you are interested in this functionality please see our Remote Management Guide.
Tool Examples
The following example commands are provided to illustrate how tools can be specified in SimpleHelp to perform different tasks. The tools are not comprehensive, and often for more advanced functionality scripts should be used instead.
The following tools can be executed on Windows. Note that in most instances cmd.exe /c can be excluded if the tool is configured to run a Batch Script.
The following tools can be executed on Windows. Note that in most instances cmd.exe /c can be excluded if the tool is configured to run a Batch Script.
Launch an Interactive Command Prompt |
cmd.exe /c start cmd.exe /k (or) cmd.exe /c start cmd.exe /k <command to launch> |
Launch Services Management Console |
cmd.exe /c start services.msc |
Open Control Panel |
cmd.exe /c control |
Restart the Computer |
cmd.exe /c shutdown /r /t 0 |
SimpleHelp Scripting API
The SimpleHelp Scripting API is an additional set of capabilities that allows you to do much more within a tool script than just what is available within the scripting language itself.
For example, a powershell or bash script can allow you to do a lot on the machine that it runs on, but our Scripting API allows you to go beyond the local machine, managing remote access machines, accessing server data and functions like cross-machine file transfers, and use powerful additions like user and technician input forms.
For example, a powershell or bash script can allow you to do a lot on the machine that it runs on, but our Scripting API allows you to go beyond the local machine, managing remote access machines, accessing server data and functions like cross-machine file transfers, and use powerful additions like user and technician input forms.
Basic Usage
The Scripting API is available regardless of the scripting language you use when creating a Tool, and it is used in exactly the same way for every scripting language, whether it be bash, python, powershell or windows batch.
Scripting API functions all begin with ServerUtils and follow the same form:
Scripting API functions all begin with ServerUtils and follow the same form:
ServerUtilsFunctionName(ParameterOne,ParameterTwo,...)
Each of the Scripting API functions contains one or more usage examples for that specific function so for a more specific reference you can consult the documentation for the exact function you want to use.
Real World Examples
With something as flexible as Tools and our Scripting API, it can be difficult to consider how you can put it to work for you in your particular environment. To help get you started thinking about the possibilities, we've put together a list of real world examples of how Tools and the Scripting API can be used to benefit your business.
Since these examples would often have a lot of domain-specific scripting, they are provided as a high level description to make them easy to read, rather than getting bogged down in the details.
Securely back up sensitive documents entirely within the local network
A Tool script is checks commonly important data folders such as the user Documents folder. The PushFile API call is used to push important files and folders matching certain criteria to a central backup machine, using the users login name as the destination folder on the backup machine. Because the backup machine is on the same LAN as the target machines, PushFile is able to set up a direct connection between the local and backup machine, transfer files quickly and securely and avoid using any external bandwidth. Additionally, because PushFile resumes transfers, only files that have changed are transferred.
Gather data when a server becomes unresponsive and send it to the Technician
A SimpleHelp alert is monitoring a web server. When the web server page response times become sluggish, it triggers a Tool running on the backend machine hosting the web server. The Tool is able to gather high level machine stats by using the GetCpuUsage and GetMemoryUsage scripting API calls. It also runs commands to dump the current web connections and copy the web server and backend database log files into a local folder. The PushFile API call is then used to send the entire folder to the Technician's desktop and the NotifyTech API call is used to send them a notification within the Technician App.
Automatically gather business-specific data and alert over it
A Tool is set to run on every database in the business. When it runs, it launches a number of database-specific commands to gather information about the databases, their performance, and how large they are. Each of these items of information is sent to the SimpleHelp Server using the SetMachineProperty API call to every hour on the hour automatically populate an appraisal of the database and how it is running where Technicians can easily view it within the Access tab. The Tool script also performs some logic to determine if the database is becoming too unwieldy or in need of reindexing. If this is the case it sends an email to the database admins with the SendEmail API call and notifies them within SimpleHelp using the NotifyTech API call.
Automatically pop up a maintenance request page in response to a customer issue
A SimpleHelp alert is checking for low disk space on thousands of end-user machines. For any machine that is becoming dangerously low on disk space, it takes the action to run a Tool on that machine. The Tool runs on the machine and uses the OpenBrowser API call to pop up the user's default browser to a trusted internal web server showing a custom maintenance notice, informing the user of the impending problem and asking that they enter the SimpleHelp support queue so that a Technician can run a Space Report from within SimpleHelp and help them determine where they can easily free up a large amount of space. A second alert is performing a similar check and sequence of actions but for the disk SMART status.
Since these examples would often have a lot of domain-specific scripting, they are provided as a high level description to make them easy to read, rather than getting bogged down in the details.
Securely back up sensitive documents entirely within the local network
A Tool script is checks commonly important data folders such as the user Documents folder. The PushFile API call is used to push important files and folders matching certain criteria to a central backup machine, using the users login name as the destination folder on the backup machine. Because the backup machine is on the same LAN as the target machines, PushFile is able to set up a direct connection between the local and backup machine, transfer files quickly and securely and avoid using any external bandwidth. Additionally, because PushFile resumes transfers, only files that have changed are transferred.
Gather data when a server becomes unresponsive and send it to the Technician
A SimpleHelp alert is monitoring a web server. When the web server page response times become sluggish, it triggers a Tool running on the backend machine hosting the web server. The Tool is able to gather high level machine stats by using the GetCpuUsage and GetMemoryUsage scripting API calls. It also runs commands to dump the current web connections and copy the web server and backend database log files into a local folder. The PushFile API call is then used to send the entire folder to the Technician's desktop and the NotifyTech API call is used to send them a notification within the Technician App.
Automatically gather business-specific data and alert over it
A Tool is set to run on every database in the business. When it runs, it launches a number of database-specific commands to gather information about the databases, their performance, and how large they are. Each of these items of information is sent to the SimpleHelp Server using the SetMachineProperty API call to every hour on the hour automatically populate an appraisal of the database and how it is running where Technicians can easily view it within the Access tab. The Tool script also performs some logic to determine if the database is becoming too unwieldy or in need of reindexing. If this is the case it sends an email to the database admins with the SendEmail API call and notifies them within SimpleHelp using the NotifyTech API call.
Automatically pop up a maintenance request page in response to a customer issue
A SimpleHelp alert is checking for low disk space on thousands of end-user machines. For any machine that is becoming dangerously low on disk space, it takes the action to run a Tool on that machine. The Tool runs on the machine and uses the OpenBrowser API call to pop up the user's default browser to a trusted internal web server showing a custom maintenance notice, informing the user of the impending problem and asking that they enter the SimpleHelp support queue so that a Technician can run a Space Report from within SimpleHelp and help them determine where they can easily free up a large amount of space. A second alert is performing a similar check and sequence of actions but for the disk SMART status.
Scripting API Details
Data Input Functions
Some Scripting API functions fetch data that can be used in your script. For example 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:
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:
For example, a script containing the following line:
ServerUtilsSendEmail(...)
Will have a number of scripting language-specific calls placed into it, such that when your scripting reaches this point, the request will be made to the SimpleHelp Scripting API and the email will be sent.
Security and Permissions
The Scripting API provides the Tools using it with a lot of power, and therefore has a number of important security features to restrict access to only the usage intended by technicians. These steps are all fully automated and don't require any technician or admin input, but they do have a small bearing on the usage of the API, for example entities discussed in the next section.
Broadly speaking, the 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.
When a technician runs a Tool, the script is scanned to determine not just whether the Tool uses the Scripting API, but the exact calls that it makes, and even some of the data used within those calls, and a Permission Set is built based on that.
The Permission Set 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 Set 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.
Broadly speaking, the 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.
When a technician runs a Tool, the script is scanned to determine not just whether the Tool uses the Scripting API, but the exact calls that it makes, and even some of the data used within those calls, and a Permission Set is built based on that.
The Permission Set 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 Set 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 variables may use those variables within some Scripting API calls.
Generally speaking it is not possible to use script variables within Input API calls (those calls marked with Pre), this is because these calls are resolved before the script runs and their result is substituted directly into the script.
Output API calls (those calls marked with a Post) may use variables within the call parameters, but should use inline variables rather than string concatenation. For example:
Batch script:
ServerUtilsLog("The variable value is %variable%")
Powershell script:
ServerUtilsLog("The variable value is $variable")
Bash script:
ServerUtilsLog("The variable value is $variable")
Generally speaking it is not possible to use script variables within Input API calls (those calls marked with Pre), this is because these calls are resolved before the script runs and their result is substituted directly into the script.
Output API calls (those calls marked with a Post) may use variables within the call parameters, but should use inline variables rather than string concatenation. For example:
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 make use of or require use of an Entity. Entities being with an @ symbol, and look similar to function calls:
@Emails(contact@example.com)
An entity wraps a parameter, and makes it fixed, meaning that the permissions for that API call are more locked down, and the script cannot generate many calls with a wide range of parameters or have free reign to abuse the API call.
For example, the @Emails() entity shown above, specifies that the email address contact@example.com should be used. Because 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) other than to the specified address contact@example.com.
Entities are primarily a security feature, but 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.
For example, the @Emails() entity shown above, specifies that the email address contact@example.com should be used. Because 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) other than to the specified address contact@example.com.
Entities are primarily a security feature, but 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 (Pre) 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) DownloadFile
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
Example: Download an instructional PDF from a website and save it into C drive
Param 1: Filename to download the file to
Param 2: URL or web address to download the file from
Example: Download an instructional PDF from a website and save it into C drive
ServerUtilsDownloadFile(C:\important.pdf,https://example.com/downloads/instructions.pdf)
(Pre) GetMachineName
Fetch the Remote Access Service name of the machine the script is running on. Resolves to a simple literal within your script. Available as of 5.2.11.
Example: Fetch the Remote Access Service name without it's group
Example: Fetch the Remote Access Service name without it's group
ServerUtilsGetMachineName()
(Pre) GetMachineGroup
Fetch the Remote Access Service group of the machine the script is running on, separated by slashes. Resolves to a simple literal within your script. Available as of 5.2.11.
Example: Fetch the Remote Access Service group, separated with forward slashes (e.g. USA/California)
Example: Fetch the Remote Access Service group, separated with forward slashes (e.g. USA/California)
ServerUtilsGetMachineGroup()
(Pre) GetMachineFullName
Fetch the Remote Access Service name and group, separated by slashes, of the machine the script is running on. Resolves to a simple literal within your script. Available as of 5.2.11.
Example: Fetch the Remote Access Service full name (e.g. USA/California/MyServer)
Example: Fetch the Remote Access Service full name (e.g. USA/California/MyServer)
ServerUtilsGetMachineFullName()
(Pre) GetMachineProperty
Fetch a property for a remote access machine (from the machine-specific properties list within the Technician App Access tab). Resolves to a simple literal within your script.
Param 1: @Machine(...) or @ThisMachine()
Param 2: Property name
Example: Fetch the property "Customer" for the Remote Access machine that the script is running on.
Param 1: @Machine(...) or @ThisMachine()
Param 2: Property name
Example: Fetch the property "Customer" for the Remote Access machine that the script is running on.
ServerUtilsGetMachineProperty(@ThisMachine(),Customer)
Example: Fetch the property "Emergency Phone" for the Remote Access machine with the name "Backend DB"
ServerUtilsGetMachineProperty(@Machine(Backend DB),Emergency Phone)
(Pre) PrePullFile
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)
Example: Fetch a utility folder from a remote machine called "TechUtilities"
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)
Example: Fetch a utility folder from a remote machine called "TechUtilities"
ServerUtilsPrePullFile(@Machine(TechUtilities),@Path(C:\Tools),@Folder(C:\Tools))
Example: 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(.))
(Pre) PrePushFile
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)
Example: Push a document folder onto a remote machine called "Local Backups"
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)
Example: Push a document folder onto a remote machine called "Local Backups"
ServerUtilsPrePushFile(@Machine(Local Backups),@Folder(E:\All Backups),@Path(C:\Users\abc\Documents))
Example: 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))
(Pre) CompareFiles
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
Example: Compare source and destination data on two machines being kept in sync
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
Example: Compare source and destination data on two machines being kept in sync
ServerUtilsCompareFiles(@Machines(Web Server,/opt/criticaldata,Backup Server,/opt/criticaldata))
(Pre) GetCpuUsage
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
Example: Get the CPU usage for the local machine
Param 1: @Machine or @ThisMachine
Example: Get the CPU usage for the local machine
ServerUtilsGetCpuUsage(@ThisMachine())
(Pre) GetMemoryUsage
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
Example: Get the Memory usage for a remote machine
Param 1: @Machine or @ThisMachine
Example: Get the Memory usage for a remote machine
ServerUtilsGetMemoryUsage(@Machine(Web Server))
(Pre) GetWanIp
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
Example: Get the WAN IP of a remote machine
Param 1: @Machine or @ThisMachine
Example: Get the WAN IP of a remote machine
ServerUtilsGetWanIp(@Machine(Customer Computer))
(Pre) GetWifiMbit
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
Example: Get the WiFi speed of the local machine
Param 1: @Machine or @ThisMachine
Example: Get the WiFi speed of the local machine
ServerUtilsGetWifiMbit(@ThisMachine())
(Pre) GetWifiPercent
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
Example: Get the WiFi speed of a remote machine
Param 1: @Machine or @ThisMachine
Example: Get the WiFi speed of a remote machine
ServerUtilsGetWifiPercent(@Machine(Customer Computer))
(Pre) GetRdpSessions
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
Example: Get the number of RDP sessions open on a remote machine
Param 1: @Machine or @ThisMachine
Example: Get the number of RDP sessions open on a remote machine
ServerUtilsGetRdpSessions(@Machine(Terminal Server))
(Pre) WakeOnLan
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 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
Example: Wake multiple machines
Param 1: @Machine, @Machines or @ThisMachine
Example: Wake multiple machines
ServerUtilsWakeOnLan(@Machines(Test Server,Test Client 1,Test Client 2))
(Pre) WaitUntilOnline
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
Example: Wait up to five minutes for machines to come online
Param 1: @Machine, @Machines or @ThisMachine
Example: Wait up to five minutes for machines to come online
ServerUtilsWaitUntilOnline(@Machines(Test Server,Test Client 1,Test Client 2))
(Pre) AskUser / AskTech
Prompts either the user on the machine currently running the script, or the Technician prior to running the script to gather input from them. Note: 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.
Each AskUser or AskTech call starts with the same two parameters, and then may have more depending on the type of the call.
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:
(Type) Title
The title of the input form. No additional parameters.
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.
Each AskUser or AskTech call starts with the same two parameters, and then may have more depending on the type of the call.
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:
(Type) Title
The title of the input form. No additional parameters.
ServerUtilsAskUser(Customer Input Form,title)
(Type) Submit
The text shown for the submit button on the input form. No additional parameters.
ServerUtilsAskUser(Accept,submit)
(Type) Text
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
ServerUtilsAskUser(Name,text) ServerUtilsAskUser(Login,text,username) ServerUtilsAskUser(Login,text,username,required)
(Type) Int
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
ServerUtilsAskUser(Age,int) ServerUtilsAskUser(Age,int,21) ServerUtilsAskUser(Age,int,21,required)
(Type) Decimal
An 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
ServerUtilsAskUser(Cost,decimal) ServerUtilsAskUser(Cost,decimal,10.99) ServerUtilsAskUser(Cost,decimal,10.99,required)
(Type) Phone
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
ServerUtilsAskUser(Phone Number,phone) ServerUtilsAskUser(Phone Number,phone,01234 567890) ServerUtilsAskUser(Phone Number,phone,01234 567890,required)
(Type) Email
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
ServerUtilsAskUser(Email Address,email) ServerUtilsAskUser(Email Address,email,contact@example.com) ServerUtilsAskUser(Email Address,email,contact@example.com,required)
(Type) Label
A label to show between input fields (e.g. as a sub-heading). No additional parameters.
ServerUtilsAskUser(Please note this tool may take some time to run,label)
(Type) Password
A password input field where individual characters are hidden as they are typed. No additional parameters.
ServerUtilsAskUser(Domain Password,password)
(Type) Checkbox
A checkbox.
Optional Param 3: A URL web address to have the text of the checkbox label link to
ServerUtilsAskUser(Check for updates,checkbox) ServerUtilsAskUser(Do you accept these optional terms?,checkbox,http://example.com/terms)
(Type) MustCheckbox
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
ServerUtilsAskUser(Check for updates,mustcheckbox) ServerUtilsAskUser(Do you accept these required terms?,mustcheckbox,http://example.com/terms)
(Type) File
A file path field with a button to select a file.
Optional Param 3: A default file path
ServerUtilsAskUser(File to upload,file) ServerUtilsAskUser(File to upload,file,C:\file.pdf)
(Type) Folder
A folder path field with a button to select a folder.
Optional Param 3: A default folder path
ServerUtilsAskUser(Folder to save to,folder) ServerUtilsAskUser(Folder to save to,folder,C:\)
(Type) Choice
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
ServerUtilsAskUser(Minutes to run checks for,choice,1,1,5,10,20) - default = 1 ServerUtilsAskUser(Minutes to run checks for,choice,5,1,5,10,20) - default = 5 ServerUtilsAskUser(Country,choice,UK,USA,UK,Germany) - default = UK ServerUtilsAskUser(Country,choice,Germany,USA,UK,Germany,-,Unknown) - default = Germany
(Type) Radio
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
ServerUtilsAskUser(Minutes to run checks for,radio,1,1,5,10,20) - default = 1 ServerUtilsAskUser(Minutes to run checks for,radio,5,1,5,10,20) - default = 5 ServerUtilsAskUser(Country,radio,UK,USA,UK,Germany) - default = UK ServerUtilsAskUser(Country,radio,Germany,USA,UK,Germany,-,Unknown) - default = Germany
(Post) PullFile
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)
Example: Fetch a utility folder from a remote machine with the name "TechUtilities"
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)
Example: Fetch a utility folder from a remote machine with the name "TechUtilities"
ServerUtilsPullFile(@Machine(TechUtilities),@Path(C:\Tools),@Folder(C:\Tools))
Example: 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(.))
(Post) PushFile
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)
Example: Push a document folder onto a remote machine called "Local Backups"
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)
Example: Push a document folder onto a remote machine called "Local Backups"
ServerUtilsPushFile(@Machine(Local Backups),@Folder(E:\All Backups),@Path(C:\Users\abc\Documents))
Example: 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))
(Post) SetMachineProperty
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
Example: Set the property "Database Size" for the Remote Access machine that the script is running on.
Param 1: @Machines(...), @Machine(...) or @ThisMachine()
Param 2: Property name
Param 3: Property value
Example: Set the property "Database Size" for the Remote Access machine that the script is running on.
ServerUtilsSetMachineProperty(@ThisMachine(),Database Size,999999)
Example: 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)
(Post) Log
Log to the SimpleHelp Server log file.
Param 1: Text to log
Param 1: Text to log
ServerUtilsLog(This script has completed successfully)
(Post) LogFile
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
Example: Log to a temporary file on the SimpleHelp server
Param 1: @Server, @Machine(...) or @ThisMachine()
Param 2: File path to log into
Param 3: Text to append to the log file
Example: Log to a temporary file on the SimpleHelp server
ServerUtilsLogFile(@Server(),/tmp/myscript.log,This script has completed successfully)
Example: 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)
(Post) SendEmail
Send an email to the specified addresses or Technicians.
Param 1: @Emails, @TechsByName or @TechsByLogin
Param 2: Email subject
Param 3: Email body
Example: Send an email to two email addresses
Param 1: @Emails, @TechsByName or @TechsByLogin
Param 2: Email subject
Param 3: Email body
Example: Send an email to two email addresses
ServerUtilsSendEmail(@Emails(alice@example.com,bob@example.com),Important,Detected unauthorised access!)
Example: Send an email to two Technicians, looked up by their name
ServerUtilsSendEmail(@TechsByName(Alice Smith,Bob Jones),Important,Detected unauthorised access!)
Example: Send an email to one Technician, looked up by their username login
ServerUtilsSendEmail(@TechsByLogin(alicesmith),Important,Detected unauthorised access!)
(Post) NotifyAllTechs
Notify all Technicians via the Tech App.
Param 1: Subject
Param 2: Body
Param 1: Subject
Param 2: Body
ServerUtilsNotifyAllTechs(Important,Detected unauthorised access!)
(Post) NotifyTechs
Notify one or more Technicians via the Tech App.
Param 1: @TechsByName or @TechsByLogin
Param 2: Subject
Param 3: Body
Example: Send a notification to two Technicians, looked up by their name
Param 1: @TechsByName or @TechsByLogin
Param 2: Subject
Param 3: Body
Example: Send a notification to two Technicians, looked up by their name
ServerUtilsNotifyTechs(@TechsByName(Alice Smith,Bob Jones),Important,Detected unauthorised access!)
Example: Send a notification to to one Technician, looked up by their username login
ServerUtilsNotifyTechs(@TechsByLogin(alicesmith),Important,Detected unauthorised access!)
(Post) NotifyMachines
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
Example: Send a notification to all machines in the USA and UK groups
Param 1: @ThisMachine, @Machine or @Machines
Param 2: Subject
Param 3: Body
Example: 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)
(Post) RunTool
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
Example: Run a tool with the name 'Fix Printer' from a Technician toolbox on the current machine
Param 1: @Machine, @Machines or @ThisMachine(...)
Param 2: @TechByName or @TechByLogin
Param 3: @Tool
Example: Run a tool with the name 'Fix Printer' from a Technician toolbox on the current machine
ServerUtilsRunTool(@ThisMachine(),@TechsByLogin(alicesmith),@Tool(Fix Printer))
Example: Run a tool with the name 'Fix Printer' on multiple Remote Access machines
ServerUtilsRunTool(@Machines(Customer Desktop,Customer Laptop),@TechsByName(Alice),@Tool(Fix Printer))
(Post) Relocate
Relocate and run the remainder of this script on another machine.
Param 1: @Machine or @Machines
Example: Run the rest of this script on a backup server
Param 1: @Machine or @Machines
Example: Run the rest of this script on a backup server
ServerUtilsRelocate(@Machine(Backup Server))
(Post) OpenBrowser
Open a URL (web address) on the machine running the script using the default browser.
Param 1: The URL (web address) to open
Param 1: The URL (web address) to open
ServerUtilsOpenBrowser(http://example.com)
(Post) AlertTrigger / AlertReset
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.
Example: Force the Scheduled Alert to reset
Example: Force the Scheduled Alert to reset
ServerUtilsAlertReset()
Example: Force the Scheduled Alert to trigger, even if ServerUtilsAlertReset has been called within this script
ServerUtilsAlertTrigger()