Toolbox Guide

SimpleHelp toolboxes let technicians run repeatable commands and scripts on remote machines. A tool can include a command or script, resource files, target operating system rules, launch context, notes and result handling rules. Tools can be run during a support session, from the Access tab, or as monitoring or alerting actions.

What is a Toolbox?

A toolbox is a group of tools. Each tool defines:

• The command or script to run.
• The operating system and processor architecture it applies to.
• Files, folders or download URLs that should be made available before the tool starts.
• The working directory and remote account context used to launch the tool.
• Whether SimpleHelp should wait for the process to finish before reporting a result.
• Rules that determine whether the tool run was successful.

The Toolbox tab in the Technician Console is used to create and manage these tools. The Access tab and in-session tool panels are used to run them. Tools launched in the Access tab can be run across multiple remote machines at the same time.

Toolbox Permissions

Toolbox functionality is controlled by Technician Group permissions. The group permissions apply to all technicians who are members of the group and dictate whether a technician can:

• Manage tools and toolboxes.
• Import tools and shared toolboxes.
• Run tools from the Access tab.
• Run tools in active sessions.
• Use Cyana assistance in the script editor.

If a feature described in this guide is not visible, check that your technician account has the appropriate permissions to access the feature.

The Toolbox Tab

Open the Technician Console and select the Toolbox tab. The current Toolbox view is split into a hierarchical layout on the left and an editor on the right.

The hierarchy can contain several top-level branches:

• ToolBoxes - your own toolboxes and tools. By default, these are specific to your technician account and are not visible to other technicians unless shared.
• Favourites - tools you have marked as favourites. Favourite tools are easier to find and quicker to launch.
• Imported ToolBoxes - toolboxes imported from other technician accounts.
• All Technicians - an administrator-only view of the toolboxes owned by other technicians.

The toolbar above the hierarchy provides the main toolbox management actions. These actions include:

• Create a new toolbox or tool.
• Duplicate an existing tool.
• Import toolboxes that have been shared by other technicians.
• Export toolboxes to file for sharing, or Import toolboxes from file.
• Remove a toolbox or tool.
• Search the tool hierarchy.

When the toolbox hierarchy is changed, or items are modified, changes are saved immediately and stored on the SimpleHelp server. This allows technicians to access their tools when logging in from different locations.

Creating and Organising Toolboxes

A toolbox group is a container that can hold toolbox items and other toolbox groups. The technician is free to create a hierarchy that suits their own requirements. To create a new toolbox group:

1. Select the root ToolBoxes element or an existing toolbox group.
2. Use the Create a New ToolBox toolbar button to create a new group.
3. Enter the toolbox name when the new group appears in the tree.

Toolbox groups can contain both tools and toolbox groups. Use child groups to organise tools by customer, platform, workflow or risk level.

To rename a toolbox, start by selecting it in the hierarchy. The details of the toolbox will appear in the right panel. Click on the name to change it.

Tools or toolboxes can be moved from one parent group to another. To move tools or groups, drag them onto another toolbox group in the hierarchy. SimpleHelp will prompt you for confirmation before performing the move operation. Note that it is currently not possible to move imported toolboxes in the same way.

To remove a toolbox or tool, select it and choose Remove from the toolbar menu.

Creating a Tool

To create a tool:

1. Select a toolbox group.
2. Click the Create a New Tool toolbar button. A new tool is created immediately.
3. Enter the tool name and complete the tool configuration on the right.

The tool editor has a Configuration tab with general settings and a Notes tab where the technician can add free-form text and documentation for the tool.

Tool Configuration

The Notes tab stores technician-facing notes for the tool. Notes are useful for describing what the tool changes, expected output, prerequisites or rollback steps.

Resources

A tool can use three kinds of resources:

• Files - individual files uploaded from the technician machine.
• Folders - folders uploaded from the technician machine.
• Downloads - URLs that the remote machine downloads when the tool runs.

You can add files and folders with Add a Resource or by dragging them onto the Resources section. Use Add a Download to enter a download URL and an optional target filename.

Resources are stored on the SimpleHelp server so they can be fetched by remote machines. When you add or change local resources, SimpleHelp synchronises them with the server. The resource list shows upload progress until the synchronisation is complete.

Resources are placed in the tool's working directory on the remote machine before the tool process starts. If the tool uses a temporary working directory, SimpleHelp can remove the temporary directory after the run when Always remove resources after a tool run is enabled.

Scripts

When a tool is set to Run a script, SimpleHelp writes the script body to a temporary script file on the remote machine and launches it with the selected interpreter.

The built-in interpreter commands use the ${SCRIPT} placeholder for the generated script file. For example:

PowerShell.exe -ExecutionPolicy Bypass -NoLogo -NonInteractive -WindowStyle Hidden -file ${SCRIPT}

For custom interpreters, include ${SCRIPT} where the script filename should appear. If the placeholder is not present, SimpleHelp appends the script filename to the interpreter command.

Click the script preview to open the full editor. The editor provides syntax highlighting based on the selected interpreter. If enabled for your server and account, the editor also includes Cyana assistance for working on toolbox scripts.

See the Toolbox Scripting Guide for details on SimpleHelp's scripting API, technician input forms and advanced script capabilities.

Commands, Shells and Return Codes

SimpleHelp launches command tools directly. It does not automatically run the command inside a shell such as cmd.exe, PowerShell, bash or sh.

For example, this Windows command depends on shell wildcard handling:

dir *.exe

To run it as a command tool, launch it through the Windows command prompt:

cmd.exe /c dir *.exe

The same principle applies to shell features such as pipes, redirects, environment expansion and built-in shell commands. Use a shell explicitly, or use Run a script and choose the appropriate interpreter.

Return codes are only meaningful when Wait for the tool to complete before returning is enabled. If return code success checking is disabled, SimpleHelp does not mark the tool as failed simply because it returned a non-zero code. If success codes are configured, SimpleHelp marks the result as successful only when the process returns one of those codes.

For PowerShell scripts, explicitly exit with the desired return code when you want SimpleHelp to report a specific success or failure state:

[Environment]::Exit(1)

Sharing Toolboxes

Select a toolbox group to configure sharing. The right-hand panel shows a Sharing tab for groups you own or can modify.

A toolbox has a description and two separate sharing levels:

• Technicians with Read Access can view and run tools from the toolbox, but cannot modify it.
• Technicians with Write Access can view, run and modify the toolbox.

For each level, choose one of:

• No other technicians
• Technicians in your group
• All technicians
• Specific technicians

Optionally, enter a description that will be shown to other technicians when they import your shared toolbox.

Imported shared toolboxes appear under Imported ToolBoxes. If the owner granted write access, the imported toolbox can be edited. If the owner granted read access only, it can be viewed and run but its configuration controls are disabled.

Importing Shared Toolboxes

To import toolboxes shared by other technicians:

1. Open the Toolbox tab.
2. Click Import Shared in the toolbar menu.
3. Use the filter field to search by toolbox name, description or tool.
4. Select one or more shared toolboxes.
5. Confirm the import.

The import dialog shows the toolbox owner and description for the selected shared toolbox. Imported toolboxes are added under Imported ToolBoxes in the tool hierarchy.

Importing and Exporting Toolbox Files

Toolboxes can also be moved between systems as .tbx files. To export a toolbox:

1. Select a single toolbox group.
2. Choose Export Toolbox to file... from the toolbar menu.
3. Save the .tbx file.

The exported file includes the selected toolbox, its tools and its bundled resources. To import a toolbox file:

1. Choose Import Toolbox from file... from the toolbar menu.
2. Select a .tbx file.
3. Wait while SimpleHelp creates the toolbox and uploads bundled resources to the server.

Imported files are added to your ToolBoxes branch and resources are immediately synchronised with the SimpleHelp server.

Duplicating Tools

Select a tool and click Duplicate to create a copy in the same toolbox group. SimpleHelp creates a new tool with a new unique ID, copies the tool configuration and duplicates the tool resources on the server. The duplicate is selected after it is created so you can rename or edit it.

Running Tools in a Session

When a remote support or remote access session allows toolbox tools, the session side panel includes a toolbox tab. The list is filtered to only include tools that match the remote machine's operating system and architecture.

From the in-session toolbox list you can:

• Double-click a tool or click the run icon beside a selected tool to launch it on the remote machine.
• Click the stop icon for a running tool to terminate the tool on the remote machine.
• Open tool results from the result icon.
• Use Run All on a group to run all compatible tools in that group on the remote machine.

While a tool runs, the session user interface will show progress states such as Initialising, Fetching Resources, Launching and Running. When the tool finishes, the user interface shows whether it completed successfully, any return code, and any standard output or standard error captured from the process.

Running Tools from Access

Tools can also be run against Remote Access machines from the Access tab. For a single machine:

1. Select an online machine that allows scripting.
2. Select Run tools and scripts.
3. Click Run a ToolBox Tool.
4. Choose one or more compatible tools and confirm the run.

The run dialog only lists tools that match the selected machine's operating system and architecture. Groups in the dialog include Run All for launching every compatible tool in that group.

For multiple machines, use the Access tab's advanced actions panel. SimpleHelp filters each selected tool to the machines that match its target OS. Tool launches on offline machines are queued to run when the remote machine next comes online.

Tool Runs and Results

The Access machine details view includes a Tool Runs panel for the selected machine. It shows current and previous tool runs for that machine.

Each tool run can show:

• Start time.
• Current status.
• Return code.
• Standard output.
• Standard error.
• Launch errors, if the process could not be started.

For output sections, use the copy button to copy the text to the clipboard or the pop-out button to open a searchable output window.

After a run completes, Run Again repeats the same tool on the selected machine. Clear All removes the displayed tool runs. If any displayed tools are still running, SimpleHelp asks for confirmation before terminating them.

Favourite Tools

Mark a tool as a favourite from its configuration panel. Favourite tools are stored for your technician account. Favourites appear:

• In the Favourites branch of the Toolbox tab.
• In the optional favourites panel beside the Access Tool Runs view.

The Access favourites panel is filtered to tools that can run on the selected machine. Clicking a favourite runs it on that machine and is a convenient way to launch commonly used tools.

Batch and Scheduled Runs

SimpleHelp can run tools across multiple Remote Access machines and can queue tool runs for machines that are offline. For Remote Management workflows, see the Remote Management Guide.

Practical Examples

The following examples illustrate command-style tools. For more complex logic, use Run a script and choose the appropriate interpreter.

Windows Command Prompt

cmd.exe /c start cmd.exe /k

or:

cmd.exe /c start cmd.exe /k <command to launch>

Windows: Open Services Management

cmd.exe /c start services.msc

Windows: Open Control Panel

cmd.exe /c control

Windows: Restart Immediately

cmd.exe /c shutdown /f /r /t 0

macOS or Linux: Restart Immediately

shutdown -r 0

Shut Down

shutdown -h 0