Integration, App Customisation and APIs

This guide details how you can customise your SimpleHelp apps or integrate them into your website and third party software.

Basic Integration

A simple but effective form of branding is to embed the SimpleHelp app download buttons into your existing website. Once embedded the SimpleHelp components appear seamlessly alongside your existing images, text and other branding providing a fast, simple and highly effective way to give your customers a consistent support experience.

To embed the SimpleHelp customer client add the following to your web page:

<script
    id = "jwEmbed"
    src = "http://1.2.3.4/customer/embed.js"
    configuration = "offline*"
    imageURL = "/branding/applet_splash.png"
    showAppName = "yes"
    type = "text/javascript">
</script>

Note: Make sure to replace 1.2.3.4 with the address or hostname of your server.

The embed script can be configured as follows:

• Required - The src line should contain the domain name or IP address of your SimpleHelp server. Replace /customer with /technician to embed technician download links.

• Optional - The configuration line specifies which download options are preferred. Options followed by a * are preferred and highlighted. Valid options are:

  • online - On legacy versions prior to 5.5.0 only, the online standalone is a small executable that bundles the essential components required to start the application. Additional requirements on demand are downloaded when required. This is the recommended way to launch an application.
  • offline - The offline standalone is a larger executable that contains all essential and optional components. Here nothing is downloaded on demand.

• Optional - Set showAppName to no to hide the application name.

• Optional - Set showImage to no to hide the image.

Example Basic Integrations

The following examples show a variety of common embed options:

Example 1 - Standard Download

A simple integration showing a custom logo and only the single offline app download option.

<script
    id = "jwEmbed"
    src = "http://1.2.3.4/customer/embed.js"
    configuration = "offline*"
    imageURL = "/branding/applet_splash.png"
    type = "text/javascript">
</script>

Example 2 - Multiple Download

For legacy versions prior to 5.5.0 only: Another integration which provides the user with multiple launch options.

<script
    id = "jwEmbed"
    src = "http://1.2.3.4/customer/embed.js"
    configuration = "online*,offline*"
    imageURL = "/branding/applet_splash.png"
    type = "text/javascript">
</script>

Example 3 - Minimal Download

A minimalist integration showing only the download button.

<script
    id = "jwEmbed"
    src = "http://1.2.3.4/customer/embed.js"
    configuration = "offline*"
    showAppName = "no"
    showImage = "no"
    type = "text/javascript">
</script>

Web API Integrations

SimpleHelp v5.1 and later includes a comprehensive HTTP Web API. Easily connect to your SimpleHelp server and query it to perform the following tasks:

• See existing technician account details, create new accounts or remove existing accounts.
• Assign technicians to group, specify filters and perform general account management tasks.
• View the list of machines registering with the server.
• Collect hardware and monitoring information from a remote machine.
• View the list of historical sessions and collect details about each session.

See the HTTP web API documentation for more information.

Configuring App Downloads

SimpleHelp customer and technician downloads can be configured by passing in options via the download page URL or in the src element of the embed script. Configuration options are included in the downloaded application permanently and will apply every time the application is run. This allows you to preconfigure settings that override the SimpleHelp defaults.

Passing in Configuration Parameters

Download options can be appended to the download link. For example, to set the width and height of the customer window to 500x500 pixels use the following page address:

http://1.2.3.4/customer?width=500&height=500

The same parameters can be passed in with your web page embedding script as follows:

<script
    id = "jwEmbed"
    src = "http://1.2.3.4/customer/embed.js?width=500&height=500"
    …
</script>

Common Parameters

The following options are available for the customer, technician and access downloads.

Customer Application Parameters

The following options apply only to the remote support customer application.

Passing Details into SimpleHelp

Prior to joining the waiting queue, customers are asked to accept a disclaimer and enter in their required details. It is possible to skip these steps by passing the customer's information into SimpleHelp. For example, if you wish to automatically add customer 'Bob' from company 'SimpleHelp' to the queue you can use the following:

http://1.2.3.4/customer?connectnow=on,Bob,Company=SimpleHelp

To configure multiple aspects of the customer client simply chain multiple parameters together separating them with '&':

http://1.2.3.4/customer?connectnow=on,Bob,Company=SimpleHelp&chat=off

Connecting to a Specific Technician

Customers that join the waiting queue are visible to all technicians. If you wish to have customers be visible to specific technicians you can specify the technicians or technician groups on the customer link.

• Filtering By Technician Username - to filter by technician username you can specify a comma separated list on the connect link as follows:

http://1.2.3.4/customer?technician=<technician username>,<technician username>…

• Filtering By Technician Group - to filter by technician group you can specify the group on the connect link as follows:

http://1.2.3.4/customer?techniciangroup=<technician group>

Technician Application Parameters

The following options apply only to the technician application.

Passing Credentials into SimpleHelp

If you wish to automate the logging in of technicians you can pass their credentials on the technician login URL. For example, to log the technician Andy in technician group Administrators with password abcd1234 you can use the following link:

http://1.2.3.4/technician?technician=Andy&password=abcd1234&group=Administrators

Parameters in POST Requests

SimpleHelp allows for the configuration of customer downloads by performing POST requests against the SimpleHelp server. If you wish to configure a download in this manner then you should not POST to the download choice pages:

• http://1.2.3.4/customer
• http://1.2.3.4/technician
• http://1.2.3.4/access

Instead, POST options are only accepted for specific file downloads, such as:

• http://1.2.3.4/customer/Remote%20Support-macos-offline.dmg
• http://1.2.3.4/technician/SimpleHelp%20Technician-windows32-offline.exe
• http://1.2.3.4/access/Remote%20Access-linux32-offline.tar

Command Line Launch

SimpleHelp allows you to launch the technician session user interface from the command line. This is useful if you wish to integrate SimpleHelp with another application.

Technician Session Launching

The command line arguments to launch a Technician session are as follows:

Tech-windows32.exe JWVAPP SessionUI JW_launchapi=yes <other args>

where <other args> may be one or more of:

• JW_serverurl=<server URL> - the URL of the SimpleHelp server to connect to (e.g. http://1.2.3.4:8888)
• JW_machine=<machine name> - the machine name or the machine ID to connect to.
• JW_machine_filter=<any data> - the machine to connect to, found by a filtering search. The filter will match all machine data looking for a match including IP address etc. To test your filter you can open the Technician Client and type the text into the Filter box in the access tab. Your text should match one machine only.
• JW_supported_langs=<language code> - used to force one language (e.g 'es' for Spanish).
• JW_technician=<tech username>
• JW_password=<tech password>
• JW_group=<Technician Group>
• JW_techname=<technician human readable name>
• JW_mode=<screen | file | diagnostics>

NOTE: When using the JW_machine name (rather than the machine ID) the name MUST include the group separated by forward slashes. To get the full machine name to use you should open the Technician Console, select the machine in the Access tab and click the Get Direct Url button below. The URL produced will have the full machine name URL encoded. You can then pass this through an online URL decoder to get the full machine name. An example full machine name might be:

US/Texas/Machine 1 [Windows x86]

When you pass this into the JW_machine parameter you should ensure you surround the entire argument with quotes:

"JW_machine=US/Texas/Machine 1 [Windows x86]"

NOTE: On macOS the command is open Technician.app --args and then these arguments. On other operating systems the command is just the executable and then these arguments.

Remote Support

The customer support client can also be launched and configured via the command line. To do this you should download the customer executable from your server, then to pass in any parameters, just prefix them with JW_, for example:

RemoteSupport.exe JW_connectnow=on,Bob,Company=SH

You can use any of the parameters mentioned earlier in the App Downloads section for the customer client in exactly the same way to configure whatever you wish.

NOTE: On macOS the command is open Customer.app --args and then these arguments. On other operating systems the command is just the executable and then these arguments.

NOTE: You may need to surround the arguments with double quotes to make sure any spaces are preserved.

Remote Access

For more information on how to configure the remote access client for silent or preconfigured installation see this document.

Launching using a URL

If the SimpleHelp Technician application is already installed on a system it can be launched using a configurable URL. This allows for in depth integrations with third party software as SimpleHelp sessions can be started on-demand simply by invoking a URL, and without having to manually script the technician executable. SimpleHelp technician URLs take the form:

simplehelp:///?arg=value&arg=value…

where arg=value can be any of the JW_ arguments specified above for command line launches. Remember that values need to be URL encoded. For example, to establish a session to a service called George's Laptop, you can use a URL of the form:

simplehelp:///?JW_machine=George%27s%20Laptop

Data Export and Logging

Advanced integrations of SimpleHelp often look to not only embed SimpleHelp components into a site, but also retrieve data from the SimpleHelp server. SimpleHelp includes a very powerful logging and data export framework that allows integrators to have SimpleHelp post event data to their integration point of choice. The configuration of the SimpleHelp server is covered in our Administrator Guide . A few of the things you can do with SimpleHelp include:

• Send emails to technicians, customers and administrators when sessions finish.
• Populate a database with customer information.
• Log failed technician log in attempts.
• Send email alerts when remote machines become available, or go offline.
• Log technician usage, customer activity and session details.